Cldr.Unit.to_string
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.
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 at:Cldr.Unit
struct or a list oft:Cldr.Unit
structsbackend
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 at:Cldr.Unit
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.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.: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.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."}}