.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Convert 3pm" .TH Convert 3pm "2015-10-22" "perl v5.20.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Math::Base::Convert \- very fast base to base conversion .SH "SYNOPSIS" .IX Header "SYNOPSIS" .SS "As a function" .IX Subsection "As a function" .Vb 2 \& 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); .Ve .SS "As a method:" .IX Subsection "As a method:" .Vb 2 \& 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); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module provides fast functions and methods to convert between arbitrary number bases from 2 (binary) thru 65535. .PP This module is pure Perl, has no external dependencies, and is backward compatible with old versions of Perl 5. .SH "PREFERRED USE" .IX Header "PREFERRED USE" Setting up the conversion parameters, context and error checking consume a significant portion of the execution time of a \&\fBsingle\fR base conversion. These operations are performed each time \fBcnv\fR is called as a function. .PP 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. .SH "BUILT IN NUMBER SETS" .IX Header "BUILT IN NUMBER SETS" Number set variants courtesy of the authors of Math::Base:Cnv and Math::BaseConvert. .PP The functions below return a reference to an array .PP .Vb 1 \& $arrayref = function; \& \& bin => [\*(Aq0\*(Aq, \*(Aq1\*(Aq] # binary \& dna => [\*(Aqa\*(Aq,\*(Aqt\*(Aq,\*(Aqc\*(Aq,\*(Aqg\*(Aq] # lc dna \& DNA => [\*(AqA\*(Aq,\*(AqT\*(Aq,\*(AqC\*(Aq,\*(AqG\*(Aq], {default} # uc DNA \& oct => [\*(Aq0\*(Aq..\*(Aq7\*(Aq] # octal \& dec => [\*(Aq0\*(Aq..\*(Aq9\*(Aq] # decimal \& hex => [\*(Aq0\*(Aq..\*(Aq9\*(Aq, \*(Aqa\*(Aq..\*(Aqf\*(Aq] # lc hex \& HEX => [\*(Aq0\*(Aq..\*(Aq9\*(Aq, \*(AqA\*(Aq..\*(AqF\*(Aq] {default} # uc HEX \& b62 => [\*(Aq0\*(Aq..\*(Aq9\*(Aq, \*(Aqa\*(Aq..\*(Aqz\*(Aq, \*(AqA\*(Aq..\*(AqZ\*(Aq] # base 62 \& b64 => [\*(Aq0\*(Aq..\*(Aq9\*(Aq, \*(AqA\*(Aq..\*(AqZ\*(Aq, \*(Aqa\*(Aq..\*(Aqz\*(Aq, \*(Aq.\*(Aq, \*(Aq_\*(Aq] # m:C:12 d:V:31 \& m64 => [\*(AqA\*(Aq..\*(AqZ\*(Aq, \*(Aqa\*(Aq..\*(Aqz\*(Aq, \*(Aq0\*(Aq..\*(Aq9\*(Aq, \*(Aq+\*(Aq, \*(Aq/\*(Aq] # MIMI::Base64 \& iru => [\*(AqA\*(Aq..\*(AqZ\*(Aq, \*(Aqa\*(Aq..\*(Aqz\*(Aq, \*(Aq0\*(Aq..\*(Aq9\*(Aq, \*(Aq[\*(Aq, \*(Aq]\*(Aq] # P10 \- IRCu \& url => [\*(AqA\*(Aq..\*(AqZ\*(Aq, \*(Aqa\*(Aq..\*(Aqz\*(Aq, \*(Aq0\*(Aq..\*(Aq9\*(Aq, \*(Aq*\*(Aq, \*(Aq\-\*(Aq] # url no %2B %2F \& rex => [\*(AqA\*(Aq..\*(AqZ\*(Aq, \*(Aqa\*(Aq..\*(Aqz\*(Aq, \*(Aq0\*(Aq..\*(Aq9\*(Aq, \*(Aq!\*(Aq, \*(Aq\-\*(Aq] # regex variant \& id0 => [\*(AqA\*(Aq..\*(AqZ\*(Aq, \*(Aqa\*(Aq..\*(Aqz\*(Aq, \*(Aq0\*(Aq..\*(Aq9\*(Aq, \*(Aq_\*(Aq, \*(Aq\-\*(Aq] # ID 0 \& id1 => [\*(AqA\*(Aq..\*(AqZ\*(Aq, \*(Aqa\*(Aq..\*(Aqz\*(Aq, \*(Aq0\*(Aq..\*(Aq9\*(Aq, \*(Aq.\*(Aq, \*(Aq_\*(Aq] # ID 1 \& xnt => [\*(AqA\*(Aq..\*(AqZ\*(Aq, \*(Aqa\*(Aq..\*(Aqz\*(Aq, \*(Aq0\*(Aq..\*(Aq9\*(Aq, \*(Aq.\*(Aq, \*(Aq\-\*(Aq] # XML (Nmtoken) \& xid => [\*(AqA\*(Aq..\*(AqZ\*(Aq, \*(Aqa\*(Aq..\*(Aqz\*(Aq, \*(Aq0\*(Aq..\*(Aq9\*(Aq, \*(Aq_\*(Aq, \*(Aq:\*(Aq] # XML (Name) \& b85 => [\*(Aq0\*(Aq..\*(Aq9\*(Aq, \*(AqA\*(Aq..\*(AqZ\*(Aq, \*(Aqa\*(Aq..\*(Aqz\*(Aq, \*(Aq!\*(Aq, \*(Aq#\*(Aq, # RFC 1924 \& \*(Aq$\*(Aq, \*(Aq%\*(Aq, \*(Aq&\*(Aq, \*(Aq(\*(Aq, \*(Aq)\*(Aq, \*(Aq*\*(Aq, \*(Aq+\*(Aq, \*(Aq\-\*(Aq, \& \*(Aq;\*(Aq, \*(Aq<\*(Aq, \*(Aq=\*(Aq, \*(Aq>\*(Aq, \*(Aq?\*(Aq, \*(Aq@\*(Aq, \*(Aq^\*(Aq, \*(Aq_\*(Aq, \& \*(Aq\*(Aq, \*(Aq{\*(Aq, \*(Aq|\*(Aq, \*(Aq}\*(Aq, \*(Aq~\*(Aq] \& An arbitrary base 96 composed of printable 7 bit ascii \& from 0x20 (space) through 0x7F (tilde ~) \& ascii => [ \& \*(Aq \*(Aq,\*(Aq!\*(Aq,\*(Aq"\*(Aq,\*(Aq#\*(Aq,\*(Aq$\*(Aq,\*(Aq%\*(Aq,\*(Aq&\*(Aq,"\*(Aq",\*(Aq(\*(Aq,\*(Aq)\*(Aq, \& \*(Aq*\*(Aq,\*(Aq+\*(Aq,\*(Aq,\*(Aq,\*(Aq\-\*(Aq,\*(Aq.\*(Aq,\*(Aq/\*(Aq, \& \*(Aq0\*(Aq,\*(Aq1\*(Aq,\*(Aq2\*(Aq,\*(Aq3\*(Aq,\*(Aq4\*(Aq,\*(Aq5\*(Aq,\*(Aq6\*(Aq,\*(Aq7\*(Aq,\*(Aq8\*(Aq,\*(Aq9\*(Aq, \& \*(Aq:\*(Aq,\*(Aq;\*(Aq,\*(Aq<\*(Aq,\*(Aq=\*(Aq,\*(Aq>\*(Aq,\*(Aq?\*(Aq,\*(Aq@\*(Aq, \& \*(AqA\*(Aq,\*(AqB\*(Aq,\*(AqC\*(Aq,\*(AqD\*(Aq,\*(AqE\*(Aq,\*(AqF\*(Aq,\*(AqG\*(Aq,\*(AqH\*(Aq,\*(AqI\*(Aq,\*(AqJ\*(Aq,\*(AqK\*(Aq,\*(AqL\*(Aq,\*(AqM\*(Aq, \& \*(AqN\*(Aq,\*(AqO\*(Aq,\*(AqP\*(Aq,\*(AqQ\*(Aq,\*(AqR\*(Aq,\*(AqS\*(Aq,\*(AqT\*(Aq,\*(AqU\*(Aq,\*(AqV\*(Aq,\*(AqW\*(Aq,\*(AqX\*(Aq,\*(AqY\*(Aq,\*(AqZ\*(Aq, \& \*(Aq[\*(Aq,\*(Aq\e\*(Aq,\*(Aq]\*(Aq,\*(Aq^\*(Aq,\*(Aq_\*(Aq,\*(Aq\`\*(Aq, \& \*(Aqa\*(Aq,\*(Aqb\*(Aq,\*(Aqc\*(Aq,\*(Aqd\*(Aq,\*(Aqe\*(Aq,\*(Aqf\*(Aq,\*(Aqg\*(Aq,\*(Aqh\*(Aq,\*(Aqi\*(Aq,\*(Aqj\*(Aq,\*(Aqk\*(Aq,\*(Aql\*(Aq,\*(Aqm\*(Aq, \& \*(Aqn\*(Aq,\*(Aqo\*(Aq,\*(Aqp\*(Aq,\*(Aqq\*(Aq,\*(Aqr\*(Aq,\*(Aqs\*(Aq,\*(Aqt\*(Aq,\*(Aqu\*(Aq,\*(Aqv\*(Aq,\*(Aqw\*(Aq,\*(Aqx\*(Aq,\*(Aqy\*(Aq,\*(Aqz\*(Aq, \& \*(Aq{\*(Aq,\*(Aq|\*(Aq,\*(Aq}\*(Aq,\*(Aq~\*(Aq] \& \& NOTE: Clean text with =~ s/\es+/ /; before applying to ascii .Ve .SH "USAGE" .IX Header "USAGE" .IP "\(bu" 4 \&\f(CW$converted\fR = cnv($number,[from],[to]) .Sp \&\s-1SCALAR\s0 context: array context covered later in this document. .Sp To preserve similarity to other similar base conversion modules, \fBcnv\fR returns the converted number string with \s-1SIGN\s0 if both the input and output base strings are in known signed set of bases in this module. .Sp 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 \s-1NOT\s0 applied to the output. .Sp The context of base \s-1FROM\s0 and \s-1TO\s0 is optional and flexible. .Sp Unconditional conversion from decimal to \s-1HEX\s0 [upper case] .Sp .Vb 1 \& $converted = cnv($number); .Ve .Sp Example conversion from octal to default \s-1HEX\s0 [upper case] with different context for the 'octal' designator. .Sp .Vb 2 \& base as a number \& $converted = cnv($number,8); \& \& base as a function (imported) \& $converted = cnv($number,oct); \& \& base as text \& $converted = convbase($number,\*(Aqoct\*(Aq); .Ve .Sp Conversion to/from arbitrary bases i.e. .Sp .Vb 5 \& $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... .Ve .IP "\(bu" 4 \&\f(CW$bc\fR = new Math::Base::Convert([from],[to]); .Sp This method has the same usage and syntax for \s-1FROM\s0 and \s-1TO\s0 as \fBcnv\fR above. .Sp Setup for unconditional conversion from \s-1HEX\s0 to decimal .Sp .Vb 1 \& $bc = new Math::Base::Convert(); .Ve .Sp Example conversion from octal to decimal .Sp .Vb 2 \& base number \& $bc = new Math::Base::Convert(8); \& \& base function (imported) \& $bc = new Math::Base::Convert(oct); \& \& base text \& $bc = new Math::Base::Convert(\*(Aqoct\*(Aq) .Ve .Sp The number conversion for any of the above: .Sp \&\s-1NOTE:\s0 iterative conversions using a method pointer are \s-1ALWAYS\s0 faster than calling \fBcnv\fR as a function. .Sp .Vb 1 \& $converted = $bc\->cnv($number); .Ve .IP "\(bu" 4 \&\f(CW$converted\fR = cnvpre($number,[from],[to]) .Sp Same as \fBcnv\fR except that base descriptor PREfixes are applied to \fBbinary\fR, \&\fBoctal\fR, and \fBhexadecimal\fR output strings. .IP "\(bu" 4 \&\f(CW$converted\fR = cnvabs($number,[from],[to]) .Sp Same as \fBcnv\fR except that the ABSolute value of the number string is returned without \s-1SIGN\s0 is returned. i.e. just the raw string. .IP "\(bu" 4 ($sign,$prefix,$string) = cnv($number,[$from,[$to]]) .IP "\(bu" 4 ($sign,$prefix,$string) = cnv($number,[$from,[$to]]) .IP "\(bu" 4 ($sign,$prefix,$string) = cnv($number,[$from,[$to]]) .Sp \&\s-1ARRAY\s0 context: .Sp All three functions return the same items in array context. .Sp .Vb 1 \& sign the sign of the input number string \& \& prefix the prefix which would be applied to output \& \& string the raw output string .Ve .IP "\(bu" 4 \&\f(CW$basemap\fR = basemap(base); .IP "\(bu" 4 \&\f(CW$basemap\fR = \f(CW$bc\fR\->basemap(base); .Sp 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 \fBbase\fR in any of the forms described for \fBcnv\fR. .Sp The return basemap includes upper and lower case variants of the the number base in cases such as \fBhex\fR where upper and lower case a..f, A..F map to the same numeric value for base conversion. .Sp .Vb 10 \& 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 \& }; .Ve .SH "BENCHMARKS" .IX Header "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. .PP .Vb 1 \& make test BENCHMARK=1 .Ve .PP 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) .PP .Vb 2 \& base 2 4 8 16 32 64 85 128 256 \& bin, dna, oct, hex, b32, b64, b85, b128, b256 .Ve .PP Conversions are performed \s-1FROM\s0 all bases \s-1TO\s0 decimal and are repeated in the opposing direction \s-1FROM\s0 decimal \s-1TO\s0 all bases. .PP Benchmark 1 results indicate the Math::Base::Convert typically runs significantly faster ( 10x to 100x) than Math::BigInt based implementations used in similar modules. .PP .Vb 1 \& make test BENCHMARK=2 .Ve .PP 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. .PP .Vb 1 \& make test BENCHMARK=3 .Ve .PP Checks the relative timing of short and long number string conversions. \s-1FROM\s0 a base number to n*32 bit register and \s-1TO\s0 a base number from an n*32 bit register set. .PP i.e. strings that convert to and from 1, 2, 3... etc.. 32 bit registers .SH "DEPENDENCIES" .IX Header "DEPENDENCIES" .Vb 1 \& none \& \& Math::BigInt is conditionally used in \& the test suite but is not a requirement .Ve .SH "EXPORT_OK" .IX Header "EXPORT_OK" Conditional \s-1EXPORT\s0 functions .PP .Vb 10 \& cnv \& cnvabs \& cnvpre \& basemap \& bin \& oct \& dec \& heX \& HEX \& b62 \& b64 \& m64 \& iru \& url \& rex \& id0 \& id1 \& xnt \& xid \& b85 \& ascii .Ve .SH "EXPORT_TAGS" .IX Header "EXPORT_TAGS" Conditional \s-1EXPORT\s0 function groups .PP .Vb 2 \& :all => all of above \& :base => all except \*(Aqcnv,cnvabs,cnvpre\*(Aq .Ve .SH "ACKNOWLEDGEMENTS" .IX Header "ACKNOWLEDGEMENTS" This module was inspired by Math::BaseConvert maintained by Shane Warden and forked from Math::BaseCnv, both authored by Pip Stuart .SH "AUTHOR" .IX Header "AUTHOR" Michael Robinton, .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2012\-2015, Michael Robinton .PP This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself. .PP This program is distributed in the hope that it will be useful, but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of \&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0