Cldr Units v2.8.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.
Localizes a unit according to a territory
Returns the default measurement system for a territory.
Returns the default measurement system for a territory in a given category.
Returns the measurement system in use by territory
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 known unit categories.
Returns the units category for a given unit
Returns a mapping of units to their respective unit categories
Returns a map of unit preferences
Returns a list of the unit categories and associated units
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 section Functions
See Cldr.Unit.Math.add/2
.
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,
:solar_radius, :yard]
iex> Cldr.Unit.compatible_units :me, jaro: true
[{0.7999999999999999, :meter}]
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]
Arguments
unit
is any unit returned byCldr.Unit.new/2
decompose_list
is a list of valid units (one or more from the list returned byCldr.units/0
). All units must be from the same category.
Returns
- a list of units after decomposition or an error tuple
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)]
Returns the default formatting style.
Example
iex> Cldr.Unit.default_style
:long
See Cldr.Unit.Math.div/2
.
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}]
Localizes a unit according to a territory
A territory can be derived from a locale_name
or Cldr.LangaugeTag.t()
.
Use this function if you have a unit which
should be presented in a user interface using
units relevant to the audience. For example, a
unit #Unit<100, :meter>
might be better
presented to a US audiance as #Unit<328, :foot>
.
Arguments
unit
is any unit returned byCldr.Unit.new/2
usage
is the way in which the unit is intended to be used. The availableusage
varyies according to the unit category. SeeCldr.Unit.unit_preferences/0
.options
is a keyword list of options
Options
:locale
is any valid locale name returned byCldr.known_locale_names/0
or aCldr.LanguageTag
struct. The default isCldr.get_locale/0
:territory
is any valid territory code returned byCldr.known_territories/0
. The default is the territory defined as part of the:locale
.:scope
may be set to:small
to indicate that a unit conversion intended for "small" unit sizes is preferred. In some territories it is customary to use different units for "small" sizes from those that are "large".:style
may be set to:informal
to indicate that a more informal unit conversion be applied.
Examples
iex> Cldr.Unit.localize(Cldr.Unit.new(100, :meter), :person, territory: :US)
[Cldr.Unit.new(:inch, 3937)]
iex> Cldr.Unit.localize(Cldr.Unit.new(100, :meter), :person, territory: :US, style: :informal)
[Cldr.Unit.new(:foot, 328), Cldr.Unit.new(:inch, 1)]
Returns the default measurement system for a territory.
Example
iex> Cldr.Unit.measurement_system_for :US
:US
iex> Cldr.Unit.measurement_system_for :GB
:UK
iex> Cldr.Unit.measurement_system_for :AU
:metric
Returns the default measurement system for a territory in a given category.
Example
iex> Cldr.Unit.measurement_system_for :US, :temperature
:US
iex> Cldr.Unit.measurement_system_for :BS, :temperature
:US
iex> Cldr.Unit.measurement_system_for :BS
:metric
Returns the measurement system in use by territory
Example
iex> Cldr.Unit.measurement_systems
%{
default: %{
"001": :metric,
GB: :UK,
LR: :US,
MM: :US,
US: :US
},
paper_size: %{
"001": :A4,
BZ: :"US-Letter",
CA: :"US-Letter",
CL: :"US-Letter",
CO: :"US-Letter",
CR: :"US-Letter",
GT: :"US-Letter",
MX: :"US-Letter",
NI: :"US-Letter",
PA: :"US-Letter",
PH: :"US-Letter",
PR: :"US-Letter",
SV: :"US-Letter",
US: :"US-Letter",
VE: :"US-Letter"
},
temperature: %{
BS: :US,
BZ: :US,
KY: :US,
LR: :metric,
MM: :metric,
PR: :US,
PW: :US
}
}
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."}}
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 the known styles for a unit.
Example
iex> Cldr.Unit.styles
[:long, :short, :narrow]
See Cldr.Unit.Math.sub/2
.
to_string(list_or_number, backend \\ Cldr.default_backend(), options \\ [])
View SourceFormats 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_locale/0
:style
is one of those returned byCldr.Unit.styles
. The current styles are:long
,:short
and:narrow
. The default isstyle: :long
:per
allows compound units to be formatted. For example, assume we want to format a string which represents "kilograms per second". There is no such unit defined in CLDR (or perhaps anywhere!). If however we define the unitunit = Cldr.Unit.new(:kilogram, 20)
we can then executeCldr.Unit.to_string(unit, per: :second)
. Each locale defines a specific way to format such a compount unit. Usually it will return something like20 kilograms/second
: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> Cldr.Unit.to_string 1234, MyApp.Cldr, unit: :foot, style: :narrow, per: :second
{:ok, "1,234′/s"}
iex> Cldr.Unit.to_string 1234, MyApp.Cldr, unit: :foot, per: :second
{:ok, "1,234 feet per second"}
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 SourceFormats 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_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"
Returns a list of the known unit categories.
Example
iex> Cldr.Unit.unit_categories
[:acceleration, :angle, :area, :compound, :concentr, :consumption, :coordinate, :digital,
:duration, :electric, :energy, :force, :frequency, :graphics, :length, :light, :mass,
:power, :pressure, :speed, :temperature, :torque, :volume]
Returns the units category for a given unit
Options
unit
is any units returned byCldr.Unit.new/2
or units returned byCldr.Unit.units/0
Returns
a valid category or
{:error, {exception, message}}
Examples
iex> Cldr.Unit.unit_category :pint_metric
:volume
iex> Cldr.Unit.unit_category :stone
:mass
Returns a mapping of units to their respective unit categories
Example
=> iex> Cldr.Unit.unit_category_map
%{
kilowatt: :power,
percent: :concentr,
picometer: :length,
centiliter: :volume,
square_inch: :area,
megapascal: :pressure,
atmosphere: :pressure,
per: :compound,
...
}
Returns a map of unit preferences
Units of measure vary country by country. While most countries standardize on the metric system, others use the US or UKL systems of measure.
When presening a unit to an end user it is appropriate to do so using units familiar and relevant to that end user.
The data returned by this function supports the opportunity to convert a give unit to meet this requirement.
Unit preferences can vary by usage, not just territory, Therefore the data is structured according to unit category and unit usage.
Returns a list of the unit categories 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]
...
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_categories/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]
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
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
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