FunC standard library
This section discusses the stdlib.fc library with standard functions used in FunC.
Currently, the library is just a wrapper for the most common assembler of the TVM commands which are not built-in. Each TVM command description used in the library can be found in the TVM documentation section. Some descriptions were borrowed for this document.
Some functions are commented out in the file. It means that they have already become built-ins for optimization purposes. However, the type signature and semantics remain the same.
Note that some less common commands are not presented in the stdlib. Someday they will also be added.
Tuple manipulation primitives
The names and the types are mostly self-explaining. See polymorhism with forall for more info on the polymorphic functions.
Note that currently values of atomic type tuple
cannot be cast into composite tuple types (e.g. [int, cell]
) and vise versa.
Lisp-style lists
Lists can be represented as nested 2-element tuples. Empty list is conventionally represented as TVM null
value (it can be obtained by calling null()
). For example, the tuple (1, (2, (3, null)))
represents the list [1, 2, 3]
. Elements of a list can be of different types.
cons
forall X -> tuple cons(X head, tuple tail) asm "CONS";
Adds an element to the beginning of a lisp-style list.
uncons
forall X -> (X, tuple) uncons(tuple list) asm "UNCONS";
Extracts the head and the tail of lisp-style list.
list_next
forall X -> (tuple, X) list_next(tuple list) asm( -> 1 0) "UNCONS";
Extracts the head and tail of a lisp-style list. Can be used as a (non-)modifying method.
() foo(tuple xs) {
(_, int x) = xs.list_next(); ;; get the first element, `_` means do not use tail list
int y = xs~list_next(); ;; pop the first element
int z = xs~list_next(); ;; pop the second element
}
car
forall X -> X car(tuple list) asm "CAR";
Returns the head of a lisp-style list.
cdr
tuple cdr(tuple list) asm "CDR";
Returns the tail of a lisp-style list.
Other tuple primitives
empty_tuple
tuple empty_tuple() asm "NIL";
Creates 0-element tuple.
tpush
forall X -> tuple tpush(tuple t, X value) asm "TPUSH";
forall X -> (tuple, ()) ~tpush(tuple t, X value) asm "TPUSH";
Appends the value x
to the Tuple t = (x1, ..., xn)
but only if the resulting Tuple t' = (x1, ..., xn, x)
is no longer than 255 characters. Otherwise, a type check exception is thrown.
single
forall X -> [X] single(X x) asm "SINGLE";
Creates a singleton, i.e., a tuple of length one.
unsingle
forall X -> X unsingle([X] t) asm "UNSINGLE";
Unpacks a singleton.
pair
forall X, Y -> [X, Y] pair(X x, Y y) asm "PAIR";
Creates a pair.
unpair
forall X, Y -> (X, Y) unpair([X, Y] t) asm "UNPAIR";
Unpacks a pair.
triple
forall X, Y, Z -> [X, Y, Z] triple(X x, Y y, Z z) asm "TRIPLE";
Creates a triple.
untriple
forall X, Y, Z -> (X, Y, Z) untriple([X, Y, Z] t) asm "UNTRIPLE";
Unpacks a triple.
tuple4
forall X, Y, Z, W -> [X, Y, Z, W] tuple4(X x, Y y, Z z, W w) asm "4 TUPLE";
Creates 4-element tuple.
untuple4
forall X, Y, Z, W -> (X, Y, Z, W) untuple4([X, Y, Z, W] t) asm "4 UNTUPLE";
Unpacks 4-element tuple.
first
forall X -> X first(tuple t) asm "FIRST";
Returns the first element of a tuple.
second
forall X -> X second(tuple t) asm "SECOND";
Returns the second element of a tuple.
third
forall X -> X third(tuple t) asm "THIRD";
Returns the third element of a tuple.
fourth
forall X -> X fourth(tuple t) asm "3 INDEX";
Returns the fourth element of a tuple.
pair_first
forall X, Y -> X pair_first([X, Y] p) asm "FIRST";
Returns the first element of a pair.
pair_second
forall X, Y -> Y pair_second([X, Y] p) asm "SECOND";
Returns the second element of a pair.
triple_first
forall X, Y, Z -> X triple_first([X, Y, Z] p) asm "FIRST";
Returns the first element of a triple.
triple_second
forall X, Y, Z -> Y triple_second([X, Y, Z] p) asm "SECOND";
Returns the second element of a triple.
triple_third
forall X, Y, Z -> Z triple_third([X, Y, Z] p) asm "THIRD";
Returns the third element of a triple.
Domain specific primitives
Extracting info from c7
Some useful information regarding smart contract invocation can be found in the c7 special register. These primitives serve for convenient data extraction.
now
int now() asm "NOW";
Returns the current Unix time as an Integer
my_address
slice my_address() asm "MYADDR";
Returns the internal address of the current smart contract as a Slice with MsgAddressInt
. If necessary, it can be parsed further using primitives such as parse_std_addr
.
get_balance
[int, cell] get_balance() asm "BALANCE";
Returns the remaining balance of the smart contract as tuple
consisting of int
(the remaining balance in nanotoncoins) and cell
(a dictionary with 32-bit keys representing the balance of “extra currencies”). Note that RAW primitives such as send_raw_message
do not update this field.
cur_lt
int cur_lt() asm "LTIME";
Returns the logical time of the current transaction.
block_lt
int block_lt() asm "BLOCKLT";