base58_id

Base58Id

Convert Integer ID or UUID String to/from Base58 String; Generate random Base58 String

Install

Install it from rubygems.org in your terminal:

gem install base58_id

Or via Gemfile in your project:

source 'https://rubygems.org'

gem 'base58_id', '~> 1.2'

Or build and install the gem locally:

gem build base58_id.gemspec
gem install base58_id-1.2.0.gem

Require it in your Ruby code and the Base58Id class will be available:

require 'base58_id'

Alphabet

It is based on Base64 URL-safe alphabet but with I, O, l, 0, -, _ removed:

A B C D E F G H   J K L M N   P Q R S T U V W X Y Z
a b c d e f g h i j k   m n o p q r s t u v w x y z
  1 2 3 4 5 6 7 8 9

Examples

Converting

require 'base58_id'

Base58Id.uuid_to_base58('058917af-0d2e-4755-b0bd-25b02b249824')
# => "qocqGYw9LEfu4WVujMzJv"

Base58Id.base58_to_uuid('qocqGYw9LEfu4WVujMzJv')
# => "058917af-0d2e-4755-b0bd-25b02b249824"

Base58Id.uuid_to_integer('058917af-0d2e-4755-b0bd-25b02b249824')
# => 7357965012972427318415208560898381860

Base58Id.integer_to_uuid(7357965012972427318415208560898381860)
# => "058917af-0d2e-4755-b0bd-25b02b249824"

Base58Id.base58_to_integer('qocqGYw9LEfu4WVujMzJv')
# => 7357965012972427318415208560898381860

Base58Id.integer_to_base58(7357965012972427318415208560898381860)
# => "qocqGYw9LEfu4WVujMzJv"

Base58Id.valid_base58?('qocqGYw9LEfu4WVujMzJv')
# => true

Base58Id.valid_base58?('IOl0-_')
# => false

# It accepts UUID String in many formats:
[
  '058917af0d2e4755b0bd25b02b249824',
  '058917AF0D2E4755B0BD25B02B249824',
  '0x058917af0d2e4755b0bd25b02b249824',
].map { |uuid| Base58Id.valid_uuid?(uuid) }
# => [true, true, true]

Base58Id::UUID_PATTERN
# => /\A(0x)?[0-9a-f]{8}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{12}\z/i

Notes about zero

As it performs an integer conversion, Base58 leading zeros (represented by A) are ignored/lost:

require 'base58_id'

Base58Id.base58_to_integer('A') == Base58Id.base58_to_integer('AAAAAA')
# => true

Base58Id.base58_to_integer('AAAAAAqocqGYw9LEfu4WVujMzJv') ==
Base58Id.base58_to_integer('qocqGYw9LEfu4WVujMzJv')
# => true

Base58Id.integer_to_base58(Base58Id.base58_to_integer('AAAAAAqocqGYw9LEfu4WVujMzJv'))
# => "qocqGYw9LEfu4WVujMzJv"

And an empty Base58 String also represents zero:

require 'base58_id'

Base58Id.base58_to_integer('')
# => 0

Base58Id.base58_to_uuid('')
# => "00000000-0000-0000-0000-000000000000"

Base58Id.base58_to_integer('') == Base58Id.base58_to_integer('A')
# => true

Generating random Base58 number strings from Integers

require 'base58_id'

# Using the default range [0, 2^63 - 1]
Base58Id.random_number
# => "RvHTkxcYYJ4"

# With a custom max, i.e. [0, max)
Base58Id.random_number(100) # [0, 100)
# => "BW"

# With custom ranges
Base58Id.random_number(100..1_000) # [100, 1000]
# => "L2"
Base58Id.random_number(100...1_000) # [100, 1000)
# => "Qv"

Under the hood, the implementation just passes the max_or_range argument to SecureRandom.random_number and then the result to Base58Id.integer_to_base58:

require 'securerandom'
require 'base58_id'

class Base58Id
  # ...

  DEFAULT_RANDOM_RANGE = 0..(2**63 - 1)

  # ...

  def self.random_number(max_or_range = nil)
    max_or_range = DEFAULT_RANDOM_RANGE if max_or_range.nil?

    integer_to_base58(SecureRandom.random_number(max_or_range))
  end

  def self.rand(*args)
    random_number(*args)
  end
end

Generating random Base58 string digits

require 'base58_id'

# Using the default number of random digits, 10
Base58Id.random_digits
# => "EWcSDcga66"

# With a custom number of random digits
Base58Id.random_digits(42)
# => "YJn8u1UhkS9vt3YrWFPTXzMjzqFze7v2nWUbcdmnrU"

Tests

Run tests with:

bundle exec rspec

Linter

Check your code with:

bundle exec rubocop