Appendix B: Operators and Symbols

This appendix is a complete reference for every operator and special symbol in VibeLang, including precedence rules, descriptions, and examples.

B.1 Operator Precedence Table

Operators listed from highest precedence (binds tightest) to lowest. All binary operators are left-associative unless noted.

When in doubt, use parentheses.

B.2 Arithmetic Operators

+ — Addition

Adds two numeric values. Also concatenates strings.

sum := 3 + 4            // 7
greeting := "hi" + "!"  // "hi!"

- — Subtraction / Negation

Binary subtraction or unary negation.

diff := 10 - 3   // 7
neg := -42        // -42

* — Multiplication

area := width * height

/ — Division

Integer division truncates toward zero. Division by zero is a runtime error.

half := 10 / 2      // 5
truncated := 7 / 3  // 2

% — Remainder

Returns the remainder of integer division. Result sign matches the dividend.

remainder := 17 % 5   // 2
is_even := n % 2 == 0

B.2a Bitwise Operators

Bitwise operators work on Int values only. They operate on the binary representation of integers.

& — Bitwise AND

mask := 255 & 15    // 15 (0xFF & 0x0F = 0x0F)
flag := value & 1   // extract lowest bit

| — Bitwise OR

combined := 5 | 3   // 7 (0b101 | 0b011 = 0b111)

^ — Bitwise XOR

toggled := 6 ^ 3    // 5 (0b110 ^ 0b011 = 0b101)

<< — Left Shift

doubled := 1 << 4   // 16 (shift 1 left by 4 positions)

>> — Right Shift (Arithmetic)

halved := 32 >> 2   // 8 (shift 32 right by 2 positions)

Bitwise operators are useful for flag manipulation, hash computation, encoding algorithms, and low-level data processing.

B.3 Comparison Operators

All comparison operators return Bool.

== / != — Equality

if status == 200 { println("OK") }
if name != "" { println(name) }

< / > / <= / >= — Ordering

if temperature < 0 { println("freezing") }
if score > high_score { high_score = score }
if retries <= MAX_RETRIES { attempt(request) }
if age >= 18 { println("eligible") }

B.4 Logical Operators

Logical operators work exclusively on Bool values. && and || short-circuit.

&& — Logical AND

Returns true only if both operands are true.

if is_valid && is_authorized { proceed() }

|| — Logical OR

Returns true if either operand is true.

if is_admin || is_owner { grant_access() }

! — Logical NOT

Unary prefix. Returns the boolean inverse.

if !found { println("not found") }

B.5 Assignment Operators

:= — Binding

Creates a new variable binding (immutable by default, mutable with mut).

name := "VibeLang"
mut counter := 0

= — Assignment

Reassigns a value to an existing mutable binding.

mut x := 10
x = 20

Using = on an immutable binding is a compile-time error.

B.6 Pipe Operator

|> — Pipe

Passes the left expression as the first argument to the function on the right. Enables readable left-to-right data transformation chains.

result := raw_input
  |> trim()
  |> parse_int()
  |> validate()

Equivalent without pipe: validate(parse_int(trim(raw_input))).

B.7 Range Operator

.. — Range

Creates a half-open range (start inclusive, end exclusive). Used in for loops and slice operations.

for i in 0..5 {
  println(i.to_str())  // 0, 1, 2, 3, 4
}

B.8 Error Propagation Operator

? — Propagate

Postfix on Result<T, E>. If the result is an error, the function returns it immediately. If success, the inner value is extracted.

pub read_text_file(path: Str) -> Result<Str, Error> {
  @effect io
  fs.read_text(path)?
}

json.parse returns Json, not Result, so it does not compose with ? the same way as fs.read_text. Combine file I/O with ?, then parse the Str when you are ready to handle invalid JSON (for example after json.is_valid, or via json.decode with a fallback value).

Only valid inside functions that return Result<T, E>.

B.9 Special Symbols

-> — Return Type Arrow

Separates a function's parameter list from its return type.

pub add(a: Int, b: Int) -> Int { a + b }

=> — Match Arm

Separates a pattern from its body in match and select branches.

match direction {
  "north" => move(0, 1)
  "south" => move(0, -1)
  _ => stay()
}

: — Type Annotation

Separates a name from its type in declarations, parameters, and struct fields.

pub type Config { host: Str, port: Int }

, — Separator

Separates items in arguments, list literals, map entries, and type parameters.

result := add(3, 4)
items := [1, 2, 3]

. — Member Access

Accesses a field or method on a value.

length := name.len()

@ — Annotation Prefix

Introduces a contract annotation: @intent, @examples, @require, @ensure, or @effect.

pub clamp(val: Int, lo: Int, hi: Int) -> Int {
  @intent "constrain val to [lo, hi]"
  @require lo <= hi
  @ensure . >= lo && . <= hi
  if val < lo { lo } else if val > hi { hi } else { val }
}

// — Line Comment

Everything after // on a line is ignored by the compiler.

{ } — Block Delimiters

Enclose function bodies, control flow branches, type definitions, and match arms.

( ) — Grouping / Call

Group sub-expressions or delimit function parameters and call arguments.

[ ] — List / Index

Create list literals or index into a list.

items := [10, 20, 30]
first := items[0]

B.10 Annotation Keywords

B.11 Quick Reference Card