Iter

custom : state, [Known(U64), Unknown], (state -> Try((item, state), [NoMore])) -> Iter(item)
exclusive_range : num, num -> Iter(num) where { num.is_lt : num, num -> Bool, num.add_try : num, num -> Try(num, [Overflow]), num.from_numeral : Numeral -> Try(num, [InvalidNumeral(Str)]), num.steps_between : num, num -> [Known(U64), Unknown] }

Iterator over num values from start up to but not including end. Returns an empty iterator if start >= end. This is what start..<end desugars to.

inclusive_range : num, num -> Iter(num) where { num.is_lte : num, num -> Bool, num.add_try : num, num -> Try(num, [Overflow]), num.from_numeral : Numeral -> Try(num, [InvalidNumeral(Str)]), num.steps_between : num, num -> [Known(U64), Unknown] }

Iterator over num values from start up to and including end. Returns an empty iterator if start > end. This is what start..=end desugars to.

iter : Iter(item) -> Iter(item)
single : item -> Iter(item)

Returns an iterator that yields exactly one item.

expect Iter.fold(Iter.single(42.I64), [], |acc, item| acc.append(item)) == [42]
prepended : Iter(item), item -> Iter(item)

Returns an iterator that yields the given item first, followed by everything the given iterator yields.

The compiler uses this to assemble the iterator it passes to from_interpolation when checking an interpolated string literal.

expect Iter.fold([2, 3].iter().prepended(1), [], |acc, item| acc.append(item)) == [1, 2, 3]
concat : Iter(item), Iter(item) -> Iter(item)

Returns an iterator that yields all items from the first iterator, then all items from the second iterator.

expect Iter.fold([1.I64, 2].iter().concat([3, 4].iter()), [], |acc, item| acc.append(item)) == [1, 2, 3, 4]
append : Iter(item), item -> Iter(item)

Returns an iterator that yields everything from the given iterator, followed by the given item.

expect Iter.fold([1.I64, 2].iter().append(3), [], |acc, item| acc.append(item)) == [1, 2, 3]
next : Iter(item) -> [One({ item : item, rest : Iter(item) }), Skip({ rest : Iter(item) }), Done]
map : Iter(a), (a -> b) -> Iter(b)
keep_if : Iter(a), (a -> Bool) -> Iter(a)
drop_if : Iter(a), (a -> Bool) -> Iter(a)
fold : Iter(a), acc, (acc, a -> acc) -> acc
size_hint : Iter(item) -> [Known(U64), Unknown]

Returns the iterator's length if it is known up front, so collections can pre-size their allocation.

collect : Iter(item) -> output where { output.from_iter : Iter(item) -> output }

Collect this iterator into any output type that provides from_iter.

stream : Iter(item) -> Stream(item)

Lift this pure iterator into an effectful Stream, so it can be combined with effectful operations like Stream.map.

take_first : Iter(item), U64 -> Iter(item)

Returns an iterator that yields at most the first n items of this iterator. If the source has fewer than n items, all of them are yielded.

expect Iter.fold(Iter.take_first(List.iter([1, 2, 3, 4, 5]), 3), [], |acc, item| acc.append(item)) == [1, 2, 3]

expect Iter.fold(Iter.take_first(List.iter([1, 2]), 5), [], |acc, item| acc.append(item)) == [1, 2]
drop_first : Iter(item), U64 -> Iter(item)

Returns an iterator that skips the first n items of this iterator. If the source has n or fewer items, the result is empty.

expect Iter.fold(Iter.drop_first(List.iter([1, 2, 3, 4, 5]), 2), [], |acc, item| acc.append(item)) == [3, 4, 5]

expect Iter.fold(Iter.drop_first(List.iter([1, 2, 3]), 10), [], |acc, item| acc.append(item)) == []
take_last : Iter(item), U64 -> Iter(item)

Returns an iterator that yields the last n items of this iterator. If the source has fewer than n items, all of them are yielded.

When the source iterator's length is unknown, this materializes the source into a list to find where the last n items begin. Avoid calling this on iterators whose length is unknown and might be huge.

expect Iter.fold(Iter.take_last(List.iter([1, 2, 3, 4, 5]), 3), [], |acc, item| acc.append(item)) == [3, 4, 5]

expect Iter.fold(Iter.take_last(List.iter([1, 2]), 5), [], |acc, item| acc.append(item)) == [1, 2]
drop_last : Iter(item), U64 -> Iter(item)

Returns an iterator that yields all items except the last n. If the source has n or fewer items, the result is empty.

When the source iterator's length is unknown, this materializes the source into a list to find where the last n items begin. Avoid calling this on iterators whose length is unknown and might be huge.

expect Iter.fold(Iter.drop_last(List.iter([1, 2, 3, 4, 5]), 2), [], |acc, item| acc.append(item)) == [1, 2, 3]

expect Iter.fold(Iter.drop_last(List.iter([1, 2, 3]), 10), [], |acc, item| acc.append(item)) == []
step_by : Iter(item), U64 -> Iter(item)

Returns an iterator that yields the first item and then every nth item after it, skipping the n - 1 items in between. A step of 0 yields an empty iterator.

expect Iter.fold(Iter.step_by(List.iter([1, 2, 3, 4, 5]), 2), [], |acc, item| acc.append(item)) == [1, 3, 5]

expect Iter.fold(Iter.step_by(List.iter([1, 2, 3]), 0), [], |acc, item| acc.append(item)) == []
rev : Iter(item) -> Iter(item)

Returns an iterator that yields this iterator's items in reverse order.

Because an Iter only moves forward, this materializes the source into a list to reverse it. The result always has a known length, so collecting it is efficient. Avoid calling this on iterators whose length is unknown and might be huge.

expect Iter.fold(Iter.rev(List.iter([1, 2, 3])), [], |acc, item| acc.append(item)) == [3, 2, 1]

expect Iter.fold(Iter.rev(List.iter([])), [], |acc, item| acc.append(item)) == []