Cldr Units v2.5.1 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
See Cldr.Unit.Math.add/2
.
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,
:solar_radius, :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
See Cldr.Unit.Math.div/2
.
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
See Cldr.Unit.Math.sub/2
.
sub!(unit_1, unit_2) View Source
to_string(list_or_number, backend \\ Cldr.default_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()
structsbackend
is any module that includesuse Cldr
and therefore is aCldr
backend module. The default isCldr.default_backend/0
.options
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, 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> 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."}}
to_string!(number, backend \\ Cldr.default_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()
structbackend
is any module that includesuse Cldr
and therefore is aCldr
backend module. The default isCldr.default_backend/0
.options
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, 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"
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, :force, :frequency, :length, :light, :mass,
:power, :pressure, :speed, :temperature, :torque, :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,
:solar_radius, :yard]
units_for(locale, style, backend \\ Cldr.default_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