Abacus v1.0.0 Abacus

Abacus is a tool to simplify the handling of units.

For example :

# This module is used during the documentation to 
# show some examples.

defmodule AbacusTest.Length do 
  use Abacus.SystemMetric

  # :cm is the unit used as a reference in the metric system 'Length'
  unit :cm 
  unit :mm, (1/10)
  unit :dm, 10
  unit :m,  100
  unit :km, 100000

end

This module provides functions for referencing a metric type:

Length.cm/0
Length.mm/0
Length.dm/0
Length.m/0
Length.km/0

and to create a value enclosed in a metric system:

Length.cm/1
Length.mm/1
Length.dm/1
Length.m/1
Length.km/1

Here is an example of using Abacus :

a_distance = Length.cm(12)
a_distance_in_km = Abacus.from(a_distance, to: Length.km)

A metric_type is defined by a module and a subtype. For example Length and :cm.

Summary

Types

comparison_result()

This type represents a results of a comparison

metric_type()

This type represents a unit of measure (defined with using Abacus.SystemMetric)

typed_value()

This type represents a value wrapped in a metric system

Functions

add(a, b)

Makes the addition between two typed_value() of the same metric system. The return value will have the subtype of the left typed_value()

compare(left, list)

Comparison between two typed_value() of the same metric system

div(a, b)

Divides a typed_value() by a number(). The subtype of the return value will be the subtype of the left typed_value()

fold(list, default, f, list)

List.foldl for a list of typed_value() from the same metric system

from(arg, list)

Converts a typed_value() to another subtype of its metric system

map(arg, f)

Applies a function to the numeric value of a typed value and re-packs the result of the function in the same subtype

map2(arg1, elt2, f)

Applies a function to the two numeric values of two typed_values() in the same metric system, and re-packages the result of the function in a typed_value() of the subtype of the left typed_values()

mult(a, b)

Multiplies a typed_value() by a number(). The subtype of the return value will be the subtype of the left typed_value()

sub(a, b)

Makes the subtraction between two typed_value() of the same metric system. The return value will have the subtype of the left typed_value()

sum(list, list)

Calculates the sum of a list of typed_value() of the same metric system, projected into a specific subtype

unwrap(arg)

Retrieves the wrapped numeric value in a typed_value()

Types

comparison_result()

comparison_result() :: :eq | :lt | :gt

This type represents a results of a comparison

metric_type()

metric_type() :: {module, atom, number}

This type represents a unit of measure (defined with using Abacus.SystemMetric)

typed_value()

typed_value() :: {metric_type, float}

This type represents a value wrapped in a metric system

Functions

add(a, b)

add(typed_value, typed_value) :: typed_value

Makes the addition between two typed_value() of the same metric system. The return value will have the subtype of the left typed_value().

iex> a = AbacusTest.Length.cm(12)
...> b = AbacusTest.Length.m(2)
...> Abacus.add(a, b)
{AbacusTest.Length.cm, 212.0}

compare(left, list)

compare(typed_value, [{:with, typed_value}]) :: comparison_result

Comparison between two typed_value() of the same metric system.

The function returns:

:eq for equals
:lt if the left-values is lower than the right-values
:gt if the left-values is greater than the right-values

For example:

iex> x = AbacusTest.Length.m(1)
...> y = AbacusTest.Length.cm(100)
...> Abacus.compare(x, with: y)
:eq

div(a, b)

div(typed_value, number) :: typed_value

Divides a typed_value() by a number(). The subtype of the return value will be the subtype of the left typed_value().

iex> a = AbacusTest.Length.cm(12)
...> Abacus.div(a, 2)
{AbacusTest.Length.cm, 6.0}

fold(list, default, f, list)

fold([typed_value], any, (typed_value, any -> any), [{:to, metric_type}]) :: any

List.foldl for a list of typed_value() from the same metric system.

For example:

iex> Abacus.fold(
...>   [
...>       AbacusTest.Length.cm(10), 
...>       AbacusTest.Length.dm(1), 
...>       AbacusTest.Length.m(12)
...>   ],
...>   AbacusTest.Length.cm(12),
...>   fn(x, acc) -> Abacus.map2(x, acc, &(&1+&2)) end,
...>   to: AbacusTest.Length.cm
...>)
{AbacusTest.Length.cm, 1232.0}

from(arg, list)

from(typed_value, [{:to, metric_type}]) :: typed_value

Converts a typed_value() to another subtype of its metric system.

For example:

iex> x = AbacusTest.Length.cm(120)
...> Abacus.from(x, to: AbacusTest.Length.m)
{AbacusTest.Length.m, 1.2}

map(arg, f)

map(typed_value, (number -> number)) :: typed_value

Applies a function to the numeric value of a typed value and re-packs the result of the function in the same subtype.

For example:

iex> AbacusTest.Length.km(120)
...> |> Abacus.map(fn(x) -> x * 2 end)
{AbacusTest.Length.km, 240.0}

map2(arg1, elt2, f)

map2(typed_value, typed_value, (number, number -> number)) :: typed_value

For example:

iex> a = AbacusTest.Length.dm(100)
...> b = AbacusTest.Length.dm(2)
...> Abacus.map2(a, b, &(&1 * &2))
{AbacusTest.Length.dm, 200.0}

mult(a, b)

mult(typed_value, number) :: typed_value

Multiplies a typed_value() by a number(). The subtype of the return value will be the subtype of the left typed_value().

iex> a = AbacusTest.Length.cm(12)
...> Abacus.mult(a, 10)
{AbacusTest.Length.cm, 120.0}

sub(a, b)

sub(typed_value, typed_value) :: typed_value

Makes the subtraction between two typed_value() of the same metric system. The return value will have the subtype of the left typed_value().

iex> a = AbacusTest.Length.cm(12)
...> b = AbacusTest.Length.m(2)
...> Abacus.sub(b, a)
{AbacusTest.Length.m, 1.88}

sum(list, list)

sum([typed_value], [{:to, metric_type}]) :: typed_value

Calculates the sum of a list of typed_value() of the same metric system, projected into a specific subtype.

For example:

iex> Abacus.sum(
...>   [
...>       AbacusTest.Length.cm(10), 
...>       AbacusTest.Length.dm(1), 
...>       AbacusTest.Length.m(12)
...>   ], 
...>   to: AbacusTest.Length.dm
...> )
{AbacusTest.Length.dm, 122.0}

unwrap(arg)

unwrap(typed_value) :: number

Retrieves the wrapped numeric value in a typed_value().

For example:

iex> x = AbacusTest.Length.cm(12)
...> Abacus.unwrap(x)
12.0