Iteration utilities

Iteration utilities

Stateful(itr)

There are several different ways to think about this iterator wrapper:

It provides a mutable wrapper around an iterator and its iteration state.
It turns an iterator-like abstraction into a Channel-like abstraction.
It’s an iterator that mutates to become its own rest iterator whenever an item is produced.

Stateful provides the regular iterator interface. Like other mutable iterators (e.g. Channel), if iteration is stopped early (e.g. by a break in a for loop), iteration can be resumed from the same spot by continuing to iterate over the same iterator object (in contrast, an immutable iterator would restart from the beginning).

Examples

julia> a = Iterators.Stateful("abcdef");
julia> isempty(a)
false
julia> popfirst!(a)
'a': ASCII/Unicode U+0061 (category Ll: Letter, lowercase)
julia> collect(Iterators.take(a, 3))
3-element Vector{Char}:
 'b': ASCII/Unicode U+0062 (category Ll: Letter, lowercase)
 'c': ASCII/Unicode U+0063 (category Ll: Letter, lowercase)
 'd': ASCII/Unicode U+0064 (category Ll: Letter, lowercase)
julia> collect(a)
2-element Vector{Char}:
 'e': ASCII/Unicode U+0065 (category Ll: Letter, lowercase)
 'f': ASCII/Unicode U+0066 (category Ll: Letter, lowercase)
julia> Iterators.reset!(a); popfirst!(a)
'a': ASCII/Unicode U+0061 (category Ll: Letter, lowercase)
julia> Iterators.reset!(a, "hello"); popfirst!(a)
'h': ASCII/Unicode U+0068 (category Ll: Letter, lowercase)

julia> a = Iterators.Stateful([1,1,1,2,3,4]);
julia> for x in a; x == 1 || break; end
julia> peek(a)
3
julia> sum(a) # Sum the remaining elements
7

source

Base.Iterators.zip — Function

zip(iters...)

Run multiple iterators at the same time, until any of them is exhausted. The value type of the zip iterator is a tuple of values of its subiterators.

Note

zip orders the calls to its subiterators in such a way that stateful iterators will not advance when another iterator finishes in the current iteration.

See also: zip, Iterators.flatten.

Examples

julia> collect(Iterators.product(1:2, 3:5))
2×3 Matrix{Tuple{Int64, Int64}}:
 (1, 3)  (1, 4)  (1, 5)
 (2, 3)  (2, 4)  (2, 5)
julia> ans == [(x,y) for x in 1:2, y in 3:5]  # collects a generator involving Iterators.product
true

source

Base.Iterators.flatten — Function

flatten(iter)

Given an iterator that yields iterators, return an iterator that yields the elements of those iterators. Put differently, the elements of the argument iterator are concatenated.

Examples

julia> collect(Iterators.flatten((1:2, 8:9)))
4-element Vector{Int64}:
 1
 2
 8
 9
julia> [(x,y) for x in 0:1 for y in 'a':'c']  # collects generators involving Iterators.flatten
6-element Vector{Tuple{Int64, Char}}:
 (0, 'a')
 (0, 'b')
 (0, 'c')
 (1, 'a')
 (1, 'b')
 (1, 'c')

source

Base.Iterators.partition — Function

partition(collection, n)

Iterate over a collection n elements at a time.

Examples

julia> collect(Iterators.partition([1,2,3,4,5], 2))
3-element Vector{SubArray{Int64, 1, Vector{Int64}, Tuple{UnitRange{Int64}}, true}}:
 [1, 2]
 [3, 4]
 [5]

source

Base.Iterators.map — Function

Iterators.map(f, iterators...)

Create a lazy mapping. This is another syntax for writing (f(args...) for args in zip(iterators...)).

Julia 1.6

This function requires at least Julia 1.6.

Examples

julia> collect(Iterators.map(x -> x^2, 1:3))
3-element Vector{Int64}:
 1
 4
 9

source

Base.Iterators.filter — Function

Iterators.filter(flt, itr)

Given a predicate function flt and an iterable object itr, return an iterable object which upon iteration yields the elements x of itr that satisfy flt(x). The order of the original iterator is preserved.

This function is lazy; that is, it is guaranteed to return in $Θ(1)$ time and use $Θ(1)$ additional space, and flt will not be called by an invocation of filter. Calls to flt will be made when iterating over the returned iterable object. These calls are not cached and repeated calls will be made when reiterating.

See Base.filter for an eager implementation of filtering for arrays.

Examples

julia> f = Iterators.filter(isodd, [1, 2, 3, 4, 5])
Base.Iterators.Filter{typeof(isodd), Vector{Int64}}(isodd, [1, 2, 3, 4, 5])
julia> foreach(println, f)
1
3
5
julia> [x for x in [1, 2, 3, 4, 5] if isodd(x)]  # collects a generator over Iterators.filter
3-element Vector{Int64}:
 1
 3
 5

source

Base.Iterators.accumulate — Function

Iterators.accumulate(f, itr; [init])

Given a 2-argument function f and an iterator itr, return a new iterator that successively applies f to the previous value and the next element of itr.

This is effectively a lazy version of Base.accumulate.

Julia 1.5

Keyword argument init is added in Julia 1.5.

Examples

julia> f = Iterators.accumulate(+, [1,2,3,4]);
julia> foreach(println, f)
1
3
6
10
julia> f = Iterators.accumulate(+, [1,2,3]; init = 100);
julia> foreach(println, f)
101
103
106

source

Base.Iterators.reverse — Function

Iterators.reverse(itr)

Given an iterator itr, then reverse(itr) is an iterator over the same collection but in the reverse order.

This iterator is “lazy” in that it does not make a copy of the collection in order to reverse it; see Base.reverse for an eager implementation.

Not all iterator types T support reverse-order iteration. If T doesn’t, then iterating over Iterators.reverse(itr::T) will throw a MethodError because of the missing iterate methods for Iterators.Reverse{T}. (To implement these methods, the original iterator itr::T can be obtained from r = Iterators.reverse(itr) by r.itr.)

Examples

julia> foreach(println, Iterators.reverse(1:5))
5
4
3
2
1

source

Base.Iterators.only — Function

only(x)

Returns the one and only element of collection x, and throws an ArgumentError if the collection has zero or multiple elements.