NAME

Encode::Base32::GMP - High speed Base32 encoding using GMP with BigInt and MD5 support

SYNOPSIS

  use Encode::Base32::GMP;

  # Encode Int as Base32
  encode_base32(12345);                        # => C1S string
  encode_base32('0x3039');                     # => C1S string
  encode_base32(Math::GMPz->new('0x3039'));    # => C1S string

  # Encode Int as Base32 using GMP alphabet
  encode_base32(12345,'rfc4648');              # => MBZ string
  encode_base32(12345,'zbase32');              # => CB3 string
  encode_base32(12345,'base32hex');            # => C1P string
  encode_base32(12345,'gmp');                  # => C1P string

  # Decode Base32 as Math::GMPz Int
  decode_base32('C1S');                        # => 12345 Math::GMPz object
  int decode_base32('C1S');                    # => 12345 integer

  # Decode Base32 as Math::GMPz Int using normaliztion (built-in)
  decode_base32('c1s');                        # => 12345 Math::GMPz object
  decode_base32('cis');                        # => 12345 Math::GMPz object

  # Decode Base32 as Math::GMPz Int using GMP alphabet
  decode_base32('MBZ','rfc4648');              # => 12345 Math::GMPz object
  decode_base32('CB3','zbase32');              # => 12345 Math::GMPz object

  # MD5 Base32 Digest
  md5_base32('foo@bar.com');                   # => 7KNPJ0BKM91DQR41099QNH5P58

  # Convert between alphabets, e.g. Crockford and RFC-4648
  base32_from_to('0123456789ABCDEFGHJKMNPQRSTVWXYZ','crockford','rfc4648');
    # => ABCDEFGHIJKLMNOPQRSTUVWXYZ234567
  base32_from_to('ABCDEFGHIJKLMNOPQRSTUVWXYZ234567','rfc4648','zbase32');
    # => YBNDRFG8EJKMCPQXOT1UWISZA345H769

DESCRIPTION

Encode::Base32::GMP is a numerical Base32 encoder/decoder implementation using the GNU Multiple Precision Arithmetic Library (GMP) with transcoding between Crockford, RFC 4648, z-base-32, and Base32hex / GMP implementations. The Crockford alphabet is the default and used when no alphabet is provided. Crockford was selected as the default because it extends hexadecimal more naturally than other alphabets and it is easier to distinguish visually.

  crockford: [0123456789ABCDEFGHJKMNPQRSTVWXYZ]
  rfc4648:   [ABCDEFGHIJKLMNOPQRSTUVWXYZ234567]
  zbase32:   [YBNDRFG8EJKMCPQXOT1UWISZA345H769]
  base32hex: [0123456789ABCDEFGHIJKLMNOPQRSTUV]
  gmp:       [0123456789ABCDEFGHIJKLMNOPQRSTUV]

The encode_base32, decode_base32 and md5_base32 methods support an alphabet parameter which can be set to the supported alphabets to indicate the value to be encoded or decoded:

  [qw/crockford rfc4648 base32hex zbase32 gmp/]

This module functions similarly to Encode::Base58::GMP with Base32 being ideal for case-insensitive encoding and Base58 being ideal for case-sensitive encoding.

FUNCTIONS

encode_base32 ( $number [, $alphabet ] )

This routine encodes a $number in Base32. $number can be a Math::GMPz object or a binary, octal, decimal or hexidecimal number. Binary, octal and hexidecimal string literals must be prefixed with 0[Bb]/0/0[Xx] respectively. The resulting Base32 encoded number is provided in upper case per Crockford and RFC-4648 definitions. The Crockford alphabet is used unless $alphabet is set.

decode_base32( $base32 [, $alphabet ] )

This routine decodes a Base32 value and returns a Math::GMPz object. Use int on the return value to convert the Math::GMPz object to an integer. The input can be upper or lower case. Crockford and RFC-4648 inputs are normalized exchanging the set [01ilo] as necessary. The Crockford alphabet is used unless $alphabet is set.

base32_from_to( $base32, $from_alphabet, $to_alphabet )

This routine encodes a Base32 string from one encoding to another encoding. The input can be upper or lower case. Crockford and RFC-4648 inputs are normalized exchanging the set [01ilo] as necessary. The resulting Base32 encoded number is provided in upper case per Crockford and RFC-4648 definitions. This routing is not exported by default.

md5_base32( $data [, $alphabet ] )

This routine returns a MD5 digest in Base32. This routine is not exported by default.

NOTE

This module is designed to encode and decode numbers. As such, it is backward compatible with Encode::Base32::Crockford while also adding BigInt support.

While this module can be used to transcode other Base32 encodings, this module is not designed to encode and decode binary strings, for which Convert::Base32, Convert::Base32::Crockford, and MIME::Base32 can be used. These modules also result in different and longer encodings for numbers which is not desirable when encoding digests and other uids.

AUTHOR

John Wang <johncwang@gmail.com>, <http://johnwang.com>

COPYRIGHT

This software is released under the MIT license cited below.

COPYRIGHT AND LICENSE (The MIT License)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.