Home

Awesome

Convertat

Build Status Coverage Status Package License

Convertat is a small Elixir library that provides functions for converting values from and to arbitrary bases.

Installation and docs

To use this library with Mix, just declare its dependency in the mix.exs file:

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. The documentation for the current and the older versions of Convertat can be found on its hex.pm page.

Usage

Convertat leverages on the power of the |> operator in order to provide a clean syntax for converting values between bases. The only two functions that it exports are Convertat.from_base/2 and Convertat.to_base/3.

For example, say we want to convert the binary value "11011" (27 in base 10) to its hex representation:

iex> "10110" |> Convertat.from_base(2) |> Convertat.to_base(16)
"1b"

That's pretty straightforward and, moreover, easily achievable using Elixir's standard library (String.to_integer/2 and to_string/1). In fact, when using integers as bases, you're limited to the standard 2..36 range.

What about this:

iex> "↑↓↑" |> Convertat.from_base(["↓", "↑"])
5

We just used a binary (it has two digits) base where the digits are the "↓" and "↑" strings.

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:

iex> ["foo", "bar"] |> Convertat.from_base(["bar", "foo"])
2

As you can see, digits significance in list values is the opposite from bases: the least significant digits are on the right, like they would be in written numbers.

While the from_base/2 function converts a value in an arbitrary base to an integer in base 10, the to_base/3 function does the opposite:

iex> 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:

iex> 16 |> Convertat.to_base(16, as_list: true)
["1", "0"]

This may seem useless, but think of the multichar-digits base from above:

iex> 2 |> Convertat.to_base(["bar", "foo"])
"foobar"

How can you parse "foobar" back into a base 10 value with the same ["bar", "foo"] base?

iex> base = ["bar", "foo"]
["bar", "foo"]
iex> val = 2 |> Convertat.to_base(base, as_list: true)
["foo", "bar"]
iex> val |> Convertat.from_base(base)
2

One more thing: if you're converting between bases a lot of times, consider importing the two functions for a uber-clean syntax:

iex> import Convertat, only: :functions
nil
iex> "1011" |> from_base(2) |> to_base(16)
"b"

Contributing

If you wish to contribute to this project, well, thanks! You know the deal:

Feel free to open an issue if you find something wrong with the library.

License

MIT © 2014 Andrea Leopardi, see the license file