Cldr Units v2.3.3 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 stringCldr.Unit.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.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
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 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
style()
View Source
style() :: atom()
style() :: atom()
unit()
View Source
unit() :: atom()
unit() :: atom()
value()
View Source
value() :: Cldr.Math.number_or_decimal()
value() :: Cldr.Math.number_or_decimal()
Link to this section Functions
add(unit_1, unit_2) View Source
add!(unit_1, unit_2) View Source
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 byCldr.Unit.units/0
or byCldr.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 ornil
Examples
iex> Cldr.Unit.best_match :ft
:fathom
iex> Cldr.Unit.best_match :zippity
nil
compatible?(unit_1, unit_2) View Source
Returns a boolean indicating if two units are of the same unit type.
Options
unit_1
andunit_2
are any units returned byCldr.Unit.new/2
or units returned byCldr.Unit.units/0
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
compatible_units(unit, options \\ [jaro: false, distance: 0.75]) View Source
Returns a list of units that are compatible with the provided unit.
Arguments
unit
is any unit returned byCldr.Unit.units/0
or byCldr.Unit.new/2
options
is a keyword list of options
Options
:jaro
is a boolean which determines if the match is to use the jaro distance. The default isfalse
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) View Source
decompose(unit, list)
View Source
decompose(Cldr.Unit.t(), [Cldr.Unit.unit(), ...]) ::
[Cldr.Unit.t(), ...] | {:error, {module(), String.t()}}
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), 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)]
default_style() View Source
Returns the default formatting style.
Example
iex> Cldr.Unit.default_style
:long
div(unit_1, unit_2) View Source
div!(unit_1, unit_2) View Source
jaro_match(unit, distance \\ 0.75) View Source
Returns a list of units that are within the specified jaro distance of the provided unit.
Arguments
unit
is any unit returned byCldr.Unit.units/0
or byCldr.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) View Source
mult!(unit_1, unit_2) View Source
new(value, unit) View Source
Returns a new Unit.t
struct.
Options
value
is any float, integer orDecimal
unit
is any unit returned byCldr.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."}}
new!(unit, value) View Source
Returns a new Unit.t
struct or raises on error.
Options
value
is any float, integer orDecimal
unit
is any unit returned byCldr.Unit.units/0
Returns
unit
orraises 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
round(unit) View Source
round(unit, places) View Source
round(unit, places, mode) View Source
styles() View Source
Returns the known styles for a unit.
Example
iex> Cldr.Unit.styles
[:long, :short, :narrow]
sub(unit_1, unit_2) View Source
sub!(unit_1, unit_2) View Source
to_string(list_or_number, backend, options \\ []) View Source
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 aCldr.Unit.t()
struct or a list ofCldr.Unit.t()
structsoptions
is a keyword list of options
Options
:unit
is any unit returned byCldr.Unit.units/1
. Ignored if the number to be formatted is aCldr.Unit.t()
struct:locale
is any valid locale name returned byCldr.known_locale_names/1
or aCldr.LanguageTag
struct. The default isCldr.get_current_locale/0
:style
is one of those returned byCldr.Unit.styles
. The current styles are:long
,:short
and:narrow
. The default isstyle: :long
: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 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."}}
to_string!(number, backend, options \\ [])
View Source
to_string!(value(), Cldr.backend(), Keyword.t()) :: String.t() | no_return()
to_string!(value(), Cldr.backend(), 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 aCldr.Unit.t()
structoptions
is a keyword list
Options
:unit
is any unit returned byCldr.Unit.units/1
. Ignored if the number to be formatted is aCldr.Unit.t()
struct:locale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag
struct. The default isCldr.get_current_locale/0
:style
is one of those returned byCldr.Unit.available_styles
. 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 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"
unit_tree()
View Source
unit_tree() :: map()
unit_tree() :: map()
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)
View Source
unit_type(Cldr.Unit.t() | String.t() | atom()) ::
atom() | {:error, {Exception.t(), String.t()}}
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 byCldr.Unit.new/2
or units returned byCldr.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() View Source
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()
View Source
units() :: [atom(), ...]
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) View Source
Returns the units for a given unit type
Arguments
type
is any unit type returned byCldr.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]
units_for(locale, style, backend) View Source
validate_style(style) View Source
Validates a unit style and normalizes it to a standard downcased atom form
validate_unit(unit) View Source
Validates a unit name and normalizes it to a standard downcased atom form
value(unit) View Source
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
zero(unit) View Source
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>
zero?(unit) View Source
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