反覆運算工具程式

Stateful(itr)

有許多不同的方式可以思考這個反覆運算包裝器

1. 它提供了一個可變包裝器，用於反覆運算器及其反覆運算狀態。
2. 它將類反覆運算的抽象轉換為類 Channel 的抽象。
3. 它是一個反覆運算器，會在產生項目時變異為自己的餘數反覆運算器。

Stateful 提供常規迭代器介面。與其他可變動迭代器（例如 Base.Channel）一樣，如果提早停止迭代（例如在 for 迴圈中使用 break），可以繼續對同一個迭代器物件進行迭代，從同一個點繼續迭代（相反地，不可變動迭代器會從頭開始）。

範例

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

zip(iters...)

同時執行多個迭代器，直到其中任何一個耗盡。zip 迭代器的值類型是其子迭代器值的元組。

另請參閱：enumerate、Base.splat。

範例

julia> a = 1:5
1:5

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

julia> c = zip(a,b)
zip(1:5, ["e", "d", "b", "c", "a"])

julia> length(c)
5

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

enumerate(iter)

一個產生 (i, x) 的迭代器，其中 i 是從 1 開始的計數器，而 x 是給定迭代器中的第 i 個值。當您不僅需要您正在迭代的值 x，還需要到目前為止的迭代次數時，這很有用。

請注意，i 可能不適用於對 iter 進行索引，或者可能索引不同的元素。如果 iter 的索引不是從 1 開始，這就會發生，並且可能會發生在字串、字典等。如果您想確保 i 是索引，請參閱 pairs(IndexLinear(), iter) 方法。

範例

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

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

julia> str = "naïve";

julia> for (i, val) in enumerate(str)
           print("i = ", i, ", val = ", val, ", ")
           try @show(str[i]) catch e println(e) end
       end
i = 1, val = n, str[i] = 'n'
i = 2, val = a, str[i] = 'a'
i = 3, val = ï, str[i] = 'ï'
i = 4, val = v, StringIndexError("naïve", 4)
i = 5, val = e, str[i] = 'v'

rest(iter, state)

一個迭代器，產生與 iter 相同的元素，但從給定的 state 開始。

另見：Iterators.drop、Iterators.peel、Base.rest。

範例

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

countfrom(start=1, step=1)

一個永遠計數的迭代器，從 start 開始並以 step 為增量。

範例

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

take(iter, n)

一個迭代器，產生 iter 最多前 n 個元素。

另見：drop、peel、first、Base.take!。

範例

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

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

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

takewhile(pred, iter)

一個迭代器，只要謂詞 pred 為真就從 iter 產生元素，之後，捨棄每個元素。

範例

julia> s = collect(1:5)
5-element Vector{Int64}:
 1
 2
 3
 4
 5

julia> collect(Iterators.takewhile(<(3),s))
2-element Vector{Int64}:
 1
 2

drop(iter, n)

一個迭代器，產生 iter 中除了前 n 個元素之外的所有元素。

範例

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

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

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

dropwhile(pred, iter)

一個迭代器，只要謂詞 pred 為真就從 iter 捨棄元素，之後，傳回每個元素。

範例

julia> s = collect(1:5)
5-element Vector{Int64}:
 1
 2
 3
 4
 5

julia> collect(Iterators.dropwhile(<(3),s))
3-element Vector{Int64}:
 3
 4
 5

cycle(iter)

一個永遠循環遍歷 iter 的迭代器。如果 iter 為空，則 cycle(iter) 也為空。

另請參閱：Iterators.repeated、Base.repeat。

範例

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

repeated(x[, n::Int])

一個永遠產生值 x 的迭代器。如果指定了 n，則產生 x 這麼多次（等同於 take(repeated(x), n)）。

另請參閱：Iterators.cycle、Base.repeat。

範例

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

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

product(iters...)

傳回多個迭代器乘積的迭代器。每個產生的元素都是一個元組，其第 i 個元素來自第 i 個參數迭代器。第一個迭代器變化的最快。

另請參閱：zip、Iterators.flatten。

範例

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

flatten(iter)

給定一個產生迭代器的迭代器，傳回一個產生這些迭代器元素的迭代器。換句話說，參數迭代器的元素會被串接。

範例

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')

Iterators.flatmap(f, iterators...)

等同於 flatten(map(f, iterators...))。

另請參閱 Iterators.flatten、Iterators.map。

範例

julia> Iterators.flatmap(n -> -n:2:n, 1:3) |> collect
9-element Vector{Int64}:
 -1
  1
 -2
  0
  2
 -3
 -1
  1
  3

julia> stack(n -> -n:2:n, 1:3)
ERROR: DimensionMismatch: stack expects uniform slices, got axes(x) == (1:3,) while first had (1:2,)
[...]

julia> Iterators.flatmap(n -> (-n, 10n), 1:2) |> collect
4-element Vector{Int64}:
 -1
 10
 -2
 20

julia> ans == vec(stack(n -> (-n, 10n), 1:2))
true

partition(collection, n)

一次遍歷集合中的 n 個元素。

範例

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]

Iterators.map(f, iterators...)

建立一個延遲映射。這是寫入 (f(args...) for args in zip(iterators...)) 的另一種語法。

範例

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

Iterators.filter(flt, itr)

給定一個謂詞函數 flt 和一個可迭代物件 itr，回傳一個可迭代物件，在迭代時會產生滿足 flt(x) 的 itr 元素 x。原始迭代器的順序會被保留。

此函數是延遲的；也就是說，它保證在 $Θ(1)$ 時間內回傳並使用 $Θ(1)$ 的額外空間，而且 flt 函數不會在呼叫 filter 時被呼叫。呼叫 flt 函數會在迭代回傳的可迭代物件時進行。這些呼叫不會被快取，而且在重新迭代時會重複呼叫。

請參閱 Base.filter 以取得陣列過濾的立即實作。

範例

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

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

給定一個 2 個引數的函數 f 和一個迭代器 itr，回傳一個新的迭代器，會連續將 f 套用至前一個值和 itr 的下一個元素。

這實際上是 Base.accumulate 的延遲版本。

範例

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

julia> foreach(println, a)
1
3
6
10

julia> b = Iterators.accumulate(/, (2, 5, 2, 5); init = 100);

julia> collect(b)
4-element Vector{Float64}:
 50.0
 10.0
  5.0
  1.0

Iterators.reverse(itr)

假設有一個反覆子 itr，則 reverse(itr) 是同一個集合的反覆子，但順序相反。這個反覆子是「惰性」的，也就是說它不會為了反轉而複製集合；請參閱 Base.reverse 以取得急切實作。

（預設情況下，這會傳回一個包裝 itr 的 Iterators.Reverse 物件，如果對應的 iterate 方法有定義，則此物件可反覆，但某些 itr 類型可能會實作更專業的 Iterators.reverse 行為。）

並非所有反覆子類型 T 都支援反向順序反覆。如果 T 不支援，則反覆 Iterators.reverse(itr::T) 會擲出 MethodError，因為 Iterators.Reverse{T} 缺少 iterate 方法。（若要實作這些方法，可以透過 r.itr 從 r::Iterators.Reverse{T} 物件取得原始反覆子 itr::T；更一般來說，可以使用 Iterators.reverse(r)。）

範例

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

only(x)

傳回集合 x 的唯一元素，如果集合有零個或多個元素，則擲出 ArgumentError。

另請參閱 first、last。

範例

julia> only(["a"])
"a"

julia> only("a")
'a': ASCII/Unicode U+0061 (category Ll: Letter, lowercase)

julia> only(())
ERROR: ArgumentError: Tuple contains 0 elements, must contain exactly 1 element
Stacktrace:
[...]

julia> only(('a', 'b'))
ERROR: ArgumentError: Tuple contains 2 elements, must contain exactly 1 element
Stacktrace:
[...]

peel(iter)

傳回第一個元素和一個反覆子，反覆子會反覆其餘元素。

如果反覆子是空的，則傳回 nothing（就像 iterate）。

另請參閱：Iterators.drop、Iterators.take。

範例

julia> (a, rest) = Iterators.peel("abc");

julia> a
'a': ASCII/Unicode U+0061 (category Ll: Letter, lowercase)

julia> collect(rest)
2-element Vector{Char}:
 'b': ASCII/Unicode U+0062 (category Ll: Letter, lowercase)
 'c': ASCII/Unicode U+0063 (category Ll: Letter, lowercase)