Cldr.Unit.to_string

You're seeing just the function to_string, go back to Cldr.Unit module for more information.

Specs

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

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

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

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

Link to this function

to_string(list_or_unit, backend, options \\ [])

View Source

Specs

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

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

During processing any :format_options of a Unit.t() are merged with options with options taking precedence.

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

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

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

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

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

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

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

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

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

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

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

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

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

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