1NAME
2 Math::BaseCnv - basic functions to CoNVert between number Bases
3
4VERSION
5 This documentation refers to version 1.14 of Math::BaseCnv, which was
6 released on Sat Jul 30 06:44:28:46 -0500 2016.
7
8SYNOPSIS
9 #!/usr/bin/perl
10 use strict;use warnings;use utf8;use v5.10;use Math::BaseCnv;
11
12 # CoNVert 63 from base-10 (decimal) to base- 2 (binary )
13 my $binary__63 = cnv( 63 , 10, 2 );
14 # CoNVert 111111 from base- 2 (binary ) to base-16 (HEX )
15 my $HEX_____63 = cnv( 111111 , 2, 16 );
16 # CoNVert 3F from base-16 (HEX ) to base-10 (decimal)
17 my $decimal_63 = cnv( '3F', 16, 10 );
18 say "63 dec->bin $binary__63 bin->HEX $HEX_____63 HEX->dec $decimal_63";
19
20DESCRIPTION
21 BaseCnv provides a few simple functions for converting between arbitrary
22 number bases. You're probably better off using Michael Robinton's
23 Math::Base::Convert benchmarked high-performance Perl modules. Another
24 object syntax for number-base conversion is Ken Williams' fine
25 Math::BaseCalc module.
26
27PURPOSE
28 The reason I created BaseCnv was that I needed a simple way to convert
29 quickly between the 3 number bases I use most (10, 16, and 64). It
30 turned out that it was trivial to handle any arbitrary number base that
31 is represented as characters. High-bit ASCII has proven somewhat
32 problemmatic but at least BaseCnv can simply and reliably convert
33 between any possible base between 2 and 64 (or 96). I'm happy with it
34 and employ b64() in places I probably shouldn't now.
35
36USAGE
37 cnv($numb[,$from[,$tobs]])
38 CoNVert the number contained in $numb from its current number base
39 ($from) into the result number base ($tobs).
40
41 When only $numb is provided as a parameter:
42
43 If $numb only contains valid decimal (base 10) digits, it will be
44 converted to HEXADECIMAL (base 16).
45
46 If $numb only contains valid hexadecimal (base 16) digits or begins with
47 '0x', it will be it will be converted to decimal (base 10).
48
49 When only $numb and $from are provided as parameters:
50
51 cnv() assumes that $numb is already in decimal format and uses $from as
52 the $tobs.
53
54 When all three parameters are provided:
55
56 The normal (and most clear) usage of cnv() is to provide all three
57 parameters where $numb is converted from $from base to $tobs.
58
59 cnv() is the only function that is exported from a normal 'use
60 Math::BaseCnv;' command. The other functions below can be imported to
61 local namespaces explicitly or with the following tags:
62
63 :all - every function described here
64 :heX - only cnv(), dec(), heX(), and HEX()
65 :b64 - only cnv(), b10(), b64(), and b64sort()
66 :dig - only dig() and diginit()
67 :sfc - only summ(), fact(), and choo()
68
69 b10($b64n)
70 A shortcut to convert the number given as a parameter ($b64n) from base
71 64 to decimal (base 10).
72
73 b64($b10n)
74 A shortcut to convert the number given as a parameter ($b10n) from
75 decimal (base 10) to base 64.
76
77 b64sort(@b64s)
78 A way to sort b64 strings as though they were decimal numbers.
79
80 dec($b16n)
81 A shortcut to convert the number given as a parameter ($b16n) from
82 hexadecimal (base 16) to decimal (base 10).
83
84 HEX($b10n)
85 A shortcut to convert the number given as a parameter ($b10n) from
86 decimal (base 10) to HEXADECIMAL (base 16) uppercase.
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) lowercase.
91
92 Please read the "NOTES" regarding heX().
93
94 dig(\@newd)
95 Assign the new digit character list to be used in place of the default
96 one. dig() can also alternately accept a string name matching one of the
97 following predefined digit sets:
98
99 'bin' => ['0', '1'],
100 'dna' => ['a', 'c', 'g', 't'],
101 'DNA' => ['A', 'C', 'G', 'T'],
102 'oct' => ['0'..'7'],
103 'dec' => ['0'..'9'],
104 'heX' => ['0'..'9', 'a'..'f'],
105 'HEX' => ['0'..'9', 'A'..'F'],
106 'b36' => ['0'..'9', 'a'..'z'],
107 'B36' => ['0'..'9', 'A'..'Z'],
108 'b62' => ['0'..'9', 'a'..'z', 'A'..'Z'],
109 'b64' => ['0'..'9', 'A'..'Z', 'a'..'z', '.', '_'], # month:C:12 day:V:31
110 'm64' => ['A'..'Z', 'a'..'z', '0'..'9', '+', '/'], # 0-63 from MIME::Base64
111 'iru' => ['A'..'Z', 'a'..'z', '0'..'9', '[', ']'], # P10 server-server protocol used by IRCu daemon
112 'url' => ['A'..'Z', 'a'..'z', '0'..'9', '-', '_'], # MIME::Base64::URLSafe (avoid %2B %2F expansions)
113 'rgx' => ['A'..'Z', 'a'..'z', '0'..'9', '!', '-'], # ReGular eXpression variant
114 'id0' => ['A'..'Z', 'a'..'z', '0'..'9', '_', '-'], # IDentifier style 0
115 'id1' => ['A'..'Z', 'a'..'z', '0'..'9', '.', '_'], # IDentifier style 1
116 'xnt' => ['A'..'Z', 'a'..'z', '0'..'9', '.', '-'], # XML Name Tokens (Nmtoken)
117 'xid' => ['A'..'Z', 'a'..'z', '0'..'9', '_', ':'], # XML identifiers (Name )
118 'sxl' => ['?', '@', 'A'..'Z', '[','\\', ']', '^', # Sixel Base64 from VT100.Net
119 '_', '`', 'a'..'z', '{', '|', '}', '~'],
120 'b85' => ['0'..'9', 'A'..'Z', 'a'..'z', '!', '#', # RFC 1924 for IPv6 addresses like in Math::Base85
121 '$', '%', '&', '(', ')', '*', '+', '-',
122 ';', '<', '=', '>', '?', '@', '^', '_',
123 '`', '{', '|', '}', '~' ],
124 'asc' => [' ', '!', '"', '#', '$', '%', '&', "'", # Base96 7-bit printable 0x20 (space) - 0x7F
125 '(', ')', '*', '+', ',', '-', '.', '/', # (tilde ~) 'ascii' from Math::Base::Convert
126 '0'..'9', ':', ';', '<', '=', '>', '?',
127 '@', 'A'..'Z', '[','\\', ']', '^', '_',
128 '`', 'a'..'z', '{', '|', '}', '~' ],
129 'b96' => ['0'..'9', 'A'..'Z', 'a'..'z', '.', '_', # Base96 but starting with b64 characters
130 ' ', '!', '"', '#', '$', '%', '&', "'",
131 '(', ')', '*', '+', ',', '-', '/', ':',
132 ';', '<', '=', '>', '?', '@', '[','\\',
133 ']', '^', '`', '{', '|', '}', '~' ],
134
135 If no \@newd list or digit set name is provided as a parameter, dig()
136 returns the current character list. It's fine to have many more
137 characters in your current digit set than will be used with your
138 conversions (e.g., using dig('b64') works fine for any cnv() call with
139 $from and $tobs params less than or equal to 64).
140
141 An example of a \@newd parameter for a specified alternate digit set for
142 base 9 conversions is:
143
144 dig( [ qw( n a c h o z y u m ) ] );
145
146 diginit()
147 Resets the used digit list to the initial default order of the
148 predefined digit set: 'b64'. This is simply a shortcut for calling
149 dig('b64') for reinitialization purposes.
150
151 summ($numb)
152 A simple function to calculate a memoized BigInt summation of $numb down
153 to 1.
154
155 fact($numb)
156 A simple function to calculate a memoized BigInt factorial of $numb.
157
158 choo($ennn, $emmm)
159 A simple function to calculate a memoized BigInt function of $ennn
160 choose $emmm.
161
162NOTES
163 The Perl built-in hex() function takes a hex string as a parameter and
164 returns the decimal value (FromBase = 16, ToBase = 10). This notation
165 seems counter-intuitive to me since I prefer to read the code as though
166 a hex() function will turn your parameter into hexadecimal (i.e., I
167 think hex() should hexify your parameter but Perl's built-in does not.).
168 I initially decided to invert the notation for my similar functions, but
169 reconsidered the potential harm possible by introducing exported
170 conflicting opposite behavior into other people's maybe crucial code, so
171 I am falling back on unique casing with heX().
172
173 My b64() function takes a decimal number as a parameter and returns the
174 base64 equivalent (FromBase = 10, ToBase = 64) and my b10() function
175 takes a base64 number (string) and returns the decimal value (FromBase =
176 64, ToBase = 10). My heX() function opposes Perl's built-in hex() (which
177 is similar to my dec()).
178
179 Please think of my dec() and heX() functions as meaning decify and
180 heXify. Also the pronunciation of dec() is 'dess' (not 'deck').
181
182 Error checking is minimal.
183
184 This module does not handle fractional number inputs because I like
185 using the dot (.) character as a standard base64 digit since it makes
186 for clean filenames.
187
188 summ(), fact(), and choo() are general Math function utilities which are
189 unrelated to number-base conversion but I didn't feel like making
190 another separate module just for them so they snuck in here.
191
192 I hope you find Math::BaseCnv useful. TTFN.
193
194CHANGES
195 Revision history for Perl extension Math::BaseCnv:
196
197 - 1.14 G7UM6iSk Sat Jul 30 06:44:28:46 -0500 2016
198 * synchronized README and Changes to updated POD
199
200 - 1.12 G7OMKBCn Sun Jul 24 20:11:12:49 -0500 2016
201 * added digit set 'b96' as a reordering of 'asc'
202
203 - 1.10 G7OMF3ZT Sun Jul 24 15:03:35:29 -0500 2016
204 * added new digit sets from Math::Base::Convert
205
206 * switched all old hex() to distinct new heX() and updated POD to
207 reflect
208
209 * fixed META license to match POD and resolve issue:
210 <HTTPS://RT.CPAN.Org/Public/Bug/Display.html?id=60122> (Thanks again
211 xenoterracide.)
212
213 * removed PT from VERSION to resolve issue:
214 <HTTPS://RT.CPAN.Org/Public/Bug/Display.html?id=60275> (Thanks
215 Alexandr.)
216
217 - 1.8.B59BrZX Mon May 9 11:53:35:33 2011
218 * updated 'url' digit set to URLSafe to resolve
219 <HTTPS://RT.CPAN.Org/Ticket/Display.html?id=60125> (Thanks
220 xenoterracide.)
221
222 * updated license copyright years (already had GPLv3)
223
224 - 1.6.A6FGHKE Tue Jun 15 16:17:20:14 2010
225 * bumped minor version number so they'll keep ascending (without PT
226 comprehension)
227
228 - 1.4.A6FAbEb Tue Jun 15 10:37:14:37 2010
229 * added Math::BigInt code for >64-bit number-base conversions
230
231 * added a bunch more DigitSets: IRCu, URL, RegEx, identifier variants,
232 XML Nmtoken, and XML ID Name
233
234 - 1.4.75O6Pbr Thu May 24 06:25:37:53 2007
235 * added Test::Pod(::Coverage)? tests and PREREQ entries
236
237 * added b85 for IPv6, generated META.yml (with needed newline before
238 EOF) and updated minor version number
239
240 - 1.2.68J9uJQ Sat Aug 19 09:56:19:26 2006
241 * added b64sort() and put POD at bottom
242
243 - 1.2.59M7mRX Thu Sep 22 07:48:27:33 2005
244 * testing Make as primary and BuildPL backup (needing rename for dot)
245
246 - 1.2.59IBlgw Sun Sep 18 11:47:42:58 2005
247 * testing just using Module::Build instead of MakeMaker
248
249 * fixed test 12 which was failing on AMD64
250
251 * added Build.PL to package
252
253 - 1.2.54HK3pB Sun Apr 17 20:03:51:11 2005
254 * removed 128 digit-set since some high-bit characters cause problems
255 on Win32
256
257 * made bin/cnv only executable to go in EXE_FILES
258
259 * made Math::BaseCalc a link in POD and updated License
260
261 - 1.2.45UC8fo Sun May 30 12:08:41:50 2004
262 * tidied POD and increased minor version number since CPAN can't read
263 PT in VERSION
264
265 - 1.0.44E9ljP Wed Apr 14 09:47:45:25 2004
266 * added test for divide-by-zero error in choo()
267
268 * added summ()
269
270 - 1.0.446EIbS Tue Apr 6 14:18:37:28 2004
271 * snuck in fact() and choo()
272
273 - 1.0.42REDir Fri Feb 27 14:13:44:53 2004
274 * changed test.pl to hopefully pass MSWin32-x86-multi-thread
275
276 - 1.0.428LV46 Sun Feb 8 21:31:04:06 2004
277 * broke apart CHANGES to descend chronologically
278
279 * made dec() auto uppercase param since dec(a) was returning 36
280 instead of 10
281
282 - 1.0.41M4GMP Thu Jan 22 04:16:22:25 2004
283 * put cnv in bin/ as EXE_FILES
284
285 - 1.0.418BEPc Thu Jan 8 11:14:25:38 2004
286 * testing new e auto-generate MANIFEST(.SKIP)?
287
288 - 1.0.3CNH37s Tue Dec 23 17:03:07:54 2003
289 * updated POD
290
291 - 1.0.3CG3dIx Tue Dec 16 03:39:18:59 2003
292 * normalized base spelling
293
294 - 1.0.3CD1Vdd Sat Dec 13 01:31:39:39 2003
295 * added ABSTRACT section to WriteMakeFile()
296
297 * changed synopsis example
298
299 * updated all POD indenting
300
301 - 1.0.3CCA5Mi Fri Dec 12 10:05:22:44 2003
302 * removed indenting from POD NAME field
303
304 - 1.0.3CB7M43 Thu Dec 11 07:22:04:03 2003
305 * updated package to coincide with Time::Fields release
306
307 - 1.0.39B36Lv Thu Sep 11 03:06:21:57 2003
308 * synchronized POD with README documentation using new e utility
309
310 * templatized package compilation
311
312 * fixed boundary bugs
313
314 - 1.0.37SLNGN Mon Jul 28 21:23:16:23 2003
315 * first version (and my first Perl module... yay!) put on CPAN
316
317 - 1.0.37JKj3w Sat Jul 19 20:45:03:58 2003
318 * reworked interface from shell utility to package
319
320 - 1.0.3159mLT Sun Jan 5 09:48:21:29 2003
321 * original version
322
323TODO
324 - better error checking
325 - handle fractions and exponents?
326
327INSTALL
328 Please run:
329
330 `perl -MCPAN -e "install Math::BaseCnv"`
331
332 or uncompress the package and run:
333
334 `perl Makefile.PL; make; make test; make install`
335 or if you don't have `make` but Module::Build is installed, try:
336 `perl Build.PL; perl Build; perl Build test; perl Build install`
337
338FILES
339 Math::BaseCnv requires:
340
341 Math::BigInt to allow Big summ(), fact(), and choo() results
342
343 Memoize to cache summ(), fact(), and choo() results
344
345 Carp to allow errors to croak() from calling sub
346
347LICENSE
348 Most source code should be Free! Code I have lawful authority over is
349 and shall be! Copyright: (c) 2003-2016, Pip Stuart. Copyleft : This
350 software is licensed under the GNU General Public License (version 3 or
351 later). Please consult <HTTP://GNU.Org/licenses/gpl-3.0.txt> for
352 important information about your freedom. This is Free Software: you are
353 free to change and redistribute it. There is NO WARRANTY, to the extent
354 permitted by law. See <HTTP://FSF.Org> for further information.
355
356AUTHOR
357 Pip Stuart <Pip@CPAN.Org>
358
359