/ 
Gestinanna-POF-0.07
/ Gestinanna::POF::Iterator

NAME

Gestinanna::POF::Iterator - Search result iterator

SYNOPSIS

Returned from data store object:

Gestinanna::POF::Iterator -> new(
    factory => $factory,
    type => $type,
    limit => $limit,
    %list_params
);

In user code:

$cursor = $factory -> find(type => (
     where => [ ... ],
     limit => [ min, max ],
));

while($obj = $cursor -> next) { }
while($id = $cursor -> next_id) { }

$cursor -> is_first;
$cursor -> has_next;
$cursor -> is_last;

$cursor -> position;

@obs = $cursor -> get_all;
@ids = $cursor -> get_all_ids;

$cursor -> discard;

DESCRIPTION

The find method available in the factory and in the data store objects returns an iterator object.

CREATING AN ITERATOR

Iterators should only be created from within a data store's find method (or similar). There are two different ways to create a useful iterator.

Both methods of creating an iterator accept three arguments in common:

factory
factory => $factory

This is a factory object which can create objects of the type stored in the data store the iterator is for.

If this is defined, then the object methods will be able to create objects as needed (i.e., get_all and next).

limit
limit => $limit

If this is a scalar, then this indicates how many objects or object identifiers to iterate over, beginning with the first.

limit => [ $limit, $offset ]

If this is an array reference with two elements, then objects or object identifiers are returned starting at $offset with no more than $limit objects or object identifiers being returned. If $offset is undefined, then it indicates the beginning of the sequence. If $limit is undefined, then iteration begins at $offset and continues until there are no objects or object identifiers left.

type
type => $type

This is the type that the object is known as within the factory:

$type = $factory -> get_object_type($class);

If this is defined, then the object methods will be able to create objects as needed (i.e., get_all and next).

Creating From a List

The easiest way is to build up an array of object ids and give the iterator constructor a reference to this array.

$cursor = Iterator::Class -> new(
  list => [ ... ],
  limit => ...,
  factory => $factory,
  type => $object_type,
);

The resulting iterator will step through the list of object ids, returning undef when it is exhausted. It will use the given factory object and object type to create objects if needed. If the factory and object type are not given, then only object identifiers will be available.

For objects based on Gestinanna::POF::Container (or similar consolidating objects) to work correctly, the list of object identifiers must be sorted in ascending order (a simple sort @list should suffice).

Creating from a Generating Function

The best way to conserve memory and time for potentially large or expensive lists of object identifiers is to pass a code reference that will return an object identifier on each call (or undef if there are no more identifiers).

$cursor = Iterator::Class -> new(
  generator => sub { ... },
  cleanup => sub { ... },
  limit => ...,
  factory => $factory,
  type => $type,
);

The resulting iterator will call the generator function each time a new object identifier is needed.

USER METHODS

The following methods are available for code using an iterator instance.

discard

Calling this method tells the iterator to release any resources it might have held.

get_all

Returns the remaining list of objects in the search results.

get_all_ids

Returns the remaining list of object identifiers in the search results.

has_next

Returns true if there is at least one more object identifier or object in the search results.

is_first

Returns true if the most recently returned object or identifier is the first object or identifier returned by the iterator.

is_last

This is true if the most recently returned object or object identifier is the last object or object identifier in the search results. Any subsequent calls to next or next_id should return undef. This should return the opposite truth of has_next.

next

This will retrieve the next identifier of an object that satisfies the search criteria and return the object associated with the identifier. If no such object identifier or object exists, then undef is returned, indicating that there are no more search results.

next_id

This will retrieve and return the next object identifier of an object that satisfies the search criteria. If no such object exists, then undef is returned, indicating that there are no more search results.

position

This will return the position of the most recently returned object or object identifier. If no objects or object identifiers have been returned, then this will be undef.

BUGS

Please report bugs to either the request tracker for CPAN (http://rt.cpan.org/) or at the SourceForge project (http://sourceforge.net/projects/gestinanna/).

AUTHOR

James G. Smith, <jsmith@cpan.org>

COPYRIGHT

Copyright (C) 2002-2003 Texas A&M University. All Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.