Operators

Operators perform operations on values (operands).

Arithmetic Operators

Addition (+)

1val sum: i32 = 10 + 20      // 302val total: f64 = 3.14 + 2.86  // 6.00

Types: Works with numeric types (integers and floats), and with string (concatenation) Requirement: Both operands must be the same type

On two strings, + is concatenation: it allocates a new owned, immutable string holding the left operand's bytes followed by the right operand's. A &string slice may stand in for either side. Operands are read, not consumed, so they remain usable afterward.

1val greeting: string = "Hello, " + "Neuro!"   // "Hello, Neuro!"2val a: string = "ab"3val b: string = "cd"4val joined: string = a + &b                   // "abcd"; a and b still valid

The concatenated buffer is heap-allocated. Deterministic Drop landed with 1C, so it is freed where the compiler can prove who owns it: a temporary the statement consumes, or a binding whose initializer allocated it. One that escapes that analysis still leaks, notably a heap string stored into a collection or a struct field, returned from a function, or displaced by reassigning its binding. See the alpha memory warning in the README.

Subtraction (-)

1val diff: i32 = 50 - 20     // 302val delta: f64 = 10.5 - 2.3  // 8.2

Types: Works with numeric types Requirement: Both operands must be the same type

Multiplication (*)

1val product: i32 = 6 * 7    // 422val area: f64 = 3.14 * 2.0  // 6.28

Types: Works with numeric types Requirement: Both operands must be the same type

Division (/)

1val quotient: i32 = 20 / 4  // 52val ratio: f64 = 10.0 / 3.0  // 3.333...

Types: Works with numeric types Requirement: Both operands must be the same type Note: Integer division truncates (5 / 2 = 2)

Modulo (%)

1val remainder: i32 = 17 % 5  // 22val mod: i32 = 10 % 3        // 1

Types: Works with integer types Requirement: Both operands must be integers

Comparison Operators

All comparison operators return bool.

Equal (==)

1val is_equal: bool = 42 == 42  // true2val same: bool = x == y

Not Equal (!=)

1val is_different: bool = 42 != 10  // true2val not_same: bool = x != y

Less Than (<)

1val is_less: bool = 5 < 10  // true2val smaller: bool = x < y

Greater Than (>)

1val is_greater: bool = 10 > 5  // true2val larger: bool = x > y

Less Than or Equal (<=)

1val is_lte: bool = 5 <= 5  // true2val at_most: bool = x <= max

Greater Than or Equal (>=)

1val is_gte: bool = 10 >= 5  // true2val at_least: bool = x >= min

Types: Work with numeric types, booleans, and strings (==/!= only) Requirement: Both operands must be the same type Chaining: Comparison operators cannot be chained. a < b < c is a compile error, write a < b && b < c instead.

Logical Operators

Work with boolean values, return boolean.

Logical AND (&&)

1val both: bool = true && true    // true2val result: bool = flag1 && flag23val valid: bool = x > 0 && x < 100

Short-circuit: If left side is false, right side is not evaluated

Logical OR (||)

1val either: bool = true || false  // true2val result: bool = flag1 || flag23val valid: bool = x < 0 || x > 100

Short-circuit: If left side is true, right side is not evaluated

Logical NOT (!)

1val inverted: bool = !true  // false2val opposite: bool = !flag

Unary operator: Takes single boolean operand

Unary Operators

Negation (-)

1val neg: i32 = -42       // -422val opposite: i32 = -x3val abs_neg: i32 = -abs(x)

Types: Works with numeric types Returns: Same type as operand

On an integer, -x is 0 - x and follows the same overflow rule as the subtraction: it panics in debug builds and wraps in release ones. That makes it an overflow at a signed type's MIN, and at every nonzero value of an unsigned type — see integer overflow.

Logical NOT (!)

1val not_true: bool = !true  // false2val not_flag: bool = !flag

Types: Works with boolean type only Returns: boolean

Bitwise Operators

Work with integer values only (i8 to i64, u8 to u64). Cannot be used with floats or bools.

Bitwise AND (&)

1val a: i32 = 0b1100   // 122val b: i32 = 0b1010   // 103val r: i32 = a & b    // 0b1000 = 8

Returns: same type as operands

Bitwise OR (|)

1val a: i32 = 0b1100   // 122val b: i32 = 0b1010   // 103val r: i32 = a | b    // 0b1110 = 14

Returns: same type as operands

Bitwise XOR (^)

1val a: i32 = 0b1100   // 122val b: i32 = 0b1010   // 103val r: i32 = a ^ b    // 0b0110 = 6

Returns: same type as operands

Left Shift (<<)

1val a: i32 = 12val r: i32 = a << 4   // 1 * 2^4 = 16

Returns: same type as operands Note: Right shift is exposed as the .shr(n) method, not an operator (ashr for signed receivers, lshr for unsigned). See types.md.

Bitwise NOT (~)

1val a: i32 = 02val r: i32 = ~a       // -1 (all bits set, two's complement)

Unary: takes a single integer operand Returns: same type as operand

Type Casting Operator (as)

Performs an explicit numeric or boolean type conversion.

1val n: i32 = 422val x: f64 = n as f64          // widen integer to float3val y: i64 = n as i64          // widen to larger integer4 5val pi: f64 = 3.141596val trunc: i32 = pi as i32     // truncate toward zero → 37 8val flag: bool = true9val one: i32 = flag as i32     // false → 0, true → 1

Types: Works with numeric types and booleans. Rules:

• Widening integers zero-extends (unsigned) or sign-extends (signed).
• Floats to integers truncate towards zero.
• Booleans to integers map false → 0 and true → 1.

Assignment Operator (=)

Variable Assignment

1mut x: i32 = 102x = 20              // Reassign3x = x + 5           // Update4x = add(x, 10)      // Assign from expression

Requirement: Variable must be declared with mut Type checking: Right-hand side must match variable type

Cannot Assign to Immutable

1val x: i32 = 102// x = 20  // Error: cannot assign to immutable variable

Compound Assignment Operators

Shorthand for updating a mutable variable in-place. Each form is equivalent to a plain assignment with the corresponding binary operator on the right-hand side.

1mut score: i32 = 1002score += 50    // 1503score -= 25    // 1254score *= 2     // 2505score /= 5     // 506score %= 13    // 11

1mut sum: i32 = 02mut i: i32 = 13while i <= 10 {4    sum += i5    i += 16}

Requirement: Left-hand side must be a mut variable Type checking: Same rules as the underlying binary operator apply Note: Compound assignment on struct fields (point.x += 1.0) is not yet supported

Null/Error Coalescing Operator (??)

?? is the read-site equivalent of unwrap_or(default), it returns the unwrapped value of an Option<T> or Result<T, E> when present, and falls back to the right-hand expression when absent (None) or failed (Err). The expression's type is the unwrapped payload T.

1val present = lookup(1) ?? 0        // the Some payload2val absent  = lookup(7) ?? 5        // 5, the fallback3 4val ok     = divide(24, 4) ?? 0     // the Ok payload5val failed = divide(1, 0)  ?? 4     // 4, the Err payload is discarded

For a Result, the error payload is discarded: ?? states "I do not care why it failed, use this instead". When the reason matters, match on the value instead.

Laziness: the fallback is only evaluated when the left-hand side is absent or failed. A fallback that calls a function, panics, or does real work is skipped entirely when the value is present.

Fallback type: the right-hand side must produce the payload type T, not another Option/Result. A mismatch is an ordinary type error.

Associativity: right-to-left. a ?? b ?? c parses as a ?? (b ?? c), so each fallback is evaluated only when every left-hand side up to it has produced the absent / error variant. Left-to-right would force the middle fallback even when the chain succeeds early, defeating the short-circuit contract. In a chain, every operand but the last must itself be fallible:

1val chained = lookup(7) ?? lookup(1) ?? 99

Precedence: level 14, looser than || (so a ?? b || c means a ?? (b || c)), tighter than range operators.

Applying ?? to anything that is not an Option<T> or Result<T, E> is rejected:

Payloads are scalar Copy values in this phase (see types.md), so ?? unwraps to a scalar. Runnable program: examples/operators/null_coalesce.nr.

Error Propagation Operator (?)

? is the postfix complement of ??: instead of supplying a fallback, it hands the failure to the caller. expr? evaluates to the unwrapped payload when expr is Some / Ok, and otherwise leaves the enclosing function immediately, carrying the failure variant on.

1func quarter(n: i32) -> Result<i32, i32> {2    val half = halve(n)?     // Err(n) leaves quarter() right here3    val rest = halve(half)?4    Result::Ok(rest)5}

It desugars to exactly this match:

1val half = match halve(n) {2    Result::Ok(v)  => v,3    Result::Err(e) => return Result::Err(e)4}

Enclosing function: the function containing the ? must return the same fallible enum, a Result propagates only out of a -> Result<_, _> function, an Option only out of a -> Option<_> one. Otherwise the failure has nowhere to go:

No conversion: the error travels as-is. There is no From/Into trait system, so the callee's E must already be the caller's E; a mismatch is an ordinary type error. Convert first with .map_err(...) when the types differ.

Payload types are independent: only the error types must agree. ? on a Result<bool, E> inside a -> Result<i32, E> function is fine, the unwrapped bool is used locally, not returned.

Short-circuiting: nothing after a failing ? runs, including the rest of a loop body, ? returns from the function, not from the iteration.

Precedence: postfix, binding as tightly as a call or index. f(x)? + 1 adds to the unwrapped payload, and parse(s)?.field reads a field of the unwrapped value.

Runnable program: examples/operators/error_propagation.nr.

When the reason for a failure should be handled rather than forwarded, use match, ?? for a fallback, or val-else to unwrap or leave the scope.

Operator Precedence

From highest to lowest, matching the parser's Pratt ladder:

Comparison binds tighter than equality: x < y == z parses as (x < y) == z. There is no >> operator; right shift is the .shr(n) method because >> is reserved for function composition. |

Precedence Examples

1a + b * c       // Same as: a + (b * c)2a * b + c       // Same as: (a * b) + c3a < b == c < d  // Same as: (a < b) == (c < d)4!a && b         // Same as: (!a) && b5a || b && c     // Same as: a || (b && c)

Using Parentheses

1(a + b) * c     // Force addition first2a * (b + c)     // Force addition before multiplication3(a && b) || c   // Force AND before OR (though same as default)

Type Requirements

Numeric Operators

+, -, *, / work with:

• i8, i16, i32, i64
• u8, u16, u32, u64
• f32, f64

Both operands must be the same type.

+ additionally works on string (and &string) as concatenation, producing a new owned string. The other arithmetic operators have no string meaning.

Integer-Only Operators

%, &, |, ^, ~, << work only with integer types:

• i8, i16, i32, i64
• u8, u16, u32, u64

Comparison Operators

==, !=, <, >, <=, >= work with:

• All numeric types (same type required)
  • Note: Float comparison (f32, f64) utilizes native IEEE-754 ordered predicates. Comparisons involving NaN will naturally return false.
• bool (only == and !=)
• char, which has a built-in total order over its Unicode scalar values
• string (only == and !=), byte-level equality via length check + memcmp
• a newtype over any of the above, which compares as its inner type does

Nothing else has comparison built in. A struct gets == / != from impl PartialEq and the ordering operators from impl Comparable (see Operator Overloading); comparing one that implements neither is a type error naming the missing trait. Arrays, tuples, enums and collections have no equality at all yet, and neither does a reference to anything but a string — read through it with * first.

Logical Operators

&&, ||, ! work only with bool

Common Patterns

Range Checking

1val in_range: bool = x >= min && x <= max2val out_of_range: bool = x < min || x > max

Clamping

1val clamped: i32 = if x < min { min } else if x > max { max } else { x }

Sign Determination

1val sign: i32 = if x > 0 { 1 } else if x < 0 { -1 } else { 0 }

Absolute Value

1val abs: i32 = if x >= 0 { x } else { -x }

Common Mistakes

Type Mismatch

1val x: i32 = 102val y: f64 = 3.143// val z = x + y  // Error: cannot add i32 and f64

Integer Division

1val result: i32 = 5 / 2  // Result is 2, not 2.5

Use floats for decimal division:

1val result: f64 = 5.0 / 2.0  // Result is 2.5

Boolean Comparison

1val flag: bool = true2// if flag == true { }  // Redundant3if flag { }             // Better

Operator Overloading

Operators on a custom type are sugar for method calls. Implement the corresponding operator trait to make an operator work on your type. The operator traits are built into the compiler: you write only the impl, never a trait declaration.

An arithmetic, bitwise, or unary operator trait declares its result type with type Output = T:

1@derive(Copy, Clone)2struct Vec2 { x: i32, y: i32 }3 4impl Add for Vec2 {5    type Output = Vec26    func add(self, rhs: Vec2) -> Vec2 {7        Vec2 { x: self.x + rhs.x, y: self.y + rhs.y }8    }9}10 11impl Neg for Vec2 {12    type Output = Vec213    func neg(self) -> Vec2 { Vec2 { x: -self.x, y: -self.y } }14}15 16val c = Vec2 { x: 1, y: 2 } + Vec2 { x: 3, y: 4 }   // (4, 6), via Add::add17val d = -c                                          // (-4, -6), via Neg::neg

Comparison uses PartialEq (equality) and Comparable (ordering); their methods take &self and rhs: &Self and return bool. Comparable requires PartialEq on the same type:

1impl PartialEq for Vec2 {2    func eq(&self, rhs: &Vec2) -> bool { self.x == rhs.x && self.y == rhs.y }3    func ne(&self, rhs: &Vec2) -> bool { self.x != rhs.x || self.y != rhs.y }4}5 6if Vec2 { x: 1, y: 2 } == Vec2 { x: 1, y: 2 } { }   // via PartialEq::eq

Operator → trait → method:

Rules and limits:

• The receiver type must be Copy (the scalar path). Each operator dispatches to its own method; implement the method for every operator you use.
• A declared type Output must match the method's return type.
• The logical !a (boolean NOT) is not overloadable: it is always boolean negation.
• Compound assignment (v += w) works when the type implements the matching by-value operator: it desugars to v = v + w. Dedicated in-place *Assign traits, matrix multiply @, and auto-derived comparison defaults are planned for later phases.
• Operator overloading is fully monomorphized and erased: each operator becomes the method call it stands for, with no vtable and no runtime cost.

See examples/operators/operator_overloading.nr for a complete program.

References

• Types - Type requirements for operators
• Expressions - Operator precedence and evaluation
• Variables - Assignment operator