Unit Fun v0.5.3 UnitFun
Adds units to numbers in elixir to give some added type saftey when dealing with numeric quantities.
Summary
Functions
Adds together two values. If the units mismatch a conversion will be attempted if this isn’t possible an error will be raised
Raises an error unless the units are as asserted
Divides the left by the right. If either or both quantities have units new composite units will be created
Equality. Two values will only be considered equal if they have the same value and units. If the units can be converted in to one or another this will be attempted first. If the units do not match and they can’t be converted an error will be raised
Multiples two quantities together. If either or both quantities have units new composite units will be created
Subtracts one value from the other. If the units mismatch a conversion will be attempted if this isn’t possible an error will be raised
Takes a bare value and creates a quantitiy with units
Functions
Adds together two values. If the units mismatch a conversion will be attempted if this isn’t possible an error will be raised.
Examples
Plain values
iex> UnitFun.add(3, 7)
10
Matching units
iex> left = 3 |> UnitFun.with_units(UnitFun.Examples.SimpleUnit)
iex> right = 5 |> UnitFun.with_units(UnitFun.Examples.SimpleUnit)
iex> UnitFun.add(left, right).value
8
Mismatched units
iex> left = 3 |> UnitFun.with_units(UnitFun.Examples.SimpleUnit)
iex> right = 5 |> UnitFun.with_units(UnitFun.Examples.OtherUnit)
iex> UnitFun.add(left, right).value
** (UnitFun.Errors.MissingConversionError) No conversions into Elixir.UnitFun.Examples.SimpleUnit implemented
Raises an error unless the units are as asserted
Examples
valid assertion - no error thrown
iex> x = UnitFun.with_units(5, UnitFun.Examples.SimpleUnit)
iex> y = x |> UnitFun.assert_units(UnitFun.Examples.SimpleUnit)
iex> y.value
5
Returns false when values don’t have units
iex> 6 |> UnitFun.assert_units(UnitFun.Examples.SimpleUnit)
** (UnitFun.Errors.UnitAssertionError) Expected value with units Elixir.UnitFun.Examples.SimpleUnit; Got: 6
Divides the left by the right. If either or both quantities have units new composite units will be created.
Examples
Plain values
iex> UnitFun.divide(6, 3)
2.0
Both values have the same units
iex> left = 8 |> UnitFun.with_units(UnitFun.Examples.SimpleUnit)
iex> right = 2 |> UnitFun.with_units(UnitFun.Examples.SimpleUnit)
iex> UnitFun.divide(left, right)
4.0
Both values have units but they are different
iex> left = 8 |> UnitFun.with_units(UnitFun.Examples.SimpleUnit)
iex> right = 2 |> UnitFun.with_units(UnitFun.Examples.OtherUnit)
iex> answer = UnitFun.divide(left, right)
iex> simple_per_other_units = UnitFun.divide(UnitFun.Examples.SimpleUnit, UnitFun.Examples.OtherUnit)
iex> answer |> UnitFun.assert_units(simple_per_other_units)
iex> answer.value
4.0
Equality. Two values will only be considered equal if they have the same value and units. If the units can be converted in to one or another this will be attempted first. If the units do not match and they can’t be converted an error will be raised.
Examples
Plain values
iex> UnitFun.equal(5, 5)
true
Both values have the same value & units
iex> left = 6 |> UnitFun.with_units(UnitFun.Examples.SimpleUnit)
iex> right = 6 |> UnitFun.with_units(UnitFun.Examples.SimpleUnit)
iex> UnitFun.equal(left, right)
true
Both values have the same value but different units
iex> left = 6 |> UnitFun.with_units(UnitFun.Examples.SimpleUnit)
iex> right = 6 |> UnitFun.with_units(UnitFun.Examples.OtherUnit)
iex> UnitFun.equal(left, right)
** (UnitFun.Errors.CannotCompareError) Can't compare Elixir.UnitFun.Examples.SimpleUnit to Elixir.UnitFun.Examples.OtherUnit. No conversions into Elixir.UnitFun.Examples.SimpleUnit implemented
Multiples two quantities together. If either or both quantities have units new composite units will be created.
Examples
Plain values
iex> UnitFun.multiply(2, 3)
6
One united value and one plain number
iex> left = 5 |> UnitFun.with_units(UnitFun.Examples.SimpleUnit)
iex> right = 2
iex> answer = UnitFun.multiply(left, right)
iex> answer |> UnitFun.assert_units(UnitFun.Examples.SimpleUnit)
iex> answer.value
10
Both united numbers
iex> left = 5 |> UnitFun.with_units(UnitFun.Examples.SimpleUnit)
iex> right = 2 |> UnitFun.with_units(UnitFun.Examples.SimpleUnit)
iex> answer = UnitFun.multiply(left, right)
iex> square_units = UnitFun.multiply(UnitFun.Examples.SimpleUnit, UnitFun.Examples.SimpleUnit)
iex> answer |> UnitFun.assert_units(square_units)
iex> answer.value
10
Subtracts one value from the other. If the units mismatch a conversion will be attempted if this isn’t possible an error will be raised.
Examples
Plain values
iex> UnitFun.subtract(7, 3)
4
Matching units
iex> left = 5 |> UnitFun.with_units(UnitFun.Examples.SimpleUnit)
iex> right = 2 |> UnitFun.with_units(UnitFun.Examples.SimpleUnit)
iex> UnitFun.subtract(left, right).value
3
Mismatched units
iex> left = 5 |> UnitFun.with_units(UnitFun.Examples.SimpleUnit)
iex> right = 3 |> UnitFun.with_units(UnitFun.Examples.OtherUnit)
iex> UnitFun.subtract(left, right).value
** (UnitFun.Errors.MissingConversionError) No conversions into Elixir.UnitFun.Examples.SimpleUnit implemented
Takes a bare value and creates a quantitiy with units.
Examples
Plain values
iex> x = UnitFun.with_units(5, UnitFun.Examples.SimpleUnit)
iex> x |> UnitFun.assert_units(UnitFun.Examples.SimpleUnit)
iex> x.value
5
It will attempt to convert to new units but fail if a conversion isn’t defined
iex> x = UnitFun.with_units(5, UnitFun.Examples.SimpleUnit)
iex> y = UnitFun.with_units(x, UnitFun.Examples.OtherUnit)
** (UnitFun.Errors.MissingConversionError) No conversions into Elixir.UnitFun.Examples.OtherUnit implemented