UR::Iterator(3pm)

💖 UR::Iterator — bestie's guide to iterating thru data 💖

okay so this is UR::Iterator, it's a Perl module (a 3pm man page, user-contributed Perl docs, the whole vibe ✨) and it's literally just the iterator pattern in Perl form. no cap.

---

✨ 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";
  }

(yes bestie, that stray quote in the first print is exactly how it's written up there, we don't touch the code, code is sacred 💅)

---

🌸 DESCRIPTION 🌸

UR::Iterator instances implement the iterator pattern. periodt. you can make these objects two ways:

• from a list of values
• by applying a mapping function to another iterator

and here's the tea 🫖 — UR::Iterator instances are normal Perl object references, not UR-based objects. they do not live in the Context's object cache, and they obey the normal Perl rules about scoping. so like, they're just regular lil guys doing regular Perl things. iconic behavior honestly. 👑

---

🎀 METHODS 🎀

create_for_list

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

creates an iterator based on values contained in the given list. ⚠️ heads up though: this constructor will throw an exception if any of the supplied values is "undef". so if you're passing in a maybe-undef, that's a you problem and the module is gonna yell at you 😭

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. and the new iterator will be exhausted when the original iterator is exhausted — they're linked, fr fr 🔗

when the mapping function is called, $_ is set to the value obtained from the original iterator. so your sub just goes $_ and does its lil glow-up ✨

next

  $obj = $iter->next();

return the next object matching the iterator's rule. when there are no more matching objects, it returns undef. that's the whole thing bestie, undef = we're done here 💀

peek

  $obj = $iter->peek();

return the next object matching the iterator's rule without removing it. so 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 👀 like a lil vibe check on your iterator before you commit.

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. so like, if you get nothing back, that's your sign 🍓

---

💜 SEE ALSO 💜

• UR::Object::Iterator

---

that's the whole page bestie, slay 💅✨

this was perl v5.32.1, dated 2022-01-17 — mwah, go iterate on something cute 🦋🎀