Built-in Functions

All built-in functions use lowercase snake_case names. Default parameter values (shown as = value) and keyword arguments (e.g., to_int(b, signed=True)) are supported on built-in functions. Every expression in the tables below is verified against the real interpreter.

Length & Allocation

len

len(x: bytes | list[T]) → int — Returns the byte count of a bytes buffer or the element count of a list.

zeros

zeros(n: int) → bytes — Returns a byte array of n zero bytes (0x00). Fails with BYTES_INVALID_ARGUMENT if n < 0.

fill

fill(value: int, n: int) → bytes — Returns a byte array of length n filled with the byte value value (0..255). Fails with BYTES_INVALID_ARGUMENT if out of range.

Structure Manipulation

concat

concat(parts: list[bytes]) → bytes — Joins a list of byte arrays in order. Fails with BYTES_SIZE_LIMIT if the result exceeds 16 MiB.

reverse

reverse(b: bytes) → bytes — Reverses the byte order of b (endianness swap).

blocks

blocks(b: bytes, size: int) → list[bytes] — Splits b into chunks of size bytes from the start; the final chunk may be shorter than size. Fails with BYTES_INVALID_ARGUMENT if size ≤ 0.

to_ints

to_ints(b: bytes) → list[int] — Converts each byte of b into an integer in 0..255.

from_ints

from_ints(xs: list[int]) → bytes — Packs a list of integers (0..255) into a byte array. Fails with BYTES_INVALID_ARGUMENT if any element is outside 0..255.

Bit Rotation

rol

rol(b: bytes, n: int) → bytes — Rotates the entire bit sequence of b left by n bits.

ror

ror(b: bytes, n: int) → bytes — Rotates the entire bit sequence of b right by n bits.

Comparison

ct_equals

ct_equals(a: bytes, b: bytes) → bool — Best-effort constant-time byte array equality check.

compare

compare(a: bytes, b: bytes) → int — Lexicographical comparison returning -1, 0, or 1.

Integer Conversion

to_int

to_int(b: bytes, endian: string = "big", signed: bool = False) → int — Interprets b as an integer (two's complement when signed=True; empty bytes yield 0).

to_bytes

to_bytes(n: int, length: int, endian: string = "big", signed: bool = False) → bytes — Encodes integer n into exactly length bytes. Fails with BYTES_INT_OVERFLOW if n does not fit.

String & Hex Conversion

from_hex

from_hex(s: string) → bytes — Decodes a hexadecimal string (spaces ignored, no 0x prefix, even digit count) to bytes. Fails with BYTES_INVALID_HEX on invalid input.

to_hex

to_hex(b: bytes, upper: bool = False) → string — Encodes bytes as a contiguous 2-digit-per-byte hex string.

from_utf8

from_utf8(s: string) → bytes — Encodes a Unicode string into UTF-8 bytes.

to_utf8

to_utf8(b: bytes) → string — Strictly decodes UTF-8 bytes into a string; raises BYTES_INVALID_UTF8 on malformed sequences.

str

str(n: int) → string — Formats an integer in base 10.

Integer Math

abs

abs(n: int) → int — Absolute value.

min

min(a: int, b: int) → int — Minimum of two integers.

max

max(a: int, b: int) → int — Maximum of two integers.

pow

pow(base: int, exp: int, mod: int) → int — Modular exponentiation (baseexp mod m). Requires exp ≥ 0 and mod ≥ 1.

bit_length

bit_length(n: int) → int — Minimum number of bits required to represent abs(n) (0 returns 0).

Control & Failure

range

range(n), range(start, stop), range(start, stop, step) — Integer sequence iterable for for loops (see for Loops and range).

up = 0
for i in range(5):
    up += i
down = 0
for i in range(10, 0, -3):
    down += i

fail

fail(code: string, message: string) — Immediately aborts script execution and puts the Script node into an ERROR state with the given code and message. User error codes cannot start with the reserved prefixes SCRIPT_ or BYTES_ (doing so raises SCRIPT_INVALID_ERROR_CODE).

if n == 0:
    fail("ZERO_NOT_ALLOWED", "n must not be 0")
o = 100 // n