---
name: "UR::Iterator"
section: "3pm"
platform: "linux"
package: "libur-perl"
version: "0.470+ds-3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/UR::Iterator"
---

# UR::Iterator(3pm)

API for iterating through data

## 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