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

NAME

6       Math::BaseCnv - basic functions to CoNVert between number Bases
7

VERSION

9       This documentation refers to version 1.14 of Math::BaseCnv, which was
10       released on Sat Jul 30 06:44:28:46 -0500 2016.
11

SYNOPSIS

13         #!/usr/bin/perl
14         use strict;use warnings;use utf8;use v5.10;use Math::BaseCnv;
15
16                     # CoNVert     63 from base-10 (decimal) to base- 2 (binary )
17         my $binary__63 = cnv(     63 , 10,  2 );
18                     # CoNVert 111111 from base- 2 (binary ) to base-16 (HEX    )
19         my $HEX_____63 = cnv( 111111 ,  2, 16 );
20                     # CoNVert     3F from base-16 (HEX    ) to base-10 (decimal)
21         my $decimal_63 = cnv(    '3F', 16, 10 );
22         say "63 dec->bin $binary__63 bin->HEX $HEX_____63 HEX->dec $decimal_63";
23

DESCRIPTION

25       BaseCnv provides a few simple functions for converting between
26       arbitrary number bases. You're probably better off using Michael
27       Robinton's Math::Base::Convert benchmarked high-performance Perl
28       modules. Another object syntax for number-base conversion is Ken
29       Williams' fine Math::BaseCalc module.
30

PURPOSE

32       The reason I created BaseCnv was that I needed a simple way to convert
33       quickly between the 3 number bases I use most (10, 16, and 64). It
34       turned out that it was trivial to handle any arbitrary number base that
35       is represented as characters. High-bit ASCII has proven somewhat
36       problemmatic but at least BaseCnv can simply and reliably convert
37       between any possible base between 2 and 64 (or 96). I'm happy with it
38       and employ b64() in places I probably shouldn't now.
39

USAGE

41   cnv($numb[,$from[,$tobs]])
42       CoNVert the number contained in $numb from its current number base
43       ($from) into the result number base ($tobs).
44
45       When only $numb is provided as a parameter:
46
47       If $numb only contains valid decimal (base 10) digits, it will be
48       converted to HEXADECIMAL (base 16).
49
50       If $numb only contains valid hexadecimal (base 16) digits or begins
51       with '0x', it will be it will be converted to decimal (base 10).
52
53       When only $numb and $from are provided as parameters:
54
55       cnv() assumes that $numb is already in decimal format and uses $from as
56       the $tobs.
57
58       When all three parameters are provided:
59
60       The normal (and most clear) usage of cnv() is to provide all three
61       parameters where $numb is converted from $from base to $tobs.
62
63       cnv() is the only function that is exported from a normal 'use
64       Math::BaseCnv;' command. The other functions below can be imported to
65       local namespaces explicitly or with the following tags:
66
67         :all - every function described here
68         :heX - only cnv(), dec(), heX(), and HEX()
69         :b64 - only cnv(), b10(), b64(), and b64sort()
70         :dig - only dig() and diginit()
71         :sfc - only summ(), fact(), and choo()
72
73   b10($b64n)
74       A shortcut to convert the number given as a parameter ($b64n) from base
75       64 to decimal (base 10).
76
77   b64($b10n)
78       A shortcut to convert the number given as a parameter ($b10n) from
79       decimal (base 10) to base 64.
80
81   b64sort(@b64s)
82       A way to sort b64 strings as though they were decimal numbers.
83
84   dec($b16n)
85       A shortcut to convert the number given as a parameter ($b16n) from
86       hexadecimal (base 16) to decimal (base 10).
87
88   HEX($b10n)
89       A shortcut to convert the number given as a parameter ($b10n) from
90       decimal (base 10) to HEXADECIMAL (base 16) uppercase.
91
92   heX($b10n)
93       A shortcut to convert the number given as a parameter ($b10n) from
94       decimal (base 10) to hexadecimal (base 16) lowercase.
95
96       Please read the "NOTES" regarding heX().
97
98   dig(\@newd)
99       Assign the new digit character list to be used in place of the default
100       one. dig() can also alternately accept a string name matching one of
101       the following predefined digit sets:
102
103         'bin' => ['0', '1'],
104         'dna' => ['a', 'c', 'g', 't'],
105         'DNA' => ['A', 'C', 'G', 'T'],
106         'oct' => ['0'..'7'],
107         'dec' => ['0'..'9'],
108         'heX' => ['0'..'9', 'a'..'f'],
109         'HEX' => ['0'..'9', 'A'..'F'],
110         'b36' => ['0'..'9', 'a'..'z'],
111         'B36' => ['0'..'9', 'A'..'Z'],
112         'b62' => ['0'..'9', 'a'..'z', 'A'..'Z'],
113         'b64' => ['0'..'9', 'A'..'Z', 'a'..'z', '.', '_'], # month:C:12 day:V:31
114         'm64' => ['A'..'Z', 'a'..'z', '0'..'9', '+', '/'], # 0-63 from MIME::Base64
115         'iru' => ['A'..'Z', 'a'..'z', '0'..'9', '[', ']'], # P10 server-server protocol used by IRCu daemon
116         'url' => ['A'..'Z', 'a'..'z', '0'..'9', '-', '_'], # MIME::Base64::URLSafe (avoid %2B %2F expansions)
117         'rgx' => ['A'..'Z', 'a'..'z', '0'..'9', '!', '-'], # ReGular eXpression variant
118         'id0' => ['A'..'Z', 'a'..'z', '0'..'9', '_', '-'], # IDentifier style 0
119         'id1' => ['A'..'Z', 'a'..'z', '0'..'9', '.', '_'], # IDentifier style 1
120         'xnt' => ['A'..'Z', 'a'..'z', '0'..'9', '.', '-'], # XML Name Tokens (Nmtoken)
121         'xid' => ['A'..'Z', 'a'..'z', '0'..'9', '_', ':'], # XML identifiers (Name   )
122         'sxl' => ['?', '@', 'A'..'Z', '[','\\', ']', '^',  # Sixel Base64 from VT100.Net
123                   '_', '`', 'a'..'z', '{', '|', '}', '~'],
124         'b85' => ['0'..'9', 'A'..'Z', 'a'..'z', '!', '#',  # RFC 1924 for IPv6 addresses like in Math::Base85
125                   '$', '%', '&', '(', ')', '*', '+', '-',
126                   ';', '<', '=', '>', '?', '@', '^', '_',
127                   '`', '{', '|', '}', '~'               ],
128         'asc' => [' ', '!', '"', '#', '$', '%', '&', "'",  # Base96 7-bit printable 0x20 (space) - 0x7F
129                   '(', ')', '*', '+', ',', '-', '.', '/',  #   (tilde ~) 'ascii' from Math::Base::Convert
130                   '0'..'9', ':', ';', '<', '=', '>', '?',
131                   '@', 'A'..'Z', '[','\\', ']', '^', '_',
132                   '`', 'a'..'z', '{', '|', '}', '~'     ],
133         'b96' => ['0'..'9', 'A'..'Z', 'a'..'z', '.', '_',  # Base96 but starting with b64 characters
134                   ' ', '!', '"', '#', '$', '%', '&', "'",
135                   '(', ')', '*', '+', ',', '-', '/', ':',
136                   ';', '<', '=', '>', '?', '@', '[','\\',
137                   ']', '^', '`', '{', '|', '}', '~'     ],
138
139       If no \@newd list or digit set name is provided as a parameter, dig()
140       returns the current character list. It's fine to have many more
141       characters in your current digit set than will be used with your
142       conversions (e.g., using dig('b64') works fine for any cnv() call with
143       $from and $tobs params less than or equal to 64).
144
145       An example of a \@newd parameter for a specified alternate digit set
146       for base 9 conversions is:
147
148         dig( [ qw( n a c h o z   y u m ) ] );
149
150   diginit()
151       Resets the used digit list to the initial default order of the
152       predefined digit set: 'b64'. This is simply a shortcut for calling
153       dig('b64') for reinitialization purposes.
154
155   summ($numb)
156       A simple function to calculate a memoized BigInt summation of $numb
157       down to 1.
158
159   fact($numb)
160       A simple function to calculate a memoized BigInt factorial of $numb.
161
162   choo($ennn, $emmm)
163       A simple function to calculate a memoized BigInt function  of $ennn
164       choose $emmm.
165

NOTES

167       The Perl built-in hex() function takes a hex string as a parameter and
168       returns the decimal value (FromBase = 16, ToBase = 10). This notation
169       seems counter-intuitive to me since I prefer to read the code as though
170       a hex() function will turn your parameter into hexadecimal (i.e., I
171       think hex() should hexify your parameter but Perl's built-in does
172       not.). I initially decided to invert the notation for my similar
173       functions, but reconsidered the potential harm possible by introducing
174       exported conflicting opposite behavior into other people's maybe
175       crucial code, so I am falling back on unique casing with heX().
176
177       My b64() function takes a decimal number as a parameter and returns the
178       base64 equivalent (FromBase = 10, ToBase = 64) and my b10() function
179       takes a base64 number (string) and returns the decimal value (FromBase
180       = 64, ToBase = 10). My heX() function opposes Perl's built-in hex()
181       (which is similar to my dec()).
182
183       Please think of my dec() and heX() functions as meaning decify and
184       heXify. Also the pronunciation of dec() is 'dess' (not 'deck').
185
186       Error checking is minimal.
187
188       This module does not handle fractional number inputs because I like
189       using the dot (.) character as a standard base64 digit since it makes
190       for clean filenames.
191
192       summ(), fact(), and choo() are general Math function utilities which
193       are unrelated to number-base conversion but I didn't feel like making
194       another separate module just for them so they snuck in here.
195
196       I hope you find Math::BaseCnv useful. TTFN.
197

CHANGES

199       Revision history for Perl extension Math::BaseCnv:
200
201       - 1.14 G7UM6iSk  Sat Jul 30 06:44:28:46 -0500 2016
202         * synchronized README and Changes to updated POD
203
204       - 1.12 G7OMKBCn  Sun Jul 24 20:11:12:49 -0500 2016
205         * added digit set 'b96' as a reordering of 'asc'
206
207       - 1.10 G7OMF3ZT  Sun Jul 24 15:03:35:29 -0500 2016
208         * added new digit sets from Math::Base::Convert
209
210         * switched all old hex() to distinct new heX() and updated POD to
211         reflect
212
213         * fixed META license to match POD and resolve issue:
214         <HTTPS://RT.CPAN.Org/Public/Bug/Display.html?id=60122> (Thanks again
215         xenoterracide.)
216
217         * removed PT from VERSION to resolve issue:
218         <HTTPS://RT.CPAN.Org/Public/Bug/Display.html?id=60275> (Thanks
219         Alexandr.)
220
221       - 1.8.B59BrZX  Mon May  9 11:53:35:33 2011
222         * updated 'url' digit set to URLSafe to resolve
223         <HTTPS://RT.CPAN.Org/Ticket/Display.html?id=60125> (Thanks
224         xenoterracide.)
225
226         * updated license copyright years (already had GPLv3)
227
228       - 1.6.A6FGHKE  Tue Jun 15 16:17:20:14 2010
229         * bumped minor version number so they'll keep ascending (without PT
230         comprehension)
231
232       - 1.4.A6FAbEb  Tue Jun 15 10:37:14:37 2010
233         * added Math::BigInt code for >64-bit number-base conversions
234
235         * added a bunch more DigitSets: IRCu, URL, RegEx, identifier
236         variants, XML Nmtoken, and XML ID Name
237
238       - 1.4.75O6Pbr  Thu May 24 06:25:37:53 2007
239         * added Test::Pod(::Coverage)? tests and PREREQ entries
240
241         * added b85 for IPv6, generated META.yml (with needed newline before
242         EOF) and updated minor version number
243
244       - 1.2.68J9uJQ  Sat Aug 19 09:56:19:26 2006
245         * added b64sort() and put POD at bottom
246
247       - 1.2.59M7mRX  Thu Sep 22 07:48:27:33 2005
248         * testing Make as primary and BuildPL backup (needing rename for dot)
249
250       - 1.2.59IBlgw  Sun Sep 18 11:47:42:58 2005
251         * testing just using Module::Build instead of MakeMaker
252
253         * fixed test 12 which was failing on AMD64
254
255         * added Build.PL to package
256
257       - 1.2.54HK3pB  Sun Apr 17 20:03:51:11 2005
258         * removed 128 digit-set since some high-bit characters cause problems
259         on Win32
260
261         * made bin/cnv only executable to go in EXE_FILES
262
263         * made Math::BaseCalc a link in POD and updated License
264
265       - 1.2.45UC8fo  Sun May 30 12:08:41:50 2004
266         * tidied POD and increased minor version number since CPAN can't read
267         PT in VERSION
268
269       - 1.0.44E9ljP  Wed Apr 14 09:47:45:25 2004
270         * added test for divide-by-zero error in choo()
271
272         * added summ()
273
274       - 1.0.446EIbS  Tue Apr  6 14:18:37:28 2004
275         * snuck in fact() and choo()
276
277       - 1.0.42REDir  Fri Feb 27 14:13:44:53 2004
278         * changed test.pl to hopefully pass MSWin32-x86-multi-thread
279
280       - 1.0.428LV46  Sun Feb  8 21:31:04:06 2004
281         * broke apart CHANGES to descend chronologically
282
283         * made dec() auto uppercase param since dec(a) was returning 36
284         instead of 10
285
286       - 1.0.41M4GMP  Thu Jan 22 04:16:22:25 2004
287         * put cnv in bin/ as EXE_FILES
288
289       - 1.0.418BEPc  Thu Jan  8 11:14:25:38 2004
290         * testing new e auto-generate MANIFEST(.SKIP)?
291
292       - 1.0.3CNH37s  Tue Dec 23 17:03:07:54 2003
293         * updated POD
294
295       - 1.0.3CG3dIx  Tue Dec 16 03:39:18:59 2003
296         * normalized base spelling
297
298       - 1.0.3CD1Vdd  Sat Dec 13 01:31:39:39 2003
299         * added ABSTRACT section to WriteMakeFile()
300
301         * changed synopsis example
302
303         * updated all POD indenting
304
305       - 1.0.3CCA5Mi  Fri Dec 12 10:05:22:44 2003
306         * removed indenting from POD NAME field
307
308       - 1.0.3CB7M43  Thu Dec 11 07:22:04:03 2003
309         * updated package to coincide with Time::Fields release
310
311       - 1.0.39B36Lv  Thu Sep 11 03:06:21:57 2003
312         * synchronized POD with README documentation using new e utility
313
314         * templatized package compilation
315
316         * fixed boundary bugs
317
318       - 1.0.37SLNGN  Mon Jul 28 21:23:16:23 2003
319         * first version (and my first Perl module... yay!) put on CPAN
320
321       - 1.0.37JKj3w  Sat Jul 19 20:45:03:58 2003
322         * reworked interface from shell utility to package
323
324       - 1.0.3159mLT  Sun Jan  5 09:48:21:29 2003
325         * original version
326

TODO

328       - better error checking
329       - handle fractions and exponents?
330

INSTALL

332       Please run:
333
334         `perl -MCPAN -e "install Math::BaseCnv"`
335
336       or uncompress the package and run:
337
338         `perl Makefile.PL;       make;       make test;       make install`
339           or if you don't have  `make` but Module::Build is installed, try:
340         `perl    Build.PL; perl Build; perl Build test; perl Build install`
341

FILES

343       Math::BaseCnv requires:
344
345       Math::BigInt          to allow Big summ(), fact(), and choo() results
346
347       Memoize               to cache     summ(), fact(), and choo() results
348
349       Carp                  to allow errors to croak() from calling sub
350

LICENSE

352       Most source code should be Free! Code I have lawful authority over is
353       and shall be!  Copyright: (c) 2003-2016, Pip Stuart.  Copyleft :  This
354       software is licensed under the GNU General Public License
355         (version 3 or later). Please consult
356       <HTTP://GNU.Org/licenses/gpl-3.0.txt>
357         for important information about your freedom. This is Free Software:
358       you
359         are free to change and redistribute it. There is NO WARRANTY, to the
360         extent permitted by law. See <HTTP://FSF.Org> for further
361       information.
362

AUTHOR

364       Pip Stuart <Pip@CPAN.Org>
365
366
367
368perl v5.30.0                      2019-07-26                        BaseCnv(3)
Impressum