# 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 @deprecated Array.append has critical performance flaws; use a Buffer, and Buffer.append, instead.

## 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];assert(Array.sort(xs, Nat.compare) == [2, 4, 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] = [var 4, 2, 6, 1, 5];Array.sortInPlace(xs, 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