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

FreeBSD Manual Pages

  
 
  

home | help
Number::Nary(3)	      User Contributed Perl Documentation      Number::Nary(3)

NAME
       Number::Nary - encode and decode	numbers	as n-ary strings

VERSION
       version 1.100312

SYNOPSIS
       This module lets	you convert numbers into strings that encode the
       number using the	digit set of your choice.  For example,	you could get
       routines	to convert to and from hex like	so:

	 my ($enc_hex, $dec_hex) = n_codec('0123456789ABCDEF');

	 my $hex = $enc_hex->(255);  # sets $hex to FF
	 my $num = $dec_hex->('A0'); # sets $num to 160

       This would be slow and stupid, since Perl already provides the means to
       easily and quickly convert between decimal and hex representations of
       numbers.	 Number::Nary's	utility	comes from the fact that it can	encode
       into bases composed of arbitrary	digit sets.

	 my ($enc, $dec) = n_codec('0123'); # base 4 (for working with nybbles?)

	 # base64
	 my ($enc, $dec) = n_codec(
	   join('', 'A'	.. 'Z',	'a' .. 'z', 0 .. 9, '+', '/', '=')
	 );

FUNCTIONS
   n_codec
	 my ($encode_sub, $decode_sub) = n_codec($digit_string,	\%arg);

       This routine returns a reference	to a subroutine	which will encode
       numbers into the	given set of digits and	a reference which will do the
       reverse operation.

       The digits may be given as a string or an arrayref.  This routine will
       croak if	the set	of digits contains repeated digits, or if there	could
       be ambiguity in decoding	a string of the	given digits.  (Number::Nary
       is overly aggressive about weeding out possibly ambiguous digit sets,
       for the sake of the author's sanity.)

       The encode sub will croak if it is given	input other than a non-
       negative	integer.

       The decode sub will croak if given a string that	contains characters
       not in the digit	string,	or, for	fixed-string digit sets, if the	lenth
       of the string to	decode is not a	multiple of the	length of the
       component digits.

       Valid arguments to be passed in the second parameter are:

	 predecode  - if given,	this coderef will be used to preprocess	strings
		      passed to	the decoder

	 postencode - if given,	this coderef will be used to postprocess strings
		      produced by the encoder

   n_encode
	 my $string = n_encode($value, $digit_string);

       This encodes the	given value into a string using	the given digit
       string.	It is written in terms of "n_codec", above, so it's not
       efficient at all	for multiple uses in one process.

   n_decode
	 my $number = n_decode($string,	$digit_string);

       This is the decoding equivalent to "n_encode", above.

EXPORTS
       "n_codec" is exported by	default.  "n_encode" and "n_decode" are
       exported.

       Pairs of	routines to encode and decode may be imported by using the
       "codec_pair" group as follows:

	 use Number::Nary -codec_pair => { digits => '01234567', -suffix => '8'	};

	 my $encoded = encode8($number);
	 my $decoded = decode8($encoded);

       For more	information on this kind of exporting, see Sub::Exporter.

SECRET ORIGINS
       I originally used this system to	produce	unique worksheet names in
       Excel.  I had a large report generating system that used	Win32::OLE,
       and to keep track of what was where I'd Storable-digest the options
       used to produce each worksheet and then n-ary encode them into the set
       of characters that were valid in	worksheet names.  Working out that set
       of characters was by far	the hardest part.

ACKNOWLEDGEMENTS
       Thanks, Jesse Vincent.  When I remarked,	on IRC,	that this would	be
       trivial to do, he said, "Great.	Would you mind doing it?"  (Well, more
       or less.)  It was a fun little distraction.

       Mark Jason Dominus and Michael Peters offered some useful advice	on how
       to weed out ambiguous digit sets, enabling me to	allow digit sets made
       up of varying-length digits.

SEE ALSO
       Math::BaseCalc is in the	same problem space wth Number::Nary.  It
       provides	only an	OO interface and does not reliably handle
       multicharacter digits or	recognize ambiguous digit sets.

AUTHOR
       Ricardo Signes <rjbs@cpan.org>

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2013 by Ricardo Signes.

       This is free software; you can redistribute it and/or modify it under
       the same	terms as the Perl 5 programming	language system	itself.

perl v5.32.1			  2013-10-07		       Number::Nary(3)

NAME | VERSION | SYNOPSIS | FUNCTIONS | EXPORTS | SECRET ORIGINS | ACKNOWLEDGEMENTS | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

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

home | help