Iter[T]
Abstract type for iterators, whose instances have the methods below. Built-in
iterators are Iter; a class that only implements (next)
is not.
Iter is not constructible directly. See
Classes for defining custom iterators.
Inherits from: Iterable[T]
Implements: BaseIter[T], Unpack[T]
Methods
all … -> Bool
Returns true if every yielded value is truthy.
When pred is provided, it tests pred(value) instead.
Empty iterators return true.
Parameters
| Name | Type | Description |
|---|---|---|
pred? |
((T) -> Value) |
any … -> Bool
Returns true if any yielded value is truthy.
When pred is provided, it tests pred(value) instead.
Empty iterators return false.
Parameters
| Name | Type | Description |
|---|---|---|
pred? |
((T) -> Value) |
chain[...Us] ...values -> Iter[Union[T, ...Us]]
Returns an iterator that yields this iterator followed by each additional iterable in sequence.
Parameters
| Name | Type | Description |
|---|---|---|
...values |
...Iterable[Us] |
chomp[U @ (Str | Bin)]() -> Iter[U]
Creates a wrapper Iter which removes one trailing line terminator (\r\n or
\n) from each item, if present.
Parameters
| Name | Type | Description |
|---|---|---|
self |
Iter[U] |
Receiver. |
Errors
Getting an item raises TypeError if the underlying
Iter yields neither a Str nor a Bin.
Example
assert_eq [...["a\n", "b\r\n", "c"].chomp()] ["a", "b", "c"]
for line = shell.stdin.chomp()
echo "got $line"
Distinct from Str.trim_end, which is about whitespace generally
and takes an optional character set. chomp is about a line terminator
specifically and takes nothing.
count() -> Int
Consumes the iterator and returns the number of yielded values.
crimp[U @ (Str | Bin)] … -> Iter[U]
Creates a wrapper Iter which appends a line terminator to each item.
The inverse of chomp, and the usual way to terminate values on
their way into a byte stream.
The terminator is appended unconditionally: an item that already ends in one gets a second.
Parameters
| Name | Type | Description |
|---|---|---|
self |
Iter[U] |
Receiver. |
terminator? |
(Str | Bin) |
Errors
Raises TypeError for an item, or a terminator, that is
neither a Str nor a Bin, or if a Bin terminator would leave a Str item
invalid UTF-8.
Example
assert_eq [...["a", "b"].crimp()] ["a\n", "b\n"]
assert_eq [...["a"].crimp("\r\n")] ["a\r\n"]
run cmd stdin: (["one", "two"].crimp())
enumerate() -> Iter[Tuple[Int, T]]
Returns an iterator that yields [index, value] tuples.
The first index is 0.
filter pred -> Iter[T]
Creates a wrapper Iter which yields each value from the wrapper iterator
only if pred(value) is truthy.
Parameters
| Name | Type | Description |
|---|---|---|
pred |
((T) -> Value) |
find[D = T] pred … -> (T | D)
Consumes the iterator and returns the first value where pred(value) is truthy.
Parameters
| Name | Type | Description |
|---|---|---|
pred |
((T) -> Value) |
|
:default? |
D |
|
:else? |
(() -> D) |
Errors
Raises RuntimeError if no value matches and
no fallback is provided.
fold[A] init func -> A
Consumes the iterator left-to-right, repeatedly applying func(acc, value).
Returns init unchanged if the iterator is empty.
Parameters
| Name | Type | Description |
|---|---|---|
init |
A |
|
func |
((A, T) -> A) |
kv() -> Iter[T]
Returns an iterator wrapper that preserves normal iteration, but opts into key/value spreading.
When spread in a keyed context such as a dict literal or argument spread, each yielded item must unpack into exactly two values.
let entries = ["x=1", "y=2"].iter().map do |e| e.split "="
assert_eq {...entries.kv()} {"x": "1", "y": "2"}
map[U] func -> Iter[U]
Creates a wrapper Iter which yields func(value) for each value yielded by
the wrapper iterator.
Parameters
| Name | Type | Description |
|---|---|---|
func |
((T) -> U) |
max[D = T] … -> (T | D)
Consumes the iterator and returns the maximum yielded value.
Parameters
| Name | Type | Description |
|---|---|---|
:default? |
D |
Errors
Raises IterStop if the iterator is empty and no
default: is provided.
min[D = T] … -> (T | D)
Consumes the iterator and returns the minimum yielded value.
Parameters
| Name | Type | Description |
|---|---|---|
:default? |
D |
Errors
Raises IterStop if the iterator is empty and no
default: is provided.
next[D = T] … -> (T | D)
Returns the next value from the iterator.
Parameters
| Name | Type | Description |
|---|---|---|
:default? |
D |
|
:else? |
(() -> D) |
Errors
Raises IterStop when exhausted and no fallback
is provided.
skip n -> Iter[T]
Returns an iterator that discards the first n values, then yields the rest.
Parameters
| Name | Type | Description |
|---|---|---|
n |
Int |
Errors
| Exception | Condition |
|---|---|
TypeError |
n is not an Int |
ValueError |
n is negative |
take n -> Iter[T]
Returns an iterator that yields at most n values.
Parameters
| Name | Type | Description |
|---|---|---|
n |
Int |
Errors
| Exception | Condition |
|---|---|
TypeError |
n is not an Int |
ValueError |
n is negative |
zip[...Us] ...values -> Iter[Tuple[T, ...Us]]
Returns an iterator that yields one tuple for each step across this iterator and the additional iterables. The zipped iterator stops as soon as any input is exhausted.
Parameters
| Name | Type | Description |
|---|---|---|
...values |
...Iterable[Us] |