MyApp.Cldr.Unit.preferred_units
preferred_units
, go back to MyApp.Cldr.Unit module for more information.
Returns a list of the preferred units for a given unit, locale, use case and scope.
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 aCldr.Unit.Conversion.Options
struct. The default is[]
.
Options
:usage
is the unit usage. for example;person
for a unit type of length. The available usage for a given unit category can be seen withCldr.Config.unit_preferences/3
. The default isnil
:locale
is any locale returned byCldr.validate_locale/2
Returns
{:ok, unit_list, formatting_options}
or{:error, {exception, reason}}
Notes
formatting_options
is a keyword list of options
that can be passed to Cldr.Unit.to_string/3
. Its
primary intended usage is for localizing a unit that
decomposes into more than one unit (for example when
2 meters might become 6 feet 6 inches.) In such
cases, the last unit in the list (in this case the
inches) is formatted with the formatting_options
.
Examples
iex> meter = Cldr.Unit.new!(:meter, 1)
iex> MyApp.Cldr.Unit.preferred_units meter, locale: "en-US", usage: :person_height
{:ok, [:foot, :inch], []}
iex> MyApp.Cldr.Unit.preferred_units meter, locale: "en-US", usage: :person
{:ok, [:inch], []}
iex> MyApp.Cldr.Unit.preferred_units meter, locale: "en-AU", usage: :person
{:ok, [:centimeter], []}
iex> MyApp.Cldr.Unit.preferred_units meter, locale: "en-US", usage: :road
{:ok, [:foot], [round_nearest: 1]}
iex> MyApp.Cldr.Unit.preferred_units meter, locale: "en-AU", usage: :road
{:ok, [:meter], [round_nearest: 1]}