SPOPS::Iterator 0.87

SPOPS::Iterator is a class to cycle through results and return SPOPS objects.

SYNOPSIS

my $iter = $spops_class->fetch_iterator({ where => last_name like ?,
value => [ smi% ] });
while ( $iter->has_next ) {
my $object = $iter->get_next;
print "Object ID: ", $object->id, " at position: ",
$iter->position, "n";
}

One of the problems with current SPOPS implementations is that retrieving groups of objects is an all-or-nothing affair -- you get a list with all instantiated objects or you do not retrive them in the first place. This can be quite memory intensive, particularly when a user executes a query that can return thousands of objects back at one time.
This class -- or, more specifically, implementations of the interface in this class -- aims to change that. Instead of returning a list of objects from a group retrieval, you get back an SPOPS::Iterator object. This object has a simple interface to cycle forward through objects and let you deal with them one at a time.

It does not keep track of these for you -- once you request the SPOPS object through the get_next() call, the iterator loses track of it. The iterator does keep track of the current count (on a 1-based scheme) and whether you are currently on the first or last element.

It is important to state that this works within the realm of other SPOPS capabilities -- just like the fetch_group() method, all objects returned will get checked for security, and if a user cannot see a certain object it does not get returned and the iterator moves onto the next object.

As a result, users will never create an SPOPS::Iterator object themselves. Instead, the object is returned from a method in a SPOPS implementation class, such as SPOPS::DBI.

The initial module documentation is for the interface; there is also a section of creating a subclass of this module for SPOPS authors.