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