Iterato...ookahead(3)

💖 Iterato...ookahead(3) 💖

okay bestie, welcome to the Iterator::Simple::Lookahead page from the User Contributed Perl Documentation — yes the title's got that lil truncation glow, it's Iterato...ookahead(3), we love a mysterious queen 💅

---

✨ NAME ✨

Iterator::Simple::Lookahead — a simple iterator with lookahead and unget. like, you can peek at the future AND shove stuff back into the past. main character energy fr fr 👑

---

🌈 SYNOPSIS 🌈

use Iterator::Simple::Lookahead;
my $iter = Iterator::Simple::Lookahead->new( sub {}, @values );
my $first = $iter->peek();
my $second = $iter->peek(1);
my $next = $iter->next; # or $iter->()
$iter->unget( sub {}, @values );

no cap, that's the whole vibe check right there ✨

---

🦋 DESCRIPTION 🦋

so this module encapsulates an iterator function. and what's an iterator function? it's a lil function that returns the next element in the stream every time you call it, and returns "undef" when the input is done-done. periodt. 💀

the iterator can return a code reference — and when it does, this new iterator gets inserted at the head of the queue. sneaky? iconic? both. 🎀

the object lets you peek() the *N*th element of the stream without consuming it, or get it and remove it from the stream. your choice, bestie. 🫶

you can also push a list of items back into the stream with unget(), and they'll get retrieved in the subsequent next() calls. and the next item? you can also grab it by calling $iter->(). yes literally just call the object, she's fun like that. 💅

the input list you hand to the constructor and to unget() contains items that get retrieved on each next() call, or code references that get called to extract the next item from the stream. 🌸

other types of input can be converted to a code reference by iter() of Iterator::Simple. (iykyk)

this module is built on top of Iterator::Simple and returns iterators that are compatible with it — meaning an object of type "Iterator::Simple::Lookahead" can be used as an input to iter(). slay, compatible queen. 👑

---

⭐ FUNCTIONS ⭐

🎀 new

creates a new object ready to retrieve elements from the given input list. the list contains either values to be returned in a subsequent next() call, or code references to be called to extract the next item from the stream.

other types of input can be converted to a code reference by iter() of Iterator::Simple.

🍓 peek

retrieves the *N*th-element at the head of the stream, but keeps it in the stream to be retrieved by next(). no take-backsies, she just looks. 👀

calls the iterator function to compute the items up to the Nth element, and returns "undef" if the stream is exhausted before reaching N.

as a special case, peek() retrieves the element at the head of the stream, or "undef" if the stream is empty. so peek() with no args = just gimme the first one bestie. 💖

🧚 next

retrieves the element at the head of the stream and removes it from the stream. gone. consumed. ate. 🔥

returns "undef" if the stream is empty.

💜 unget

pushes back a list of values and/or iterators to the stream, that will be retrieved on the subsequent calls to next().

can be called from within an iterator, to insert values that will be returned before the current call. like, calling from the iterator:

$stream->unget(1..3); return 4;

will result in the values 4,1,2,3 being returned from the stream. yes the 4 comes first, the past got reordered, time is fake, we move. ⏳✨

---

🌸 EXPORT 🌸

None. she's self-contained, she doesn't need to share. 💅

---

👑 AUTHOR 👑

Paulo Custodio, "<pscust at cpan.org>" — thank you for your service legend 🫡💖

---

🙈 BUGS and FEEDBACK 🙈

please report any bugs or feature requests through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Iterator-Simple-Lookahead>. (yes it's an old-school link, no we don't make the rules, drop the bug report bestie 💌)

---

🌈 ACKNOWLEDGEMENTS 🌈

inspired in HOP::Stream and Iterator::Simple. standing on the shoulders of icons fr fr 🧚✨

---

💖 COPYRIGHT AND LICENSE 💖

Copyright (C) 2013 by Paulo Custodio

this library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.16.1 or, at your option, any later version of Perl 5 you may have available. 🌸

---

and that's the whole page bestie, go forth and lookahead responsibly 💅

okay but for real — that's the end. this was the Iterato...ookahead(3) page, perl v5.42.0, dated 2025-07-25. mwah, love u, bye! 💖🎀🦋