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