lib/varops.x

Boxed Var operators, updates, and truthiness.

Primary API

Functions

x2c_var_equal

int x2c_var_equal(Var a, Var b)

Evaluates == on two Var operands. Two numbers compare as their native values do in C after the usual arithmetic conversions, so 3 == 3L and -1 == 4294967295u hold and a NaN equals nothing. Other values compare through Var.equal.

Raises: <bad-enc> when a numeric comparison meets invalid Var bits.

Source: lib/varops.x:475

x2c_var_identical

int x2c_var_identical(Var a, Var b)

Evaluates === on two Var operands. Two numbers are identical when they have the same tag and the same bits, so two boxes of one long are identical, NaN === NaN holds, and +0.0 === -0.0 does not. Other values are identical when their Var bits are, as Var.same reports.

Source: lib/varops.x:487

x2c_var_order

double x2c_var_order(Var a, Var b)

Orders two Var operands for <, <=, >, and >=. Two numbers order as their native values do in C after the usual arithmetic conversions. The result is -1, 0, or 1, or NaN when a NaN leaves the pair unordered, so each relation to zero is false. Other values return the order Var.compare gives.

Raises: <void-op> when either operand is void, and <bad-enc> when a numeric comparison meets invalid Var bits.

Source: lib/varops.x:497

x2c_var_postfix_volatile

Var x2c_var_postfix_volatile(volatile Var &?lhs, Symbol op)

Applies Var.postfix semantics to a volatile destination in generated code. Volatile preserves accesses across exception transfer, without providing thread synchronization.

Source: lib/varops.x:667

x2c_var_update_volatile

Var x2c_var_update_volatile(volatile Var &?lhs, Symbol op, Var rhs)

Applies Var.update semantics to a volatile destination in generated code. Volatile preserves accesses across exception transfer, without providing thread synchronization.

Source: lib/varops.x:623

Var

Var.add

meta native Var Var.add(Var lhs, Var rhs)

Adds dynamic values through numeric, String, or registered add behavior. Numeric promotion, failure, and result ownership follow Var.binary; String addition returns a canonical concatenation, and a protocol result keeps the ownership chosen by its callback.

Source: lib/varops.x:216

Var.binary

Var Var.binary(Var lhs, Symbol op, Var rhs)

Applies a dynamic arithmetic, bitwise, comparison, or logical operator. Integers use C-style promotion and wrap to the result type’s width; shifts use the promoted left operand’s type and sign-fill signed right shifts. Floating arithmetic uses the widest floating-point operand type. Comparisons and identity tests give the operators’ results on Var operands, so two numbers compare as their native values do in C. The logical operators are eager in this direct API. Equality and identity are the only operations that accept void and return an <i32> predicate. Immediate results are self-contained, canonical Strings keep their pool lifetime, and newly boxed wide results belong to the active Scope.

Raises: <bad-enc>, <void-op>, or <bad-op> at the dynamic boundary; numeric operations may additionally raise <bad-types>, <div-zero>, or <bad-shift>, and String concatenation or wide boxing may raise <size-limit>, <alloc-fail>, or <bad-enc>. A selected protocol, truth, or comparison callback may raise its own cause.

Source: lib/varops.x:172

Var.div

meta native Var Var.div(Var lhs, Var rhs)

Divides dynamic values through numeric or registered div behavior. Numeric integer zero divisors raise; floating division uses host infinity and NaN behavior. Other promotion, failure, and ownership follow Var.binary.

Source: lib/varops.x:245

Var.fallback_truth

int Var.fallback_truth(Var value)

Returns built-in truthiness without consulting a registered descriptor. Numeric and Symbol zero and null pointer-bearing values are false; other supported built-ins are true. Container-specific truth comes from dispatch.

Raises: <bad-enc> for invalid Var bits, <void-op> for void, or <bad-types> when no truthiness rule exists.

Source: lib/varops.x:585

Var.matmul

Var Var.matmul(Var lhs, Var rhs)

Multiplies matrices through a registered matmul behavior. @ has no numeric meaning, so numeric operands raise <bad-op>; a protocol result keeps the ownership chosen by its callback.

Source: lib/varops.x:237

Var.mod

meta native Var Var.mod(Var lhs, Var rhs)

Computes dynamic remainder through integer or registered mod behavior. Numeric operands use the common promoted integer type and reject a zero divisor; floating operands are not accepted. Other failure and ownership follow Var.binary.

Source: lib/varops.x:253

Var.mul

meta native Var Var.mul(Var lhs, Var rhs)

Multiplies dynamic values through numeric or registered mul behavior. Numeric promotion, failure, and result ownership follow Var.binary; a protocol result keeps the ownership chosen by its callback.

Source: lib/varops.x:230

Var.neg

meta native Var Var.neg(Var value)

Negates a dynamic value through registered neg or numeric subtraction. Without a selected protocol, this computes 0 - value with ordinary Var promotion and wrapping, so a narrow integer promotes before negation.

Raises: <bad-enc> for invalid bits, <void-op> for void, <no-member> for an object without neg, or any cause from protocol or numeric subtraction.

Source: lib/varops.x:282

Var.postfix

Var Var.postfix(Var &?lhs, Symbol op)

Applies dynamic postfix ++ or -- and returns the prior value. The update adds or subtracts an <i32> one through Var.update, preserving the destination tag. If a delegated protocol operation returns void, the function leaves the destination unchanged and returns void.

Raises: <bad-arg> for a null destination, <bad-enc> for invalid Var bits, <void-op> for void, <bad-op> for an operator other than ++ or --, or any cause from Var.update. These failures leave the stored value unchanged.

Source: lib/varops.x:661

Var.sub

meta native Var Var.sub(Var lhs, Var rhs)

Subtracts dynamic values through numeric or registered sub behavior. Numeric promotion, failure, and result ownership follow Var.binary; a protocol result keeps the ownership chosen by its callback.

Source: lib/varops.x:223

Var.truth

meta native int Var.truth(Var value)

Returns dynamic truthiness through registered dispatch or built-in rules. Numeric and Symbol zero and null unhandled pointer-bearing values are false; their nonzero or nonnull counterparts are true. A registered truth callback supplies its own result, including for a custom object, so it may return false independently of object state. The call does not retain value or inspect the contents of an iterator itself.

Raises: <bad-enc> for invalid Var bits, <void-op> for void, or <bad-types> when no truthiness rule exists, plus any cause raised by a selected descriptor callback.

Source: lib/varops.x:573

Var.update

Var Var.update(Var &?lhs, Symbol op, Var rhs)

Applies a failure-atomic dynamic compound update and returns the new value. The operation is limited to arithmetic, remainder, bitwise, and shift operators. The result is converted back to the destination’s original tag and stored only after both computation and conversion complete; this does not provide thread synchronization. If a delegated protocol operation returns void, the function leaves the destination unchanged.

Raises: <bad-arg> for a null destination, or any cause from Var.binary and Var.convert. These failures leave the stored value unchanged.

Source: lib/varops.x:616

Advanced and interop API

Functions

x2c_var_update_f32

float x2c_var_update_f32(volatile float *lhs, Symbol op, Var rhs)

Applies a dynamic compound op to a native float lvalue. The current value is boxed in its declared family, combined with rhs, converted back to that family, and stored only after all steps succeed. Returns the stored native value. This is failure-atomic but provides no thread synchronization despite accepting a volatile pointer.

Raises: <bad-arg> for a null lvalue, or any cause from Var.binary, Var.convert, or wide boxing. A transferring failure leaves the lvalue unchanged. If a delegated protocol operation returns void, the helper also leaves it unchanged and returns the native zero for float.

Source: lib/varops.x:124

x2c_var_update_f64

double x2c_var_update_f64(volatile double *lhs, Symbol op, Var rhs)

Applies a dynamic compound op to a native double lvalue. The current value is boxed in its declared family, combined with rhs, converted back to that family, and stored only after all steps succeed. Returns the stored native value. This is failure-atomic but provides no thread synchronization despite accepting a volatile pointer.

Raises: <bad-arg> for a null lvalue, or any cause from Var.binary, Var.convert, or wide boxing. A transferring failure leaves the lvalue unchanged. If a delegated protocol operation returns void, the helper also leaves it unchanged and returns the native zero for double.

Source: lib/varops.x:125

x2c_var_update_i16

short x2c_var_update_i16(volatile short *lhs, Symbol op, Var rhs)

Applies a dynamic compound op to a native short lvalue. The current value is boxed in its declared family, combined with rhs, converted back to that family, and stored only after all steps succeed. Returns the stored native value. This is failure-atomic but provides no thread synchronization despite accepting a volatile pointer.

Raises: <bad-arg> for a null lvalue, or any cause from Var.binary, Var.convert, or wide boxing. A transferring failure leaves the lvalue unchanged. If a delegated protocol operation returns void, the helper also leaves it unchanged and returns the native zero for short.

Source: lib/varops.x:116

x2c_var_update_i32

int x2c_var_update_i32(volatile int *lhs, Symbol op, Var rhs)

Applies a dynamic compound op to a native int lvalue. The current value is boxed in its declared family, combined with rhs, converted back to that family, and stored only after all steps succeed. Returns the stored native value. This is failure-atomic but provides no thread synchronization despite accepting a volatile pointer.

Raises: <bad-arg> for a null lvalue, or any cause from Var.binary, Var.convert, or wide boxing. A transferring failure leaves the lvalue unchanged. If a delegated protocol operation returns void, the helper also leaves it unchanged and returns the native zero for int.

Source: lib/varops.x:118

x2c_var_update_i8

char x2c_var_update_i8(volatile char *lhs, Symbol op, Var rhs)

Applies a dynamic compound op to a native char lvalue. The current value is boxed in its declared family, combined with rhs, converted back to that family, and stored only after all steps succeed. Returns the stored native value. This is failure-atomic but provides no thread synchronization despite accepting a volatile pointer.

Raises: <bad-arg> for a null lvalue, or any cause from Var.binary, Var.convert, or wide boxing. A transferring failure leaves the lvalue unchanged. If a delegated protocol operation returns void, the helper also leaves it unchanged and returns the native zero for char.

Source: lib/varops.x:113

x2c_var_update_long

long x2c_var_update_long(volatile long *lhs, Symbol op, Var rhs)

Applies a dynamic compound op to a native long lvalue. The current value is boxed in its declared family, combined with rhs, converted back to that family, and stored only after all steps succeed. Returns the stored native value. This is failure-atomic but provides no thread synchronization despite accepting a volatile pointer.

Raises: <bad-arg> for a null lvalue, or any cause from Var.binary, Var.convert, or wide boxing. A transferring failure leaves the lvalue unchanged. If a delegated protocol operation returns void, the helper also leaves it unchanged and returns the native zero for long.

Source: lib/varops.x:120

x2c_var_update_long_double

long double x2c_var_update_long_double(volatile long double *lhs, Symbol op, Var rhs)

Applies a dynamic compound op to a native long double lvalue. The current value is boxed in its declared family, combined with rhs, converted back to that family, and stored only after all steps succeed. Returns the stored native value. This is failure-atomic but provides no thread synchronization despite accepting a volatile pointer.

Raises: <bad-arg> for a null lvalue, or any cause from Var.binary, Var.convert, or wide boxing. A transferring failure leaves the lvalue unchanged. If a delegated protocol operation returns void, the helper also leaves it unchanged and returns the native zero for long double.

Source: lib/varops.x:126

x2c_var_update_long_long

long long x2c_var_update_long_long(volatile long long *lhs, Symbol op, Var rhs)

Applies a dynamic compound op to a native long long lvalue. The current value is boxed in its declared family, combined with rhs, converted back to that family, and stored only after all steps succeed. Returns the stored native value. This is failure-atomic but provides no thread synchronization despite accepting a volatile pointer.

Raises: <bad-arg> for a null lvalue, or any cause from Var.binary, Var.convert, or wide boxing. A transferring failure leaves the lvalue unchanged. If a delegated protocol operation returns void, the helper also leaves it unchanged and returns the native zero for long long.

Source: lib/varops.x:122

x2c_var_update_schar

signed char x2c_var_update_schar(volatile signed char *lhs, Symbol op, Var rhs)

Applies a dynamic compound op to a native signed char lvalue. The current value is boxed in its declared family, combined with rhs, converted back to that family, and stored only after all steps succeed. Returns the stored native value. This is failure-atomic but provides no thread synchronization despite accepting a volatile pointer.

Raises: <bad-arg> for a null lvalue, or any cause from Var.binary, Var.convert, or wide boxing. A transferring failure leaves the lvalue unchanged. If a delegated protocol operation returns void, the helper also leaves it unchanged and returns the native zero for signed char.

Source: lib/varops.x:114

x2c_var_update_u16

ushort x2c_var_update_u16(volatile ushort *lhs, Symbol op, Var rhs)

Applies a dynamic compound op to a native ushort lvalue. The current value is boxed in its declared family, combined with rhs, converted back to that family, and stored only after all steps succeed. Returns the stored native value. This is failure-atomic but provides no thread synchronization despite accepting a volatile pointer.

Raises: <bad-arg> for a null lvalue, or any cause from Var.binary, Var.convert, or wide boxing. A transferring failure leaves the lvalue unchanged. If a delegated protocol operation returns void, the helper also leaves it unchanged and returns the native zero for ushort.

Source: lib/varops.x:117

x2c_var_update_u32

uint x2c_var_update_u32(volatile uint *lhs, Symbol op, Var rhs)

Applies a dynamic compound op to a native uint lvalue. The current value is boxed in its declared family, combined with rhs, converted back to that family, and stored only after all steps succeed. Returns the stored native value. This is failure-atomic but provides no thread synchronization despite accepting a volatile pointer.

Raises: <bad-arg> for a null lvalue, or any cause from Var.binary, Var.convert, or wide boxing. A transferring failure leaves the lvalue unchanged. If a delegated protocol operation returns void, the helper also leaves it unchanged and returns the native zero for uint.

Source: lib/varops.x:119

x2c_var_update_u8

uchar x2c_var_update_u8(volatile uchar *lhs, Symbol op, Var rhs)

Applies a dynamic compound op to a native uchar lvalue. The current value is boxed in its declared family, combined with rhs, converted back to that family, and stored only after all steps succeed. Returns the stored native value. This is failure-atomic but provides no thread synchronization despite accepting a volatile pointer.

Raises: <bad-arg> for a null lvalue, or any cause from Var.binary, Var.convert, or wide boxing. A transferring failure leaves the lvalue unchanged. If a delegated protocol operation returns void, the helper also leaves it unchanged and returns the native zero for uchar.

Source: lib/varops.x:115

x2c_var_update_ulong

ulong x2c_var_update_ulong(volatile ulong *lhs, Symbol op, Var rhs)

Applies a dynamic compound op to a native ulong lvalue. The current value is boxed in its declared family, combined with rhs, converted back to that family, and stored only after all steps succeed. Returns the stored native value. This is failure-atomic but provides no thread synchronization despite accepting a volatile pointer.

Raises: <bad-arg> for a null lvalue, or any cause from Var.binary, Var.convert, or wide boxing. A transferring failure leaves the lvalue unchanged. If a delegated protocol operation returns void, the helper also leaves it unchanged and returns the native zero for ulong.

Source: lib/varops.x:121

x2c_var_update_ulong_long

unsigned long long x2c_var_update_ulong_long(volatile unsigned long long *lhs, Symbol op, Var rhs)

Applies a dynamic compound op to a native unsigned long long lvalue. The current value is boxed in its declared family, combined with rhs, converted back to that family, and stored only after all steps succeed. Returns the stored native value. This is failure-atomic but provides no thread synchronization despite accepting a volatile pointer.

Raises: <bad-arg> for a null lvalue, or any cause from Var.binary, Var.convert, or wide boxing. A transferring failure leaves the lvalue unchanged. If a delegated protocol operation returns void, the helper also leaves it unchanged and returns the native zero for unsigned long long.

Source: lib/varops.x:123

Design notes

Var arithmetic applies C-style numeric promotion to runtime tags, wraps integer results to the selected type’s width, and delegates eligible object operations through registered protocols. Comparisons of two numbers use the same promotion. Compound updates compute and convert completely before changing their destination.

Tests and examples

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