Iteration utilities

# Iteration utilities

`Base.Iterators.Stateful` — Type.

    Stateful(itr)

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

1. It provides a mutable wrapper around an iterator and its iteration state.
2. It turns an iterator-like abstraction into a `Channel`-like abstraction.
3. 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 Array{Char,1}:
     'b'
     'c'
     'd'

    julia> collect(a)
    2-element Array{Char,1}:
     'e'
     'f'

    julia> a = Iterators.Stateful([1,1,1,2,3,4]);

    julia> for x in a; x == 1 || break; end

    julia> Base.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.

Examples

    julia> a = 1:5
    1:5

    julia> b = ["e","d","b","c","a"]
    5-element Array{String,1}:
     "e"
     "d"
     "b"
     "c"
     "a"

    julia> c = zip(a,b)
    Base.Iterators.Zip{Tuple{UnitRange{Int64},Array{String,1}}}((1:5, ["e", "d", "b", "c", "a"]))

    julia> length(c)
    5

    julia> first(c)
    (1, "e")

source
`Base.Iterators.enumerate` — Function.

    enumerate(iter)

An iterator that yields `(i, x)` where `i` is a counter starting at 1, and `x` is the `i`th value from the given iterator. It's useful when you need not only the values `x` over which you are iterating, but also the number of iterations so far. Note that `i` may not be valid for indexing `iter`; it's also possible that `x != iter[i]`, if `iter` has indices that do not start at 1. See the `pairs(IndexLinear(), iter)` method if you want to ensure that `i` is an index.

Examples

    julia> a = ["a", "b", "c"];

    julia> for (index, value) in enumerate(a)
               println("$index $value")
           end
    1 a
    2 b
    3 c

source
`Base.Iterators.rest` — Function.

    rest(iter, state)

An iterator that yields the same elements as `iter`, but starting at the given `state`.

Examples

    julia> collect(Iterators.rest([1,2,3,4], 2))
    3-element Array{Int64,1}:
     2
     3
     4

source
`Base.Iterators.countfrom` — Function.

    countfrom(start=1, step=1)

An iterator that counts forever, starting at `start` and incrementing by `step`.

Examples

    julia> for v in Iterators.countfrom(5, 2)
               v > 10 && break
               println(v)
           end
    5
    7
    9

source
`Base.Iterators.take` — Function.

    take(iter, n)

An iterator that generates at most the first `n` elements of `iter`.

Examples

    julia> a = 1:2:11
    1:2:11

    julia> collect(a)
    6-element Array{Int64,1}:
      1
      3
      5
      7
      9
     11

    julia> collect(Iterators.take(a,3))
    3-element Array{Int64,1}:
     1
     3
     5

source
`Base.Iterators.drop` — Function.

    drop(iter, n)

An iterator that generates all but the first `n` elements of `iter`.

Examples

    julia> a = 1:2:11
    1:2:11

    julia> collect(a)
    6-element Array{Int64,1}:
      1
      3
      5
      7
      9
     11

    julia> collect(Iterators.drop(a,4))
    2-element Array{Int64,1}:
      9
     11

source
`Base.Iterators.cycle` — Function.

    cycle(iter)

An iterator that cycles through `iter` forever. If `iter` is empty, so is `cycle(iter)`.

Examples

    julia> for (i, v) in enumerate(Iterators.cycle("hello"))
               print(v)
               i > 10 && break
           end
    hellohelloh

source
`Base.Iterators.repeated` — Function.

    repeated(x[, n::Int])

An iterator that generates the value `x` forever. If `n` is specified, generates `x` that many times (equivalent to `take(repeated(x), n)`).

Examples

    julia> a = Iterators.repeated([1 2], 4);

    julia> collect(a)
    4-element Array{Array{Int64,2},1}:
     [1 2]
     [1 2]
     [1 2]
     [1 2]

source
`Base.Iterators.product` — Function.

    product(iters...)

Return an iterator over the product of several iterators. Each generated element is a tuple whose `i`th element comes from the `i`th argument iterator. The first iterator changes the fastest.

Examples

    julia> collect(Iterators.product(1:2, 3:5))
    2×3 Array{Tuple{Int64,Int64},2}:
     (1, 3)  (1, 4)  (1, 5)
     (2, 3)  (2, 4)  (2, 5)

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 Array{Int64,1}:
     1
     2
     8
     9

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 Array{Array{Int64,1},1}:
     [1, 2]
     [3, 4]
     [5]

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),Array{Int64,1}}(isodd, [1, 2, 3, 4, 5])

    julia> foreach(println, f)
    1
    3
    5

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