lib/varconvert.x

Var numeric conversion policy.

Primary API

Var

Var.convert

meta native 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:149

X2CVarNumeric

X2CVarNumeric.f32

float X2CVarNumeric.f32(X2CVarNumeric &value)

Converts a decoded numeric value to native float without boxing. Uses the target host cast, preserving its rounding behavior.

Source: lib/varconvert.x:353

X2CVarNumeric.f64

double X2CVarNumeric.f64(X2CVarNumeric &value)

Converts a decoded numeric value to native double without boxing. Uses the target host cast, preserving its rounding behavior.

Source: lib/varconvert.x:362

X2CVarNumeric.ldouble

long double X2CVarNumeric.ldouble(X2CVarNumeric &value)

Converts a decoded numeric value to native long double without boxing. Uses the target host cast, preserving its rounding behavior.

Source: lib/varconvert.x:371

Advanced and interop API

Var

Var.array

Array Var.array(Var value)

Extracts the Array payload of value.

Raises: <no-convert> for any other tag. An implicit conversion from Var to Array uses Var.array_payload, which reads the payload or NULL without raising.

Source: lib/varconvert.x:90

Var.as_iter

Iter Var.as_iter(Var value)

Extracts the Iter payload of value.

Raises: <no-convert> for any other tag. An implicit conversion from Var to Iter uses Var.iter_payload, which reads the payload or NULL without raising.

Source: lib/varconvert.x:95

Var.block

Block Var.block(Var value)

Extracts the Block payload of value.

Raises: <no-convert> for any other tag. An implicit conversion from Var to Block uses Var.block_payload, which reads the payload or NULL without raising.

Source: lib/varconvert.x:91

Var.buffer

Buffer Var.buffer(Var value)

Extracts the Buffer payload of value.

Raises: <no-convert> for any other tag. An implicit conversion from Var to Buffer uses Var.buffer_payload, which reads the payload or NULL without raising.

Source: lib/varconvert.x:92

Var.bytes

Bytes Var.bytes(Var value)

Extracts the Bytes payload of value.

Raises: <no-convert> for any other tag. An implicit conversion from Var to Bytes uses Var.bytes_payload, which reads the payload or NULL without raising.

Source: lib/varconvert.x:93

Var.file

File Var.file(Var value)

Extracts the File payload of value.

Raises: <no-convert> for any other tag. An implicit conversion from Var to File uses Var.file_payload, which reads the payload or NULL without raising.

Source: lib/varconvert.x:94

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

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

Var.list

List Var.list(Var value)

Extracts the List payload of value.

Raises: <no-convert> for any other tag. An implicit conversion from Var to List uses Var.list_payload, which reads the payload or NULL without raising.

Source: lib/varconvert.x:96

Var.map

Map Var.map(Var value)

Extracts the Map payload of value.

Raises: <no-convert> for any other tag. An implicit conversion from Var to Map uses Var.map_payload, which reads the payload or NULL without raising.

Source: lib/varconvert.x:97

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

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

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

Var.string

String Var.string(Var value)

Extracts the String payload of value.

Raises: <no-convert> for any other tag. A String destination converts a Var implicitly through Var.as_string instead, and Var.string_payload reads the payload or NULL without raising.

Source: lib/varconvert.x:72

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

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

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

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).