| 1 |
NAME |
| 2 |
Math::Base::Convert - very fast base to base conversion |
| 3 |
|
| 4 |
SYNOPSIS |
| 5 |
As a function |
| 6 |
|
| 7 |
use Math::Base::Convert qw( :all ) |
| 8 |
use Math::Base::Convert qw( |
| 9 |
|
| 10 |
cnv |
| 11 |
cnvabs |
| 12 |
cnvpre |
| 13 |
basemap |
| 14 |
|
| 15 |
# comments |
| 16 |
bin base 2 0,1 |
| 17 |
dna base 4 lower case dna |
| 18 |
DNA base 4 upper case DNA |
| 19 |
oct base 8 octal |
| 20 |
dec base 10 decimal |
| 21 |
hex base 16 lower case hex |
| 22 |
HEX base 16 upper case HEX |
| 23 |
b62 base 62 |
| 24 |
b64 base 64 month:C:12 day:V:31 |
| 25 |
m64 base 64 0-63 from MIME::Base64 |
| 26 |
iru base 64 P10 protocol - IRCu daemon |
| 27 |
url base 64 url with no %2B %2F expansion of + - / |
| 28 |
rex base 64 regular expression variant |
| 29 |
id0 base 64 IDentifier style 0 |
| 30 |
id1 base 64 IDentifier style 1 |
| 31 |
xnt base 64 XML Name Tokens (Nmtoken) |
| 32 |
xid base 64 XML identifiers (Name) |
| 33 |
b85 base 85 RFC 1924 for IPv6 addresses |
| 34 |
ascii base 95 7 bit printible 0x20 - 0x7F |
| 35 |
); |
| 36 |
|
| 37 |
my $converted = cnv($number,optionalFROM,optionalTO); |
| 38 |
my $basemap = basmap(base); |
| 39 |
|
| 40 |
As a method: |
| 41 |
|
| 42 |
use Math::Base::Convert; |
| 43 |
use Math::Base::Convert qw(:base); |
| 44 |
|
| 45 |
my $bc = new Math::Base::Convert(optionalFROM,optionalTO); |
| 46 |
my $converted = $bc->cnv($number); |
| 47 |
my $basemap = $bc->basemap(base); |
| 48 |
|
| 49 |
DESCRIPTION |
| 50 |
This module provides fast functions and methods to convert between |
| 51 |
arbitrary number bases from 2 (binary) thru 65535. |
| 52 |
|
| 53 |
This module is pure Perl, has no external dependencies, and is backward |
| 54 |
compatible with old versions of Perl 5. |
| 55 |
|
| 56 |
PREFERRED USE |
| 57 |
Setting up the conversion parameters, context and error checking consume |
| 58 |
a significant portion of the execution time of a single base conversion. |
| 59 |
These operations are performed each time cnv is called as a function. |
| 60 |
|
| 61 |
Using method calls eliminates a large portion of this overhead and will |
| 62 |
improve performance for repetitive conversions. See the benchmarks |
| 63 |
sub-directory in this distribution. |
| 64 |
|
| 65 |
BUILT IN NUMBER SETS |
| 66 |
Number set variants courtesy of the authors of Math::Base:Cnv and |
| 67 |
Math::BaseConvert. |
| 68 |
|
| 69 |
The functions below return a reference to an array |
| 70 |
|
| 71 |
$arrayref = function; |
| 72 |
|
| 73 |
bin => ['0', '1'] # binary |
| 74 |
dna => ['a','t','c','g'] # lc dna |
| 75 |
DNA => ['A','T','C','G'], {default} # uc DNA |
| 76 |
oct => ['0'..'7'] # octal |
| 77 |
dec => ['0'..'9'] # decimal |
| 78 |
hex => ['0'..'9', 'a'..'f'] # lc hex |
| 79 |
HEX => ['0'..'9', 'A'..'F'] {default} # uc HEX |
| 80 |
b62 => ['0'..'9', 'a'..'z', 'A'..'Z'] # base 62 |
| 81 |
b64 => ['0'..'9', 'A'..'Z', 'a'..'z', '.', '_'] # m:C:12 d:V:31 |
| 82 |
m64 => ['A'..'Z', 'a'..'z', '0'..'9', '+', '/'] # MIMI::Base64 |
| 83 |
iru => ['A'..'Z', 'a'..'z', '0'..'9', '[', ']'] # P10 - IRCu |
| 84 |
url => ['A'..'Z', 'a'..'z', '0'..'9', '*', '-'] # url no %2B %2F |
| 85 |
rex => ['A'..'Z', 'a'..'z', '0'..'9', '!', '-'] # regex variant |
| 86 |
id0 => ['A'..'Z', 'a'..'z', '0'..'9', '_', '-'] # ID 0 |
| 87 |
id1 => ['A'..'Z', 'a'..'z', '0'..'9', '.', '_'] # ID 1 |
| 88 |
xnt => ['A'..'Z', 'a'..'z', '0'..'9', '.', '-'] # XML (Nmtoken) |
| 89 |
xid => ['A'..'Z', 'a'..'z', '0'..'9', '_', ':'] # XML (Name) |
| 90 |
b85 => ['0'..'9', 'A'..'Z', 'a'..'z', '!', '#', # RFC 1924 |
| 91 |
'$', '%', '&', '(', ')', '*', '+', '-', |
| 92 |
';', '<', '=', '>', '?', '@', '^', '_', |
| 93 |
'', '{', '|', '}', '~'] |
| 94 |
An arbitrary base 95 composed of printable 7 bit ascii |
| 95 |
from 0x20 (space) through 0x7F (tilde ~) |
| 96 |
ascii => [ |
| 97 |
' ','!','"','#','$','%','&',"'",'(',')', |
| 98 |
'*','+',',','-','.','/', |
| 99 |
'0','1','2','3','4','5','6','7','8','9', |
| 100 |
':',';','<','=','>','?','@', |
| 101 |
'A','B','C','D','E','F','G','H','I','J','K','L','M', |
| 102 |
'N','O','P','Q','R','S','T','U','V','W','X','Y','Z', |
| 103 |
'[','\',']','^','_','`', |
| 104 |
'a','b','c','d','e','f','g','h','i','j','k','l','m', |
| 105 |
'n','o','p','q','r','s','t','u','v','w','x','y','z', |
| 106 |
'{','|','}','~'] |
| 107 |
|
| 108 |
NOTE: Clean text with =~ s/\s+/ /; before applying to ascii |
| 109 |
|
| 110 |
USAGE |
| 111 |
* $converted = cnv($number,[from],[to]) |
| 112 |
SCALAR context: array context covered later in this document. |
| 113 |
|
| 114 |
To preserve similarity to other similar base conversion modules, cnv |
| 115 |
returns the converted number string with SIGN if both the input and |
| 116 |
output base strings are in known signed set of bases in this module. |
| 117 |
|
| 118 |
In the case of binary, octal, hex, all leading base designator |
| 119 |
strings such as '0b','0', '0x' are automatically stripped from the |
| 120 |
input. Base designator strings are NOT applied to the output. |
| 121 |
|
| 122 |
The context of base FROM and TO is optional and flexible. |
| 123 |
|
| 124 |
Unconditional conversion from decimal to HEX [upper case] |
| 125 |
|
| 126 |
$converted = cnv($number); |
| 127 |
|
| 128 |
Example conversion from octal to default HEX [upper case] with |
| 129 |
different context for the 'octal' designator. |
| 130 |
|
| 131 |
base as a number |
| 132 |
$converted = cnv($number,8); |
| 133 |
|
| 134 |
base as a function (imported) |
| 135 |
$converted = cnv($number,oct); |
| 136 |
|
| 137 |
base as text |
| 138 |
$converted = convbase($number,'oct'); |
| 139 |
|
| 140 |
Conversion to/from arbitrary bases i.e. |
| 141 |
|
| 142 |
$converted = cnv($number); # dec -> hex (default) |
| 143 |
$converted = cnv($number,oct); # oct to HEX |
| 144 |
$converted = cnv($number,10,HEX); # dec to uc HEX |
| 145 |
$converted = cnv($number,10,hex); # dec to lc hex |
| 146 |
$converted = cnv($number,dec,hex);# same |
| 147 |
|
| 148 |
pointer notation |
| 149 |
$converted = cnv($number, oct => dec); |
| 150 |
|
| 151 |
$converted = cnv($number,10 => 23); # dec to base23 |
| 152 |
$converted = cnv($number,23 => 5); # b23 to base5 |
| 153 |
etc... |
| 154 |
|
| 155 |
* $bc = new Math::Base::Convert([from],[to]); |
| 156 |
This method has the same usage and syntax for FROM and TO as cnv |
| 157 |
above. |
| 158 |
|
| 159 |
Setup for unconditional conversion from HEX to decimal |
| 160 |
|
| 161 |
$bc = new Math::Base::Convert(); |
| 162 |
|
| 163 |
Example conversion from octal to decimal |
| 164 |
|
| 165 |
base number |
| 166 |
$bc = new Math::Base::Convert(8); |
| 167 |
|
| 168 |
base function (imported) |
| 169 |
$bc = new Math::Base::Convert(oct); |
| 170 |
|
| 171 |
base text |
| 172 |
$bc = new Math::Base::Convert('oct') |
| 173 |
|
| 174 |
The number conversion for any of the above: |
| 175 |
|
| 176 |
NOTE: iterative conversions using a method pointer are ALWAYS faster |
| 177 |
than calling cnv as a function. |
| 178 |
|
| 179 |
$converted = $bc->cnv($number); |
| 180 |
|
| 181 |
* $converted = cnvpre($number,[from],[to]) |
| 182 |
Same as cnv except that base descriptor PREfixes are applied to |
| 183 |
binary, octal, and hexadecimal output strings. |
| 184 |
|
| 185 |
* $converted = cnvabs($number,[from],[to]) |
| 186 |
Same as cnv except that the ABSolute value of the number string is |
| 187 |
returned without SIGN is returned. i.e. just the raw string. |
| 188 |
|
| 189 |
* ($sign,$prefix,$string) = cnv($number,[$from,[$to]]) |
| 190 |
* ($sign,$prefix,$string) = cnv($number,[$from,[$to]]) |
| 191 |
* ($sign,$prefix,$string) = cnv($number,[$from,[$to]]) |
| 192 |
ARRAY context: |
| 193 |
|
| 194 |
All three functions return the same items in array context. |
| 195 |
|
| 196 |
sign the sign of the input number string |
| 197 |
|
| 198 |
prefix the prefix which would be applied to output |
| 199 |
|
| 200 |
string the raw output string |
| 201 |
|
| 202 |
* $basemap = basemap(base); |
| 203 |
* $basemap = $bc->basemap(base); |
| 204 |
This function / method returns a pointer to a hash that maps the |
| 205 |
keys of a base to its numeric value for base conversion. It accepts |
| 206 |
base in any of the forms described for cnv. |
| 207 |
|
| 208 |
The return basemap includes upper and lower case variants of the the |
| 209 |
number base in cases such as hex where upper and lower case a..f, |
| 210 |
A..F map to the same numeric value for base conversion. |
| 211 |
|
| 212 |
i.e. $hex_ptr = { |
| 213 |
0 => 0, |
| 214 |
1 => 1, |
| 215 |
2 => 2, |
| 216 |
3 => 3, |
| 217 |
4 => 4, |
| 218 |
5 => 5, |
| 219 |
6 => 6, |
| 220 |
7 => 7, |
| 221 |
8 => 8, |
| 222 |
9 => 9, |
| 223 |
A => 10, |
| 224 |
B => 11, |
| 225 |
C => 12, |
| 226 |
D => 13, |
| 227 |
E => 14, |
| 228 |
F => 15, |
| 229 |
a => 10, |
| 230 |
b => 11, |
| 231 |
c => 12, |
| 232 |
d => 13, |
| 233 |
e => 14, |
| 234 |
f => 15 |
| 235 |
}; |
| 236 |
|
| 237 |
BENCHMARKS |
| 238 |
Math::Base::Convert includes 2 development and one real world benchmark |
| 239 |
sequences included in the test suite. Benchmark results for a 500mhz |
| 240 |
system can be found in the 'benchmarks' source directory. |
| 241 |
|
| 242 |
make test BENCHMARK=1 |
| 243 |
|
| 244 |
Provides comparison data for bi-directional conversion of an ascending |
| 245 |
series of number strings in all base powers. The test sequence contains |
| 246 |
number strings that go from a a single 32 bit register to several. |
| 247 |
Tested bases are: (note: b32, b128, b256 not useful and are for testing |
| 248 |
only) |
| 249 |
|
| 250 |
base 2 4 8 16 32 64 85 128 256 |
| 251 |
bin, dna, oct, hex, b32, b64, b85, b128, b256 |
| 252 |
|
| 253 |
Conversions are performed FROM all bases TO decimal and are repeated in |
| 254 |
the opposing direction FROM decimal TO all bases. |
| 255 |
|
| 256 |
Benchmark 1 results indicate the Math::Base::Convert typically runs |
| 257 |
significantly faster ( 10x to 100x) than Math::BigInt based |
| 258 |
implementations used in similar modules. |
| 259 |
|
| 260 |
make test BENCHMARK=2 |
| 261 |
|
| 262 |
Provides comparison data for the frontend and backend converters in |
| 263 |
Math::Base::Convert's CalcPP and Shortcuts packages, and Math::Bigint |
| 264 |
conversions if it is present on the system under test. |
| 265 |
|
| 266 |
make test BENCHMARK=3 |
| 267 |
|
| 268 |
Checks the relative timing of short and long number string conversions. |
| 269 |
FROM a base number to n*32 bit register and TO a base number from an |
| 270 |
n*32 bit register set. |
| 271 |
|
| 272 |
i.e. strings that convert to and from 1, 2, 3... etc.. 32 bit registers |
| 273 |
|
| 274 |
DEPENDENCIES |
| 275 |
none |
| 276 |
|
| 277 |
Math::BigInt is conditionally used in |
| 278 |
the test suite but is not a requirement |
| 279 |
|
| 280 |
EXPORT_OK |
| 281 |
Conditional EXPORT functions |
| 282 |
|
| 283 |
cnv |
| 284 |
cnvabs |
| 285 |
cnvpre |
| 286 |
basemap |
| 287 |
bin |
| 288 |
oct |
| 289 |
dec |
| 290 |
heX |
| 291 |
HEX |
| 292 |
b62 |
| 293 |
b64 |
| 294 |
m64 |
| 295 |
iru |
| 296 |
url |
| 297 |
rex |
| 298 |
id0 |
| 299 |
id1 |
| 300 |
xnt |
| 301 |
xid |
| 302 |
b85 |
| 303 |
ascii |
| 304 |
|
| 305 |
EXPORT_TAGS |
| 306 |
Conditional EXPORT function groups |
| 307 |
|
| 308 |
:all => all of above |
| 309 |
:base => all except 'cnv,cnvabs,cnvpre' |
| 310 |
|
| 311 |
ACKNOWLEDGEMENTS |
| 312 |
This module was inspired by Math::BaseConvert maintained by Shane Warden |
| 313 |
<[email protected]> and forked from Math::BaseCnv, both authored by Pip |
| 314 |
Stuart <[email protected]> |
| 315 |
|
| 316 |
AUTHOR |
| 317 |
Michael Robinton, <[email protected]> |
| 318 |
|
| 319 |
COPYRIGHT |
| 320 |
Copyright 2012-2015, Michael Robinton |
| 321 |
|
| 322 |
This program is free software; you may redistribute it and/or modify it |
| 323 |
under the same terms as Perl itself. |
| 324 |
|
| 325 |
This program is distributed in the hope that it will be useful, but |
| 326 |
WITHOUT ANY WARRANTY; without even the implied warranty of |
| 327 |
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. |
| 328 |
|