View Source Cldr.Unit.Format (Cldr Units v3.17.0)
Functions for formatting a unit or unit range into an iolist or a string.
Summary
Functions
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.
Formats a number into an iolist according to a unit definition for the current process's locale and backend.
Formats a number into an iolist according to a unit definition for a locale.
Formats a number into an iolist according to a unit definition for the current process's locale and backend.
Formats a unit using to_iolist/3
but raises if there is
an error.
Formats a number into a string according to a unit definition using the current process's locale and backend.
Formats a unit or unit range or a number into a string according to a unit definition for a locale.
Formats a unit or unit range or a number into a string according to a unit definition for the current locale.
Formats a unit or unit range or a number into a string according to a unit definition for a locale. Raises on error.
Traverses a unit's decomposition and invokes a function on each node of the composition tree.
Functions
@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 aCldr.Unit.t/0
or a binary unit string
Options
:locale
is any valid locale name returned byCldr.known_locale_names/1
or at:Cldr.LanguageTag
struct. The default isCldr.get_locale/0
backend
is any module that includesuse Cldr
and therefore is aCldr
backend module. The default isCldr.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 aCldr.Unit.t/0
struct or a list ofCldr.Unit.t/0
structs or aCldr.Unit.Range.t/0
struct.options
is a keyword list
Options
:unit
is any unit returned byCldr.Unit.known_units/0
. Ignored if the number to be formatted is aCldr.Unit.t/0
struct:locale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag
struct. The default isCldr.get_locale/0
:style
is one of those returned byCldr.Unit.available_styles
. The current styles are:long
,:short
and:narrow
. The default isstyle: :long
:grammatical_case
indicates that a localisation for the given locale and given grammatical case should be used. SeeCldr.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. SeeCldr.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 toCldr.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 thenumber
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 aCldr.Unit.t/0
struct or a list ofCldr.Unit.t/0
structs or aCldr.Unit.Range.t/0
struct.options
is a keyword list
Options
:unit
is any unit returned byCldr.Unit.known_units/0
. Ignored if the number to be formatted is aCldr.Unit.t/0
struct:locale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag
struct. The default isCldr.get_locale/0
:style
is one of those returned byCldr.Unit.known_styles/0
. The current styles are:long
,:short
and:narrow
. The default isstyle: :long
.:grammatical_case
indicates that a localisation for the given locale and given grammatical case should be used. SeeCldr.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. SeeCldr.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 toCldr.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 thenumber
Returns
io_list
orraises 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 aCldr.Unit.t/0
struct or a list ofCldr.Unit.t/0
structs or aCldr.Unit.Range.t/0
struct.backend
is any module that includesuse Cldr
and therefore is aCldr
backend module. The default isCldr.default_backend!/0
.options
is a keyword list of options.
Options
:unit
is any unit returned byCldr.Unit.known_units/0
. Ignored if the number to be formatted is aCldr.Unit.t/0
struct.:locale
is any valid locale name returned byCldr.known_locale_names/1
or aCldr.LanguageTag
struct. The default isCldr.get_locale/0
.style
is one of those returned byCldr.Unit.known_styles/0
. The current styles are:long
,:short
and:narrow
. The default isstyle: :long
.:grammatical_case
indicates that a localisation for the given locale and given grammatical case should be used. SeeCldr.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. SeeCldr.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 toCldr.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 thenumber
.
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 aCldr.Unit.t/0
struct or a list ofCldr.Unit.t/0
structs or aCldr.Unit.Range.t/0
struct.backend
is any module that includesuse Cldr
and therefore is aCldr
backend module. The default isCldr.default_backend!/0
.options
is a keyword list.
Options
:unit
is any unit returned byCldr.Unit.known_units/0
. Ignored if the number to be formatted is aCldr.Unit.t/0
struct.:locale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag
struct. The default isCldr.get_locale/0
.:style
is one of those returned byCldr.Unit.available_styles
. The current styles are:long
,:short
and:narrow
. The default isstyle: :long
.Any other options are passed to
Cldr.Number.to_string/2
which is used to format thenumber
.
Returns
formatted_string
orraises 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 byCldr.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