NAME

       UR::Iterator - API for iterating through data

SYNOPSIS

         my $iter = UR::Iterator->create_for_list(1, 2, 3, 4);
         while (my $i = $iter->next) {
           print $i\n";
         }

         my $mapped_iter = $iter->map(sub { $_ + 1 });
         while (my $i = $mapped_iter->next) {
           print "$i\n";
         }

DESCRIPTION

       UR::Iterator instances implement the iterator pattern.  These objects can be created with
       either a list of values, or by applying a mapping function to another iterator.

       UR::Iterator instances are normal Perl object references, not UR-based objects.  They do
       not live in the Context's object cache, and obey the normal Perl rules about scoping.

METHODS

       create_for_list
             $iter = UR::Object::Iterator->create_for_list(@values);

           Creates an iterator based on values contained in the given list.  This constructor
           will throw an exception if any of the supplied values is "undef".

       map
             $new_iter = $iter->map(sub { $_ + 1 });

           Creates a new iterator based on an existing iterator.  Values returned by this new
           iterator are based on the values of the existing iterator after going through a
           mapping function.  This new iterator will  be exhausted when the original iterator is
           exhausted.

           When the mapping function is called, $_ is set to the value obtained from the original
           iterator.

       next
             $obj = $iter->next();

           Return the next object matching the iterator's rule.  When there are no more matching
           objects, it returns undef.

       peek
             $obj = $iter->peek();

           Return the next object matching the iterator's rule without removing it.  The next
           call to peek() or next() will return the same object.  Returns undef if there are no
           more matching objects.

           This is useful to test whether a newly created iterator matched anything.

       remaining
             @objs = $iter->remaining();

           Return a list of all the objects remaining in the iterator.  The list will be empty if
           there is no more data.

SEE ALSO

       UR::Object::Iterator