Tolk vs FunC: standard library

FunC has a rich standard library, known as "stdlib.fc" file. It's quite low-level and contains many asm functions closely related to TVM instructions.

Tolk also has a standard library based on a FunC one. Three main differences:

1. It's split into multiple files: common.tolk, tvm-dicts.tolk, and others. Functions from common.tolk are always available. Functions from other files are available after import:

import "@stdlib/tvm-dicts"

beginCell()          // available always
createEmptyDict()    // available due to import

2. You don't need to download it from GitHub; it's a part of Tolk distribution.
3. Almost all FunC functions were renamed to verbose clear names. So that when you write contracts or read examples, you better understand what's going on.

A list of renamed functions

If the Required import column is empty, a function is available without imports.

Note that some of the functions were deleted because they either can be expressed syntactically, or they were very uncommon in practice.

FunC name	Tolk name	Required import
empty_tuple	createEmptyTuple
tpush	tuplePush
first	tupleFirst
at	tupleAt
touch	stackMoveToTop	tvm-lowlevel
impure_touch	(deleted)
single	(deleted)
unsingle	(deleted)
pair	(deleted)
unpair	(deleted)
triple	(deleted)
untriple	(deleted)
tuple4	(deleted)
untuple4	(deleted)
second	(deleted)
third	(deleted)
fourth	(deleted)
pair_first	(deleted)
pair_second	(deleted)
triple_first	(deleted)
triple_second	(deleted)
triple_third	(deleted)
minmax	minMax
my_address	getMyAddress
get_balance	getMyOriginalBalanceWithExtraCurrencies
cur_lt	getLogicalTime
block_lt	getCurrentBlockLogicalTime
cell_hash	cellHash
slice_hash	sliceHash
string_hash	sliceBitsHash
check_signature	isSignatureValid
check_data_signature	isSliceSignatureValid
compute_data_size	calculateCellSizeStrict
slice_compute_data_size	calculateSliceSizeStrict
compute_data_size?	calculateCellSize
slice_compute_data_size?	calculateSliceSize
~dump	debugPrint
~strdump	debugPrintString
dump_stack	debugDumpStack
get_data	getContractData
set_data	setContractData
get_c3	getTvmRegisterC3	tvm-lowlevel
set_c3	setTvmRegisterC3	tvm-lowlevel
bless	transformSliceToContinuation	tvm-lowlevel
accept_message	acceptExternalMessage
set_gas_limit	setGasLimit
buy_gas	(deleted)
commit	commitContractDataAndActions
divmod	divMod
moddiv	modDiv
muldiv	mulDivFloor
muldivr	mulDivRound
muldivc	mulDivCeil
muldivmod	mulDivMod
begin_parse	beginParse
end_parse	assertEndOfSlice
load_ref	loadRef
preload_ref	preloadRef
load_int	loadInt
load_uint	loadUint
preload_int	preloadInt
preload_uint	preloadUint
load_bits	loadBits
preload_bits	preloadBits
load_grams	loadCoins
load_coins	loadCoins
skip_bits	skipBits
first_bits	getFirstBits
skip_last_bits	removeLastBits
slice_last	getLastBits
load_dict	loadDict
preload_dict	preloadDict
skip_dict	skipDict
load_maybe_ref	loadMaybeRef
preload_maybe_ref	preloadMaybeRef
cell_depth	getCellDepth
slice_refs	getRemainingRefsCount
slice_bits	getRemainingBitsCount
slice_bits_refs	getRemainingBitsAndRefsCount
slice_empty?	isEndOfSlice
slice_data_empty?	isEndOfSliceBits
slice_refs_empty?	isEndOfSliceRefs
slice_depth	getSliceDepth
equal_slice_bits	isSliceBitsEqual
builder_refs	getBuilderRefsCount
builder_bits	getBuilderBitsCount
builder_depth	getBuilderDepth
begin_cell	beginCell
end_cell	endCell
store_ref	storeRef
store_uint	storeUint
store_int	storeInt
store_slice	storeSlice
store_grams	storeCoins
store_coins	storeCoins
store_dict	storeDict
store_maybe_ref	storeMaybeRef
store_builder	storeBuilder
load_msg_addr	loadAddress
parse_addr	parseAddress
parse_std_addr	parseStandardAddress
parse_var_addr	(deleted)
config_param	getBlockchainConfigParam
raw_reserve	reserveToncoinsOnBalance
raw_reserve_extra	reserveExtraCurrenciesOnBalance
send_raw_message	sendRawMessage
set_code	setContractCodePostponed
rand	randomRange
get_seed	randomGetSeed
set_seed	randomSetSeed
randomize	randomizeBy
randomize_lt	randomizeByLogicalTime
dump	debugPrint
strdump	debugPrintString
dump_stk	debugDumpStack
empty_list	createEmptyList	lisp-lists
cons	listPrepend	lisp-lists
uncons	listSplit	lisp-lists
list_next	listNext	lisp-lists
car	listGetHead	lisp-lists
cdr	listGetTail	lisp-lists
new_dict	createEmptyDict	tvm-dicts
dict_empty?	dictIsEmpty	tvm-dicts
idict_set_ref	iDictSetRef	tvm-dicts
udict_set_ref	uDictSetRef	tvm-dicts
idict_get_ref	iDictGetRefOrNull	tvm-dicts
idict_get_ref?	iDictGetRef	tvm-dicts
udict_get_ref?	uDictGetRef	tvm-dicts
idict_set_get_ref	iDictSetAndGetRefOrNull	tvm-dicts
udict_set_get_ref	iDictSetAndGetRefOrNull	tvm-dicts
idict_delete?	iDictDelete	tvm-dicts
udict_delete?	uDictDelete	tvm-dicts
idict_get?	iDictGet	tvm-dicts
udict_get?	uDictGet	tvm-dicts
idict_delete_get?	iDictDeleteAndGet	tvm-dicts
udict_delete_get?	uDictDeleteAndGet	tvm-dicts
udict_set	uDictSet	tvm-dicts
idict_set	iDictSet	tvm-dicts
dict_set	sDictSet	tvm-dicts
udict_add?	uDictSetIfNotExists	tvm-dicts
udict_replace?	uDictSetIfExists	tvm-dicts
idict_add?	iDictSetIfNotExists	tvm-dicts
idict_replace?	iDictSetIfExists	tvm-dicts
udict_set_builder	uDictSetBuilder	tvm-dicts
idict_set_builder	iDictSetBuilder	tvm-dicts
dict_set_builder	sDictSetBuilder	tvm-dicts
udict_add_builder?	uDictSetBuilderIfNotExists	tvm-dicts
udict_replace_builder?	uDictSetBuilderIfExists	tvm-dicts
idict_add_builder?	iDictSetBuilderIfNotExists	tvm-dicts
idict_replace_builder?	iDictSetBuilderIfExists	tvm-dicts
udict_delete_get_min	uDictDeleteFirstAndGet	tvm-dicts
idict_delete_get_min	iDictDeleteFirstAndGet	tvm-dicts
dict_delete_get_min	sDictDeleteFirstAndGet	tvm-dicts
udict_delete_get_max	uDictDeleteLastAndGet	tvm-dicts
idict_delete_get_max	iDictDeleteLastAndGet	tvm-dicts
dict_delete_get_max	sDictDeleteLastAndGet	tvm-dicts
udict_get_min?	uDictGetFirst	tvm-dicts
udict_get_max?	uDictGetLast	tvm-dicts
udict_get_min_ref?	uDictGetFirstAsRef	tvm-dicts
udict_get_max_ref?	uDictGetLastAsRef	tvm-dicts
idict_get_min?	iDictGetFirst	tvm-dicts
idict_get_max?	iDictGetLast	tvm-dicts
idict_get_min_ref?	iDictGetFirstAsRef	tvm-dicts
idict_get_max_ref?	iDictGetLastAsRef	tvm-dicts
udict_get_next?	uDictGetNext	tvm-dicts
udict_get_nexteq?	uDictGetNextOrEqual	tvm-dicts
udict_get_prev?	uDictGetPrev	tvm-dicts
udict_get_preveq?	uDictGetPrevOrEqual	tvm-dicts
idict_get_next?	iDictGetNext	tvm-dicts
idict_get_nexteq?	iDictGetNextOrEqual	tvm-dicts
idict_get_prev?	iDictGetPrev	tvm-dicts
idict_get_preveq?	iDictGetPrevOrEqual	tvm-dicts
udict::delete_get_min	uDictDeleteFirstAndGet	tvm-dicts
idict::delete_get_min	iDictDeleteFirstAndGet	tvm-dicts
dict::delete_get_min	sDictDeleteFirstAndGet	tvm-dicts
udict::delete_get_max	uDictDeleteLastAndGet	tvm-dicts
idict::delete_get_max	iDictDeleteLastAndGet	tvm-dicts
dict::delete_get_max	sDictDeleteLastAndGet	tvm-dicts
pfxdict_get?	prefixDictGet	tvm-dicts
pfxdict_set?	prefixDictSet	tvm-dicts
pfxdict_delete?	prefixDictDelete	tvm-dicts

A list of added functions

Tolk standard library has some functions missing in FunC but is pretty typical for everyday tasks.

Since Tolk is actively developed, and its standard library changes, it better considers the tolk-stdlib/ folder in sources here. Besides functions, there some constants were added: SEND_MODE_*, RESERVE_MODE_*, etc.

When FunC becomes deprecated, the documentation about Tolk stdlib will be rewritten entirely, anyway.

Remember that all the functions above are wrappers over the TVM assembler. If something is missing, you can quickly wrap any TVM instruction yourself.

Some functions became mutating, not returning a copy

FunC	Tolk
int flags = cs~load_uint(32);	var flags = cs.loadUint(32);
dict~udict_set(...);	dict.uDictSet(...);
...	...

Most FunC functions used with ~ tilda in practice now mutate the object; see examples above.

For example, if you used dict~udict_set(…), just use dict.uDictSet(…), and everything is fine. But if you used dict.udict_set(…) to obtain a copy, you'll need to express it another way.

Read about mutability.

How does embedded stdlib work under the hood

As told above, all standard functions are available out of the box. You need import for non-common functions (it's intentional), but still, no external downloads.

It works the following way.

The first thing the Tolk compiler does at the start is locate the stdlib folder by searching predefined paths relative to an executable binary. For example, if you launch the Tolk compiler from a package installed (e.g. /usr/bin/tolk), locate stdlib in /usr/share/ton/smartcont. You may pass the TOLK_STDLIB env variable if you have a non-standard installation. It's standard practice for compilers.

A WASM wrapper tolk-js also contains stdlib. So, when you take tolk-js or blueprint, all stdlib functions are still available out of the box.

JetBrains and VS Code IDE plugins also auto-locate stdlib to provide auto-completion. If you use blueprint, it automatically installs tolk-js; therefore, folder node_modules/@ton/tolk-js/ exists in your project file structure. Inside are common.tolk, tvm-dicts.tolk, and others.