Lesson 3: Primitive Types in Motoko.

Primitive types are fundamental core data types that are not composed of more fundamental types.

Primitive types are all the types that do not need to be imported before they can be used in type annotation.

A few primitive types in Motoko

🔢 Nat

Nat is used for unbounded natural numbers (1,2,3,4,...♾️). By default all positive whole numbers are casted to Nat.

let n : Nat = 1;

Is equivalent to

let n = 1; // Will be casted to Nat automatically

Unbounded means that value of type Nat will never overflow. The memory representation used will grow to accommodate any finite number. Motoko also has the concept of bounded natural numbers (Nat8, Nat16, Nat32, Nat64) that we will cover later. If you try to assign a negative number to a Nat the program will trap.

let n : Nat = -1;

This line will return an error: literal of type Int does not have expected type Nat.

Nat supports usual operations:

  • Addition: you can add two numbers using the addition operator +
let a : Nat = 1 + 1;    // 2
  • Subtraction: you can subtract two numbers using the subtraction operator -
let a : Nat = 10 - 2;   // 8

Be careful with subtractions. Nat only plays with the positive numbers. If the result of the subtraction is less than zero, it won't fit. The value will no longer be of the Nat type and that could cause trouble if your program is expecting a value of the Nat type.

  • Multiplication: you can multiply two numbers using the multiplication operator *
let a : Nat = 10 * 10;  // 100
  • Division and modulo: to divide two numbers, you can use the division operator / and to find the remainder of a divided by b, you can use the modulo operator %
let a : Nat = 10 / 2;   // 5
let b : Nat = 3 % 2;    // 1

➖ Int.

Integers represent whole numbers that can be positive or negative. The same mathematical operations seen earlier (addition, multiplication, subtraction, division, and modulo) can be performed on both Int and Nat.

let i : Int = -3;
let j : Int = 5;

Since Int includes positive and negative whole numbers it includes all value of type Nat. We say that Nat is a subtype of Int. Int is also an unbounded type and has bounded equivalents that we will cover later (Int8, Int16, Int32, Int64).

🚦 Bool.

A Bool is either true or false. Bool stands for boolean and this data type only contains two values.

let light_on : Bool = true;
let door_open : Bool = false;

Booleans can be used and combined with logical operators:

  • and
let result = false and false;   //false

let result = true and false;    //false

let result = false and true;    //false

let result = true and true;     //true
  • or
let result = false or false;   //false

let result = true or false;    //true

let result = false or true;    //true

let result = true or true;     //true
  • not
let result = not true;      //false

let result = not false;     //true

Nat and Int supports comparison operators, which compare two integers and returns a Bool:

  • The == (equality) operator which indicates if two values are equal.
  • The != (not equal) operator which indicates if two values are different.
  • The < (less than) and > (more than) operators.
  • The <= (less than or equal to) and >= (more than or equal to) operators.
3 < 5   // true
1 >= 1  // true
1 != 1  // false
2 == 10/5   // true

The == operator is very different from the = operator. The first will test if two values are equal while the later will asign a value to a variable.

💬 Text

In Motoko, strings can be written surrounded by double quotes "

"Hello Motoko Bootcamp!"

The type for string is Text.

let welcomePhrase : Text = "Hello Motoko Bootcamp!";

We can use the concatenation operator # to join two Text together.

let firstName : Text = "Motoko";
let surname : Text = "Bootcamp";
let completeName : Text = firstName # surname;

We can access the size of a Text by calling the .size() method.

let name : Text = "Motoko";
let size = name.size()  // 6

🔤 Char

A value of type Text is actually composed of values from another type: Char. A Text is the concatenation of multiple characters. Characters are single-quote delimited '

let character_1 : Char = 'c';
let character_2 : Char = '8';
let character_3 : Char = '∏';

Char are represented by their Unicode code points. We can use the Char module from the Base library to check the unicode value.

import Char "mo:base/Char";
import Debug "mo:base/Debug";
actor {
    let a : Char = 'a';
    Debug.print(debug_show(Char.toNat32(a)));   // 97
}

We can easily iterate over all the characters in a Text, by calling the chars() method. We can then use this iterator to create a for loop.

import Debug "mo:base/Debug";
import Char "mo:base/Char";
actor {
    let name : Text = "Motoko";
    for (letter in name.chars()){
        Debug.print(Char.toText(letter));
    };
};

Notice how when we iterate letter is a Char and we need to convert it back to Text to use Debug.print (learn more here). The Char module also contains a few functions that can be used to test properties of characters:

  • isDigit
Char.isDigit('9');  // true
  • isWhitespace
Char.isWhitespace('a'); // false
  • isLowercase
Char.isLowercase('c');  //  true
  • isUppercase
Char.isUppercase('D');  // true
  • isAlphabetic
Char.isAlphabetic('|'); // false

💥 Float.

Float are numbers that have a decimal part.

let pi = 3.14;
let e = 2.71;

If you want to use Float for whole numbers, you need to add the type descriptor otherwise they would automatically be casted to Int or Nat.

let f : Float = 2;
let n = 2;  // Automatically casted to type Nat

Float are implemented on 64-bits folowing the IEEE 754 representation. Due to the limited precision, operations may result in numerical errors.

0.1 + 0.1 + 0.1 == 0.3 // => false

1e16 + 1.0 != 1e16 // => false

🎛️ Bounded types

Motoko provides support for bounded types which are integer types with fixed precision. These bounded types can be useful for several reasons:

  • Memory efficiency: Bounded types allow you to know exactly how much memory your data will occupy.
  • Exact sizing: When you know that an API returns an exact number, you can use bounded types to ensure that the - returned number is represented accurately.
  • Execution efficiency: If you know that your numbers require 64-bit arithmetic, using Nat64 is more efficient than using Nat.
  • Bitwise arithmetic: Bounded types make it easier to perform bitwise operations such as << or XOR on binary data.

Nat8, Nat16, Nat32 and Nat64

There are four natural types supported in Motoko: Nat8, Nat16, Nat32, and Nat64.

The number in the type name specifies the number of bits in the type representation. For example, Nat32 represents a 32-bit natural number.

To declare a bounded variable, you must specify the type explicitly to avoid it being automatically cast to a regular Nat:

let n : Nat32 = 1;

In contrast, if you declare a variable without specifying its type, it will default to a regular Nat

let n = 1; // Will be casted to Nat automatically

Int8, Int16, Int32, and Int64

Motoko also supports integer types, including Int8, Int16, Int32, and Int64. Bounded integer types behave similarly to bounded natural types, except they support negative values. The number in the type name specifies the number of bits in the type representation. For example, Int32 represents a 32-bit integer:

let i : Int32 = -1;

🤖 Blob.

Blob stands for Binary Large Object. The Blob type represents an immutable sequence of bytes: they are immutable, iterable, but not indexable and can be empty.

Byte sequences are also often represented as [Nat8], i.e. an array of bytes, but this representation is currently much less compact than Blob, taking 4 physical bytes to represent each logical byte in the sequence. If you would like to manipulate Blobs, it is recommended that you convert Blobs to [var Nat8] or Buffer<Nat8>, do the manipulation, then convert back.

🫙 Unit type

The last type we will mention in this lesson is the unit type (). This type is also called the empty tuple type. It's useful in several places, for example in functions to indicate that a function does not return any specific type.

import Debug "mo:base/Debug";
actor {
    public func printMessage(message : Text) : async () {
        Debug.print(message);
        return();
    };
}