## README.md

```
# Convertat
*Convertat* is a small Elixir library that provides functions for converting
values **from** and **to** arbitrary bases.
## Installation
To use this library with Mix, just declare its dependency in the `mix.exs` file:
``` elixir
defp deps do
[
# Using the hex package manager:
{:convertat, "~> 1.0"},
# or grabbing the latest version (master branch) from GitHub:
{:convertat, github: "whatyouhide/convertat"},
]
end
```
Then run `mix deps.get` and go on with your life.
## Usage
Convertat leverages on the power of the `|>` operator in order to provide a
clean syntax for converting values between bases.
For example, say we want to convert the binary value `"11011"` (27 in base 10)
to its hex representation:
``` elixir
"10110" |> Convertat.from_base(2) |> Convertat.to_base(16) #=> "1b"
```
That's pretty straightforward and, moreover, easily achievable using Elixir's
standard library. In fact, when using integers as bases, you're limited to the
standard `2..36` range. What about this:
``` elixir
"↑↓↑" |> Convertat.from_base(["↓", "↑"]) #=> 5
```
We just used a (*binary*, since it has two digits) base where the digits are the
`↓` and `↑` characters.
Digits in list bases are listed from the least significant one to the most
significant one; in the above example, `↓` would be 0 in the binary base while
`↑` would be 1.
We can also use lists as values (instead of strings); this allows for some cool
multicharacter-digits bases. Here's another binary base:
``` elixir
["foo", "bar"] |> Convertat.from_base(["bar", "foo"]) #=> 2
```
As you can see, digits significance in list values is the opposite from list
bases: the least significant digits are on the right, like they would be in
written numbers.
As you just saw, the `from_base` function converts a value in an arbitrary base
to an integer in base 10. The `to_base` functions does the opposite: it converts
an integer (in base 10) into a value in an arbitrary base.
``` elixir
20 |> Convertat.to_base(["a", "b"]) #=> "babaa"
```
As with `from_base`, bases can be integers (in the `2..36` range, just like with
the standard library) or lists of digits.
By default, a string representation of the converted number is returned. You
can also specify that you want a list:
``` elixir
16 |> Convertat.to_base(16, as_list: true) #=> "10"
```
This may seem useless, but think of the multichar-digits base from above:
``` elixir
2 |> Convertat.to_base(["bar", "foo"]) #=> "foobar"
```
How can you parse `"foobar"` back into a base 10 value with the same `["bar",
"foo"]` base?
``` elixir
base = ["bar", "foo"]
val = 2 |> Convertat.to_base(base, as_list: true) #=> val = ["foo", "bar"]
val |> Convertat.from_base(base) #=> 2
```
## License
MIT © 2014 Andrea Leopardi, see [the license file](LICENSE.txt)
```