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]