Passing arguments

Beginner

Tutorial

Overview

This document aims to provide examples of passing different argument types to a canister.

Arrays

An array is a collection of items of the same data type.

The following example defines an array of numbers and a function that returns the array.

Motoko

Motoko differentiates between immutable arrays, which cannot be altered, and mutable arrays, which can be modified.

To declare an immutable array (default):

let a : [Nat] = [0, 1, 2, 3];

To declare a mutable array, the [var _] syntax is used:

let a : [var Nat] = [var 0, 1, 2, 3] ;

To declare a function that returns an array:

public func get_numbers(a: [Nat]) : [Nat] {
    return a;
}

The Array Motoko base library provides utility functions on arrays. To learn more about the Array Motoko base library, refer to the Motoko base library reference on Array and the Motoko language quick reference on arrays.

Rust

Rust uses the vec type to represent vectors (sequences, lists, arrays).

let numbers = vec![0, 1, 2, 3 ];
#[query]
fn get_numbers(numbers: Vec<u32>) -> Vec<u32> {
    numbers
}

TypeScriptBeta

Azle refers to the Vec type to represent the equivalent of an array in Typescript. This is because Vec aligns with the Candid type.

import { Canister, int32, Vec, query } from 'azle';
let numbers = [0,1,2,3];
export default Canister({
    get_numbers: query([Vec(int32], Vec(int32), () => {
        return numbers;
    })
});

To learn more about the Vec object in Typescript via Azle, refer to the Azle book reference on Vec.

PythonBeta

Kybra refers to the Vec type to represent the equivalent of an array in Python. This is because Vec aligns with the Candid type.

from kybra import int32, query, Vec
numbers = [0, 1, 2, 3]
@query
def get_numbers(Vec[int32]) -> Vec[int32]:
    return numbers

To learn more about Vec in Python via Kybra, refer to the Kybra book reference on Vec.

bash

You can pass a vector as an argument by explicitly specifying the canister name and method name using the dfx tool in the following format:

    dfx canister call canister_name method_name '(vec {})'

Assuming you have a method named get_numbers that accepts a Vec parameter, as exemplified in other examples:

    dfx canister call canister_name get_numbers '(vec {1; 2; 3})'

To learn more about calling a method from a canister in bash, refer to the dfx reference on the dfx canister call command.

For additional examples, refer to type vec in the Candid Reference.

Variants

A variant type represents a value that is from exactly one of the given cases, or tags. Similar to enums, they let you differentiate between different types within the same variable.

The following example defines a Day type representing a day of the week. It utilizes a switch statement to match the input Day with one of its variants, returning the corresponding full name of the day.

Motoko

type Day = {#sun; #mon; #tue; #wed; #thu; #fri; #sat};

public query func get_text(d : Day) : Text {
  switch d {
     case (#sun) "Sunday";
     case (#mon) "Monday";
     case (#tue) "Tuesday";
     case (#wed) "Wednesday";
     case (#thu) "Thursday";
     case (#fri) "Friday";
     case (#sat) "Saturday";
   };
};

For additional examples, refer to the Type variant reference in Motoko.

To learn more about variants in Motoko, refer to Kai Peacock's blog on using Motoko variants.

Rust

type Day = variant {
    Sun;
    Mon;
    Tue;
    Wed;
    Thu;
    Fri;
    Sat;
}

[query]
fn get_text(d: Day) -> &'static str {
    match d {
        Day::Sun => "Sunday",
        Day::Mon => "Monday",
        Day::Tue => "Tuesday",
        Day::Wed => "Wednesday",
        Day::Thu => "Thursday",
        Day::Fri => "Friday",
        Day::Sat => "Saturday",
    }
}

TypeScriptBeta

import { Canister,  query, Variant } from 'azle';

const Day = Variant({
    Sun;
    Mon;
    Tue;
    Wed;
    Thu;
    Fri;
    Sat;
});

export default Canister({
    get_text: query([Day], Day, (d)) => {
        switch (d) {
            case Day.Sun:
                return "Sunday";
            case Day.Mon:
                return "Monday";
            case Day.Tue:
                return "Tuesday";
            case Day.Wed:
                return "Wednesday";
            case Day.Thu:
                return "Thursday";
            case Day.Fri:
                return "Friday";
            case Day.Sat:
                return "Saturday";
    }
}
});

To learn more about variants in Typescript via Azle, refer to the Azle book reference on variants.

PythonBeta

from kybra import nat32, Variant, query

class Day(Variant, total=False):
    Sun: str
    Mon: str
    Tue: str
    Wed: str
    Thu: str
    Fri: str
    Sat: str

@query
def get_text(d: Day) -> str:
    if d == Day.Sun:
        return "Sunday"
    elif d == Day.Mon:
        return "Monday"
    elif d == Day.Tue:
        return "Tuesday"
    elif d == Day.Wed:
        return "Wednesday"
    elif d == Day.Thu:
        return "Thursday"
    elif d == Day.Fri:
        return "Friday"
    elif d == Day.Sat:
        return "Saturday"

To learn more about variants in Python in Kybra, refer to the Kybra book reference on variants.

bash

You can pass a variant as an argument by explicitly specifying the canister name and method name using the dfx tool in the following format:

    dfx canister call canister_name method_name '(variant {})'

Assuming you have a method named get_text that accepts a Variant parameter, as exemplified in other examples:

    dfx canister call canister_name get_text '(variant {Sun})'

To learn more about calling a method from a canister in bash, refer to the DFX reference on the dfx canister call command.

For additional examples, refer to type variant in the Candid Reference