Cldr Units v2.1.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

Returns a new Unit.t struct or raises on error

Returns a new Unit.t struct

Returns the known styles for a unit

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

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

Returns a list of the unit types and associated units

Returns the units associated with a given unit type

Returns a list of the known unit categories

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 type t() View Source
t() :: %Cldr.Unit{unit: term(), value: term()}

Link to this section Functions

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

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.t()) ::
  [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, :yard]

iex> Cldr.Unit.compatible_units :me, jaro: true
[{0.7999999999999999, :meter}]
Link to this function convert(unit_1, to_unit) View Source
Link to this function decompose(unit, list) View Source
decompose(Cldr.Unit.t(), [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]

Examples

iex> u = Cldr.Unit.new(10.3, :foot)
iex> Cldr.Unit.decompose u, [:foot, :inch]
[Cldr.Unit.new(:foot, 10.0), Cldr.Unit.new(:inch, 4.0)]

iex> u = Cldr.Unit.new(:centimeter, 1111)
iex> Cldr.Unit.decompose u, [:kilometer, :meter, :centimeter, :millimeter]
[Cldr.Unit.new(:meter, 11.0), Cldr.Unit.new(:centimeter, 11.0)]

Returns the default formatting style.

Example

iex> Cldr.Unit.default_style
:long
Link to this function jaro_match(unit, distance \\ 0.75) View Source
jaro_match(unit(), 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}
]

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

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 round(unit, places, mode) View Source

Returns the known styles for a unit.

Example

iex> Cldr.Unit.styles
[:long, :short, :narrow]
Link to this function to_string!(number, backend, options \\ []) View Source

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

  • options is a keyword list

Options

Returns

  • formatted_string or

  • raises and exception

Examples

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

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

iex> Cldr.Unit.to_string! 1, TestBackend.Cldr, unit: :gallon, locale: "af"
"1 gelling"
Link to this function to_string(list_or_number, backend, options \\ []) View Source
to_string(
  list_or_number :: Cldr.Math.number_or_decimal() | t() | [t(), ...],
  backend :: Cldr.backend(),
  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

  • options is a keyword list of options

Options

  • :unit is any unit returned by Cldr.Unit.units/2. 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_current_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

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

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

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

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

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

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

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

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

iex> unit = Cldr.Unit.new(123, :foot)
iex> Cldr.Unit.to_string unit, TestBackend.Cldr
{:ok, "123 feet"}

iex> Cldr.Unit.to_string 123, TestBackend.Cldr, unit: :megabyte, locale: "en", style: :unknown
{:error, {Cldr.UnknownFormatError, "The unit style :unknown is not known."}}

iex> Cldr.Unit.to_string 123, TestBackend.Cldr, unit: :blabber, locale: "en"
{:error, {Cldr.UnknownUnitError, "The unit :blabber is not known."}}
Link to this function unit_tree() View Source
unit_tree() :: [atom(), ...]

Returns a list of the unit types 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 unit_type(unit) View Source
unit_type(Cldr.Unit.t() | String.t() | atom()) ::
  atom() | {:error, {Exception.t(), String.t()}}

Returns the units associated with a given unit type

Options

Returns

  • a valid unit or

  • {:error, {exception, message}}

Examples

iex> Cldr.Unit.unit_type :pint_metric
:volume

iex> Cldr.Unit.unit_type :stone
:mass

Returns a list of the known unit categories.

Example

iex> Cldr.Unit.unit_types
[:acceleration, :angle, :area, :concentr, :consumption, :coordinate, :digital,
 :duration, :electric, :energy, :frequency, :length, :light, :mass, :power,
 :pressure, :speed, :temperature, :volume]
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(type) 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, :yard]
Link to this function units_for(locale, style, backend) View Source

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

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