NAME

Math::String::Sequence - defines a sequence (range) of Math::String(s)

SYNOPSIS

        use Math::String::Sequence;
        use Math::String::Charset;

        $seq = Math::String::Sequence->new( a, zzz );              # set a-z
        $seq = Math::String::Sequence->new( a, zzz, ['z'..'a'] );  # set z..a
        $seq = Math::String::Sequence->new(
          { first => 'a', last => 'zzz', charset => ['z'..'a']
          } );                                                     # same
        $x = Math::String->new('a');
        $y = Math::String->new('zz');
        $seq = Math::String::Sequence->new( {
          first => $x, last => $y, } );                            # same

        print "length: ",$seq->length(),"\n";
        print "first: ",$seq->first(),"\n";
        print "last: ",$seq->last(),"\n";
        print "5th: ",$seq->string(5),"\n";
        print "out-of-range: ",$seq->string(10000000),"\n";        # undef

        print "as array:: ",$seq->as_array(),"\n";                 # as array

REQUIRES

perl5.005, Exporter, Math::BigInt, Math::String, Math::String::Charset

EXPORTS

Exports nothing on default, but can export "sequence()".

DESCRIPTION

This module creates a sequence, or range of Math::Strings. Given a first and last string it represents all strings in between, including first and last. The sequence can be reversed, unlike 'A'..'Z', which needs the first argument be smaller than the second.

Default charset: The default charset is the set containing "abcdefghijklmnopqrstuvwxyz" (thus producing always lower case output). If either "first" or "last" is not an Math::String, they will get the given charset or this default.

USEFULL METHODS

new()

            new();

Create a new Math::String::Sequence object. Arguments are the first and last string, and optional charset. You can give a hash ref, that must then contain the keys "first", "last" and "charset".

length()

            $sequence->length();

Returns the amount of strings this sequence contains, aka (last-first)+1.

is_reversed()

            $sequence->is_reversed();

Returns true or false, depending wether the first string in the sequence is smaller than the last.

first()

            $sequence->first($length);

Return the first string in the sequence. The optional argument becomes the new first string.

last()

            $sequence->last($length);

Return the last string in the sequence. The optional argument becomes the new last string.

charset()

            $sequence->charset();

Return a reference to the charset of the Math::String::Sequence object.

string()

            $sequence->string($n);

Returns the Nth string in the sequence, 0 beeing the "first". Negative arguments count backward from "last", just like with arrays.

as_array()

            @array = $sequence->as_array();

Returns the sequence as array of strings. Usefull for emulating things like

        foreach ('a'..'z')
          {
          print "$_\n";
          }

via

        my $sequence = Math::String::Sequence->new('foo','bar');

        foreach ($sequence->as_array())
          {
          print "$_\n";
          }

Beware, might create HUGE arrays!

BUGS

None discovered yet.

LICENSE

This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

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) Tels http://bloodgate.com 2001 - 2005.