See Cldr.Unit.Math.add/2.

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

See Cldr.Unit.compatible?/2.

See Cldr.Unit.Conversion.convert/2.

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

See Cldr.Unit.decompose/2.

See Cldr.Unit.default_style/0.

@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.available_styles. The current styles are :long, :short and :narrow. The default is style: :long.

Examples

iex> Bonfire.Common.Localise.Cldr.Unit.display_name :liter
"liters"

iex> Bonfire.Common.Localise.Cldr.Unit.display_name :liter, locale: "fr"
"litres"

iex> Bonfire.Common.Localise.Cldr.Unit.display_name :liter, locale: "fr", style: :short
"l"

See Cldr.Unit.Math.div/2.

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

See Cldr.Unit.known_styles/0.

See Cldr.Unit.known_unit_categories/0.

See Cldr.Unit.known_units/0.

@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.

@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> Bonfire.Common.Localise.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)
]

See Cldr.Unit.measurement_system?/2.

See Cldr.Unit.measurement_system_for_territory/1.

See Cldr.Unit.measurement_system_for_territory/2.

See Cldr.Unit.measurement_system_for_territory/1.

See Cldr.Unit.measurement_system_for_territory/2.

See Cldr.Unit.measurement_system_from_locale/1.

See Cldr.Unit.measurement_system_from_locale/2.

See Cldr.Unit.measurement_system_from_locale/3.

See Cldr.Unit.measurement_systems_for_unit/1.

See Cldr.Unit.Math.mult/2.

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

See Cldr.Unit.new/2.

See Cldr.Unit.new!/2.

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> Bonfire.Common.Localise.Cldr.Unit.parse "1kg"
Cldr.Unit.new(1, :kilogram)

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

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

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

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> Bonfire.Common.Localise.Cldr.Unit.parse! "1kg"
Cldr.Unit.new!(1, :kilogram)

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

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

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

@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> Bonfire.Common.Localise.Cldr.Unit.parse_unit_name "kg"
{:ok, :kilogram}

iex> Bonfire.Common.Localise.Cldr.Unit.parse_unit_name "w"
{:ok, :watt}

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

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

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

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

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

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> Bonfire.Common.Localise.Cldr.Unit.parse_unit_name! "kg"
:kilogram

iex> Bonfire.Common.Localise.Cldr.Unit.parse_unit_name! "w"
:watt

iex> Bonfire.Common.Localise.Cldr.Unit.parse_unit_name! "w", only: :duration
:week

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

iex> Bonfire.Common.Localise.Cldr.Unit.parse_unit_name! "tages", locale: "de"
:day

iex> Bonfire.Common.Localise.Cldr.Unit.parse_unit_name! "tag", locale: "de"
:day

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

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

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> Bonfire.Common.Localise.Cldr.Unit.preferred_units! meter, locale: "en-US", usage: :person_height
[:foot, :inch]
iex> Bonfire.Common.Localise.Cldr.Unit.preferred_units! meter, locale: "en-AU", usage: :person
[:centimeter]
iex> Bonfire.Common.Localise.Cldr.Unit.preferred_units! meter, locale: "en-US", usage: :road
[:foot]
iex> Bonfire.Common.Localise.Cldr.Unit.preferred_units! meter, locale: "en-AU", usage: :road
[:meter]

See Cldr.Unit.Math.round/1.

See Cldr.Unit.Math.round/2.

See Cldr.Unit.Math.round/3.

See Cldr.Unit.known_styles/0.

See Cldr.Unit.Math.sub/2.

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

@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 Bonfire.Common.Localise.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> Bonfire.Common.Localise.Cldr.Unit.to_iolist Cldr.Unit.new!(:gallon, 123)
{:ok, ["123", " gallons"]}

@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 Bonfire.Common.Localise.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> Bonfire.Common.Localise.Cldr.Unit.to_iolist! 123, unit: :gallon
["123", " gallons"]

@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 Bonfire.Common.Localise.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> Bonfire.Common.Localise.Cldr.Unit.to_string Cldr.Unit.new!(:gallon, 123)
{:ok, "123 gallons"}

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

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

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

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

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

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

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

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

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

@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 Bonfire.Common.Localise.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> Bonfire.Common.Localise.Cldr.Unit.to_string! 123, unit: :gallon
"123 gallons"

iex> Bonfire.Common.Localise.Cldr.Unit.to_string! 1, unit: :gallon
"1 gallon"

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

See Cldr.Unit.unit_category/1.

See Cldr.Unit.validate_style/1.

See Cldr.Unit.validate_unit/1.

See Cldr.Unit.value/1.

See Cldr.Unit.zero/1.

See Cldr.Unit.zero?/1.