View Source Cldr.Unit.Preference (Cldr Units v3.17.0)

In many cultures, the common unit of measure for some unit categories varies based upon the usage of the unit.

For example, when describing unit length in the US, the common use units vary based upon usage such as:

  • road distance (miles for larger distances, feet for smaller)
  • person height (feet and inches)
  • snowfall (inches)

This module provides functions to introspect CLDRs preference data for difference use cases in different locales.

Summary

Functions

Link to this function

debug(category, usage, region, value, geq)

View Source
Link to this function

preferred_units(unit, backend, options \\ [])

View Source
@spec preferred_units(
  Cldr.Unit.t(),
  Cldr.backend() | Keyword.t(),
  Keyword.t() | Cldr.Unit.Conversion.Options.t()
) :: {:ok, [atom(), ...], Keyword.t()} | {:error, {module(), binary()}}

Returns a list of the preferred units for a given unit, locale, territory and use case.

The units used to represent length, volume and so on depend on a given territory, measurement system and usage.

For example, in the US, people height is most commonly referred to in inches, or informally as feet and inches. In most of the rest of the world it is centimeters.

Arguments

  • unit is any unit returned by Cldr.Unit.new/2.

  • backend is any Cldr backend module. That is, any module that includes use Cldr. The default is Cldr.default_backend!/0

  • options is a keyword list of options or a t:Cldr.Unit.Conversion.Options struct. The default is [].

Options

  • :usage is the unit usage. for example ;person for a unit of type :length. The available usage for a given unit category can be seen with Cldr.Unit.unit_category_usage/0. The default is nil.

  • :scope is either :small or nil. In some usage, the units used are different when the unit size is small. It is up to the developer to determine when scope: :small is appropriate.

  • :alt is either :informal or nil. Like :scope, the units in use depend on whether they are being used in a formal or informal context.

  • :locale is any locale returned by Cldr.validate_locale/2

Returns

  • {:ok, unit_list} or

  • {:error, {exception, reason}}

Examples

iex> meter = Cldr.Unit.new!(:meter, 1)
iex> many_meters = Cldr.Unit.new!(:meter, 10_000)
iex> Cldr.Unit.Preference.preferred_units meter, MyApp.Cldr, locale: "en-US", usage: :person
{:ok, [:inch], []}
iex> Cldr.Unit.Preference.preferred_units meter, MyApp.Cldr, locale: "en-AU", usage: :person
{:ok, [:centimeter], []}
iex> Cldr.Unit.Preference.preferred_units meter, MyApp.Cldr, locale: "en-US", usage: :road
{:ok, [:foot], [round_nearest: 1]}
iex> Cldr.Unit.Preference.preferred_units many_meters, MyApp.Cldr, locale: "en-US", usage: :road
{:ok, [:mile], []}
iex> Cldr.Unit.Preference.preferred_units meter, MyApp.Cldr, locale: "en-AU", usage: :road
{:ok, [:meter], [round_nearest: 1]}
iex> Cldr.Unit.Preference.preferred_units many_meters, MyApp.Cldr, locale: "en-AU", usage: :road
{:ok, [:kilometer], []}

Notes

One common pattern is to convert a given unit into the unit appropriate for a given locale and usage. This can be accomplished with a combination of Cldr.Unit.Preference.preferred_units/3 and Cldr.Unit.decompose/2. For example:

iex> meter = Cldr.Unit.new!(:meter, 1)
iex> preferred_units = Cldr.Unit.Preference.preferred_units(meter,
...>   MyApp.Cldr, locale: "en-US", usage: :person)
iex> with {:ok, preferred_units, _} <- preferred_units do
...>   Cldr.Unit.decompose(meter, preferred_units)
...> end
[Cldr.Unit.new!(:inch, "39.37007874015748031496062992")]
Link to this function

preferred_units(category, usage, region, value)

View Source
Link to this function

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

View Source
@spec preferred_units!(
  Cldr.Unit.t(),
  Cldr.backend() | Keyword.t(),
  Keyword.t() | Cldr.Unit.Conversion.Options.t()
) :: [atom(), ...] | no_return()

Returns a list of the preferred units for a given unit, locale, territory and use case.

The units used to represent length, volume and so on depend on a given territory, measurement system and usage.

For example, in the US, people height is most commonly referred to in inches, or feet and inches. In most of the rest of the world it is centimeters.

Arguments

  • unit is any unit returned by Cldr.Unit.new/2.

  • backend is any Cldr backend module. That is, any module that includes use Cldr. The default is Cldr.default_backend!/0

  • options is a keyword list of options or a t:Cldr.Unit.Conversion.Options struct. The default is [].

Options

  • :locale is any valid locale name returned by Cldr.known_locale_names/0 or a Cldr.LanguageTag struct. The default is backend.get_locale/0

  • :territory is any valid territory code returned by Cldr.known_territories/0. The default is the territory defined as part of the :locale. The option :territory has a precedence over the territory in a locale.

  • :usage is the way in which the unit is intended to be used. The available usage varyies according to the unit category. See Cldr.Unit.unit_category_usage/0.

Returns

  • unit_list or

  • raises an exception

Note

This function, unlike Cldr.Unit.preferred_units/3 does not return any available formatting hints.

Examples

iex> meter = Cldr.Unit.new!(:meter, 1)
iex> Cldr.Unit.Preference.preferred_units! meter, MyApp.Cldr, locale: "en-US", usage: :person_height
[:foot, :inch]
iex> Cldr.Unit.Preference.preferred_units! meter, MyApp.Cldr, locale: "en-US", usage: :person
[:inch]
iex> Cldr.Unit.Preference.preferred_units! meter, MyApp.Cldr, locale: "en-AU", usage: :person
[:centimeter]
iex> Cldr.Unit.Preference.preferred_units! meter, MyApp.Cldr, locale: "en-US", usage: :road
[:foot]
iex> Cldr.Unit.Preference.preferred_units! meter, MyApp.Cldr, locale: "en-AU", usage: :road
[:meter]
Link to this function

unknown_preferences_error(category, usage, regions, value)

View Source
Link to this function

unknown_usage_error(category, usage)

View Source
Link to this function

validate_usage(category, usage)

View Source