lib/common.x

The shared Var union and operations used by every module.

Advanced and interop API

Functions

x2c_initialize

void x2c_initialize(void)

Initializes the x2c runtime once for the current process.

Source: lib/common.x:790

x2c_initialize_protocols

void x2c_initialize_protocols(void)

Runs compiler-generated runtime protocol registration.

Source: lib/common.x:786

x2c_normalize_index

int x2c_normalize_index(int index, int length)

Normalizes one element index against length.

Source: lib/common.x:814

x2c_normalize_slice

int x2c_normalize_slice(int *start, int *stop, int step, int length)

Normalizes slice bounds and returns the resulting element count.

Source: lib/common.x:834

Array

Array.var

inline Var Array.var(Array x)

Boxes an Array value as Var.

Source: lib/common.x:526

Block

Block.var

inline Var Block.var(Block x)

Boxes a Block value as Var.

Source: lib/common.x:528

Buffer

Buffer.var

inline Var Buffer.var(Buffer x)

Boxes a Buffer value as Var.

Source: lib/common.x:530

Bytes

Bytes.var

inline Var Bytes.var(Bytes x)

Boxes a Bytes value as Var.

Source: lib/common.x:532

File

File.var

inline Var File.var(File x)

Boxes a File value as Var.

Source: lib/common.x:537

Iter

Iter.truth

inline int Iter.truth(Iter iter)

Returns nonzero when iter is not null.

Source: lib/common.x:395

Iter.var

inline Var Iter.var(Iter x)

Boxes an Iter value as Var.

Source: lib/common.x:547

List

List.truth

inline int List.truth(List list)

Returns nonzero when list is not nil, the null empty List.

Source: lib/common.x:398

List.var

inline Var List.var(List x)

Boxes a List value as Var.

Source: lib/common.x:534

Map

Map.var

inline Var Map.var(Map x)

Boxes a Map value as Var.

Source: lib/common.x:539

String

String.truth

inline int String.truth(String string)

Returns nonzero when string contains at least one byte. The canonical empty String is null, with no allocated storage.

Source: lib/common.x:402

String.var

inline Var String.var(String x)

Boxes a String value as Var.

Source: lib/common.x:541

Symbol

Symbol.var

inline Var Symbol.var(Symbol x)

Boxes a Symbol value as Var.

Source: lib/common.x:544

Var

Var.array

inline Array Var.array(Var value)

Extracts the Array payload of value, or NULL for another tag.

Source: lib/common.x:615

Var.as_iter

inline Iter Var.as_iter(Var value)

Extracts the Iter payload of value, or NULL for another tag.

Source: lib/common.x:620

Var.block

inline Block Var.block(Var value)

Extracts the Block payload of value, or NULL for another tag.

Source: lib/common.x:616

Var.box_f32

inline Var Var.box_f32(float value)

Boxes a native float as an immediate <f32> Var.

Source: lib/common.x:508

Var.box_f64

inline Var Var.box_f64(double value)

Boxes a native double as an immediate <f64> Var.

Source: lib/common.x:515

Var.box_i16

inline Var Var.box_i16(short value)

Boxes a native short as an immediate <i16> Var.

Source: lib/common.x:499

Var.box_i32_bits

inline Var Var.box_i32_bits(unsigned value)

Boxes an unsigned 32-bit pattern as an immediate <i32> Var.

Source: lib/common.x:503

Var.box_i8

inline Var Var.box_i8(char value)

Boxes a native char as an immediate <i8> Var.

Source: lib/common.x:495

Var.box_u16

inline Var Var.box_u16(ushort value)

Boxes a native ushort as an immediate <u16> Var.

Source: lib/common.x:501

Var.box_u32

inline Var Var.box_u32(unsigned value)

Boxes a native uint as an immediate <u32> Var.

Source: lib/common.x:505

Var.box_u8

inline Var Var.box_u8(uchar value)

Boxes a native uchar as an immediate <u8> Var.

Source: lib/common.x:497

Var.buffer

inline Buffer Var.buffer(Var value)

Extracts the Buffer payload of value, or NULL for another tag.

Source: lib/common.x:617

Var.bytes

inline Bytes Var.bytes(Var value)

Extracts the Bytes payload of value, or NULL for another tag.

Source: lib/common.x:618

Var.char

char Var.char(Var x)

Returns x as a native char under the Var.convert rules.

Raises: Var.convert’s causes when the source is nonnumeric, void, out of floating range, or invalidly encoded.

Source: lib/common.x:642

Var.decode_f32

inline float Var.decode_f32(Var value)

Decodes an immediate <f32> Var.

Source: lib/common.x:462

Var.decode_f64

inline double Var.decode_f64(Var value)

Decodes an immediate <f64> Var.

Source: lib/common.x:470

Var.double

double Var.double(Var x)

Returns x as a native double under the Var.convert rules.

Raises: Var.convert’s causes when the source is nonnumeric, void, or invalidly encoded.

Source: lib/common.x:771

Var.file

inline File Var.file(Var value)

Extracts the File payload of value, or NULL for another tag.

Source: lib/common.x:619

Var.float

float Var.float(Var x)

Returns x as a native float under the Var.convert rules.

Raises: Var.convert’s causes when the source is nonnumeric, void, or invalidly encoded.

Source: lib/common.x:762

Var.int

int Var.int(Var x)

Returns x as a native int under the Var.convert rules.

Raises: Var.convert’s causes when the source is nonnumeric, void, out of floating range, or invalidly encoded.

Source: lib/common.x:678

Var.is_row

inline int Var.is_row( Var value, unsigned top, unsigned long mask, unsigned long bottom)

Reports whether value occupies the encoding row at top/bottom. mask selects the bits the decoder discriminates on within top’s group, so a caller that already knows the row tests it with two compares instead of a decode. var-tags.xmacro projects the rows that qualify; a row whose decoded form carries a validity clause is not one of them and must ask Var.is.

Source: lib/common.x:611

Var.is_wide

inline int Var.is_wide(Var v)

Reports whether v uses a scope-owned wide numeric box.

Source: lib/common.x:453

Var.list

inline List Var.list(Var value)

Extracts the List payload of value, or NULL for another tag.

Source: lib/common.x:621

Var.long

long Var.long(Var x)

Returns x as a native long under the Var.convert rules.

Raises: Var.convert’s causes when the source is nonnumeric, void, out of floating range, or invalidly encoded.

Source: lib/common.x:705

Var.long_double

long double Var.long_double(Var x)

Returns x as a native long double under the Var.convert rules.

Raises: Var.convert’s causes when the source is nonnumeric, void, or invalidly encoded.

Source: lib/common.x:752

Var.long_long

long long Var.long_long(Var x)

Returns x as a native long long under the Var.convert rules.

Raises: Var.convert’s causes when the source is nonnumeric, void, out of floating range, or invalidly encoded.

Source: lib/common.x:728

Var.map

inline Map Var.map(Var value)

Extracts the Map payload of value, or NULL for another tag.

Source: lib/common.x:622

Var.payload32

inline unsigned Var.payload32(Var value)

Returns the low 32 payload bits of an immediate Var.

Source: lib/common.x:459

Var.short

short Var.short(Var x)

Returns x as a native short under the Var.convert rules.

Raises: Var.convert’s causes when the source is nonnumeric, void, out of floating range, or invalidly encoded.

Source: lib/common.x:660

Var.string

inline String Var.string(Var value)

Extracts the String payload of value, or NULL for another tag.

Source: lib/common.x:623

Var.symbol

inline Symbol Var.symbol(Var x)

Extracts the symbol payload after the caller establishes the matching Var kind.

Source: lib/common.x:628

Var.uchar

uchar Var.uchar(Var x)

Returns x as a native uchar under the Var.convert rules.

Raises: Var.convert’s causes when the source is nonnumeric, void, out of floating range, or invalidly encoded.

Source: lib/common.x:651

Var.uint

uint Var.uint(Var x)

Returns x as a native uint under the Var.convert rules.

Raises: Var.convert’s causes when the source is nonnumeric, void, out of floating range, or invalidly encoded.

Source: lib/common.x:687

Var.ulong

ulong Var.ulong(Var x)

Returns x as a native ulong under the Var.convert rules.

Raises: Var.convert’s causes when the source is nonnumeric, void, out of floating range, or invalidly encoded.

Source: lib/common.x:717

Var.ulong_long

unsigned long long Var.ulong_long(Var x)

Returns x as a native unsigned long long under the Var.convert rules.

Raises: Var.convert’s causes when the source is nonnumeric, void, out of floating range, or invalidly encoded.

Source: lib/common.x:740

Var.unsigned

unsigned Var.unsigned(Var x)

Returns x as a native unsigned under the Var.convert rules.

Raises: Var.convert’s causes when the source is nonnumeric, void, out of floating range, or invalidly encoded.

Source: lib/common.x:696

Var.ushort

ushort Var.ushort(Var x)

Returns x as a native ushort under the Var.convert rules.

Raises: Var.convert’s causes when the source is nonnumeric, void, out of floating range, or invalidly encoded.

Source: lib/common.x:669

char

char.repr

inline String char.repr(char x)

Returns the readable representation of char.

Source: lib/common.x:581

char.str

inline String char.str(char x)

Returns the display String of char.

Source: lib/common.x:581

char.var

inline Var char.var(char x)

Boxes a native char value as Var.

Source: lib/common.x:581

double

double.repr

inline String double.repr(double x)

Returns the readable representation of double.

Source: lib/common.x:589

double.str

inline String double.str(double x)

Returns the display String of double.

Source: lib/common.x:589

double.var

inline Var double.var(double x)

Boxes a native double value as Var.

Source: lib/common.x:589

float

float.repr

inline String float.repr(float x)

Returns the readable representation of float.

Source: lib/common.x:588

float.str

inline String float.str(float x)

Returns the display String of float.

Source: lib/common.x:588

float.var

inline Var float.var(float x)

Boxes a native float value as Var.

Source: lib/common.x:588

int

int.repr

inline String int.repr(int x)

Returns the readable representation of int.

Source: lib/common.x:585

int.str

inline String int.str(int x)

Returns the display String of int.

Source: lib/common.x:585

int.var

inline Var int.var(int x)

Boxes a native int value as Var.

Source: lib/common.x:585

long

long.repr

inline String long.repr(long l)

Returns the readable representation of long.

Source: lib/common.x:600

long.str

inline String long.str(long l)

Returns the display String of long.

Source: lib/common.x:598

long.var

inline Var long.var(long x)

Boxes a long value as Var.

Source: lib/common.x:594

short

short.repr

inline String short.repr(short x)

Returns the readable representation of short.

Source: lib/common.x:583

short.str

inline String short.str(short x)

Returns the display String of short.

Source: lib/common.x:583

short.var

inline Var short.var(short x)

Boxes a native short value as Var.

Source: lib/common.x:583

uchar

uchar.repr

inline String uchar.repr(uchar x)

Returns the readable representation of uchar.

Source: lib/common.x:582

uchar.str

inline String uchar.str(uchar x)

Returns the display String of uchar.

Source: lib/common.x:582

uchar.var

inline Var uchar.var(uchar x)

Boxes a native uchar value as Var.

Source: lib/common.x:582

uint

uint.repr

inline String uint.repr(uint x)

Returns the readable representation of uint.

Source: lib/common.x:586

uint.str

inline String uint.str(uint x)

Returns the display String of uint.

Source: lib/common.x:586

uint.var

inline Var uint.var(uint x)

Boxes a native uint value as Var.

Source: lib/common.x:586

ulong

ulong.var

inline Var ulong.var(ulong x)

Boxes a ulong value as Var.

Source: lib/common.x:596

unsigned

unsigned.repr

inline String unsigned.repr(unsigned x)

Returns the readable representation of unsigned.

Source: lib/common.x:587

unsigned.str

inline String unsigned.str(unsigned x)

Returns the display String of unsigned.

Source: lib/common.x:587

unsigned.var

inline Var unsigned.var(unsigned x)

Boxes a native unsigned value as Var.

Source: lib/common.x:587

ushort

ushort.repr

inline String ushort.repr(ushort x)

Returns the readable representation of ushort.

Source: lib/common.x:584

ushort.str

inline String ushort.str(ushort x)

Returns the display String of ushort.

Source: lib/common.x:584

ushort.var

inline Var ushort.var(ushort x)

Boxes a native ushort value as Var.

Source: lib/common.x:584

Runtime-internal callables

These callables connect runtime translation units. They are documented for source readers but are not supported as user API.

Functions

x2c_hash_bytes

inline unsigned x2c_hash_bytes( unsigned long seed, const void *data, size_t width)

Hashes an arbitrary byte block through the shared 64-bit mixer. seed distinguishes callers that hash the same bytes under different types; the byte width distinguishes a final partial word from zero padding.

Source: lib/common.x:432

x2c_hash_word

inline unsigned x2c_hash_word(unsigned long word)

Narrows a mixed word to the nonzero 32-bit hash the tables expect. Zero is reserved to mark an empty bucket, so it maps to all ones.

Source: lib/common.x:422

x2c_mix64

inline unsigned long x2c_mix64(unsigned long word)

Avalanches one 64-bit word. This is MurmurHash3’s fmix64 finalizer, the shared mixer behind every fixed-width hash in the runtime. It is six instructions, and its low bits are as well distributed as its high ones, which is what Map masks. Use x2c_hash_bytes for a block that spans several words.

Source: lib/common.x:410

Public types

Array

typedef Block Array

Scope-owned mutable Block view whose elements are Vars.

Source: lib/common.x:77

Atom

typedef Var Atom

Exact-name Var using a Symbol or a pooled canonical long spelling.

Source: lib/common.x:75

Block

typedef struct Block *Block

Opaque handle to Scope-owned mutable fixed-width storage.

Source: lib/common.x:67

Buffer

typedef struct Buffer *Buffer

Opaque handle to a Scope-owned mutable text builder.

Source: lib/common.x:69

Bytes

typedef void *Bytes

Data pointer into Block-owned raw element storage.

Source: lib/common.x:65

Context

typedef struct Context *Context

Bounded Scope, Error, Match, and optional canonical-pool state.

Source: lib/common.x:89

File

typedef FILE *File

Native stdio stream handle whose opener determines close ownership.

Source: lib/common.x:103

Func

typedef struct Func *Func

Scope-owned generic native-call adapter and optional bound context.

Source: lib/common.x:97

Iter

typedef struct Iter *Iter

Mutable traversal state whose sources must outlive its iteration.

Source: lib/common.x:105

List

typedef struct List *List

Immutable canonical cons chain; NULL is nil. Its lifetime follows its owning List pool, which may be an ancestor.

Source: lib/common.x:81

Map

typedef struct Map *Map

Scope-owned mutable table mapping Var keys to Var values.

Source: lib/common.x:85

Mutex

typedef struct Mutex *Mutex

Scope-owned opaque mutex that must outlive every accessing thread.

Source: lib/common.x:91

Pool

typedef struct Pool *Pool

Nested canonicalization table with Scope-backed object storage.

Source: lib/common.x:87

RenderPath

typedef struct RenderPath { const void *identity; struct RenderPath *previous; } RenderPath

Caller-owned frame in this thread’s active recursive rendering path.

Source: lib/common.x:117

Scope

typedef struct Scope *Scope

Region owner for individually tracked runtime allocations.

Source: lib/common.x:83

String

typedef char *String

Immutable canonical NUL-terminated bytes; NULL is the empty String. Its lifetime follows its owning String pool, which may be an ancestor.

Source: lib/common.x:101

Symbol

typedef unsigned long Symbol

Immediate compact name encoding with no allocation ownership.

Source: lib/common.x:71

SymbolSet

typedef unsigned char *SymbolSet

Borrowed immutable compiler-generated set of compact Symbols.

Source: lib/common.x:73

Thread

typedef struct Thread *Thread

Caller-owned handle to a Context-backed worker. Join the worker before freeing the handle.

Source: lib/common.x:95

Var

typedef union Var { unsigned long u64; double f64, void *p64; } Var

Eight-byte tagged runtime value for immediate scalars and encoded handles. Pointer-bearing values follow the ownership rules of their concrete type; raw Null is all zero bits and void is all one bits.

Source: lib/common.x:30

VarBinaryFn

typedef Var (*VarBinaryFn)(Var lhs, Var rhs)

Applies one descriptor-owned binary operation and returns its result.

Source: lib/common.x:144

VarCompareFn

typedef int (*VarCompareFn)(Var, Var)

Returns negative, zero, or positive for two Vars of one descriptor.

Source: lib/common.x:138

VarContainsFn

typedef int (*VarContainsFn)(Var receiver, Var needle)

Reports whether receiver contains needle.

Source: lib/common.x:142

VarEqualFn

typedef int (*VarEqualFn)(Var, Var)

Reports value equality for two Vars with the same descriptor.

Source: lib/common.x:132

VarExportContextFn

typedef Var (*VarExportContextFn)(Var value, Context source)

Exports a custom value from source into its destination Context. Implementations move owned storage and recursively export nested values.

Source: lib/common.x:158

VarGetIndexFn

typedef Var (*VarGetIndexFn)(Var receiver, Var key)

Reads one dynamically indexed value.

Source: lib/common.x:148

VarHashFn

typedef unsigned (*VarHashFn)(Var)

Computes one Var hash; Var.hash normalizes a zero result.

Source: lib/common.x:130

VarIterIntoFn

typedef Iter (*VarIterIntoFn)(Var, Iter)

Initializes traversal in caller-provided Iter storage and returns it. The storage and any retained receiver state must outlive traversal.

Source: lib/common.x:136

VarMethods

typedef struct VarMethods { VarStrFn str, repr, VarHashFn hash, VarEqualFn equal, VarCompareFn compare; VarTruthFn truth, VarIterIntoFn iter, VarWriteFn write_str, write_repr; VarContainsFn contains, VarBinaryFn add, sub, mul, div, mod, matmul; VarUnaryFn neg; VarGetIndexFn getindex, VarSetIndexFn setindex, VarUpdateIndexFn updateindex; VarPostfixIndexFn postfixindex, VarExportContextFn export_context; } VarMethods

Sparse process-global callback row for one Var descriptor. Registration stores each non-NULL function pointer without ownership and leaves existing slots unchanged for NULL fields. Callback code must remain loaded until its pointer is replaced or the process ends. Callbacks run synchronously when their operation dispatches; registration invokes none and retains no callback context.

Source: lib/common.x:171

VarPostfixIndexFn

typedef Var (*VarPostfixIndexFn)(Var receiver, Var key, Symbol op)

Applies an indexed postfix operation and returns the prior value.

Source: lib/common.x:154

VarSetIndexFn

typedef Var (*VarSetIndexFn)(Var receiver, Var key, Var value)

Stores an indexed value and returns the assignment result.

Source: lib/common.x:150

VarStrFn

typedef String (*VarStrFn)(Var)

Renders one Var as a display or readable String.

Source: lib/common.x:126

VarTruthFn

typedef int (*VarTruthFn)(Var)

Reports whether a Var is true.

Source: lib/common.x:140

VarUnaryFn

typedef Var (*VarUnaryFn)(Var value)

Applies one descriptor-owned unary operation and returns its result.

Source: lib/common.x:146

VarUpdateIndexFn

typedef Var (*VarUpdateIndexFn)(Var receiver, Var key, Symbol op, Var rhs)

Applies an indexed compound operation and returns the stored result.

Source: lib/common.x:152

VarWriteFn

typedef Buffer (*VarWriteFn)(Var, Buffer)

Appends one Var rendering to a caller-owned Buffer and returns it.

Source: lib/common.x:128

X2CErrorSite

typedef struct X2CErrorSite { const char *file, *function, int line; } X2CErrorSite

Borrowed source location supplied during one compiler-generated raise. The pointed-to file and function spellings must outlive that call.

Source: lib/common.x:186

X2CStatic

typedef struct X2CStatic { int ready; void *payload, *owner; struct X2CStatic *next; } X2CStatic

Zero-initialized compiler storage for one dynamic local static. The runtime owns its fields. payload becomes available to the winning initializer before publication; an acquire returning zero observes the committed value. Failed attempts retain their address until teardown. Payload storage retains no referenced runtime objects.

Source: lib/common.x:221

uchar

typedef unsigned char uchar

Unsigned native character type.

Source: lib/common.x:108

uint

typedef unsigned int uint

Unsigned native int type.

Source: lib/common.x:112

ulong

typedef unsigned long ulong

Unsigned native long type.

Source: lib/common.x:114

ushort

typedef unsigned short ushort

Unsigned native short type.

Source: lib/common.x:110

Design notes

Every runtime module includes this one. It defines the eight-byte Var union itself, the compile-time assertions that pin the native type sizes the encoding depends on, the Symbol outcome names that status returning APIs share, and the declarations that let modules name each other without an include cycle. It also defines immediate scalar boxing, runtime startup, and shared index normalization. Pointer-shaped Var extractors are ABI crossings whose callers establish the advertised source kind; scalar readers instead convert nonmatching numeric tags through Var.convert.