# `Cldr.Unit.Conversion`
[🔗](https://github.com/elixir-cldr/cldr_units/blob/v3.20.3/lib/cldr/unit/conversion.ex#L1)

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

# `factor`

```elixir
@type factor() :: integer() | float()
```

# `offset`

```elixir
@type offset() :: integer() | float()
```

# `t`

```elixir
@type t() :: %{
  factor: factor(),
  base_unit: [atom(), ...],
  offset: offset(),
  special: atom() | nil
}
```

# `base_unit_and_conversion`

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{
          factor: 1000000,
          offset: 0,
          base_unit: [:square, :meter]
        }}
     ]}

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

# `conversion_for`

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

# `convert`

```elixir
@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, ...)

## Arguments

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

* `to_unit` is any unit name returned by `Cldr.Unit.known_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 with the same base unit. Received :mile and :gallon"}}

# `convert!`

```elixir
@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.

## Arguments

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

* `to_unit` is any unit name returned by `Cldr.Unit.known_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.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`

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/0` 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!`

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/0` 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)

# `maybe_invert_value`

---

*Consult [api-reference.md](api-reference.md) for complete listing*