Provided by: libmath-base-convert-perl_0.11-2_all bug

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 variant
               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 variants 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 variant
         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

       •   $converted = cnv($number,[from],[to])

           SCALAR context: array context covered later in this document.

           To preserve similarity to other similar base conversion modules, cnv returns the
           converted number string with SIGN if both the input and output base strings are in
           known signed set of bases in this module.

           In the case of binary, octal, hex, all leading base designator strings such as
           '0b','0', '0x' are automatically stripped from the input. Base designator strings are
           NOT applied to the output.

           The context of base FROM and TO is optional and flexible.

           Unconditional conversion from decimal to HEX [upper case]

                   $converted = cnv($number);

           Example conversion from octal to default HEX [upper case] with different context for
           the 'octal' designator.

             base as a number
                   $converted = cnv($number,8);

             base as a function    (imported)
                   $converted = cnv($number,oct);

             base as text
                   $converted = convbase($number,'oct');

           Conversion to/from arbitrary bases i.e.

             $converted = cnv($number); # dec -> hex (default)
             $converted = cnv($number,oct);        # oct to HEX
             $converted = cnv($number,10,HEX);     # dec to uc HEX
             $converted = cnv($number,10,hex);     # dec to lc hex
             $converted = cnv($number,dec,hex);#    same

                   pointer notation
             $converted = cnv($number, oct => dec);

             $converted = cnv($number,10 => 23); # dec to base23
             $converted = cnv($number,23 => 5);  # b23 to base5
             etc...

       •   $bc = new Math::Base::Convert([from],[to]);

           This method has the same usage and syntax for FROM and TO as cnv above.

           Setup for unconditional conversion from HEX to decimal

                   $bc = new Math::Base::Convert();

           Example conversion from octal to decimal

             base number
                   $bc = new Math::Base::Convert(8);

             base function (imported)
                   $bc = new Math::Base::Convert(oct);

             base text
                   $bc = new Math::Base::Convert('oct')

           The number conversion for any of the above:

           NOTE: iterative conversions using a method pointer are ALWAYS faster than calling cnv
           as a function.

                   $converted = $bc->cnv($number);

       •   $converted = cnvpre($number,[from],[to])

           Same as cnv except that base descriptor PREfixes are applied to binary, octal, and
           hexadecimal output strings.

       •   $converted = cnvabs($number,[from],[to])

           Same as cnv except that the ABSolute value of the number string is returned without
           SIGN is returned. i.e. just the raw string.

       •   ($sign,$prefix,$string) = cnv($number,[$from,[$to]])

       •   ($sign,$prefix,$string) = cnv($number,[$from,[$to]])

       •   ($sign,$prefix,$string) = cnv($number,[$from,[$to]])

           ARRAY context:

           All three functions return the same items in array context.

             sign          the sign of the input number string

             prefix        the prefix which would be applied to output

             string        the raw output string

       •   $basemap = basemap(base);

       •   $basemap = $bc->basemap(base);

           This function / method returns a pointer to a hash that maps the keys of a base to its
           numeric value for base conversion. It accepts base in any of the forms described for
           cnv.

           The return basemap includes upper and lower case variants of the the number base in
           cases such as hex where upper and lower case a..f, A..F map to the same numeric value
           for base conversion.

             i.e. $hex_ptr = {
                   0  => 0,
                   1  => 1,
                   2  => 2,
                   3  => 3,
                   4  => 4,
                   5  => 5,
                   6  => 6,
                   7  => 7,
                   8  => 8,
                   9  => 9,
                   A  => 10,
                   B  => 11,
                   C  => 12,
                   D  => 13,
                   E  => 14,
                   F  => 15,
                   a  => 10,
                   b  => 11,
                   c  => 12,
                   d  => 13,
                   e  => 14,
                   f  => 15
             };

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-2015, 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.