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:801

x2c_initialize_protocols

void x2c_initialize_protocols(void)

Runs compiler-generated runtime protocol registration.

Source: lib/common.x:797

x2c_normalize_index

int x2c_normalize_index(int index, int length)

Normalizes one element index against length.

Source: lib/common.x:827

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:847

Array

Array.var

inline Var Array.var(Array x)

Boxes an Array value as Var.

Source: lib/common.x:503

Block

Block.var

inline Var Block.var(Block x)

Boxes a Block value as Var.

Source: lib/common.x:505

Buffer

Buffer.var

inline Var Buffer.var(Buffer x)

Boxes a Buffer value as Var.

Source: lib/common.x:507

Bytes

Bytes.var

inline Var Bytes.var(Bytes x)

Boxes a Bytes value as Var.

Source: lib/common.x:509

File

File.var

inline Var File.var(File x)

Boxes a File value as Var.

Source: lib/common.x:513

Iter

Iter.truth

inline int Iter.truth(Iter iter)

Returns nonzero when iter is not null.

Source: lib/common.x:373

Iter.var

inline Var Iter.var(Iter x)

Boxes an Iter value as Var.

Source: lib/common.x:521

List

List.truth

inline int List.truth(List list)

Returns nonzero when list is not nil.

Source: lib/common.x:376

List.var

inline Var List.var(List x)

Boxes a List value as Var.

Source: lib/common.x:511

Map

Map.var

inline Var Map.var(Map x)

Boxes a Map value as Var.

Source: lib/common.x:515

String

String.truth

inline int String.truth(String string)

Returns nonzero when string contains at least one byte.

Source: lib/common.x:379

String.var

inline Var String.var(String x)

Boxes a String value as Var.

Source: lib/common.x:517

Symbol

Symbol.var

inline Var Symbol.var(Symbol x)

Boxes a Symbol value as Var.

Source: lib/common.x:519

Var

Var.array

inline Array Var.array(Var x)

Extracts the Array pointer from x, or NULL for another tag.

Source: lib/common.x:579

Var.as_iter

inline Iter Var.as_iter(Var x)

Extracts the Iter pointer from x, or NULL for another tag.

Source: lib/common.x:617

Var.block

inline Block Var.block(Var x)

Extracts the Block pointer from x, or NULL for another tag.

Source: lib/common.x:585

Var.box_f32

inline Var Var.box_f32(float value)

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

Source: lib/common.x:485

Var.box_f64

inline Var Var.box_f64(double value)

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

Source: lib/common.x:492

Var.box_i16

inline Var Var.box_i16(short value)

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

Source: lib/common.x:476

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:480

Var.box_i8

inline Var Var.box_i8(char value)

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

Source: lib/common.x:472

Var.box_u16

inline Var Var.box_u16(ushort value)

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

Source: lib/common.x:478

Var.box_u32

inline Var Var.box_u32(unsigned value)

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

Source: lib/common.x:482

Var.box_u8

inline Var Var.box_u8(uchar value)

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

Source: lib/common.x:474

Var.buffer

inline Buffer Var.buffer(Var x)

Extracts the Buffer pointer from x, or NULL for another tag.

Source: lib/common.x:591

Var.bytes

inline Bytes Var.bytes(Var x)

Extracts the Bytes pointer from x, or NULL for another tag.

Source: lib/common.x:597

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:653

Var.decode_f32

inline float Var.decode_f32(Var value)

Decodes an immediate <f32> Var.

Source: lib/common.x:439

Var.decode_f64

inline double Var.decode_f64(Var value)

Decodes an immediate <f64> Var.

Source: lib/common.x:447

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:782

Var.file

inline File Var.file(Var x)

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

Source: lib/common.x:605

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:773

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:689

Var.is_wide

inline int Var.is_wide(Var v)

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

Source: lib/common.x:430

Var.list

inline List Var.list(Var x)

Extracts the List pointer from x, or nil for another tag.

Source: lib/common.x:611

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:716

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:763

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:739

Var.map

inline Map Var.map(Var x)

Extracts the Map pointer from x, or NULL for another tag.

Source: lib/common.x:623

Var.payload32

inline unsigned Var.payload32(Var value)

Returns the low 32 payload bits of an immediate Var.

Source: lib/common.x:436

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:671

Var.string

inline String Var.string(Var x)

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

Source: lib/common.x:631

Var.symbol

inline Symbol Var.symbol(Var x)

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

Source: lib/common.x:639

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:662

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:698

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:728

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:751

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:707

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:680

char

char.repr

inline String char.repr(char x)

Returns the readable representation of char.

Source: lib/common.x:555

char.str

inline String char.str(char x)

Returns the display String of char.

Source: lib/common.x:555

char.var

inline Var char.var(char x)

Boxes a native char value as Var.

Source: lib/common.x:555

double

double.repr

inline String double.repr(double x)

Returns the readable representation of double.

Source: lib/common.x:563

double.str

inline String double.str(double x)

Returns the display String of double.

Source: lib/common.x:563

double.var

inline Var double.var(double x)

Boxes a native double value as Var.

Source: lib/common.x:563

float

float.repr

inline String float.repr(float x)

Returns the readable representation of float.

Source: lib/common.x:562

float.str

inline String float.str(float x)

Returns the display String of float.

Source: lib/common.x:562

float.var

inline Var float.var(float x)

Boxes a native float value as Var.

Source: lib/common.x:562

int

int.repr

inline String int.repr(int x)

Returns the readable representation of int.

Source: lib/common.x:559

int.str

inline String int.str(int x)

Returns the display String of int.

Source: lib/common.x:559

int.var

inline Var int.var(int x)

Boxes a native int value as Var.

Source: lib/common.x:559

long

long.repr

inline String long.repr(long l)

Returns the readable representation of long.

Source: lib/common.x:574

long.str

inline String long.str(long l)

Returns the display String of long.

Source: lib/common.x:572

long.var

inline Var long.var(long x)

Boxes a long value as Var.

Source: lib/common.x:568

short

short.repr

inline String short.repr(short x)

Returns the readable representation of short.

Source: lib/common.x:557

short.str

inline String short.str(short x)

Returns the display String of short.

Source: lib/common.x:557

short.var

inline Var short.var(short x)

Boxes a native short value as Var.

Source: lib/common.x:557

uchar

uchar.repr

inline String uchar.repr(uchar x)

Returns the readable representation of uchar.

Source: lib/common.x:556

uchar.str

inline String uchar.str(uchar x)

Returns the display String of uchar.

Source: lib/common.x:556

uchar.var

inline Var uchar.var(uchar x)

Boxes a native uchar value as Var.

Source: lib/common.x:556

uint

uint.repr

inline String uint.repr(uint x)

Returns the readable representation of uint.

Source: lib/common.x:560

uint.str

inline String uint.str(uint x)

Returns the display String of uint.

Source: lib/common.x:560

uint.var

inline Var uint.var(uint x)

Boxes a native uint value as Var.

Source: lib/common.x:560

ulong

ulong.var

inline Var ulong.var(ulong x)

Boxes a ulong value as Var.

Source: lib/common.x:570

unsigned

unsigned.repr

inline String unsigned.repr(unsigned x)

Returns the readable representation of unsigned.

Source: lib/common.x:561

unsigned.str

inline String unsigned.str(unsigned x)

Returns the display String of unsigned.

Source: lib/common.x:561

unsigned.var

inline Var unsigned.var(unsigned x)

Boxes a native unsigned value as Var.

Source: lib/common.x:561

ushort

ushort.repr

inline String ushort.repr(ushort x)

Returns the readable representation of ushort.

Source: lib/common.x:558

ushort.str

inline String ushort.str(ushort x)

Returns the display String of ushort.

Source: lib/common.x:558

ushort.var

inline Var ushort.var(ushort x)

Boxes a native ushort value as Var.

Source: lib/common.x:558

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:409

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:399

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:387

Public types

Array

typedef Block Array

Scope-owned mutable Block view whose elements are Vars.

Source: lib/common.x:79

Atom

typedef Var Atom

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

Source: lib/common.x:77

Block

typedef struct Block *Block

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

Source: lib/common.x:69

Buffer

typedef struct Buffer *Buffer

Opaque handle to a Scope-owned mutable text builder.

Source: lib/common.x:71

Bytes

typedef void *Bytes

Data pointer into Block-owned raw element storage.

Source: lib/common.x:67

Context

typedef struct Context *Context

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

Source: lib/common.x:91

File

typedef FILE *File

Native stdio stream handle whose opener determines close ownership.

Source: lib/common.x:105

Func

typedef struct Func *Func

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

Source: lib/common.x:99

Iter

typedef struct Iter *Iter

Mutable traversal state whose sources must outlive its iteration.

Source: lib/common.x:107

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:83

Map

typedef struct Map *Map

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

Source: lib/common.x:87

Mutex

typedef struct Mutex *Mutex

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

Source: lib/common.x:93

Pool

typedef struct Pool *Pool

Nested canonicalization table with Scope-backed object storage.

Source: lib/common.x:89

Scope

typedef struct Scope *Scope

Region owner for individually tracked runtime allocations.

Source: lib/common.x:85

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:103

Symbol

typedef unsigned long Symbol

Immediate compact name encoding with no allocation ownership.

Source: lib/common.x:73

SymbolSet

typedef unsigned char *SymbolSet

Borrowed immutable compiler-generated set of compact Symbols.

Source: lib/common.x:75

Thread

typedef struct Thread *Thread

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

Source: lib/common.x:97

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:29

VarBinaryFn

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

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

Source: lib/common.x:137

VarCompareFn

typedef int (*VarCompareFn)(Var, Var)

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

Source: lib/common.x:131

VarContainsFn

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

Reports whether receiver contains needle.

Source: lib/common.x:135

VarEqualFn

typedef int (*VarEqualFn)(Var, Var)

Reports value equality for two Vars with the same descriptor.

Source: lib/common.x:125

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:151

VarGetIndexFn

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

Reads one dynamically indexed value.

Source: lib/common.x:141

VarHashFn

typedef unsigned (*VarHashFn)(Var)

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

Source: lib/common.x:123

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:129

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, 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:164

VarPostfixIndexFn

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

Applies an indexed postfix operation and returns the prior value.

Source: lib/common.x:147

VarSetIndexFn

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

Stores an indexed value and returns the assignment result.

Source: lib/common.x:143

VarStrFn

typedef String (*VarStrFn)(Var)

Renders one Var as a display or readable String.

Source: lib/common.x:119

VarTruthFn

typedef int (*VarTruthFn)(Var)

Reports whether a Var is true.

Source: lib/common.x:133

VarUnaryFn

typedef Var (*VarUnaryFn)(Var value)

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

Source: lib/common.x:139

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:145

VarWriteFn

typedef Buffer (*VarWriteFn)(Var, Buffer)

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

Source: lib/common.x:121

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:178

uchar

typedef unsigned char uchar

Unsigned native character type.

Source: lib/common.x:110

uint

typedef unsigned int uint

Unsigned native int type.

Source: lib/common.x:114

ulong

typedef unsigned long ulong

Unsigned native long type.

Source: lib/common.x:116

ushort

typedef unsigned short ushort

Unsigned native short type.

Source: lib/common.x:112

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.