Name

Sort::MergeSort::Iterator - iteration object

Synopsis

  my $input = Sort::MergeSort::Iterator->new( sub { ... } );

  while (<$input>) {
  }

  while (my $i = $input->next) {
  }

  my $ahead = $input->peek;

Description

This class implements a simple iterator interface for iterating over items. Just pass a code reference to the constructor that returns the next value over which to iterate. Sort::MergeSort::Iterator will do the rest.

FileHandle Interface

You can pretend that an Iterator object is a filehandle. It doesn't support all filehandle operations, but it does allow you to iterate in the natural way:

 while (<$input>) {
 }

Instance Methods

Class Interface

Constructors

new

  my $iter = Sort::MergeSort::Iterator->new(\&code_ref);
  my $iter = Sort::MergeSort::Iterator->new(\&code_ref, \&destroy_code_ref);

Constructs and returns a new iterator object. The code reference passed as the first argument is required and must return the next item to iterate over each time it is called, and undef when there are no more items. undef cannot itself be an item. The optional second argument must also be a code reference, and will only be executed when the iterator object is destroyed (that is, it will be called in the DESTROY() method).

current

  my $current = $iter->current;

Returns the current item in the iterator--that is, the same item returned by the most recent call to next().

next

  while (my $thing = $iter->next) {
          # Do something with $thing.
  }

Returns the next item in the iterator. Returns undef when there are no more items to iterate.

peek

  while ($iter->peek) {
          $iter->next;
  }

Returns the next item to be returned by next() without actually removing it from the list of items to be returned. The item returned by peek() will be returned by the next call to next(). After that, it will not be available from peek() but the next item will be.

position

  my $pos = $iter->position;

Returns the current position in the iterator. After the first time next() is called, the position is set to 1. After the second time, it's set to 2. And so on. If next() has never been called, position() returns 0.

all

  for my $item ($iter->all) {
          print "Item: $item\n";
  }

Returns a list or array reference of all of the items to be returned by the iterator. If next() has been called prior to the call to all(), then only the remaining items in the iterator will be returned. Use this method with caution, as it could cause a large number of items to be loaded into memory at once.

do

  $iter->do( sub { print "$_[0]\n"; return $_[0]; } );
  $iter->do( sub { print "$_\n"; return $_; } );

Pass a code reference to this method to execute it for each item in the iterator. Each item will be set to $_ before executing the code reference, and will also be passed as the sole argument to the code reference. If next() has been called prior to the call to do(), then only the remaining items in the iterator will passed to the code reference. Iteration terminates when the code reference returns false, so be sure to have it return a true value if you want it to iterate over every item.

Author

David Wheeler <wheeler@searchme.com>

Copyright and License

Copyright (c) 2004-2008 Kineticode, Inc. <info@kineticode.com>.

This work was based on Object::Relation::Iterator module developed by Kineticode, Inc. As such, it is is free software; it can be redistributed it and/or modified it under the same terms as Perl itself.