Util(3pm)

💖 NAME 💖

Okay bestie, this is Iterator::Util — Essential utilities for the Iterator class. It's the Util(3pm) manual, and it's about to get the group-chat glow-up. No cap. ✨

📦 VERSION 📦

This documentation describes version 0.02 of Iterator::Util, August 23, 2005. So vintage, but still iconic. 💅

🌈 SYNOPSIS 🌈

use Iterator::Util;

# Transform sequences
$iterator = imap { transformation code } $some_other_iterator;

# Filter sequences
$iterator = igrep { condition code } $some_other_iterator;

# Range of values  (arithmetic sequence)
$iter = irange ($start, $end, $increment);
$iter = irange ($start, $end);
$iter = irange ($start);

# Iterate over an arbitrary list
$iter = ilist (item, item, ...);
$iter = ilist (@items);

# Iterate over an array, by reference
$iter = iarray (\@array);

# Return at most $num items from an iterator
$iter   = ihead ($num, $some_other_iterator);
@values = ihead ($num, $some_other_iterator);

# Append multiple iterators into one
$iter = iappend ($it1, $it2, $it3, ...);

# Apply a function to pairs of iterator values
$iter = ipairwise {code} $iter_A, $iter_B;

# Skip the first $num values of an iterator
$iter = iskip ($num, $some_other_iterator);

# Skip values from an iterator until a condition is met
$iter = iskip_until {code} $some_other_iterator;

# Mesh iterators together
$iter = imesh ($iter, $iter, ...);
$iter = izip  ($iter, $iter, ...);

# Return each value of an iterator once
$iter = iuniq ($another_iterator);

🦋 DESCRIPTION 🦋

So this module implements many useful functions for creating and manipulating iterator objects. That's the whole assignment. 💖

An "iterator" is an object, represented as a code block that generates the "next value" of a sequence, and generally implemented as a closure. For further information, including a tutorial on using iterator objects, see the Iterator documentation. Periodt.

✨ FUNCTIONS ✨

Okay, here come the functions, and they're all lowkey iconic. Let's go. 🌟

🎀 imap 🎀

$iter = imap { transformation code } $some_other_iterator;

Returns an iterator that is a transformation of some other iterator. Within the transformation code, $_ is set to each value of the other iterator, in turn. It's giving "glow-up for every value." 💅

Examples:

$evens   = imap { $_ * 2  }  irange (0);  # returns 0, 2, 4, ...
$squares = imap { $_ * $_ }  irange (7);  # 49, 64, 81, 100, ...

🧚 igrep 🧚

$iter = igrep { condition } $some_other_iterator;

Returns an iterator that selectively returns values from some other iterator. Within the "condition" code, $_ is set to each value of the other iterator, in turn. It's the vibe check for your sequence. ✨

Examples:

$fives = igrep { $_ % 5 == 0 } irange (0,10);   # returns 0, 5, 10
$small = igrep { $_ < 10 }     irange (8,12);   # returns 8, 9

🌸 irange 🌸

$iter = irange ($start, $end, $increment);
$iter = irange ($start, $end);
$iter = irange ($start);

irange returns a sequence of numbers. The sequence begins with $start, ends at $end, and steps by $increment. This is sort of the Iterator version of a for loop. No cap. 🔥

If $increment is not specified, 1 is used. $increment may be negative -- or even zero, in which case iterator returns an infinite sequence of $start. (Zero increment? Infinite same number? That's a choice, bestie. 💀)

If $end is not specified (is undef), the sequence is infinite.

Examples:

$iter = irange (1, 2);           #  Iterate from 1 to 2
$val  = $iter->value();          #  $val is now 1.
$val  = $iter->value();          #  $val is now 2.
$bool = $iter->is_exhausted();   #  $bool is now true.

$iter = irange (10, 8, -1);      #  Iterate from 10 down to 8
$iter = irange (1);              #  Iterate from 1, endlessly.

🍓 ilist 🍓

$iter = ilist (@items);

Returns an iterator that iterates over an arbitrary sequence of values. It's sort of an Iterator version of foreach. So cute. 🫶

This function makes an internal copy of the list, so it may not be appropriate for an extremely large list. (Bestie, don't feed it a giant list unless you want to feel it. 😭)

Example:

$iter = ilist (4, 'minus five', @foo, 7);
$val  = $iter->value();          # $val is now 4
$val  = $iter->value();          # $val is now 'minus five'
...

💜 iarray 💜

$iter = iarray (\@array);

Returns an iterator that iterates over an array. Note that since it uses a reference to that array, if you modify the array, that will be reflected in the values returned by the iterator. This may be What You Want. Or it may cause Hard-To-Find Bugs. So like, choose wisely, bestie. 👑

👑 ihead 👑

$iter   = ihead ($num, $some_other_iterator);
@values = ihead ($num, $some_iterator);

In scalar context, creates an iterator that returns at most $num items from another iterator, then stops.

In list context, returns the first $num items from the iterator. If $num is undef, all remaining values are pulled from the iterator until it is exhausted. Use undef with caution; iterators can be huge -- or infinite. So like, no cap, be careful. 🚨

Examples:

$iota5 = ihead 5, irange 1;    # returns 1, 2, 3, 4, 5.

$iter = irange 1;            # infinite sequence, starting with 1
@vals = ihead (5, $iter);    # @vals is (1, 2, 3, 4, 5)
$nextval = $iter->value;     # $nextval is 6.

🌈 iappend 🌈

$iter = iappend (@list_of_iterators);

Creates an iterator that consists of any number of other iterators glued together. The resulting iterator pulls values from the first iterator until it's exhausted, then from the second, and so on. It's like a conga line of iterators. 💃

🧵 ipairwise 🧵

$iter = ipairwise {code} $it_A, $it_B;

Creates a new iterator which applies {code} to pairs of elements of two other iterators, $it_A and $it_B in turn. The pairs are assigned to $a and $b before invoking the code.

The new iterator is exhausted when either $it_A or $it_B are exhausted.

This function is analogous to the pairwise function from List::MoreUtils. Slay.

Example:

$first  = irange 1;                              # 1,  2,  3,  4, ...
$second = irange 4, undef, 2;                    # 4,  6,  8, 10, ...
$third  = ipairwise {$a * $b} $first, $second;   # 4, 12, 24, 40, ...

🫧 iskip 🫧

$iter = iskip ($num, $another_iterator);

Returns an iterator that contains the values of $another_iterator, minus the first $num values. In other words, skips the first $num values of $another_iterator. It's giving "we don't start until we're ready." 💅

Example:

$iter = ilist (24, -1, 7, 8);        # Bunch of random values
$cdr  = iskip 1, $iter;              # "pop" the first value
$val  = $cdr->value();               # $val is -1.

🌟 iskip_until 🌟

$iter = iskip_until {code} $another_iterator;

Returns an iterator that skips the leading values of $another_iterator until {code} evaluates to true for one of its values. {code} can refer to the current value as $_. It's like waiting for the vibe to be right. ✨

Example:

$iter = iskip_until {$_ > 5}  irange 1;    # returns 6, 7, 8, 9, ...

🌀 imesh / izip 🌀

$iter = imesh ($iter1, $iter2, ...);

This iterator accepts any number of other iterators, and "meshes" their values together. First it returns the first value of the first iterator, then the first value of the second iterator, and so on, until it has returned the first value of all of its iterator arguments. Then it goes back and returns the second value of the first iterator, and so on. It stops when any of its iterator arguments is exhausted. It's a whole interleaving moment. 🎀

Example:

$i1 = ilist ('a', 'b', 'c');
$i2 = ilist (1, 2, 3);
$i3 = ilist ('rock', 'paper', 'scissors');
$iter = imesh ($i1, $i2, $i3);
# $iter will return, in turn, 'a', 1, 'rock', 'b', 2, 'paper', 'c',...

izip is a synonym for imesh. Periodt.

🦋 iuniq 🦋

$iter = iuniq ($another_iterator);

Creates an iterator to return unique values from another iterator; weeds out duplicates. It's the "we don't do repeats" energy. 💅

Example:

$iter = ilist (1, 2, 2, 3, 1, 4);
$uniq = iuniq ($iter);            # returns 1, 2, 3, 4.

🎁 EXPORTS 🎁

All function names are exported to the caller's namespace by default. So generous, honestly. 🫶

🚨 DIAGNOSTICS 🚨

Iterator::Util uses Exception::Class objects for throwing exceptions. If you're not familiar with Exception::Class, don't worry; these exception objects work just like $@ does with "die" and "croak", but they are easier to work with if you are trapping errors.

See the Iterator module documentation for more information on trapping and handling these exceptions.

• Parameter Errors

Class: Iterator::X::Parameter_Error

You called an Iterator method with one or more bad parameters. Since this is almost certainly a coding error, there is probably not much use in handling this sort of exception.

As a string, this exception provides a human-readable message about what the problem was.

• Exhausted Iterators

Class: Iterator::X::Exhausted

You called "value|Iterator/value" on an iterator that is exhausted; that is, there are no more values in the sequence to return.

As a string, this exception is "Iterator is exhausted."

• User Code Exceptions

Class: Iterator::X::User_Code_Error

This exception is thrown when the sequence generation code throws any sort of error besides "Am_Now_Exhausted". This could be because your code explicitly threw an error (that is, "die"d), or because it otherwise encountered an exception (any runtime error).

This exception has one method, "eval_error", which returns the original $@ that was trapped by the Iterator object. This may be a string or an object, depending on how "die" was invoked.

As a string, this exception evaluates to the stringified $@.

• I/O Errors

Class: Iterator::X::IO_Error

This exception is thrown when any sort of I/O error occurs; this only happens with the filesystem iterators.

This exception has one method, "os_error", which returns the original $! that was trapped by the Iterator object.

As a string, this exception provides some human-readable information along with $!.

• Internal Errors

Class: Iterator::X::Internal_Error

Something happened that I thought couldn't possibly happen. I would appreciate it if you could send me an email message detailing the circumstances of the error.

📚 REQUIREMENTS 📚

Requires the following additional modules:

• Iterator

👀 SEE ALSO 👀

Higher Order Perl, Mark Jason Dominus, Morgan Kauffman 2005.

<http://perl.plover.com/hop/>

💐 THANKS 💐

Much thanks to Will Coleda and Paul Lalli (and the RPI lily crowd in general) for suggestions for the pre-release version.

---

👑 AUTHOR / COPYRIGHT 👑

Okay bestie, gather round, it's time to give credit where credit is absolutely, undeniably due 💖

This whole icon was written by Eric J. Roode, and you can slide into his inbox at roode@cpan.org. He's the main character of this manpage, no cap.

---

🌸 The Legal Bit (read it, it's short, I promise) 🌸

Copyright (c) 2005 by Eric J. Roode. All Rights Reserved.

This module is free software — you can redistribute it and/or modify it under the same terms as Perl itself. That's it, that's the whole vibe. Go forth and remix, just keep the terms intact, periodt ✨

---

📬 One tiny favour before you hit send 📬

His spam filter is, and I quote, doing the most, so if you're emailing him, please:

• put "Perl", "module", or this module's name in the subject line of your message, and/or
• GPG-sign your message 🫶

Do that and your email actually reaches a human instead of getting swallowed by the void 💀

---

And that's the whole page, bestie — you made it to the end like the scholar you are 🎀

This beauty ships as part of perl v5.34.0, and the page itself is dated 2022-06-15. It's filed under Util(3pm), and yeah, it ate 💅✨

Now go write something iconic with it. Mwah. 💖