Math::String::Charset::Grouped - A charset of simple charsets for Math::String objects.
use Math::String::Charset::Grouped;
perl5.005, Exporter, Math::BigInt, Math::String::Charset
Exports nothing.
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).
The default charset is the set containing "abcdefghijklmnopqrstuvwxyz" (thus producing always lower case output).
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:
_error
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";
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.
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 and end are synomyms for sets-{1}> and sets-{-1}>, respectively. The will override what you specify in sets and are only for convienence.
start
end
sets-
The resulting charset will always be of order 1, type 1.
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 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.
sets
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 two-character 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 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 in end and start to produce a string with one character. The same can be acomplished by specifying sets-{-1}>.
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 non-empty class of the charset.
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.
$charset->minlen();
Return minimum string length.
$charset->maxlen();
Return maximum string length.
$charset->length();
Return the number of items in the charset, for higher order charsets the number of valid 1-character long strings. Shortcut for $charset->class(1).
$charset->class(1)
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.
$charset->class($order);
Return the number of items in a class.
print $charset->class(5); # how many strings with length 5?
$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
$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);
$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 = $charset->order();
Return the order of the charset: is always 1 for grouped charsets. See also type.
$type = $charset->type();
Return the type of the charset: is always 1 for grouped charsets. See also order.
$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.
$sep = $charset->seperator();
Returns the separator string, or undefined if none is used.
$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.
$charset->first( $length );
Return the first string with a length of $length, according to the charset. See lowest() for the corrospending number.
lowest()
$charset->last( $length );
Return the last string with a length of $length, according to the charset. See highest() for the corrospending number.
highest()
$charset->is_valid();
Check wether a string conforms to the charset set or not.
$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 to 0 to get the error message, otherwise the program will die.
$Math::String::Charset::die_on_error
0
$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()>.
$charset-
$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.
$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 in start.
ones
$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.
$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.
use Math::String::Charset::Grouped; # not ready yet
None doscovered yet.
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 2000-2003.
To install Math::String, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Math::String
CPAN shell
perl -MCPAN -e shell install Math::String
For more information on module installation, please visit the detailed CPAN module installation guide.