5.67. kink/iter/ITER

Provides operations for iters or iterators.

5.67.1. type iter

Unidirectional iterator.

An iter is backed by an ifun.

5.67.1.1. Iter.ifun

`ifun` returns the ifun backing the Iter.

5.67.1.2. Iter.each($on_elem)

`each` calls $on_elem for each elements of `Iter`, then returns the last result of $on_elem.

If `Iter` has no elements, `each` returns nada.

5.67.1.3. Iter.concat

`concat` returns an iter, which concatenates the elements of iters in `Iter`.

`Iter` must be an iter of iters.

5.67.1.4. Iter.chunk(Chunk_size)

`chunk` returns an iter of chunks with `Chunk_size`.

For example, if `Iter` contains E1, E2, E3, E4, E5, E6, E7, and `Chunk_size` is 2, this method returns an iter containing [E1 E2], [E3 E4] and [E5 E6]. The last E7 is ignored because there are not enough number of elements as a chunk.

`Chunk_size` must be an int num, and >= 1.

5.67.1.5. Iter.map($transform)

`map` returns an iter whose elements are transformed from `Iter` by $transform.

When `Iter` has elements E1, E2, ,,, , the result iter has elements transform(E1), transform(E2), ,,, .

5.67.1.6. Iter.concat_map($transform_to_iter)

Calling `concat_map` is equivalent to call Iter.map($transform_to_iter).concat.

5.67.1.7. Iter.filter($include?)

`filter` filters elements of `Iter` by the predicate $include?.

The result iter only contains elements of `Iter` which satisfy $include?. the order of elements are not changed.

5.67.1.8. Iter.count($counted?)

`count` returns the number of elements of `Iter` which satisfy $counted?.

5.67.1.9. Iter.fold(Init $combine)

`fold` accumulates elements of `Iter` seeded by `Init`.

If the elements of `Iter` is E1, E2, ,,, En_1, En, this fun returns combine(combine(,,,combine(combine(Init E1) E2),,, En_1) En).

If `Iter` is empty, this fun returns `Init`.

5.67.1.10. Iter.reduce($combine ...[$empty_fallback])

`reduce` accumulates elements of `Iter` mutually.

If `Iter` has elements E1, E2, E3, ,,, En_1, En, `reduce` returns combine(combine(,,,combine(combine(E1 E2) E3),,, En_1) En).

If `Iter` has a single element `E`, `reduce` returns `E`.

If `Iter` has no element, and $empty_fallback is given, `reduce` tail-calls $empty_fallback with no arg.

If `Iter` has no element, and $empty_fallback is not given, `reduce` raises an exception.

5.67.1.11. Iter.scan(Init $combine)

`scan` returns an iter of accumulated vals, seeded by `Init`.

If `Iter` has finite n elements E(1), E(2), ,,, E(n), the result iter has finite n+1 elements R(0), R(1), R(2), ,,, R(n).

If `Iter` has infinite elements E(1), E(2), ,,, , the result iter has infinite elements R(0), R(1), R(2), ,,, .

In both cases, R(i) is given as below:

For i=0, R(0) = Init.

For i>=1, R(i) = combine(R(i - 1) E(i)).

5.67.1.12. Iter.scan_inside($combine)

`scan_inside` returns an iter of vals accumulated inside `Iter`.

If `Iter` is empty, the result iter is empty.

If `Iter` has finite n (n >= 1) elements E(1), E(2), ,,, E(n), the result iter has finite n elements R(1), R(2), ,,, R(n).

If the Iter has infinite elements E(1), E(2), ,,, , the result iter has infinite elements R(1), R(2), ,,, .

In the latter two cases, R(i) is given as below:

For i=1, R(1) = E(1).

For i>=2, R(i) = combine(R(i - 1) E(i))

5.67.1.13. Iter.take_front(N)

`take_front` returns an iter containing the first N elements of `Iter`, or all the elements if `Iter` has less than `N` elements.

5.67.1.14. Iter.drop_front(N)

`drop_front` returns an iter omitting the first `N` elements of `Iter`, or an empty iter if `Iter` has less than `N` elements.

5.67.1.15. Iter.take_while($include?)

`take_while` returns an iter of the longest initial prefix of `Iter`, whose elements all satisfy $include?.

5.67.1.16. Iter.drop_while($exclude?)

`drop_while` returns an iter after the longest initial prefix of `Iter` whose elements all satisfy $exclude?.

5.67.1.17. Iter.all?($ok?)

`all?` returns true if all the elements of `Iter` satisfy $ok?. `all?` returns false if at least one element of `Iter` does not satisfy $ok?.

If `Iter` is infinite, this method is not guaranteed to return.

5.67.1.18. Iter.any?($ok?)

`any?` returns true if at least one element of `Iter` satisfies $ok?. `any?` returns false if all the elements of `Iter` does not satisfy $ok?.

If `Iter` is infinite, this method is not guaranteed to return.

5.67.1.19. Iter.fetcher_thunk

`fetcher_thunk` makes a stateful thunk to fetch each element of `Iter`.

When the result thunk is called, it returns a list containing the current element and go to next, when there are remaining elements. Otherwise, it returns an empty list.

For example:

:Iter <- ['foo' 'bar' 'baz']
:fetch <- Iter.fetcher_thunk
print_line(fetch.repr)  # => ["foo"]
print_line(fetch.repr)  # => ["bar"]
print_line(fetch.repr)  # => ["baz"]
print_line(fetch.repr)  # => []
print_line(fetch.repr)  # => []

5.67.1.20. Front + Back

`+` operator, or `op_add` method, concatenates two iters `Front` and `Back` into a single iter in the order from `Front` to `Back`.

Example:

:Iter <- 1.up.take_front(3) + 11.up.take_front(3)
Iter.each{(:N)
  stdout.print_line(N.repr)
}
# => 1 2 3 11 12 13

5.67.2. ITER.new($ifun)

`new` makes an iter backed by the $ifun.

5.67.3. ITER.is?(Val)

`is?` returns whether `Val` is an iter.

5.67.4. ITER.of(...Elems)

`of` returns an iter containing `Elems`.

5.67.5. ITER.zip(First_iter ...Other_iters)

Zips the elements of the given iters.

For example, an iter X has elements X1, X2, X3, ,,, , an iter Y has elements Y1, Y2, Y3, ,,, , and an iter Z has elements Z1, Z2, Z3, ,,, , zip(X Y Z) returns an iter containing [X1 Y1 Z1], [X2 Y2 Z2], [X3 Y3 Z3], ,,, .

The size of the result iter is the minimum of the size of the given iters.

5.67.6. ITER.cycle($make_iter)

`cycle` returns an iter which repeatedly concatenates elements of iters created by the $make_iter thunk.

If the $make_iter makes an empty iter, the result iter is terminated there.

5.67.7. ITER.lazy($make_iter)

`lazy` returns an iter whose elements are same as the iter created by the $make_iter.

5.67.8. ITER.from_generator($body)

`from_generator` makes an iter of elements yielded in $body.

$body must take an unary fun $yield as the arg, When $yield is called with a val in invocation of $body, those vals will be the elements of the result iter.

For example:

:ITER.require_from('kink/iter/')
:Iter <- ITER.from_generator{(:yield)
  yield('foo')
  yield('bar')
  yield('baz')
}
Iter.each{(:Str)
  stdout.print_line(Str)
}
# Output:
#   foo
#   bar
#   baz

A generator is stackfull. You can call $yield from another fun.

:ITER.require_from('kink/iter/')
:Iter <- ITER.from_generator{(:yield)
  yield('foo')
  bar($yield)
  yield('baz')
}
:bar <- {(:yield)
  yield('bar')
}
Iter.each{(:Str)
  stdout.print_line(Str)
}
# Output:
#   foo
#   bar
#   baz

5.67.9. ITER.from_each(Eacher)

`from_each` makes an iter of elements which is enumerated in Eacher.each.