Search documentation of Localize

# Localize.Unit.Preference (Localize v0.39.0)

Copy Markdown View Source

Returns the preferred units for a given unit, territory, and usage.

In many cultures, the common unit of measure for some unit categories varies based upon the usage. For example, when describing length in the US, the units vary by context:

- road distance — miles for larger distances, feet for smaller
- person height — feet and inches
- snowfall — inches

This module provides functions to look up CLDR preference data for different use cases in different territories.

## Summary

### Functions

preferred_units(unit, options \\ [])

Returns the preferred units for a given unit, territory, and usage.

preferred_units!(unit, options \\ [])

Same as `preferred_units/2` but raises on error.

## Functions

# preferred_units(unit, options \\ [])

    @spec preferred_units(Localize.Unit.t(), Keyword.t()) ::
      {:ok, [atom()], Keyword.t()} | {:error, Exception.t()}

Returns the preferred units for a given unit, territory, and usage.

The unit's value is converted to the base unit for its category and compared against the `geq` (greater-than-or-equal) thresholds in the preference data to select the appropriate unit set.

### Arguments

- `unit` is a `Localize.Unit.t/0` struct.

- `options` is a keyword list of options.

### Options

- `:usage` is the unit usage context as an atom (e.g., `:person_height`, `:road`). The default is `:default`.

- `:territory` is a territory code atom (e.g., `:US`, `:GB`). The default is derived from the current locale.

- `:locale` is a locale identifier. Used to derive the territory when `:territory` is not provided.

- `:scope` is `:small` or `nil`. Forward-compatible placeholder for CLDR's planned scope-keyed preferences (small-quantity contexts); accepted but currently has no effect because no `<unitPreference>` in the shipped CLDR data carries a `scope` attribute. Same shape as `Cldr.Unit.Preference.preferred_units/3`.

- `:alt` is `:informal` or `nil`. Forward-compatible placeholder for CLDR's planned alt-keyed preferences (informal-context units); accepted but currently has no effect because no `<unitPreference>` in the shipped CLDR data carries an `alt` attribute.

### Returns

- `{:ok, units, options}` where `units` is a list of unit name atoms and `options` is a keyword list of formatting hints (e.g., `[round_nearest: 1]`).

- `{:error, exception}` if preferences cannot be resolved.

### Examples

    iex> meter = Localize.Unit.new!(1, "meter")
    iex> {:ok, units, _opts} = Localize.Unit.Preference.preferred_units(meter, usage: :person, territory: :US)
    iex> units
    [:inch]

    iex> many_meters = Localize.Unit.new!(10_000, "meter")
    iex> {:ok, units, _opts} = Localize.Unit.Preference.preferred_units(many_meters, usage: :road, territory: :US)
    iex> units
    [:mile]

# preferred_units!(unit, options \\ [])

    @spec preferred_units!(Localize.Unit.t(), Keyword.t()) :: [atom()] | no_return()

Same as `preferred_units/2` but raises on error.