Cldr Units v2.0.0 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 stringCldr.Unit.available_units/0
identifies the available units for localization
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
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
Link to this section Types
Link to this section Functions
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
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
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}]
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}
]
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
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."}}
to_string!(Math.decimal_or_number(), 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/2
. 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"
to_string(Cldr.Math.number_or_decimal() | t(), Cldr.backend(), Keyword.t()) :: {:ok, String.t()} | {:error, {atom(), binary()}}
Formats a number into a string according to a unit definition for a locale.
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/2
. 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
{: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: "af-NA"
{: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."}}
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(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
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]
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, ...]
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]
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
value(unit :: Cldr.Unit.t()) :: Cldr.Math.number_or_decimal()
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