iterator

all

|Iterable, |Value| -> Bool| -> Bool

Checks the Iterable's values against a test Function.

The provided function should return true or false, and then all will return true if all values pass the test.

all stops running as soon as it finds a failing test, and then false is returned.

Example

(1..9).all |x| x > 0
# -> true

('', '', 'foo').all string.is_empty
# -> false

[10, 20, 30]
  .each |x| x / 10
  .all |x| x < 10
# -> true

any

|Iterable, |Value| -> Bool| -> Bool

Checks the Iterable's values against a test Function.

The provided function should return true or false, and then any will return true if any of the values pass the test.

any stops running as soon as it finds a passing test.

Example

(1..9).any |x| x == 5
# -> true

('', '', 'foo').any string.is_empty
# -> true

[10, 20, 30]
  .each |x| x / 10
  .any |x| x == 2
# -> true

chain

|Iterable, Iterable| -> Iterator

chain returns an iterator that iterates over the output of the first iterator, followed by the output of the second iterator.

Example

[1, 2]
  .chain 'abc'
  .to_tuple()
# -> (1, 2, 'a', 'b', 'c')

chunks

|Iterable, Number| -> Iterator

Returns an iterator that splits up the input data into chunks of size N, where each chunk is provided as a Tuple. The final chunk may have fewer than N elements.

Example

1..=10
  .chunks 3
  .to_list()
# -> [(1, 2, 3), (4, 5, 6), (7, 8, 9), (10)]

consume

|Iterable| -> Null

Consumes the output of the iterator.

|Iterable, Function| -> Null

Consumes the output of the iterator, calling the provided function with each iterator output value.

Example

result = []
1..=10
  .keep |n| n % 2 == 0
  .each |n| result.push n
  .consume()
result
# -> [2, 4, 6, 8, 10]

# Alternatively, calling consume with a function is equivalent to having an
# `each` / `consume` chain
result = []
1..=10
  .keep |n| n % 2 == 1
  .consume |n| result.push n
result
# -> [1, 3, 5, 7, 9]

count

|Iterable| -> Number

Counts the number of items yielded from the iterator.

Example

(5..15).count()
# -> 10

0..100
  .keep |x| x % 2 == 0
  .count()
# -> 50

cycle

|Iterable| -> Iterator

Takes an Iterable and returns a new iterator that endlessly repeats the iterable's output.

The iterable's output gets cached, which may result in a large amount of memory being used if the cycle has a long length.

Example

(1, 2, 3)
  .cycle()
  .take 10
  .to_list()
# -> [1, 2, 3, 1, 2, 3, 1, 2, 3, 1]

each

|Iterable, |Value| -> Value| -> Iterator

Takes an Iterable and a Function, and returns a new iterator that provides the result of calling the function with each value in the iterable.

Example

(2, 3, 4)
  .each |x| x * 2
  .to_list()
# -> [4, 6, 8]

enumerate

|Iterable| -> Iterator

Returns an iterator that provides each value along with an associated index.

Example

('a', 'b', 'c').enumerate().to_list()
# -> [(0, 'a'), (1, 'b'), (2, 'c')]

find

|Iterable, |Value| -> Bool| -> Value

Returns the first value in the iterable that passes the test function.

The function is called for each value in the iterator, and returns either true if the value is a match, or false if it's not.

The first matching value will cause iteration to stop.

If no match is found then Null is returned.

Example

(10..20).find |x| x > 14 and x < 16
# -> 15

(10..20).find |x| x > 100
# -> null

flatten

|Iterable| -> Value

Returns the output of the input iterator, with any nested iterable values flattened out.

Note that only one level of flattening is performed, so any double-nested containers will still be present in the output.

Example

[(2, 4), [6, 8, (10, 12)]]
  .flatten()
  .to_list()
# -> [2, 4, 6, 8, (10, 12)]

See Also

fold

|Iterable, Value, |Value, Value| -> Value| -> Value

Returns the result of 'folding' the iterator's values into an accumulator function.

The function takes the accumulated value and the next iterator value, and then returns the result of folding the value into the accumulator.

The first argument is an initial accumulated value that gets passed to the function along with the first value from the iterator.

The result is then the final accumulated value.

This operation is also known in other languages as reduce, accumulate, inject, fold left, along with other names.

Example

('a', 'b', 'c')
  .fold [], |result, x| 
    result.push x
    result.push '-'
# -> ['a', '-', 'b', '-', 'c', '-']

See Also

generate

|Function| -> Iterator

Provides an iterator that yields the result of repeatedly calling the provided function. Note that this version of generate won't terminate and will iterate endlessly.

|Number, Function| -> Value

Provides an iterator that yields the result of repeatedly calling the provided function n times.

Example

from iterator import generate

state = {x: 0}
f = || state.x += 1

generate(f)
  .take(5)
  .to_list()
# -> [1, 2, 3, 4, 5]

generate(3, f).to_tuple()
# -> (6, 7, 8)

See Also

intersperse

|Iterable, Value| -> Iterator

Returns an iterator that yields a copy of the provided value between each adjacent pair of output values.

|Iterable, || -> Value| -> Iterator

Returns an iterator that yields the result of calling the provided function between each adjacent pair of output values.

Example

('a', 'b', 'c').intersperse('-').to_string()
# -> a-b-c

separators = (1, 2, 3).iter()
('a', 'b', 'c')
  .intersperse || separators.next().get()
  .to_tuple(),
# -> ('a', 1, 'b', 2, 'c')

iter

|Iterable| -> Iterator

Returns an iterator that yields the provided iterable's values.

Iterable values will be automatically accepted by most iterator operations, so it's usually not necessary to call .iter(), however it can be usefult sometimes to make a standalone iterator for manual iteration.

Note that calling .iter with an Iterator will return the iterator without modification. If a copy of the iterator is needed then see koto.copy and koto.deep_copy.

Example

i = (1..10).iter()
i.skip 5
i.next().get()
# -> 6

See Also

keep

|Iterable, |Value| -> Bool| -> Iterator

Returns an iterator that keeps only the values that pass a test function.

The function is called for each value in the iterator, and returns either true if the value should be kept in the iterator output, or false if it should be discarded.

Example

0..10
  .keep |x| x % 2 == 0
  .to_tuple()
# -> (0, 2, 4, 6, 8)

last

|Iterable| -> Value

Consumes the iterator, returning the last yielded value.

Example

(1..100).take(5).last()
# -> 5

(0..0).last()
# -> null

max

|Iterable| -> Value

Returns the maximum value found in the iterable.

|Iterable, |Value| -> Value| -> Value

Returns the maximum value found in the iterable, based on first calling a 'key' function with the value, and then using the resulting keys for the comparisons.

A < 'less than' comparison is performed between each value and the maximum found so far, until all values in the iterator have been compared.

Example

(8, -3, 99, -1).max()
# -> 99

See Also

min

|Iterable| -> Value

Returns the minimum value found in the iterable.

|Iterable, |Value| -> Value| -> Value

Returns the minimum value found in the iterable, based on first calling a 'key' function with the value, and then using the resulting keys for the comparisons.

A < 'less than' comparison is performed between each value and the minimum found so far, until all values in the iterator have been compared.

Example

(8, -3, 99, -1).min()
# -> -3

See Also

min_max

|Iterable| -> (Value, Value)

Returns the minimum and maximum values found in the iterable.

|Iterable, |Value| -> Value| -> Value

Returns the minimum and maximum values found in the iterable, based on first calling a 'key' function with the value, and then using the resulting keys for the comparisons.

A < 'less than' comparison is performed between each value and both the minimum and maximum found so far, until all values in the iterator have been compared.

Example

(8, -3, 99, -1).min_max()
# -> (-3, 99)

See Also

next

|Iterable| -> IteratorOutput

Returns the next value from the iterator wrapped in an IteratorOutput, or null if the iterator has been exhausted.

Example

x = (1, null, 'x').iter()
x.next()
# -> IteratorOutput(1)
x.next()
# -> IteratorOutput(null)
x.next()
# -> IteratorOutput(x)
x.next()
# -> null

# Call .get() to access the value from an IteratorOutput
'abc'.next().get()
# -> a

See Also

next_back

|Iterable| -> IteratorOutput

Returns the next value from the end of the iterator wrapped in an IteratorOutput, or null if the iterator has been exhausted.

This only works with iterators that have a defined end, so attempting to call next_back on endless iterators like iterator.generate will result in an error.

Example

x = (1..=5).iter()
x.next_back()
# -> IteratorOutput(5)
x.next_back()
# -> IteratorOutput(4)

# calls to next and next_back can be mixed together
x.next()
# -> IteratorOutput(1)
x.next_back()
# -> IteratorOutput(3)
x.next_back()
# -> IteratorOutput(2)

# 1 has already been produced by the iterator, so it's now exhausted
x.next_back()
# -> null

See Also

once

|Value| -> Iterator

Returns an iterator that yields the given value a single time.

Example

iterator.once(99)
  .chain('abc')
  .to_tuple()
# -> (99, 'a', 'b', 'c')

See Also

peekable

|Iterable| -> Peekable

Wraps the given iterable value in a peekable iterator.

Peekable.peek

Returns the next value from the iterator without advancing it. The peeked value is cached until the iterator is advanced.

Example

x = 'abc'.peekable()
x.peek()
# -> IteratorOutput(a)
x.peek()
# -> IteratorOutput(a)
x.next()
# -> IteratorOutput(a)
x.peek()
# -> IteratorOutput(b)
x.next(), x.next()
# -> (IteratorOutput(b), IteratorOutput(c))
x.peek()
# -> null

See Also

Peekable.peek_back

Returns the next value from the end of the iterator without advancing it. The peeked value is cached until the iterator is advanced.

Example

x = 'abc'.peekable()
x.peek_back()
# -> IteratorOutput(c)
x.next_back()
# -> IteratorOutput(c)
x.peek()
# -> IteratorOutput(a)
x.peek_back()
# -> IteratorOutput(b)
x.next_back(), x.next_back()
# -> (IteratorOutput(b), IteratorOutput(a))
x.peek_back()
# -> null

See Also

position

|Iterable, |Value| -> Bool| -> Value

Returns the position of the first value in the iterable that passes the test function.

The function is called for each value in the iterator, and returns either true if the value is a match, or false if it's not.

The first matching value will cause iteration to stop, and the number of steps taken to reach the matched value is returned as the result.

If no match is found then Null is returned.

Example

(10..20).position |x| x == 15
# -> 5

(10..20).position |x| x == 99
# -> null

See Also

product

|Iterable| -> Value

Returns the result of multiplying each value in the iterable together.

Example

(2, 3, 4).product()
# -> 24

See also

repeat

|Value| -> Iterator
|Value, Number| -> Iterator

Provides an iterator that repeats the provided value. A number of repeats can be optionally provided as the second argument.

Example

iterator.repeat(42)
  .take(5)
  .to_list()
# -> [42, 42, 42, 42, 42]

iterator.repeat('x', 3).to_tuple()
# -> ('x', 'x', 'x')

See Also

reversed

|Iterator| -> Iterator

Reverses the order of the iterator's output.

This only works with iterators that have a defined end, so attempting to reverse endless iterators like iterator.generate will result in an error.

Example

'Héllö'.reversed().to_tuple()
# -> ('ö', 'l', 'l', 'é', 'H')

(1..=10).reversed().skip(5).to_tuple()
# -> (5, 4, 3, 2, 1)

skip

|Iterable, Number| -> Iterator

Skips over a number of steps in the iterator.

Example

(100..200).skip(50).next().get()
# -> 150

See also

step

|Iterable, Number| -> Iterator

Steps over the iterable's output by the provided step size.

Example

(0..10).step(3).to_tuple()
# -> (0, 3, 6, 9)

'Héllö'.step(2).to_string()
# -> Hlö

See also

sum

|Iterable| -> Value

Returns the result of adding each value in the iterable together.

Example

(2, 3, 4).sum()
# -> 9

See also

take

|Iterable, Number| -> Iterator

Provides an iterator that yields a number of values from the input before finishing.

|Iterable, Callable| -> Iterator

Provides an iterator that yields values from the input while they pass a predicate function.

Example

(100..200).take(3).to_tuple()
# -> (100, 101, 102)

'hey!'.take(|c| c != '!').to_string()
# -> hey

See also

to_list

|Iterable| -> List

Consumes all values coming from the iterator and places them in a list.

Example

('a', 42, (-1, -2)).to_list()
# -> ['a', 42, (-1, -2)]

See also

to_map

|Iterable| -> Map

Consumes all values coming from the iterator and places them in a map.

If a value is a tuple, then the first element in the tuple will be inserted as the key for the map entry, and the second element will be inserted as the value.

If the value is anything other than a tuple, then it will be inserted as the map key, with Null as the entry's value.

Example

('a', 'b', 'c').to_map()
# -> {a: null, b: null, c: null}

('a', 'bbb', 'cc')
  .each |x| x, size x
  .to_map()
# -> {a: 1, bbb: 3, cc: 2}

See also

to_string

|Iterable| -> String

Consumes all values coming from the iterator and produces a string containing the formatted values.

Example

('x', 'y', 'z').to_string()
# -> xyz

(1, 2, 3).intersperse('-').to_string()
# -> 1-2-3

See also

to_tuple

|Iterable| -> Tuple

Consumes all values coming from the iterator and places them in a tuple.

Example

['a', 42, (-1, -2)].to_tuple()
# -> ('a', 42, (-1, -2))

See also

windows

|Iterable, Number| -> Iterator

Returns an iterator that splits up the input data into overlapping windows of size N, where each window is provided as a Tuple.

If the input has fewer than N elements then no windows will be produced.

Example

1..=5
  .windows 3
  .to_list(),
# -> [(1, 2, 3), (2, 3, 4), (3, 4, 5)]

zip

|Iterable, Iterable| -> Iterator

Combines the values in two iterables into an iterator that provides corresponding pairs of values, one at a time from each input iterable.

Example

(1, 2, 3)
  .zip ('a', 'b', 'c')
  .to_list()
# -> [(1, 'a'), (2, 'b'), (3, 'c')]

IteratorOutput

A wrapper for a single item of iterator output.

This exists to allow functions like iterator.next to return null to indicate that the iterator has been exhausted, while also allowing null to appear in the iterator's output.

IteratorOutput.get

|IteratorOutput| -> Value

Returns the wrapped iterator output value.

Example

x = 'abc'.next()
# -> IteratorOutput(a)
x.get()
# -> a