4.63. kink/iter/ITER

Provides operations for iters or iterators.

4.63.1. type iter

Unidirectional iterator.

An iter is backed by an ifun.

4.63.1.1. Iter.ifun

Returns the ifun backing the Iter.

4.63.1.2. Iter.each($on_elem)

Calls $on_elem for each elements of the Iter, then return the last result of $on_elem.

If $ifun has no elements, it returns nada.

4.63.1.3. Iter.concat

Returns an iter, which concatenates the elements of iters in the Iter.

The Iter must be an iter of iters.

4.63.1.4. Iter.chunk(Chunk_size)

Returns an iter of chunks with the Chunk_size.

For example, if the 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.

4.63.1.5. Iter.map($transform)

Returns an iter whose elements are transformed from the Iter by $transform.

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

4.63.1.6. Iter.concat_map($transform_to_iter)

Equivalent to call Iter.map($transform_to_iter).concat.

4.63.1.7. Iter.filter($include?)

Filters elements of $ifun by the predicate $include?.

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

4.63.1.8. Iter.count($counted?)

Returns the number of elements of the Iter which satisfy $counted?.

4.63.1.9. Iter.fold(Init $combine)

Accumulates elements of the Iter seeded by Init.

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

If the Iter is empty, this fun returns Init.

4.63.1.10. Iter.reduce($combine)

Accumulates elements of the Iter mutually, then returns a maybe tuple.

If the Iter has elements E1, E2, E3, ,,, En_1, En, this method returns [combine(combine(,,,combine(combine(E1 E2) E3),,, En_1) En)].

If the Iter has a single element E, this method returns [E].

If the Iter is empty, this method returns [].

4.63.1.11. Iter.scan(Init $combine)

Returns an iter of accumulated vals, seeded by Init.

If the 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 the 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)).

4.63.1.12. Iter.scan_inside($combine)

Returns an iter of vals accumulated inside the Iter.

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

If the 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))

4.63.1.13. Iter.take_front(N)

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

4.63.1.14. Iter.drop_front(N)

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

4.63.1.15. Iter.take_while($include?)

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

4.63.1.16. Iter.drop_while($exclude?)

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

4.63.1.17. Iter.all?($ok?)

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

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

4.63.1.18. Iter.any?($ok?)

Returns true if at least one element of the Iter satisfies $ok?. Returns fall if all the elements of the Iter does not satisfy $ok?.

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

4.63.1.19. Iter.fetcher_thunk

Makes a stateful thunk to fetch each element of the 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)  # => []

4.63.2. ITER.new($ifun)

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

4.63.3. ITER.is?(Val)

ITER.is? returns whether the Val is an iter.

4.63.4. ITER.of(...Elems)

Returns an iter containing the Elems.

4.63.5. ITER.chain(...Iters)

`chain` makes an iter concatenates the elements of each iter of `Iters`.

Precondition:

• Each element of `Iters` must be an iter.

Example:

:ITER.require_from('kink/iter/')

:Chained <- ITER.chain(ITER.of(1 2 3) ITER.of(4 5 6) ITER.of(7 8 9))
Chained.each{(:N)
  stdout.print_line(N.repr)
} # => 1 2 3 4 5 6 7 8 9

4.63.6. 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.

4.63.7. ITER.cycle($make_iter)

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.

4.63.8. ITER.lazy($make_iter)

Returns an iter whose elements are same as the iter created by the $make_iter.

4.63.9. 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

4.63.10. ITER.from_each(Eacher)

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