Search documentation of bb

# BB.Cldr.Unit (bb v0.8.0)

View Source

Supports the CLDR Units definitions which provide for the localization of many unit types.

# Summary

## Functions

add(unit_1, unit_2)

See `Cldr.Unit.Math.add/2`.

add!(unit_1, unit_2)

See `Cldr.Unit.Math.add!/2`.

compatible?(unit_1, unit_2)

See `Cldr.Unit.compatible?/2`.

convert(unit_1, to_unit)

See `Cldr.Unit.Conversion.convert/2`.

convert!(unit_1, to_unit)

See `Cldr.Unit.Conversion.convert!/2`.

decompose(unit, list)

See `Cldr.Unit.decompose/2`.

default_gender(locale_name)
default_style()

See `Cldr.Unit.default_style/0`.

display_name(unit, options \\ [])

Returns the localized display name for a unit.

div(unit_1, unit_2)

See `Cldr.Unit.Math.div/2`.

div!(unit_1, unit_2)

See `Cldr.Unit.Math.div!/2`.

grammatical_features(locale_name)
grammatical_gender(locale_name)
known_styles()

See `Cldr.Unit.known_styles/0`.

known_unit_categories()

See `Cldr.Unit.known_unit_categories/0`.

known_units()

See `Cldr.Unit.known_units/0`.

localize(unit)

Localizes a unit according to the current processes locale and backend.

localize(unit, options \\ [])

Localizes a unit according to a territory

measurement_system?(unit, systems)

See `Cldr.Unit.measurement_system?/2`.

measurement_system_for(territory) deprecated

See `Cldr.Unit.measurement_system_for_territory/1`.

measurement_system_for(territory, key) deprecated

See `Cldr.Unit.measurement_system_for_territory/2`.

measurement_system_for_territory(territory)

See `Cldr.Unit.measurement_system_for_territory/1`.

measurement_system_for_territory(territory, key)

See `Cldr.Unit.measurement_system_for_territory/2`.

measurement_system_from_locale(locale)

See `Cldr.Unit.measurement_system_from_locale/1`.

measurement_system_from_locale(locale, category)

See `Cldr.Unit.measurement_system_from_locale/2`.

measurement_system_from_locale(locale, backend, category)

See `Cldr.Unit.measurement_system_from_locale/3`.

measurement_systems_for_unit(unit)

See `Cldr.Unit.measurement_systems_for_unit/1`.

mult(unit_1, unit_2)

See `Cldr.Unit.Math.mult/2`.

mult!(unit_1, unit_2)

See `Cldr.Unit.Math.mult!/2`.

new(unit, value)

See `Cldr.Unit.new/2`.

new!(unit, value)

See `Cldr.Unit.new!/2`.

parse(unit_string, options \\ [])

Parse a string to create a new unit.

parse!(unit_string, options \\ [])

Parse a string to create a new unit or raises an exception.

parse_unit_name(unit_name_string, options \\ [])

Parse a string to find a matching unit-atom.

parse_unit_name!(unit_name_string, options \\ [])

Parse a string to find a matching unit-atom.

preferred_units(unit, options \\ [])

Returns a list of the preferred units for a given unit, locale, use case and scope.

preferred_units!(unit, options \\ [])

Returns a list of the preferred units for a given unit, locale, use case and scope.

round(unit)

See `Cldr.Unit.Math.round/1`.

round(unit, places)

See `Cldr.Unit.Math.round/2`.

round(unit, places, mode)

See `Cldr.Unit.Math.round/3`.

styles()

See `Cldr.Unit.known_styles/0`.

sub(unit_1, unit_2)

See `Cldr.Unit.Math.sub/2`.

sub!(unit_1, unit_2)

See `Cldr.Unit.Math.sub!/2`.

to_iolist(number, options \\ [])

Formats a number into an iolist according to a unit definition for a locale.

to_iolist!(number, options \\ [])

Formats a unit using `to_iolist/3` but raises if there is an error.

to_string(number, options \\ [])

Formats a number into a string according to a unit definition for a locale.

to_string!(number, options \\ [])

Formats a list using `to_string/3` but raises if there is an error.

unit_category(unit)

See `Cldr.Unit.unit_category/1`.

unit_strings_for(locale)
validate_style(unit)

See `Cldr.Unit.validate_style/1`.

validate_unit(unit)

See `Cldr.Unit.validate_unit/1`.

value(unit)

See `Cldr.Unit.value/1`.

zero(unit)

See `Cldr.Unit.zero/1`.

zero?(unit)

See `Cldr.Unit.zero?/1`.

# Functions

# add(unit_1, unit_2)

See `Cldr.Unit.Math.add/2`.

# add!(unit_1, unit_2)

See `Cldr.Unit.Math.add!/2`.

# compatible?(unit_1, unit_2)

See `Cldr.Unit.compatible?/2`.

# convert(unit_1, to_unit)

See `Cldr.Unit.Conversion.convert/2`.

# convert!(unit_1, to_unit)

See `Cldr.Unit.Conversion.convert!/2`.

# decompose(unit, list)

See `Cldr.Unit.decompose/2`.

# default_gender(locale_name)

# default_style()

See `Cldr.Unit.default_style/0`.

# display_name(unit, options \\ [])

    @spec display_name(Cldr.Unit.translatable_unit() | Cldr.Unit.t(), Keyword.t()) ::
      String.t() | {:error, {module(), binary()}}

Returns the localized display name for a unit.

The returned text is generally suitable for including in UI elements such as selection boxes.

## Arguments

- `unit` is any `t:Cldr.Unit` or any unit name returned by `Cldr.Unit.known_units/0`.

- `options` is a keyword list of options.

## Options

- `:locale` is any valid locale name returned by `Cldr.known_locale_names/0` or a `Cldr.LanguageTag` struct. The default is `Cldr.get_locale/0`.

- `:style` is one of those returned by `Cldr.Unit.known_styles/0`. The current styles are `:long`, `:short` and `:narrow`. The default is `style: :long`.

## Examples

    iex> BB.Cldr.Unit.display_name :liter
    "liters"

    iex> BB.Cldr.Unit.display_name :liter, locale: "fr"
    "litres"

    iex> BB.Cldr.Unit.display_name :liter, locale: "fr", style: :short
    "l"

# div(unit_1, unit_2)

See `Cldr.Unit.Math.div/2`.

# div!(unit_1, unit_2)

See `Cldr.Unit.Math.div!/2`.

# grammatical_features(locale_name)

# grammatical_gender(locale_name)

# known_styles()

See `Cldr.Unit.known_styles/0`.

# known_unit_categories()

See `Cldr.Unit.known_unit_categories/0`.

# known_units()

See `Cldr.Unit.known_units/0`.

# localize(unit)

    @spec localize(Cldr.Unit.t()) ::
      [Cldr.Unit.t(), ...] | {:error, {module(), String.t()}}

Localizes a unit according to the current processes locale and backend.

The current process's locale is set with `Cldr.put_locale/1`.

See `Cldr.Unit.localize/3` for further details.

# localize(unit, options \\ [])

    @spec localize(Cldr.Unit.t(), Keyword.t()) ::
      [Cldr.Unit.t(), ...] | {:error, {module(), String.t()}}

Localizes a unit according to a territory

A territory can be derived from a `t:Cldr.Locale.locale_name` or `t:Cldr.LangaugeTag`.

Use this function if you have a unit which should be presented in a user interface using units relevant to the audience. For example, a unit `#Cldr.Unit100, :meter>` might be better presented to a US audience as `#Cldr.Unit<328, :foot>`.

## Arguments

- `unit` is any unit returned by `Cldr.Unit.new/2`

- `options` is a keyword list of options

## 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.preferred_units/3`.

## Examples

    iex> unit = Cldr.Unit.new!(1.83, :meter)
    iex> BB.Cldr.Unit.localize(unit, usage: :person_height, territory: :US)
    [
      Cldr.Unit.new!(:foot, 6, usage: :person_height),
      Cldr.Unit.new!(:inch, "0.04724409448818897637795275598", usage: :person_height)
    ]

# measurement_system?(unit, systems)

See `Cldr.Unit.measurement_system?/2`.

# measurement_system_for(territory)

This function is deprecated. Use BB.Cldr.Unit.measurement_system_for_territory/1.

See `Cldr.Unit.measurement_system_for_territory/1`.

# measurement_system_for(territory, key)

This function is deprecated. Use BB.Cldr.Unit.measurement_system_for_territory/2.

See `Cldr.Unit.measurement_system_for_territory/2`.

# measurement_system_for_territory(territory)

See `Cldr.Unit.measurement_system_for_territory/1`.

# measurement_system_for_territory(territory, key)

See `Cldr.Unit.measurement_system_for_territory/2`.

# measurement_system_from_locale(locale)

See `Cldr.Unit.measurement_system_from_locale/1`.

# measurement_system_from_locale(locale, category)

See `Cldr.Unit.measurement_system_from_locale/2`.

# measurement_system_from_locale(locale, backend, category)

See `Cldr.Unit.measurement_system_from_locale/3`.

# measurement_systems_for_unit(unit)

See `Cldr.Unit.measurement_systems_for_unit/1`.

# mult(unit_1, unit_2)

See `Cldr.Unit.Math.mult/2`.

# mult!(unit_1, unit_2)

See `Cldr.Unit.Math.mult!/2`.

# new(unit, value)

See `Cldr.Unit.new/2`.

# new!(unit, value)

See `Cldr.Unit.new!/2`.

# parse(unit_string, options \\ [])

(since 3.10.0)

Parse a string to create a new unit.

This function attempts to parse a string into a `number` and `unit type`. If successful it attempts to create a new unit using `Cldr.Unit.new/3`.

The parsed `unit type` is aliased against all the known unit names for a give locale (or the current locale if no locale is specified). The known aliases for unit types can be returned with `MyApp.Cldr.Unit.unit_strings_for/1` where `MyApp.Cldr` is the name of a backend module.

## Arguments

- `unit string` is any string to be parsed and if possible used to create a new `t:Cldr.Unit`

- `options` is a keyword list of options

## Options

- `:locale` is any valid locale name returned by `Cldr.known_locale_names/0` or a `t:Cldr.LanguageTag` struct. The default is `Cldr.get_locale/0`

## Returns

- `{:ok, unit}` or

- `{:error, {exception, reason}}`

## Examples

    iex> BB.Cldr.Unit.parse "1kg"
    Cldr.Unit.new(1, :kilogram)

    iex> BB.Cldr.Unit.parse "1 tages", locale: "de"
    Cldr.Unit.new(1, :day)

    iex> BB.Cldr.Unit.parse "1 tag", locale: "de"
    Cldr.Unit.new(1, :day)

    iex> BB.Cldr.Unit.parse("42 millispangels")
    {:error, {Cldr.UnknownUnitError, "Unknown unit was detected at \"spangels\""}}

# parse!(unit_string, options \\ [])

(since 3.10.0)

Parse a string to create a new unit or raises an exception.

This function attempts to parse a string into a `number` and `unit type`. If successful it attempts to create a new unit using `Cldr.Unit.new/3`.

The parsed `unit type` is un-aliased against all the known unit names for a give locale (or the current locale if no locale is specified). The known aliases for unit types can be returned with `MyApp.Cldr.Unit.unit_strings_for/1` where `MyApp.Cldr` is the name of a backend module.

## Arguments

- `unit string` is any string to be parsed and if possible used to create a new `t:Cldr.Unit`

- `options` is a keyword list of options

## Options

- `:locale` is any valid locale name returned by `Cldr.known_locale_names/0` or a `t:Cldr.LanguageTag` struct. The default is `Cldr.get_locale/0`

## Returns

- `unit` or

- raises an exception

## Examples

    iex> BB.Cldr.Unit.parse! "1kg"
    Cldr.Unit.new!(1, :kilogram)

    iex> BB.Cldr.Unit.parse! "1 tages", locale: "de"
    Cldr.Unit.new!(1, :day)

    iex> BB.Cldr.Unit.parse!("42 candela per lux")
    Cldr.Unit.new!(42, "candela per lux")

    iex> BB.Cldr.Unit.parse!("42 millispangels")
    ** (Cldr.UnknownUnitError) Unknown unit was detected at "spangels"

# parse_unit_name(unit_name_string, options \\ [])

(since 3.13.4)

    @spec parse_unit_name(binary(), Keyword.t()) ::
      {:ok, atom()} | {:error, {module(), binary()}}

Parse a string to find a matching unit-atom.

This function attempts to parse a string and extract the `unit type`.

The parsed `unit type` is aliased against all the known unit names for a give locale (or the current locale if no locale is specified). The known aliases for unit types can be returned with `MyApp.Cldr.Unit.unit_strings_for/1` where `MyApp.Cldr` is the name of a backend module.

## Arguments

- `unit_name_string` is any string to be parsed and converted into a `unit type`

- `options` is a keyword list of options

## Options

- `:locale` is any valid locale name returned by `Cldr.known_locale_names/0` or a `t:Cldr.LanguageTag` struct. The default is `Cldr.get_locale/0`

- `:backend` is any module that includes `use Cldr` and therefore is a `Cldr` backend module. The default is `Cldr.default_backend!/0`.

- `:only` is a unit category or unit, or a list of unit categories and units. The parsed unit must match one of the categories or units in order to be valid. This is helpful when disambiguating parsed units. For example, parsing "w" could be either `:watt` or `:weeks`. Specifying `only: :duration` would return `:weeks`. Specifying `only: :power` would return `:watt`

- `:except` is the oppostte of `:only`. The parsed unit must not match the specified unit or category, or unit categories and units.

## Returns

- `{:ok, unit_name}` or

- `{:error, {exception, reason}}`

## Notes

- When both `:only` and `:except` options are passed, both conditions must be true in order to return a parsed result.

- Only units returned by `Cldr.Unit.known_units/0` can be used in the `:only` and `:except` filters.

## Examples

    iex> BB.Cldr.Unit.parse_unit_name "kg"
    {:ok, :kilogram}

    iex> BB.Cldr.Unit.parse_unit_name "w"
    {:ok, :watt}

    iex> BB.Cldr.Unit.parse_unit_name "w", only: :duration
    {:ok, :week}

    iex> BB.Cldr.Unit.parse_unit_name "m", only: [:year, :month, :day]
    {:ok, :month}

    iex> BB.Cldr.Unit.parse_unit_name "tages", locale: "de"
    {:ok, :day}

    iex> BB.Cldr.Unit.parse_unit_name "tag", locale: "de"
    {:ok, :day}

    iex> BB.Cldr.Unit.parse_unit_name("millispangels")
    {:error, {Cldr.UnknownUnitError, "Unknown unit was detected at \"spangels\""}}

# parse_unit_name!(unit_name_string, options \\ [])

(since 3.13.4)

Parse a string to find a matching unit-atom.

This function attempts to parse a string and extract the `unit type`.

The parsed `unit type` is aliased against all the known unit names for a give locale (or the current locale if no locale is specified). The known aliases for unit types can be returned with `MyApp.Cldr.Unit.unit_strings_for/1` where `MyApp.Cldr` is the name of a backend module.

## Arguments

- `unit_name_string` is any string to be parsed and converted into a `unit type`

- `options` is a keyword list of options

## Options

- `:locale` is any valid locale name returned by `Cldr.known_locale_names/0` or a `t:Cldr.LanguageTag` struct. The default is `Cldr.get_locale/0`

- `:backend` is any module that includes `use Cldr` and therefore is a `Cldr` backend module. The default is `Cldr.default_backend!/0`.

- `:only` is a unit category or unit, or a list of unit categories and units. The parsed unit must match one of the categories or units in order to be valid. This is helpful when disambiguating parsed units. For example, parsing "w" could be either `watts` or `:week`. Specifying `only: :duration` would return `:week`. Specifying `only: :power` would return `:watts`

- `:except` is the oppostte of `:only`. The parsed unit must not match the specified unit or category, or unit categories and units.

## Returns

- `unit_name` or

- raises an exception

## Notes

- When both `:only` and `:except` options are passed, both conditions must be true in order to return a parsed result.

- Only units returned by `Cldr.Unit.known_units/0` can be used in the `:only` and `:except` filters.

## Examples

    iex> BB.Cldr.Unit.parse_unit_name! "kg"
    :kilogram

    iex> BB.Cldr.Unit.parse_unit_name! "w"
    :watt

    iex> BB.Cldr.Unit.parse_unit_name! "w", only: :duration
    :week

    iex> BB.Cldr.Unit.parse_unit_name! "m", only: [:year, :month, :day]
    :month

    iex> BB.Cldr.Unit.parse_unit_name! "tages", locale: "de"
    :day

    iex> BB.Cldr.Unit.parse_unit_name! "tag", locale: "de"
    :day

    iex> BB.Cldr.Unit.parse_unit_name!("millispangels")
    ** (Cldr.UnknownUnitError) Unknown unit was detected at "spangels"

# preferred_units(unit, options \\ [])

    @spec preferred_units(Cldr.Unit.t(), Keyword.t()) ::
      {:ok, [atom(), ...], Keyword.t()} | {:error, {module(), binary()}}

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 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 `Cldr.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 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, 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> BB.Cldr.Unit.preferred_units meter, locale: "en-US", usage: :person_height
    {:ok, [:foot, :inch], []}
    iex> BB.Cldr.Unit.preferred_units meter, locale: "en-US", usage: :person
    {:ok, [:inch], []}
    iex> BB.Cldr.Unit.preferred_units meter, locale: "en-AU", usage: :person
    {:ok, [:centimeter], []}
    iex> BB.Cldr.Unit.preferred_units meter, locale: "en-US", usage: :road
    {:ok, [:foot], [round_nearest: 1]}
    iex> BB.Cldr.Unit.preferred_units meter, locale: "en-AU", usage: :road
    {:ok, [:meter], [round_nearest: 1]}

# preferred_units!(unit, options \\ [])

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 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 `Cldr.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 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

- `unit_list` or

- raises an exception

## Examples

    iex> meter = Cldr.Unit.new!(:meter, 2)
    iex> BB.Cldr.Unit.preferred_units! meter, locale: "en-US", usage: :person_height
    [:foot, :inch]
    iex> BB.Cldr.Unit.preferred_units! meter, locale: "en-AU", usage: :person
    [:centimeter]
    iex> BB.Cldr.Unit.preferred_units! meter, locale: "en-US", usage: :road
    [:foot]
    iex> BB.Cldr.Unit.preferred_units! meter, locale: "en-AU", usage: :road
    [:meter]

# round(unit)

See `Cldr.Unit.Math.round/1`.

# round(unit, places)

See `Cldr.Unit.Math.round/2`.

# round(unit, places, mode)

See `Cldr.Unit.Math.round/3`.

# styles()

See `Cldr.Unit.known_styles/0`.

# sub(unit_1, unit_2)

See `Cldr.Unit.Math.sub/2`.

# sub!(unit_1, unit_2)

See `Cldr.Unit.Math.sub!/2`.

# to_iolist(number, options \\ [])

    @spec to_iolist(Cldr.Unit.value() | Cldr.Unit.t() | [Cldr.Unit.t(), ...], Keyword.t()) ::
      {:ok, list()} | {:error, {atom(), binary()}}

Formats a number into an iolist according to a unit definition for a locale.

## Arguments

- `list_or_number` is any number (integer, float or Decimal) or a `t:Cldr.Unit` struct or a list of `t:Cldr.Unit` structs

- `options` is a keyword list

## Options

- `:unit` is any unit returned by `Cldr.Unit.known_units/0`. Ignored if the number to be formatted is a `t:Cldr.Unit` struct

- `:locale` is any valid locale name returned by `Cldr.known_locale_names/0` or a `Cldr.LanguageTag` struct. The default is `Cldr.get_locale/0`

- `:style` is one of those returned by `Cldr.Unit.known_styles`. The current styles are `:long`, `:short` and `:narrow`. The default is `style: :long`

- `:grammatical_case` indicates that a localisation for the given locale and given grammatical case should be used. See `Cldr.Unit.known_grammatical_cases/0` for the list of known grammatical cases. Note that not all locales define all cases. However all locales do define the `:nominative` case, which is also the default.

- `:gender` indicates that a localisation for the given locale and given grammatical gender should be used. See `Cldr.Unit.known_grammatical_genders/0` for the list of known grammatical genders. Note that not all locales define all genders. The default gender is `BB.Cldr.Unit.default_gender/1` for the given locale.

- `:list_options` is a keyword list of options for formatting a list which is passed through to `Cldr.List.to_string/3`. This is only applicable when formatting a list of units.

- Any other options are passed to `Cldr.Number.to_string/2` which is used to format the `number`

## Returns

- `{:ok, io_list}` or

- `{:error, {exception, message}}`

## Examples

    iex> BB.Cldr.Unit.to_iolist Cldr.Unit.new!(:gallon, 123)
    {:ok, ["123", " gallons"]}

# to_iolist!(number, options \\ [])

    @spec to_iolist!(
      Cldr.Unit.value() | Cldr.Unit.t() | [Cldr.Unit.t(), ...],
      Keyword.t()
    ) ::
      list() | no_return()

Formats a unit using `to_iolist/3` but raises if there is an error.

## Arguments

- `list_or_number` is any number (integer, float or Decimal) or a `t:Cldr.Unit` struct or a list of `t:Cldr.Unit` structs

- `options` is a keyword list

## Options

- `:unit` is any unit returned by `Cldr.Unit.known_units/0`. Ignored if the number to be formatted is a `t:Cldr.Unit` struct

- `:locale` is any valid locale name returned by `Cldr.known_locale_names/0` or a `Cldr.LanguageTag` struct. The default is `Cldr.get_locale/0`

- `:style` is one of those returned by `Cldr.Unit.known_styles/0`. The current styles are `:long`, `:short` and `:narrow`. The default is `style: :long`.

- `:grammatical_case` indicates that a localisation for the given locale and given grammatical case should be used. See `Cldr.Unit.known_grammatical_cases/0` for the list of known grammatical cases. Note that not all locales define all cases. However all locales do define the `:nominative` case, which is also the default.

- `:gender` indicates that a localisation for the given locale and given grammatical gender should be used. See `Cldr.Unit.known_grammatical_genders/0` for the list of known grammatical genders. Note that not all locales define all genders. The default gender is `BB.Cldr.Unit.default_gender/1` for the given locale.

- `:list_options` is a keyword list of options for formatting a list which is passed through to `Cldr.List.to_string/3`. This is only applicable when formatting a list of units.

- Any other options are passed to `Cldr.Number.to_string/2` which is used to format the `number`

## Returns

- `io_list` or

- raises an exception

## Examples

    iex> BB.Cldr.Unit.to_iolist! 123, unit: :gallon
    ["123", " gallons"]

# to_string(number, options \\ [])

    @spec to_string(Cldr.Unit.value() | Cldr.Unit.t() | [Cldr.Unit.t(), ...], Keyword.t()) ::
      {:ok, String.t()} | {:error, {atom(), binary()}}

Formats a number into a string according to a unit definition for a locale.

## Arguments

- `list_or_number` is any number (integer, float or Decimal) or a `t:Cldr.Unit` struct or a list of `t:Cldr.Unit` structs

- `options` is a keyword list

## Options

- `:unit` is any unit returned by `Cldr.Unit.known_units/0`. Ignored if the number to be formatted is a `t:Cldr.Unit` struct

- `:locale` is any valid locale name returned by `Cldr.known_locale_names/0` or a `Cldr.LanguageTag` struct. The default is `Cldr.get_locale/0`

- `:style` is one of those returned by `Cldr.Unit.known_styles`. The current styles are `:long`, `:short` and `:narrow`. The default is `style: :long`

- `:grammatical_case` indicates that a localisation for the given locale and given grammatical case should be used. See `Cldr.Unit.known_grammatical_cases/0` for the list of known grammatical cases. Note that not all locales define all cases. However all locales do define the `:nominative` case, which is also the default.

- `:gender` indicates that a localisation for the given locale and given grammatical gender should be used. See `Cldr.Unit.known_grammatical_genders/0` for the list of known grammatical genders. Note that not all locales define all genders. The default gender is `BB.Cldr.Unit.default_gender/1` for the given locale.

- `:list_options` is a keyword list of options for formatting a list which is passed through to `Cldr.List.to_string/3`. This is only applicable when formatting a list of units.

- Any other options are passed to `Cldr.Number.to_string/2` which is used to format the `number`

## Returns

- `{:ok, formatted_string}` or

- `{:error, {exception, message}}`

## Examples

    iex> BB.Cldr.Unit.to_string Cldr.Unit.new!(:gallon, 123)
    {:ok, "123 gallons"}

    iex> BB.Cldr.Unit.to_string Cldr.Unit.new!(:gallon, 1)
    {:ok, "1 gallon"}

    iex> BB.Cldr.Unit.to_string Cldr.Unit.new!(:gallon, 1), locale: "af"
    {:ok, "1 gelling"}

    iex> BB.Cldr.Unit.to_string Cldr.Unit.new!(:gallon, 1), locale: "af-NA"
    {:ok, "1 gelling"}

    iex> BB.Cldr.Unit.to_string Cldr.Unit.new!(:gallon, 1), locale: "bs"
    {:ok, "1 galon"}

    iex> BB.Cldr.Unit.to_string Cldr.Unit.new!(:gallon, 1234), format: :long
    {:ok, "1 thousand gallons"}

    iex> BB.Cldr.Unit.to_string Cldr.Unit.new!(:gallon, 1234), format: :short
    {:ok, "1K gallons"}

    iex> BB.Cldr.Unit.to_string Cldr.Unit.new!(:megahertz, 1234)
    {:ok, "1,234 megahertz"}

    iex> BB.Cldr.Unit.to_string Cldr.Unit.new!(:megahertz, 1234), style: :narrow
    {:ok, "1,234MHz"}

    iex> BB.Cldr.Unit.to_string Cldr.Unit.new!(:megabyte, 1234), locale: "en", style: :unknown
    {:error, {Cldr.UnknownFormatError, "The unit style :unknown is not known."}}

# to_string!(number, options \\ [])

    @spec to_string!(
      Cldr.Unit.value() | Cldr.Unit.t() | [Cldr.Unit.t(), ...],
      Keyword.t()
    ) ::
      String.t() | no_return()

Formats a list using `to_string/3` but raises if there is an error.

## Arguments

- `list_or_number` is any number (integer, float or Decimal) or a `t:Cldr.Unit` struct or a list of `t:Cldr.Unit` structs

- `options` is a keyword list

## Options

- `:unit` is any unit returned by `Cldr.Unit.known_units/0`. Ignored if the number to be formatted is a `t:Cldr.Unit` struct

- `:locale` is any valid locale name returned by `Cldr.known_locale_names/0` or a `Cldr.LanguageTag` struct. The default is `Cldr.get_locale/0`

- `:style` is one of those returned by `Cldr.Unit.known_styles`. The current styles are `:long`, `:short` and `:narrow`. The default is `style: :long`

- `:grammatical_case` indicates that a localisation for the given locale and given grammatical case should be used. See `Cldr.Unit.known_grammatical_cases/0` for the list of known grammatical cases. Note that not all locales define all cases. However all locales do define the `:nominative` case, which is also the default.

- `:gender` indicates that a localisation for the given locale and given grammatical gender should be used. See `Cldr.Unit.known_grammatical_genders/0` for the list of known grammatical genders. Note that not all locales define all genders. The default gender is `BB.Cldr.Unit.default_gender/1` for the given locale.

- `:list_options` is a keyword list of options for formatting a list which is passed through to `Cldr.List.to_string/3`. This is only applicable when formatting a list of units.

- Any other options are passed to `Cldr.Number.to_string/2` which is used to format the `number`

## Returns

- `formatted_string` or

- raises an exception

## Examples

    iex> BB.Cldr.Unit.to_string! 123, unit: :gallon
    "123 gallons"

    iex> BB.Cldr.Unit.to_string! 1, unit: :gallon
    "1 gallon"

    iex> BB.Cldr.Unit.to_string! 1, unit: :gallon, locale: "af"
    "1 gelling"

# unit_category(unit)

See `Cldr.Unit.unit_category/1`.

# unit_strings_for(locale)

# validate_style(unit)

See `Cldr.Unit.validate_style/1`.

# validate_unit(unit)

See `Cldr.Unit.validate_unit/1`.

# value(unit)

See `Cldr.Unit.value/1`.

# zero(unit)

See `Cldr.Unit.zero/1`.

# zero?(unit)

See `Cldr.Unit.zero?/1`.