oracular (3) Math::Base::Convert.3pm.gz
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.