View Source Cldr.Unit (Cldr Units v3.17.0)

Supports the CLDR Units definitions which provide for the localization of many unit types.

The primary public API defines:

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.

Returns a new Unit.t struct from a map.

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 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.

Parse a string to find a matching unit-atom.

Parse a string to find a matching unit-atom.

Convert a float or integer t:Unit to a Decimal t:Unit.

Convert a 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.

unit_type(unit) deprecated

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.

Types

@type base_conversion() :: {translatable_unit(), Cldr.Unit.Conversion.t()}
@type category() :: atom()
@type conversion() :: [base_conversion()] | {[base_conversion()], [base_conversion()]}
@type grammatical_case() ::
  :vocative
  | :translative
  | :terminative
  | :superessive
  | :sublative
  | :sociative
  | :prepositional
  | :partitive
  | :oblique
  | :nominative
  | :localtivecopulative
  | :locative
  | :instrumental
  | :inessive
  | :illative
  | :genitive
  | :ergative
  | :elative
  | :delative
  | :dative
  | :comitative
  | :causal
  | :allative
  | :adessive
  | :accusative
  | :ablative
  | :abessive
@type grammatical_gender() ::
  :neuter | :masculine | :feminine | :common | :personal | :inanimate | :animate
@type measurement_system() ::
  :ussystem
  | :uksystem
  | :si_acceptable
  | :si
  | :prefixable
  | :person_age
  | :metric_adjacent
  | :metric
  | :jpsystem
  | :astronomical
@type style() :: :narrow | :short | :long
@type t() :: %Cldr.Unit{
  backend: term(),
  base_conversion: conversion(),
  format_options: Keyword.t(),
  unit: unit(),
  usage: usage(),
  value: value()
}
@type translatable_unit() :: atom() | [atom()]
@type unit() :: translatable_unit() | String.t()
@type usage() :: atom()
@type value() :: Cldr.Math.number_or_decimal()

Functions

See Cldr.Unit.Math.add/2.

See Cldr.Unit.Math.add!/2.

Returns the base unit for a given unit.

Argument

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\""}}
Link to this function

base_unit_category_map()

View Source
@spec 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:

  1. When converting between units. If two units have the same base unit they can be converted to each other. See Cldr.Unit.Conversion.

  2. 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.

See Cldr.Unit.Math.compare/2.

Link to this function

compatible?(unit_1, unit_2)

View Source
@spec compatible?(t() | unit(), t() | unit()) :: boolean()

Returns a boolean indicating if two units are of the same unit category.

Arguments

  • unit_1 and unit_2 are any units returned by Cldr.Unit.new/2 or a valid unit name.

Returns

  • true or false

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
Link to this function

convert(unit_1, to_unit)

View Source

See Cldr.Unit.Conversion.convert/2.

Link to this function

convert!(unit_1, to_unit)

View Source

See Cldr.Unit.Conversion.convert!/2.

Link to this function

decompose(unit, unit_list, format_options \\ [])

View Source
@spec decompose(unit :: t(), unit_list :: [unit()], options :: Keyword.t()) :: [t()]

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 by Cldr.Unit.new/2

  • unit_list is a list of valid units (one or more from the list returned by Cldr.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 in unit_list. The format_options will be applied when calling Cldr.Unit.to_string/3 on the unit. 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, "3.6")]

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)]
@spec default_style() :: style()

Returns the default formatting style.

Example

iex> Cldr.Unit.default_style()
:long
Link to this function

display_name(unit, options \\ [])

View Source
@spec display_name(translatable_unit() | t(), Keyword.t()) ::
  String.t() | {:error, {module(), binary()}}

Returns the localized display name for a unit.

The returned text is generally suitable for including in UI elements such as selection boxes.

Arguments

Options

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.

See Cldr.Unit.Math.div!/2.

Returns a new Unit.t struct from a map.

A map representation of a unit may be generated from json or other external format data.

The map provided must have the keys unit and value in either String.t or atom (both keys must be of the same type).

value must be either an integer, a float or a map representation of a rational number. A rational number map has the keys numerator and denominator in either String.t or atom format (both keys must be of the same type).

Arguments

  • map is a map with the keys unit and value

Returns

  • {:ok, unit} or

  • {:error, {exception, reason}}

Examples

Cldr.Unit.from_map %{value: 1, unit: "kilogram"}
=> {:ok, #Cldr.Unit<:kilogram, 1>}

Cldr.Unit.from_map %{value: %{numerator: 3, denominator: 4}, unit: "kilogram"}
=> {:ok, #Cldr.Unit<:kilogram, 3 <|> 4>}

Cldr.Unit.from_map %{"value" => 1, "unit" => "kilogram"}
=> {:ok, #Cldr.Unit<:kilogram, 1>}
Link to this function

grammatical_gender(unit, options \\ [])

View Source (since 3.5.0)
@spec grammatical_gender(t(), Keyword.t()) :: grammatical_gender()

Return the grammatical gender for a unit.

Arguments

Options

Returns

Examples

Link to this function

grammatical_gender_error(grammatical_gender, locale)

View Source
@spec invert(t()) :: {:ok, t()} | {:error, {module(), String.t()}}

Inverts a unit

Only "per" units can be inverted.

Link to this function

known_grammatical_cases()

View Source (since 3.5.0)

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()
[
  :abessive,
  :ablative,
  :accusative,
  :adessive,
  :allative,
  :causal,
  :comitative,
  :dative,
  :delative,
  :elative,
  :ergative,
  :genitive,
  :illative,
  :inessive,
  :instrumental,
  :locative,
  :localtivecopulative,
  :nominative,
  :oblique,
  :partitive,
  :prepositional,
  :sociative,
  :sublative,
  :superessive,
  :terminative,
  :translative,
  :vocative
]
Link to this function

known_grammatical_genders()

View Source (since 3.5.0)

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
]
Link to this function

known_measurement_systems()

View Source
@spec known_measurement_systems() :: [measurement_system()]

Return a list of known measurement systems.

Example

iex> Cldr.Unit.known_measurement_systems()
[:astronomical, :jpsystem, :metric, :metric_adjacent, :person_age, :prefixable, :si, :si_acceptable, :uksystem, :ussystem]
@spec known_styles() :: [style(), ...]

Returns the known styles for a unit.

Example

iex> Cldr.Unit.known_styles()
[:long, :short, :narrow]
@spec 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]
@spec 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, ...]
Link to this function

known_units_by_category()

View Source (since 3.4.0)
@spec 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], ...
 }
Link to this function

known_units_for_category(category)

View Source (since 3.4.0)
@spec known_units_for_category(category()) ::
  {:ok, [translatable_unit(), ...]} | {:error, {module(), String.t()}}

Returns the list of units defined for a given category.

Arguments

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,
    ...
  ]
}
@spec localize(t()) :: [t(), ...]

Localizes a unit according to the current processes locale and backend.

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

See Cldr.Unit.localize/3 for further details.

Link to this function

localize(unit, backend, options \\ [])

View Source
@spec localize(t(), Cldr.backend(), Keyword.t()) :: [t(), ...]

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.Unit<328, :foot>.

Arguments

  • unit is any unit returned by Cldr.Unit.new/2

  • backend is any module that includes use Cldr and therefore is a Cldr backend module.

  • options is a keyword list of options

Options

  • :locale is any valid locale name returned by Cldr.known_locale_names/0 or a Cldr.LanguageTag struct. The default is backend.get_locale/0.

  • :territory is any valid territory code returned by Cldr.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 available usage varyies according to the unit category. See Cldr.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, usage: :person_height),
  Cldr.Unit.new!(:inch, "0.04724409448818897637795275598", usage: :person_height)
]
Link to this function

maybe_new(a, b, options)

View Source
Link to this function

measurement_system?(unit, system)

View Source (since 3.4.0)
@spec 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

Returns

  • true or false 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."}}
Link to this function

measurement_system_for_territory(territory, category \\ :default)

View Source
@spec 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 by Cldr.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"}}
Link to this function

measurement_system_from_locale(locale \\ Cldr.get_locale(), key \\ :default)

View Source (since 3.4.0)
@spec measurement_system_from_locale(
  Cldr.LanguageTag.t() | Cldr.Locale.locale_name(),
  measurement_system() | Cldr.backend()
) :: 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 by Cldr.known_locale_names/0 or a t:Cldr.LanguageTag struct. The default is Cldr.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"}}
Link to this function

measurement_system_from_locale(locale, backend, key)

View Source (since 3.4.0)
@spec measurement_system_from_locale(
  Cldr.Locale.locale_reference(),
  Cldr.backend(),
  measurement_system()
) :: measurement_system() | {:error, {module(), String.t()}}
Link to this function

measurement_system_units(system)

View Source (since 3.4.0)
@spec measurement_system_units(measurement_system()) ::
  [translatable_unit(), ...] | {:error, {module(), String.t()}}

Returns the list of units defined in a given measurement system.

Arguments

Returns

  • A list of translatable units as atoms or

  • {:error, {exception, message}}

Example

=> Cldr.Unit.measurement_system_units :uksystem
[
  :ton,
  :inch,
  :yard,
  ...
]
This function is deprecated. Use Cldr.Unit.measurement_systems_by_territory/0.

See Cldr.Unit.measurement_systems_by_territory/0.

Link to this function

measurement_systems_by_territory()

View Source
@spec measurement_systems_by_territory() :: %{
  required(Cldr.Locale.territory_code()) => 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},
  ...
}
Link to this function

measurement_systems_for_unit(unit)

View Source (since 3.4.0)
@spec measurement_systems_for_unit(t() | unit()) ::
  [measurement_system(), ...] | {:error, {module(), String.t()}}

Returns the measurement systems for a given unit.

Arguments

Returns

  • A list of measurement systems to which the unit belongs.

  • {:error, {exception, message}}

Examples

iex> Cldr.Unit.measurement_systems_for_unit :foot
[:uksystem, :ussystem]

iex> Cldr.Unit.measurement_systems_for_unit :meter
[:metric, :prefixable, :si]

iex> Cldr.Unit.measurement_systems_for_unit :invalid
{:error, {Cldr.UnknownUnitError, "The unit :invalid is not known."}}

See Cldr.Unit.Math.mult/2.

See Cldr.Unit.Math.mult!/2.

Link to this function

new(value, unit, options \\ [])

View Source
@spec new(unit() | value(), value() | unit(), Keyword.t()) ::
  {:ok, t()} | {:error, {module(), String.t()}}

Returns a new Unit.t struct.

Arguments

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. See Cldr.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: []>}
Link to this function

new!(unit, value, options \\ [])

View Source

Returns a new Unit.t struct or raises on error.

Arguments

Returns

  • unit or

  • raises an exception

Examples

iex> Cldr.Unit.new! 23, :gallon
Cldr.Unit.new!(: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
Link to this function

parse(unit_string, options \\ [])

View Source (since 3.6.0)

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 new Cldr.Unit.t/0

  • options is a keyword list of options

Options

  • :locale is any valid locale name returned by Cldr.known_locale_names/0 or a t:Cldr.LanguageTag struct. The default is Cldr.get_locale/0

  • :backend is any module that includes use Cldr and therefore is a Cldr backend module. The default is Cldr.default_backend!/0.

  • :only is a unit category or unit, or a list of unit categories and units. The parsed unit must match one of the categories or units in order to be valid. This is helpful when disambiguating parsed units. For example, parsing "2w" could be either "2 watts" or "2 weeks". Specifying only: :duration would return "2 weeks". Specifying only: :power would return "2 watts"

  • :except is the oppostte of :only. The parsed unit must not match the specified unit or category, or unit categories and units.

Returns

  • {:ok, unit} or

  • {:error, {exception, reason}}

Notes

  • When both :only and :except options are passed, both conditions must be true in order to return a parsed result.

  • Only units returned by Cldr.Unit.known_units/0 can be used in the :only and :except filters.

Examples

iex> Cldr.Unit.parse "1kg"
Cldr.Unit.new(1, :kilogram)

iex> Cldr.Unit.parse "1w"
Cldr.Unit.new(1, :watt)

iex> Cldr.Unit.parse "1w", only: :duration
Cldr.Unit.new(1, :week)

iex> Cldr.Unit.parse "1m", only: [:year, :month, :day]
Cldr.Unit.new(1, :month)

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\""}}
Link to this function

parse!(unit_string, options \\ [])

View Source (since 3.6.0)

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 new Cldr.Unit.t/0

  • options is a keyword list of options

Options

  • :locale is any valid locale name returned by Cldr.known_locale_names/0 or a t:Cldr.LanguageTag struct. The default is Cldr.get_locale/0

  • :backend is any module that includes use Cldr and therefore is a Cldr backend module. The default is Cldr.default_backend!/0.

  • :only is a unit category or unit, or a list of unit categories and units. The parsed unit must match one of the categories or units in order to be valid. This is helpful when disambiguating parsed units. For example, parsing "2w" could be either "2 watts" or "2 weeks". Specifying only: :duration would return "2 weeks". Specifying only: :power would return "2 watts"

  • :except is the oppostte of :only. The parsed unit must not match the specified unit or category, or unit categories and units.

Notes

  • When both :only and :except options are passed, both conditions must be true in order to return a parsed result.

  • Only units returned by Cldr.Unit.known_units/0 can be used in the :only and :except filters.

Returns

  • unit or

  • raises 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"
Link to this function

parse_unit_name(unit_name_string, options \\ [])

View Source (since 3.14.0)
@spec parse_unit_name(binary(), Keyword.t()) ::
  {:ok, atom()} | {:error, {module(), binary()}}

Parse a string to find a matching unit-atom.

This function attempts to parse a string and extract the unit type.

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_name_string is any string to be parsed and converted into a unit type

  • options is a keyword list of options

Options

  • :locale is any valid locale name returned by Cldr.known_locale_names/0 or a t:Cldr.LanguageTag struct. The default is Cldr.get_locale/0

  • :backend is any module that includes use Cldr and therefore is a Cldr backend module. The default is Cldr.default_backend!/0.

  • :only is a unit category or unit, or a list of unit categories and units. The parsed unit must match one of the categories or units in order to be valid. This is helpful when disambiguating parsed units. For example, parsing "w" could be either :watt or :weeks. Specifying only: :duration would return :weeks. Specifying only: :power would return :watt

  • :except is the oppostte of :only. The parsed unit must not match the specified unit or category, or unit categories and units.

Returns

  • {:ok, unit_name} or

  • {:error, {exception, reason}}

Notes

  • When both :only and :except options are passed, both conditions must be true in order to return a parsed result.

  • Only units returned by Cldr.Unit.known_units/0 can be used in the :only and :except filters.

Examples

iex> Cldr.Unit.parse_unit_name "kg"
{:ok, :kilogram}

iex> Cldr.Unit.parse_unit_name "w"
{:ok, :watt}

iex> Cldr.Unit.parse_unit_name "w", only: :duration
{:ok, :week}

iex> Cldr.Unit.parse_unit_name "m", only: [:year, :month, :day]
{:ok, :month}

iex> Cldr.Unit.parse_unit_name "tages", locale: "de"
{:ok, :day}

iex> Cldr.Unit.parse_unit_name "tag", locale: "de"
{:ok, :day}

iex> Cldr.Unit.parse_unit_name("millispangels")
{:error, {Cldr.UnknownUnitError, "Unknown unit was detected at \"spangels\""}}
Link to this function

parse_unit_name!(unit_name_string, options \\ [])

View Source (since 3.14.0)

Parse a string to find a matching unit-atom.

This function attempts to parse a string and extract the unit type.

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_name_string is any string to be parsed and converted into a unit type

  • options is a keyword list of options

Options

  • :locale is any valid locale name returned by Cldr.known_locale_names/0 or a t:Cldr.LanguageTag struct. The default is Cldr.get_locale/0

  • :backend is any module that includes use Cldr and therefore is a Cldr backend module. The default is Cldr.default_backend!/0.

  • :only is a unit category or unit, or a list of unit categories and units. The parsed unit must match one of the categories or units in order to be valid. This is helpful when disambiguating parsed units. For example, parsing "w" could be either watts or :week. Specifying only: :duration would return :week. Specifying only: :power would return :watts

  • :except is the oppostte of :only. The parsed unit must not match the specified unit or category, or unit categories and units.

Returns

  • unit_name or

  • raises an exception

Notes

  • When both :only and :except options are passed, both conditions must be true in order to return a parsed result.

  • Only units returned by Cldr.Unit.known_units/0 can be used in the :only and :except filters.

Examples

iex> Cldr.Unit.parse_unit_name! "kg"
:kilogram

iex> Cldr.Unit.parse_unit_name! "w"
:watt

iex> Cldr.Unit.parse_unit_name! "w", only: :duration
:week

iex> Cldr.Unit.parse_unit_name! "m", only: [:year, :month, :day]
:month

iex> Cldr.Unit.parse_unit_name! "tages", locale: "de"
:day

iex> Cldr.Unit.parse_unit_name! "tag", locale: "de"
:day

iex> Cldr.Unit.parse_unit_name!("millispangels")
** (Cldr.UnknownUnitError) Unknown unit was detected at "spangels"
Link to this function

preferred_units(unit, backend, options)

View Source

See Cldr.Unit.Preference.preferred_units/3.

Link to this function

preferred_units!(unit, backend, options)

View Source

See Cldr.Unit.Preference.preferred_units!/3.

This function is deprecated. Use Cldr.Unit.to_decimal_unit/1.

See Cldr.Unit.to_decimal_unit/1.

This function is deprecated. Use Cldr.Unit.to_float_unit/1.

See Cldr.Unit.to_float_unit/1.

See Cldr.Unit.Math.round/1.

See Cldr.Unit.Math.round/2.

Link to this function

round(unit, places, mode)

View Source

See Cldr.Unit.Math.round/3.

This function is deprecated. Use Cldr.Unit.known_styles/0.

See Cldr.Unit.known_styles/0.

See Cldr.Unit.Math.sub/2.

See Cldr.Unit.Math.sub!/2.

Link to this function

to_decimal_unit(unit)

View Source (since 3.5.0)

Convert a float or integer t:Unit to a Decimal t:Unit.

Link to this function

to_float_unit(unit)

View Source (since 3.5.0)

Convert a Decimal or integer t:Unit to a float t:Unit.

@spec 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 current 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
@spec 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 Cldr.Unit.t/0 struct or a list of Cldr.Unit.t/0 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 Cldr.Unit.t/0 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."}}
@spec to_string!(list_or_number :: value() | t() | [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.

The current 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!(unit, backend, options \\ [])

View Source
@spec 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 Cldr.Unit.t/0 are merged with options with options taking precedence.

Arguments

  • number is any number (integer, float or Decimal) or a Cldr.Unit.t/0 struct

  • 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

Options

Returns

  • formatted_string or

  • raises 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"
This function is deprecated. Use Cldr.Unit.known_units/0.

See Cldr.Unit.known_units/0.

This function is deprecated. Use `Cldr.Unit.known_unit_categories/0.

See Cldr.Unit.known_unit_categories/0.

@spec unit_category(t() | String.t() | atom()) ::
  {:ok, category()} | {:error, {module(), String.t()}}

Returns the units category for a given unit

Options

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 :watt
{:ok, :power}

iex> Cldr.Unit.unit_category "kilowatt hour"
{:ok, :energy}

iex> Cldr.Unit.unit_category "watt hour per light year"
{:ok, :force}

iex> Cldr.Unit.unit_category "watt per kilogram"
{:error,
 {Cldr.Unit.UnknownCategoryError,
  "The category for \"watt_per_kilogram\" is not known."}}

Returns a mapping between Unit categories and the uses they define.

Example

iex> Cldr.Unit.unit_category_usage()
%{
  area: [:default, :floor, :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, :rainfall, :snowfall, :wind],
  temperature: [:default, :weather],
  volume: [:default, :fluid, :oil, :vehicle],
  year_duration: [:default, :person_age]
}
This function is deprecated. Please use `Cldr.Unit.unit_category/1.
Link to this function

validate_grammatical_case(grammatical_case)

View Source (since 3.5.0)

Validates a grammatical case and normalizes it to a standard downcased atom form

Link to this function

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

Link to this function

validate_unit(unit_name)

View Source

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 directly

  • or a String.t/0 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

Returns

  • {:ok, canonical_unit_name, conversion} where canonical_unit_name is the normalized unit name and conversion 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 String.t/0 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{
      factor: Decimal.new("1609.3440"),
      offset: 0,
      base_unit: [:meter]
    }
  ],
  [
    liter: %Cldr.Unit.Conversion{
      factor: Decimal.new("0.001"),
      offset: 0,
      base_unit: [:cubic_meter]
    }
  ]}}
@spec value(unit :: t()) :: value()

Return the value of the Unit struct

Arguments

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

Example

iex> u = Cldr.Unit.new!(:foot, 23.3)
Cldr.Unit.new!(:foot, "23.3")
iex> Cldr.Unit.zero(u)
Cldr.Unit.new!(:foot, 0)

Returns a boolean indicating whether a given unit has a zero value.

Argument

Examples

iex> u = Cldr.Unit.new!(:foot, 23.3)
Cldr.Unit.new!(:foot, 23.3)
iex> Cldr.Unit.zero?(u)
false

iex> u = Cldr.Unit.new!(:foot, 0)
Cldr.Unit.new!(:foot, 0)
iex> Cldr.Unit.zero?(u)
true