# `Cldr.Unit.Preference`
[🔗](https://github.com/elixir-cldr/cldr_units/blob/v3.20.3/lib/cldr/unit/conversion/preference.ex#L1)

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.

# `debug`

# `preferred_units`

```elixir
@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")]

# `preferred_units`

# `preferred_units!`

```elixir
@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]

# `unknown_preferences_error`

# `unknown_usage_error`

# `validate_usage`

---

*Consult [api-reference.md](api-reference.md) for complete listing*