1Convert(3)            User Contributed Perl Documentation           Convert(3)
2
3
4

NAME

6       Math::Base::Convert - very fast base to base conversion
7

SYNOPSIS

9   As a function
10         use Math::Base::Convert qw( :all )
11         use Math::Base::Convert qw(
12
13               cnv
14               cnvabs
15               cnvpre
16               basemap
17
18                               # 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
40         my $converted = cnv($number,optionalFROM,optionalTO);
41         my $basemap = basmap(base);
42
43   As a method:
44         use Math::Base::Convert;
45         use Math::Base::Convert qw(:base);
46
47         my $bc = new Math::Base::Convert(optionalFROM,optionalTO);
48         my $converted = $bc->cnv($number);
49         my $basemap = $bc->basemap(base);
50

DESCRIPTION

52       This module provides fast functions and methods to convert between
53       arbitrary number bases from 2 (binary) thru 65535.
54
55       This module is pure Perl, has no external dependencies, and is backward
56       compatible with old versions of Perl 5.
57

PREFERRED USE

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
64       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

BUILT IN NUMBER SETS

69       Number set variants courtesy of the authors of Math::Base:Cnv and
70       Math::BaseConvert.
71
72       The functions below return a reference to an array
73
74         $arrayref     = function;
75
76         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
111         NOTE: Clean text with =~ s/\s+/ /; before applying to ascii
112

USAGE

114       •   $converted = cnv($number,[from],[to])
115
116           SCALAR context: array context covered later in this document.
117
118           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
123           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
127           The context of base FROM and TO is optional and flexible.
128
129           Unconditional conversion from decimal to HEX [upper case]
130
131                   $converted = cnv($number);
132
133           Example conversion from octal to default HEX [upper case] with
134           different context for the 'octal' designator.
135
136             base as a number
137                   $converted = cnv($number,8);
138
139             base as a function    (imported)
140                   $converted = cnv($number,oct);
141
142             base as text
143                   $converted = convbase($number,'oct');
144
145           Conversion to/from arbitrary bases i.e.
146
147             $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
153                   pointer notation
154             $converted = cnv($number, oct => dec);
155
156             $converted = cnv($number,10 => 23); # dec to base23
157             $converted = cnv($number,23 => 5);  # b23 to base5
158             etc...
159
160       •   $bc = new Math::Base::Convert([from],[to]);
161
162           This method has the same usage and syntax for FROM and TO as cnv
163           above.
164
165           Setup for unconditional conversion from HEX to decimal
166
167                   $bc = new Math::Base::Convert();
168
169           Example conversion from octal to decimal
170
171             base number
172                   $bc = new Math::Base::Convert(8);
173
174             base function (imported)
175                   $bc = new Math::Base::Convert(oct);
176
177             base text
178                   $bc = new Math::Base::Convert('oct')
179
180           The number conversion for any of the above:
181
182           NOTE: iterative conversions using a method pointer are ALWAYS
183           faster than calling cnv as a function.
184
185                   $converted = $bc->cnv($number);
186
187       •   $converted = cnvpre($number,[from],[to])
188
189           Same as cnv except that base descriptor PREfixes are applied to
190           binary, octal, and hexadecimal output strings.
191
192       •   $converted = cnvabs($number,[from],[to])
193
194           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
197       •   ($sign,$prefix,$string) = cnv($number,[$from,[$to]])
198
199       •   ($sign,$prefix,$string) = cnv($number,[$from,[$to]])
200
201       •   ($sign,$prefix,$string) = cnv($number,[$from,[$to]])
202
203           ARRAY context:
204
205           All three functions return the same items in array context.
206
207             sign          the sign of the input number string
208
209             prefix        the prefix which would be applied to output
210
211             string        the raw output string
212
213       •   $basemap = basemap(base);
214
215       •   $basemap = $bc->basemap(base);
216
217           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
221           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
225             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

BENCHMARKS

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
255         make test BENCHMARK=1
256
257       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
263           base 2    4    8    16   32   64   85   128   256
264               bin, dna, oct, hex, b32, b64, b85, b128, b256
265
266       Conversions are performed FROM all bases TO decimal and are repeated in
267       the opposing direction FROM decimal TO all bases.
268
269       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
273         make test BENCHMARK=2
274
275       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
279         make test BENCHMARK=3
280
281       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
285       i.e. strings that convert to and from 1, 2, 3... etc.. 32 bit registers
286

DEPENDENCIES

288               none
289
290               Math::BigInt is conditionally used in
291               the test suite but is not a requirement
292

EXPORT_OK

294       Conditional EXPORT functions
295
296               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

EXPORT_TAGS

319       Conditional EXPORT function groups
320
321               :all    => all of above
322               :base   => all except 'cnv,cnvabs,cnvpre'
323

ACKNOWLEDGEMENTS

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

AUTHOR

330       Michael Robinton, <miker@cpan.org>
331
333       Copyright 2012-2015, Michael Robinton
334
335       This program is free software; you may redistribute it and/or modify it
336       under the same terms as Perl itself.
337
338       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.
341
342
343
344perl v5.38.0                      2023-07-20                        Convert(3)
Impressum