Tie-Array-Iterable-0.03/0040755000175000017500000000000007375075224014721 5ustar mneylonmneylonTie-Array-Iterable-0.03/README0100755000175000017500000000205007375074023015572 0ustar mneylonmneylonTie/Array/Iterable version 0.01 =============================== Tie::Array::Iterable is a implementation of iterators for perl lists and arrays; while mimicing the C++ STL counterpart, it's not a complete clone of them. Iterators allow one to progress through lists without having to worry about changes to the list that may occur (specifically operations like splice, pop/push, and shift/unshift), as well as to 'save' one's position in a iteration of an array. While perl's builtin iteration functions (for/foreach) work well, they cannot handle these situations easily. INSTALLATION To install this module type the following: perl Makefile.PL make make test make install DEPENDENCIES Tie::Array::Iterable extends from the standard library Tie::Array. Testing of the module uses Test::More. COPYRIGHT AND LICENCE Copyright 2001 by Michael K. Neylon . This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See http://www.perl.com/perl/misc/Artistic.html Tie-Array-Iterable-0.03/Makefile.PL0100644000175000017500000000102707375074023016664 0ustar mneylonmneylonuse ExtUtils::MakeMaker; # See lib/ExtUtils/MakeMaker.pm for details of how to influence # the contents of the Makefile that is written. WriteMakefile( 'NAME' => 'Tie::Array::Iterable', 'VERSION_FROM' => 'Iterable.pm', # finds $VERSION 'PREREQ_PM' => {Test::More => 0.33}, # e.g., Module::Name => 1.1 ($] >= 5.005 ? ## Add these new keywords supported since 5.005 (ABSTRACT_FROM => 'Iterable.pm', # retrieve abstract from module AUTHOR => 'Michael K. Neylon ') : ()), ); Tie-Array-Iterable-0.03/Iterable/0040755000175000017500000000000007375075224016450 5ustar mneylonmneylonTie-Array-Iterable-0.03/Iterable/ForwardIterator.pm0100755000175000017500000000743207375074656022142 0ustar mneylonmneylon#!/usr/bin/perl -w package Tie::Array::Iterable::ForwardIterator; #============================================================================= # # $Id: ForwardIterator.pm,v 0.03 2001/11/16 02:27:58 mneylon Exp $ # $Revision: 0.03 $ # $Author: mneylon $ # $Date: 2001/11/16 02:27:58 $ # $Log: ForwardIterator.pm,v $ # Revision 0.03 2001/11/16 02:27:58 mneylon # Fixed packing version variables # # Revision 0.01.01.2 2001/11/16 02:12:16 mneylon # Added code to clean up iterators after use # clear_iterators() now not needed, simply returns 1; # # Revision 0.01.01.1 2001/11/15 01:41:21 mneylon # Branch from 0.01 for new features # # Revision 0.01 2001/11/11 18:36:14 mneylon # Initial Release # # #============================================================================= use 5.006; use strict; my $FORWARDID; my %FORWARDITERS; BEGIN { use Exporter (); use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS); ( $VERSION ) = '$Revision: 0.03 $ ' =~ /\$Revision:\s+([^\s]+)/; @ISA = qw( Exporter ); @EXPORT = qw( ); @EXPORT_OK = qw( ); %EXPORT_TAGS = ( ); } sub new { my $class = shift; my $iterarray = shift; my $pos = shift || 0; warn "Must be created from a Tie::Array::Iterable" unless ( UNIVERSAL::isa( $iterarray, "Tie::Array::Iterable" ) ); my %data = ( array => $iterarray, pos => $pos, id => ++$FORWARDID ); $FORWARDITERS{ $data{ id } } = \%data; return bless \%data, $class; } sub DESTROY { my $self = shift; $self->{ array }->_remove_forward_iterator( $self->{ id } ); } sub at_start () { my $self = shift; if ( $self->{ pos } <= 0 ) { return 1; } else { return 0; } } sub at_end () { my $self = shift; if ( $self->{ pos } >= scalar @{ $self->{ array } } ) { return 1; } else { return 0; } } sub to_start () { my $self = shift; $self->{ pos } = 0; } sub to_end () { my $self = shift; $self->{ pos } = scalar @{ $self->{ array } }; } sub value { my $self = shift; if ( $self->at_end() ) { return undef }; return $self->{ array }->[ $self->{ pos } ]; } sub set_value { my $self = shift; my $value = shift; if ( $self->at_end() ) { return undef; }; return ( $self->{ array }->[ $self->{ pos } ] = $value ); } sub index { my $self = shift; return $self->{ pos }; } sub set_index { my $self = shift; my $index = shift; if ( $index < 0 ) { $index = 1; } if ( $index > scalar @{ $self->{ array } } ) { $index = scalar @{ $self->{ array } }; } $self->{ pos } = $index; } sub next () { my $self = shift; if ( $self->at_end() ) { return undef; } $self->{ pos }++; return $self->value(); } sub prev () { my $self = shift; if ( $self->at_start() ) { return undef; } $self->{ pos }--; return $self->value(); } sub forward { my $self = shift; my $steps = shift; die "Number of steps must be non-negative" if $steps < 0; $steps = 1 if ( !$steps && $steps ne "0" ); my $value = $self->value(); $value = $self->next() for ( 1..$steps ); return $value; } sub backward { my $self = shift; my $steps = shift; die "Number of steps must be non-negative" if $steps < 0; $steps = 1 if ( !$steps && $steps ne "0" ); my $value = $self->value(); $value = $self->prev() for ( 1..$steps ); return $value; } sub _lookup ($) { my $id = shift; return $FORWARDITERS{ $id }; } sub _id { my $self = shift; return $self->{ id }; } 1; __END__ =head1 NAME Tie::Array::Iterable::ForwardIterator - Forward Iterator object =head1 DESCRIPTION Please see the L documentation for full usage. =head1 AUTHOR Michael K. Neylon Emneylon-pm@masemware.comE =head1 COPYRIGHT Copyright 2001 by Michael K. Neylon Emneylon-pm@masemware.comE. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See http://www.perl.com/perl/misc/Artistic.html =cutTie-Array-Iterable-0.03/Iterable/BackwardIterator.pm0100755000175000017500000000744607375074656022261 0ustar mneylonmneylon#!/usr/bin/perl -w package Tie::Array::Iterable::BackwardIterator; #============================================================================= # # $Id: BackwardIterator.pm,v 0.03 2001/11/16 02:27:58 mneylon Exp $ # $Revision: 0.03 $ # $Author: mneylon $ # $Date: 2001/11/16 02:27:58 $ # $Log: BackwardIterator.pm,v $ # Revision 0.03 2001/11/16 02:27:58 mneylon # Fixed packing version variables # # Revision 0.01.01.2 2001/11/16 02:12:16 mneylon # Added code to clean up iterators after use # clear_iterators() now not needed, simply returns 1; # # Revision 0.01.01.1 2001/11/15 01:41:21 mneylon # Branch from 0.01 for new features # # Revision 0.01 2001/11/11 18:36:14 mneylon # Initial Release # # #============================================================================= use 5.006; use strict; my $BACKWARDID; my %BACKWARDITERS; BEGIN { use Exporter (); use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS); ( $VERSION ) = '$Revision: 0.03 $ ' =~ /\$Revision:\s+([^\s]+)/; @ISA = qw( Exporter ); @EXPORT = qw( ); @EXPORT_OK = qw( ); %EXPORT_TAGS = ( ); } sub new { my $class = shift; my $iterarray = shift; my $pos = shift || scalar @$iterarray; warn "Must be created from a Tie::Array::Iterable" unless ( UNIVERSAL::isa( $iterarray, "Tie::Array::Iterable" ) ); my %data = ( array => $iterarray, pos => $pos, id => ++$BACKWARDID ); $BACKWARDITERS{ $data{ id } } = \%data; return bless \%data, $class; } sub DESTORY { my $self = shift; $self->{ array }->_remove_backward_iterator( $self->{ id } ); } sub at_start { my $self = shift; if ( $self->{ pos } >= scalar @{ $self->{ array } } ) { return 1; } else { return 0; } } sub at_end { my $self = shift; if ( $self->{ pos } <= 0 ) { return 1; } else { return 0; } } sub to_start { my $self = shift; $self->{ pos } = scalar @{ $self->{ array } }; } sub to_end { my $self = shift; $self->{ pos } = 0; } sub value { my $self = shift; if ( $self->at_end() ) { return undef }; return $self->{ array }->[ $self->{ pos } - 1 ]; } sub set_value { my $self = shift; my $value = shift; if ( $self->at_end() ) { return undef; }; return ( $self->{ array }->[ $self->{ pos } - 1 ] = $value ); } sub index { my $self = shift; return $self->{ pos }; } sub set_index { my $self = shift; my $index = shift(); if ( $index < 0 ) { $index = 1; } if ( $index > scalar @{ $self->{ array } } ) { $index = scalar @{ $self->{ array } }; } $self->{ pos } = $index; } sub next { my $self = shift; if ( $self->at_end() ) { return undef; } $self->{ pos }--; return $self->value(); } sub prev { my $self = shift; if ( $self->at_start() ) { return undef; } $self->{ pos }++; return $self->value(); } sub forward { my $self = shift; my $steps = shift; die "Number of steps must be non-negative" if $steps < 0; $steps = 1 if ( !$steps && $steps ne "0" ); my $value = $self->value(); $value = $self->next() for ( 1..$steps ); return $value; } sub backward { my $self = shift; my $steps = shift; die "Number of steps must be non-negative" if $steps < 0; $steps = 1 if ( !$steps && $steps ne "0" ); my $value = $self->value(); $value = $self->prev() for ( 1..$steps ); return $value; } sub _lookup ($) { return $BACKWARDITERS{ +shift }; } sub _id { my $self = shift; return $self->{ id }; } 1; __END__ =pod =head1 NAME Tie::Array::Iterable::ForwardIterator - Forward Iterator object =head1 DESCRIPTION Please see the L documentation for full usage. =head1 AUTHOR Michael K. Neylon Emneylon-pm@masemware.comE =head1 COPYRIGHT Copyright 2001 by Michael K. Neylon Emneylon-pm@masemware.comE. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See http://www.perl.com/perl/misc/Artistic.html =cutTie-Array-Iterable-0.03/Changes0100644000175000017500000000045407375074654016222 0ustar mneylonmneylonRevision history for Perl extension Tie::Array::Iterable. $Log: Changes,v $ Revision 0.03 2001/11/16 02:27:56 mneylon Fixed packing version variables Revision 0.01.01.1 2001/11/15 01:41:19 mneylon Branch from 0.01 for new features Revision 0.01 2001/11/11 18:36:10 mneylon Initial Release Tie-Array-Iterable-0.03/t/0040755000175000017500000000000007375075224015164 5ustar mneylonmneylonTie-Array-Iterable-0.03/t/forward.t0100755000175000017500000001234207375075202017013 0ustar mneylonmneylon#!/usr/bin/perl -w #============================================================================= # # $Id: forward.t,v 0.03 2001/11/16 02:31:30 mneylon Exp $ # $Revision: 0.03 $ # $Author: mneylon $ # $Date: 2001/11/16 02:31:30 $ # $Log: forward.t,v $ # Revision 0.03 2001/11/16 02:31:30 mneylon # Updating to fix version problems # # Revision 0.02 2001/11/16 02:21:31 mneylon # Update to version 0.02 # # Revision 0.01.01.1 2001/11/15 01:43:52 mneylon # Branch for 0.01 changes # # Revision 0.01 2001/11/11 18:40:57 mneylon # Initial release # # #============================================================================= # Forward iterator testing use strict; use Tie::Array::Iterable; use Test::More tests => 62; my @array = ( 0 .. 10 ); my $iterarray = new Tie::Array::Iterable( @array ); my $iter = $iterarray->from_start(); is( $iter->value(), 0, "Forward, value from start" ); is( $iter->index(), 0, "Forward, index from start" ); ok( $iter->at_start(), "Forward, at start" ); $iter->prev(); # Should go nowhere is( $iter->value(), 0, "Forward, prev value from start" ); is( $iter->index(), 0, "Forward, prev index from start" ); ok( $iter->at_start(), "Forward, at start with prev" ); $iter->next(); # now go to 1 is( $iter->value(), 1, "Forward, next value from start" ); is( $iter->index(), 1, "Forward, next index from start" ); ok( !$iter->at_start(), "Forward, not at start with next" ); $iter->forward(2); # now to 3 is( $iter->value(), 3, "Forward, forward in array" ); is( $iter->index(), 3, "Forward, forward in array" ); $iter->forward(20); # now way past end, back to end is( $iter->value(), undef, "Forward, forward past end" ); is( $iter->index(), 11, "Forward, forward past end" ); ok( $iter->at_end(), "Forward, at end with forward" ); $iter->next(); # again try to move past end is( $iter->value(), undef, "Forward, next past end" ); is( $iter->index(), 11, "Forward, next past end" ); ok( $iter->at_end(), "Forward, at end with next" ); $iter->prev(); # should be able to go back now is( $iter->value(), 10, "Forward, prev from end" ); is( $iter->index(), 10, "Forward, prev from end" ); ok( !$iter->at_end(), "Forward, not at end with prev" ); $iter->backward(3); #back to 7 is( $iter->value(), 7, "Forward, backward from end" ); is( $iter->index(), 7, "Forward, backward from end" ); $iter->backward(20); #overshoot is( $iter->value(), 0, "Forward, backward past start" ); is( $iter->index(), 0, "Forward, backward past start" ); $iter->to_end(); is( $iter->value(), undef, "Forward, next past end" ); is( $iter->index(), 11, "Forward, next past end" ); ok( $iter->at_end(), "Forward, at end with next" ); $iter->to_start(); is( $iter->value(), 0, "Forward, to_start" ); is( $iter->index(), 0, "Forward, to_start" ); ok( $iter->at_start(), "Forward, to_start" ); # Shift/unshift at start shift @$iterarray; is( $iter->value(), 1, "Forward, shift at start" ); is( $iter->index(), 0, "Forward, shift at start" ); unshift @$iterarray, 0; is( $iter->value(), 0, "Forward, unshift at start" ); is( $iter->index(), 0, "Forward, unshift at start" ); # Shift/unshift elsewhere besides start $iter->forward(4); shift @$iterarray; is( $iter->value(), 4, "Forward, shift in middle" ); is( $iter->index(), 3, "Forward, shift in middle" ); unshift @$iterarray, 0; is( $iter->value(), 4, "Forward, unshift in middle" ); is( $iter->index(), 4, "Forward, unshift in middle" ); # Push/pop elsewhere besides end pop @$iterarray; is( $iter->value(), 4, "Forward, pop in middle" ); is( $iter->index(), 4, "Forward, pop in middle" ); push @$iterarray, 10; is( $iter->value(), 4, "Forward, push in middle" ); is( $iter->index(), 4, "Forward, push in middle" ); # Push/pop at end $iter->to_end(); pop @$iterarray; is( $iter->value(), undef, "Forward, pop at end" ); is( $iter->index(), 10, "Forward, pop at end" ); push @$iterarray, 10; is( $iter->value(), undef, "Forward, push at end" ); is( $iter->index(), 11, "Forward, push at end" ); # Splice before iterator (but not including it) my @elems; $iter->backward( 6 ); # Pointing to 5 @elems = splice @$iterarray, 0, 3; is( $iter->value(), 5, "Forward, splice before" ); is( $iter->index(), 2, "Forward, splice before" ); splice @$iterarray, 0, 0, @elems; is( $iter->value(), 5, "Forward, splice before" ); is( $iter->index(), 5, "Forward, splice before" ); # Splice including iterator @elems = splice @$iterarray, 4, 3; is( $iter->value(), 7, "Forward, splice including" ); is( $iter->index(), 4, "Forward, splice including" ); splice @$iterarray, 4, 0, @elems; is( $iter->value(), 4, "Forward, splice including" ); is( $iter->index(), 4, "Forward, splice including" ); # Splice at iterator $iter->forward( 1 ); @elems = splice @$iterarray, 5, 3; is( $iter->value(), 8, "Forward, splice at" ); is( $iter->index(), 5, "Forward, splice at" ); splice @$iterarray, 5, 0, @elems; is( $iter->value(), 5, "Forward, splice at" ); is( $iter->index(), 5, "Forward, splice at" ); # Splice after iterator @elems = splice @$iterarray, 7, 3; is( $iter->value(), 5, "Forward, splice after" ); is( $iter->index(), 5, "Forward, splice after" ); splice @$iterarray, 7, 0, @elems; is( $iter->value(), 5, "Forward, splice after" ); is( $iter->index(), 5, "Forward, splice after" ); 1;Tie-Array-Iterable-0.03/t/reverse.t0100755000175000017500000001241107375075202017017 0ustar mneylonmneylon#!/usr/bin/perl -w #============================================================================= # # $Id: reverse.t,v 0.03 2001/11/16 02:31:30 mneylon Exp $ # $Revision: 0.03 $ # $Author: mneylon $ # $Date: 2001/11/16 02:31:30 $ # $Log: reverse.t,v $ # Revision 0.03 2001/11/16 02:31:30 mneylon # Updating to fix version problems # # Revision 0.02 2001/11/16 02:21:31 mneylon # Update to version 0.02 # # Revision 0.01.01.1 2001/11/15 01:43:52 mneylon # Branch for 0.01 changes # # Revision 0.01 2001/11/11 18:40:57 mneylon # Initial release # # #============================================================================= # Reverse iterator testing use strict; use Tie::Array::Iterable; use Test::More tests => 62; my @array = ( 0 .. 10 ); my $iterarray = new Tie::Array::Iterable( @array ); my $iter = $iterarray->from_end(); is( $iter->value(), 10, "Reverse, value from start" ); is( $iter->index(), 11, "Reverse, index from start" ); ok( $iter->at_start(), "Reverse, at start" ); $iter->prev(); # Should go nowhere is( $iter->value(), 10, "Reverse, prev value from start" ); is( $iter->index(), 11, "Reverse, prev index from start" ); ok( $iter->at_start(), "Reverse, at start with prev" ); $iter->next(); # now go to 9 is( $iter->value(), 9, "Reverse, next value from start" ); is( $iter->index(), 10, "Reverse, next index from start" ); ok( !$iter->at_start(), "Reverse, not at start with next" ); $iter->forward(2); # now to 7 is( $iter->value(), 7, "Reverse, forward in array" ); is( $iter->index(), 8, "Reverse, forward in array" ); $iter->forward(20); # now way past end, back to end is( $iter->value(), undef, "Reverse, forward past end" ); is( $iter->index(), 0, "Reverse, forward past end" ); ok( $iter->at_end(), "Reverse, at end with forward" ); $iter->next(); # again try to move past end is( $iter->value(), undef, "Reverse, next past end" ); is( $iter->index(), 0, "Reverse, next past end" ); ok( $iter->at_end(), "Reverse, at end with next" ); $iter->prev(); # should be able to go back now is( $iter->value(), 0, "Reverse, prev from end" ); is( $iter->index(), 1, "Reverse, prev from end" ); ok( !$iter->at_end(), "Reverse, not at end with prev" ); $iter->backward(3); #back to 3 is( $iter->value(), 3, "Reverse, backward from end" ); is( $iter->index(), 4, "Reverse, backward from end" ); $iter->backward(20); #overshoot is( $iter->value(), 10, "Reverse, backward past start" ); is( $iter->index(), 11, "Reverse, backward past start" ); $iter->to_end(); is( $iter->value(), undef, "Reverse, next past end" ); is( $iter->index(), 0, "Reverse, next past end" ); ok( $iter->at_end(), "Reverse, at end with next" ); $iter->to_start(); is( $iter->value(), 10, "Reverse, to_start" ); is( $iter->index(), 11, "Reverse, to_start" ); ok( $iter->at_start(), "Reverse, to_start" ); # Shift/unshift at end $iter->to_end(); shift @$iterarray; is( $iter->value(), undef, "Reverse, shift at end" ); is( $iter->index(), 0, "Reverse, shift at end" ); unshift @$iterarray, 0; is( $iter->value(), undef, "Reverse, unshift at end" ); is( $iter->index(), 0, "Reverse, unshift at end" ); # Shift/unshift elsewhere besides start $iter->backward(4); shift @$iterarray; is( $iter->value(), 3, "Reverse, shift in middle" ); is( $iter->index(), 3, "Reverse, shift in middle" ); unshift @$iterarray, 0; is( $iter->value(), 3, "Reverse, unshift in middle" ); is( $iter->index(), 4, "Reverse, unshift in middle" ); # Push/pop elsewhere besides end pop @$iterarray; is( $iter->value(), 3, "Reverse, pop in middle" ); is( $iter->index(), 4, "Reverse, pop in middle" ); push @$iterarray, 10; is( $iter->value(), 3, "Reverse, push in middle" ); is( $iter->index(), 4, "Reverse, push in middle" ); # Push/pop at start $iter->to_start(); pop @$iterarray; is( $iter->value(), 9, "Reverse, pop at start" ); is( $iter->index(), 10, "Reverse, pop at start" ); push @$iterarray, 10; is( $iter->value(), 10, "Reverse, push at start" ); is( $iter->index(), 11, "Reverse, push at start" ); # Splice before iterator (but not including it) my @elems; $iter->forward( 5 ); # Pointing to 5 @elems = splice @$iterarray, 0, 3; is( $iter->value(), 5, "Reverse, splice before" ); is( $iter->index(), 3, "Reverse, splice before" ); splice @$iterarray, 0, 0, @elems; is( $iter->value(), 5, "Reverse, splice before" ); is( $iter->index(), 6, "Reverse, splice before" ); # Splice including iterator @elems = splice @$iterarray, 4, 3; is( $iter->value(), 7, "Reverse, splice including" ); is( $iter->index(), 5, "Reverse, splice including" ); splice @$iterarray, 4, 0, @elems; is( $iter->value(), 7, "Reverse, splice including" ); is( $iter->index(), 8, "Reverse, splice including" ); # Splice at iterator $iter->forward( 2 ); @elems = splice @$iterarray, 5, 3; is( $iter->value(), 8, "Reverse, splice at" ); is( $iter->index(), 6, "Reverse, splice at" ); splice @$iterarray, 5, 0, @elems; is( $iter->value(), 8, "Reverse, splice at" ); is( $iter->index(), 9, "Reverse, splice at" ); # Splice after iterator $iter->forward( 3 ); @elems = splice @$iterarray, 7, 3; is( $iter->value(), 5, "Reverse, splice after" ); is( $iter->index(), 6, "Reverse, splice after" ); splice @$iterarray, 7, 0, @elems; is( $iter->value(), 5, "Reverse, splice after" ); is( $iter->index(), 6, "Reverse, splice after" ); 1;Tie-Array-Iterable-0.03/MANIFEST0100644000175000017500000000020107375074023016034 0ustar mneylonmneylonChanges Iterable.pm Iterable/ForwardIterator.pm Iterable/BackwardIterator.pm Makefile.PL MANIFEST README t/forward.t t/reverse.t Tie-Array-Iterable-0.03/Iterable.pm0100755000175000017500000004321507375074654017021 0ustar mneylonmneylon#!/usr/bin/perl -w package Tie::Array::Iterable; #============================================================================= # # $Id: Iterable.pm,v 0.03 2001/11/16 02:27:56 mneylon Exp $ # $Revision: 0.03 $ # $Author: mneylon $ # $Date: 2001/11/16 02:27:56 $ # $Log: Iterable.pm,v $ # Revision 0.03 2001/11/16 02:27:56 mneylon # Fixed packing version variables # # Revision 0.01.01.2 2001/11/16 02:12:14 mneylon # Added code to clean up iterators after use # clear_iterators() now not needed, simply returns 1; # # Revision 0.01.01.1 2001/11/15 01:41:19 mneylon # Branch from 0.01 for new features # # Revision 0.01 2001/11/11 18:36:10 mneylon # Initial Release # # #============================================================================= use 5.006; use strict; use Tie::Array; use Tie::Array::Iterable::ForwardIterator; use Tie::Array::Iterable::BackwardIterator; BEGIN { use Exporter (); use vars qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS); ( $VERSION ) = '$Revision: 0.03 $ ' =~ /\$Revision:\s+([^\s]+)/; @ISA = qw( Exporter Tie::StdArray ); @EXPORT = qw( ); @EXPORT_OK = qw( iterate_from_start iterate_from_end ); %EXPORT_TAGS = ( quick=>[ qw( iterate_from_start iterate_from_end ) ] ); } sub new { my $class = shift; my @self; tie @self, $class, \@_; return bless \@self, $class; } sub TIEARRAY { my $class = shift; my $arrayref = shift || []; my %data = ( array => $arrayref, forward_iters => [], backward_iters => [] ); return bless \%data, $class; } sub FETCH { my $self = shift; my $index = shift; return $self->{ array }->[ $index ]; } sub STORE { my $self = shift; my $index = shift; my $value = shift; $self->{ array }->[ $index ] = $value; } sub FETCHSIZE { my $self = shift; return scalar @{ $self->{ array } }; } sub STORESIZE { my $self = shift; my $count = shift; if ( $count > $self->FETCHSIZE() ) { foreach ( $count - $self->FETCHSIZE() .. $count ) { $self->STORE( $_, '' ); } } elsif ( $count < $self->FETCHSIZE() ) { foreach ( 0 .. $self->FETCHSIZE() - $count - 2 ) { $self->POP(); } } } sub EXTEND { my $self = shift; my $count = shift; $self->STORESIZE( $count ); } sub EXISTS { my $self = shift; my $index = shift; return exists $self->{ array }->[ $index ]; } sub CLEAR { my $self = shift; $self->{ array } = []; foreach my $iter ( $self->_get_forward_iters() ) { $iter->set_index( 0 ); } foreach my $iter ( $self->_get_backward_iters() ) { $iter->set_index( 0 ); } return 1; } sub PUSH { my $self = shift; my @list = @_; my $last = $self->FETCHSIZE(); $self->STORE( $last + $_, $list[$_] ) foreach 0 .. $#list; foreach my $iter ( $self->_get_forward_iters() ) { if ( $iter->index() == $last ) { $iter->set_index( $last + scalar @list ); } } foreach my $iter ( $self->_get_backward_iters() ) { if ( $iter->index() == $last ) { $iter->set_index( $last + scalar @list ); } } return $self->FETCHSIZE(); } sub POP { my $self = shift; foreach my $iter ( $self->_get_forward_iters() ) { if ( $iter->index() >= $self->FETCHSIZE() ) { $iter->set_index( $iter->index()-1 ); } } foreach my $iter ( $self->_get_backward_iters() ) { if ( $iter->index() >= $self->FETCHSIZE() ) { $iter->set_index( $iter->index()-1 ); } } return pop @{ $self->{ array } }; } sub UNSHIFT { my $self = shift; my @list = @_; my $size = scalar( @list ); # make room for our list @{$self->{ array }}[ $size .. $#{$self->{ array }} + $size ] = @{$self->{ array }}; $self->STORE( $_, $list[$_] ) foreach 0 .. $#list; foreach my $iter ( $self->_get_forward_iters() ) { if ( $iter->index() > 0 ) { $iter->set_index( $iter->index() + scalar @list ); } } foreach my $iter ( $self->_get_backward_iters() ) { if ( $iter->index() > 0 ) { $iter->set_index( $iter->index() + scalar @list ); } } } sub SHIFT { my $self = shift; foreach my $iter ( $self->_get_forward_iters() ) { if ( $iter->index() > 0 ) { $iter->set_index( $iter->index()-1 ); } } foreach my $iter ( $self->_get_backward_iters() ) { if ( $iter->index() > 0 ) { $iter->set_index( $iter->index()-1 ); } } return shift @{ $self->{ array } }; } sub SPLICE { my $self = shift; my $offset = shift || 0; if ( $offset < 0 ) { $offset = $self->FETCHSIZE() + $offset + 1; } my $length = shift; if ( $length == 0 && $length ne "0" ) { $length = $self->FETCHSIZE() - $offset; } my @list = @_; # Do the splice first: my @data = splice @{ $self->{ array } }, $offset, $length, @list; foreach my $iter ( $self->_get_forward_iters() ) { # If beyond the splice point... if ( $iter->index() > $offset ) { # If outside of the offset boundary if ( $iter->index() > $offset + $length ) { # Simply adjust the counter $iter->set_index( $iter->index() + ( scalar @list - $length ) ); } else { # Push the iter back to the offset point $iter->set_index( $offset ); } } } foreach my $iter ( $self->_get_backward_iters() ) { # If beyond the splice point... if ( $iter->index() > $offset ) { # If outside of the offset boundary if ( $iter->index() > $offset + $length ) { # Simply adjust the counter $iter->set_index( $iter->index() + ( scalar @list - $length ) ); } else { # Push the iter back to the offset point $iter->set_index( $offset + scalar @list + 1 ); } } } return splice @data; } sub from_start () { my $self = shift; my $iter = new Tie::Array::Iterable::ForwardIterator( $self, 0 ); push @{ tied(@$self)->{ forward_iters } }, $iter->_id(); return $iter; } sub forward_from { my $self = shift; my $pos = shift; if ( $pos == 0 && $pos ne "0" ) { $pos = 0; } die "Position must be in array bounds" unless $pos >= 0 && $pos < scalar @$self; my $iter = new Tie::Array::Iterable::ForwardIterator( $self, $pos ); push @{ tied(@$self)->{ forward_iters } }, $iter->_id(); return $iter; } sub from_end () { my $self = shift; my $iter = new Tie::Array::Iterable::BackwardIterator( $self, scalar @$self ); push @{ tied(@$self)->{ backward_iters } }, $iter->_id(); return $iter; } sub backward_from { my $self = shift; my $pos = shift; if ( $pos == 0 && $pos ne "0" ) { $pos = scalar @$self; } die "Position must be in array bounds" unless $pos >= 0 && $pos <= scalar @$self; my $iter = new Tie::Array::Iterable::BackwardIterator( $self, $pos ); push @{ tied(@$self)->{ backward_iters } }, $iter->_id(); return $iter; } # This function is no longer necessary sub clear_iterators { 1; } sub iterate_from_start { my $array = new Tie::Array::Iterable( @_ ); return $array->from_start(); } sub iterate_from_end { my $array = new Tie::Array::Iterable( @_ ); return $array->from_end(); } sub iterate_forward_from { my $pos = shift; my $array = new Tie::Array::Iterable( @_ ); return $array->forward_from( $pos ); } sub iterate_backward_from { my $pos = shift; my $array = new Tie::Array::Iterable( @_ ); return $array->backward_from( $pos ); } sub _get_forward_iters { my $self = shift; return grep { $_ } map { Tie::Array::Iterable::ForwardIterator::_lookup( $_ ) } @{ $self->{ forward_iters } }; } sub _get_backward_iters { my $self = shift; return grep { $_ } map { Tie::Array::Iterable::BackwardIterator::_lookup( $_ ) } @{ $self->{ backward_iters } }; } sub _remove_forward_iterator { my $self = shift; my $id = shift; use Data::Dumper; tied(@$self)->{ forward_iters } = [ grep { $_ != $id } @{ tied(@$self)->{ forward_iters } } ]; } sub _remove_backward_iterator { my $self = shift; my $id = shift; tied(@$self)->{ backward_iters } = [ grep { $_ != $id } @{ tied(@$self)->{ backward_iters } } ]; } 1; __END__ =head1 NAME Tie::Array::Iterable - Allows creation of iterators for lists and arrays =head1 SYNOPSIS use Tie::Array::Iterable qw( quick ); my $iterarray = new Tie::Array::Iterable( 1..10 ); for( my $iter = $iterarray->start() ; !$iter->at_end() ; $iter->next() ) { print $iter->index(), " : ", $iter->value(); if ( $iter->value() == 3 ) { unshift @$iterarray, (11..15); } } my @array = ( 1..10 ); for( my $iter = iterator_from_start( @array ) ; !$iter->at_end() ; $iter->next() ) { ... } for( my $iter = iterate_from_end( @array ) ; !$iter->at_end() ; $iter->next() ) { ... } =head1 DESCRIPTION C allows one to create iterators for lists and arrays. The concept of iterators is borrowed from the C++ STL [1], in which most of the collections have iterators, though this class does not attempt to fully mimic it. Typically, in C/C++ or Perl, the 'easy' way to visit each item on a list is to use a counter, and then a for( ;; ) loop. However, this requires knowledge on how long the array is to know when to end. In addition, if items are removed or inserted into the array during the loop, then the counter will be incorrect on the next run through the loop, and will cause problems. While some aspects of this are fixed in Perl by the use of for or foreach, these commands still suffer when items are removed or added to the array while in these loops. Also, if one wished to use break to step out of a foreach loop, then restart where they left at some later point, there is no way to do this without maintaining some additional state information. The concept of iterators is that each iterator is a bookmark to a spot, typically concidered between two elements. While there is some overhead to the use of iterators, it allows elements to be added or removed from the list, with the iterator adjusting appropriate, and allows the state of a list traversal to be saved when needed. For example, the following perl code will drop into an endless block (this mimics the functionality of the above code): my @array = (0..10); for my $i ( @a ) { print "$i\n"; if ( $i == 3 ) { unshift @a, ( 11..15 ); } } However, the synopsis code will not be impared when the unshift operation is performed; the iteration will simply continue at the next element, being 4 in this case. Tie::Array::Iterable does this by first tying the desired list to this class as well as blessing it in order to give it functionality. When a new iterator is requested via the iterable array object, a new object is generated from either Tie::Array::Iterable::ForwardIterator or Tie::Array::Iterable::BackwardIterator. These objects are then used in associated for loops to move through the array and to access values. When changes in the positions of elements of the initial array are made, the tied variable does the appropriate bookkeeping with any iterators that have been created to make sure they point to the appropriate elements. Note that the iterable array object is also a tied array, and thus, you can use all standard array operations on it (with arrow notation due to the reference, of course). The logic behind how iterators will 'move' depending on actions are listed here. Given the list 0 1 2 3 4 5 6 7 8 9 10 ^ Forward iterator current position Several possible cases can be considered: =over =item unshift If an item was unshifted on the list, thus pushing all elements to the right, the iterator will follow this and will still point to 5. =item shift Removing an item from the start of the list will push all elements to the left, and the iterator again will follow and point to 5. =item pop, push Since these affect the list after the position of the iterator, there is no change in the iterator at this time. However, an iterator that is at the end of the list will pass over these new elements if it is moved backwards though the list. =item splice 3, 4, () If the array is spliced from 3 to 6, then the position that the iterator is at is invalid, and is pushed back to the last 'valid' entry, this being between 2 and 7 after the splice and pointing to 7. =item splice 3, 4, ( 11, 12, 13 ) Even though we are adding new data, this is similar to the situation above, and the iterator will end up pointing at 11, sitting between 2 and 11. =item splice 4, 0, ( 11, 12, 13 ) This will push extra data between 3 and 4, but does not affect the position of the iteration, which will still point at 5. =item splice 5, 0, ( 11, 12, 13 ) Because the data is now being pushed between 4 and 5, this will affect the iterator, and the iterator will now point at 11. =item splice 0, 6 Remove all data from the head to the iterator position will result it in being at the leftmost part of the array, and will be pointing at 7. =back This is only for the forward iterator; the backwards iterator would work similarly. =head2 PACKAGE METHODS =over =item new( [] ) Creates a new iterable array object; this is returned as a reference to an array. If an array is passed, then the iterable array is set up to use this array as storage. =item iterate_from_start( ) Returns a forward iterator that can be used to iterator over the given list. This allows one to avoid explicitly creating the iterable array object first, though one still is created for this purpose. =item iterate_from_end( ) Returns a backwards iterator that can be used to iterate over the given list. =item iterate_forward_from( , ) Returns a forward iterator for the given list set at the indicated position. =item iterate_backward_from( , ) Returns a backward iterator for the given list set at the indicated position. =back =head2 CLASS METHODS =over =item from_start( ) Returns a new forward iterator set at the start of the array. Parentheses are not required. =item from_end( ) Returns a new backward iterator set at the end of the array. Parentheses are not required. =item forward_from ([]) Returns a new forward iterator set at the indicated position (or at the start of the array if no value is passed). =item backward_from ([]) Returns a new backward iterator set at the indicated position (or at the end of the array if no value is passed). =item clear_iterators( ) This function was previously used to clear references that might accumulate; however, this functionality has been fixed, and this function does nothing besides return a true value. =back =head2 ITERATOR METHODS The iterators that are generated by the functions above have the following functions associated with them. =over =item value() Returns the current value from the array where the iterator is pointing, or undef if the iterator is at the end. =item set_value( ) Sets the value of the array where the iterator is currently positions to the passed value. This will do nothing if the iterator is at the end of the array. =item index() Returns the index in the array where the iterator is currently pointing. =item set_index( ) Moves the iterator to this position in the array. =item at_end() Returns true if the iterator is pointing at the end position (at the end of the array for a Forward iterator, at the start of the array for the Backward iterator), false otherwise. Parentheses are not required. =item at_start() Returns true if the iterator is pointing at the start position (at the beginning of the array for a Forward iterator, at the end of the array for the Backward iterator), false otherwise. Parentheses are not required. =item next() Advances the iterator to the next position; the value of this new position is returned as per C. This will not move past the end position. Parentheses are not required. =item prev() Advances the iterator to the previous position; the value of this new position is returned as per C. This will not move past the starting position. Parentheses are not required. =item to_end() Advances the iterator to the very end position. Note that this is the undefined state, and the only way to resume traversal is to move to preceeding elements. Also note that for a backwards iterator, this means to move to the beginning of the array. Parentheses are not required. =item to_start() Advances the iterator back to the starting position for the iterator. Again, for a backwards iterator, this means moving to the end of the list. Parentheses are not required. =item forward( [] ) Advances the iterator in the forward direction the number of steps passed, or just 1 if no value is passed (and thus acting like C). =item backward( [] ) Advances the iterator in the backward direction the number of steps passed, or just 1 if no value is passed (and thus acting like C). =back =head1 EXPORT The 'quick' export will export C, C, C, and C functions into the global namespace. Optionally, you may import these functions individually. =head1 CAVAETS You should not directly tie your array to this class, nor use the ForwardIterator or BackwardIterator classes directly. There are factory-like methods for these classes that you should use instead. You might run in to trouble if you use more than MAXINT (typically 2^32 on most 32-bit machines) iterators during a single instance of the program. If this is a practical concern, please let me know; that can be fixed though with some time consumption. =head1 AUTHOR Michael K. Neylon Emneylon-pm@masemware.comE =head1 ACKNOWLEDGEMENTS I'd like to thank Chip Salzenberg for a useful suggesting in helping to remove the reference problem without having to resort to weak references on Perlmonks. =head1 REFERENCES [1] A reference guide to the C++ STL can be found at http://www.cs.rpi.edu/projects/STL/htdocs/stl.html =head1 COPYRIGHT Copyright 2001 by Michael K. Neylon Emneylon-pm@masemware.comE. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See http://www.perl.com/perl/misc/Artistic.html =cut