# View Source Cldr.Unit.Conversion(Cldr Units v3.16.4)

Unit conversion functions for the units defined in Cldr.

# Summary

## Functions

Returns the base unit and the base unit conversionfor a given unit.

Returns the conversion that calculates the base unit into another unit or and error.

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

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

Convert a unit into its base unit.

Convert a unit into its base unit and raises on error

# factor()

View Source
@type factor() :: integer() | float()

# offset()

View Source
@type offset() :: integer() | float()

# t()

View Source
@type t() :: %{factor: factor(), base_unit: [atom(), ...], offset: offset()}

# base_unit_and_conversion(unit_name)

View Source

Returns the base unit and the base unit conversionfor a given unit.

## Argument

• unit is either a t:Cldr.Unit, an atom or a t:String

## Returns

• {:ok, base_unit, conversion} or

• {:error, {exception, reason}}

## Example

iex> Cldr.Unit.Conversion.base_unit_and_conversion :square_kilometer
{
:ok,
:square_meter,
[square_kilometer: %Cldr.Unit.Conversion{base_unit: [:square, :meter], factor: 1000000, offset: 0}]
}

iex> Cldr.Unit.Conversion.base_unit_and_conversion :square_table
{:error, {Cldr.UnknownUnitError, "Unknown unit was detected at \"table\""}}

# conversion_for(unit_1, unit_2)

View Source

Returns the conversion that calculates the base unit into another unit or and error.

# convert(unit, to_unit)

View Source
@spec 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, ...)

## 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 with the same base unit. Received :mile and :gallon"}}

# convert!(unit, to_unit)

View Source
@spec 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

## 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.new!(:fahrenheit, 32)

iex> Cldr.Unit.Conversion.convert!(Cldr.Unit.new!(:fahrenheit, 32), :celsius)
...> |> Cldr.Unit.round
Cldr.Unit.new!(:celsius, 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_to_base_unit(unit)

View Source

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.

## 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)

View Source

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.

## 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.new!(:meter, 10000)

View Source