IterTools

Installation

Install this package with Pkg.add("IterTools")

Usage

distinct(xs)

Iterate through values skipping over those already encountered.

IterTools.distinctFunction
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
source

firstrest(xs)

Return first element and Iterators.rest iterator as a tuple.

IterTools.firstrestFunction
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
source

groupby(f, xs)

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

IterTools.groupbyFunction
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"]
source

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

Iterate over values of a function applied to successive values from one or more iterators.

IterTools.imapFunction
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
source

iterated(f, x)

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

IterTools.iteratedFunction
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
source

ncycle(xs, n)

Cycles through an iterator n times.

IterTools.ncycleFunction
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
source

nth(xs, n)

Return the nth element of xs.

IterTools.nthFunction
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
source

partition(xs, n, [step])

Group values into n-tuples.

IterTools.partitionFunction
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)
source

ivec(xs)

Iterate over xs but do not preserve shape information.

IterTools.ivecFunction
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
source

peekiter(xs)

Peek at the head element of an iterator without updating the state.

IterTools.peekiterFunction
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")
source

repeatedly(f, [n])

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

IterTools.repeatedlyFunction
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
source

takenth(xs, n)

Iterate through every n'th element of xs

IterTools.takenthFunction
takenth(xs, n)

Iterate through every nth element of xs.

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

subsets(xs, [k])

Iterate over every subset of an indexable collection xs, or iterate over every subset of size k from an indexable collection xs.

IterTools.subsetsFunction
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)
source

takestrict(xs, n)

Equivalent to take, but will throw an exception if fewer than n items are encountered in xs.

IterTools.takestrictFunction
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
source

takewhile(cond, xs)

Iterates through values from the iterable xs as long as a given predicate cond is true.

IterTools.takewhileFunction
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
source

flagfirst(xs)

Provide a flag to check if this is the first element.

IterTools.flagfirstFunction
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)
source

IterTools.@ifsomething

Helper macro for returning from the enclosing block when there are no more elements.

IterTools.@ifsomethingMacro
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
source

properties(x)

Iterate over struct or named tuple properties.

IterTools.propertiesFunction
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)
source

propertyvalues(x)

Iterate over struct or named tuple property values.

IterTools.propertyvaluesFunction
propertyvalues(x)

Iterate through the values of the properties of x.

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

fieldvalues(x)

Like (getfield(x, i) for i in 1:nfields(x)) but faster.

IterTools.fieldvaluesFunction
fieldvalues(x)

Iterate through the values of the fields of x.

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