Iteration utilities

Stateful(itr)

هناك عدة طرق مختلفة للتفكير في هذا الغلاف الخاص بالمكرر:

1. يوفر غلافًا قابلًا للتغيير حول مكرر وحالته في التكرار.
2. يحول تجريدًا يشبه المكرر إلى تجريد يشبه Channel.
3. إنه مكرر يتغير ليصبح مكرره الخاص المتبقي كلما تم إنتاج عنصر.

يوفر Stateful واجهة المكرر العادية. مثل المكررات القابلة للتغيير الأخرى (مثل Base.Channel)، إذا تم إيقاف التكرار مبكرًا (مثل break في حلقة for)، يمكن استئناف التكرار من نفس النقطة من خلال الاستمرار في التكرار على نفس كائن المكرر (على عكس، سيعيد المكرر غير القابل للتغيير البدء من البداية).

أمثلة

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 هو مجموعة من قيم مكرراته الفرعية.

!!! ملاحظة يقوم zip بترتيب المكالمات لمكرراته الفرعية بطريقة تجعل المكررات ذات الحالة لا تتقدم عندما ينتهي مكرر آخر في التكرار الحالي.

!!! ملاحظة 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، وقد يحدث ذلك بالنسبة للسلاسل، والقواميس، وما إلى ذلك. انظر إلى طريقة pairs(IndexLinear(), iter) إذا كنت تريد التأكد من أن i هو فهرس.

أمثلة

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، ولكن بدءًا من الحالة المعطاة.

انظر أيضًا: 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)

مكرر يقوم بإنشاء ما يصل إلى أول n عناصر من iter.

انظر أيضًا: 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)

مكرر يقوم بإنشاء عناصر من iter طالما أن الشرط pred صحيح، وبعد ذلك، يتجاهل كل عنصر.

أمثلة

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)

مكرر يقوم بإنشاء جميع العناصر ما عدا أول n عنصر من iter.

أمثلة

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)

مكرر يقوم بإسقاط العناصر من iter طالما أن الشرط pred صحيح، وبعد ذلك، يعيد كل عنصر.

أمثلة

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[, n::Int])

مكرر يتنقل عبر iter إلى الأبد. إذا تم تحديد n، فإنه يتنقل عبر iter بعدد مرات يساوي n. عندما يكون iter فارغًا، فإن cycle(iter) و cycle(iter, n) يكونان فارغين أيضًا.

Iterators.cycle(iter, n) هو المعادل الكسول لـ Base.repeat(vector, n), بينما Iterators.repeated(iter, n) هو Base.fill(item, n) الكسول.

أمثلة

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

julia> foreach(print, Iterators.cycle(['j', 'u', 'l', 'i', 'a'], 3))
juliajuliajulia

julia> repeat([1,2,3], 4) == collect(Iterators.cycle([1,2,3], 4))
true

julia> fill([1,2,3], 4) == collect(Iterators.repeated([1,2,3], 4))
true

repeated(x[, n::Int])

مكرر يولد القيمة x إلى الأبد. إذا تم تحديد n، فإنه يولد x بعدد مرات n (ما يعادل take(repeated(x), n)).

انظر أيضًا fill، وقارن Iterators.cycle.

أمثلة

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

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

julia> ans == fill([1 2], 4)
true

julia> Iterators.cycle([1 2], 4) |> collect |> println
[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]  # يجمع مولد يتضمن 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']  # يجمع المولدات التي تتضمن 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، تُرجع كائنًا قابلًا للتكرار والذي عند التكرار عليه يُنتج العناصر x من itr التي تحقق flt(x). يتم الحفاظ على ترتيب المُكرّر الأصلي.

هذه الدالة كسولة؛ أي أنه من المؤكد أنها ستُرجع في $Θ(1)$ زمن وتستخدم $Θ(1)$ مساحة إضافية، وflt لن يتم استدعاؤها بواسطة استدعاء filter. سيتم إجراء استدعاءات لـ flt عند التكرار على كائن iterable المُرجع. هذه الاستدعاءات ليست مخزنة وسيتم إجراء استدعاءات متكررة عند إعادة التكرار.

!!! تحذير ستؤخر التحولات الكسولة اللاحقة على المُكرّر المُرجع من filter، مثل تلك التي يتم تنفيذها بواسطة Iterators.reverse أو cycle، أيضًا استدعاءات flt حتى يتم جمع أو التكرار على كائن iterable المُرجع. إذا كانت دالة الشرط غير حتمية أو كانت قيم إرجاعها تعتمد على ترتيب التكرار على عناصر itr، قد تؤدي التركيبة مع التحولات الكسولة إلى سلوك مفاجئ. إذا كان هذا غير مرغوب فيه، تأكد إما من أن flt هي دالة نقية أو اجمع مُكرّرات filter الوسيطة قبل إجراء مزيد من التحولات.

انظر 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)]  # يجمع مولدًا عبر Iterators.filter
3-element Vector{Int64}:
 1
 3
 5

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

بالنظر إلى دالة ذات وسيطتين 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 لتنفيذ متحمس.

(بشكل افتراضي، فإن هذا يعيد كائن Iterators.Reverse الذي يلتف حول itr، والذي يمكن تكراره إذا كانت طرق iterate المقابلة معرفة، ولكن بعض أنواع itr قد تنفذ سلوكيات Iterators.reverse أكثر تخصصًا.)

ليس كل أنواع المكررات T تدعم التكرار بترتيب عكسي. إذا لم يكن T يدعم ذلك، فإن التكرار على Iterators.reverse(itr::T) سيثير MethodError بسبب عدم وجود طرق iterate لـ Iterators.Reverse{T}. (لتنفيذ هذه الطرق، يمكن الحصول على المكرر الأصلي itr::T من كائن r::Iterators.Reverse{T} بواسطة r.itr؛ بشكل عام، يمكن استخدام 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 (الفئة Ll: حرف، صغير)

julia> only(())
ERROR: ArgumentError: Tuple يحتوي على 0 عناصر، يجب أن يحتوي بالضبط على 1 عنصر
Stacktrace:
[...]

julia> only(('a', 'b'))
ERROR: ArgumentError: Tuple يحتوي على 2 عناصر، يجب أن يحتوي بالضبط على 1 عنصر
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)