Cldr Units

v2.5.1

Cldr Units

Cldr Units v2.5.1 Cldr.Unit.Math View Source

Simple arithmetic functions for the Unit.t type

Link to this section Summary

Functions

add(unit_1, unit_1)

Adds two compatible %Unit{} types

add!(unit_1, unit_2)

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

cmp(unit_1, unit_2)

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

div(unit_1, unit_1)

Divides one compatible %Unit{} type by another

div!(unit_1, unit_2)

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

mult(unit_1, unit_1)

Multiplies two compatible %Unit{} types

mult!(unit_1, unit_2)

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

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

Rounds the value of a unit.

sub(unit_1, unit_1)

Subtracts two compatible %Unit{} types

sub!(unit_1, unit_2)

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

trunc(unit)

Link to this section Functions

Link to this function

add(unit_1, unit_1) View Source 
add(Cldr.Unit.t(), Cldr.Unit.t()) ::
  Cldr.Unit.t() | {:error, {module(), String.t()}}

Adds two compatible %Unit{} types

Options

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)
#Unit<:foot, 2>

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

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 of the same type. Received #Unit<:foot, 1> and #Unit<:gallon, 1>"}}
Link to this function

add!(unit_1, unit_2) View Source 
add!(Cldr.Unit.t(), Cldr.Unit.t()) :: Cldr.Unit.t() | no_return()

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

Options

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

Link to this function

cmp(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.cmp x, y
:eq
Link to this function

div(unit_1, unit_1) View Source 
div(Cldr.Unit.t(), Cldr.Unit.t()) ::
  Cldr.Unit.t() | {:error, {module(), String.t()}}

Divides one compatible %Unit{} type by another

Options

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) #Unit<:kilogram, 11.023100000000001>

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

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

Link to this function

div!(unit_1, unit_2) View Source 
div!(Cldr.Unit.t(), Cldr.Unit.t()) :: Cldr.Unit.t() | no_return()

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

Options

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

Link to this function

mult(unit_1, unit_1) View Source 
mult(Cldr.Unit.t(), Cldr.Unit.t()) ::
  Cldr.Unit.t() | {:error, {module(), String.t()}}

Multiplies two compatible %Unit{} types

Options

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)
#Unit<:kilogram, 2.2679645471781984>

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

iex> Cldr.Unit.mult Cldr.Unit.new!(:pint, 5), Cldr.Unit.new!(:pint, 1)
#Unit<:pint, 5>
Link to this function

mult!(unit_1, unit_2) View Source 
mult!(Cldr.Unit.t(), Cldr.Unit.t()) :: Cldr.Unit.t() | no_return()

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

Options

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

Link to this function

round(unit, places \\ 0, mode \\ :half_up) View Source 
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
#Unit<:yard, 1031.6>

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

iex> Cldr.Unit.round Cldr.Unit.new(:yard, 1031.61), 1, :up
#Unit<:yard, 1031.7>
Link to this function

sub(unit_1, unit_1) View Source 
sub(Cldr.Unit.t(), Cldr.Unit.t()) ::
  Cldr.Unit.t() | {:error, {module(), String.t()}}

Subtracts two compatible %Unit{} types

Options

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)
#Unit<:kilogram, 4.54640709056436>

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

iex> Cldr.Unit.sub Cldr.Unit.new!(:pint, 5), Cldr.Unit.new!(:pint, 1)
#Unit<:pint, 4>
Link to this function

sub!(unit_1, unit_2) View Source 
sub!(Cldr.Unit.t(), Cldr.Unit.t()) :: Cldr.Unit.t() | no_return()

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

Options

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

Link to this function

trunc(unit) View Source