# ExUc - Elixir Unit Converter

Converts values between units.

## Installation

From [Hex](https://hexdocs.pm/ex_uc), the package can be installed as:

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

    ```elixir
    def deps do
      [{:ex_uc, "~> 0.1.0"}]
    end
    ```

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

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

## Usage

The quickest way is with the function `convert`:
```elixir
iex>ExUc.convert("5 pounds", "oz")
"80.00 oz"
```
This is just a shortcut in the 3 steps pipeline:
```elixir
import ExUc

new_val = from("5 pounds")  # %ExUc.Value{unit: :lb, value: 5, kind: :mass}
|> to(:oz)                  # %ExUc.Value{unit: :oz, value: 80, kind: :mass}
|> as_string                # "80.00 oz"
```

### Errors

Only two errors are returned when found, both self descriptive **strings**:

  - `"undefined origin"`: Unit for the original value can't be parsed or found in the configuration.
  - `"undetermined conversion"`: Conversion between the given units can't be determined.


## Configuration

The only actually configurable variable is `precision`, by default is `2`. It determines only how many decimals will have the result when is converted to **string**.

### Adding more units

Every unit supported by **ExUc** is defined in a config file in _config/units/<KIND>.ex_, e.g. `config/units/temperature.ex`.

Each of these files requires to have the following structure:
```elixir
use Mix.Config

config :ex_uc, :<KIND>_units,
  <UNIT>: ["alias 1", "alias 2", "alias N"], # List with every alias intended to relate to unit identified by UNIT

config :ex_uc, :<KIND>_conversions,
  <UNIT_A>_to_<UNIT_B>: 0.001,      # Multiplication factor
  <UNIT_C>_to_<UNIT_D>: &(&1 + 5)   # Conversion formula.
  <UNIT_X>_to_<UNIT_Y>: :special    # Atom referencing a special method.  
```

Basically, two sections:

  - **Aliases**
    - Key as `<KIND>_units` where kind identifies the type of measurement, e.g: _length_, _temperature_, _pressure_, etc.
    - Each unit to support in the `kind` as a pair `unit:aliases` where **unit** is the most used unit and **aliases** is a list of strings (or a single one), one for each supported representation of the unit.
  - **Conversions**
    - Key as `<KIND_conversions>` using the same **kind** from the **alias** section.
    - Each conversion as a pair `key:conversion`, where **key** is an atom with the pattern `<UNIT_FROM>_to_<UNIT_TO>`, and **conversion** could be a _number_, or a _closure_, or an _atom_. Numeric conversions describe multiplication factors, and can be also used as `<B>_to_<A>: 1 / conversion` for a `<A>_to_<B>: factor` without explicit definition. When a factor is not enough, a _closure_ can be used as a simple formula. For special cases use an _atom_ to describe a function in module `Special`.

## Documentation

Detailed documentation can be found at [hex docs](https://hexdocs.pm/ex_uc).

## Note

This project was inspired by the awesome [Ruby gem](https://github.com/olbrich/ruby-units) by _Kevin C. Olbrich, Ph.D._

## License

[MIT](https://github.com/carturoch/ex_uc/blob/master/License.md)