Envzn operators

Every operator in the language, grouped by what it does: the symbols, the word operators, and the pipe-result sigils with their word forms. The normative rules live in ENVZN_CONSTITUTION.md (Part I.F.ii for arithmetic, comparison and bitwise; the grammar in Article III); this page is the quick reference.

Generated by bin/build_operators_doc.py from the compiler's lexer (compiler/parse/tokens.py). Do not edit by hand: change the generator and re-run it. The build fails if the lexer gains an operator this page does not describe.

Arithmetic

Operator Description
+ Adds two numbers, or joins two Strings. Integer overflow is a MathError PANIC, never a silent wrap.
- Subtracts the right operand from the left; as a prefix, negates its operand. Integer overflow PANICs.
* Multiplies two numbers. Integer overflow PANICs.
/ Divides the left operand by the right. Integer division by zero PANICs.
~/ Floor division: divides and rounds toward negative infinity (-7 ~/ 2 is -4). Spelled ~/ because // starts a comment.
% The remainder of integer division. A zero divisor PANICs.
^ Power: raises the left operand to the right, right-associative. It is not bitwise XOR, which is BXOR.
! Postfix factorial (n!). Integer overflow PANICs; != is lexed first, so it never collides.
# Hash-combine: folds two hash values into one with defined wraparound. The one arithmetic operator that never PANICs.
++ Increments a mutable numeric variable. Prefix ++i yields the new value, postfix i++ the old one.
-- Decrements a mutable numeric variable. Prefix --i yields the new value, postfix i-- the old one.

Wrapping arithmetic (integers only)

Operator Description
&+ Wrapping add: the true sum modulo 2ⁿ, never a PANIC. The sanctioned way to ask for modular arithmetic.
&- Wrapping subtract: the true difference modulo 2ⁿ, never a PANIC.
&* Wrapping multiply: the low n bits of the full product, never a PANIC.

Comparison

Operator Description
== Value equality. On floats it is exact IEEE equality, so NaN == NaN is FALSE.
!= Value inequality, the negation of ==.
< Less than. An ordering comparison on a complex operand is an error (E2118).
<= Less than or equal.
> Greater than.
>= Greater than or equal.
≈ Approximate equality for number operands (U+2248): a relative tolerance with an absolute floor. It has no ASCII spelling.
≉ Not approximately equal (U+2249), the negation of ≈.
BEQUALS Bit-pattern equality: compares the raw bits of two values rather than the values themselves.
BNEQUALS Bit-pattern inequality, the negation of BEQUALS.

Logical

Operator Description
AND Boolean and. Each clause of a compound condition is parenthesized (I.H.i).
OR Boolean or.
XOR Boolean exclusive or: TRUE when exactly one side is TRUE.
NOT Boolean negation.

Bitwise and shift (integers)

Operator Description
BAND Bitwise and.
BOR Bitwise or.
BXOR Bitwise exclusive or.
BNOT Bitwise complement: flips every bit of its operand.
LSHIFT Shifts left by a count. A count at or past the bit width is an error when provable (E2130), otherwise a PANIC.
RSHIFT Logical right shift: the vacated high bits are filled with zeros.
ASHIFT Arithmetic right shift: the vacated high bits copy the sign bit.
LROTATE Rotates the bits left; bits shifted out re-enter at the low end.
RROTATE Rotates the bits right; bits shifted out re-enter at the high end.

Assignment and binding

Operator Description
= Binds a value: any primitive, value class, STATUS or enum expression. A String takes only a literal, and any other class only EMPTY.
:= Binds ownership: construct (CREATE), copy (DUPLICATE) or move. A moved-from local cannot be read again.
=@ Binds a non-owning reference to an existing value (REFERENCE T r =@ x).
+= x += e means x = x + e, with +'s overflow rules. A statement on a plain local variable only.
-= x -= e means x = x - e.
*= x *= e means x = x * e.
/= x /= e means x = x / e.
%= x %= e means x = x % e.

Absence, type tests and conversion

Operator Description
?? Coalescing read: a ?? b is a when it is present, otherwise b.
IS VALID Presence test on a class-typed binding; narrows it to present inside the THEN branch. IS NOT VALID is the negation.
IS Compile-time type test in WHEN and MATCH (WHEN T IS String). IS NOT negates it, and IS PRIMITIVE tests for any primitive.
AS A checked conversion that can fail: narrowing or reinterpreting, range-checked at run time, never a silent truncation (int64 AS int32).
INTO A lossless conversion into a type that can represent every source value (int32 INTO int64, 42 INTO String).

Set algebra (on Set)

Operator Description
\|+\| Union: a new Set holding every element of either operand. Both operands must be Sets (E2034).
\|&\| Intersection: a new Set holding the elements present in both operands.
\|-\| Difference: a new Set holding the elements of the left operand that are not in the right.

Access and structure

Operator Description
-> Calls a method on an object: obj->method(args).
:: Qualifies a name with its module or namespace: Json::Parser, FOREIGN::open.
... Marks a variadic parameter: Type... name.
=> Attaches the message to ASSERT(cond) => msg and UNREACHABLE! => msg. Reserved everywhere else (E1023).

Pipe-result sigils (inside a pipe-XOR IF / WHILE)

Operator Description
$= The success value in the success branch; $=[1] reads a second slot.
$RETURNED The word form of $=.
$! The failure message (a String) in the failure branch.
$ERR_MESSAGE The word form of $!.
$# The failure's numeric code (int32; 0 when none was supplied) in the failure branch.
$ERR_CODE The word form of $#.
$? Discards a returned slot: $? := call(), or a $? slot in a multi-value receive.

FOREIGN BIND owned-return markers

Operator Description
$* The C result is owned by the caller: copy it into the Envzn value, then free() it.
$(freer) As $*, but frees with the named C function: $(sqlite3_free).

Lexed, but not operators

Token Why it is lexed
& Lexed only so a C++-style & before a parameter is reported (E7009); Envzn has no address-of operator.