lib/varops.x

Boxed Var operators, updates, and truthiness.

Primary API

Var

Var.add

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

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. 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:600

Var.div

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

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

Var.mod

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

Var.mul

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

Var.neg

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

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

Var.sub

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

Var.truth

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

Var.truthy

int Var.truthy(Var value)

Returns value.truth() under the compatibility spelling truthy.

Source: lib/varops.x:500

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

Advanced and interop API

Functions

x2c_array_updateindex_from_array

Var x2c_array_updateindex_from_array( Array dst, int dst_index, Symbol op, Array src, int src_index)

Updates an Array element after capturing one source Array element. The source read completes before the destination update, including when both arguments name the same Array and slot. Result, mutation, bounds, conversion, and failure behavior then follow Array.updateindex.

Raises: <bad-arg> for a null source, plus any cause from the source read or destination update. A transferring failure leaves the destination unchanged.

Source: lib/varops.x:97

x2c_array_updateindex_from_map

Var x2c_array_updateindex_from_map( Array dst, int dst_index, Symbol op, Map src, Var src_key)

Updates an Array element after capturing one source Map value. The source lookup completes before the destination update, including when the containers share stored objects. A missing source key supplies void, which the destination rejects without mutation. Other result and failure behavior follows Map.getindex and Array.updateindex.

Source: lib/varops.x:113

x2c_map_updateindex_from_array

Var x2c_map_updateindex_from_array( Map dst, Var dst_key, Symbol op, Array src, int src_index)

Updates a Map value after capturing one source Array element. The source read completes before lookup or mutation of the destination. An out-of-range source supplies void, which the destination rejects. Other result and failure behavior follows Array.getindex and Map.updateindex.

Raises: <bad-arg> for a null source, plus any cause from either operation.

Source: lib/varops.x:129

x2c_map_updateindex_from_map

Var x2c_map_updateindex_from_map( Map dst, Var dst_key, Symbol op, Map src, Var src_key)

Updates a Map value after capturing one source Map value. The source lookup completes before the destination update, including a same-Map, same-key update. A missing source supplies void, which the destination rejects. Other result and failure behavior follows the two Map operations.

Source: lib/varops.x:146

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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. Compound updates compute and convert completely before changing their destination.

Tests and examples

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