Iterable(3pm)						User Contributed Perl Documentation					     Iterable(3pm)

NAME

       Tie::Array::Iterable - Allows creation of iterators for lists and arrays

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() ) { ... }

DESCRIPTION

       "Tie::Hash::Iterable" 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 considered 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
";
		  if ( $i == 3 ) { unshift @a, ( 11..15 ); }
	  }

       However, the synopsis code will not be impaired 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:

       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.

       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.

       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.

       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.

       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.

       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.

       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.

       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.

       This is only for the forward iterator; the backwards iterator would work similarly.

   PACKAGE METHODS
       new( [<array>] )
	   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.

       iterate_from_start( <list> )
	   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.

       iterate_from_end( <list> )
	   Returns a backwards iterator that can be used to iterate over the given list.

       iterate_forward_from( <int>, <list> )
	   Returns a forward iterator for the given list set at the indicated position.

       iterate_backward_from( <int>, <list> )
	   Returns a backward iterator for the given list set at the indicated position.

   CLASS METHODS
       from_start( )
	   Returns a new forward iterator set at the start of the array.  Parentheses are not required.

       from_end( )
	   Returns a new backward iterator set at the end of the array.  Parentheses are not required.

       forward_from ([<int>])
	   Returns a new forward iterator set at the indicated position (or at the start of the array if no value is passed).

       backward_from ([<int>])
	   Returns a new backward iterator set at the indicated position (or at the end of the array if no value is passed).

       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.

   ITERATOR METHODS
       The iterators that are generated by the functions above have the following functions associated with them.

       value()
	   Returns the current value from the array where the iterator is pointing, or undef if the iterator is at the end.

       set_value( <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.

       index()
	   Returns the index in the array where the iterator is currently pointing.

       set_index( <pos> )
	   Moves the iterator to this position in the array.

       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.

       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.

       next()
	   Advances the iterator to the next position; the value of this new position is returned as per "value()".  This will not move past the
	   end position.  Parentheses are not required.

       prev()
	   Advances the iterator to the previous position; the value of this new position is returned as per "value()".  This will not move past
	   the starting position.  Parentheses are not required.

       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 preceding elements.  Also note that for a backwards iterator, this means to move to the beginning of the array.  Parentheses are not
	   required.

       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.

       forward( [<int>] )
	   Advances the iterator in the forward direction the number of steps passed, or just 1 if no value is passed (and thus acting like
	   "next()").

       backward( [<int>] )
	   Advances the iterator in the backward direction the number of steps passed, or just 1 if no value is passed (and thus acting like
	   "prev()").

EXPORT

       The 'quick' export will export "iterate_from_start", "iterate_from_end", "iterate_forward_from", and "iterate_backward_from" functions into
       the global namespace.  Optionally, you may import these functions individually.

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.

AUTHOR

       Michael K. Neylon <mneylon-pm@masemware.com>

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.

REFERENCES

       [1] A reference guide to the C++ STL can be found at
	   http://www.cs.rpi.edu/projects/STL/htdocs/stl.html

COPYRIGHT

       Copyright 2001 by Michael K. Neylon <mneylon-pm@masemware.com>.

       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

perl v5.12.4							    2011-07-26							     Iterable(3pm)