Number::Nary - encode and decode numbers as n-ary strings
version 1.100312
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, '+', '/', '=')
);
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
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.
my $number = n_decode($string, $digit_string);
This is the decoding equivalent to "n_encode", above.
"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.
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.
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.
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.
Ricardo Signes <rjbs@cpan.org>
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.