View Source Cldr.Unit.Math (Cldr Units v3.17.0)
Simple arithmetic functions for the t.Cldr.Unit.t/0
type.
Summary
Functions
Adds two compatible Cldr.Unit.t/0
types
Adds two compatible Cldr.Unit.t/0
types
and raises on error.
Compare two units, converting to a common unit type if required.
Divides any Cldr.Unit.t/0
type into another or a
number into a Cldr.Unit.t/0
.
Divides one Cldr.Unit.t/0
type into another.
Any unit can be divided by another.
Multiplies any two Cldr.Unit.t/0
types or a t:Cldr.Unit.t/0and a scalar. ## Arguments *
unit_1is a unit returned by
Cldr.Unit.new/2. *
unit_2is a unit returned by
Cldr.Unit.new/2or a number or Decimal. ## Returns * A
t:Cldr.Unit.t/0of a type that is the product of
unit_1and
unit_2with a value that is the product of
unit_1and
unit_2`'s
values.
## Examples
iex> Cldr.Unit.mult Cldr.Unit.new!(:kilogram, 5), Cldr.Unit.new!(:pound, 1)
Cldr.Unit.new!(:kilogram, "2.26796185")
iex> Cldr.Unit.mult Cldr.Unit.new!(:pint, 5), Cldr.Unit.new!(:liter, 1)
Cldr.Unit.new!(:pint, "10.56688209432593661519599687")
iex> Cldr.Unit.mult Cldr.Unit.new!(:pint, 5), Cldr.Unit.new!(:pint, 1)
Cldr.Unit.new!(:pint, 5)
Multiplies two compatible Cldr.Unit.t/0
types
and raises on error.
Rounds the value of a unit.
Subtracts two compatible Cldr.Unit.t/0
types.
Subtracts two compatible Cldr.Unit.t/0
types
and raises on error.
Truncates a unit's value.
Types
@type rounding_mode() ::
:down | :up | :ceiling | :floor | :half_even | :half_up | :half_down
Functions
@spec add(Cldr.Unit.t(), Cldr.Unit.t()) :: Cldr.Unit.t() | {:error, {module(), String.t()}}
Adds two compatible Cldr.Unit.t/0
types
Arguments
unit_1
andunit_2
are compatible Units returned byCldr.Unit.new/2
.
Returns
A
Cldr.Unit.t/0
of the same type asunit_1
with a value that is the sum ofunit_1
and the potentially convertedunit_2
, or{:error, {IncompatibleUnitError, message}}
.
Examples
iex> Cldr.Unit.Math.add Cldr.Unit.new!(:foot, 1), Cldr.Unit.new!(:foot, 1)
Cldr.Unit.new!(:foot, 2)
iex> Cldr.Unit.Math.add Cldr.Unit.new!(:foot, 1), Cldr.Unit.new!(:mile, 1)
Cldr.Unit.new!(: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"}}
@spec add!(Cldr.Unit.t(), Cldr.Unit.t()) :: Cldr.Unit.t() | no_return()
Adds two compatible Cldr.Unit.t/0
types
and raises on error.
Arguments
unit_1
andunit_2
are compatible Units returned byCldr.Unit.new/2
.
Returns
A
Cldr.Unit.t/0
of the same type asunit_1
with a value that is the sum ofunit_1
and the potentially convertedunit_2
orRaises an exception.
@spec compare(unit_1 :: Cldr.Unit.t(), unit_2 :: Cldr.Unit.t()) :: :eq | :lt | :gt
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
@spec div(Cldr.Unit.t(), Cldr.Unit.t()) :: Cldr.Unit.t()
Divides any Cldr.Unit.t/0
type into another or a
number into a Cldr.Unit.t/0
.
Options
unit_1
is a unit returned byCldr.Unit.new/2
.unit_2
is a unit returned byCldr.Unit.new/2
or a number or Decimal.
Returns
- A
Cldr.Unit.t/0
of a type that is the dividend ofunit_1
andunit_2
with a value that is the dividend ofunit_1
andunit_2
's values.
Examples
iex> Cldr.Unit.Math.div Cldr.Unit.new!(:kilogram, 5), Cldr.Unit.new!(:pound, 1)
Cldr.Unit.new!(:kilogram, "11.02311310924387903614869007")
iex> Cldr.Unit.Math.div Cldr.Unit.new!(:pint, 5), Cldr.Unit.new!(:liter, 1)
Cldr.Unit.new!(:pint, "2.365882365000000000000000000")
iex> Cldr.Unit.Math.div Cldr.Unit.new!(:pint, 5), Cldr.Unit.new!(:pint, 1)
Cldr.Unit.new!(:pint, 5)
@spec div!(Cldr.Unit.t(), Cldr.Unit.t()) :: Cldr.Unit.t()
Divides one Cldr.Unit.t/0
type into another.
Any unit can be divided by another.
Arguments
unit_1
is a unit returned byCldr.Unit.new/2
.unit_2
is a unit returned byCldr.Unit.new/2
or a number or Decimal.
Returns
A
Cldr.Unit.t/0
of the same type asunit_1
with a value that is the dividend ofunit_1
and the potentially convertedunit_2
orRaises an exception.
@spec mult(Cldr.Unit.t(), Cldr.Unit.t()) :: Cldr.Unit.t()
Multiplies any two Cldr.Unit.t/0
types or a t:Cldr.Unit.t/0and a scalar. ## Arguments *
unit_1is a unit returned by
Cldr.Unit.new/2. *
unit_2is a unit returned by
Cldr.Unit.new/2or a number or Decimal. ## Returns * A
t:Cldr.Unit.t/0of a type that is the product of
unit_1and
unit_2with a value that is the product of
unit_1and
unit_2`'s
values.
## Examples
iex> Cldr.Unit.mult Cldr.Unit.new!(:kilogram, 5), Cldr.Unit.new!(:pound, 1)
Cldr.Unit.new!(:kilogram, "2.26796185")
iex> Cldr.Unit.mult Cldr.Unit.new!(:pint, 5), Cldr.Unit.new!(:liter, 1)
Cldr.Unit.new!(:pint, "10.56688209432593661519599687")
iex> Cldr.Unit.mult Cldr.Unit.new!(:pint, 5), Cldr.Unit.new!(:pint, 1)
Cldr.Unit.new!(:pint, 5)
@spec mult!(Cldr.Unit.t(), Cldr.Unit.t()) :: Cldr.Unit.t()
Multiplies two compatible Cldr.Unit.t/0
types
and raises on error.
Options
unit_1
is a unit returned byCldr.Unit.new/2
.unit_2
is a unit returned byCldr.Unit.new/2
or a number or Decimal.
Returns
A
Cldr.Unit.t/0
of the same type asunit_1
with a value that is the product ofunit_1
and the potentially convertedunit_2
orRaises an exception.
@spec round( unit :: Cldr.Unit.t() | number() | Decimal.t(), places :: non_neg_integer(), mode :: rounding_mode() ) :: Cldr.Unit.t() | number() | Decimal.t()
Rounds the value of a unit.
Arguments
unit
is any unit returned byCldr.Unit.new/2
places
is the number of decimal places to round to. The default is0
.mode
is the rounding mode to be applied. The default is:half_up
.
Returns
- A
%Unit{}
of the same type asunit
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.new!(:yard, "1031.6")
iex> Cldr.Unit.round Cldr.Unit.new!(:yard, 1031.61), 2
Cldr.Unit.new!(:yard, "1031.61")
iex> Cldr.Unit.round Cldr.Unit.new!(:yard, 1031.61), 1, :up
Cldr.Unit.new!(:yard, "1031.7")
@spec sub(Cldr.Unit.t(), Cldr.Unit.t()) :: Cldr.Unit.t() | {:error, {module(), String.t()}}
Subtracts two compatible Cldr.Unit.t/0
types.
Arguments
unit_1
andunit_2
are compatible Units returned byCldr.Unit.new/2
.
Returns
A
Cldr.Unit.t/0
of the same type asunit_1
with a value that is the difference betweenunit_1
and the potentially convertedunit_2
, or{:error, {IncompatibleUnitError, message}}
.
Examples
iex> Cldr.Unit.sub Cldr.Unit.new!(:kilogram, 5), Cldr.Unit.new!(:pound, 1)
Cldr.Unit.new!(:kilogram, "4.54640763")
iex> Cldr.Unit.sub Cldr.Unit.new!(:pint, 5), Cldr.Unit.new!(:liter, 1)
Cldr.Unit.new!(:pint, "2.886623581134812676960800627")
iex> Cldr.Unit.sub Cldr.Unit.new!(:pint, 5), Cldr.Unit.new!(:pint, 1)
Cldr.Unit.new!(:pint, 4)
@spec sub!(Cldr.Unit.t(), Cldr.Unit.t()) :: Cldr.Unit.t() | no_return()
Subtracts two compatible Cldr.Unit.t/0
types
and raises on error.
Arguments
unit_1
andunit_2
are compatible Units returned byCldr.Unit.new/2
.
Returns
A
Cldr.Unit.t/0
of the same type asunit_1
with a value that is the difference betweenunit_1
and the potentially convertedunit_2
orRaises an exception.
Truncates a unit's value.