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

Simple arithmetic functions for the `Unit.t` type

# Link to this section Summary

## Functions

Adds two compatible `%Unit{}` types

Adds two compatible `%Unit{}` types and raises on error

cmp(unit_1, unit_2) deprecated

Compare two units, converting to a common unit type if required.

Divides one compatible `%Unit{}` type by another

Divides one compatible `%Unit{}` type by another and raises on error

Multiplies two compatible `%Unit{}` types

Multiplies two compatible `%Unit{}` types and raises on error

Rounds the value of a unit.

Subtracts two compatible `%Unit{}` types

Subtracts two compatible `%Unit{}` types and raises on error

Truncates a unit's value

# Link to this section Functions

View Source

## Specs

```add(Cldr.Unit.t(), Cldr.Unit.t()) ::
Cldr.Unit.t() | {:error, {module(), String.t()}}```

Adds two compatible `%Unit{}` types

## Returns

• A `%Unit{}` of the same type as `unit_1` with a value that is the sum of `unit_1` and the potentially converted `unit_2` or

• `{:error, {IncompatibleUnitError, message}}`

## Examples

``````iex> Cldr.Unit.Math.add Cldr.Unit.new!(:foot, 1), Cldr.Unit.new!(:foot, 1)
#Cldr.Unit<:foot, 2>

iex> Cldr.Unit.Math.add Cldr.Unit.new!(:foot, 1), Cldr.Unit.new!(:mile, 1)
#Cldr.Unit<:foot, 5281>

iex> Cldr.Unit.Math.add Cldr.Unit.new!(:foot, 1), Cldr.Unit.new!(:gallon, 1)
{:error, {Cldr.Unit.IncompatibleUnitsError,
"Operations can only be performed between units with the same base unit. Received :foot and :gallon"}}``````

View Source

## Specs

`add!(Cldr.Unit.t(), Cldr.Unit.t()) :: Cldr.Unit.t() | no_return()`

Adds two compatible `%Unit{}` types and raises on error

## Returns

• A `%Unit{}` of the same type as `unit_1` with a value that is the sum of `unit_1` and the potentially converted `unit_2` or

• Raises an exception

# cmp(unit_1, unit_2)

View Source
This function is deprecated. Please use Cldr.Unit.Math.compare/2.

# compare(unit_1, unit_2)

View Source

Compare two units, converting to a common unit type if required.

If conversion is performed, the results are both rounded to a single decimal place before comparison.

Returns `:gt`, `:lt`, or `:eq`.

## Example

``````iex> x = Cldr.Unit.new!(:kilometer, 1)
iex> y = Cldr.Unit.new!(:meter, 1000)
iex> Cldr.Unit.Math.compare x, y
:eq``````

# div(unit_1, unit_1)

View Source

## Specs

```div(Cldr.Unit.t(), Cldr.Unit.t()) ::
Cldr.Unit.t() | {:error, {module(), String.t()}}```

Divides one compatible `%Unit{}` type by another

## Returns

• A `%Unit{}` of the same type as `unit_1` with a value that is the dividend of `unit_1` and the potentially converted `unit_2`

• `{:error, {IncompatibleUnitError, message}}`

## Examples

``````iex> Cldr.Unit.div Cldr.Unit.new!(:kilogram, 5), Cldr.Unit.new!(:pound, 1)
#Cldr.Unit<:kilogram, 8171193714040401 <|> 90071992547409920>

iex> Cldr.Unit.div Cldr.Unit.new!(:pint, 5), Cldr.Unit.new!(:liter, 1)
#Cldr.Unit<:pint, 26938398179283203149098379558387912499591752187904 <|> 63733081193714246983132277926414951878417636536165>

iex> Cldr.Unit.div Cldr.Unit.new!(:pint, 5), Cldr.Unit.new!(:pint, 1)
#Cldr.Unit<:pint, 5.0>``````

# div!(unit_1, unit_2)

View Source

## Specs

`div!(Cldr.Unit.t(), Cldr.Unit.t()) :: Cldr.Unit.t() | no_return()`

Divides one compatible `%Unit{}` type by another and raises on error

## Returns

• A `%Unit{}` of the same type as `unit_1` with a value that is the dividend of `unit_1` and the potentially converted `unit_2`

• Raises an exception

# mult(unit_1, unit_1)

View Source

## Specs

```mult(Cldr.Unit.t(), Cldr.Unit.t()) ::
Cldr.Unit.t() | {:error, {module(), String.t()}}```

Multiplies two compatible `%Unit{}` types

## Returns

• A `%Unit{}` of the same type as `unit_1` with a value that is the product of `unit_1` and the potentially converted `unit_2`

• `{:error, {IncompatibleUnitError, message}}`

## Examples

``````iex> Cldr.Unit.mult Cldr.Unit.new!(:kilogram, 5), Cldr.Unit.new!(:pound, 1)
#Cldr.Unit<:kilogram, 40855968570202005 <|> 18014398509481984>

iex> Cldr.Unit.mult Cldr.Unit.new!(:pint, 5), Cldr.Unit.new!(:liter, 1)
#Cldr.Unit<:pint, 134691990896416015745491897791939562497958760939520 <|> 12746616238742849396626455585282990375683527307233>

iex> Cldr.Unit.mult Cldr.Unit.new!(:pint, 5), Cldr.Unit.new!(:pint, 1)
#Cldr.Unit<:pint, 5>``````

# mult!(unit_1, unit_2)

View Source

## Specs

`mult!(Cldr.Unit.t(), Cldr.Unit.t()) :: Cldr.Unit.t() | no_return()`

Multiplies two compatible `%Unit{}` types and raises on error

## Returns

• A `%Unit{}` of the same type as `unit_1` with a value that is the product of `unit_1` and the potentially converted `unit_2`

• Raises an exception

# round(unit, places \\ 0, mode \\ :half_up)

View Source

## Specs

```round(
unit :: Cldr.Unit.t(),
places :: non_neg_integer(),
mode :: :down | :up | :ceiling | :floor | :half_even | :half_up | :half_down
) :: Cldr.Unit.t()```

Rounds the value of a unit.

## Options

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

• `places` is the number of decimal places to round to. The default is `0`.

• `mode` is the rounding mode to be applied. The default is `:half_up`.

## Returns

• A `%Unit{}` of the same type as `unit` with a value that is rounded to the specified number of decimal places

## Rounding modes

Directed roundings:

• `:down` - Round towards 0 (truncate), eg 10.9 rounds to 10.0

• `:up` - Round away from 0, eg 10.1 rounds to 11.0. (Non IEEE algorithm)

• `:ceiling` - Round toward +∞ - Also known as rounding up or ceiling

• `:floor` - Round toward -∞ - Also known as rounding down or floor

Round to nearest:

• `:half_even` - Round to nearest value, but in a tiebreak, round towards the nearest value with an even (zero) least significant bit, which occurs 50% of the time. This is the default for IEEE binary floating-point and the recommended value for decimal.

• `:half_up` - Round to nearest value, but in a tiebreak, round away from 0. This is the default algorithm for Erlang's Kernel.round/2

• `:half_down` - Round to nearest value, but in a tiebreak, round towards 0 (Non IEEE algorithm)

## Examples

``````iex> Cldr.Unit.round Cldr.Unit.new!(:yard, 1031.61), 1
#Cldr.Unit<:yard, 1031.6>

iex> Cldr.Unit.round Cldr.Unit.new!(:yard, 1031.61), 2
#Cldr.Unit<:yard, 1031.61>

iex> Cldr.Unit.round Cldr.Unit.new!(:yard, 1031.61), 1, :up
#Cldr.Unit<:yard, 1031.7>``````

# sub(unit_1, unit_1)

View Source

## Specs

```sub(Cldr.Unit.t(), Cldr.Unit.t()) ::
Cldr.Unit.t() | {:error, {module(), String.t()}}```

Subtracts two compatible `%Unit{}` types

## Returns

• A `%Unit{}` of the same type as `unit_1` with a value that is the difference between `unit_1` and the potentially converted `unit_2`

• `{:error, {IncompatibleUnitError, message}}`

## Examples

``````iex> Cldr.Unit.sub Cldr.Unit.new!(:kilogram, 5), Cldr.Unit.new!(:pound, 1)
#Cldr.Unit<:kilogram, -81900798833369519 <|> 18014398509481984>

iex> Cldr.Unit.sub Cldr.Unit.new!(:pint, 5), Cldr.Unit.new!(:liter, 1)
#Cldr.Unit<:pint, -36794683014431043834033898368027039378825884348261 <|> 12746616238742849396626455585282990375683527307233>

iex> Cldr.Unit.sub Cldr.Unit.new!(:pint, 5), Cldr.Unit.new!(:pint, 1)
#Cldr.Unit<:pint, 4>``````

# sub!(unit_1, unit_2)

View Source

## Specs

`sub!(Cldr.Unit.t(), Cldr.Unit.t()) :: Cldr.Unit.t() | no_return()`

Subtracts two compatible `%Unit{}` types and raises on error

## Returns

• A `%Unit{}` of the same type as `unit_1` with a value that is the difference between `unit_1` and the potentially converted `unit_2`

• Raises an exception