Michael Robinton > Math-Base-Convert-0.08 > Math::Base::Convert

Download:
Math-Base-Convert-0.08.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.08   Source  

NAME ^

Math::Base::Convert - very fast base to base conversion

SYNOPSIS ^

As a function

  use Math::Base::Convert qw( :all )
  use Math::Base::Convert qw( 

        cnv
        cnvabs
        cnvpre
        basemap

                        # comments
        bin             base 2 0,1
        dna             base 4 lower case dna
        DNA             base 4 upper case DNA
        oct             base 8 octal
        dec             base 10 decimal
        hex             base 16 lower case hex
        HEX             base 16 upper case HEX
        b62             base 62
        b64             base 64 month:C:12 day:V:31
        m64             base 64 0-63 from MIME::Base64
        iru             base 64 P10 protocol - IRCu daemon
        url             base 64 url with no %2B %2F expansion of + - /
        rex             base 64 regular expression varient
        id0             base 64 IDentifier style 0
        id1             base 64 IDentifier style 1
        xnt             base 64 XML Name Tokens (Nmtoken)
        xid             base 64 XML identifiers (Name)
        b85             base 85 RFC 1924 for IPv6 addresses
        ascii           base 96 7 bit printible 0x20 - 0x7F
  );

  my $converted = cnv($number,optionalFROM,optionalTO);
  my $basemap = basmap(base);

As a method:

  use Math::Base::Convert;
  use Math::Base::Convert qw(:base);

  my $bc = new Math::Base::Convert(optionalFROM,optionalTO);
  my $converted = $bc->cnv($number);
  my $basemap = $bc->basemap(base);

DESCRIPTION ^

This module provides fast functions and methods to convert between arbitrary number bases from 2 (binary) thru 65535.

This module is pure Perl, has no external dependencies, and is backward compatible with old versions of Perl 5.

PREFERRED USE ^

Setting up the conversion parameters, context and error checking consume a significant portion of the execution time of a single base conversion. These operations are performed each time cnv is called as a function.

Using method calls eliminates a large portion of this overhead and will improve performance for repetitive conversions. See the benchmarks sub-directory in this distribution.

BUILT IN NUMBER SETS ^

Number set varients courtesy of the authors of Math::Base:Cnv and Math::BaseConvert.

The functions below return a reference to an array

  $arrayref     = function;

  bin => ['0', '1']                               # binary
  dna => ['a','t','c','g']                        # lc dna
  DNA => ['A','T','C','G'],     {default}         # uc DNA
  oct => ['0'..'7']                               # octal
  dec => ['0'..'9']                               # decimal
  hex => ['0'..'9', 'a'..'f']                     # lc hex
  HEX => ['0'..'9', 'A'..'F']   {default}         # uc HEX
  b62 => ['0'..'9', 'a'..'z', 'A'..'Z']           # base 62
  b64 => ['0'..'9', 'A'..'Z', 'a'..'z', '.', '_'] # m:C:12 d:V:31
  m64 => ['A'..'Z', 'a'..'z', '0'..'9', '+', '/'] # MIMI::Base64
  iru => ['A'..'Z', 'a'..'z', '0'..'9', '[', ']'] # P10 - IRCu
  url => ['A'..'Z', 'a'..'z', '0'..'9', '*', '-'] # url no %2B %2F
  rex => ['A'..'Z', 'a'..'z', '0'..'9', '!', '-'] # regex varient
  id0 => ['A'..'Z', 'a'..'z', '0'..'9', '_', '-'] # ID 0
  id1 => ['A'..'Z', 'a'..'z', '0'..'9', '.', '_'] # ID 1
  xnt => ['A'..'Z', 'a'..'z', '0'..'9', '.', '-'] # XML (Nmtoken)
  xid => ['A'..'Z', 'a'..'z', '0'..'9', '_', ':'] # XML (Name)
  b85 => ['0'..'9', 'A'..'Z', 'a'..'z', '!', '#', # RFC 1924
          '$', '%', '&', '(', ')', '*', '+', '-', 
          ';', '<', '=', '>', '?', '@', '^', '_', 
          '', '{', '|', '}', '~']
  An arbitrary base 96 composed of printable 7 bit ascii
  from 0x20 (space) through 0x7F (tilde ~)
  ascii => [
        ' ','!','"','#','$','%','&',"'",'(',')',
        '*','+',',','-','.','/',
        '0','1','2','3','4','5','6','7','8','9',
        ':',';','<','=','>','?','@',
        'A','B','C','D','E','F','G','H','I','J','K','L','M',
        'N','O','P','Q','R','S','T','U','V','W','X','Y','Z',
        '[','\',']','^','_','`',
        'a','b','c','d','e','f','g','h','i','j','k','l','m',
        'n','o','p','q','r','s','t','u','v','w','x','y','z',
        '{','|','}','~']

  NOTE: Clean text with =~ s/\s+/ /; before applying to ascii

USAGE ^

BENCHMARKS ^

Math::Base::Convert includes 2 development and one real world benchmark sequences included in the test suite. Benchmark results for a 500mhz system can be found in the 'benchmarks' source directory.

  make test BENCHMARK=1

Provides comparison data for bi-directional conversion of an ascending series of number strings in all base powers. The test sequence contains number strings that go from a a single 32 bit register to several. Tested bases are: (note: b32, b128, b256 not useful and are for testing only)

    base 2    4    8    16   32   64   85   128   256
        bin, dna, oct, hex, b32, b64, b85, b128, b256

Conversions are performed FROM all bases TO decimal and are repeated in the opposing direction FROM decimal TO all bases.

Benchmark 1 results indicate the Math::Base::Convert typically runs significantly faster ( 10x to 100x) than Math::BigInt based implementations used in similar modules.

  make test BENCHMARK=2

Provides comparison data for the frontend and backend converters in Math::Base::Convert's CalcPP and Shortcuts packages, and Math::Bigint conversions if it is present on the system under test.

  make test BENCHMARK=3

Checks the relative timing of short and long number string conversions. FROM a base number to n*32 bit register and TO a base number from an n*32 bit register set.

i.e. strings that convert to and from 1, 2, 3... etc.. 32 bit registers

DEPENDENCIES ^

        none

        Math::BigInt is conditionally used in
        the test suite but is not a requirement

EXPORT_OK ^

Conditional EXPORT functions

        cnv
        cnvabs
        cnvpre
        basemap
        bin
        oct
        dec
        heX
        HEX
        b62
        b64
        m64
        iru
        url
        rex
        id0
        id1
        xnt
        xid
        b85
        ascii

EXPORT_TAGS ^

Conditional EXPORT function groups

        :all    => all of above
        :base   => all except 'cnv,cnvabs,cnvpre'

ACKNOWLEDGEMENTS ^

This module was inspired by Math::BaseConvert maintained by Shane Warden <chromatic@cpan.org> and forked from Math::BaseCnv, both authored by Pip Stuart <Pip@CPAN.Org>

AUTHOR ^

Michael Robinton, <miker@cpan.org>

COPYRIGHT ^

Copyright 2012-2014, Michael Robinton

This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

syntax highlighting: