Debian Codegraph @

README

raw
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