Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
BaseCnv(3)	      User Contributed Perl Documentation	    BaseCnv(3)

NAME
       Math::BaseCnv - basic functions to CoNVert between number Bases

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

SYNOPSIS
	 #!/usr/bin/perl
	 use strict;use	warnings;use utf8;use v5.10;use	Math::BaseCnv;

		     # CoNVert	   63 from base-10 (decimal) to	base- 2	(binary	)
	 my $binary__63	= cnv(	   63 ,	10,  2 );
		     # CoNVert 111111 from base- 2 (binary ) to	base-16	(HEX	)
	 my $HEX_____63	= cnv( 111111 ,	 2, 16 );
		     # CoNVert	   3F from base-16 (HEX	   ) to	base-10	(decimal)
	 my $decimal_63	= cnv(	  '3F',	16, 10 );
	 say "63 dec->bin $binary__63 bin->HEX $HEX_____63 HEX->dec $decimal_63";

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

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

USAGE
   cnv($numb[,$from[,$tobs]])
       CoNVert the number contained in $numb from its current number base
       ($from) into the	result number base ($tobs).

       When only $numb is provided as a	parameter:

       If $numb	only contains valid decimal (base 10) digits, it will be
       converted to HEXADECIMAL	(base 16).

       If $numb	only contains valid hexadecimal	(base 16) digits or begins
       with '0x', it will be it	will be	converted to decimal (base 10).

       When only $numb and $from are provided as parameters:

       cnv() assumes that $numb	is already in decimal format and uses $from as
       the $tobs.

       When all	three parameters are provided:

       The normal (and most clear) usage of cnv() is to	provide	all three
       parameters where	$numb is converted from	$from base to $tobs.

       cnv() is	the only function that is exported from	a normal 'use
       Math::BaseCnv;' command.	The other functions below can be imported to
       local namespaces	explicitly or with the following tags:

	 :all -	every function described here
	 :heX -	only cnv(), dec(), heX(), and HEX()
	 :b64 -	only cnv(), b10(), b64(), and b64sort()
	 :dig -	only dig() and diginit()
	 :sfc -	only summ(), fact(), and choo()

   b10($b64n)
       A shortcut to convert the number	given as a parameter ($b64n) from base
       64 to decimal (base 10).

   b64($b10n)
       A shortcut to convert the number	given as a parameter ($b10n) from
       decimal (base 10) to base 64.

   b64sort(@b64s)
       A way to	sort b64 strings as though they	were decimal numbers.

   dec($b16n)
       A shortcut to convert the number	given as a parameter ($b16n) from
       hexadecimal (base 16) to	decimal	(base 10).

   HEX($b10n)
       A shortcut to convert the number	given as a parameter ($b10n) from
       decimal (base 10) to HEXADECIMAL	(base 16) uppercase.

   heX($b10n)
       A shortcut to convert the number	given as a parameter ($b10n) from
       decimal (base 10) to hexadecimal	(base 16) lowercase.

       Please read the "NOTES" regarding heX().

   dig(\@newd)
       Assign the new digit character list to be used in place of the default
       one. dig() can also alternately accept a	string name matching one of
       the following predefined	digit sets:

	 'bin' => ['0',	'1'],
	 'dna' => ['a',	'c', 'g', 't'],
	 'DNA' => ['A',	'C', 'G', 'T'],
	 'oct' => ['0'..'7'],
	 'dec' => ['0'..'9'],
	 'heX' => ['0'..'9', 'a'..'f'],
	 'HEX' => ['0'..'9', 'A'..'F'],
	 'b36' => ['0'..'9', 'a'..'z'],
	 'B36' => ['0'..'9', 'A'..'Z'],
	 'b62' => ['0'..'9', 'a'..'z', 'A'..'Z'],
	 'b64' => ['0'..'9', 'A'..'Z', 'a'..'z', '.', '_'], # month:C:12 day:V:31
	 'm64' => ['A'..'Z', 'a'..'z', '0'..'9', '+', '/'], # 0-63 from	MIME::Base64
	 'iru' => ['A'..'Z', 'a'..'z', '0'..'9', '[', ']'], # P10 server-server	protocol used by IRCu daemon
	 'url' => ['A'..'Z', 'a'..'z', '0'..'9', '-', '_'], # MIME::Base64::URLSafe (avoid %2B %2F expansions)
	 'rgx' => ['A'..'Z', 'a'..'z', '0'..'9', '!', '-'], # ReGular eXpression variant
	 'id0' => ['A'..'Z', 'a'..'z', '0'..'9', '_', '-'], # IDentifier style 0
	 'id1' => ['A'..'Z', 'a'..'z', '0'..'9', '.', '_'], # IDentifier style 1
	 'xnt' => ['A'..'Z', 'a'..'z', '0'..'9', '.', '-'], # XML Name Tokens (Nmtoken)
	 'xid' => ['A'..'Z', 'a'..'z', '0'..'9', '_', ':'], # XML identifiers (Name   )
	 'sxl' => ['?',	'@', 'A'..'Z', '[','\\', ']', '^',  # Sixel Base64 from	VT100.Net
		   '_',	'`', 'a'..'z', '{', '|', '}', '~'],
	 'b85' => ['0'..'9', 'A'..'Z', 'a'..'z', '!', '#',  # RFC 1924 for IPv6	addresses like in Math::Base85
		   '$',	'%', '&', '(', ')', '*', '+', '-',
		   ';',	'<', '=', '>', '?', '@', '^', '_',
		   '`',	'{', '|', '}', '~'		 ],
	 'asc' => [' ',	'!', '"', '#', '$', '%', '&', "'",  # Base96 7-bit printable 0x20 (space) - 0x7F
		   '(',	')', '*', '+', ',', '-', '.', '/',  #	(tilde ~) 'ascii' from Math::Base::Convert
		   '0'..'9', ':', ';', '<', '=', '>', '?',
		   '@',	'A'..'Z', '[','\\', ']', '^', '_',
		   '`',	'a'..'z', '{', '|', '}', '~'	 ],
	 'b96' => ['0'..'9', 'A'..'Z', 'a'..'z', '.', '_',  # Base96 but starting with b64 characters
		   ' ',	'!', '"', '#', '$', '%', '&', "'",
		   '(',	')', '*', '+', ',', '-', '/', ':',
		   ';',	'<', '=', '>', '?', '@', '[','\\',
		   ']',	'^', '`', '{', '|', '}', '~'	 ],

       If no \@newd list or digit set name is provided as a parameter, dig()
       returns the current character list. It's	fine to	have many more
       characters in your current digit	set than will be used with your
       conversions (e.g., using	dig('b64') works fine for any cnv() call with
       $from and $tobs params less than	or equal to 64).

       An example of a \@newd parameter	for a specified	alternate digit	set
       for base	9 conversions is:

	 dig( [	qw( n a	c h o z	  y u m	) ] );

   diginit()
       Resets the used digit list to the initial default order of the
       predefined digit	set: 'b64'. This is simply a shortcut for calling
       dig('b64') for reinitialization purposes.

   summ($numb)
       A simple	function to calculate a	memoized BigInt	summation of $numb
       down to 1.

   fact($numb)
       A simple	function to calculate a	memoized BigInt	factorial of $numb.

   choo($ennn, $emmm)
       A simple	function to calculate a	memoized BigInt	function  of $ennn
       choose $emmm.

NOTES
       The Perl	built-in hex() function	takes a	hex string as a	parameter and
       returns the decimal value (FromBase = 16, ToBase	= 10). This notation
       seems counter-intuitive to me since I prefer to read the	code as	though
       a hex() function	will turn your parameter into hexadecimal (i.e., I
       think hex() should hexify your parameter	but Perl's built-in does
       not.). I	initially decided to invert the	notation for my	similar
       functions, but reconsidered the potential harm possible by introducing
       exported	conflicting opposite behavior into other people's maybe
       crucial code, so	I am falling back on unique casing with	heX().

       My b64()	function takes a decimal number	as a parameter and returns the
       base64 equivalent (FromBase = 10, ToBase	= 64) and my b10() function
       takes a base64 number (string) and returns the decimal value (FromBase
       = 64, ToBase = 10). My heX() function opposes Perl's built-in hex()
       (which is similar to my dec()).

       Please think of my dec()	and heX() functions as meaning decify and
       heXify. Also the	pronunciation of dec() is 'dess' (not 'deck').

       Error checking is minimal.

       This module does	not handle fractional number inputs because I like
       using the dot (.) character as a	standard base64	digit since it makes
       for clean filenames.

       summ(), fact(), and choo() are general Math function utilities which
       are unrelated to	number-base conversion but I didn't feel like making
       another separate	module just for	them so	they snuck in here.

       I hope you find Math::BaseCnv useful. TTFN.

CHANGES
       Revision	history	for Perl extension Math::BaseCnv:

       - 1.14 G7UM6iSk	Sat Jul	30 06:44:28:46 -0500 2016
	 * synchronized	README and Changes to updated POD

       - 1.12 G7OMKBCn	Sun Jul	24 20:11:12:49 -0500 2016
	 * added digit set 'b96' as a reordering of 'asc'

       - 1.10 G7OMF3ZT	Sun Jul	24 15:03:35:29 -0500 2016
	 * added new digit sets	from Math::Base::Convert

	 * switched all	old hex() to distinct new heX()	and updated POD	to
	 reflect

	 * fixed META license to match POD and resolve issue:
	 <HTTPS://RT.CPAN.Org/Public/Bug/Display.html?id=60122>	(Thanks	again
	 xenoterracide.)

	 * removed PT from VERSION to resolve issue:
	 <HTTPS://RT.CPAN.Org/Public/Bug/Display.html?id=60275>	(Thanks
	 Alexandr.)

       - 1.8.B59BrZX  Mon May  9 11:53:35:33 2011
	 * updated 'url' digit set to URLSafe to resolve
	 <HTTPS://RT.CPAN.Org/Ticket/Display.html?id=60125> (Thanks
	 xenoterracide.)

	 * updated license copyright years (already had	GPLv3)

       - 1.6.A6FGHKE  Tue Jun 15 16:17:20:14 2010
	 * bumped minor	version	number so they'll keep ascending (without PT
	 comprehension)

       - 1.4.A6FAbEb  Tue Jun 15 10:37:14:37 2010
	 * added Math::BigInt code for >64-bit number-base conversions

	 * added a bunch more DigitSets: IRCu, URL, RegEx, identifier
	 variants, XML Nmtoken,	and XML	ID Name

       - 1.4.75O6Pbr  Thu May 24 06:25:37:53 2007
	 * added Test::Pod(::Coverage)?	tests and PREREQ entries

	 * added b85 for IPv6, generated META.yml (with	needed newline before
	 EOF) and updated minor	version	number

       - 1.2.68J9uJQ  Sat Aug 19 09:56:19:26 2006
	 * added b64sort() and put POD at bottom

       - 1.2.59M7mRX  Thu Sep 22 07:48:27:33 2005
	 * testing Make	as primary and BuildPL backup (needing rename for dot)

       - 1.2.59IBlgw  Sun Sep 18 11:47:42:58 2005
	 * testing just	using Module::Build instead of MakeMaker

	 * fixed test 12 which was failing on AMD64

	 * added Build.PL to package

       - 1.2.54HK3pB  Sun Apr 17 20:03:51:11 2005
	 * removed 128 digit-set since some high-bit characters	cause problems
	 on Win32

	 * made	bin/cnv	only executable	to go in EXE_FILES

	 * made	Math::BaseCalc a link in POD and updated License

       - 1.2.45UC8fo  Sun May 30 12:08:41:50 2004
	 * tidied POD and increased minor version number since CPAN can't read
	 PT in VERSION

       - 1.0.44E9ljP  Wed Apr 14 09:47:45:25 2004
	 * added test for divide-by-zero error in choo()

	 * added summ()

       - 1.0.446EIbS  Tue Apr  6 14:18:37:28 2004
	 * snuck in fact() and choo()

       - 1.0.42REDir  Fri Feb 27 14:13:44:53 2004
	 * changed test.pl to hopefully	pass MSWin32-x86-multi-thread

       - 1.0.428LV46  Sun Feb  8 21:31:04:06 2004
	 * broke apart CHANGES to descend chronologically

	 * made	dec() auto uppercase param since dec(a)	was returning 36
	 instead of 10

       - 1.0.41M4GMP  Thu Jan 22 04:16:22:25 2004
	 * put cnv in bin/ as EXE_FILES

       - 1.0.418BEPc  Thu Jan  8 11:14:25:38 2004
	 * testing new e auto-generate MANIFEST(.SKIP)?

       - 1.0.3CNH37s  Tue Dec 23 17:03:07:54 2003
	 * updated POD

       - 1.0.3CG3dIx  Tue Dec 16 03:39:18:59 2003
	 * normalized base spelling

       - 1.0.3CD1Vdd  Sat Dec 13 01:31:39:39 2003
	 * added ABSTRACT section to WriteMakeFile()

	 * changed synopsis example

	 * updated all POD indenting

       - 1.0.3CCA5Mi  Fri Dec 12 10:05:22:44 2003
	 * removed indenting from POD NAME field

       - 1.0.3CB7M43  Thu Dec 11 07:22:04:03 2003
	 * updated package to coincide with Time::Fields release

       - 1.0.39B36Lv  Thu Sep 11 03:06:21:57 2003
	 * synchronized	POD with README	documentation using new	e utility

	 * templatized package compilation

	 * fixed boundary bugs

       - 1.0.37SLNGN  Mon Jul 28 21:23:16:23 2003
	 * first version (and my first Perl module... yay!) put	on CPAN

       - 1.0.37JKj3w  Sat Jul 19 20:45:03:58 2003
	 * reworked interface from shell utility to package

       - 1.0.3159mLT  Sun Jan  5 09:48:21:29 2003
	 * original version

TODO
       - better	error checking
       - handle	fractions and exponents?

INSTALL
       Please run:

	 `perl -MCPAN -e "install Math::BaseCnv"`

       or uncompress the package and run:

	 `perl Makefile.PL;	  make;	      make test;       make install`
	   or if you don't have	 `make`	but Module::Build is installed,	try:
	 `perl	  Build.PL; perl Build;	perl Build test; perl Build install`

FILES
       Math::BaseCnv requires:

       Math::BigInt	     to	allow Big summ(), fact(), and choo() results

       Memoize		     to	cache	  summ(), fact(), and choo() results

       Carp		     to	allow errors to	croak()	from calling sub

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

AUTHOR
       Pip Stuart <Pip@CPAN.Org>

perl v5.32.1			  2016-07-30			    BaseCnv(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | PURPOSE | USAGE | NOTES | CHANGES | TODO | INSTALL | FILES | LICENSE | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Math::BaseCnv&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help