BaseX

BaseX is a arbitrary base conversion library that, in addition to converting to/from integers, also supports encoding and decoding arbitrary binary data into and out of any base.

Many known bases are included, such as Bitcoin Base58.

BaseX is useful for generating human-friendly cryptographic tokens and ID's, and could even be usde for encoding, transmitting, and decoding binary data over binary-unsafe mediums.

BaseX was constructed to back the HumanToken token generator.

Add this line to your application's Gemfile:

gem 'base_x'

And then execute:

$ bundle

Or install it yourself as:

$ gem install base_x

Let's convert some numbers.

# Emulate hex, just for fun.
BaseX.integer_to_string(241,  numerals: "0123456789abcdef")
# => "f1"
BaseX.string_to_integer("f1", numerals: "0123456789abcdef")
# => 241

# Bitcoin Base58 numerals. No O, 0, I, or l
BaseX.integer_to_string(456724510, numerals: "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz")
# => "hMqHX"
BaseX.string_to_integer("hMqHX",   numerals: "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz")
# => 456724510

# That was rather clumsy, so let's use the provided Base58 object
BaseX::Base58.integer_to_string(456724510)
# => "hMqHX"

If you use a base more than once, make it a constant.

Base24Greek = BaseX.new("αβγδεζηθικλμνξοπρστυφχψω")

Base24Greek.integer_to_string(456724510)
# => "ιψια"
Base24Greek.string_to_integer("ιψια")
# => 456724510

Use the encode and decode methods to convert arbitary binary data to and from the desired base.

BaseX::Base30L.encode("Hello World!")
# => "3xtzc85paptyrbdjgd27"
BaseX::Base30L.decode("3xtzc85paptyrbdjgd27")
# => "Hello World!"

BaseX.encode("SOS", numerals: "01")
# => "010100110100111101010011"
BaseX.decode("010100110100111101010011", numerals: "01")
# => "SOS"

The encoding scheme is simple: BaseX treats the whole binary blob as one large big-endian binary number and then converts that number into the desired base. If the original binary had leading 0 bytes, leading "0"'s are added to the converted number.

Base10 = BaseX.new("0123456789")

Base10.encode("Hi")         # => "18537"
Base10.encode("\x00Hi")     # => "00018537"
Base10.encode("\x00\x00Hi") # => "0000018537"

BaseX is great for generating tokens for identification or cryptographic purposes.

require 'securerandom'

bytes = SecureRandom.random_bytes(16) # 128 bits

BaseX::Base30L.encode(bytes)
# => "347wbrazxkvj59atq5zh2fdk55e"
BaseX::Base58.encode(bytes)
# => "SLrA71VABcvExTht6KLr89"

The HumanToken gem wraps BaseX to generate such tokens.

require 'human_token'

HumanToken.generate
# => "4f5wveesz5kkkpexxynpacjkhxd"
HumanToken.base_58
# => "n6FXaQYCEHnQgFPxHfddZL"

BaseX provides some bases you can use right away.

Note that although the number schemes from various standards are represented here, BaseX is a number converter only: it does not do padding or other standard-specific details. BaseX is not, for example, a Z85 compliant encoder/decoder. You could, however, easily build one with BaseX.

In Ruby, you can use BaseX.bases and BaseX.print_bases to get information similar to the above table.

> BaseX.print_bases
Binary          2   111111001000111000111… 01
Base16          16  fc8e3c917d58368b       0123456789abcdef
Base16L         16  fc8e3c917d58368b       0123456789abcdef
Base16U         16  FC8E3C917D58368B       0123456789ABCDEF
Hex             16  fc8e3c917d58368b       0123456789abcdef
Hexadecimal     16  fc8e3c917d58368b       0123456789abcdef
Base30L         30  369be5e68tfqth         23456789abcdefghjkmnpqrstvwxyz
...

In addition to the named constants above, you can also quickly generate any alphanumeric base between 2 and 62. This could be handy becuase Ruby's to_i and to_s methods only support bases 2 to 36.

BaseX.base(49).integer_to_string(456724510)
# => "1UB4UI"
BaseX.base(49).string_to_integer("1UB4UI")
# => 456724510

# The order of numerals is digits then uppercase then lowercase
BaseX.base(49).numerals
# => "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklm"

If you want your text to be transferred by any means other than copy-paste, I recommend BaseX::Base30L. Tokens have a bad habit of landing in places where they cannot be copied and pasted. Anecdotal evidence from my recent past:

• There was an infographic that had cited URLs baked into the image. I wanted to check the sources but could not copy the URLs, so I had to retype them. Also, some of the URLs had "O"'s in them.
• I recently transferred a shared secret from one computer to another "off the wire". I had my mother read the secret out loud from the other computer. Happily, the secret did not have mixed case: saying "capital L, lowercase u" would have doubled the tedium.

You can't predict what people are going to do with your encoded text, so it makes sense to be prepared.

Even though "".to_i is 0 in Ruby, BaseX's string_to_integer will reject empty strings with a BaseX::EmptyString error. An empty string here is probably a bug in your code. (In contrast, the encode and decode functions do accept empty strings.)

If you try to convert a string that uses a character not in the base, a BaseX::InvalidNumeral error will be raised.

If you try to encode/decode in a numeral system larger than base 256 (why would you do this?!), leading 0 bytes may not be properly preserved. Integer conversion will still work as expected.

Public Domain; no rights reserved.

No restrictions are placed on the use of BaseX. That freedom also means, of course, that no warrenty of fitness is claimed; use BaseX at your own risk.

This public domain dedication follows the the CC0 1.0 at https://creativecommons.org/publicdomain/zero/1.0/

1. Fork it ( http://github.com/brianhempel/base_x/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Run the tests with either guard or minitest
4. Commit your changes (git commit -am 'Add some feature')
5. Push to the branch (git push -u origin my-new-feature)
6. Create a new Pull Request