An iterator wrapper, iter, is a builtin type that can wrap any iterator to automatically add support for a set of chainable, lazily-evaluated utility methods.

$iter(arg: iterator|iterable) -> iter

Wraps an iterator in an iter wrapper. The argument can be an iterator or an instance of an iterable type.

All the iterators returned by Pyro builtins come pre-wrapped in iter wrappers, e.g. the char iterator returned by a string's :chars() method:

for item in "abcd":chars():enumerate() {
    echo item;
}

Here, calling the :chars() method on the string returns an iter[char] — i.e. an iterator over the string's UTF-8 encoded Unicode codepoints. The :enumerate() method is provided by the iter wrapper. It adds an index to each element in the input, giving us the following output:

(0, 'a')
(1, 'b')
(2, 'c')
(3, 'd')

Note that an iter object is both an iterator and an iterable type — it's an iterator because it has a :$next() method that returns the next item from the sequence, and it's an iterable type because it has an :$iter() method that returns an iterator (in this case, it simply returns itself).

You can learn more about Pyro's iterator protocol here.

Methods

:count() -> i64

Returns the number of items in the sequence. Note that calling this method exhausts the iterator.

:enumerate() -> iter[tup[i64, any]]
:enumerate(start_index: i64) -> iter[tup[i64, any]]

Returns a new iter instance whose output values are two-item tuples containing an integer index and the original input value. start_index defaults to zero if not specified.

:filter(callback: callable(any) -> bool) -> iter

Returns a new iter instance that filters the output of the source iterator using the callback function.

• callback should be a callable that takes a single argument and returns a bool.
• Input values will be passed through the filter if callback returns true.

:join() -> str
:join(sep: str) -> str

Joins the items returned by the iterator into a string, with each pair of items separated by sep. (The separator defaults to an empty string if not specified.)

Items are automatically stringified — this is equivalent to calling $str() on each item.

Returns an empty string if the iterator is empty or exhausted.

:map(callback: callable(any) -> any) -> iter

Returns a new iter instance mapping the function callback to the output of the source iterator.

• callback should be a callable that takes a single argument.
• The return values of callback will form the output of the new iterator.

:next() -> any

Returns the next item from the iterator. Returns an err if the iterator has been exhausted.

:product() -> any

Returns the result of multiplying the iterator's values using the * operator.

Returns null if the iterator is empty.

:reduce(
    callback: callable(any, any) -> any,
    initial_value: any
) -> any

Reduces the iterator to single value using callback, where callback is a function that takes two arguments — an accumulator value and the next value from the iterator.

initial_value is the initial value of the accumulator.

Returns initial_value if the iterator is empty.

:skip_first(n: i64) -> iter

Skips the first n items generated by the iterator. Panics if the iterator generates less than n items.

:skip_last(n: i64) -> iter

Skips the last n items generated by the iterator. Panics if the iterator generates less than n items.

Note that this method needs to buffer the iterator's full output to determine the end point.

:sum() -> any

Returns the result of adding the iterator's values using the + operator.

Returns null if the iterator is empty.

:to_set() -> set

Drains the iterator into a new set.

:to_vec() -> vec

Drains the iterator into a new vector.