Array

Functions on Arrays

equal

func equal<A>(a : [A], b : [A], eq : (A, A) -> Bool) : Bool

Test if two arrays contain equal values

append

func append<A>(xs : [A], ys : [A]) : [A]

Append the values of two input arrays

sort

func sort<A>(xs : [A], cmp : (A, A) -> Order.Order) : [A]

Sorts the given array according to the cmp function. This is a stable sort.

import Array "mo:base/Array";
import Nat "mo:base/Nat";
let xs = [4, 2, 6, 1, 5];
assert(Array.sort(xs, Nat.compare) == [1, 2, 4, 5, 6])

sortInPlace

func sortInPlace<A>(xs : [var A], cmp : (A, A) -> Order.Order)

Sorts the given array in place according to the cmp function. This is a stable sort.

import Array "mo:base/Array";
import Nat "mo:base/Nat";
let xs : [var Nat] = [4, 2, 6, 1, 5];
xs.sort(Nat.compare);
assert(Array.freeze(xs) == [1, 2, 4, 5, 6])

chain

func chain<A, B>(xs : [A], f : A -> [B]) : [B]

Transform each array value into zero or more output values, appended in order

filter

func filter<A>(xs : [A], f : A -> Bool) : [A]

Output array contains each array-value if and only if the predicate is true; ordering retained.

mapFilter

func mapFilter<A, B>(xs : [A], f : A -> ?B) : [B]

Output array contains each transformed optional value; ordering retained.

foldLeft

func foldLeft<A, B>(xs : [A], initial : B, f : (B, A) -> B) : B

Aggregate and transform values into a single output value, by increasing indices.

foldRight

func foldRight<A, B>(xs : [A], initial : B, f : (A, B) -> B) : B

Aggregate and transform values into a single output value, by decreasing indices.

find

func find<A>(xs : [A], f : A -> Bool) : ?A

Returns optional first value for which predicate is true

freeze

func freeze<A>(xs : [var A]) : [A]

Transform mutable array into immutable array

flatten

func flatten<A>(xs : [[A]]) : [A]

Transform an array of arrays into a single array, with retained array-value order.

map

func map<A, B>(xs : [A], f : A -> B) : [B]

Transform each value using a function, with retained array-value order.

mapEntries

func mapEntries<A, B>(xs : [A], f : (A, Nat) -> B) : [B]

Transform each entry (index-value pair) using a function.

mapResult

func mapResult<A, R, E>(xs : [A], f : A -> Result.Result<R, E>) : Result.Result<[R], E>

Maps a Result-returning function over an Array and returns either the first error or an array of successful values.

import Array "mo:base/Array";
import Result "mo:base/Result";
import Int "mo:base/Int";
func makeNatural(x : Int) : Result.Result<Nat, Text> =
  if (x >= 0) {
    #ok(Int.abs(x))
  } else {
    #err(Int.toText(x) # " is not a natural number.")
  };

assert(Array.mapResult<Int, Nat, Text>([0, 1, 2], makeNatural) == #ok([0, 1, 2]));
assert(Array.mapResult([-1, 0, 1], makeNatural) == #err("-1 is not a natural number."));

make

func make<A>(x : A) : [A]

Make an array from a single value.

vals

func vals<A>(xs : [A]) : I.Iter<A>

Returns xs.vals().

keys

func keys<A>(xs : [A]) : I.Iter<Nat>

Returns xs.keys().

thaw

func thaw<A>(xs : [A]) : [var A]

Transform an immutable array into a mutable array.

init

func init<A>(size : Nat, initVal : A) : [var A]

Initialize a mutable array with size copies of the initial value.

tabulate

func tabulate<A>(size : Nat, gen : Nat -> A) : [A]

Initialize an immutable array of the given size, and use the gen function to produce the initial value for every index.

tabulateVar

func tabulateVar<A>(size : Nat, gen : Nat -> A) : [var A]

Initialize a mutable array using a generation function