| 1 |
NAME |
| 2 |
Math::BaseCnv - basic functions to CoNVert between number Bases |
| 3 |
|
| 4 |
VERSION |
| 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 |
|
| 8 |
SYNOPSIS |
| 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 |
|
| 20 |
DESCRIPTION |
| 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 |
|
| 27 |
PURPOSE |
| 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 |
|
| 36 |
USAGE |
| 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 |
|
| 162 |
NOTES |
| 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 |
|
| 194 |
CHANGES |
| 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 |
|
| 323 |
TODO |
| 324 |
- better error checking |
| 325 |
- handle fractions and exponents? |
| 326 |
|
| 327 |
INSTALL |
| 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 |
|
| 338 |
FILES |
| 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 |
|
| 347 |
LICENSE |
| 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 |
|
| 356 |
AUTHOR |
| 357 |
Pip Stuart <[email protected]> |
| 358 |
|