This module provides data encoding and decoding functions for Base2.

Overview

Converting to and from Base2 is very simple in Elixir and Erlang. Unfortunately, most approaches use generic methodologies that are suitable for any Base, and thus do not optimize for any Base typically.

Working with Base2 is a relatively simple task chaining a few Elixir built-in functions or using a third-party generic “BaseX” type library, but most of these implementations leave a lot to be desired. Generally, most built-in methods and third-party libraries are often not very optimized. Using built-in functions also is not uniform with other ways of handling Bases such as via the Elixir Base module. Most of these methods are great for scratch work, but less suitable for bulk encoding and decoding. Further, the multiple ways of approaching different bases lead to very inconsistent interfaces, for instance Integer.to_string() vs. Base vs a third-party module with its own conventions.

Base2 includes the following functionality:

• Encodes and Decodes binaries as Base2.
• Consistent with the Base module interface design.
• Optionally preserves transparency encoding and decoding leading zeroes.

• Reasonably fast, because every library claims it is fast.

  • Faster than libraries that take generic approaches to encode any Base either via module generation or runtime alphabets
  • Faster than doing :binary.encode_unsigned("hello") |> Integer.to_string(2)
  • Faster than methods using power-based functions that can also overflow when using the BIF
  • Avoids the div/rem operation that is the source of many slowdowns, such as in Integer.to_string/2 and its wrapped :erlang.integer_to_binary/2
• Uses less memory than most other methods

• Option to remove extra padding if losing losing leading zeroes is desirable or wanted to produce smaller resulting binaries

  • Loses transparency

• Control over shape of output binary

  • Force padding always, only for leading zeroes, or return a smaller binary representation

Padding

Base2 allows full control over padding behavior when encoding a binary into a Base2 string.

There are three options for padding:

• :zeroes (default) - Allows zeroes to be padded to ensure transparent decode of leading zeroes.
• :all - Uniformly pads the data with zeroes. String length will always a multiple of 8 and fast, but at the cost of an increased output size.

• :none - Produces a smaller representation by dropping all leading zeroes, but at the cost of fully transparent decode if there are leading zeroes.

  :zeroes is good for general usage, while typically being smaller. Zeroes are fully padded to byte boundaries. Transparency is fully preserved.

  :all is good for uniformly working with Base2 string output. Transparency is fully preserved.

  :none exhibit the same behavior as methods such as Integer.to_string("hello", 2) that try to use a smaller representation. This method should be used with caution as it comes at a cost of transparency. Simply, if you want the exact same output when decoding as your input, do not use this option. If, however, you want the smallest representation, then it is a good choice.