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\""}}

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

@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"}}

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