Using the Motoko standard library

For various practical language engineering reasons, the design of Motoko strives to minimize built-in types and operations.

Instead, whenever possible, the Motoko standard library provides the types and operations that make the language feel complete. However, this standard library is still currently under development, and is still incomplete.

This section describes a selected subset of modules from the Motoko standard library, with an emphasis on the modules that support core features and the libraries that are referenced in the examples. The libraries documented in this section are the most stable and least likely to change. However, all of the standard library APIs are subject to change over time to varying degrees. You should note, in particular, that the size and number of modules and functions included in the standard library may increase dramatically as Motoko evolves.

Importing from the standard library

To import from the standard library, use the import keyword. Give a local module name to introduce, in this example P for “Prelude”, and a URL where the import declaration may locate the imported module:

import P "mo:stdlib/prelude";
P.printLn("hello world");

This example illustrates how to import Motoko code—indicated by using the mo: prefix—using the stdlib/ standard library path and the module name prelude. You can also import Motoko code and other modules using relative paths. For example, if you have created a Motoko program named types.mo in the same folder as your main program, you could include it with an import declaration like this:

import Types "./types";

Using predefined compiler prelude function

The compiler itself contains a prelude in every program, effectively extending the language definition with a set of types and declarations that are always available.

In addition to these built-in compiler definitions, the prelude of the standard library contributes some additional functions in a supplemental Prelude module.

In contrast to the definitions in other modules, the compiler prelude definitions are always present, and do not require any import declaration to bring them into the current scope.

Iteration

Use type iter to perform iteration over an object.

type Iter<T_> = {next : () -> ?T_};

Absolute function

Use the abs function to return the absolute value of a number. The absolute value of a number is the number without its sign.

func abs(x : Int) : Nat ;

function ignore

func ignore(_ : Any) {};

function range

Sets a start and end values for a range.

class range(x : Nat, y : Nat) {
  var i = x;
  public func next() : ?Nat { if (i > y) null else {let j = i; i += 1; ?j} };
};

function revrange

class revrange(x : Nat, y : Nat) {
  var i = x + 1;
  public func next() : ?Nat { if (i <= y) null else {i -= 1; ?i} };
};

Printing

func printNat(x : Nat) ;
func printInt(x : Int) ;
func printChar(x : Char) ;
func print(x : Text) ;

RTS version

func rts_version() : Text ;

Hashing

func hashInt(x : Int) : Word32 ;
func idlHash(x : Text) : Word32 ;

Number conversions

func int64ToInt(n : Int64) : Int ;
func intToInt64(n : Int) : Int64 ;
func int64ToWord64(n : Int64) : Word64 ;
func word64ToInt64(n : Word64) : Int64 ;
func int32ToInt(n : Int32) : Int ;
func intToInt32(n : Int) : Int32 ;
func int32ToWord32(n : Int32) : Word32 ;
func word32ToInt32(n : Word32) : Int32 ;
func int16ToInt(n : Int16) : Int ;
func intToInt16(n : Int) : Int16 ;
func int16ToWord16(n : Int16) : Word16 ;
func word16ToInt16(n : Word16) : Int16 ;
func int8ToInt(n : Int8) : Int ;
func intToInt8(n : Int) : Int8 ;
func int8ToWord8(n : Int8) : Word8 ;
func word8ToInt8(n : Word8) : Int8 ;

func nat64ToNat(n : Nat64) : Nat ;
func natToNat64(n : Nat) : Nat64 ;
func nat64ToWord64(n : Nat64) : Word64 ;
func word64ToNat64(n : Word64) : Nat64 ;
func nat32ToNat(n : Nat32) : Nat ;
func natToNat32(n : Nat) : Nat32 ;
func nat32ToWord32(n : Nat32) : Word32 ;
func word32ToNat32(n : Word32) : Nat32 ;
func nat16ToNat(n : Nat16) : Nat ;
func natToNat16(n : Nat) : Nat16 ;
func nat16ToWord16(n : Nat16) : Word16 ;
func word16ToNat16(n : Word16) : Nat16 ;
func nat8ToNat(n : Nat8) : Nat ;
func natToNat8(n : Nat) : Nat8 ;
func nat8ToWord8(n : Nat8) : Word8 ;
func word8ToNat8(n : Word8) : Nat8 ;

func natToWord8(n : Nat) : Word8 ;
func word8ToNat(n : Word8) : Nat ;
func intToWord8(n : Int) : Word8 ;
func word8ToInt(n : Word8) : Int ;

func natToWord16(n : Nat) : Word16 ;
func word16ToNat(n : Word16) : Nat ;
func intToWord16(n : Int) : Word16 ;
func word16ToInt(n : Word16) : Int ;

func natToWord32(n : Nat) : Word32 ;
func word32ToNat(n : Word32) : Nat ;
func intToWord32(n : Int) : Word32 ;
func word32ToInt(n : Word32) : Int ;

func natToWord64(n : Nat) : Word64 ;
func word64ToNat(n : Word64) : Nat ;
func intToWord64(n : Int) : Word64 ;
func word64ToInt(n : Word64) : Int ;

func charToWord32(c : Char) : Word32 ;
func word32ToChar(w : Word32) : Char ;

func charToText(c : Char) : Text ;

// Exotic bitwise operations
func popcntWord8(w : Word8) : Word8 ;
func clzWord8(w : Word8) : Word8 ;
func ctzWord8(w : Word8) : Word8 ;
func btstWord8(w : Word8, amount : Word8) : Bool ;

func popcntWord16(w : Word16) : Word16 ;
func clzWord16(w : Word16) : Word16 ;
func ctzWord16(w : Word16) : Word16 ;
func btstWord16(w : Word16, amount : Word16) : Bool ;

func popcntWord32(w : Word32) : Word32 ;
func clzWord32(w : Word32) : Word32 ;
func ctzWord32(w : Word32) : Word32 ;
func btstWord32(w : Word32, amount : Word32) : Bool ;

func popcntWord64(w : Word64) : Word64 ;
func clzWord64(w : Word64) : Word64 ;
func ctzWord64(w : Word64) : Word64 ;
func btstWord64(w : Word64, amount : Word64) : Bool ;

Array utilities

func Array_init<T>(len : Nat,  x : T) : [var T] ;

func Array_tabulate<T>(len : Nat,  gen : Nat -> T) : [T] ;

Error utilities

// these will change
type ErrorCode = {#error; #system}; /* TBC */

func error(message : Text) : Error ;

func errorCode(e : Error) : ErrorCode ;

func errorMessage(e : Error) : Text ;

type Result<T> = {#ok : T; #error : Error};