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

Unit conversion functions for the units defined in `Cldr`.

# Link to this section 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

# Link to this section Types

Link to this type

# factor()

View Source

## Specs

`factor() :: integer() | float() | Ratio.t()`
Link to this type

# offset()

View Source

## Specs

`offset() :: integer() | float()`
Link to this type

# t()

View Source

## Specs

`t() :: %{factor: factor(), base_unit: [atom(), ...], offset: offset()}`

# Link to this section Functions

Link to this function

# 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\""}}``````
Link to this function

# conversion_for(unit_1, unit_2)

View Source

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

Link to this function

# convert(unit, to_unit)

View Source

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

## 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"}}``````
Link to this function

# convert!(unit, to_unit)

View Source

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

## 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``````
Link to this function

# 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)}``````
Link to this function

# 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<:meter, 10000>``````
Link to this function

View Source