lib/varconvert.x

Var numeric conversion policy.

Primary API

Var

Var.convert

Var Var.convert(Var value, Symbol target)

Converts value to a numeric target, or returns exact-tag identity. All fifteen numeric families cross through the rules in this module. Integer narrowing keeps low bits, floating-to-integer truncates toward zero with a range check, and floating results follow host conversion. Identity returns the original Var and preserves its ownership; a newly boxed wide numeric result belongs to the active Scope. Converting a discrete <nan>, <-inf>, or <+inf> value to <f64> also returns the original Var, preserving its discrete tag.

Raises: <bad-enc> for invalid Var bits, <void-op> for void, <bad-target> for an unsupported target, <no-convert> for a nonnumeric source, <conv-range> when the result does not fit, or <alloc-fail> while boxing a wide result. A nonnumeric source is rejected before decoding, with the decoder’s <bad-types> detail nested under <no-convert>.

Source: lib/varconvert.x:265

Advanced and interop API

Var

Var.integer_box

Var Var.integer_box(Symbol target, unsigned long long raw)

Boxes the low target-width bits of raw using integer target. Signed targets interpret those bits as two’s-complement. Immediate targets return self-contained values; wide targets allocate their boxes in the active Scope.

Raises: <bad-target> for a noninteger target, or <alloc-fail> or <bad-enc> while boxing a wide result.

Source: lib/varconvert.x:122

Var.integer_tag

Symbol Var.integer_tag(int rank, int unsigned_value)

Returns the integer tag selected by rank and signedness. rank must be positive. Ranks one through three map to <i32> or <u32>; callers applying integer promotion must first select its resulting signedness. Ranks four through six select the 48-bit, long, and long long families. A rank above six returns the null Symbol.

Source: lib/varconvert.x:41

Var.numeric_decode

void Var.numeric_decode(Var value, X2CVarNumeric *out)

Decodes a numeric value into caller-owned out storage. The result retains no pointer into value; integer and floating payloads use the members described by X2CVarNumeric.

Raises: <bad-arg> for a null output, <bad-enc> for invalid Var bits, <void-op> for void, or <bad-types> for a nonnumeric tag. These failures leave out unchanged.

Source: lib/varconvert.x:79

Var.numeric_info

int Var.numeric_info(Symbol tag, X2CVarNumericInfo *out)

Writes numeric-family metadata for tag and returns nonzero. The special <nan>, <-inf>, and <+inf> tags report the <f64> family. A null out or nonnumeric tag returns zero and leaves storage untouched.

Source: lib/varconvert.x:170

Var.signed_from_bits

long long Var.signed_from_bits(unsigned long long raw, int bits)

Interprets the low bits of raw as a two’s-complement signed value. bits must be between one and the width of unsigned long long.

Source: lib/varconvert.x:60

Var.width_mask

unsigned long long Var.width_mask(int bits)

Returns a mask containing the low bits bits. Zero yields zero and a width at least unsigned long long yields ULLONG_MAX; bits must not be negative.

Source: lib/varconvert.x:53

Public types

X2CVarNumeric

typedef struct X2CVarNumeric { Symbol tag, int floating, unsigned_value, bits, rank; unsigned long long raw; long double floating_value; } X2CVarNumeric

Holds a decoded numeric Var and its promotion metadata. Integer values use the low bits of raw, with signed values represented in two’s-complement; floating values use floating_value. The record holds no storage and retains nothing from the source Var.

Source: lib/varconvert.x:29

X2CVarNumericInfo

typedef struct X2CVarNumericInfo { Symbol tag, int floating, unsigned_value, bits, rank; } X2CVarNumericInfo

Describes one numeric Var family without holding a value. tag is canonical, floating and unsigned_value classify it, bits is its native payload width, and rank orders promotion. Callers normally obtain a valid record from Var.numeric_info.

Source: lib/varconvert.x:20

Design notes

Converts among Var’s fifteen numeric families. Integer conversions keep the target width’s low bits; floating-to-integer conversions truncate toward zero and require a representable result. A nonnumeric value converts only to its own tag.

Tests and examples

make verify (unittest/test-var.x).