Cldr.Unit (Cldr Units v3.4.0) View Source
Supports the CLDR Units definitions which provide for the localization of many unit types.
The primary public API defines:
Cldr.Unit.to_string/3
which, given a unit or unit list will output a localized stringCldr.Unit.known_units/0
identifies the available units for localizationCldr.Unit.{add, sub, mult, div}/2
to support basic unit mathematics between units of compatible type (like length or volume)Cldr.Unit.compare/2
to compare one unit to another unit as long as they are convertable.Cldr.Unit.convert/2
to convert one unit to another unit as long as they are convertable.Cldr.Unit.localize/3
will convert a unit into the units preferred for a given locale and usageCldr.Unit.preferred_units/3
which, for a given unit and locale, will return a list of preferred units that can be applied toCldr.Unit.decompose/2
Cldr.Unit.decompose/2
to take a unit and return a list of units decomposed by a list of smaller units.
Link to this section Summary
Functions
Returns the base unit for a given unit.
Returns a mapping of base units to their respective unit categories.
Returns a mapping from unit categories to the base unit.
Returns a boolean indicating if two units are of the same unit category.
Decomposes a unit into subunits.
Returns the default formatting style.
Returns the localized display name for a unit.
Return a list of known measurement systems.
Returns a list of the known unit categories.
Returns the known units.
Returns the units that are defined for a given category (such as :volume, :length)
Returns the list of units defined for a given category.
Localizes a unit according to the current processes locale and backend.
Localizes a unit according to a territory
Returns a boolean indicating if a given unit belongs to one or more measurement systems.
Returns the default measurement system for a territory and a given system key.
Determines the preferred measurement system from a locale.
Returns the list of units defined in a given measurement system.
Returns a map of measurement systems by territory.
Returns the measurement systems for a given unit.
Returns a new Unit.t
struct.
Returns a new Unit.t
struct or raises on error.
Convert a ratio Unit to a float unit
Returns the known styles for a unit.
Formats a number into a 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 or raises on error.
Formats a number into an iolist according to a unit definition for the current process's locale and backend or raises on error.
Formats a number into a string according to a unit definition for the current process's locale and backend.
Formats a number into a string according to a unit definition for a locale.
Formats a number into a string according to a unit definition for the current process's locale and backend or raises on error.
Formats a number into a string according to a unit definition for the current process's locale and backend or raises on error.
Returns the units category for a given unit
Returns a mapping between Unit categories and the uses they define.
Validates a unit style and normalizes it to a standard downcased atom form
Validates a unit name and normalizes it,
Return the value of the Unit struct
Returns a new unit of the same unit type but with a zero value.
Returns a boolean indicating whether a given unit has a zero value.
Link to this section Types
Specs
category() :: atom()
Specs
conversion() :: Cldr.Unit.Conversion.t() | {[Cldr.Unit.Conversion.t(), ...], [Cldr.Unit.Conversion.t(), ...]} | list()
Specs
locale() :: Cldr.Locale.locale_name() | Cldr.LanguageTag.t()
Specs
measurement_system() :: :metric | :ussystem | :uksystem
Specs
measurement_system_key() :: :default | :temperature | :paper_size
Specs
style() :: :narrow | :short | :long
Specs
t() :: %Cldr.Unit{ base_conversion: conversion(), format_options: [], unit: unit(), usage: usage(), value: value() }
Specs
translatable_unit() :: atom()
Specs
unit() :: translatable_unit() | String.t()
Specs
usage() :: atom()
Specs
value() :: Cldr.Math.number_or_decimal() | Ratio.t()
Link to this section Functions
See Cldr.Unit.Math.add/2
.
Returns the base unit for a given unit.
Argument
unit
is either at:Cldr.Unit
or anatom
Returns
{:ok, base_unit}
or{:error, {exception, reason}}
Example
iex> Cldr.Unit.base_unit :square_kilometer
{:ok, :square_meter}
iex> Cldr.Unit.base_unit :square_table
{:error, {Cldr.UnknownUnitError, "Unknown unit was detected at \"table\""}}
Specs
base_unit_category_map() :: map()
Returns a mapping of base units to their respective unit categories.
Base units are a common unit for a given unit category which are used in two scenarios:
When converting between units. If two units have the same base unit they can be converted to each other. See
Cldr.Unit.Conversion
.When identifying the preferred units for a given locale or territory, the base unit is used to aid identification of preferences for given use cases. See
Cldr.Unit.Preference
.
Example
=> Cldr.Unit.base_unit_category_map
%{
"kilogram_square_meter_per_cubic_second_ampere" => :voltage,
"kilogram_meter_per_meter_square_second" => :torque,
"square_meter" => :area,
"kilogram" => :mass,
"kilogram_square_meter_per_square_second" => :energy,
"revolution" => :angle,
"candela_per_square_meter" => :luminance,
...
}
Returns a mapping from unit categories to the base unit.
Specs
Returns a boolean indicating if two units are of the same unit category.
Arguments
unit_1
andunit_2
are any units returned byCldr.Unit.new/2
or a valid unit name.
Returns
true
orfalse
Examples
iex> Cldr.Unit.compatible? :foot, :meter
true
iex> Cldr.Unit.compatible? Cldr.Unit.new!(:foot, 23), :meter
true
iex> Cldr.Unit.compatible? :foot, :liter
false
iex> Cldr.Unit.compatible? "light_year_per_second", "meter_per_gallon"
false
Specs
Decomposes a unit into subunits.
Any list compatible units can be provided
however a list of units of decreasing scale
is recommended. For example [:foot, :inch]
or [:kilometer, :meter, :centimeter, :millimeter]
Arguments
unit
is any unit returned byCldr.Unit.new/2
unit_list
is a list of valid units (one or more from the list returned byCldr.Unit.known_units/0
. All units must be from the same unit category.format_options
is a Keyword list of options that is added to the last unit inunit_list
. Theformat_options
will be applied when callingCldr.Unit.to_string/3
on theunit
. The default is[]
.
Returns
- a list of units after decomposition or an error tuple
Examples
iex> u = Cldr.Unit.new!(10.3, :foot)
iex> Cldr.Unit.decompose u, [:foot, :inch]
[Cldr.Unit.new!(:foot, 10), Cldr.Unit.new!(:inch, Ratio.new(18, 5))]
iex> u = Cldr.Unit.new!(:centimeter, 1111)
iex> Cldr.Unit.decompose u, [:kilometer, :meter, :centimeter, :millimeter]
[Cldr.Unit.new!(:meter, 11), Cldr.Unit.new!(:centimeter, 11)]
Specs
default_style() :: style()
Returns the default formatting style.
Example
iex> Cldr.Unit.default_style
:long
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 anyt:Cldr.Unit
or any unit name returned byCldr.Unit.known_units/0
.options
is a keyword list of options.
Options
:locale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.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
.:style
is one of those returned byCldr.Unit.available_styles
. The current styles are:long
,:short
and:narrow
. The default isstyle: :long
.
Examples
iex> Cldr.Unit.display_name :liter
"liters"
iex> Cldr.Unit.display_name :liter, locale: "fr"
"litres"
iex> Cldr.Unit.display_name :liter, locale: "fr", style: :short
"l"
See Cldr.Unit.Math.div/2
.
Specs
known_measurement_systems() :: %{ required(measurement_system()) => %{alias: atom(), description: String.t()} }
Return a list of known measurement systems.
Example
iex> Cldr.Unit.known_measurement_systems()
%{
metric: %{alias: nil, description: "Metric System"},
uksystem: %{
alias: :imperial,
description: "UK System of measurement: feet, pints, etc.; pints are 20oz"
},
ussystem: %{
alias: nil,
description: "US System of measurement: feet, pints, etc.; pints are 16oz"
}
}
Specs
known_unit_categories() :: [category()]
Returns a list of the known unit categories.
Example
iex> Cldr.Unit.known_unit_categories
[:acceleration, :angle, :area, :concentr, :consumption, :digital,
:duration, :electric, :energy, :force, :frequency, :graphics, :length, :light, :mass,
:power, :pressure, :speed, :temperature, :torque, :volume]
Specs
known_units() :: [translatable_unit(), ...]
Returns the known units.
Known units means units that can be localised directly.
Example
=> Cldr.Unit.known_units
[:acre, :acre_foot, :ampere, :arc_minute, :arc_second, :astronomical_unit, :bit,
:bushel, :byte, :calorie, :carat, :celsius, :centiliter, :centimeter, :century,
:cubic_centimeter, :cubic_foot, :cubic_inch, :cubic_kilometer, :cubic_meter,
:cubic_mile, :cubic_yard, :cup, :cup_metric, :day, :deciliter, :decimeter,
:degree, :fahrenheit, :fathom, :fluid_ounce, :foodcalorie, :foot, :furlong,
:g_force, :gallon, :gallon_imperial, :generic, :gigabit, :gigabyte, :gigahertz,
:gigawatt, :gram, :hectare, :hectoliter, :hectopascal, :hertz, :horsepower,
:hour, :inch, ...]
Specs
known_units_by_category() :: %{ required(category()) => [translatable_unit(), ...] }
Returns the units that are defined for a given category (such as :volume, :length)
See also Cldr.Unit.known_unit_categories/0
.
Example
=> Cldr.Unit.known_units_by_category
%{
acceleration: [:g_force, :meter_per_square_second],
angle: [:arc_minute, :arc_second, :degree, :radian, :revolution],
area: [:acre, :dunam, :hectare, :square_centimeter, :square_foot,
:square_inch, :square_kilometer, :square_meter, :square_mile, :square_yard],
concentr: [:karat, :milligram_per_deciliter, :millimole_per_liter, :mole,
:percent, :permille, :permillion, :permyriad], ...
}
Specs
known_units_for_category(category()) :: {:ok, [translatable_unit(), ...]} | {:error, {module(), String.t()}}
Returns the list of units defined for a given category.
Arguments
category
is any unit category returned byCldr.Unit.known_unit_categories/0
.
See also Cldr.Unit.known_units_by_category/0
.
Example
=> Cldr.Unit.known_units_for_category :volume
{
:ok,
[
:cubic_centimeter,
:centiliter,
:hectoliter,
:cubic_kilometer,
:acre_foot,
...
]
}
Localizes a unit according to the current processes locale and backend.
The curent process's locale is set with
Cldr.put_locale/1
.
See Cldr.Unit.localize/3
for futher
details.
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.Unit328, :foot>
.
Arguments
unit
is any unit returned byCldr.Unit.new/2
backend
is any module that includesuse Cldr
and therefore is aCldr
backend module.options
is a keyword list of options
Options
:locale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag
struct. The default isbackend.get_locale/0
:territory
is any valid territory code returned byCldr.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 availableusage
varyies according to the unit category. SeeCldr.Unit.preferred_units/3
.
Examples
iex> unit = Cldr.Unit.new!(1.83, :meter)
iex> Cldr.Unit.localize(unit, usage: :person_height, territory: :US)
[Cldr.Unit.new!(:foot, 6), Cldr.Unit.new!(:inch, Ratio.new(6485183463413016, 137269716642252725))]
Specs
measurement_system?(t() | unit(), measurement_system() | [measurement_system()]) :: boolean() | {:error, {module(), String.t()}}
Returns a boolean indicating if a given unit belongs to one or more measurement systems.
When a list or more than one measurement
system is provided, the test is one of
inclusion. That is, if the unit belongs to
any of the provided measurement systems
the return is true
.
Arguments
system
is any measurement system or list of measurement systems returned byCldr.Unit.known_measurement_systems/0
Returns
true
orfalse
or{:error, {exception, message}}
Examples
iex> Cldr.Unit.measurement_system? :foot, :uksystem
true
iex> Cldr.Unit.measurement_system? :foot, [:uksystem, :ussystem]
true
iex> Cldr.Unit.measurement_system? :foot, [:metric]
false
iex> Cldr.Unit.measurement_system? :invalid, [:metric]
{:error, {Cldr.UnknownUnitError, "The unit :invalid is not known."}}
Specs
measurement_system_for_territory(atom(), atom()) :: :metric | :ussystem | :uksystem | :a4 | :us_letter | {:error, {module(), String.t()}}
Returns the default measurement system for a territory and a given system key.
Arguments
territory
is any valid territory returned byCldr.validate_territory/1
key
is any measurement system key. The known keys are:default
,:temperature
and:paper_size
. The default key is:default
.
Examples
iex> Cldr.Unit.measurement_system_for_territory :US
:ussystem
iex> Cldr.Unit.measurement_system_for_territory :GB
:uksystem
iex> Cldr.Unit.measurement_system_for_territory :AU
:metric
iex> Cldr.Unit.measurement_system_for_territory :US, :temperature
:ussystem
iex> Cldr.Unit.measurement_system_for_territory :GB, :temperature
:uksystem
iex> Cldr.Unit.measurement_system_for_territory :GB, :volume
{:error,
{Cldr.Unit.InvalidSystemKeyError,
"The key :volume is not known. Valid keys are :default, :paper_size and :temperature"}}
measurement_system_from_locale(locale \\ Cldr.get_locale(), key \\ :default)
View Source (since 3.4.0)Specs
measurement_system_from_locale( Cldr.LanguageTag.t() | Cldr.Locale.locale_name(), measurement_system_key() ) :: measurement_system() | {:error, {module(), String.t()}}
Determines the preferred measurement system from a locale.
See also Cldr.Unit.known_measurement_systems/0
.
Arguments
locale
is any valid locale name returned byCldr.known_locale_names/0
or at:Cldr.LanguageTag
struct. The default isCldr.get_locale/0
.key
is any measurement system key. The known keys are:default
,:temperature
and:paper_size
. The default key is:default
.
Examples
iex> Cldr.Unit.measurement_system_from_locale "en"
:ussystem
iex> Cldr.Unit.measurement_system_from_locale "en-GB"
:uksystem
iex> Cldr.Unit.measurement_system_from_locale "en-AU"
:metric
iex> Cldr.Unit.measurement_system_from_locale "en-AU-u-ms-ussystem"
:ussystem
iex> Cldr.Unit.measurement_system_from_locale "en-GB", :temperature
:uksystem
iex> Cldr.Unit.measurement_system_from_locale "en-AU", :paper_size
:a4
iex> Cldr.Unit.measurement_system_from_locale "en-GB", :invalid
{:error,
{Cldr.Unit.InvalidSystemKeyError,
"The key :invalid is not known. Valid keys are :default, :paper_size and :temperature"}}
Specs
measurement_system_units(measurement_system()) :: [translatable_unit(), ...] | {:error, {module(), String.t()}}
Returns the list of units defined in a given measurement system.
Arguments
system
is any measurement system returned byCldr.Unit.known_measurement_systems/0
Returns
A list of translatable units as atoms or
{:error, {exception, message}}
Example
=> Cldr.Unit.measurement_system_units :uksystem
[
:ton,
:inch,
:yard,
...
]
Specs
measurement_systems_by_territory() :: %{required(Cldr.territory()) => map()}
Returns a map of measurement systems by territory.
Example
=> Cldr.Unit.measurement_systems_by_territory
%{
KE: %{default: :metric, paper_size: :a4, temperature: :metric},
GU: %{default: :metric, paper_size: :a4, temperature: :metric},
...
}
Specs
measurement_systems_for_unit(t() | unit()) :: [measurement_system(), ...] | {:error, {module(), String.t()}}
Returns the measurement systems for a given unit.
Arguments
unit
is anyt:Cldr.Unit
or any unit returned byCldr.Unit.known_units/0
or a string unit name.
Returns
A list of measurement systems to which the
unit
belongs.{:error, {exception, message}}
Examples
iex> Cldr.Unit.measurement_systems_for_unit :foot
[:ussystem, :uksystem]
iex> Cldr.Unit.measurement_systems_for_unit :meter
[:metric]
iex> Cldr.Unit.measurement_systems_for_unit :invalid
{:error, {Cldr.UnknownUnitError, "The unit :invalid is not known."}}
Specs
new(unit() | value(), value() | unit(), Keyword.t()) :: {:ok, t()} | {:error, {module(), String.t()}}
Returns a new Unit.t
struct.
Arguments
unit
is any unit returned byCldr.Unit.known_units/0
options
is Keyword list of options. The default is[]
Options
:usage
is the intended use of the unit. This is used during localization to convert the unit to that appropriate for the unit category, usage, target territory and unit value. The:use
must be known for the unit's category. SeeCldr.Unit
for more information.
Returns
unit
or{:error, {exception, message}}
Examples
iex> Cldr.Unit.new(23, :gallon)
{:ok, Cldr.Unit.new!(:gallon, 23)}
iex> Cldr.Unit.new(:gallon, 23)
{:ok, Cldr.Unit.new!(:gallon, 23)}
iex> Cldr.Unit.new(14, :gadzoots)
{:error, {Cldr.UnknownUnitError,
"Unknown unit was detected at \"gadzoots\""}}
iex> Cldr.Unit.new(:gallon, 23, usage: :fluid)
iex> Cldr.Unit.new(:gallon, 23, usage: "fluid")
Returns a new Unit.t
struct or raises on error.
Arguments
value
is any float, integer orDecimal
unit
is any unit returned byCldr.Unit.known_units/0
Returns
unit
orraises an exception
Examples
iex> Cldr.Unit.new! 23, :gallon
#Cldr.Unit<:gallon, 23>
Cldr.Unit.new! 14, :gadzoots
** (Cldr.UnknownUnitError) The unit :gadzoots is not known.
(ex_cldr_units) lib/cldr/unit.ex:57: Cldr.Unit.new!/2
Convert a ratio Unit to a float unit
Specs
styles() :: [style(), ...]
Returns the known styles for a unit.
Example
iex> Cldr.Unit.styles
[:long, :short, :narrow]
See Cldr.Unit.Math.sub/2
.
Specs
to_iolist(list_or_number :: value() | t() | [t()]) :: {:ok, String.t()} | {:error, {atom(), binary()}}
Formats a number into a iolist 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_iolist/3
for full details.
Specs
to_iolist(value() | t(), Cldr.backend() | Keyword.t(), Keyword.t()) :: {:ok, list()} | {:error, {module(), binary()}}
Formats a number into an iolist
according to a unit definition
for a locale.
During processing any :format_options
of a t:Unit()
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 aCldr.Unit.t()
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
: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.to_iolist Cldr.Unit.new!(:gallon, 123), MyApp.Cldr
{:ok, ["123", " gallons"]}
iex> Cldr.Unit.to_iolist 123, MyApp.Cldr, unit: :megabyte, locale: "en", style: :unknown
{:error, {Cldr.UnknownFormatError, "The unit style :unknown is not known."}}
Specs
Formats a number into an iolist according to a unit definition for the current process's locale and backend or raises on error.
The curent process's locale is set with
Cldr.put_locale/1
.
See Cldr.Unit.to_iolist!/3
for full details.
Specs
Formats a number into an iolist according to a unit definition for the current process's locale and backend or raises on error.
During processing any :format_options
of a t:Cldr.Unit
are merged with
options
with options
taking precedence.
Arguments
number
is any number (integer, float or Decimal) or at:Cldr.Unit
structbackend
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()
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
io_list
orraises an exception
Examples
iex> Cldr.Unit.to_iolist! Cldr.Unit.new!(:gallon, 123), MyApp.Cldr
["123", " gallons"]
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 aCldr.Unit.t()
struct or a list ofCldr.Unit.t()
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 aCldr.Unit.t()
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
: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."}}
Specs
Formats a number into a string according to a unit definition for the current process's locale and backend or raises on error.
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()) :: String.t() | no_return()
Formats a number into a string according to a unit definition for the current process's locale and backend or raises on error.
During processing any :format_options
of a t:Cldr.Unit
are merged with
options
with options
taking precedence.
Arguments
number
is any number (integer, float or Decimal) or at:Cldr.Unit
structbackend
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 at:Cldr.Unit
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.to_string! Cldr.Unit.new!(:gallon, 123), MyApp.Cldr
"123 gallons"
iex> Cldr.Unit.to_string! Cldr.Unit.new!(:gallon, 1), MyApp.Cldr
"1 gallon"
iex> Cldr.Unit.to_string! Cldr.Unit.new!(:gallon, 1), MyApp.Cldr, locale: "af"
"1 gelling"
Specs
Returns the units category for a given unit
Options
unit
is any unit returned byCldr.Unit.new/2
Returns
{:ok, category}
or{:error, {exception, message}}
Examples
iex> Cldr.Unit.unit_category :pint_metric
{:ok, :volume}
iex> Cldr.Unit.unit_category :stone
{:ok, :mass}
Returns a mapping between Unit categories and the uses they define.
Example
iex> Cldr.Unit.unit_category_usage
%{
area: [:default, :geograph, :land],
concentration: [:blood_glucose, :default],
consumption: [:default, :vehicle_fuel],
consumption_inverse: [:default, :vehicle_fuel],
duration: [:default, :media],
energy: [:default, :food],
length: [:default, :focal_length, :person, :person_height, :rainfall, :road,
:snowfall, :vehicle, :visiblty],
mass: [:default, :person],
mass_density: [:blood_glucose, :default],
power: [:default, :engine],
pressure: [:baromtrc, :default],
speed: [:default, :wind],
temperature: [:default, :weather],
volume: [:default, :fluid, :oil, :vehicle],
year_duration: [:default, :person_age]
}
Validates a unit style and normalizes it to a standard downcased atom form
Validates a unit name and normalizes it,
A unit name can be expressed as:
an
atom()
in which case the unit must be localizable in CLDR directlyor a
t:String
in which case it is parsed into a list of composable subunits that can be converted but are not guaranteed to be output as a localized string.
Arguments
unit_name
is anatom()
ort:String
, supplied as is or as part of ant:Cldr.Unit
struct.
Returns
{:ok, canonical_unit_name, conversion}
wherecanonical_unit_name
is the normalized unit name andconversion
is an opaque structure used to convert this this unit into its base unit or{:error, {exception, reason}}
Notes
A returned unit_name
that is an atom is directly
localisable (CLDR has translation data for the unit).
A unit_name
that is a t:String
is composed of
one or more unit names that need to be resolved in
order for the unit_name
to be localised.
The difference is an implementation detail and should not be of concern to the user of this library.
Examples
iex> Cldr.Unit.validate_unit :meter
{
:ok,
:meter,
[meter: %Cldr.Unit.Conversion{base_unit: [:meter], factor: 1, offset: 0}]
}
iex> Cldr.Unit.validate_unit "meter"
{:ok, :meter,
[meter: %Cldr.Unit.Conversion{base_unit: [:meter], factor: 1, offset: 0}]}
iex> Cldr.Unit.validate_unit "miles_per_liter"
{:error, {Cldr.UnknownUnitError, "Unknown unit was detected at \"s\""}}
iex> Cldr.Unit.validate_unit "mile_per_liter"
{:ok, "mile_per_liter",
{[
mile:
%Cldr.Unit.Conversion{
base_unit: [:meter],
factor: Ratio.new(905980129838867985, 562949953421312),
offset: 0
}
],
[
liter:
%Cldr.Unit.Conversion{
base_unit: [:cubic_meter],
factor: Ratio.new(1152921504606847, 1152921504606846976),
offset: 0
}
]}}
Specs
Return the value of the Unit struct
Arguments
unit
is any unit returned byCldr.Unit.new/2
Returns
- an integer, float or Decimal representing the amount of the unit
Example
iex> Cldr.Unit.value Cldr.Unit.new!(:kilogram, 23)
23
Returns a new unit of the same unit type but with a zero value.
Argument
unit
is any unit returned byCldr.Unit.new/2
Example
iex> u = Cldr.Unit.new!(:foot, 23.3)
#Cldr.Unit<:foot, 23.3>
iex> Cldr.Unit.zero(u)
#Cldr.Unit<:foot, 0.0>
Returns a boolean indicating whether a given unit has a zero value.
Argument
unit
is any unit returned byCldr.Unit.new/2
Examples
iex> u = Cldr.Unit.new!(:foot, 23.3)
#Cldr.Unit<:foot, 23.3>
iex> Cldr.Unit.zero?(u)
false
iex> u = Cldr.Unit.new!(:foot, 0)
#Cldr.Unit<:foot, 0>
iex> Cldr.Unit.zero?(u)
true