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
Returns a list of the preferred units for a given unit, locale, territory and use case.
Returns a list of the preferred units for a given unit, locale, territory and use case.
Functions
@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 byCldr.Unit.new/2
.backend
is any Cldr backend module. That is, any module that includesuse Cldr
. The default isCldr.default_backend!/0
options
is a keyword list of options or at: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 withCldr.Unit.unit_category_usage/0
. The default isnil
.:scope
is either:small
ornil
. In some usage, the units used are different when the unit size is small. It is up to the developer to determine whenscope: :small
is appropriate.:alt
is either:informal
ornil
. Like:scope
, the units in use depend on whether they are being used in a formal or informal context.:locale
is any locale returned byCldr.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")]
@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 byCldr.Unit.new/2
.backend
is any Cldr backend module. That is, any module that includesuse Cldr
. The default isCldr.default_backend!/0
options
is a keyword list of options or at:Cldr.Unit.Conversion.Options
struct. The default is[]
.
Options
:locale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag
struct. The default isbackend.get_locale/0
:territory
is any valid territory code returned byCldr.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 availableusage
varyies according to the unit category. SeeCldr.Unit.unit_category_usage/0
.
Returns
unit_list
orraises 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]