Cldr Units v1.2.2 Cldr.Unit View Source

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

The public API defines two primary functions:

Cldr.Unit.to_string/3 which, given a number and a unit name will output a localized string
Cldr.Unit.available_units/0 identifies the available units for localization

Link to this section Summary

Types

style()

t()

unit()

Functions

add!(unit_1, unit_2)

add(unit_1, unit_2)

best_match(unit, distance \\ 0.75)

Returns the unit closed in jaro distance to the provided unit

compatible?(unit_1, unit_2)

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

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

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

convert(unit_1, to_unit)

default_style()

Returns the default formatting style

div!(unit_1, unit_2)

div(unit_1, unit_2)

jaro_match(unit, distance \\ 0.75)

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

mult!(unit_1, unit_2)

mult(unit_1, unit_2)

new!(unit, value)

Returns a new Unit.t struct or raises on error

new(value, unit)

Returns a new Unit.t struct

round(unit)

round(unit, places)

round(unit, places, mode)

styles()

Returns the known styles for a unit

sub!(unit_1, unit_2)

sub(unit_1, unit_2)

to_string!(number, options \\ [])

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

to_string(number, options \\ [])

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

unit_tree()

Returns a list of the unit types and associated units

unit_type(unit)

Returns the units associated with a given unit type

unit_types()

Returns a list of the known unit categories

units()

Returns the known units

units(type)

Returns the units for a given unit type

validate_style(style)

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

validate_unit(unit)

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

value(unit)

Return the value of the Unit struct

Link to this section Types

style()

style() :: atom()

t()

t() :: %Cldr.Unit{unit: term(), value: term()}

unit()

unit() :: atom()

Link to this section Functions

add!(unit_1, unit_2)

add(unit_1, unit_2)

best_match(unit, distance \\ 0.75)

Returns the unit closed in jaro distance to the provided unit

Options

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

compatible?(unit_1, unit_2)

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

Options

unit_1 and unit_2 are any units returned by Cldr.Unit.new/2 or units returned by Cldr.Unit.units/0

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

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

compatible_units(unit(), Keyword.t() | Map.t()) ::
  [unit(), ...] | [{float(), unit()}, ...] | []

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

Options

unit is any unit returned by Cldr.Unit.units/0 or by Cldr.Unit.new/2
options is a keyword list of options, The valid options are:
- :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}]

convert(unit_1, to_unit)

default_style()

Returns the default formatting style.

Example

iex> Cldr.Unit.default_style
:long

div!(unit_1, unit_2)

div(unit_1, unit_2)

jaro_match(unit, distance \\ 0.75)

jaro_match(unit(), number()) :: [{float(), unit()}, ...] | []

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

Options

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

mult!(unit_1, unit_2)

mult(unit_1, unit_2)

new!(unit, value)

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

Options

value is any float, integer or Decimal
unit is any unit returned by Cldr.Unit.units/0

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

new(value, unit)

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

round(unit)

round(unit, places)

round(unit, places, mode)

styles()

Returns the known styles for a unit.

Example

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

sub!(unit_1, unit_2)

sub(unit_1, unit_2)

to_string!(number, options \\ [])

to_string!(Math.decimal_or_number(), Keyword.t()) :: String.t() | no_return()

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

Options

number is any number (integer, float or Decimal)
unit is any unit returned by Cldr.Unit.units/2
options are:
- :locale is any valid locale name returned by Cldr.known_locale_names/0 or a Cldr.LanguageTag struct. The default is Cldr.get_current_locale/0
- :style is one of those returned by Cldr.Unit.available_styles. The current styles are :long, :short and :narrow. The default is style: :long
- Any other options are passed to Cldr.Number.to_string/2 which is used to format the number

Returns

formatted_string or
raises and exception

Examples

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

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

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

to_string(number, options \\ [])

to_string(Cldr.Math.number_or_decimal(), Keyword.t()) ::
  {:ok, String.t()} | {:error, {atom(), binary()}}

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

Options

number is any number (integer, float or Decimal)
unit is any unit returned by Cldr.Unit.units/2
options are:
- :locale is any valid locale name returned by Cldr.known_locale_names/0 or a Cldr.LanguageTag struct. The default is Cldr.get_current_locale/0
- :style is one of those returned by Cldr.Unit.available_styles. The current styles are :long, :short and :narrow. The default is style: :long
- 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, unit: :gallon
{:ok, "123 gallons"}

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

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

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

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

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

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

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

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

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

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

unit_tree()

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

unit_type(unit)

unit_type(Cldr.Unit.t() | String.t() | atom()) ::
  atom() | {:error, {Exception.t(), String.t()}}

Returns the units associated with a given unit type

Options

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

Returns

a valid unit or
{:error, {exception, message}}

Examples

iex> Cldr.Unit.unit_type :pint_metric
:volume

iex> Cldr.Unit.unit_type :stone
:mass

unit_types()

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]

units()

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

units(type)

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

Returns the units for a given unit type

Options

type is any unit type returned by Cldr.Unit.unit_types/0

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]

validate_style(style)

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

validate_unit(unit)

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

value(unit)

value(unit :: Cldr.Unit.t()) :: Cldr.Math.number_or_decimal()

Return the value of the Unit struct

Options

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

Returns

an integer, float or Decimal representing the amount of the unit

Example

iex(1)> Cldr.Unit.value Cldr.Unit.new(:kilogram, 23)
23