3.58. kink/iter/ITER

Provides operations for iters or iterators.

3.58.1. type iter

Unidirectional iterator.

An iter is backed by an ifun.

Iter.ifun

Returns the ifun backing the Iter.

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.

Iter.concat

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

The Iter must be an iter of iters.

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.

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), ,,, .

Iter.concat_map($transform_to_iter)

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

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.

Iter.count($counted?)

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

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.

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 [].

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

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

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.

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.

Iter.take_while($include?)

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

Iter.drop_while($exclude?)

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

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.

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.

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)  # => []

3.58.2. ITER.new($ifun)

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

3.58.3. ITER.is?(Val)

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

3.58.4. ITER.of(...Elems)

Returns an iter containing the Elems.

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

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

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

3.58.8. ITER.lazy($make_iter)

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

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

3.58.10. ITER.from_each(Eacher)

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