Cldr.Unit.Conversion (Cldr Units v3.3.0) View Source

Unit conversion functions for the units defined in Cldr.

Link to this section Summary

Types

t()

Functions

convert(unit, to_unit)

Convert one unit into another unit of the same unit type (length, volume, mass, ...)

convert!(unit, to_unit)

Convert one unit into another unit of the same unit type (length, volume, mass, ...) and raises on a unit type mismatch

convert_from_base(value, to)

convert_to_base(value, from)

convert_to_base_unit(unit)

Convert a unit into its base unit.

convert_to_base_unit!(unit)

Convert a unit into its base unit and raises on error

Link to this section Types

t()

Specs

t() :: %{
  factor: integer() | float() | Ratio.t(),
  base_unit: [atom(), ...],
  offset: integer() | float()
}

Link to this section Functions

convert(unit, to_unit)

Specs

convert(Cldr.Unit.t(), Cldr.Unit.unit()) ::
  {:ok, Cldr.Unit.t()} | {:error, {module(), String.t()}}

Convert one unit into another unit of the same unit type (length, volume, mass, ...)

Arguments

unit is any unit returned by Cldr.Unit.new/2
to_unit is any unit name returned by Cldr.Unit.units/0

Returns

a Unit.t of the unit type to_unit or
{:error, {exception, message}}

Examples

iex> Cldr.Unit.convert Cldr.Unit.new!(:mile, 1), :foot
{:ok, Cldr.Unit.new!(:foot, 5280)}

iex> Cldr.Unit.convert Cldr.Unit.new!(:mile, 1), :gallon
{:error, {Cldr.Unit.IncompatibleUnitsError,
  "Operations can only be performed between units of the same category. Received :mile and :gallon"}}

convert!(unit, to_unit)

Specs

convert!(Cldr.Unit.t(), Cldr.Unit.unit()) :: Cldr.Unit.t() | no_return()

Convert one unit into another unit of the same unit type (length, volume, mass, ...) and raises on a unit type mismatch

Arguments

unit is any unit returned by Cldr.Unit.new/2
to_unit is any unit name returned by Cldr.Unit.units/0

Returns

a Unit.t of the unit type to_unit or
raises an exception

Examples

iex> Cldr.Unit.Conversion.convert!(Cldr.Unit.new!(:celsius, 0), :fahrenheit)
...> |> Cldr.Unit.round
#Cldr.Unit<:fahrenheit, 32.0>

iex> Cldr.Unit.Conversion.convert!(Cldr.Unit.new!(:fahrenheit, 32), :celsius)
...> |> Cldr.Unit.round
#Cldr.Unit<:celsius, 0.0>

Cldr.Unit.Conversion.convert Cldr.Unit.new!(:mile, 1), :gallon
** (Cldr.Unit.IncompatibleUnitsError) Operations can only be performed between units of the same type. Received :mile and :gallon

convert_from_base(value, to)

convert_to_base(value, from)

convert_to_base_unit(unit)

Convert a unit into its base unit.

For example, the base unit for length is meter. The base unit is an intermediary unit used in all conversions.

Arguments

unit is any unit returned by Cldr.Unit.new/2

Returns

unit converted to its base unit as a t:Unit.t() or
{;error, {exception, reason}} as an error

Example

iex> unit = Cldr.Unit.new!(:kilometer, 10)
iex> Cldr.Unit.Conversion.convert_to_base_unit unit
{:ok, Cldr.Unit.new!(:meter, 10000)}

convert_to_base_unit!(unit)

Convert a unit into its base unit and raises on error

For example, the base unit for length is meter. The base unit is an intermediary unit used in all conversions.

Arguments

unit is any unit returned by Cldr.Unit.new/2

Returns

unit converted to its base unit as a t:Unit.t() or
raises an exception

Example

iex> unit = Cldr.Unit.new!(:kilometer, 10)
iex> Cldr.Unit.Conversion.convert_to_base_unit! unit
#Cldr.Unit<:meter, 10000>