Passing arguments
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
- Rust
- TypeScript
- Python
- bash
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 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
}
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.
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.
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