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 { IDL, query } from 'azle';

const Day = IDL.Variant({
    Sun: IDL.Text,
    Mon: IDL.Text,
    Tue: IDL.Text,
    Wed: IDL.Text,
    Thu: IDL.Text,
    Fri: IDL.Text,
    Sat: IDL.Text
});
type Day =
    | { Sun: string }
    | { Mon: string }
    | { Tue: string }
    | { Wed: string }
    | { Thu: string }
    | { Fri: string }
    | { Sat: string };

export default class {
    @query([Day], IDL.Text)
    getText(day: Day): string {
        if ('Sun' in day) {
            return day.Sun;
        }

        if ('Mon' in day) {
            return day.Mon;
        }

        if ('Tue' in day) {
            return day.Tue;
        }

        if ('Wed' in day) {
            return day.Wed;
        }

        if ('Thu' in day) {
            return day.Thu;
        }

        if ('Fri' in day) {
            return day.Fri;
        }

        if ('Sat' in day) {
            return day.Sat;
        }

        throw new Error(`Variant "Day" has unknown tag`);
    }
}

To learn more about variants in Typescript via Azle, refer to the Azle code.

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