API Reference

cache(it)

Cache the elements of an iterator so that subsequent iterations are served from the cache.

julia> c = cache(Iterators.map(println, 1:3));

julia> collect(c);
1
2
3

julia> collect(c);

Be aware that if iterating the original has a side-effect it will not be repeated when iterating again, – indeed that is a key feature of the CachedIterator. Be aware also that if the original iterator is nondeterminatistic in its order, when iterating again from the cache it will infact be determinatistic and will be the same order as before – this also is a feature.

distinct(xs)

Iterate through values skipping over those already encountered.

julia> for i in distinct([1,1,2,1,2,4,1,2,3,4])
           @show i
       end
i = 1
i = 2
i = 4
i = 3

fieldvalues(x)

Iterate through the values of the fields of x.

julia> collect(fieldvalues(1 + 2im))
2-element Vector{Any}:
 1
 2

firstrest(xs) -> (f, r)

Return the first element and an iterator of the rest as a tuple.

See also: Base.Iterators.peel.

julia> f, r = firstrest(1:3);

julia> f
1

julia> collect(r)
2-element Vector{Int64}:
 2
 3

flagfirst(iter)

An iterator that yields (isfirst, x) where isfirst::Bool is true for the first element, and false after that, while the xs are elements from iter.

julia> collect(flagfirst(1:3))
3-element Vector{Tuple{Bool, Int64}}:
 (1, 1)
 (0, 2)
 (0, 3)

groupby(f, xs)

Group consecutive values that share the same result of applying f.

julia> for i in groupby(x -> x[1], ["face", "foo", "bar", "book", "baz", "zzz"])
           @show i
       end
i = ["face", "foo"]
i = ["bar", "book", "baz"]
i = ["zzz"]

imap(f, xs1, [xs2, ...])

Iterate over values of a function applied to successive values from one or more iterators. Like Iterators.zip, the iterator is done when any of the input iterators have been exhausted.

julia> for i in imap(+, [1,2,3], [4,5,6])
            @show i
       end
i = 5
i = 7
i = 9

interleaveby(predicate=Base.isless, a, b)

Iterate over the an interleaving of a and b selected by the predicate (default less-than).

Input:

• predicate(ak,bk) -> Bool: Whether to pick the next element of a (true) or b (false).
• fa(ak), fb(bk): Functions to apply to the picked elements

julia> collect(interleaveby(1:2:5, 2:2:6))
6-element Vector{Int64}:
 1
 2
 3
 4
 5
 6

If the predicate is Base.isless (the default) and both inputs are sorted, this produces the sorted output. If the predicate is a stateful functor that alternates true-false-true-false... then this produces the classic interleave operation as described e.g. in the definition of microkanren.

iterated(f, x)

Iterate over successive applications of f, as in x, f(x), f(f(x)), f(f(f(x))), ...

Use Base.Iterators.take() to obtain the required number of elements.

julia> for i in Iterators.take(iterated(x -> 2x, 1), 5)
           @show i
       end
i = 1
i = 2
i = 4
i = 8
i = 16

julia> for i in Iterators.take(iterated(sqrt, 100), 6)
           @show i
       end
i = 100
i = 10.0
i = 3.1622776601683795
i = 1.7782794100389228
i = 1.333521432163324
i = 1.1547819846894583

ivec(iter)

Drops all shape from iter while iterating. Like a non-materializing version of vec.

julia> m = collect(reshape(1:6, 2, 3))
2×3 Matrix{Int64}:
 1  3  5
 2  4  6

julia> collect(ivec(m))
6-element Vector{Int64}:
 1
 2
 3
 4
 5
 6

ncycle(iter, n)

Cycle through iter n times.

julia> for i in ncycle(1:3, 2)
           @show i
       end
i = 1
i = 2
i = 3
i = 1
i = 2
i = 3

nth(xs, n)

Return the nth element of xs. This is mostly useful for non-indexable collections.

julia> powers_of_two = iterated(x->2x,1);

julia> nth(powers_of_two, 4)
8

partition(xs, n, [step])

Group values into n-tuples.

julia> for i in partition(1:9, 3)
           @show i
       end
i = (1, 2, 3)
i = (4, 5, 6)
i = (7, 8, 9)

If the step parameter is set, each tuple is separated by step values.

julia> for i in partition(1:9, 3, 2)
           @show i
       end
i = (1, 2, 3)
i = (3, 4, 5)
i = (5, 6, 7)
i = (7, 8, 9)

julia> for i in partition(1:9, 3, 3)
           @show i
       end
i = (1, 2, 3)
i = (4, 5, 6)
i = (7, 8, 9)

julia> for i in partition(1:9, 2, 3)
           @show i
       end
i = (1, 2)
i = (4, 5)
i = (7, 8)

peekiter(xs)

Lets you peek at the head element of an iterator without updating the state.

julia> it = peekiter(["face", "foo", "bar", "book", "baz", "zzz"]);

julia> peek(it)
Some("face")

julia> peek(it)
Some("face")

julia> x, s = iterate(it)
("face", ("foo", 3))

julia> x
"face"

julia> peek(it, s)
Some("foo")

properties(x)

Iterate through the names and value of the properties of x.

julia> collect(properties(1 + 2im))
2-element Vector{Any}:
 (:re, 1)
 (:im, 2)

propertyvalues(x)

Iterate through the values of the properties of x.

julia> collect(propertyvalues(1 + 2im))
2-element Vector{Any}:
 1
 2

repeatedly(f)
repeatedly(f, n)

Call function f n times, or infinitely if n is omitted.

julia> t() = (sleep(0.1); Dates.millisecond(now()))
t (generic function with 1 method)

julia> collect(repeatedly(t, 5))
5-element Vector{Any}:
 993
  97
 200
 303
 408

subsets(xs)
subsets(xs, k)
subsets(xs, Val{k}())

Iterate over every subset of the indexable collection xs. You can restrict the subsets to a specific size k.

Giving the subset size in the form Val{k}() allows the compiler to produce code optimized for the particular size requested. This leads to performance comparable to hand-written loops if k is small and known at compile time, but may or may not improve performance otherwise.

julia> for i in subsets([1, 2, 3])
          @show i
       end
i = Int64[]
i = [1]
i = [2]
i = [1, 2]
i = [3]
i = [1, 3]
i = [2, 3]
i = [1, 2, 3]

julia> for i in subsets(1:4, 2)
          @show i
       end
i = [1, 2]
i = [1, 3]
i = [1, 4]
i = [2, 3]
i = [2, 4]
i = [3, 4]

julia> for i in subsets(1:4, Val{2}())
           @show i
       end
i = (1, 2)
i = (1, 3)
i = (1, 4)
i = (2, 3)
i = (2, 4)
i = (3, 4)

takenth(xs, n)

Iterate through every nth element of xs.

julia> collect(takenth(5:15,3))
3-element Vector{Int64}:
  7
 10
 13

takestrict(xs, n::Int)

Like take(), an iterator that generates at most the first n elements of xs, but throws an exception if fewer than n items are encountered in xs.

julia> collect(takestrict(1:2:11, 3))
3-element Vector{Int64}:
 1
 3
 5

takewhile(cond, xs)

An iterator that yields values from the iterator xs as long as the predicate cond is true.

julia> collect(takewhile(x-> x^2 < 10, 1:100))
3-element Vector{Int64}:
 1
 2
 3

zip_longest(iters...; default=nothing)

For one or more iterable objects, return an iterable of tuples, where the ith tuple contains the ith component of each input iterable if it is not finished, and default otherwise. default can be a scalar, or a tuple with one default per iterable.

julia> for t in zip_longest(1:2, 5:8)
         @show t
       end
t = (1, 5)
t = (2, 6)
t = (nothing, 7)
t = (nothing, 8)

julia> for t in zip_longest('a':'e', ['m', 'n']; default='x')
         @show t
       end
t = ('a', 'm')
t = ('b', 'n')
t = ('c', 'x')
t = ('d', 'x')
t = ('e', 'x')

IterTools.@ifsomething expr

If expr evaluates to nothing, equivalent to return nothing, otherwise the macro evaluates to the value of expr. Not exported, useful for implementing iterators.

julia> IterTools.@ifsomething iterate(1:2)
(1, 1)

julia> let elt, state = IterTools.@ifsomething iterate(1:2, 2); println("not reached"); end