Packages
ex_cldr
0.3.0
2.47.5
2.47.4
2.47.3
2.47.2
2.47.1
2.47.0
2.46.0
2.45.2
2.45.1
2.45.0
2.44.1
2.44.0
2.43.2
2.43.1
2.43.0
2.42.0
2.41.1
2.41.0
2.40.4
2.40.3
2.40.2
2.40.1
2.40.0
2.39.2
2.39.1
2.39.0
2.38.1
2.38.0
2.37.5
2.37.4
2.37.3
retired
2.37.2
2.37.1
2.37.0
2.36.0
2.35.1
2.35.0
retired
2.34.2
2.34.1
2.34.0
2.33.2
2.33.1
2.33.1-rc.0
2.33.0
2.32.1
2.32.0
2.31.0
2.30.0
2.29.0
2.28.0
2.27.1
2.27.0
retired
2.26.3
2.26.2
2.26.1
2.26.0
2.25.0
2.24.2
2.24.1
2.24.0
2.24.0-rc.6
2.24.0-rc.5
2.24.0-rc.4
2.24.0-rc.3
2.24.0-rc.2
2.24.0-rc.1
2.24.0-rc.0
2.23.2
2.23.1
2.23.0
2.22.1
2.22.0
2.21.0
2.20.0
2.20.0-rc.3
2.20.0-rc.2
2.20.0-rc.1
2.20.0-rc.0
2.19.1
2.19.0
2.18.2
2.18.1
2.18.0
2.18.0-rc.0
2.17.2
2.17.1
2.17.0
2.16.2
2.16.1
2.16.1-rc.0
2.16.0
2.15.0
2.14.1
2.14.0
2.14.0-rc.0
2.13.0
2.12.1
2.12.0
2.11.1
2.11.0
2.10.2
2.10.1
2.10.0
retired
2.9.0
2.8.1
2.8.0
2.7.2
2.7.1
2.7.0
2.6.2
2.6.1
2.6.0
2.5.0
2.4.3
2.4.2
2.4.1
2.4.0
2.3.2
2.3.1
2.3.0
2.2.7
2.2.6
2.2.5
2.2.4
2.2.3
2.2.2
2.2.1
2.2.0
2.1.0
2.0.4
2.0.3
2.0.2
2.0.1
2.0.0
2.0.0-rc.3
retired
2.0.0-rc.2
retired
2.0.0-rc.1
retired
2.0.0-rc.0
retired
1.8.2
1.8.1
1.8.0
1.7.1
1.7.0
1.6.4
1.6.3
1.6.2
1.6.1
1.6.0
1.5.2
1.5.1
1.5.0
1.4.5
1.4.4
1.4.3
1.4.2
1.4.1
1.4.0
retired
1.4.0-rc.3
retired
1.4.0-rc.2
retired
1.4.0-rc.1
retired
1.4.0-rc.0
retired
1.3.2
1.3.1
1.3.0
1.2.0
1.1.0
1.0.0
1.0.0-rc.3
retired
1.0.0-rc.2
retired
1.0.0-rc.1
retired
1.0.0-rc.0
retired
0.13.1
0.13.0
0.12.2
retired
0.12.1
retired
0.12.0
retired
0.11.0
retired
0.10.0
retired
0.9.0
retired
0.8.3
retired
0.8.2
retired
0.8.1
retired
0.8.0
retired
0.7.0
retired
0.6.2
retired
0.6.1
retired
0.6.0
retired
0.5.2
retired
0.5.1
retired
0.5.0
retired
0.4.2
retired
0.4.1
retired
0.4.0
retired
0.3.0
retired
0.2.1
retired
0.2.0
retired
0.1.3
retired
0.1.2
retired
0.1.1
retired
0.1.0
retired
0.0.20
retired
0.0.19
retired
0.0.18
retired
0.0.17
retired
0.0.16
retired
0.0.15
retired
0.0.14
retired
0.0.13
retired
0.0.12
retired
0.0.11
retired
0.0.10
retired
0.0.8
retired
0.0.7
retired
0.0.6
retired
0.0.5
retired
0.0.4
retired
0.0.3
retired
Common Locale Data Repository (CLDR) functions for Elixir to localize and format numbers, dates, lists, messages, languages, territories and units with support for over 700 locales for internationalized (i18n) and localized (L10N) applications.
Retired package: Deprecated
Current section
Files
Jump to
Current section
Files
lib/cldr/units.ex
defmodule Cldr.Unit do
@moduledoc """
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
"""
alias Cldr.Substitution
@unit_styles [:long, :short, :narrow]
@default_style :long
@doc """
Formats a number into a string according to a unit definition for a locale.
* `number` is any number (integer, float or Decimal)
* `unit` is any unit returned by `Cldr.Unit.available_units/0`
* `options` are:
* `locale` is any configured locale. See `Cldr.known_locales()`. The default
is `locale: Cldr.get_locale()`
* `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`
## Examples
iex> Cldr.Unit.to_string 123, :volume_gallon
"123 gallons"
iex> Cldr.Unit.to_string 1, :volume_gallon
"1 gallon"
iex> Cldr.Unit.to_string 1, :volume_gallon, locale: "af"
"1 gelling"
iex> Cldr.Unit.to_string 1, :volume_gallon, locale: "af-NA"
"1 gelling"
iex> Cldr.Unit.to_string 1, :volume_gallon, locale: "bs"
"1 galona"
iex> Cldr.Unit.to_string 1234, :volume_gallon, format: :long
"1 thousand gallons"
iex> Cldr.Unit.to_string 1234, :volume_gallon, format: :short
"1K gallons"
iex> Cldr.Unit.to_string 1234, :frequency_megahertz
"1,234 megahertz"
iex> Cldr.Unit.to_string 1234, :frequency_megahertz, style: :narrow
"1,234MHz"
Cldr.Unit.to_string 123, :digital_megabyte, locale: "en-XX"
{:error, {Cldr.UnknownLocaleError, "The locale \"en-XX\" is not known."}}
Cldr.Unit.to_string 123, :digital_megabyte, locale: "en", style: :unknown
{:error, {Cldr.UnknownFormatError, "The unit style :unknown is not known."}}
"""
@spec to_string(Cldr.Math.number_or_decimal, atom, Keyword.t) :: String.t | {:error, {atom, binary}}
def to_string(number, unit, options \\ []) do
case normalize_options(options) do
{:error, {_exception, _message}} = error ->
error
{locale, style, options} ->
case result = to_string(number, unit, locale, style, options) do
{:error, _} -> result
_ -> :erlang.iolist_to_binary(result)
end
end
end
@doc """
Formats a list using `to_string/3` but raises if there is
an error.
"""
@spec to_string!(List.t, atom, Keyword.t) :: String.t | Exception.t
def to_string!(number, unit, options \\ []) do
case string = to_string(number, unit, options) do
{:error, {exception, message}} ->
raise exception, message
_ ->
string
end
end
defp to_string(number, unit, locale, style, options) do
number_string = Cldr.Number.to_string(number, options ++ [locale: locale])
if patterns = pattern_for(locale, style, unit) do
pattern = Cldr.Number.Ordinal.pluralize(number, locale, patterns)
Substitution.substitute([number_string], pattern)
else
verify_unit(locale, style, unit)
end
end
@doc """
Returns the available units for a given locale and style.
* `locale` is any configured locale. See `Cldr.known_locales()`. The default
is `locale: Cldr.get_locale()`
* `style` is one of those returned by `Cldr.Unit.available_styles`.
The current styles are `:long`, `:short` and `:narrow`. The default is `style: :long`
## Example
Cldr.Unit.available_units
[:volume_gallon, :pressure_pound_per_square_inch, :digital_terabyte,
:digital_bit, :digital_gigabit, :digital_kilobit, :volume_pint,
:speed_kilometer_per_hour, :concentr_part_per_million, :energy_calorie,
:volume_milliliter, :length_fathom, :length_foot, :volume_cubic_yard,
:mass_microgram, :length_nautical_mile, :volume_deciliter,
:consumption_mile_per_gallon, :volume_bushel, :volume_cubic_centimeter,
:length_light_year, :volume_gallon_imperial, :speed_meter_per_second,
:power_kilowatt, :power_watt, :length_millimeter, :digital_gigabyte,
:duration_nanosecond, :length_centimeter, :volume_cup_metric,
:length_kilometer, :angle_degree, :acceleration_g_force, :electric_ampere,
:volume_quart, :duration_century, :angle_revolution, :volume_hectoliter,
:area_square_meter, :digital_megabyte, :light_lux, :duration_year,
:energy_kilocalorie, :frequency_megahertz, :power_horsepower,
:volume_cubic_meter, :area_hectare, :frequency_hertz, :length_furlong,
:length_astronomical_unit, ...]
"""
def available_units(locale \\ Cldr.get_locale(), style \\ @default_style) do
Cldr.Locale.get_locale(locale)
|> get_in([:units, style])
|> Map.keys
end
@doc """
Returns the available styles for a unit localiation.
## Example
iex> Cldr.Unit.available_styles
[:long, :short, :narrow]
"""
def available_styles do
@unit_styles
end
defp pattern_for(locale, style, unit) do
Cldr.Locale.get_locale(locale)
|> get_in([:units, style, unit])
end
defp normalize_options(options) do
locale = options[:locale] || Cldr.get_locale()
style = options[:style] || @default_style
options = Keyword.delete(options, :locale) |> Keyword.delete(:style)
with :ok <- verify_locale(locale),
:ok <- verify_style(style)
do
{locale, style, options}
else
{:error, {_exception, _message}} = error -> error
end
end
defp verify_locale(locale) do
if !Cldr.known_locale?(locale) do
{:error, {Cldr.UnknownLocaleError, "The locale #{inspect locale} is not known."}}
else
:ok
end
end
defp verify_unit(locale, style, unit) do
if !pattern_for(locale, style, unit) do
{:error, {Cldr.UnknownUnitError, "The unit #{inspect unit} is not known."}}
else
:ok
end
end
defp verify_style(style) do
if !(style in @unit_styles) do
{:error, {Cldr.UnknownFormatError, "The unit style #{inspect style} is not known."}}
else
:ok
end
end
end