term.h

Include dependency graph for term.h:

This graph shows which files directly or indirectly include term.h:

term manipulation functions

This header implements term manipulation functions.

Defines

COMPACT_LITERAL 0

COMPACT_INTEGER 1

COMPACT_ATOM 2

COMPACT_XREG 3

COMPACT_YREG 4

COMPACT_LABEL 5

COMPACT_EXTENDED 7

COMPACT_LARGE_LITERAL 8

COMPACT_LARGE_INTEGER 9

COMPACT_LARGE_ATOM 10

COMPACT_LARGE_XREG 11

COMPACT_LARGE_YREG 12

COMPACT_EXTENDED_LIST 0x17

COMPACT_EXTENDED_FP_REGISTER 0x27

COMPACT_EXTENDED_ALLOCATION_LIST 0x37

COMPACT_EXTENDED_LITERAL 0x47

COMPACT_EXTENDED_TYPED_REGISTER 0x57

COMPACT_EXTENDED_ALLOCATOR_LIST_TAG_WORDS 0

COMPACT_EXTENDED_ALLOCATOR_LIST_TAG_FLOATS 1

COMPACT_EXTENDED_ALLOCATOR_LIST_TAG_FUNS 2

COMPACT_LARGE_IMM_MASK 0x18

COMPACT_11BITS_VALUE 0x8

COMPACT_NBITS_VALUE 0x18

TERM_PRIMARY_MASK 0x3

TERM_PRIMARY_CP 0x0

TERM_PRIMARY_LIST 0x1

TERM_PRIMARY_BOXED 0x2

TERM_PRIMARY_IMMED 0x3

TERM_BOXED_VALUE_TAG _Pragma("TERM_BOXED_VALUE_TAG is deprecated, use TERM_PRIMARY_BOXED instead") TERM_PRIMARY_BOXED

TERM_IMMED_TAG_MASK 0xF

TERM_PID_TAG 0x3

TERM_PORT_TAG 0x7

TERM_INTEGER_TAG 0xF

TERM_IMMED2_TAG 0xB

TERM_BOXED_TAG_MASK 0x3F

TERM_BOXED_TUPLE 0x0

TERM_BOXED_BIN_MATCH_STATE 0x4

TERM_BOXED_POSITIVE_INTEGER 0x8

TERM_BOXED_NEGATIVE_INTEGER (TERM_BOXED_POSITIVE_INTEGER | TERM_BOXED_INTEGER_SIGN_BIT)

TERM_BOXED_REF 0x10

TERM_BOXED_FUN 0x14

TERM_BOXED_FLOAT 0x18

TERM_BOXED_REFC_BINARY 0x20

TERM_BOXED_HEAP_BINARY 0x24

TERM_BOXED_SUB_BINARY 0x28

TERM_BOXED_MAP 0x2C

TERM_BOXED_EXTERNAL_THING 0x30

TERM_BOXED_EXTERNAL_PID 0x30

TERM_BOXED_EXTERNAL_PORT 0x34

TERM_BOXED_EXTERNAL_REF 0x38

TERM_BOXED_INTEGER_SIGN_BIT_POS 2

TERM_BOXED_INTEGER_SIGN_BIT (1 << TERM_BOXED_INTEGER_SIGN_BIT_POS)

TERM_IMMED2_TAG_MASK 0x3F

TERM_IMMED2_TAG_SIZE 6

TERM_IMMED2_ATOM 0xB

TERM_IMMED2_CATCH 0x1B

TERM_NIL 0x3B

TERM_UNUSED 0x2B

TERM_RESERVED_MARKER(x) ((x << 6) | TERM_UNUSED)

TERM_BOXED_REFC_BINARY_SIZE 6

TERM_BOXED_BIN_MATCH_STATE_SIZE 4

TERM_BOXED_SUB_BINARY_SIZE 4

TERM_BOXED_RESOURCE_SIZE TERM_BOXED_REFC_BINARY_SIZE 

REFC_BINARY_MIN 32

SUB_BINARY_MIN 8

TERM_MAX_LOCAL_PROCESS_ID ((1 << 28) - 1)

BINARY_HEADER_SIZE 2

FUNCTION_REFERENCE_SIZE 4

BOXED_INT_SIZE (BOXED_TERMS_REQUIRED_FOR_INT + 1)

BOXED_INT64_SIZE (BOXED_TERMS_REQUIRED_FOR_INT64 + 1)

BOXED_FUN_SIZE 3

FLOAT_SIZE (sizeof(float_term_t) / sizeof(term) + 1)

REF_SIZE ((int) ((sizeof(uint64_t) / sizeof(term)) + 1))

EXTERNAL_PID_SIZE 5

EXTERNAL_PORT_SIZE EXTERNAL_PID_SIZE 

EXTERNAL_REF_SIZE(words) (3 + words)

TUPLE_SIZE(elems) ((int) (elems + 1))

CONS_SIZE 2

REFC_BINARY_CONS_OFFSET 4

LIST_SIZE(num_elements, element_size) ((num_elements) * ((element_size) + CONS_SIZE))

TERM_STRING_SIZE(length) (2 * (length))

TERM_MAP_SIZE(num_elements) (3 + 2 * (num_elements))

TERM_MAP_SHARED_SIZE(num_elements) (2 + (num_elements))

LIST_HEAD_INDEX 1

LIST_TAIL_INDEX 0

TERM_BINARY_SIZE_IS_HEAP(size) ((size) < REFC_BINARY_MIN)

TERM_BINARY_DATA_SIZE_IN_TERMS(size) (TERM_BINARY_SIZE_IS_HEAP(size) ? (((size) + 4 - 1) >> 2) + 1 : TERM_BOXED_REFC_BINARY_SIZE)

TERM_BINARY_HEAP_SIZE(size) (TERM_BINARY_DATA_SIZE_IN_TERMS(size) + BINARY_HEADER_SIZE)

BOXED_BIGINT_HEAP_SIZE(term_size) ((term_size) + 1)

Calculate total heap allocation size for a bigint including header.

See also

term_bigint_size_requirements() which provides the term_size parameter

Parameters:

term_size – Data size in terms (from term_bigint_size_requirements())

Returns:

Total heap size needed including 1 term for boxed header

TERM_DEBUG_ASSERT(...)

TERM_FROM_ATOM_INDEX(atom_index) ((atom_index << TERM_IMMED2_TAG_SIZE) | TERM_IMMED2_ATOM)

REF_AS_CSTRING_LEN 70

PID_AS_CSTRING_LEN 32

PORT_AS_CSTRING_LEN 37

TERM_MAP_NOT_FOUND -1

TERM_MAP_MEMORY_ALLOC_FAIL -2

Typedefs

typedef struct PrinterFun PrinterFun

typedef int (*printer_function_t)(PrinterFun *fun, const char *fmt, ...)

typedef struct BinaryPosLen BinaryPosLen

Enums

enum RefcBinaryFlags

Values:

enumerator RefcNoFlags = 0

enumerator RefcBinaryIsConst

enum TermCompareOpts

Values:

enumerator TermCompareNoOpts = 0

enumerator TermCompareExact = 1

enum TermCompareResult

Values:

enumerator TermCompareMemoryAllocFail = 0

enumerator TermEquals = 1

enumerator TermLessThan = 2

enumerator TermGreaterThan = 4

enum term_integer_sign_t

Values:

enumerator TermPositiveInteger = 0

enumerator TermNegativeInteger = (1 << 2)

Functions

TermCompareResult term_compare(term t, term other, TermCompareOpts opts, GlobalContext *global)

Compares two terms.

Tells if first term is >, < or == to the second term.

Parameters:

t – the first term.
other – the second term.
opts – a value of 1 will compare exact equality, 0 for less strict equality.
global – the global context.

Returns:

any of TermEquals, TermLessThan, TermGreaterThan or TermCompareMemoryAllocFail error.

term term_alloc_refc_binary(size_t size, bool is_const, Heap *heap, GlobalContext *glb)

Create a reference-counted binary on the heap.

This function will create a reference-counted binary on the heap. If the data supplied is “const” (e.g., read from a literal in a BEAM file), then the returned term will point directly to the supplied data, and will not technically be reference-counted. Otherwise, a block of memory will be allocated to contain a copy of the data, in addition to a reference counter, so that the block can be free’d when no other terms reference the created object. (The reference count will be initialized to 1). If the data is non-NULL, it will be copied into the newly allocated block of memory.

Parameters:

size – the size (in bytes) of the data to allocate
is_const – designates whether the data pointed to is “const”, such as a term literal
heap – the heap to allocate the binary in
glb – the global context as refc binaries are global

Returns:

a term (reference) pointing to the newly allocated binary in the process heap or term_invalid_term() if there isn’t enough memory to allocate the refc buffer.

term term_alloc_sub_binary(term binary, size_t offset, size_t len, Heap *heap)

Create a sub-binary.

This function will create a sub-binary on the heap, using the supplied binary, offset into the binary, and length of the sub-binary. This function assumes the length of the referenced binary is greater or equal to offset + len.

Parameters:

binary – the referenced binary
offset – the offset into the referenced binary to start the sub-binary
len – the length (in bytes) of the sub-binary
heap – the heap to allocate the binary in

Returns:

a term (reference) pointing to the newly allocated sub-binary in the process heap.

static inline term *term_to_term_ptr(term t)

Gets a pointer to a term stored on the heap.

Casts a term to a term * that points to a value stored on the heap. Be aware: terms are assumed to be immutable.

Parameters:

t – the term that will be casted, it must be valid.

Returns:

a pointer to a term.

static inline const term *term_to_const_term_ptr(term t)

Gets a const pointer to a term stored on the heap.

Casts a term to a const term * that points to a value stored on the heap.

Parameters:

t – the term that will be casted, it must be valid.

Returns:

a const pointer to a term.

static inline bool term_is_atom(term t)

Checks if a term is an atom.

Returns true if a term is an atom, otherwise false.

Parameters:

t – the term that will be checked.

Returns:

true if check succeeds, false otherwise.

static inline bool term_is_invalid_term(term t)

Check if a term is an invalid term.

Returns true if a term is an invalid term, otherwise false is returned.

Parameters:

t – the term that will be checked.

Returns:

true if check succeeds, false otherwise.

static inline bool term_is_nil(term t)

Checks if a term is nil.

Returns true if a term is nil, otherwise false.

Parameters:

t – the term that will be checked.

Returns:

true if check succeeds, false otherwise.

static inline bool term_is_nonempty_list(term t)

Checks if a term is a non empty list.

Returns true if a term is a non empty list (cons), otherwise false.

Parameters:

t – the term that will be checked.

Returns:

true if check succeeds, false otherwise.

static inline bool term_is_list(term t)

Checks if a term is a list.

Returns true if a term is a list (cons) or an empty list (nil term), otherwise false.

Parameters:

t – the term that will be checked.

Returns:

true if check succeeds, false otherwise.

static inline bool term_is_boxed(term t)

Checks if a term is a boxed value.

Returns true if a term is a boxed value stored on the heap, such as a tuple, otherwise false.

Parameters:

t – the term that will be checked.

Returns:

true if check succeeds, false otherwise.

static inline size_t term_get_size_from_boxed_header(term header)

Returns size of a boxed term from its header.

Returns the size that is stored in boxed term header most significant bits for variable size boxed terms.

Parameters:

header – the boxed term header.

Returns:

the size of the boxed term that follows the header. 0 is returned if the boxed term is just the header.

static inline size_t term_boxed_size(term t)

Returns size of a boxed term.

Returns the size of a boxed term in term units.

Parameters:

t – the boxed term.

Returns:

size of given term.

static inline bool term_is_binary(term t)

Checks if a term is a binary.

Returns true if a term is a binary stored on the heap, otherwise false.

Parameters:

t – the term that will be checked.

Returns:

true if check succeeds, false otherwise.

static inline bool term_is_refc_binary(term t)

Checks if a term is a refc binary.

Returns true if a term is a ref-counted binary, otherwise false.

Parameters:

t – the term that will be checked.

Returns:

true if check succeeds, false otherwise.

static inline bool term_is_heap_binary(term t)

Checks if a term is a heap binary.

Returns true if a term is a binary stored on the heap, otherwise false.

Parameters:

t – the term that will be checked.

Returns:

true if check succeeds, false otherwise.

static inline bool term_refc_binary_is_const(term t)

static inline bool term_is_sub_binary(term t)

Checks if a term is a sub-binary.

Returns true if a term is a sub-binary; false, otherwise.

Parameters:

t – the term that will be checked.

Returns:

true if check succeeds; false, otherwise.

static inline bool term_is_int(term t)

Check if term is an integer within platform-specific avm_int_t range.

Tests whether a term represents an integer stored directly in the term word without boxing. Returns true only for integers that fit within the platform’s unboxed integer range:

32-bit builds: [-2^28, 2^28 - 1] (28-bit signed)
64-bit builds: [-2^60, 2^60 - 1] (60-bit signed)

Integers outside these ranges are stored as boxed integers on the heap and will return false from this function.

See also

term_is_boxed_integer() for boxed integer checking

See also

term_is_any_integer() for checking all integer representations

See also

term_to_int() for extracting the integer value

Note

Returns false for boxed integers and big integers, even if their values would fit in avm_int_t full range

Note

Values passing this check can be safely converted to avm_int_t or size_t using term_to_int()

Note

Terms for which this functions returns true are not moved during garbage collection

Warning

Values passing this check may NOT fit in int on platforms where int is smaller than avm_int_t

Parameters:

t – Term to check

Returns:

true if term is an unboxed integer, false otherwise

static inline bool term_is_integer(term t)

Check if term is an integer within platform-specific avm_int_t range.

Deprecated:: Use term_is_int() instead. This function will raise a warning in the future and will eventually be removed.

See also

term_is_int() for the replacement function

Parameters:

t – Term to check

Returns:

true if term is an unboxed integer, false otherwise

static inline bool term_is_uint8(term t)

Checks if a term is a uint8_t.

Returns true if a term is an integer value in the [0, 255] range, otherwise false.

Parameters:

t – the term that will be checked.

Returns:

true if check succeeds, false otherwise.

static inline bool term_is_boxed_integer(term t)

static inline bool term_is_any_integer(term t)

static inline bool term_is_catch_label(term t)

static inline bool term_is_local_pid(term t)

Checks if a term is a local pid.

Returns true if a term is a process id, otherwise false.

Parameters:

t – the term that will be checked.

Returns:

true if check succeeds, false otherwise.

static inline bool term_is_external_pid(term t)

Checks if a term is an external pid.

Returns true if a term is an external process id, otherwise false.

Parameters:

t – the term that will be checked.

Returns:

true if check succeeds, false otherwise.

static inline bool term_is_external(term t)

Checks if a term is an external thing.

Returns true if a term is an external thing, otherwise false.

Parameters:

t – the term that will be checked.

Returns:

true if check succeeds, false otherwise.

static inline bool term_is_pid(term t)

Checks if a term is a pid.

Returns true if a term is a process id, otherwise false.

Parameters:

t – the term that will be checked.

Returns:

true if check succeeds, false otherwise.

static inline bool term_is_local_port(term t)

Checks if a term is a local port.

Returns true if a term is a local port, otherwise false.

Parameters:

t – the term that will be checked.

Returns:

true if check succeeds, false otherwise.

static inline bool term_is_external_port(term t)

Checks if a term is an external port.

Returns true if a term is an external port, otherwise false.

Parameters:

t – the term that will be checked.

Returns:

true if check succeeds, false otherwise.

static inline bool term_is_port(term t)

Checks if a term is a port.

Returns true if a term is a port, otherwise false.

Parameters:

t – the term that will be checked.

Returns:

true if check succeeds, false otherwise.

static inline bool term_is_local_pid_or_port(term t)

Checks if a term is a local port or a local pid.

Returns true if a term is a local port or a local process id, otherwise false.

Parameters:

t – the term that will be checked.

Returns:

true if check succeeds, false otherwise.

static inline bool term_is_tuple(term t)

Checks if a term is a tuple.

Returns true if a term is a tuple, otherwise false.

Parameters:

t – the term that will be checked.

Returns:

true if check succeeds, false otherwise.

static inline bool term_is_local_reference(term t)

Checks if a term is a local reference.

Returns true if a term is a local reference, otherwise false.

Parameters:

t – the term that will be checked.

Returns:

true if check succeeds, false otherwise.

static inline bool term_is_external_reference(term t)

Checks if a term is an external reference.

Returns true if a term is a local reference, otherwise false.

Parameters:

t – the term that will be checked.

Returns:

true if check succeeds, false otherwise.

static inline bool term_is_reference(term t)

Checks if a term is a reference.

Returns true if a term is a reference, otherwise false.

Parameters:

t – the term that will be checked.

Returns:

true if check succeeds, false otherwise.

static inline bool term_is_function(term t)

Checks if a term is a fun.

Returns true if a term is a fun, otherwise false.

Deprecated:: renamed to term_is_fun.

Parameters:

t – the term that will be checked.

Returns:

true if check succeeds, false otherwise.

static inline bool term_is_fun(term t)

Checks if a term is a fun.

Returns true if a term is a fun, otherwise false.

Parameters:

t – the term that will be checked.

Returns:

true if check succeeds, false otherwise.

static inline bool term_is_external_fun(term t)

Checks if a term is an external fun.

Returns true if a term is an external fun such as “fun m:f/a”, otherwise false.

Parameters:

t – the term that will be checked.

Returns:

true if check succeeds, false otherwise.

static inline bool term_is_cp(term t)

Checks if a term is a saved CP.

Returns true if a term is a saved continuation pointer, otherwise false.

Parameters:

t – the term that will be checked.

Returns:

true if check succeeds, false otherwise.

static inline term term_invalid_term(void)

Gets invalid term.

Returns always an invalid term.

Returns:: invalid term.

static inline term term_nil(void)

Gets nil value.

Returns always the nil value.

Returns:: nil value term.

static inline atom_index_t term_to_atom_index(term t)

Gets global atom table index.

Returns atom table index for given atom term.

Parameters:

t – the term that will be converted to atom table index. t must be a valid atom term.

Returns:

a global atom table index.

static inline term term_from_atom_index(atom_index_t atom_index)

Term from global atom table index.

Returns a term from the given global atom table index.

Parameters:

atom_index – global atoms table index.

Returns:

a term that encapsulates the atom.

static inline uint8_t term_to_uint8(term t)

Term to uint8.

Returns an uint8 for a given term. No overflow check is executed.

Parameters:

t – the term that will be converted to uint8.

Returns:

an uint8_t value.

static inline int32_t term_to_int32(term t)

Term to int32.

Returns an int32 for a given term. No overflow check is executed.

Parameters:

t – the term that will be converted to int32, term type is checked.

Returns:

a int32 value.

static inline avm_int_t term_to_int(term t)

Extract avm_int_t value from unboxed integer term.

Extracts the avm_int_t value from a term that contains an unboxed integer. An unboxed integer is an integer value stored directly within the term itself, not as a separate allocation on the heap.

See also

term_is_int() to validate term before extraction

See also

term_unbox_int() for extracting boxed integers

See also

term_maybe_unbox_int() for extracting from either unboxed or boxed integers

Note

This function performs no type checking - validation must be done by caller using term_is_int()

Note

Only extracts from unboxed integers (28-bit on 32-bit builds, 60-bit on 64-bit builds)

Note

Safe conversions: size_t s = term_to_int(t) is always valid

Warning

Undefined behavior if called on non-integer or boxed integer terms

Warning

Unsafe conversions on 64-bit builds: int or int32_t may overflow since avm_int_t can hold 60-bit values

Parameters:

t – Term containing unboxed integer

Returns:

The extracted avm_int_t value

Pre:

term_is_int(t) must be true

static inline int term_to_catch_label_and_module(term t, int *module_index)

static inline int32_t term_to_local_process_id(term t)

Gets process table index for a local pid or port.

Returns local process table index for given atom term.

Parameters:

t – the term that will be converted to local process table index, term type is checked.

Returns:

a local process table index.

static inline term term_from_int4(int8_t value)

Term from int4.

Returns a term for a given 4 bits integer value.

Parameters:

value – the value that will be converted to a term.

Returns:

a term that encapsulates the integer value.

static inline term term_from_int11(int16_t value)

Term from int11.

Returns a term for a given 11 bits integer value.

Parameters:

value – the value that will be converted to a term.

Returns:

a term that encapsulates the integer value.

static inline term term_from_int32(int32_t value)

Term from int32.

Returns a term for a given 32 bits integer value.

Parameters:

value – the value that will be converted to a term.

Returns:

a term that encapsulates the integer value.

static inline term term_from_int64(int64_t value)

static inline term term_from_int(avm_int_t value)

static inline bool term_is_non_neg_int(term t)

Check if term is a non-negative unboxed integer.

See also

term_is_int() for unboxed integer details

Parameters:

t – Term to check

Returns:

true if term is an unboxed integer >= 0, false otherwise

static inline bool term_is_pos_int(term t)

Check if term is a positive (non-zero) unboxed integer.

See also

term_is_int() for unboxed integer details

Parameters:

t – Term to check

Returns:

true if term is an unboxed integer > 0, false otherwise

static inline bool term_is_neg_int(term t)

Check if term is a negative unboxed integer.

See also

term_is_int() for unboxed integer details

Parameters:

t – Term to check

Returns:

true if term is an unboxed integer < 0, false otherwise

static inline bool term_is_pos_boxed_integer(term t)

static inline bool term_is_neg_boxed_integer(term t)

static inline term_integer_sign_t term_boxed_integer_sign(term t)

static inline bool term_is_any_non_neg_integer(term t)

static inline bool term_is_any_pos_integer(term t)

static inline bool term_is_any_neg_integer(term t)

static inline avm_int_t term_unbox_int(term boxed_int)

static inline avm_int64_t term_unbox_int64(term boxed_long)

static inline avm_int_t term_maybe_unbox_int(term maybe_boxed_int)

static inline avm_int64_t term_maybe_unbox_int64(term maybe_boxed_int)

static inline term_integer_sign_t term_integer_sign_from_int(avm_int_t value)

static inline term term_make_boxed_int(avm_int_t value, Heap *heap)

static inline term term_make_boxed_int64(avm_int64_t large_int64, Heap *heap)

static inline term term_make_maybe_boxed_int64(avm_int64_t value, Heap *heap)

static inline size_t term_boxed_integer_size(avm_int64_t value)

static inline term term_create_uninitialized_bigint(size_t n, term_integer_sign_t sign, Heap *heap)

Create an uninitialized bigint term with allocated storage.

Allocates heap space for a multi-precision integer term and sets up the boxed header with size and sign information. The digit data area is left uninitialized and must be filled using term_initialize_bigint().

See also

term_initialize_bigint() to fill the allocated data area

See also

term_bigint_size_requirements() to calculate required size

See also

BOXED_BIGINT_HEAP_SIZE() to calculate total heap allocation including header

Note

The size n is in terms, not intn_digit_t digits

Note

Use term_bigint_size_requirements() to calculate appropriate n value

Warning

When ensuring heap space, use BOXED_BIGINT_HEAP_SIZE(n) to include the header term in the allocation size

Parameters:

n – Size of data area in terms (not digits), from term_bigint_size_requirements()
sign – Sign of the integer (TERM_INTEGER_POSITIVE or TERM_INTEGER_NEGATIVE)
heap – Heap to allocate from

Returns:

Newly created uninitialized bigint term

Pre:

n must be > BOXED_TERMS_REQUIRED_FOR_INT64 to ensure bigint distinction

Pre:

heap must have at least (1 + n) terms of free space

Post:

Allocates 1 header term + n data terms on the heap

Post:

Header contains size and sign information

Post:

Data area is uninitialized and must be filled before use

static inline void term_initialize_bigint(term t, const intn_digit_t *bigint, size_t bigint_len, size_t uninitialized_size)

Initialize multi-precision integer data in a pre-allocated term.

Copies multi-precision integer digits into an already allocated boxed term, zero-extending to fill the entire allocated space. This function is used after creating an uninitialized bigint term to populate it with actual data.

See also

term_create_uninitialized_bigint() to allocate the term before initialization

See also

intn_copy() which performs the actual copy and zero-extension

Note

This function does not set the sign - that should be done when creating the term

Note

The destination buffer size (uninitialized_size) is typically rounded up for alignment

Parameters:

t – Uninitialized bigint term (created with term_create_uninitialized_bigint())
bigint – Source digit array to copy
bigint_len – Number of digits in source array
uninitialized_size – Total size of destination buffer in digits

Pre:

t must be a valid uninitialized bigint term

Pre:

bigint != NULL

Pre:

uninitialized_size must match the size allocated for the term

Post:

Copies bigint_len digits from source to term

Post:

Zero-fills remaining space from bigint_len to uninitialized_size

static inline void term_bigint_size_requirements(size_t n, size_t *intn_data_size, size_t *rounded_num_len)

Calculate term allocation size for multi-precision integer.

Converts the number of intn_digit_t digits needed for a bigint into the corresponding term allocation size and rounded digit count. Handles platform differences between 32-bit systems (where term = intn_digit_t) and 64-bit systems (where term = 2 × intn_digit_t), including alignment requirements.

// Example usage:
size_t count = intn_count_digits(bigint, bigint_len);
size_t intn_data_size, rounded_res_len;
term_bigint_size_requirements(count, &intn_data_size, &rounded_res_len);

// Ensure heap has space for data + header
memory_ensure_free(ctx, BOXED_BIGINT_HEAP_SIZE(intn_data_size));

term t = term_create_uninitialized_bigint(intn_data_size, sign, heap);
term_initialize_bigint(t, bigint, count, rounded_res_len);

See also

BOXED_BIGINT_HEAP_SIZE() to include header in heap allocation

Note

Forces minimum size > BOXED_TERMS_REQUIRED_FOR_INT64 to distinguish bigints from regular boxed int64 values (which use two’s complement)

Note

Rounds up to 8-byte boundaries for alignment

Note

On 64-bit systems, 2 digits fit per term; on 32-bit systems, 1 digit per term

Warning

The returned intn_data_size does NOT include the boxed header term. Use BOXED_BIGINT_HEAP_SIZE(intn_data_size) when allocating heap space.

Parameters:

n – Number of non-zero intn_digit_t digits in the integer
intn_data_size – [out] Number of terms needed for storage (excludes header)
rounded_num_len – [out] Rounded number of digits for zero-padding

Pre:

n > 0

Pre:

intn_data_size != NULL

Pre:

rounded_num_len != NULL

Post:

*intn_data_size > BOXED_TERMS_REQUIRED_FOR_INT64 (ensures bigint distinction)

Post:

*rounded_num_len >= n (includes padding for alignment)

static inline bool term_is_bigint(term t)

Check if term is a multi-precision integer larger than int64_t.

Tests whether a term represents a boxed integer that requires multi-precision representation (i.e., larger than can fit in int64_t). These are integers that need more than INTN_INT64_LEN digits for their representation.

In the current implementation, a bigint is defined as a boxed integer with size greater than:

BOXED_TERMS_REQUIRED_FOR_INT64 on 32-bit systems
BOXED_TERMS_REQUIRED_FOR_INT on 64-bit systems

This effectively identifies integers that cannot be represented in the platform’s native integer types and require multi-precision arithmetic, while avoiding confusion with regular boxed int64_t values that still fit within standard integer ranges.

See also

term_to_bigint() to extract the multi-precision integer data

See also

term_is_boxed_integer() for checking any boxed integer

See also

term_is_any_integer() for checking all integer representations

Note

Returns false for integers that fit in int64_t, even if boxed

Note

This is the correct check before calling term_to_bigint()

Parameters:

t – Term to check

Returns:

true if term is a multi-precision integer, false otherwise

static inline void term_to_bigint(term t, const intn_digit_t *bigint[], size_t *bigint_len, intn_integer_sign_t *bigint_sign)

Extract multi-precision integer data from boxed term.

Extracts the raw multi-precision integer representation from a boxed integer term. This function provides direct access to the internal digit array without copying, returning a pointer to the data within the term structure.

See also

term_is_bigint() to check if term is a multi-precision integer

See also

term_boxed_integer_sign() to get the sign

Note

The digit array may not be normalized (may have leading zeros)

Note

Length is calculated as boxed_size * (sizeof(term) / sizeof(intn_digit_t))

Warning

Returned pointer is a borrowed reference into the term structure

Warning

Data becomes invalid if term is garbage collected or modified

Warning

Caller must not free the returned pointer

Parameters:

t – Boxed integer term to extract from
bigint – [out] Pointer to the digit array within the term (borrowed reference)
bigint_len – [out] Number of digits in the integer
bigint_sign – [out] Sign of the integer

Pre:

term_is_bigint(t) must be true

Pre:

bigint != NULL

Pre:

bigint_len != NULL

Pre:

bigint_sign != NULL

static inline term term_from_catch_label(unsigned int module_index, unsigned int label)

static inline term term_from_local_process_id(uint32_t local_process_id)

Term from local process id.

Returns a term for a given local process table index.

Parameters:

local_process_id – the local process table index that will be converted to a term.

Returns:

a term that encapsulates a PID.

static inline term term_port_from_local_process_id(uint32_t local_process_id)

Port term from local process id.

Returns a term for a given local process table index.

Parameters:

local_process_id – the local process table index that will be converted to a term.

Returns:

a term that encapsulates a PID.

static inline bool term_binary_size_is_heap_binary(size_t size)

Determine whether a binary should be a heap binary or not.

Returns true if a binary of the specified size should be allocated in the process heap (as opposed to being a refc binary)

Parameters:

size – the intended binary size

Returns:

true if the binary should be allocated in the process heap; false, otherwise.

static inline size_t term_binary_data_size_in_terms(size_t size)

The count of terms needed to store the given amount of bytes.

Returns the count of terms needed to store the given size in bytes.

Parameters:

size – the size in bytes

Returns:

the count of terms

static inline size_t term_binary_heap_size(size_t size)

The size (in terms) of a binary of size-many bytes in the heap.

Returns the number of terms needed in the heap to store a binary of a given size (in bytes)

Parameters:

size – the size of the binary (in bytes)

Returns:

the size (in terms) of a binary of size-many bytes in the heap

static inline unsigned long term_binary_size(term t)

Gets binary size.

Returns binary size for a given binary term.

Parameters:

t – a term pointing to binary data. Fails if t is not a binary term.

Returns:

binary size in bytes.

static inline struct RefcBinary *term_refc_binary_ptr(term refc_binary)

Get the pointer off heap refc binary.

Returns address

Returns:: offset (in words).

static inline const char *term_binary_data(term t)

Gets binary data.

Returns a pointer to stored binary data.

Parameters:

t – a term pointing to binary data. Fails if t is not a binary term.

Returns:

a const char * pointing to binary internal data.

static inline term term_create_uninitialized_binary(size_t size, Heap *heap, GlobalContext *glb)

Create an uninitialized binary.

Allocates a binary on the heap, and returns a term pointing to it. Note that the data in the binary is uninitialized and could contain any garbage. Make sure to initialize before use, if needed (e.g., via memset). The binary may be allocated as a refc if it is large enough.

Parameters:

size – size of binary data buffer.
heap – the heap to allocate the binary in
glb – the global context as refc binaries are global

Returns:

a term pointing to the boxed binary pointer or term_invalid_term() if there isn’t enough memory to allocate the refc buffer

static inline term term_from_literal_binary(const void *data, size_t size, Heap *heap, GlobalContext *glb)

Term from binary data.

Allocates a binary on the heap, and returns a term pointing to it.

Parameters:

data – binary data.
size – size of binary data buffer.
heap – the heap to allocate the binary in
glb – the global context as refc binaries are global

Returns:

a term pointing to the boxed binary pointer.

static inline size_t term_sub_binary_heap_size(term binary, size_t len)

Get the number of words in the heap to allocate for a sub-binary.

This function is used to compute the number of words needed on the heap to allocate for a sub-binary. This function is typically used in conjunction with term_maybe_create_sub_binary

Parameters:

binary – source binary
len – desired length of the sub-binary

Returns:

the number of words needed to allocate on the process heap for the desired sub-binary

static inline term term_maybe_create_sub_binary(term binary, size_t offset, size_t len, Heap *heap, GlobalContext *glb)

(Maybe) create a sub-binary — if not, create a heap binary.

Allocates a sub-binary if the source binary is reference-counted binary and if the length of the sub-binary is sufficiently large.

Parameters:

binary – source binary
offset – offset into the source binary marking the start of the sub-binary
len – desired length of the sub-binary
heap – the heap to allocate memory in
glb – the global context as refc binaries are global

Returns:

a term pointing to the boxed binary pointer.

static inline void term_set_refc_binary_data(term t, const void *data)

static inline term term_from_const_binary(const void *data, size_t size, Heap *heap, GlobalContext *glb)

static inline term term_create_empty_binary(size_t size, Heap *heap, GlobalContext *glb)

Create an empty binary. All bytes in the binary are initialized to 0x00.

Allocates a binary on the heap, and returns a term pointing to it.

Parameters:

size – size of binary data buffer.
heap – the heap to allocate memory in
glb – the global context as refc binaries are global

Returns:

a term pointing to the boxed binary pointer.

term term_reuse_binary(term src, size_t size, Heap *heap, GlobalContext *glb)

Reuse a binary. If the binary is a refc binary with a ref count of 1, try to reuse it. Otherwise, create a new binary and copy the data.

Try to reuse a binary and return a term pointing to it.

Parameters:

src – binary to reuse.
size – size of binary data buffer.
heap – the heap to allocate memory in
glb – the global context as refc binaries are global

Returns:

a term pointing to the boxed binary pointer.

static inline bool term_normalize_binary_pos_len(term binary, avm_int_t pos, avm_int_t len, BinaryPosLen *pos_len)

static inline bool term_is_nomatch_binary_pos_len(BinaryPosLen pos_len)

static inline BinaryPosLen term_nomatch_binary_pos_len(void)

static inline int term_bs_insert_binary(term t, int offset, term src, int n)

Insert an binary into a binary (using bit syntax).

Insert the data from the input binary, starting at the bit position starting in offset.

Parameters:

t – a term pointing to binary data. Fails if t is not a binary term.
offset – the bitwise offset in t at which to start writing the integer value
src – binary source to insert binary data into.
n – the number of low-order bits from value to write.

Returns:

0 on success; non-zero value if: t is not a binary term n is greater than the number of bits in an integer there is insufficient capacity in the binary to write these bits In general, none of these conditions should apply, if this function is being called in the context of generated bit syntax instructions.

static inline term term_from_ref_ticks(uint64_t ref_ticks, Heap *heap)

Get a ref term from ref ticks.

Parameters:

ref_ticks – an unique uint64 value that will be used to create ref term.
heap – the heap to allocate memory in

Returns:

a ref term created using given ref ticks.

static inline uint64_t term_to_ref_ticks(term rt)

static inline term term_make_external_process_id(term node, uint32_t process_id, uint32_t serial, uint32_t creation, Heap *heap)

Make an external pid term from node, process_id, serial and creation.

Parameters:

node – name of the node (atom)
process_id – process id on that node
serial – serial of process id on that node
creation – creation of that node
heap – the heap to allocate memory in

Returns:

an external heap term created using given parameters.

static inline term term_make_external_port_number(term node, uint64_t number, uint32_t creation, Heap *heap)

Get a port term from node, number and creation.

Parameters:

node – name of the node (atom)
number – port number on that node
creation – creation of that node
heap – the heap to allocate memory in

Returns:

an external heap term created using given parameters.

static inline term term_get_external_node(term t)

Get the name of a node for a given external thing.

Parameters:

term – external term

Returns:

the name of the node

static inline uint32_t term_get_external_node_creation(term t)

Get the creation for a given external thing.

Parameters:

term – external term

Returns:

the serial of the external pid

static inline uint32_t term_get_external_pid_process_id(term t)

Get the process id of an external pid.

Parameters:

term – external pid

Returns:

the process id of the external pid

static inline uint32_t term_get_external_pid_serial(term t)

Get the serial of an external pid.

Parameters:

term – external term

Returns:

the serial of the external pid

static inline uint64_t term_get_external_port_number(term t)

Get the port number of an external port.

Parameters:

term – external port

Returns:

the port number of the external port

static inline term term_make_external_reference(term node, uint16_t len, uint32_t *data, uint32_t creation, Heap *heap)

Make an external reference term from node, creation, number of words and words.

Parameters:

node – name of the node (atom)
len – number of words (1..5)
data – words
creation – creation of that node
heap – the heap to allocate memory in

Returns:

an external heap term created using given parameters.

static inline uint32_t term_get_external_reference_len(term t)

Get the number of words of an external reference.

Parameters:

term – external term

Returns:

the number of words of the external reference (from 1 to 5)

static inline const uint32_t *term_get_external_reference_words(term t)

Get the words of an external reference.

Parameters:

term – external term

Returns:

a pointer to (len) words of the external reference

static inline term term_alloc_tuple(uint32_t size, Heap *heap)

Allocates a tuple on a context heap.

Allocates an uninitialized tuple on the heap with given arity.

Parameters:

size – tuple arity (count of tuple elements).
heap – the heap to allocate memory in

Returns:

a term pointing on an empty tuple allocated on the heap.

static inline void term_put_tuple_element(term t, uint32_t elem_index, term put_value)

Replaces the content of a tuple element.

Destructively replaces the nth element of an existing tuple, it should be used only on newly allocated tuples.

Parameters:

t – the term pointing to the target tuple, fails if not a tuple.
elem_index – the index of the element that will be replaced.
put_value – the term that will be put on the nth tuple element.

static inline term term_get_tuple_element(term t, int elem_index)

Returns the nth tuple element.

Returns the nth element for a given tuple pointed by a term.

Parameters:

t – a term that points to a tuple, fails otherwise.
elem_index – index of the nth element that will be returned.

Returns:

nth tuple term.

static inline int term_get_tuple_arity(term t)

static inline term term_from_string(const uint8_t *data, uint16_t size, Heap *heap)

Allocates a new list using string data.

Returns a term that points to a list (cons) that will be created using a string.

Parameters:

data – a pointer to a string, it doesn’t need to be NULL terminated.
size – of the string/list that will be read and allocated.
heap – the heap to allocate memory in

Returns:

a term pointing to a list.

static inline term *term_get_list_ptr(term t)

Gets a term * pointing to a list.

Returns a term * pointer to a list (cons) from a given term.

Parameters:

t – a term that points to a valid cons.

Returns:

a term * pointing to the head of the first cell of a list.

static inline term term_list_from_list_ptr(term *list_elem)

Gets list term from pointer.

Return given list term from a list element pointer.

Parameters:

list_elem – a pointer to a list element.

Returns:

a list term

static inline term term_get_list_head(term t)

Gets list head.

Returns given list head term

Parameters:

t – a term pointing to a valid list (cons)

Returns:

list head term

static inline term term_get_list_tail(term t)

Gets list item tail.

Returns the tail, which is either a pointer to the next list item or nil, of the given list (that is not list tail).

Returns:: list item tail term.

static inline term *term_list_alloc(Heap *heap)

Allocate uninitialized memory for a list item.

Allocates a memory area that will be used to store a list item.

Parameters:

heap – the heap to allocate memory in

Returns:

a pointer to a newly allocated memory area.

static inline term term_list_init_prepend(term *list_elem, term head, term tail)

Prepends a term to an existing list.

Initializes a list item, set head to the given term and points tail to the given next item (that might be nil).

Parameters:

head – term, the encapsulated list item value.
tail – either nil or next list item.
list_elem – the memory area that will be initialized.

Returns:

a term pointing to the newly initialized list item.

static inline term term_list_prepend(term head, term tail, Heap *heap)

Prepends a term to an existing list.

Allocates a new list item, set head to the given term and points tail to the given next item (that might be nil).

Parameters:

head – term, the encapsulated list item value.
tail – either nil or next list item.
heap – the heap to allocate memory in

Returns:

a term pointing to the newly created list item.

static inline int term_list_length(term t, int *proper)

Returns list length.

Counts the number of list items

Returns:: number of list items

static inline bool term_is_float(term t)

static inline term term_from_float(avm_float_t f, Heap *heap)

static inline avm_float_t term_to_float(term t)

static inline bool term_is_number(term t)

void term_display(FILE *fd, term t, const Context *ctx)

Prints a term to stdout.

Print any term to the given file.

Parameters:

fd – the file where the term will be printed.
t – the term that will be printed.
ctx – the context.

int term_funprint(PrinterFun *pf, term t, const GlobalContext *global)

Prints a term using given printer fun.

Print any given term using a printer fun

Parameters:

pf – function that will handle printing.
t – the term that will be printed.
global – the GlobalContext.

Returns:

the number of printed characters.

int term_fprint(FILE *fd, term t, const GlobalContext *global)

Prints a term to the given file.

Print any given term to the given file.

Parameters:

fd – the file where the term will be printed.
t – the term that will be printed.
global – the GlobalContext.

Returns:

the number of printed characters.

int term_snprint(char *buf, size_t size, term t, const GlobalContext *global)

Write a term to a string as text.

Print any given term to the given buffer.

Parameters:

buf – the buffer where the term will be printed.
size – the buffer size.
t – the term that will be printed.
global – the GlobalContext.

Returns:

the number of printed characters.

avm_float_t term_conv_to_float(term t)

static inline bool term_is_string(term t)

Checks if a term is a string (i.e., a list of characters)

Returns true if a term is a proper (nil-terminated) list of characters or an empty list (nil term), otherwise 0.

Parameters:

t – the term that will be checked.

Returns:

true if check succeeds, false otherwise.

void term_get_function_mfa(term fun, term *m, term *f, term *a)

Gets function module name, name and arity.

Allows to retrieve partial information by passing NULL pointers.

Parameters:

fun – function term.
m – module name as an atom.
f – function name as an atom.
a – function arity as an integer.

static inline term term_make_function_reference(term m, term f, term a, Heap *heap)

static inline bool term_is_match_state(term t)

static inline term term_get_match_state_binary(term match_state)

static inline avm_int_t term_get_match_state_offset(term match_state)

static inline void term_set_match_state_offset(term match_state, avm_int_t offset)

static inline void term_match_state_save_offset(term match_state, int index)

static inline void term_match_state_save_start_offset(term match_state)

static inline void term_match_state_restore_start_offset(term match_state)

static inline void term_match_state_restore_offset(term match_state, int index)

static inline term term_alloc_bin_match_state(term binary_or_state, int slots, Heap *heap)

static inline void term_truncate_boxed(term boxed, size_t new_size, Heap *heap)

truncates last allocated boxed term to given size

This function can be used to shrink last allocated boxed term

Parameters:

boxed – the boxed term that will be shrinked (it must be the last allocated)
new_size – in terms
heap – the heap where the term has been allocated

static inline bool term_is_map(term t)

static inline size_t term_get_map_keys_offset(void)

static inline size_t term_get_map_value_offset(void)

static inline size_t term_map_size_in_terms_maybe_shared(size_t num_entries, bool is_shared)

static inline size_t term_map_size_in_terms(size_t num_entries)

static inline term term_alloc_map_maybe_shared(avm_uint_t size, term keys, Heap *heap)

static inline term term_alloc_map(avm_uint_t size, Heap *heap)

static inline term term_get_map_keys(term t)

static inline int term_get_map_size(term t)

static inline void term_set_map_assoc(term map, avm_uint_t pos, term key, term value)

static inline term term_get_map_key(term map, avm_uint_t pos)

static inline term term_get_map_value(term map, avm_uint_t pos)

static inline void term_set_map_value(term map, avm_uint_t pos, term value)

static inline int term_find_map_pos(term map, term key, GlobalContext *global)

term term_get_map_assoc(term map, term key, GlobalContext *glb)

static inline term term_get_map_assoc_default(term map, term key, term default_value, GlobalContext *glb)

static inline term term_get_sub_binary_ref(term t)

static inline term term_from_resource(void *resource, Heap *heap)

Create a resource on the heap.

This function creates a resource (obtained from enif_alloc_resource) on the heap which must have TERM_BOXED_RESOURCE_SIZE free terms.

This function does increment the reference counter as the resource is added to the heap’s mso list.

Parameters:

resource – resource obtained from enif_alloc_resource
heap – the heap to allocate the resource in

Returns:

a term pointing to the resource

Variables

const term empty_tuple: All empty tuples will reference this.

struct PrinterFun

#include <term.h>

Collaboration diagram for PrinterFun:

Public Members

printer_function_t print

struct BinaryPosLen

#include <term.h>

Public Members

avm_int_t pos

avm_int_t len