Iterators
An iterator that produces values of type T
. Calling next
returns
null
when iteration is finished.
Iterators are inherently stateful. Calling next
"consumes" a value from
the Iterator that cannot be put back, so keep that in mind when sharing
iterators between consumers.
An iterater i
can be iterated over using
for (x in i) {
…do something with x…
}
public func next() : ?Nat
Creates an iterator that produces all Nat
s from x
to y
including
both of the bounds.
import Iter "mo:base/Iter";
let iter = Iter.range(1, 3);
assert(?1 == iter.next());
assert(?2 == iter.next());
assert(?3 == iter.next());
assert(null == iter.next());
public func next() : ?Int
Like range
but produces the values in the opposite
order.
public func iterate<A>(xs : Iter<A>, f : (A, Nat) -> ())
Calls a function f
on every value produced by an iterator and discards
the results. If you're looking to keep these results use map
instead.
import Iter "mo:base/Iter";
var sum = 0;
Iter.iterate<Nat>(Iter.range(1, 3), func(x, _index) {
sum += x;
});
assert(6 == sum)
public func size<A>(xs : Iter<A>) : Nat
Consumes an iterator and counts how many elements were produced (discarding them in the process).
public func map<A, B>(xs : Iter<A>, f : A -> B) : Iter<B>
Takes a function and an iterator and returns a new iterator that lazily applies the function to every element produced by the argument iterator.
import Iter "mo:base/Iter";
let iter = Iter.range(1, 3);
let mappedIter = Iter.map(iter, func (x : Nat) : Nat { x * 2 });
assert(?2 == mappedIter.next());
assert(?4 == mappedIter.next());
assert(?6 == mappedIter.next());
assert(null == mappedIter.next());
public func filter<A>(xs : Iter<A>, f : A -> Bool) : Iter<A>
Takes a function and an iterator and returns a new iterator that produces elements from the original iterator if and only if the predicate is true.
import Iter "mo:base/Iter";
let iter = Iter.range(1, 3);
let mappedIter = Iter.filter(iter, func (x : Nat) : Bool { x % 2 == 1 });
assert(?1 == mappedIter.next());
assert(?3 == mappedIter.next());
assert(null == mappedIter.next());
public func make<A>(x : A) : Iter<A>
Creates an iterator that produces an infinite sequence of x
.
import Iter "mo:base/Iter";
let iter = Iter.make(10);
assert(?10 == iter.next());
assert(?10 == iter.next());
assert(?10 == iter.next());
// ...
public func concat<A>(a : Iter<A>, b : Iter<A>) : Iter<A>
Takes two iterators and returns a new iterator that produces elements from the original iterators sequentally.
import Iter "mo:base/Iter";
let iter1 = Iter.range(1, 2);
let iter2 = Iter.range(5, 6);
let concatenatedIter = Iter.concat(iter1, iter2);
assert(?1 == concatenatedIter.next());
assert(?2 == concatenatedIter.next());
assert(?5 == concatenatedIter.next());
assert(?6 == concatenatedIter.next());
assert(null == concatenatedIter.next());
public func fromArray<A>(xs : [A]) : Iter<A>
Creates an iterator that produces the elements of an Array in ascending index order.
import Iter "mo:base/Iter";
let iter = Iter.fromArray([1, 2, 3]);
assert(?1 == iter.next());
assert(?2 == iter.next());
assert(?3 == iter.next());
assert(null == iter.next());
public func fromArrayMut<A>(xs : [var A]) : Iter<A>
Like fromArray
but for Arrays with mutable elements. Captures
the elements of the Array at the time the iterator is created, so
further modifications won't be reflected in the iterator.
public let fromList :
Like fromArray
but for Lists.
public func toArray<A>(xs : Iter<A>) : [A]
Consumes an iterator and collects its produced elements in an Array.
import Iter "mo:base/Iter";
let iter = Iter.range(1, 3);
assert([1, 2, 3] == Iter.toArray(iter));
public func toArrayMut<A>(xs : Iter<A>) : [var A]
Like toArray
but for Arrays with mutable elements.
public func sort<A>(xs : Iter<A>, compare : (A, A) -> Order.Order) : Iter<A>
Sorted iterator. Will iterate over all elements to sort them, necessarily.