GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  NUMBER::NARY (3)

.ds Aq ’

NAME

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

CONTENTS

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.

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 NUMBER::NARY (3) 2013-10-07

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.