Localize.Unit.Preference (Localize v0.36.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

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.