Solstice::List - A basic list object.

  use List;

  my $list = new List;

  $list->add($element);
  $list->add($position, $element);
  $element = $list->get($position);
  $list->remove($position);
  $list->move($oldindex, $newindex);
  $isempty = $list->isEmpty();
  my $size = $list->size();
  $list->clear();

  my $iterator = $list->iterator();
  while ($iterator->hasNext()) {
    my $element = $iterator->next();
  }

package Solstice::List;

# $Id: List.pm 2065 2005-03-05 01:16:48Z tleffler $

use 5.006_000;
use strict;
use warnings;

use base qw(Solstice);

use Carp qw(confess);

use constant TRUE  => 1;
use constant FALSE => 0;

our ($VERSION) = ('$Revision: 2065 $' =~ /^\$Revision:\s*([\d.]*)/);

sub new {
    my ($class, $input) = @_;
    
    my $self = $class->SUPER::new();
    $self->Solstice::List::_init($input);

    return $self;
}

sub clear {
    my ($self) = @_;
    @{$self->{'_list'}} = ();
    return TRUE;
}

sub reverse {
    my ($self) = @_;
    my @list = CORE::reverse(@{$self->{'_list'}});
    $self->{'_list'} = \@list;
    return TRUE;
}

sub push {
    my ($self, $element) = @_;
    CORE::push(@{$self->{'_list'}}, $element);
}

sub pop {
    my ($self) = @_;
    return CORE::pop(@{$self->{'_list'}});
}

sub unshift {
    my ($self, $element) = @_;
    CORE::unshift(@{$self->{'_list'}}, $element);
}

sub shift {
    my ($self) = @_;
    return CORE::shift(@{$self->{'_list'}});
}

sub add {
    my $self = CORE::shift;
    my ($index, $element);

    if ($#_ == 0) { 
        $index   = $self->size();
        $element = CORE::shift;
    
    } elsif ($#_ == 1) {
        $index   = CORE::shift;
        $element = CORE::shift;
        my $size = $self->size();
        
        unless ($self->exists($index) or $index == $size) {
            my $limit = $size + 1;
            confess "add(): Index $index is not between 0 and the allowed maximum ($limit)";
        }
        
        @{$self->{'_list'}}[($index+1)..($size)] = @{$self->{'_list'}}[($index)..($size-1)];
    
    } else {
        confess "add(): Requires at least one argument";
    }

    $self->{'_list'}->[$index] = $element;
    return TRUE;
}

sub addList {
    my ($self, $list) = @_;

    return FALSE unless defined $list;
    
    if ($self->isValidObject($list, 'Solstice::List')) {
        $list = $list->getAll();
    } else {
        return FALSE unless $self->isValidArrayRef($list);
    }
    
    CORE::push(@{$self->{'_list'}}, @$list);
    
    return TRUE;
}

sub replace {
    my ($self, $index, $element) = @_;

    confess "replace(): Requires two arguments"
        unless (defined $index and defined $element);
    
    unless ($self->exists($index)) {
        my $size = $self->size();
        confess "replace(): Index $index is not between 0 and the list size ($size)";
    }

    my $return = $self->{'_list'}->[$index];
    
    $self->{'_list'}->[$index] = $element;
    
    return $return;
}

sub contains {
    confess "contains(): unimplemented";
}

sub exists {
    my ($self, $index) = @_;
    return FALSE unless (defined $index and $index =~ /^\d+$/ and scalar @{$self->{'_list'}} > $index);
}

sub get {
    my ($self, $index) = @_;

    unless ($self->exists($index)) {
        my $size = $self->size();
        confess "get(): Index $index is not between 0 and the list size ($size)";
    }
    return $self->{'_list'}->[$index];
}

sub getAll {
    my ($self) = @_;
    return $self->{'_list'};
}

sub indexOf {
    confess "indexOf(): unimplemented";
}

sub isEmpty {
    my ($self) = @_;
    return !$self->size();
}

sub lastIndexOf {
    confess "lastIndexOf(): unimplemented";
}

sub size {
    my ($self) = @_;
    return scalar @{$self->{'_list'}};
}

sub subList {
    confess "subList(): unimplemented";
}

sub move {
    my ($self, $oldindex, $newindex) = @_;
    my $size = $self->size();

    unless ($self->exists($oldindex)) {
        confess "move(): Source index $oldindex is not between 0 and the list size ($size)";
    }

    unless ($self->exists($newindex)) {
        confess "move(): Target index $newindex is not between 0 and the list size ($size)";
    }
    
    my $element;
    if ($oldindex == $size) {
        # If the element is at the end, just pop it.
        $element = CORE::pop(@{$self->{'_list'}});
    } else {
        # The harder case, where the array gets manipulated, and then pop the last element
        $element = $self->{'_list'}->[$oldindex];
        @{$self->{'_list'}}[($oldindex)..($size-1)] = @{$self->{'_list'}}[($oldindex+1)..($size)];
        CORE::pop(@{$self->{'_list'}});
    }
    # Now put the element back in it's proper place.
    # Easy if it's at the end of the array...
    if ($newindex == $size) {
        CORE::push(@{$self->{'_list'}}, $element);
    } else {
        $size = $self->size(); # List size has changed
        @{$self->{'_list'}}[($newindex + 1)..($size)] = @{$self->{'_list'}}[($newindex)..($size-1)];
        $self->{'_list'}[$newindex] = $element;
    }
    return TRUE;
}

sub remove {
    my ($self, $index) = @_;
    my $size = $self->size();

    unless ($self->exists($index)) {
        confess "remove(): Index $index is not between 0 and the list size ($size)";
    }
    
    my $element;
    if ($index == $size) {
        # If the element is at the end, just pop it.
        $element = CORE::pop(@{$self->{'_list'}});
    } else {
        # Manipulate the array, and then pop the last element
        $element = $self->{'_list'}->[$index];
        @{$self->{'_list'}}[($index)..($size-1)] = @{$self->{'_list'}}[($index+1)..($size)];
        CORE::pop(@{$self->{'_list'}});
    }
    return $element; 
}

sub iterator {
    my ($self) = @_;
    return Solstice::List::Iterator->new($self);
}

sub _init {
    my ($self, $input) = @_;
    
    $self->Solstice::List::clear();
    $self->addList($input) if defined $input; 
    
    return TRUE;
}

sub _getDataArray {
    my ($self) = @_;
    return $self->{'_list'};
}

sub _setDataArray {
    my ($self, $list) = @_;
    $self->{'_list'} = $list;
}


package Solstice::List::Iterator;

use constant TRUE  => 1;
use constant FALSE => 0;

sub new {
    my ($obj, $list) = @_;

    confess("Iterator::new(): Requires a List object") unless (defined $list and $list->isa('Solstice::List'));

    my $self = bless {
        _list  => $list,
        _index => 0,
    }, $obj;

    return $self;
}

sub sort {
    my ($self, $sort_ref) = @_;

    my @new_data;

    if (defined $sort_ref) {
        # $a and $b are package variables, so we want to copy $a and $b 
        # into the namespace of the caller. Since we're doing this work 
        # for every sort call, we had to make a block based sort instead 
        # of a usersub sort, and so we had to explicitely call our sorting 
        # subroutine reference.  
        my $calling_package = (caller)[0];
        { 
            no strict 'refs'; ## no critic
            @new_data = CORE::sort { ${"${calling_package}::a"} = $a; ${"${calling_package}::b"} = $b; &$sort_ref($a, $b); } @{$self->{'_list'}->_getDataArray()};
        }
    }
    else {
        @new_data = CORE::sort @{$self->{'_list'}->_getDataArray()};
    }

    my $package = ref $self->{'_list'};
    my $list = $package->new();
    $list->_setDataArray(\@new_data);

    $self->{'_list'} = $list;
    $self->{'_index'} = 0;

    return TRUE;
}

sub hasNext {
    my ($self) = @_;
    return $self->{'_index'} < $self->{'_list'}->size();
}

sub next {
    my ($self) = @_; 
    return undef if $self->{'_index'} >= $self->{'_list'}->size() || (defined $self->{'_end_index'} && $self->{'_index'} >= $self->{'_end_index'});
    return $self->{'_list'}->get($self->{'_index'}++);
}

sub index {
    my ($self) = @_;
    return $self->{'_index'} ? $self->{'_index'} - 1 : $self->{'_index'};
}

sub setStartIndex {
    my $self = shift;
    my $start_index = shift;
    
    return unless defined $start_index;

    $self->{'_index'} = $start_index if $start_index < $self->{'_list'}->size() && $start_index >= 0;
}

sub setEndIndex {
    my $self = shift;
    my $end_index = shift;

    return unless defined $end_index;

    $self->{'_end_index'} = $end_index if $end_index < $self->{'_list'}->size() && $end_index >= 0;
}

1;

__END__