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

perl v5.32.1                                       2022-01-17                                  UR::Iterator(3pm)