Cldr.Unit.Preference (Cldr Units v3.5.0) View Source
Link to this section 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.
Link to this section Functions
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.Config.preferred_units/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> 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 meter, MyApp.Cldr, locale: "en-AU", usage: :road
{:ok, [:meter], [round_nearest: 1]}
Notes
One common pattern is to convert a given unit into the unit
appropriate for a given local 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, Ratio.new(216172782113783808, 5490788665690109))]
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.preferred_units/3
.
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]