> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gorules.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Operators

> Complete reference for ZEN expression operators.

ZEN provides operators for arithmetic, comparison, logic, and data manipulation.

## Arithmetic operators

Perform mathematical calculations on numbers.

| Operator | Name               | Example  | Result |
| -------- | ------------------ | -------- | ------ |
| `+`      | Addition           | `5 + 3`  | `8`    |
| `-`      | Subtraction        | `10 - 4` | `6`    |
| `*`      | Multiplication     | `6 * 7`  | `42`   |
| `/`      | Division           | `15 / 3` | `5`    |
| `%`      | Modulo (remainder) | `17 % 5` | `2`    |
| `^`      | Power              | `2 ^ 10` | `1024` |

### Operator precedence

Operations follow standard mathematical precedence:

1. `^` (power)
2. `*`, `/`, `%` (multiply, divide, modulo)
3. `+`, `-` (add, subtract)

Use parentheses to control order:

```
(5 + 3) * 2    // 16, not 11
10 / (2 + 3)   // 2, not 7
```

## Comparison operators

Compare values and return boolean results.

| Operator | Name             | Example  | Result |
| -------- | ---------------- | -------- | ------ |
| `==`     | Equal            | `5 == 5` | `true` |
| `!=`     | Not equal        | `5 != 3` | `true` |
| `>`      | Greater than     | `10 > 5` | `true` |
| `<`      | Less than        | `3 < 10` | `true` |
| `>=`     | Greater or equal | `5 >= 5` | `true` |
| `<=`     | Less or equal    | `3 <= 5` | `true` |

## Logical operators

Combine boolean conditions.

| Operator | Name        | Example          | Result  |
| -------- | ----------- | ---------------- | ------- |
| `and`    | Logical AND | `true and false` | `false` |
| `or`     | Logical OR  | `true or false`  | `true`  |
| `not`    | Logical NOT | `not true`       | `false` |

### Short-circuit evaluation

Logical operators stop early when the result is determined:

```
false and expensiveFunction()   // Never calls the function
true or expensiveFunction()     // Never calls the function
```

## Ternary operator

Conditionally return one of two values.

```
condition ? valueIfTrue : valueIfFalse
```

**Examples:**

```
age >= 18 ? "adult" : "minor"
score >= 70 ? "pass" : "fail"
stock > 0 ? "In Stock" : "Out of Stock"
```

**Nested ternary:**

```
score >= 90 ? "A" : score >= 80 ? "B" : score >= 70 ? "C" : "F"
```

## Null coalescing operator

Return the first non-null value.

```
value ?? fallback
```

**Examples:**

```
user.nickname ?? user.name              // Use nickname, fall back to name
config.timeout ?? 30                    // Use config or default to 30
a ?? b ?? c ?? "default"                // Chain multiple fallbacks
```

## Membership operators

Check if a value exists in a collection or range.

### In operator

```
// Array membership
"US" in ["US", "CA", "GB"]              // true
5 in [1, 2, 3, 4, 5]                    // true

// Range membership (inclusive)
x in [1..10]                            // true if 1 <= x <= 10

// Range membership (exclusive)
x in (0..100)                           // true if 0 < x < 100

// Mixed brackets
x in [0..100)                           // true if 0 <= x < 100
x in (0..100]                           // true if 0 < x <= 100
```

### Not in operator

Negate membership tests:

```
status not in ["deleted", "archived"]
x not in [0..100]
```

## String operators

### Concatenation

The `+` operator joins strings:

```
"Hello" + " " + "World"                 // "Hello World"
"Order #" + string(orderId)             // "Order #12345"
firstName + " " + lastName              // "John Doe"
```

### Template strings

Embed expressions in strings:

```
`Hello, ${name}!`
`Total: ${round(total, 2)}`
`Items: ${len(items)}`
```

## Array operators

### Index access

```
items[0]                                // First item
items[len(items) - 1]                 // Last item
items[-1]                               // Last item (negative index)
```

## Object operators

### Property access

```
user.name                               // Dot notation
user["name"]                            // Bracket notation
user[fieldName]                         // Dynamic key
```

### Optional chaining

Access nested properties is optional:

```
user.address.city    // Returns null if any part is null
```

## Operator precedence table

From highest to lowest precedence:

| Precedence | Operators                                        |
| ---------- | ------------------------------------------------ |
| 1          | `()` (grouping)                                  |
| 2          | `.`, `[]` (property access)                      |
| 3          | `+`, `-` (unary)                                 |
| 4          | `??` (null coalescing)                           |
| 5          | `^` (power, right-associative)                   |
| 6          | `*`, `/`, `%`                                    |
| 7          | `not` (unary)                                    |
| 8          | `+`, `-` (binary)                                |
| 9          | `==`, `!=`, `<`, `>`, `<=`, `>=`, `in`, `not in` |
| 10         | `and`                                            |
| 11         | `or`                                             |
| 12         | `? :` (ternary)                                  |