—

              
#############################################################################
# Math/String/Sequence.pm -- defines a sequence or range of strings.
#
# Copyright (C) 2001 - 2005 by Tels.
#############################################################################
# the following hash values are used
# _first : first string
# _last  : last string
# _set   : charset for first/last
# _size  : last-first
# _rev   : 1 if reversed sequence
package Math::String::Sequence;
use vars qw($VERSION);
$VERSION = '1.06';      # Current version of this package
require  5.005;         # requires this Perl version or later
use Exporter;
@ISA = qw(Exporter);
@EXPORT_OK = qw(sequence);
use Math::String;
use Math::String::Charset;
use strict;
my $class = "Math::String::Sequence";
# some shortcuts for easier life
sub sequence
  {
  # exportable version of new
  $class->new(@_);
  }
###############################################################################
# constructor
sub new
  {
  # takes the following arguments:
  # first, last: Math:Strings or scalars
  # charset: optional, if you pass a scalar as first or last
  my $class = shift;
  $class = ref($class) || $class;
  my $args;
  if (ref $_[0] eq 'HASH')
    {
    $args = shift;
    }
  else
    {
    $args->{first} = shift;
    $args->{last} = shift;
    $args->{charset} = shift;
    }
  my $self = {};
  bless $self, $class;
  if (ref $args eq $class)
    {
    # make copy
    for (qw/_first _last/)
      {
      $self->{$_} = Math::String->new($args->{$_});
      }
    return $self; 
    }
  my $first = $args->{first};
  my $last = $args->{last};
  my $set = $args->{charset};
  $first = Math::String->new($first,$set) unless ref $first;
  $last = Math::String->new($last,$set) unless ref $last;
  
  die ("first is NaN") if $first->is_nan();
  die ("last is NaN") if $last->is_nan();
  #die ("$first is not smaller than $last") if 
  # adjustment by $self->_size(): $self->{_rev} = $first > $last ? 1 : 0; 
  bless $self, $class;
  $self->{_first} = $first;
  $self->{_last} = $last;
  $self->_initialize();
  $self; 
  }
#############################################################################
# private, initialize self 
sub _initialize
  {
  # init sequence
  my $self = shift;
  $self->_size();
  $self->{_set} = $self->{_first}->{_set};
  $self;
  }
sub _size
  {
  # calculate new size and adjust _rev
  my $self = shift;
  $self->{_rev} = $self->{_first} < $self->{_last} ? 0 : 1; 
  $self->{_size} = $self->{_last} - $self->{_first};
  $self->{_size} = $self->{_size}->babs()->as_number();
  $self->{_size}++;
  $self;
  }
#############################################################################
# public
sub charset
  {
  my $self = shift;
  $self->{_first}->{_set};
  }
sub length
  {
  my $self = shift;
  $self->{_size};
  }
sub is_reversed
  {
  # return true if the sequence is reversed, or false
  my $self = shift;
  $self->{_rev};
  }
sub first
  {
  my $self = shift;
  if (defined $_[0])
    {
    $self->{_first} = shift;
    $self->{_first} = Math::String->new($self->{_first},$self->{_set})
      unless ref $self->{_first};
    $self->_size();
    }
  $self->{_first};
  }
sub last
  {
  my $self = shift;
  if (defined $_[0])
    {
    $self->{_last} = shift;
    $self->{_last} = Math::String->new($self->{_last},$self->{_set})
      unless ref $self->{_last};
    $self->_size();
    }
  $self->{_last};
  }
sub string
  {
  # return the Nth string in sequence or undef for out-of-range
  my $self = shift;
  my $nr = shift; $nr = 0 if !defined $nr;
  $nr = Math::BigInt->new($nr) unless ref $nr;
  my $n;
  if ($self->{_rev})
    {
    if ($nr < 0)
      {
      $n = $self->{_last}-$nr; $n--;
      }
    else
      {
      $n = $self->{_first}-$nr;
      } 
    return if $n > $self->{_first} || $n < $self->{_last};
    }
  else
    {
    if ($nr < 0)
      {
      $n = $self->{_last}+$nr; $n++;
      }
    else
      {
      $n = $self->{_first}+$nr;
      } 
    return if $n > $self->{_last} || $n < $self->{_first};
    }
  $n;
  } 
sub error
  {
  my $self = shift;
  $self->{_set}->error();
  }
sub as_array
  {
  # return the sequence as array of strings
  my $x = shift;
  my @a;
  my $f = $x->{_first}; my $l = $x->{_last};
  if ($x->{_rev})
    {
    while ($f >= $l) { push @a,$f->copy(); $f->bdec(); }
    }
  else
    {
    while ($f <= $l) { push @a,$f->copy(); $f->binc(); }
    }
  @a;
  }
__END__
#############################################################################
HideShow 142 lines of Pod
=head1 NAME
Math::String::Sequence - defines a sequence (range) of Math::String(s)
=head1 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
=head1 REQUIRES
perl5.005, Exporter, Math::BigInt, Math::String, Math::String::Charset
=head1 EXPORTS
Exports nothing on default, but can export C<sequence()>.
=head1 DESCRIPTION
This module creates a sequence, or range of Math::Strings. Given a B<first> and
B<last> string it represents all strings in between, including B<first> and
B<last>. The sequence can be reversed, unlike 'A'..'Z', which needs the first
argument be smaller than the second.
=over 1
=item Default charset
The default charset is the set containing "abcdefghijklmnopqrstuvwxyz"
(thus producing always lower case output). If either C<first> or C<last> is
not an Math::String, they will get the given charset or this default.
=back
=head1 USEFULL METHODS
=head2 B<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 C<first>, C<last> and C<charset>.
=head2 B<length()>
            $sequence->length();
Returns the amount of strings this sequence contains, aka (last-first)+1.
=head2 B<is_reversed()>
            $sequence->is_reversed();
Returns true or false, depending wether the first string in the sequence
is smaller than the last.
=head2 B<first()>
            $sequence->first($length);
Return the first string in the sequence. The optional argument becomes the
new first string.
=head2 B<last()>
            $sequence->last($length);
Return the last string in the sequence. The optional argument becomes the
new last string.
=head2 B<charset()>
            $sequence->charset();
Return a reference to the charset of the Math::String::Sequence object.
=head2 B<string()>
            $sequence->string($n);
Returns the Nth string in the sequence, 0 beeing the C<first>. Negative
arguments count backward from C<last>, just like with arrays.
=head2 B<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!
=head1 BUGS
None discovered yet.
=head1 LICENSE
This program is free software; you may redistribute it and/or modify it
under the same terms as Perl itself.
=head1 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.
=cut