Introduction
In the FunC programming language, the stdlib.fc library is an indispensable part, providing numerous standard functions that form the foundation of FunC application development. This technical article will delve into the stdlib.fc library, particularly its assembler wrapper for TVM commands, and how these commands support the functionality and performance of the FunC programming language.
The Body
1. Tuple Operation Primitives
cons: Adds an element to the beginning of a Lisp-style list.uncons: Extracts the head and tail of a Lisp-style list.list_next: Extracts the head and tail of a Lisp-style list.car: Returns the head of a Lisp-style list.cdr: Returns the tail of a Lisp-style list.
2. Other Tuple Primitives
empty_tuple: Creates a tuple with 0 elements.tpush: Appends value x to Tuple t = (x1, …, xn), but only if the resulting Tuple t’ = (x1, …, xn, x) does not exceed 255 characters.single: Creates a singleton, i.e., a tuple of length one.unsingle: Unpacks a singleton.pair: Creates a pair.unpair: Unpacks a pair.triple: Creates a triple.untriple: Unpacks a triple.tuple4: Creates a quadruple.untuple4: Unpacks a quadruple.first: Returns the first element of a tuple.second: Returns the second element of a tuple.third: Returns the third element of a tuple.fourth: Returns the fourth element of a tuple.pair_first: Returns the first element of a pair.pair_second: Returns the second element of a pair.triple_first: Returns the first element of a triple.triple_second: Returns the second element of a triple.triple_third: Returns the third element of a triple.
3. Domain-Specific Primitives
now: Returns the current Unix time as an integer.my_address: Returns the internal address of the current smart contract in Slice form.get_balance: Returns the remaining balance of the smart contract in tuple form.cur_lt: Returns the logical time of the current transaction.block_lt: Returns the starting logical time of the current block.config_param: Returns the value of a global configuration parameter as a cell or null.cell_hash: Calculates the representation hash of cell c and returns it as a 256-bit unsigned integer x.slice_hash: Calculates the hash of slice s and returns it as a 256-bit unsigned integer x.string_hash: Calculates the sha256 of the data bits of slice s.check_signature: Checks the Ed25519 signature of hash using public_key.check_data_signature: Checks if signature is a valid Ed25519 signature of the data part of slice data using public_key.compute_data_size?: Returns the number of different cells x, data bits y, and cell references z in the DAG rooted at cell c, computed recursively.slice_compute_data_size?: Similar to compute_data_size?, but accepts slice s instead of cell.compute_data_size: Non-silent version of compute_data_size?, throws a cell overflow exception on failure.slice_compute_data_size: Non-silent version of slice_compute_data_size?, throws a cell overflow exception on failure.
4. Persistent Storage Save and Load
get_data: Returns the cell of the persisted contract storage.set_data: Sets cell c as the persisted contract data.
5. Continuation Primitives
get_c3: Returns the current value of c3, which usually has a continuation initialized by the entire code of the contract. It is used for function calls.set_c3: Updates the current value of c3. Typically, it is used to update the smart contract code in real-time. Note that after executing this primitive, the current code (and the recursive function call stack) does not change, but any other function calls will use the functions in the new code.bless: Converts slice s into a simple ordinary continuation c, where c.code = s, with an empty stack and save list.
6. Gas-Related Primitives
accept_message: Sets the current gas limit gl to its maximum allowed value gm, resets the gas credit gc to zero, and decreases the value of gr by gc.set_gas_limit: Sets the current gas limit gl to the minimum of limit and gm, and resets the gas credit gc to zero.commit: Commits the current state of registers c4 (“persistent data”) and c5 (“actions”), so that the current execution is considered “successful” even if an exception is thrown later, and saves these values.buy_gas: Calculates the amount of gas that can be purchased with gramnanoton coins and sets gl accordingly in the same way as set_gas_limit.
7. Action Primitives
raw_reserve: Creates an output action that reserves exactly amount nanoton coins.raw_reserve_extra: Similar to raw_reserve, but also accepts an extra token dictionary extra_amount represented by a cell or null.send_raw_message: Sends the raw message contained in msg.set_code: Creates an output action that changes the code of this smart contract to the code given by cell new_code.
8. Random Number Generator Primitives
random: Generates a new pseudo-random unsigned 256-bit integer x.rand: Generates a new pseudo-random integer z in the range 0…range−1.get_seed: Returns the current random seed as an unsigned 256-bit integer.set_seed: Sets the random seed to an unsigned 256-bit seed.randomize: Mixes an unsigned 256-bit integer x into the random seed r.randomize_lt: Equivalent to randomize(cur_lt());.
9. Address Operation Primitives
load_msg_addr: Loads the unique valid MsgAddress prefix from slice s.parse_addr: Parses the slice s containing a valid MsgAddress into tuple t.parse_std_addr: Parses the slice s containing a valid MsgAddressInt.parse_var_addr: Variant of parse_std_addr, which works even if the address is not exactly 256 bits long.
10. Debugging Primitives
dump_stack: Dumps the stack (up to the first 255 values) and shows the total stack depth.
11. Slice Primitives
begin_parse: Converts a cell to a slice.end_parse: Checks if s is empty.load_ref: Loads the first reference from the slice.preload_ref: Preloads the first reference from the slice.load_int: Loads a signed len-bit integer from the slice.load_uint: Loads an unsigned len-bit integer from the slice.preload_int: Preloads a signed len-bit integer from the slice.preload_uint: Preloads an unsigned len-bit integer from the slice.load_bits: Loads the first 0 ≤ len ≤ 1023 bits from slice s into a separate slice s’'.preload_bits: Preloads the first 0 ≤ len ≤ 1023 bits from slice s into a separate slice s’'.load_coins: Loads the amount of serialized Toncoins.skip_bits: Returns all but the first 0 ≤ len ≤ 1023 bits of s.first_bits: Returns the first 0 ≤ len ≤ 1023 bits of s.skip_last_bits: Returns all but the last 0 ≤ len ≤ 1023 bits of s.slice_last: Returns the last 0 ≤ len ≤ 1023 bits of s.load_dict: Loads dictionary D from slice s.preload_dict: Preloads dictionary D from slice s.skip_dict: Loads the dictionary like load_dict, but only returns the rest of the slice.slice_refs: Returns the number of references in slice s.slice_bits: Returns the number of data bits in slice s.slice_bits_refs: Returns the data bits and reference count in s.slice_empty?: Checks if slice s is empty.slice_data_empty?: Checks if slice s has no data bits.slice_refs_empty?: Checks if slice s has no references.slice_depth: Returns the depth of slice s.
12. Builder Primitives
begin_cell: Creates a new empty builder.end_cell: Converts the builder to a regular cell.store_ref: Stores a reference to cell c in builder b.store_uint: Stores an unsigned len-bit integer x in b.store_int: Stores a signed len-bit integer x in b.store_slice: Stores slice s in builder b.store_grams: Stores (serializes) an integer x in the range 0…2^120 − 1 in builder b.store_dict: Stores dictionary D represented by cell c or null in builder b.store_maybe_ref: Equivalent to store_dict.
13. Builder Size Primitives
builder_refs: Returns the number of cell references already stored in builder b.builder_bits: Returns the number of data bits already stored in builder b.builder_depth: Returns the depth of builder b.
14. Cell Primitives
cell_depth: Returns the depth of cell c.cell_null?: Checks if c is null.
15. Dictionary Primitives
dict_set: Sets the value associated with the key_len-bit key index in dictionary dict.dict_set_ref: Similar to dict_set, but sets the value to a reference to cell value.dict_get?: Looks up the key_len-bit key index in dictionary dict.dict_get_ref?: Similar to dict_get?, but returns the first reference to the found value.dict_get_ref: Variant of dict_get_ref?, returns null instead of the value if key index is not in dictionary dict.dict_set_get_ref: Sets the value associated with index to value and returns the old value.dict_delete?: Deletes the key_len-bit key index from dictionary dict.dict_delete_get?: Deletes the key_len-bit key index from dictionary dict and returns the old value.dict_add?: Add corresponding item of dict_set, sets the value associated with the key index in dictionary dict to value, but only if it is not already present in D.dict_replace?: Replace corresponding item of dict_set, sets the value associated with the key index in dictionary dict to value and returns the old value.
Conclusion
These primitives in the FunC standard library provide developers with rich functionality in the FunC environment. From tuple operations to slice handling, from persistent storage to random number generation, these primitives provide a solid foundation for writing smart contracts. With a deep understanding and flexible application of these primitives, developers can build efficient and reliable smart contracts, thus promoting the development of the FunC ecosystem.
In the future, as the FunC standard library continues to expand and improve, we look forward to seeing more innovative applications and solutions emerge on the FunC platform. At the same time, developers should also pay attention to the latest developments in the FunC community to keep up with the latest features and best practices of the standard library.
In summary, the FunC standard library is a powerful tool that provides rich functionality and flexibility for FunC application development. By deeply understanding and utilizing these primitives, developers can fully leverage the potential of the FunC platform to build smart contracts with practical application value.