1BaseCnv(3) User Contributed Perl Documentation BaseCnv(3)
2
6 Math::BaseCnv - fast functions to CoNVert between number Bases
7
9 This documentation refers to version 1.4.75O6Pbr of Math::BaseCnv,
10 which was released on Thu May 24 06:25:37:53 2007.
11
13 use Math::BaseCnv;
14 # CoNVert 63 from base-10 (decimal) to base- 2 (binary )
16 $binary_63 = cnv( 63, 10, 2 );
17 # CoNVert 111111 from base- 2 (binary ) to base-16 (hex )
18 $hex_63 = cnv( 111111, 2, 16 );
19 # CoNVert 3F from base-16 (hex ) to base-10 (decimal)
20 $decimal_63 = cnv( '3F', 16, 10 );
21 print "63 dec->bin $binary_63 bin->hex $hex_63 hex->dec $decimal_63\n";
22
24 BaseCnv provides a few simple functions for converting between
25 arbitrary number bases. It is as fast as I currently know how to make
26 it (of course relying only on the lovely Perl). If you would rather
27 utilize an object syntax for number-base conversion, please see Ken
28 Williams's <Ken@Forum.Swarthmore.Edu> fine Math::BaseCalc module.
29
31 The reason I created BaseCnv was that I needed a simple way to convert
32 quickly between the 3 number bases I use most (10, 16, && 64). It
33 turned out that it was trivial to handle any arbitrary number base that
34 is represented as characters. High-bit ASCII has proven somewhat
35 problemmatic but at least BaseCnv can simply && realiably convert
36 between any possible base between 2 && 64 (or 85). I'm happy with it
37 && employ b64() in places I probably shouldn't now =).
38
40 cnv($numb[,$from[,$tobs]])
41 CoNVert the number contained in $numb from its current number base
42 ($from) into the result number base ($tobs).
43 When only $numb is provided as a parameter:
45 If $numb only contains valid decimal (base 10) digits, it will be
47 converted to hexadecimal (base 16).
48 If $numb only contains valid hexadecimal (base 16) digits or begins
50 with '0x', it will be it will be converted to decimal (base 10).
51 When only $numb && $from are provided as parameters:
53 cnv() assumes that $numb is already in decimal format && uses $from as
55 the $tobs.
56 When all three parameters are provided:
58 The normal (&& most clear) usage of cnv() is to provide all three
60 parameters where $numb is converted from $from base to $tobs.
61 cnv() is the only function that is exported from a normal 'use
63 Math::BaseCnv;' command. The other functions below can be imported to
64 local namespaces explicitly or with the following tags:
65 :all - every function described here
67 :hex - only dec() && hex()
68 :b64 - only b10() && b64() && b64sort() && cnv()
69 :dig - only dig() && diginit()
70 :sfc - only summ(), fact(), && choo()
71 b10($b64n)
73 A shortcut to convert the number given as a parameter ($b64n) from base
74 64 to decimal (base 10).
75 b64($b10n)
77 A shortcut to convert the number given as a parameter ($b10n) from
78 decimal (base 10) to base 64.
79 b64sort(@b64s)
81 A way to sort b64 strings as though they were decimal numbers.
82 dec($b16n)
84 A shortcut to convert the number given as a parameter ($b16n) from
85 hexadecimal (base 16) to decimal (base 10).
86 hex($b10n)
88 A shortcut to convert the number given as a parameter ($b10n) from
89 decimal (base 10) to hexadecimal (base 16).
90 Please read the "NOTES" regarding hex().
92 dig(\@newd)
94 Assign the new digit character list to be used in place of the default
95 one. dig() can also alternately accept a string name matching one of
96 the following predefined digit sets:
97 'bin' => ['0', '1']
99 'oct' => ['0'..'7']
100 'dec' => ['0'..'9']
101 'hex' => ['0'..'9', 'a'..'f']
102 'HEX' => ['0'..'9', 'A'..'F']
103 'b62' => ['0'..'9', 'a'..'z', 'A'..'Z']
104 'm64' => ['A'..'Z', 'a'..'z', '0'..'9', '+', '/'] # MIME::Base64
105 'b64' => ['0'..'9', 'A'..'Z', 'a'..'z', '.', '_']
106 'b85' => ['0'..'9', 'A'..'Z', 'a'..'z', '!', '#', # RFC 1924 for
107 '$', '%', '&', '(', ')', '*', '+', '-', # IPv6 addrs
108 ';', '<', '=', '>', '?', '@', '^', '_', # like in
109 '`', '{', '|', '}', '~' ] # Math::Base85
110 If no \@newd list or digit set name is provided as a parameter, dig()
112 returns the current character list. It's fine to have many more
113 characters in your current digit set than will be used with your
114 conversions (e.g., using dig('b64') works fine for any cnv() call with
115 $from && $tobs params less than or equal to 64).
116 An example of a \@newd parameter for a specified alternate digit set
118 for base 9 conversions is:
119 dig( [ qw( n a c h o z y u m ) ] );
121 diginit()
123 Resets the used digit list to the initial default order of the
124 predefined digit set: 'b64'. This is simply a shortcut for calling
125 dig('b64') for reinitialization purposes.
126 summ($numb)
128 A simple function to calculate a memoized summation of $numb down to 1.
129 fact($numb)
131 A simple function to calculate a memoized factorial of $numb.
132 choo($ennn, $emmm)
134 A simple function to calculate a memoized function of $ennn choose
135 $emmm.
136
138 The Perl builtin hex() function takes a hex string as a parameter &&
139 returns the decimal value (FromBase = 16, ToBase = 10) but this
140 notation seems counter-intuitive to me since a simple reading of the
141 code suggests that a hex() function will turn your parameter into
142 hexadecimal (i.e., It sounds like Perl's hex() will hexify your
143 parameter but it does not.) so I've decided (maybe foolishly) to invert
144 the notation for my similar functions since it makes more sense to me
145 this way && will be easier to remember (I've had to lookup hex() in the
146 Camel book many times already which was part of the impetus for this
147 module... as well as the gut reaction that sprintf() is not a proper
148 natural inverse function for hex()).
149 This means that my b64() function takes a decimal number as a parameter
151 && returns the base64 equivalent (FromBase = 10, ToBase = 64) && my
152 b10() function takes a base64 number (string) && returns the decimal
153 value (FromBase = 64, ToBase = 10). My hex() function overloads Perl's
154 builtin version with this opposite behavior so my dec() function
155 behaves like Perl's normal hex() function. I know it's confusing &&
156 maybe bad form of me to do this but I like it so much better this way
157 that I'd rather go against the grain.
158 Please think of my dec() && hex() functions as meaning decify &&
160 hexify. Also the pronunciation of dec() is 'dess' (!'deck' which would
161 be the inverse of 'ink' which -- && ++ already do so well). After
162 reading the informative Perl module etiquette guidelines, I now
163 appreciate the need to export as little as is necessary by default. So
164 to be responsible, I have limited BaseCnv exporting to only cnv() under
165 normal circumstances. Please specify the other functions you'd like to
166 import into your namespace or use the tags described above in the cnv()
167 section like:
168 'use Math::BaseCnv qw(:all !:hex);'
170 Error checking is minimal.
172 This module does not handle fractional number inputs because I like
174 using the dot (.) character as a standard base64 digit since it makes
175 for clean filenames.
176 summ(), fact(), && choo() are general Math function utilities which are
178 unrelated to number-base conversion but I didn't feel like making
179 another separate module just for them so they snuck in here.
180 I hope you find Math::BaseCnv useful. Please feel free to e-mail me
182 any suggestions or coding tips or notes of appreciation ("app-ree-see-
183 ay-shun"). Thank you. TTFN.
184
186 - better error checking
187 - handle fractional parts? umm but I like using '.' as a b64 char so
188 ',' comma or some other separator?
189 - What else does BaseCnv need?
190
192 Revision history for Perl extension Math::BaseCnv:
193 - 1.4.75O6Pbr Thu May 24 06:25:37:53 2007
195 * added Test::Pod(::Coverage)? tests && PREREQ entries
196 * added b85 for IPv6, gen'd META.yml (w/ newline before EOF), up'd
198 minor ver
199 - 1.2.68J9uJQ Sat Aug 19 09:56:19:26 2006
201 * added b64sort() && put pod at bottom
202 - 1.2.59M7mRX Thu Sep 22 07:48:27:33 2005
204 * testing Make as primary and BuildPL backup (needing rename for dot)
205 - 1.2.59IBlgw Sun Sep 18 11:47:42:58 2005
207 * testing just using Module::Build instead of MakeMaker
208 * fixed test 12 which was failing on AMD64
210 * added Build.PL to pkg
212 - 1.2.54HK3pB Sun Apr 17 20:03:51:11 2005
214 * removed 128 digit-set since some hi-bit chars cause probs on Win32
215 * made bin/cnv only executable to go in EXE_FILES
217 * made Math::BaseCalc a link in pod && updated License
219 - 1.2.45UC8fo Sun May 30 12:08:41:50 2004
221 * tidied POD && upped minor version number since CPAN can't read PTVR
222 - 1.0.44E9ljP Wed Apr 14 09:47:45:25 2004
224 * added test for div-by-zero error in choo()
225 * added summ()
227 - 1.0.446EIbS Tue Apr 6 14:18:37:28 2004
229 * snuck in fact() && choo()
230 - 1.0.42REDir Fri Feb 27 14:13:44:53 2004
232 * changed test.pl to hopefully pass MSWin32-x86-multi-thread
233 - 1.0.428LV46 Sun Feb 8 21:31:04:06 2004
235 * broke apart CHANGES to descend chronologically
236 * made dec() auto uppercase param since dec(a) was returning 36
238 instead of 10
239 - 1.0.41M4GMP Thu Jan 22 04:16:22:25 2004
241 * put cnv in bin/ as EXE_FILES
242 - 1.0.418BEPc Thu Jan 8 11:14:25:38 2004
244 * testing new e auto-gen MANIFEST(.SKIP)?
245 - 1.0.3CNH37s Tue Dec 23 17:03:07:54 2003
247 * updated POD
248 - 1.0.3CG3dIx Tue Dec 16 03:39:18:59 2003
250 * normalized base spelling
251 - 1.0.3CD1Vdd Sat Dec 13 01:31:39:39 2003
253 * added ABSTRACT section to WriteMakeFile()
254 * changed synopsis example
256 * updated all POD indenting
258 - 1.0.3CCA5Mi Fri Dec 12 10:05:22:44 2003
260 * removed indenting from POD NAME field
261 - 1.0.3CB7M43 Thu Dec 11 07:22:04:03 2003
263 * updated package to coincide with Time::Fields release
264 - 1.0.39B36Lv Thu Sep 11 03:06:21:57 2003
266 * synchronized POD with README documentation using new e utility
267 * templatized package compilation
269 * fixed boundary bugs
271 - 1.0.37SLNGN Mon Jul 28 21:23:16:23 2003
273 * first version (&& my first Perl module... yay!) put on CPAN
274 - 1.0.37JKj3w Sat Jul 19 20:45:03:58 2003
276 * reworked interface from shell utility to package
277 - 1.0.3159mLT Sun Jan 5 09:48:21:29 2003
279 * original version
280
282 Please run:
283 `perl -MCPAN -e "install Math::BaseCnv"`
285 or uncompress the package && run:
287 `perl Makefile.PL; make; make test; make install`
289 or if you don't have `make` but Module::Build is installed
290 `perl Build.PL; perl Build; perl Build test; perl Build install`
291
293 Most source code should be Free! Code I have lawful authority over is
294 && shall be! Copyright: (c) 2003-2007, Pip Stuart. Copyleft : This
295 software is licensed under the GNU General Public License (version 2).
296 Please consult the Free Software Foundation (HTTP://FSF.Org)
297 for important information about your freedom.
298
300 Pip Stuart <Pip@CPAN.Org>
301perl v5.12.0 2007-05-24 BaseCnv(3)