List

The difference between a list and an array is that an array is stored as one contiguous block of bytes in memory and a list is 'scattered' around without the elements having to be adjacent to each other. The advantage is that we can use memory more efficiently by filling the memory more flexibly. The downside is that for operations on the whole list, we have to visit each element one by one which may be computationally expensive.

For more on the List data structures visit recursive types.

The convention is to name the module alias after the file name it is defined in:

import List "mo:base/List";

On this page

Function nil
Function isNil
Function push
Function last
Function pop
Function size
Function get
Function reverse
Function iterate
Function map
Function filter
Function partition
Function mapFilter
Function mapResult
Function append
Function flatten
Function take
Function drop
Function foldLeft
Function foldRight
Function find
Function some
Function all
Function merge
Function compare
Function equal
Function tabulate
Function make
Function replicate
Function zip
Function zipWith
Function split
Function chunks
Function fromArray
Function fromVarArray
Function toArray
Function toVarArray
Function toIter

List.nil

func nil<T>() : List<T>

Example

import List "mo:base/List";

List.nil<Int>();

List.isNil

func isNil<T>(l : List<T>) : Bool

Example

import List "mo:base/List";

let nil : List.List<Int> = List.nil<Int>();

List.isNil(nil);

List.push

func push<T>(

  x : T
  l : List<T>

) : List<T>

Example

import List "mo:base/List";

let nil : List.List<Int> = List.nil<Int>();

List.push(-1, nil);

List.last

func last<T>(l : List<T>) : ?T

Example

import List "mo:base/List";

let list : List.List<Int> = ?(0, ?(-1, null));

List.last(list);

List.pop

func pop<T>(l : List<T>) : (?T, List<T>)

Example

import List "mo:base/List";

let list : List.List<Int> = ?(0, ?(-1, null));

List.pop(list);

List.size

func size<T>(l : List<T>) : Nat

Example

import List "mo:base/List";

let list : List.List<Int> = ?(1, ?(0, ?(-1, null)));

List.size(list);

List.get

func get<T>(

  l : List<T>
  n : Nat

) : ?T

Example

import List "mo:base/List";

let list : List.List<Int> = ?(0, ?(-1, null));

List.get(list, 0);

List.reverse

func reverse<T>(l : List<T>) : List<T>

Example

import List "mo:base/List";

let list : List.List<Int> = ?(1, ?(0, ?(-1, null)));

List.reverse(list);

List.iterate

func iterate<T>(

  l : List<T>
  f : T -> ()

) : ()

Example

import List "mo:base/List";
import Iter "mo:base/Iter";

let list : List.List<Int> = ?(-3, ?(-2, ?(-1, null)));

var number : Int = 5;

func edit(x : Int) : () {
    number += x;
};

let iterate : () = List.iterate(list, edit);

List.toArray(list);

List.map

func map<T, U>(

  l : List<T>
  f : T -> U

) : List<U>

Example

import List "mo:base/List";
import Int "mo:base/Int";

let list : List.List<Int> = ?(-3, ?(-2, ?(-1, null)));

func change(x : Int) : Text {
    Int.toText(x);
};

List.map<Int, Text>(list, change);

List.filter

func filter<T>(

  l : List<T>
  f : T -> Bool

) : List<T>

Example

import List "mo:base/List";
import Int "mo:base/Int";

let list : List.List<Int> = ?(1, ?(0, ?(-1, null)));

func change(x : Int) : Bool {
    x > 0;
};

List.filter<Int>(list, change);

List.partition

func partition<T>(

  l : List<T>
  f : T -> Bool

) : (List<T>, List<T>)

Example

import List "mo:base/List";
import Int "mo:base/Int";

let list : List.List<Int> = ?(1, ?(0, ?(-1, ?(-2, null))));

func change(x : Int) : Bool {
    x >= 0;
};

List.partition<Int>(list, change);

List.mapFilter

func mapFilter<T, U>(

  l : List<T>
  f : T -> ?U

) : List<U>

Example

import List "mo:base/List";
import Int "mo:base/Int";

let list : List.List<Int> = ?(1, ?(0, ?(-1, null)));

func change(x : Int) : ?Text {
    if (x >= 0) {
        ?(Int.toText(x));
    } else {
        null;
    };
};

List.mapFilter<Int, Text>(list, change);

List.mapResult

func mapResult<T, R, E>(

  xs : List<T>
   f : T -> Result.Result<R, E>

) : Result.Result<List<R>, E>

Example

import List "mo:base/List";
import Result "mo:base/Result";

let list : List.List<Int> = ?(1, ?(0, ?(-1, null)));

func result(x : Int) : Result.Result<Int, Text> {
    if (x >= 0) {
        #ok(x);
    } else {
        #err("it is negative list element");
    };
};

List.mapResult<Int, Int, Text>(list, result);

List.append

func append<T>(

  l : List<T>
  m : List<T>

) : (List<T>)

Example

import List "mo:base/List";

let listN : List.List<Int> = ?(-3, ?(-2, ?(-1, null)));
let listP : List.List<Int> = ?(2, ?(1, ?(0, null)));

List.append<Int>(listP, listN);

List.flatten

func flatten<T>(

l : List<List<T>>

) : (List<T>)

Example

import List "mo:base/List";

let listN : List.List<Int> = ?(-3, ?(-2, ?(-1, null)));
let listP : List.List<Int> = ?(2, ?(1, ?(0, null)));

let listOflists : List.List<List.List<Int>> = ?(listN, ?(listP, null));

List.flatten<Int>(listOflists);

List.take

func take<T>(

  l : List<T>
  n : Nat

) : (List<T>)

Example

import List "mo:base/List";

let list : List.List<Int> = ?(-3, ?(-2, ?(-1, null)));

List.take<Int>(list, 2);

List.drop

func drop<T>(

  l : List<T>
  n : Nat

) : (List<T>)

Example

import List "mo:base/List";

let list : List.List<Int> = ?(-3, ?(-2, ?(-1, null)));

List.drop<Int>(list, 2);

List.foldLeft

func foldLeft<T, S>(

    list : List<T>
    base : S
 combine : (S, T) -> S

) : S

Example

import List "mo:base/List";

let list : List.List<Int> = ?(-3, ?(-2, ?(-1, null)));

let base : Int = 10;

func change(x : Int, y : Int) : Int {
    x + y;
};

List.foldLeft<Int, Int>(list, 2, change);

List.foldRight

func foldRight<T, S>(

    list : List<T>
    base : S
 combine : (T, S) -> S

) : S

Example

import List "mo:base/List";

let list : List.List<Int> = ?(-3, ?(-2, ?(-1, null)));

let base : Int = 10;

func change(x : Int, y : Int) : Int {
    x + y;
};

List.foldRight<Int, Int>(list, 2, change);

List.find

func find<T>(

  l : List<T>
  f : T -> Bool

) : ?T

Example

import List "mo:base/List";

let list : List.List<Int> = ?(-3, ?(-2, ?(-1, null)));

let base : Int = 10;

func change(x : Int) : Bool {
    x > -2;
};

List.find<Int>(list, change);

List.some

func some<T>(

  l : List<T>
  f : T -> Bool

) : Bool

Example

import List "mo:base/List";

let list : List.List<Int> = ?(-3, ?(-2, ?(-1, null)));

let base : Int = 10;

func change(x : Int) : Bool {
    x == -2;
};

List.some<Int>(list, change);

List.all

func all<T>(

  l : List<T>
  f : T -> Bool

) : Bool

Example

import List "mo:base/List";

let list : List.List<Int> = ?(-3, ?(-2, ?(-1, null)));

let base : Int = 10;

func change(x : Int) : Bool {
    x > 0;
};

List.all<Int>(list, change);

List.merge

func merge<T>(

    l1 : List<T>
    l2 : List<T>
    lessThanOrEqual : (T, T) -> Bool

) : List<T>

Example

import List "mo:base/List";

let list1 : List.List<Int> = ?(-3, ?(-2, ?(-1, null)));
let list2 : List.List<Int> = ?(-3, ?(-2, ?(-1, null)));

func change(x : Int, y : Int) : Bool {
    x <= y;
};

List.merge<Int>(list1, list2, change);

List.compare

func compare<T>(

     l1 : List<T>
     l2 : List<T>
compare : (T, T) -> Order.Order

) : Order.Order

Example

import List "mo:base/List";
import Int "mo:base/Int";
import Order "mo:base/Order";

let list1 : List.List<Int> = ?(-3, ?(-2, ?(-1, null)));
let list2 : List.List<Int> = ?(-3, ?(-2, ?(-1, null)));

List.compare<Int>(list1, list2, Int.compare);

List.equal

func equal<T>(

   l1 : List<T>
   l2 : List<T>
equal : (T, T) -> Bool

) : Bool

Example

import List "mo:base/List";
import Int "mo:base/Int";

let list1 : List.List<Int> = ?(-3, ?(-2, ?(-1, null)));
let list2 : List.List<Int> = ?(-3, ?(-2, ?(-1, null)));

List.equal<Int>(list1, list2, Int.equal);

List.tabulate

func tabulate<T>(

  n : Nat
  f : Nat -> T

) : List<T>

Example

import List "mo:base/List";

func change(x : Int) : Int {
    x * 2;
};

List.tabulate<Int>(3, change);

List.make

func make<T>(n : T) : List<T>

Example

import List "mo:base/List";
import Int "mo:base/Int";

List.make<Int>(3);

List.replicate

func replicate<T>(

  n : Nat
  x : T

) : List<T>

Example

import List "mo:base/List";
import Int "mo:base/Int";

List.replicate<Int>(3, 3);

List.zip

func zip<T, U>(

  xs : List<T>
  ys : List<U>

) : List<(T, U)>

Example

import List "mo:base/List";

let listN : List.List<Int> = ?(-3, ?(-2, ?(-1, null)));
let listP : List.List<Int> = ?(1, ?(0, null));

List.zip<Int, Int>(listN, listP);

List.zipWith

func zipWith<T, U, V>(

  xs : List<T>
  ys : List<U>
   f : (T, U) -> V

) : List<V>

Example

import List "mo:base/List";

let listN : List.List<Int> = ?(-3, ?(-2, ?(-1, null)));
let listP : List.List<Int> = ?(0, ?(0, null));

func edit(x : Int, y : Int) : Int {
    x * y;
};

List.zipWith<Int, Int, Int>(listN, listP, edit);

List.split

func split<T>(

  n : Nat
 xs : List<T>

) : (List<T>, List<T>)

Example

import List "mo:base/List";

let list : List.List<Int> = ?(-3, ?(-2, ?(-1, null)));

List.split<Int>(2, list);

List.chunks

func chunks<T>(

  n : Nat
 xs : List<T>

) : List<List<T>>

Example

import List "mo:base/List";

let list : List.List<Int> = ?(-3, ?(-2, ?(-1, null)));

List.chunks<Int>(1, list);

List.fromArray

func fromArray<T>(xs : [T]) : List<T>

Example

import List "mo:base/List";

let array : [Int] = [-2, -1, 0, 1, 2];

List.fromArray<Int>(array);

List.fromVarArray

func fromVarArray<T>(

 xs : [var T]

) : List<T>

Example

import List "mo:base/List";

let varArray : [var Int] = [var -2, -1, 0, 1, 2];

List.fromVarArray<Int>(varArray);

List.toArray

func toArray<T>(xs : List<T>) : [T]

Example

import List "mo:base/List";

let list : List.List<Int> = ?(-3, ?(-2, ?(-1, null)));

List.toArray<Int>(list);

List.toVarArray

func toVarArray<T>(xs : List<T>) : [var T]

Example

import List "mo:base/List";

let list : List.List<Int> = ?(-3, ?(-2, ?(-1, null)));

List.toVarArray<Int>(list);

List.toIter

func toIter<T>(xs : List<T>) : Iter.Iter<T>

Example

import List "mo:base/List";
import Iter "mo:base/Iter";

let list : List.List<Int> = ?(-3, ?(-2, ?(-1, null)));

let iter : Iter.Iter<Int> = List.toIter<Int>(list);

var number : Int = 10;

for (i in iter) {
    number += i;
};

number