# 3.49. kink/iter/ITER¶

Provides operations for iters or iterators.

- ITER.iter?(Val)
- ITER.of_ifun($ifun)
- type iter
- Iter.ifun
- Iter.each($on_elem)
- Iter.each_or($on_elem $on_empty)
- Iter.concat
- Iter.chunk(Chunk_size)
- Iter.map($transform)
- Iter.concat_map($transform_to_iter)
- Iter.filter($include?)
- Iter.count($counted?)
- Iter.fold(Init $combine)
- Iter.reduce($combine)
- Iter.scan(Init $combine)
- Iter.scan_inside($combine)
- Iter.take_front(N)
- Iter.drop_front(N)
- Iter.take_while($include?)
- Iter.drop_while($exclude?)
- Iter.for_all?($ok?)
- Iter.for_any?($ok?)
- Iter.fetcher_thunk

- ITER.of(...Elems)
- ITER.chain(Xiter Yiter)
- ITER.zip(First_iter ...Other_iters)
- ITER.cycle($make_iter)
- ITER.lazy($make_iter)
- ITER.with_yield($body)
- ITER.of_each(Eacher)

## 3.49.1. ITER.iter?(Val)¶

Returns true if the Val is an iter, or false otherwise.

## 3.49.2. ITER.of_ifun($ifun)¶

Makes an iter backed by the $ifun.

## 3.49.3. 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.each_or($on_elem $on_empty)¶

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

If the Iter has no elements, it tail-calls $on_empty thunk.

### 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.for_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.for_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.49.4. ITER.of(...Elems)¶

Returns an iter containing the Elems.

## 3.49.5. ITER.chain(Xiter Yiter)¶

Chains the two iters.

If the Xiter has finite n elements X1, X2, ,,, Xn, and the Yiter has elements Y1, Y2, ,,, , the result iter has X1, X2, ,,, Xn, Y1, Y2, ,,, .

If the Xiter is infinite, the result iter has the same elements as ones of the Xiter.

## 3.49.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.49.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.49.8. ITER.lazy($make_iter)¶

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

## 3.49.9. ITER.with_yield($body)¶

Makes an iter of elements yielded in $body.

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

For example:

```
:ITER.require_from('kink/iter/')
:Iter = ITER.with_yield{(:yield)
yield('foo')
yield('bar')
yield('baz')
}
Iter.each{(:Str)
stdout.print_line(Str)
}
# Output:
# foo
# bar
# baz
```

This fun provides functionality equivalent to Python's generators.

## 3.49.10. ITER.of_each(Eacher)¶

Makes an iter of elements which is enumerated in Eacher.each.