Import std.core.iterator

std.core.iterator

Iterators, and the Iterable Interface, which For loops go over besides arrays.

Each Next gives the next element, or Null when there are no more. The loop goes over a copy of a Struct, since its Next changes it.

Its adapters are lazy: each gives an Iterator of its own, which asks the one before it for a value only when it's asked for one. Its consumers go over the values once. They're all Final, so they're what every Iterator has, through its value too. Called on a Struct, they go over a copy of it, and a Class's object is used up, as a For loop over it is. A @PanicsAtCaller Next panics where a consumer is called, and through an adapter or a box, where its panic is, as through any Iterator<T> value.

Examples

// Anything with an Iterate() is Iterable, which a For loop goes over.
Struct Countdown Implements Iterable<Int>
    Field From: Int

    Public Method Iterate(): Range<Int> => From To 1 Step -1
End Struct

Local seen: Int[] = []
For n In Countdown(3)
    seen.Add(n)
End For

Expect(seen == [3, 2, 1])
Expect(Empty<Int>().Count() == 0)

std/core/iterator.fb

Types

`Iterator` interface

Public Interface Iterator<T>

What a For loop goes over: each Next gives the next value, and its adapters and consumers work on the values that are left.

Examples

Struct Countdown Implements Iterator<Int>
    Field At: Int

    Public ByRef Method Next(): Int?
        If At == 0 Then Return Null
        At -= 1
        Return At + 1
    End Method
End Struct

Local seen: Int[] = []
For n In Countdown(3)
    seen.Add(n)
End For

Expect(seen == [3, 2, 1])
Expect(Countdown(5).Filter(Function(n: Int) => n % 2 == 1).ToArray() == [5, 3, 1])

std/core/iterator.fb, line 59

ByRef Method Next(): T? method #

The next value, or Null when there are no more.
Final Method Map(change: Func(T): U): Iterator method #

What change gives for each value.
Final Method Filter(keep: Func(T): Bool): Iterator<T> method #

The values keep says to keep.
@PanicsAtCaller Final Method Take(count: Int): Iterator<T> method #
The first count values, or all of them when there are fewer.

Examples
```
Expect([1, 2, 3, 4].Iterate().Skip(1).Take(2).ToArray() == [2, 3])
```
@PanicsAtCaller Final Method Skip(count: Int): Iterator<T> method #

The values after the first count.
Final Method TakeWhile(keep: Func(T): Bool): Iterator<T> method #

The values before the first that keep says not to keep.
Final Method SkipWhile(skip: Func(T): Bool): Iterator<T> method #

The values from the first that skip says not to skip.
Final Method Enumerate(): Iterator<(Int, T)> method #
Each value with how many came before it.

Examples
```
Expect(["a", "b"].Iterate().Enumerate().ToArray() == [(0, "a"), (1, "b")])
```
Final Method Zip<O, U>(other: O): Iterator<(T, U)> method #
Each value with other's at the same place, as far as the shorter goes.

Examples
```
Expect([1, 2, 3].Iterate().Zip(["a", "b"].Iterate()).ToArray() == [(1, "a"), (2, "b")])
```
Final Method Chain<O>(other: O): Iterator<T> method #

These values, then other's.
Final Method Flatten(): Iterator method #

The values of each value, which is an Iterable, one after another.
@PanicsAtCaller Final Method StepBy(step: Int): Iterator<T> method #

The first value, then each step-th one after it.
@PanicsAtCaller Final Method Chunks(size: Int): Iterator<T[]> method #
The values in arrays of size, the last one shorter when they don't divide evenly.

Examples
```
Expect([1, 2, 3, 4, 5].Iterate().Chunks(2).ToArray() == [[1, 2], [3, 4], [5]])
```
@PanicsAtCaller Final Method Windows(size: Int): Iterator<T[]> method #
Each run of size values in a row, in an array of its own: none when there are fewer.

Examples
```
Expect([1, 2, 3, 4].Iterate().Windows(3).ToArray() == [[1, 2, 3], [2, 3, 4]])
```
Final Method OrderBy<K: Comparable>(key: Func(T): K): Iterator<T> method #
The values, smallest key first, where equal keys keep their order. It goes over them all when it's first asked for one.

Examples
```
Local words = ["pear", "fig", "apple"].Iterate()
Local shortest = words.OrderBy(Function(word: String) => word.Length)
Expect(shortest.ToArray() == ["fig", "pear", "apple"])
```
Final Method OrderByDescending<K: Comparable>(key: Func(T): K): Iterator<T> method #

The values, largest key first, where equal keys keep their order.
@PanicsAtCaller Final Method ToArray(): T[] method #

The values, in a new array.
@PanicsAtCaller Final Method Count(): Int method #

How many values there are.
@PanicsAtCaller Final Method Any(test: Func(T): Bool): Bool method #

Whether test says yes for any value, going no further than the first.
@PanicsAtCaller Final Method All(test: Func(T): Bool): Bool method #

Whether test says yes for every value, going no further than the first it doesn't.
@PanicsAtCaller Final Method Find(test: Func(T): Bool): T? method #

The first value test says yes for, or Null.
@PanicsAtCaller Final Method First(): T? method #

The first value, or Null when there's none.
@PanicsAtCaller Final Method Last(): T? method #

The last value, or Null when there's none.
@PanicsAtCaller Final Method Fold<A>(start: A, combine: Func(A, T): A): A method #

What combine makes of start and each value in turn.
@PanicsAtCaller Final Method Reduce(combine: Func(T, T): T): T? method #

What combine makes of the values, the first two, then that and the next, and so on: the first alone when there's one, and Null when there's none.
@PanicsAtCaller Final Method ForEach(action: Func(T)) method #

Runs action for each value.
@PanicsAtCaller Final Method Sum(): T method #
The values added up, or zero when there are none.

Examples
```
Expect([1, 2, 3].Iterate().Sum() == 6)
Expect([2, 3, 4].Iterate().Product() == 24)
```
@PanicsAtCaller Final Method Product(): T method #

The values multiplied together, or one when there are none.
@PanicsAtCaller Final Method Min(): T? method #

The smallest value, the first of equal ones, or Null when there's none.
@PanicsAtCaller Final Method Max(): T? method #

The largest value, the first of equal ones, or Null when there's none.
@PanicsAtCaller Final Method MinBy<K: Comparable>(key: Func(T): K): T? method #

The value whose key is smallest, the first of equal ones, or Null when there's none.
@PanicsAtCaller Final Method MaxBy<K: Comparable>(key: Func(T): K): T? method #
The value whose key is largest, the first of equal ones, or Null when there's none.

Examples
```
Local words = ["pear", "fig", "apple"].Iterate()
Expect(words.MaxBy(Function(word: String) => word.Length) == "apple")
```

`Iterable` interface

Public Interface Iterable<T>

What a For loop goes over through its Iterate(), for code that takes any collection. A collection's Iterate() gives a Struct of its own, which an Iterable<T>'s value or generic code gets in a box, an Iterator<T> object.

std/core/iterator.fb, line 410

Method Iterate(): Iterator<T> method #

Its values, from the first, in an Iterator of their own.

Functions

`Repeated` function

@PanicsAtCaller Public Function Repeated<T>(value: T, count: Int): Iterator<T>

value, count times.

Examples

Expect(Repeated("ab", 3).ToArray() == ["ab", "ab", "ab"])

std/core/iterator.fb, line 422

`Empty` function

Public Function Empty<T>(): Iterator<T>

No values.

std/core/iterator.fb, line 429

Report an issue with this page or with FutureBlitz on GitHub.

std.core.iterator

Examples

Types

Iterator interface

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Iterable interface

Functions

Repeated function

Examples

Empty function

`Iterator` interface

`Iterable` interface

`Repeated` function

`Empty` function