@spec grammar(Cldr.Unit.t(), Keyword.t()) ::
  grammar_list() | {grammar_list(), grammar_list()}

Traverses the components of a unit and resolves a list of base units with their gramatical case and plural selector definitions for a given locale.

This function relies upon the internal representation of units and grammatical features and is primarily for the support of formatting a function through Cldr.Unit.to_string/2.

Arguments

• unit is a Cldr.Unit.t/0 or a binary unit string

Options

• :locale is any valid locale name returned by Cldr.known_locale_names/1 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.

Returns

Examples

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

Formats a number into an iolist according to a unit definition for the current process's locale and backend.

See Cldr.Unit.Format.to_iolist/3 for full details.

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

Arguments

• list_or_unit is any number (integer, float or Decimal) or a Cldr.Unit.t/0 struct or a list of Cldr.Unit.t/0 structs or a Cldr.Unit.Range.t/0 struct.

• 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 Cldr.Unit.t/0 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.

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

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

Formats a number into an iolist according to a unit definition for the current process's locale and backend.

See Cldr.Unit.Format.to_iolist!/3 for full details.

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

Arguments

• number is any number (integer, float or Decimal) or a Cldr.Unit.t/0 struct or a list of Cldr.Unit.t/0 structs or a Cldr.Unit.Range.t/0 struct.

• 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 Cldr.Unit.t/0 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.

• :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> Cldr.Unit.Format.to_iolist! 123, unit: :gallon
["123", " gallons"]

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

Formats a number into a string according to a unit definition using the current process's locale and backend.

See Cldr.Unit.to_string/3 for full details.

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

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

During processing any :format_options of a Cldr.Unit.t/0 are merged into the options argument.

Arguments

• list_or_unit is any number (integer, float or Decimal) or a Cldr.Unit.t/0 struct or a list of Cldr.Unit.t/0 structs or a Cldr.Unit.Range.t/0 struct.

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

• options is a keyword list of options.

Options

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

• :locale is any valid locale name returned by Cldr.known_locale_names/1 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.

• :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> Cldr.Unit.Format.to_string Cldr.Unit.new!(:gallon, 123), MyApp.Cldr
{:ok, "123 gallons"}

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

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

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

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

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

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

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

iex> {:ok, range} = Cldr.Unit.Range.new(Cldr.Unit.new!(:gram, 1), Cldr.Unit.new!(:gram, 5))
iex> Cldr.Unit.to_string(range, locale: :ja)
{:ok, "1～5 グラム"}

iex> Cldr.Unit.Format.to_string Cldr.Unit.new!(123, :foot), MyApp.Cldr
{:ok, "123 feet"}

iex> Cldr.Unit.Format.to_string 123, MyApp.Cldr, unit: :foot
{:ok, "123 feet"}

iex> Cldr.Unit.Format.to_string Decimal.new(123), MyApp.Cldr, unit: :foot
{:ok, "123 feet"}

iex> Cldr.Unit.to_string Cldr.Unit.new!(2, "curr-usd-per-gallon"), MyApp.Cldr
{:ok, "$2.00 per gallon"}

iex> Cldr.Unit.to_string Cldr.Unit.new!(2, "gallon-per-curr-usd"), MyApp.Cldr
{:ok, "2 gallons per US dollar"}

iex> Cldr.Unit.Format.to_string 123, MyApp.Cldr, unit: :megabyte, locale: "en", style: :unknown
{:error, {Cldr.UnknownFormatError, "The unit style :unknown is not known."}}

iex> Cldr.Unit.Format.to_string 123, MyApp.Cldr, unit: :megabyte, locale: "en",
...> grammatical_gender: :feminine
{:error, {Cldr.UnknownGrammaticalGenderError,
  "The locale :en does not define a grammatical gender :feminine. The valid genders are [:masculine]"
}}

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

Formats a unit or unit range or a number into a string according to a unit definition for the current locale.

During processing any :format_options of a Cldr.Unit.t/0 are merged into the options argument.

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

See Cldr.Unit.to_string!/3 for full details.

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

Formats a unit or unit range or a number into a string according to a unit definition for a locale. Raises on error.

During processing any :format_options of a Cldr.Unit.t/0 are merged into the options argument.

During processing any :format_options of a Cldr.Unit.t/0 are merged with options with options taking precedence.

Arguments

• number_or_unit is any number (integer, float or Decimal) or a Cldr.Unit.t/0 struct or a list of Cldr.Unit.t/0 structs or a Cldr.Unit.Range.t/0 struct.

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

• 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 Cldr.Unit.t/0 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.

• 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> Cldr.Unit.Format.to_string! Cldr.Unit.new!(:gallon, 123), MyApp.Cldr
"123 gallons"

iex> Cldr.Unit.Format.to_string! Cldr.Unit.new!(:gallon, 1), MyApp.Cldr
"1 gallon"

iex> Cldr.Unit.Format.to_string! Cldr.Unit.new!(:gallon, 1), MyApp.Cldr, locale: "af"
"1 gelling"

iex> {:ok, range} = Cldr.Unit.Range.new(Cldr.Unit.new!(:gram, 1), Cldr.Unit.new!(:gram, 5))
iex> Cldr.Unit.to_string!(range, locale: :ja)
"1～5 グラム"

Traverses a unit's decomposition and invokes a function on each node of the composition tree.

Arguments

• unit is any unit returned by Cldr.Unit.new/2

• fun is any single-arity function. It will be invoked for each node of the composition tree. The argument is a tuple of the following form:

  • {:unit, argument}
  • {:times, {argument_1, argument_2}}
  • {:prefix, {prefix_unit, argument}}
  • {:power, {power_unit, argument}}
  • {:per, {argument_1, argument_2}}

  Where the arguments are the results returned from the fun/1.

Returns

The result returned from fun/1