Cldr Units v2.7.0 Cldr.Unit 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 number and a unit name or unit list will output a localized string

  • Cldr.Unit.units/0 identifies the available units for localization

  • Cldr.Unit.{add, sub, mult, div}/2 to support basic unit mathematics between units of compatible type (like length or volume)

  • Cldr.Unit.convert/2 to convert one unit to another unit as long as they are convertable.

  • 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 unit closed in jaro distance to the provided unit

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

Returns a list of units that are compatible with the provided unit.

Decomposes a unit into subunits.

Returns the default formatting style.

Returns a list of units that are within the specified jaro distance of the provided unit.

Localizes a unit according to a territory

Returns the default measurement system for a territory.

Returns the default measurement system for a territory in a given category.

Returns the measurement system in use by territory

Returns a new Unit.t struct.

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

Returns the known styles for a unit.

Formats a number into a string according to a unit definition for a locale.

Formats a list using to_string/3 but raises if there is an error.

Returns a list of the known unit categories.

Returns the units category for a given unit

Returns a mapping of units to their respective unit categories

Returns a map of unit preferences

Returns a list of the unit categories and associated units

Returns the known units.

Returns the units for a given unit type

Validates a unit style and normalizes it to a standard downcased atom form

Validates a unit name and normalizes it to a standard downcased atom form

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

Link to this section Functions

See Cldr.Unit.Math.add/2.

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

Link to this function

best_match(unit, distance \\ 0.75)

View Source

Returns the unit closed in jaro distance to the provided unit

Arguments

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

  • distance is a float between 0.0 and 1.0 representing the jaro distance above which a unit must match in order to be returned. The default is 0.75

Returns

  • a Unit.t struct or

  • nil

Examples

iex> Cldr.Unit.best_match :ft
:fathom

iex> Cldr.Unit.best_match :zippity
nil
Link to this function

compatible?(unit_1, unit_2)

View Source
compatible?(unit(), unit()) :: boolean()

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

Options

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

compatible_units(unit, options \\ [jaro: false, distance: 0.75])

View Source
compatible_units(unit(), Keyword.t() | map()) ::
  [unit(), ...] | [{float(), unit()}, ...] | []

Returns a list of units that are compatible with the provided unit.

Arguments

Options

  • :jaro is a boolean which determines if the match is to use the jaro distance. The default is false

  • distance is a float between 0.0 and 1.0 representing the jaro distance above which a unit must match in order to be returned. The default is 0.75

Returns

  • a list of tuples of the form {jaro_distance, unit} sorted in decending jaro distance order, or

  • {:error, {exception, message}}

Examples

iex> Cldr.Unit.compatible_units :foot
[:astronomical_unit, :centimeter, :decimeter, :fathom, :foot, :furlong, :inch,
 :kilometer, :light_year, :meter, :micrometer, :mile, :mile_scandinavian,
 :millimeter, :nanometer, :nautical_mile, :parsec, :picometer, :point,
 :solar_radius, :yard]

iex> Cldr.Unit.compatible_units :me, jaro: true
[{0.7999999999999999, :meter}]
Link to this function

convert(unit_1, to_unit)

View Source

See Cldr.Unit.Conversion.convert/2.

Link to this function

decompose(unit, list)

View Source
decompose(unit :: Cldr.Unit.t(), decompose_list :: [Cldr.Unit.unit(), ...]) ::
  [Cldr.Unit.t(), ...] | {:error, {module(), String.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

  • decompose_list is a list of valid units (one or more from the list returned by Cldr.units/0). All units must be from the same category.

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, 4)]

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)]

Returns the default formatting style.

Example

iex> Cldr.Unit.default_style
:long

See Cldr.Unit.Math.div/2.

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

Link to this function

jaro_match(unit, distance \\ 0.75)

View Source
jaro_match(unit() | String.t(), number()) :: [{float(), unit()}, ...] | []

Returns a list of units that are within the specified jaro distance of the provided unit.

Arguments

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

  • distance is a float between 0.0 and 1.0 representing the jaro distance above which a unit must match in order to be returned. The default is 0.75

Returns

  • a list of tagged tuples of the form {jaro_distance, unit} sorted in decending jaro distance order or

  • {:error, {exception, message}}

Examples

iex> Cldr.Unit.jaro_match :foot
[{1.0, :foot}]

iex> Cldr.Unit.jaro_match :meter
[
  {1.0, :meter},
  {0.7708333333333334, :meter_per_second},
  {0.7592592592592592, :kilometer_per_hour}
]
Link to this function

localize(unit, usage, options)

View Source

Localizes a unit according to a territory

A territory can be derived from a locale_name or Cldr.LangaugeTag.t().

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 #Unit<100, :meter> might be better presented to a US audiance as #Unit<328, :foot>.

Arguments

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

  • 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.unit_preferences/0.

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

  • :scope may be set to :small to indicate that a unit conversion intended for "small" unit sizes is preferred. In some territories it is customary to use different units for "small" sizes from those that are "large".

  • :style may be set to :informal to indicate that a more informal unit conversion be applied.

Examples

iex> Cldr.Unit.localize(Cldr.Unit.new(100, :meter), :person, territory: :US)
[Cldr.Unit.new(:inch, 3937)]

iex> Cldr.Unit.localize(Cldr.Unit.new(100, :meter), :person, territory: :US, style: :informal)
[Cldr.Unit.new(:foot, 328), Cldr.Unit.new(:inch, 1)]
Link to this function

measurement_system_for(territory)

View Source
measurement_system_for(atom()) ::
  :metric | :US | :UK | {:error, {module(), String.t()}}

Returns the default measurement system for a territory.

Example

iex> Cldr.Unit.measurement_system_for :US
:US

iex> Cldr.Unit.measurement_system_for :GB
:UK

iex> Cldr.Unit.measurement_system_for :AU
:metric
Link to this function

measurement_system_for(territory, category)

View Source
measurement_system_for(atom(), atom()) ::
  :metric | :US | :UK | nil | {:error, {module(), String.t()}}

Returns the default measurement system for a territory in a given category.

Example

iex> Cldr.Unit.measurement_system_for :US, :temperature
:US

iex> Cldr.Unit.measurement_system_for :BS, :temperature
:US

iex> Cldr.Unit.measurement_system_for :BS
:metric

Returns the measurement system in use by territory

Example

iex> Cldr.Unit.measurement_systems
%{
  default: %{
    "001": :metric,
    GB: :UK,
    LR: :US,
    MM: :US,
    US: :US
  },
  paper_size: %{
    "001": :A4,
    BZ: :"US-Letter",
    CA: :"US-Letter",
    CL: :"US-Letter",
    CO: :"US-Letter",
    CR: :"US-Letter",
    GT: :"US-Letter",
    MX: :"US-Letter",
    NI: :"US-Letter",
    PA: :"US-Letter",
    PH: :"US-Letter",
    PR: :"US-Letter",
    SV: :"US-Letter",
    US: :"US-Letter",
    VE: :"US-Letter"
  },
  temperature: %{
    BS: :US,
    BZ: :US,
    KY: :US,
    LR: :metric,
    MM: :metric,
    PR: :US,
    PW: :US
  }
}

See Cldr.Unit.Math.mult/2.

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

Link to this function

new(value, unit)

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

Returns a new Unit.t struct.

Options

  • value is any float, integer or Decimal

  • unit is any unit returned by Cldr.Unit.units

Returns

  • unit or

  • {:error, {exception, message}}

Examples

iex> Cldr.Unit.new(23, :gallon)
#Unit<:gallon, 23>

iex> Cldr.Unit.new(:gallon, 23)
#Unit<:gallon, 23>

iex> Cldr.Unit.new(14, :gadzoots)
{:error, {Cldr.UnknownUnitError,
  "The unit :gadzoots is not known."}}
Link to this function

new!(unit, value)

View Source
new!(unit() | value(), value() | unit()) :: t() | no_return()

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

Options

Returns

  • unit or

  • raises an exception

Examples

iex> Cldr.Unit.new! 23, :gallon
#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

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.

Returns the known styles for a unit.

Example

iex> Cldr.Unit.styles
[:long, :short, :narrow]

See Cldr.Unit.Math.sub/2.

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

Link to this function

to_string(list_or_number, backend \\ Cldr.default_backend(), options \\ [])

View Source
to_string(
  list_or_number :: value() | t() | [t()],
  backend_or_options :: Cldr.backend() | Keyword.t(),
  options :: Keyword.t()
) :: {:ok, String.t()} | {:error, {atom(), binary()}}

Formats a number into a string according to a unit definition for a locale.

Arguments

  • list_or_number is any number (integer, float or Decimal) or a Cldr.Unit.t() struct or a list of Cldr.Unit.t() 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.units/1. Ignored if the number to be formatted is a Cldr.Unit.t() 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

  • :per allows compound units to be formatted. For example, assume we want to format a string which represents "kilograms per second". There is no such unit defined in CLDR (or perhaps anywhere!). If however we define the unit unit = Cldr.Unit.new(:kilogram, 20) we can then execute Cldr.Unit.to_string(unit, per: :second). Each locale defines a specific way to format such a compount unit. Usually it will return something like 20 kilograms/second

  • :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 123, MyApp.Cldr, unit: :gallon
{:ok, "123 gallons"}

iex> Cldr.Unit.to_string 1, MyApp.Cldr, unit: :gallon
{:ok, "1 gallon"}

iex> Cldr.Unit.to_string 1, MyApp.Cldr, unit: :gallon, locale: "af"
{:ok, "1 gelling"}

iex> Cldr.Unit.to_string 1, MyApp.Cldr, unit: :gallon, locale: "bs"
{:ok, "1 galon"}

iex> Cldr.Unit.to_string 1234, MyApp.Cldr, unit: :gallon, format: :long
{:ok, "1 thousand gallons"}

iex> Cldr.Unit.to_string 1234, MyApp.Cldr, unit: :gallon, format: :short
{:ok, "1K gallons"}

iex> Cldr.Unit.to_string 1234, MyApp.Cldr, unit: :megahertz
{:ok, "1,234 megahertz"}

iex> Cldr.Unit.to_string 1234, MyApp.Cldr, unit: :megahertz, style: :narrow
{:ok, "1,234MHz"}

iex> Cldr.Unit.to_string 1234, MyApp.Cldr, unit: :foot, style: :narrow, per: :second
{:ok, "1,234′/s"}

iex> Cldr.Unit.to_string 1234, MyApp.Cldr, unit: :foot, per: :second
{:ok, "1,234 feet per second"}

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: :megabyte, locale: "en", style: :unknown
{:error, {Cldr.UnknownFormatError, "The unit style :unknown is not known."}}

iex> Cldr.Unit.to_string 123, MyApp.Cldr, unit: :blabber, locale: "en"
{:error, {Cldr.UnknownUnitError, "The unit :blabber is not known."}}
Link to this function

to_string!(number, backend \\ Cldr.default_backend(), options \\ [])

View Source
to_string!(value(), Cldr.backend() | Keyword.t(), Keyword.t()) ::
  String.t() | no_return()

Formats a list using to_string/3 but raises if there is an error.

Arguments

  • number is any number (integer, float or Decimal) or a Cldr.Unit.t() 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 and exception

Examples

iex> Cldr.Unit.to_string! 123, MyApp.Cldr, unit: :gallon
"123 gallons"

iex> Cldr.Unit.to_string! 1, MyApp.Cldr, unit: :gallon
"1 gallon"

iex> Cldr.Unit.to_string! 1, MyApp.Cldr, unit: :gallon, locale: "af"
"1 gelling"

Returns a list of the known unit categories.

Example

iex> Cldr.Unit.unit_categories
[:acceleration, :angle, :area, :compound, :concentr, :consumption, :coordinate, :digital,
 :duration, :electric, :energy, :force, :frequency, :graphics, :length, :light, :mass,
 :power, :pressure, :speed, :temperature, :torque, :volume]
Link to this function

unit_category(unit)

View Source
unit_category(Cldr.Unit.t() | String.t() | atom()) ::
  atom() | {:error, {module(), String.t()}}

Returns the units category for a given unit

Options

Returns

  • a valid category or

  • {:error, {exception, message}}

Examples

iex> Cldr.Unit.unit_category :pint_metric
:volume

iex> Cldr.Unit.unit_category :stone
:mass
Link to this function

unit_category_map()

View Source
unit_category_map() :: map()

Returns a mapping of units to their respective unit categories

Example

=> iex> Cldr.Unit.unit_category_map
%{
  kilowatt: :power,
  percent: :concentr,
  picometer: :length,
  centiliter: :volume,
  square_inch: :area,
  megapascal: :pressure,
  atmosphere: :pressure,
  per: :compound,
  ...
}
Link to this function

unit_preferences()

View Source
unit_preferences() :: map()

Returns a map of unit preferences

Units of measure vary country by country. While most countries standardize on the metric system, others use the US or UKL systems of measure.

When presening a unit to an end user it is appropriate to do so using units familiar and relevant to that end user.

The data returned by this function supports the opportunity to convert a give unit to meet this requirement.

Unit preferences can vary by usage, not just territory, Therefore the data is structured according to unit category and unit usage.

Link to this function

unit_tree()

View Source
unit_tree() :: map()

Returns a list of the unit categories and associated units

Example

Cldr.Unit.unit_tree
=> %{
  acceleration: [:g_force, :meter_per_second_squared],
  angle: [:arc_minute, :arc_second, :degree, :radian, :revolution],
  area: [:acre, :hectare, :square_centimeter, :square_foot, :square_inch,
         :square_kilometer, :square_meter, :square_mile, :square_yard],
  concentr: [:karat, :milligram_per_deciliter, :millimole_per_liter,
             :part_per_million]
  ...
Link to this function

units()

View Source
units() :: [atom(), ...]

Returns the known units.

Example

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

units(category)

View Source
units(atom()) :: [atom(), ...]

Returns the units for a given unit type

Arguments

Returns

  • a list of units

Examples

iex> Cldr.Unit.units(:length)
[:astronomical_unit, :centimeter, :decimeter, :fathom, :foot, :furlong, :inch,
 :kilometer, :light_year, :meter, :micrometer, :mile, :mile_scandinavian,
 :millimeter, :nanometer, :nautical_mile, :parsec, :picometer, :point,
 :solar_radius, :yard]

Validates a unit style and normalizes it to a standard downcased atom form

Validates a unit name and normalizes it to a standard downcased atom form

Link to this function

value(unit)

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

Example

iex> u = Cldr.Unit.new(:foot, 23.3)
#Unit<:foot, 23.3>
iex> Cldr.Unit.zero(u)
#Unit<:foot, 0.0>

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

Examples

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

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