``````# Numbers

**Numbers** is a tiny Elixir package that facilitates the creation of libraries
that want to be able to use _any_ kind of Numeric type.

Some known custom numeric types that implement the Numeric behaviour:

- [Ratio](https://hex.pm/packages/ratio) -- rational numbers.
- [Decimal](https://hex.pm/packages/decimal) -- arbitrary precision decimal numbers.
- [Tensor](https://hex.pm/packages/tensor) -- Vectors, Matrices and higher-order tensors.
- [ComplexNum](https://github.com/Qqwy/elixir_complex_num) -- Complex numbers.

## How does it work?

This is done by writing a Behaviour called `Numeric`, which standardizes the names of the following common mathematical operations:

- `new` to create a new number of the custom type from a basic integer or float (which be an operation that loses precision).
- `sub` for subtraction.
- `mul` for multiplication.
- `div` for division.
- `minus` for unary minus (also known as negation).
- `abs` for taking the absolute value.
- `pow` _(optional)_ for calculating integer powers. When no custom algorithm is specified by the data type, Numbers will provide a (possibly slower) variant itself using the Exponentiation by Squaring algorithm.
- `to_float` _(optional)_ For some Numeric data types it is possible to convert it back to a built-in datatype (possibly losing precision in the process).

The `Numbers` module then dispatches these functions to YourStructModule when called with a `%YourStructModule{}` struct as one or both of its arguments.
If the other argument is a Float or Integer, then it is first converted to an instance of YourStruct by calling `YourStructModule.new(the_int_or_float)` on it.

## Examples:

Using built-in numbers:
```
iex> alias Numbers, as: N

3

iex> N.mul(3,5)
15

iex> N.mul(1.5, 100)
150.0
```

Using Decimals: (requires the [Decimal](https://hex.pm/packages/decimal) library.)
```
iex> d = Decimal.new(2)
iex> N.div(d, 10)
#Decimal<0.2>
iex> small_number = N.div(d, 1234)
#Decimal<0.001620745542949756888168557536>
iex> N.pow(small_number, 100)

```

## Installation

The package can be installed as:

1. Add `number` to your list of dependencies in `mix.exs`:

```elixir
def deps do
[{:number, "~> 2.0.0"}]
end
```

2. Ensure `number` is started before your application:

```elixir
def application do
[applications: [:number]]
end
```

## Changelog

- 2.0.1 Fixing error message that is shown when conversion to float is not possible to use the Inspect protocol.
- 2.0.0 Breaking change, `mul` -> `mult`.
- 1.0.0 First Stable Version.
``````