Cldr.Unit (Cldr Units v3.7.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 the grammatical gender for a unit.
Inverts a unit
Returns a list of the known grammatical cases.
Returns a list of the known grammatical genders.
Return a list of known measurement system names.
Return a list of known measurement systems.
Returns the known styles for a unit.
Returns a list of the known unit categories.
Returns the known units that are directly translatable.
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.
Parse a string to create a new unit.
Parse a string to create a new unit or raises an exception.
Convert a ratio, float or integer t:Unit
to a Decimal t:Unit
Convert a ratio, Decimal or integer t:Unit
to a float t:Unit
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 grammatical case and normalizes it to a standard downcased atom form
Validates a grammatical gender and normalizes it to a standard downcased atom form
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
base_conversion() :: {translatable_unit(), Cldr.Unit.Conversion.t()}
Specs
category() :: atom()
Specs
conversion() :: [base_conversion()] | {[base_conversion()], [base_conversion()]}
Specs
grammatical_case() :: :vocative | :sociative | :prepositional | :partitive | :oblique | :nominative | :localtivecopulative | :locative | :instrumental | :genitive | :ergative | :dative | :comitative | :accusative | :ablative
Specs
grammatical_gender() :: :neuter | :masculine | :feminine | :common | :personal | :inanimate | :animate
Specs
locale() :: Cldr.Locale.locale_name() | Cldr.LanguageTag.t()
Specs
measurement_system() :: :ussystem | :uksystem | :si | :metric
Specs
measurement_system_key() :: :paper_size | :temperature | :default
Specs
style() :: :narrow | :short | :long
Specs
t() :: %Cldr.Unit{ base_conversion: conversion(), format_options: [], unit: unit(), usage: usage(), value: value() }
Specs
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
, anatom
or at:String
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
grammatical_gender(t(), Keyword.t()) :: grammatical_gender()
Return the grammatical gender for a unit.
Arguments
Options
Returns
Examples
Specs
Inverts a unit
Only "per" units can be inverted.
Returns a list of the known grammatical cases.
A grammatical case can be provided as an option to
Cldr.Unit.to_string/2
in order to localise a unit
appropriate to the context in which it is used.
Example
iex> Cldr.Unit.known_grammatical_cases
[
:ablative,
:accusative,
:comitative,
:dative,
:ergative,
:genitive,
:instrumental,
:locative,
:localtivecopulative,
:nominative,
:oblique,
:partitive,
:prepositional,
:sociative,
:vocative
]
Returns a list of the known grammatical genders.
A gender can be provided as an option to
Cldr.Unit.to_string/2
in order to localise a unit
appropriate to the context in which it is used.
Example
iex> Cldr.Unit.known_grammatical_genders
[
:animate,
:inanimate,
:personal,
:common,
:feminine,
:masculine,
:neuter
]
Specs
known_measurement_system_names() :: [measurement_system(), ...]
Return a list of known measurement system names.
Example
iex> Cldr.Unit.known_measurement_system_names()
[:metric, :si, :uksystem, :ussystem]
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"},
si: %{alias: nil, description: "SI System"}
}
Specs
known_styles() :: [style(), ...]
Returns the known styles for a unit.
Example
iex> Cldr.Unit.known_styles
[:long, :short, :narrow]
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 that are directly translatable.
These units have localised content in CLDR and are used as a key to retrieving that content.
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.Locale.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, :si]
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 name 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 usage must be defined for the unit's category. SeeCldr.Unit.unit_category_usage/0
for the known usage types for each category.
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\""}}
Cldr.Unit.new(:gallon, 23, usage: :fluid)
#=> {:ok, #Cldr.Unit<:gallon, 23, usage: :fluid, format_options: []>}
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
Parse a string to create a new unit.
This function attempts to parse a string
into a number
and unit type
. If successful
it attempts to create a new unit using
Cldr.Unit.new/3
.
The parsed unit type
is aliased against all the
known unit names for a give locale (or the current
locale if no locale is specified). The known
aliases for unit types can be returned with
MyApp.Cldr.Unit.unit_strings_for/1
where MyApp.Cldr
is the name of a backend module.
Arguments
unit string
is any string to be parsed and if possible used to create a newt:Cldr.Unit
options
is a keyword list of options
Options
:locale
is any valid locale name returned byCldr.known_locale_names/0
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
{:ok, unit}
or{:error, {exception, reason}}
Examples
iex> Cldr.Unit.parse "1kg"
Cldr.Unit.new(1, :kilogram)
iex> Cldr.Unit.parse "1 tages", locale: "de"
Cldr.Unit.new(1, :day)
iex> Cldr.Unit.parse "1 tag", locale: "de"
Cldr.Unit.new(1, :day)
iex> Cldr.Unit.parse("42 millispangels")
{:error, {Cldr.UnknownUnitError, "Unknown unit was detected at \"spangels\""}}
Parse a string to create a new unit or raises an exception.
This function attempts to parse a string
into a number
and unit type
. If successful
it attempts to create a new unit using
Cldr.Unit.new/3
.
The parsed unit type
is un-aliased against all the
known unit names for a give locale (or the current
locale if no locale is specified). The known
aliases for unit types can be returned with
MyApp.Cldr.Unit.unit_strings_for/1
where MyApp.Cldr
is the name of a backend module.
Arguments
unit string
is any string to be parsed and if possible used to create a newt:Cldr.Unit
options
is a keyword list of options
Options
:locale
is any valid locale name returned byCldr.known_locale_names/0
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
unit
orraises an exception
Examples
iex> Cldr.Unit.parse! "1kg"
Cldr.Unit.new!(1, :kilogram)
iex> Cldr.Unit.parse! "1 tages", locale: "de"
Cldr.Unit.new!(1, :day)
iex> Cldr.Unit.parse!("42 candela per lux")
Cldr.Unit.new!(42, "candela per lux")
iex> Cldr.Unit.parse!("42 millispangels")
** (Cldr.UnknownUnitError) Unknown unit was detected at "spangels"
See Cldr.Unit.Math.sub/2
.
Convert a ratio, float or integer t:Unit
to a Decimal t:Unit
Convert a ratio, Decimal or integer t:Unit
to a float t:Unit
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.: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.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.known_styles/0
. 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}
iex> Cldr.Unit.unit_category "kilowatt hour"
{:error,
{Cldr.Unit.UnknownCategoryError,
"The category for \"kilowatt hour\" is not known."}}
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],
duration: [:default, :media],
energy: [:default, :food],
length: [:default, :focal_length, :person, :person_height, :rainfall, :road,
:snowfall, :vehicle, :visiblty],
mass: [:default, :person],
mass_density: [: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 grammatical case and normalizes it to a standard downcased atom form
validate_grammatical_gender(grammatical_gender, locale \\ Cldr.default_locale())
View Source (since 3.5.0)Validates a grammatical gender and normalizes it to a standard downcased atom form
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