NAME
Math::String::Charset::Grouped  A charset of simple charsets for Math::String objects.
SYNOPSIS
use Math::String::Charset::Grouped;
REQUIRES
perl5.005, Exporter, Math::BigInt, Math::String::Charset
EXPORTS
Exports nothing.
DESCRIPTION
This module lets you create an charset object, which is used to construct Math::String objects.
This object can assign for each position in a Math::String a different simple charset (aka a Math::String::Charset object of order => 1, type => 0).
 Default charset

The default charset is the set containing "abcdefghijklmnopqrstuvwxyz" (thus producing always lower case output).
ERORRS
Upon error, the field _error
stores the error message, then die() is called with this message. If you do not want the program to die (f.i. to catch the errors), then use the following:
use Math::String::Charset::Grouped;
$Math::String::Charset::Grouped::die_on_error = 0;
$a = new Math::String::Charset::Grouped (); # error, empty set!
print $a>error(),"\n";
INTERNAL DETAILS
This object caches certain calculation results (f.i. the number of possible combinations for a certain string length), thus greatly speeding up sequentiell Math::String conversations from string to number, and vice versa.
METHODS
 new()

new();
Create a new Math::Charset::Grouped object.
The constructor takes a HASH reference. The following keys can be used:
minlen Minimum string length, inf if not defined maxlen Maximum string length, +inf if not defined sets hash, table with charsets for the different places start array ref to list of all valid (starting) characters end array ref to list of all valid ending characters sep separator character, none if undef
start
andend
are synomyms forsets>{1}
andsets>{1}
, respectively. The will override what you specify in sets and are only for convienence.The resulting charset will always be of order 1, type 1.
 start

start
contains an array reference to all valid starting characters, e.g. no valid string can start with a character not listed here.The same can be acomplished by specifying
sets>{1}
.  sets

sets
contains a hash reference, each key of the hash indicates an index. Each of the hash entries MUST point either to an ARRAY reference or a Math::String::Charset of order 1, type 0.Positive indices (greater than one) count from the left side, negative from the right. 0 denotes the default charset to be used for unspecified places.
The index count will be used for all string length, so that
sets>{2}
always refers to the second character from the left, no matter how many characters the string actually has.At each of the position indexed by a key, the appropriate charset will be used.
Example for specifying that strings must start with upper case letters, followed by lower case letters and can end in either a lower case letter or a number:
sets => { 0 => ['a'..'z'], # the default 1 => ['A'..'Z'], # first character is always A..Z 1 => ['a'..'z','0'..'9'], # last is q..z,0..9 }
In case of overlapping, a cross between the two charsets will be used, that contains all characters from both of them. The default charset will only be used when none of the charsets counting from left or right matches.
Given the definition above, valid strings with length 1 consist of:
['A'..'Z','0'..'9']
Imagine having specified a set at position 2, too:
sets => { 0 => ['a'..'z'], # the default 1 => ['A'..'Z'], # first character is always A..Z 2 => ['','+','2'], # second character is  or + 1 => ['a'..'z','0'..'9'], # last is q..z,0..9 }
For strings of length one, this character set will not be used. For strings with length 2 it will be crossed with the set at 1, so that the twocharacter long strings will start with ['A'..'Z'] and end in the characters ['','+','2','0','1','3'..'9'].
The cross is build from left to right, that is first come all characters that are in the set counting from left, and then all characters in the set counting from right, except the ones that are in both (since no doubles must be used).
 end

end
contains an array reference to all valid ending characters, e.g. no valid string can end with a character not listed here. Note that strings of length 1 start and end with their only character, so the character must be listed inend
andstart
to produce a string with one character. The same can be acomplished by specifyingsets>{1}
.  minlen

Optional minimum string length. Any string shorter than this will be invalid. Must be shorter than a (possible defined) maxlen. If not given is set to inf. Note that the minlen might be adjusted to a greater number, if it is set to 1 or greater, but there are not valid strings with 2,3 etc. In this case the minlen will be set to the first nonempty class of the charset.
 maxlen

Optional maximum string length. Any string longer than this will be invalid. Must be longer than a (possible defined) minlen. If not given is set to +inf.
 minlen()

$charset>minlen();
Return minimum string length.
 maxlen()

$charset>maxlen();
Return maximum string length.
 length()

$charset>length();
Return the number of items in the charset, for higher order charsets the number of valid 1character long strings. Shortcut for
$charset>class(1)
.  count()

Returns the count of all possible strings described by the charset as a positive BigInt. Returns 'inf' if no maxlen is defined, because there should be no upper bound on how many strings are possible.
If maxlen is defined, forces a calculation of all possible class() values and may therefore be very slow on the first call, it also caches possible lot's of values if maxlen is very high.
 class()

$charset>class($order);
Return the number of items in a class.
print $charset>class(5); # how many strings with length 5?
 char()

$charset>char($nr);
Returns the character number $nr from the set, or undef.
print $charset>char(0); # first char print $charset>char(1); # second char print $charset>char(1); # last one
 lowest()

$charset>lowest($length);
Return the number of the first string of length $length. This is equivalent to (but much faster):
$str = $charset>first($length); $number = $charset>str2num($str);
 highest()

$charset>highest($length);
Return the number of the last string of length $length. This is equivalent to (but much faster):
$str = $charset>first($length+1); $number = $charset>str2num($str); $number;
 order()

$order = $charset>order();
Return the order of the charset: is always 1 for grouped charsets. See also type.
 type()

$type = $charset>type();
Return the type of the charset: is always 1 for grouped charsets. See also order.
 charlen()

$character_length = $charset>charlen();
Return the length of one character in the set. 1 or greater. All charsets used in a grouped charset must have the same length, unless you specify a seperator char.
 seperator()

$sep = $charset>seperator();
Returns the separator string, or undefined if none is used.
 chars()

$chars = $charset>chars( $bigint );
Returns the number of characters that the string would have, when you would convert $bigint (Math::BigInt or Math::String object) back to a string. This is much faster than doing
$chars = length ("$math_string");
since it does not need to actually construct the string.
 first()

$charset>first( $length );
Return the first string with a length of $length, according to the charset. See
lowest()
for the corrospending number.  last()

$charset>last( $length );
Return the last string with a length of $length, according to the charset. See
highest()
for the corrospending number.  is_valid()

$charset>is_valid();
Check wether a string conforms to the charset set or not.
 error()

$charset>error();
Returns "" for no error or an error message that occured if construction of the charset failed. Set
$Math::String::Charset::die_on_error
to0
to get the error message, otherwise the program will die.  start()

$charset>start();
In list context, returns a list of all characters in the start set, that is the ones used at the first string position. In scalar context returns the lenght of the start set.
Think of the start set as the set of all characters that can start a string with one or more characters. The set for one character strings is called ones and you can access if via
$charset>ones()
.  end()

$charset>end();
In list context, returns a list of all characters in the end set, aka all characters a string can end with. In scalar context returns the lenght of the end set.
 ones()

$charset>ones();
In list context, returns a list of all strings consisting of one character. In scalar context returns the lenght of the ones set.
This list is the cross of start and end.
Think of a string of only one character as if it starts with and ends in this character at the same time.
The order of the chars in
ones
is the same ordering as instart
.  prev()

$string = Math::String>new( ); $charset>prev($string);
Give the charset and a string, calculates the previous string in the sequence. This is faster than decrementing the number of the string and converting the new number to a string. This routine is mainly used internally by Math::String and updates the cache of the given Math::String.
 next()

$string = Math::String>new( ); $charset>next($string);
Give the charset and a string, calculates the next string in the sequence. This is faster than incrementing the number of the string and converting the new number to a string. This routine is mainly used internally by Math::String and updates the cache of the given Math::String.
EXAMPLES
use Math::String::Charset::Grouped;
# not ready yet
BUGS
None doscovered yet.
AUTHOR
If you use this module in one of your projects, then please email me. I want to hear about how my code helps you ;)
This module is (C) Copyright by Tels http://bloodgate.com 20002003.