docs/book/src/reference/compiler_intrinsics.md
The Sway compiler supports a list of intrinsics that perform various low level operations that are useful for building libraries. Compiler intrinsics should rarely be used but are preferred over asm blocks because they are type-checked and are safer overall. Below is a list of all available compiler intrinsics:
__size_of_val<T>(val: T) -> u64
Description: Return the size of type T in bytes.
Constraints: None.
__size_of<T>() -> u64
Description: Return the size of type T in bytes.
Constraints: None.
__size_of_str_array<T>() -> u64
Description: Return the size of type T in bytes. This intrinsic differs from __size_of in the case of "string arrays" where the actual length in bytes of the string is returned without padding the byte size to the next word alignment. When T is not a "string array" 0 is returned.
Constraints: None.
__assert_is_str_array<T>()
Description: Throws a compile error if type T is not a "string array".
Constraints: None.
__to_str_array(s: str) -> str[N]
Description: Converts a "string slice" to "string array" at compile time. Parameter "s" must be a string literal.
Constraints: None.
__is_reference_type<T>() -> bool
Description: Returns true if T is a reference type and false otherwise.
Constraints: None.
__is_str_array<T>() -> bool
Description: Returns true if T is a string array and false otherwise.
Constraints: None.
__eq<T>(lhs: T, rhs: T) -> bool
Description: Returns whether lhs and rhs are equal.
Constraints: T is bool, u8, u16, u32, u64, u256, b256 or raw_ptr.
__gt<T>(lhs: T, rhs: T) -> bool
Description: Returns whether lhs is greater than rhs.
Constraints: T is u8, u16, u32, u64, u256, b256.
__lt<T>(lhs: T, rhs: T) -> bool
Description: Returns whether lhs is less than rhs.
Constraints: T is u8, u16, u32, u64, u256, b256.
__gtf<T>(index: u64, tx_field_id: u64) -> T
Description: Returns transaction field with ID tx_field_id at index index, if applicable. This is a wrapper around FuelVM's gtf instruction. The resulting field is cast to T.
Constraints: None.
__addr_of<T>(val: T) -> raw_ptr
Description: Returns the address in memory where val is stored.
Constraints: None.
Without dynamic_storage experimental feature enabled
__state_load_word(key: b256) -> u64
Description: Reads and returns a single word from storage at key key. If the storage slot at key key is not set, zero is returned.
Constraints: None.
With dynamic_storage experimental feature enabled
__state_load_word(key: b256, offset: u64) -> u64
Description: Reads and returns a single word from storage at key key and offset offset. If the storage slot at key key is not set, zero is returned.
Constraints: offset must be a valid word offset inside of the storage slot boundaries. E.g., if the storage slot contains four words, the lowest offset is zero, and the highest is three.
__state_load_quad(key: b256, ptr: raw_ptr, slots: u64) -> bool
Description: Reads slots number of slots (b256 each) from storage starting at key key and stores them in memory starting at address ptr. Returns a Boolean describing whether all the storage slots were previously set.
Constraints: None.
__state_store_word(key: b256, val: u64) -> bool
Description: Stores a single word val into storage at key key. Returns a Boolean describing whether the store slot was previously set.
Constraints: None.
__state_store_quad(key: b256, ptr: raw_ptr, slots: u64) -> bool
Description: Stores slots number of slots (b256 each) starting at address ptr in memory into storage starting at key key. Returns a Boolean describing whether the first storage slot was previously set.
Constraints: None.
__log<T>(val: T) where T: AbiEncode
Description: Logs value val.
Constraints:
T must implement AbiEncode__add<T>(lhs: T, rhs: T) -> T
Description: Adds lhs and rhs and returns the result.
Constraints: T is an integer type, i.e. u8, u16, u32, u64, u256.
__sub<T>(lhs: T, rhs: T) -> T
Description: Subtracts rhs from lhs.
Constraints: T is an integer type, i.e. u8, u16, u32, u64, u256.
__mul<T>(lhs: T, rhs: T) -> T
Description: Multiplies lhs by rhs.
Constraints: T is an integer type, i.e. u8, u16, u32, u64, u256.
__div<T>(lhs: T, rhs: T) -> T
Description: Divides lhs by rhs.
Constraints: T is an integer type, i.e. u8, u16, u32, u64, u256.
__and<T>(lhs: T, rhs: T) -> T
Description: Bitwise AND lhs and rhs.
Constraints: T is an integer type, i.e. u8, u16, u32, u64, u256, b256.
__or<T>(lhs: T, rhs: T) -> T
Description: Bitwise OR lhs and rhs.
Constraints: T is an integer type, i.e. u8, u16, u32, u64, u256, b256.
__xor<T>(lhs: T, rhs: T) -> T
Description: Bitwise XOR lhs and rhs.
Constraints: T is an integer type, i.e. u8, u16, u32, u64, u256, b256.
__mod<T>(lhs: T, rhs: T) -> T
Description: Modulo of lhs by rhs.
Constraints: T is an integer type, i.e. u8, u16, u32, u64, u256.
__rsh<T>(lhs: T, rhs: u64) -> T
Description: Logical right shift of lhs by rhs.
Constraints: T is an integer type, i.e. u8, u16, u32, u64, u256, b256.
__lsh<T>(lhs: T, rhs: u64) -> T
Description: Logical left shift of lhs by rhs.
Constraints: T is an integer type, i.e. u8, u16, u32, u64, u256, b256.
__revert(code: u64)
Description: Reverts with error code code.
Constraints: None.
__ptr_add(ptr: raw_ptr, offset: u64)
Description: Adds offset to the raw value of pointer ptr.
Constraints: None.
__ptr_sub(ptr: raw_ptr, offset: u64)
Description: Subtracts offset to the raw value of pointer ptr.
Constraints: None.
__smo<T>(recipient: b256, data: T, coins: u64)
Description: Sends a message data of arbitrary type T and coins amount of the base asset to address recipient.
Constraints: None.
__not(op: T) -> T
Description: Bitwise NOT of op
Constraints: T is an integer type, i.e. u8, u16, u32, u64, u256, b256.
__jmp_mem()
Description: Jumps to MEM[$hp].
Constraints: None.
__slice<T>(item: &[T; N], start: u64, end: u64) -> &[T]
__slice<T>(item: &[T], start: u64, end: u64) -> &[T]
__slice<T>(item: &mut [T; N], start: u64, end: u64) -> &mut [T]
__slice<T>(item: &mut [T], start: u64, end: u64) -> &mut [T]
Description: Slices an array or another slice.
This intrinsic returns a reference to a slice containing the range of elements inside item.
The mutability of reference is defined by the first parameter mutability.
Runtime bound checks are not generated, and must be done manually when and where appropriated. Compile time bound checks are done when possible.
Constraints:
item is an array or a slice;start is a literal, it must be smaller than item length;end is a literal, it must be smaller than or equal to item length;end must be greater than or equal to start__elem_at<T>(item: &[T; N], index: u64) -> &T
__elem_at<T>(item: &[T], index: u64) -> &T
__elem_at<T>(item: &mut [T; N], index: u64) -> &mut T
__elem_at<T>(item: &mut [T], index: u64) -> &mut T
Description: Returns a reference to the indexed element. The mutability of reference is defined by the first parameter mutability.
Runtime bound checks are not generated, and must be done manually when and where appropriated. Compile time bound checks are done when possible.
Constraints:
item is a reference to an array or a reference to a slice;index is a literal, it must be smaller than item length;__dbg<T>(value: T) -> T where T: Debug
Description: Automatically calls the Debug trait on the passed value, with file, line and column information. The passed value is returned without any modification, allowing __dbg(...) to be used inside of any expression.
The code generated by this intrinsic function varies with the compilation mode. For example:
forc build <- will print everything as expected
forc build --release <- nothing will be printed
To enable code generation even on Release builds, the flag force-dbg-in-release needs to be enabled inside forc.toml.
Example:
[project]
authors = ["Fuel Labs <[email protected]>"]
license = "Apache-2.0"
entry = "main.sw"
name = "some-project"
force-dbg-in-release = true
It is strongly suggested to always remove this flag before publishing binaries as it will not have any effect when running on real nodes and it only increases gas usage.
Constraints:
T must implement Debug__transmute<A, B>(src: A) -> B
Description: Reinterprets the bits of a value of one type as another type.
Constraints: A and B must have the exactly same size.
__runtime_mem_id<T>() -> u64
__encoding_mem_id<T>() -> u64
Description: Returns an opaque number that identifies the memory representation of a type. No information is conveyed by this number and should only be compared for equality.
This number is not guaranteed to be stable on different compiler versions.
__runtime_mem_id represents how the type is represented inside the VM.
__encoding_mem_id represents how the type is encoded. It returns 0 when a type does not have encoding representation.
Constraints: None
__alloc<T>(count: u64) -> raw_ptr
Description: Allocate count contiguous elements of T on the heap and return a pointer to the newly allocated memory.
Constraints None