> For the complete documentation index, see [llms.txt](https://boxlang.ortusbooks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://boxlang.ortusbooks.com/boxlang-language/syntax/operators.md).
# Operators
**Operators** are the foundation of **any** programming language. Operators are symbols that help a programmer to perform specific mathematical, structuring, destructuring, and logical computations on operands (variables or expressions). We can categorize the BoxLang operators into the following categories:
1. Arithmetic/Mathematical
2. Assignment
3. Logical
4. Comparison
5. Ternary
6. Elvis (Null Coalescing)
7. Function
8. Collections
{% hint style="danger" %}
BoxLang does not offer the capability to overload operators like other languages.
{% endhint %}
## 📊 Operator Precedence
The order of precedence exists in BoxLang, just like in mathematics. You can also control the order of precedence by using the grouping operator `()` like in mathematics, the magical ordering parenthesis.
{% code lineNumbers="true" %}
```javascript
^
*, /
\
MOD
+, -
..
&
EQ, NEQ, LT, LTE, GT, GTE, CONTAINS, DOES NOT CONTAIN, ==, !=, >, >=, <, <=
NOT, !
AND, &&
OR, ||
XOR
EQV
IMP
```
{% endcode %}
{% hint style="success" %}
Remember that using parenthesis `(Grouping Operator)` is very important to denote precedence.
{% endhint %}
## ➕ Arithmetic Operators
These operators are used to perform arithmetic/mathematical operations on operands.
| Operator | Name | Description |
| -------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `+` | Add | `a = 1 + 4` |
| `-` | Subtract | `a = 4 - 2` |
| `*` | Multiply | `a = 4 * b` |
| `/` | Divide | `a = 4 / myVariable` |
| `^` | Exponentiate | `a = 2^2 // 4` |
| `%, MOD` | Modulus / Remainder | `5 % 2 = 1` or `5 mod 2` |
| `\` | Integer Divide | `a = 7 \ 3` is 2. Please note it does not round off the integer. |
| `..` | Inclusive Range | Creates a lazy Range object (not an array).
1..5 → Range(1,2,3,4,5)
5..1 → Range(5,4,3,2,1)
See Ranges for full documentation.
|
| `>..` | Range (exclude start) | Range excluding the start value.
1>..5 → Range(2,3,4,5)
|
| `..<` | Range (exclude end) | Range excluding the end value.
1..<5 → Range(1,2,3,4)
|
| `>..<` | Range (exclude both) | Range excluding both boundaries.
1>..<5 → Range(2,3,4)
|
| `++` | Increment | a = b++ assign b to a and THEN increment b
a = ++b increment b and THEN assign to a
|
| `--` | Decrement | a = b-- assign b to a and THEN decrement b
a = --b decrement b and THEN assign to a
|
| `-` | Negate | `a = -b` Negate the value of b |
| `+` | Positive | `a = +b` Make the value of b a positive number |
| `()` | Grouping | The grouping operator is used just like in mathematics, to give precedence to operations.
result = 3 \* (2+3) which is not the same as
result = 3 \* 2 + 3
|
### 📏 Range Operators
{% hint style="info" %}
Since BoxLang 1.14.0
{% endhint %}
BoxLang supports **Range operators** that create first-class `Range` objects — lazy, iterable intervals that support multiple types (integers, decimals, characters, dates, and custom `IRangeable` types), exclusive boundaries, custom stepping, and Java Stream integration.
**Basic range syntax:**
```javascript
// Inclusive range (both ends included)
1..5 // Range: 1, 2, 3, 4, 5
5..1 // Range: 5, 4, 3, 2, 1 (descending)
// Exclusive boundaries
1>..5 // Exclude start: 2, 3, 4, 5
1..<5 // Exclude end: 1, 2, 3, 4
1>..<5 // Exclude both: 2, 3, 4
// Half-bounded and unbounded
1.. // Open-ended from 1 (infinite)
..10 // Open-start up to 10 (not iterable)
.. // Fully unbounded (contains everything)
// Using expressions
a = 2
b = 4
result = a..b // Range: 2, 3, 4
```
Ranges are **not arrays** — they're lightweight objects that generate values on demand:
```javascript
// Coerce to array when needed
arrayLen( 1..10 ) // 10
arrayToList( 1..5, "," ) // "1,2,3,4,5"
// Lazy iteration
for( i in 1..100_000_000_000 ) {
result = i
break // instant — no memory allocation
}
```
{% hint style="success" %}
For complete documentation on Ranges including custom stepping, typed ranges, Java Stream integration, and creating custom `IRangeable` types, see [**Ranges**](/boxlang-language/syntax/ranges.md).
{% endhint %}
#### Notes on mathematical casting:
For basic arithmetic operations (addition, subtraction, multiplication, and division), dates and time spans may be cast as numeric values. In BoxLang, the numeric value of a [DateTime](/boxlang-framework/modularity/compat-cfml/reference/types/datetime.md) object represents the number of decimal days since the Unix epoch. A [timespan](/boxlang-language/reference/built-in-functions/temporal/createtimespan.md) or Java [Duration](https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/time/Duration.html) object is represented as decimal days for the purpose of mathematical operations.
## 🔢 Bitwise Operators
{% hint style="info" %}
BoxLang has native [bitwise](https://en.wikipedia.org/wiki/Bitwise_operation) operators, and it also implements bitwise operations via functions (since functions can also be operators in BoxLang): `bitAnd, bitMaskClear, bitMaskRead, bitMaskSet, bitNot, bitOr, bitSHLN, bitSHRN, bitXOR` . You can find much more information here:
{% endhint %}
These operators are used to perform bitwise operations on operands.
The bitwise operators look a bit different in BoxLang vs other languages like Java since the normal bitwise operators are already used for other purposes in BoxLang.
| Operator | Name | Description |
|---|
b| | Bitwise OR | a = 12 b| 25 |
b& | Bitwise AND | a = 5 b& 9 |
b^ | Bitwise XOR | a = 10 b^ 12 |
b~ | Bitwise Complement | a = b~ 35 |
b<< | Bitwise Signed Left Shift | a = 14 b<< 4 |
b>> | Bitwise Signed Right Shift | a = 4 b>> 2 |
b>>> | Bitwise Unsigned Right Shift | a = 25 b>>> 3 |
{% hint style="success" %}
For more information about bitwise operations, you can read more here:
{% endhint %}
## ✏️ Assignment Operators
These operators are usually used for compound evaluations and assignments.
| Operator | Name | Description |
| -------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `=` | Assignment | a = 5 The way to assign a value to a variable. You can also assign them to multiple variables by chaining them:
a=b=c=5 which is the same as saying:
a=5;b=5;c=5
|
| `+=` | Compound Add | `a += b` is equivalent to `a = a + b` |
| `-=` | Compound Substract | `a -= b` is equivalent to `a = a - b` |
| `*=` | Compound Multiply | `a *= b` is equivalent to `a = a * b` |
| `/+` | Compound Divide | `a /= b` is equivalent to `a = a / b` |
| `%=` | Compound Modulus | `a %= b` is equivalent to `a = a % b` |
| `&=` | Compound Concatenation | A way to concatenate strings together
a = "hello "
a &= "luis" The result will be hello luis
|
| `&` | Concatenation | Concatenates two strings: `"Hola" & space & "Luis"` |
## 🔀 Logical Operators
Logical operators perform logic between values or values, usually denoting a `boolean` result.
| Operator | Name | Description |
| ---------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `!,NOT` | Negation | `!true = false` or `a = not true` |
| `&&,AND` | And | Returns true if both operands are true.
a = b && c
|
| `\|\|, OR` | Or | Returns true if either operand is true.
a = b
|
| `XOR` | Exclusive Or | Returns true when either of the operands is true (one is true, and the other is false), but both are not true, and both are not false.
true XOR true = false
true XOR false = true
false XOR false = false
|
| `EQV` | Equivalence | The exact opposite of an exclusive or. Meaning that it will return true when both operands are either true or false.
true EQV true = true
true EQV false = false
false EQV false = true
|
| `IMP` | Implication | A implies B is equivalent to `if a then b`. A imp b is false ONLY if a is true and b is false; else, it returns true always. |
## Comparison Operators
Comparison operators are used when comparing two values, expressions, or variables. The return of a comparison is either `true` or `false`.
| Operator | Name | Description |
| --------------------------------------------------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `eq, ==` | Equality | True if `a eq b` or `a == b` |
| neq,
!=,
<>
| Not Equal | The opposite of equality: `a neq b, a != b, a <> b` |
| `===` | Identity / Strict Equality | Returns true if the operands are equal in value and type, with type-aware normalization within BoxLang type families (no cross-type coercion). See type rules below.
2 === "2" // false
2 === 2 // true
1 === 1.0 // true
"brad" === "BRAD" // true
|
| `!===` | Negated Identity | Same as the identity operator but negating the result. |
| `gt, >` | Greater than | If the left operand is greater in value than the right operand |
| `gte, >=` | Greater than o equal | If the left operand is greater than or equal in value than the right operand |
| `lt, <` | Less than | If the left operand is less than in value than the right operand |
| `lte, <=` | Less than or equal | If the left operand is less than or equal in value than the right operand |
| `contains, ct` | Contains | Returns true if the left operand contains the right one.
'hello' contains 'lo'
|
| `does not contain, nct` | Negated contains | Returns true if the left operand does NOT contain the right one.
'hello' does not contain 'pio'
|
| `instanceOf` | Type checking | Returns true if the left operand is an instance of the right type.
true instanceOf 'Boolean'
'brad' instanceOf 'java.lang.String'
|
| `castAs` | Type casting | Casts the left operand to the type specified on the right.
value castAs int
5 castAs String
|
| `assert` | Assert an expression | Evaluate an expression and if the expression is falsey it will throw an assert exceptions. |
### Type-Aware Equality Rules for `===`
BoxLang's `===` operator normalizes values within the language's type families before comparing, avoiding cross-type coercion while correctly handling type variants within each family:
| Type Family | Includes | Comparison Rule |
| -------------- | --------------------------------------------------------------------------- | --------------------------------- |
| **String** | `java.lang.String`, `java.lang.Character`, `char[]` | Case-insensitive comparison |
| **Numeric** | `Integer`, `Short`, `Long`, `Double`, `Float`, `BigInteger`, `BigDecimal` | Compared by numeric value |
| **DateTime** | `DateTime`, `ZonedDateTime`, `Calendar`, `LocalDateTime`, `LocalDate`, etc. | Compared by epoch millis |
| **Array** | BoxLang Array, `java.util.List` | Falls back to object's `equals()` |
| **Struct** | BoxLang Struct, `java.util.Map` | Falls back to object's `equals()` |
| **All Others** | Same class + `Comparable` | Uses `compareTo()` |
| **All Others** | Same class, not `Comparable` | Falls back to object's `equals()` |
```javascript
// String family — case-insensitive
"brad" === "BRAD" // true
"B" === javacast("char", "B") // true (char is treated as string)
// Numeric family — compared by value
1 === 1.0 // true
1 === 01 // true
2 === "2" // false (different type families)
// No cross-type coercion
true === "true" // false (boolean vs string)
true === 1 // false (boolean vs numeric)
// DateTime
now() === now() // true (same moment)
```
This `===` operator is also what BoxLang Sets use internally to determine set membership and uniqueness. See [Sets Equality and Uniqueness](/boxlang-language/syntax/sets.md#equality-and-uniqueness).
## ✅ Assert Statement
BoxLang offers an `assert` statement that will evaluate an expression, and if the expression is falsey, it will throw an `AssertionError` exception. The `assert` operator returns `true` if the assertion passes, otherwise throws an exception.
```java
// Asserts that the name is truthy
assert name;
// Assert an expression
assert myService.hasData();
assert name.length() > 3;
assert 5 == 5; // Passes
// Assert a lambda/closure result - functions are called automatically
assert () -> true
assert () => getUser() != null
```
{% hint style="info" %}
If the assertion expression is a function (closure or lambda), BoxLang automatically invokes it and evaluates the result.
{% endhint %}
### Custom Assertion Messages
You can include a custom message to display if the assertion fails, separated by a colon:
```js
assert user != null : "User must be provided before processing"
assert user.isActive() : "Cannot process an inactive user: #user.name#"
assert price > 0 : "Price must be greater than zero"
```
If the assertion fails, the message is included in the thrown `AssertionError` exception, making it easier to debug failures.
[Try it on try.boxlang.io](https://try.boxlang.io)
## 🏷️ InstanceOf Operator
The `instanceOf` operator checks if an object is an instance of a specified type. It works with both BoxLang types and Java classes.
```java
// BoxLang types
result = true instanceOf 'Boolean' // true
result = "hello" instanceOf 'String' // true
// Java classes
result = "brad" instanceOf 'java.lang.String' // true
// BoxLang classes
class User {}
user = new User()
result = user instanceOf 'User' // true
```
{% hint style="info" %}
The `instanceOf` operator performs case-insensitive class name matching and supports short names (e.g., `String` instead of `java.lang.String`).
{% endhint %}
[Try it on try.boxlang.io](https://try.boxlang.io)
## 🔄 CastAs Operator
BoxLang provides a native `castAs` operator for type casting. This operator is more fluent and readable than using the `javaCast()` function.
```java
// Casting to primitives
age = value castAs int
price = value castAs double
active = value castAs boolean
// Casting to objects
name = value castAs String
tags = value castAs String[]
// Dynamic type casting
result = {
age: value castAs int,
tags: value castAs String[],
isActive: "#value#" castAs Boolean
}
// Unquoted identifiers are treated as string literals
result = value castAs Long // Same as castAs "Long"
```
{% hint style="success" %}
The `castAs` operator is integrated into the BoxLang language and is preferred over the `javaCast()` BIF for most type casting scenarios.
{% endhint %}
[Try it on try.boxlang.io](https://try.boxlang.io)
## ❓ Ternary Operator
The ternary operator is a conditional operator that works just like an `if-then-else` statement but in shorthand syntax. It has three operands:
```
condition ? value1 if true : value2 if false
```
The `condition` must evaluate to a `Boolean` value. If `true` then the `value1` will be used, or else `value2` will be used. You can combine this operator with parenthesis, Elvis operators, etc., to build rich expressions.
```javascript
result = ( 10 > 0 ) ? true : false
result = animal eq 'dog' ? 'bark' : 'not a dog'
// More complex approach
result = creditScore > 800 ? "Excellent" :
( creditScore > 700 ) ? "Good" :
( creditScore > 600 ) ? "Average" : "Bad"
```
## 🎸 Elvis Operator (Null Coalescing)
The Elvis operator is usually referred to as the [null coalescing operator](https://en.wikipedia.org/wiki/Null_coalescing_operator). Its name comes from the symbol it represents, which looks like Elivs hair turned sideways: `?:`. If the expression to the operator's left is `null` , then the expression on the right will be evaluated as the result of the expression.
```
expression ?: defaultValueOrExpression
```
Here is a simple example:
```javascript
function process( result ){
writeOutput( result ?: "nothing passed" )
}
process() // produces 'nothing passed'
process( "hello" ) // produces 'hello'
displayName = rc.name ?: 'Anonymous'
event
.getResponse()
.setError( true )
.setData( rc.id ?: "" )
```
## 🔧 Function Expressions
In BoxLang, a function invocation can be used as an expression, where the results of the function call is the effective value used.
```javascript
results = ucase( "this is text " ) & toString( 12 + 50 )
```
`Function` is also a proper type, allowing a reference to a function to be passed as an argument to another function or returned from another function as the return value. Functions which accept or return other functions are called higher order functions\*\*.
```javascript
// I can also pass lambdas or anonymous functions as arguments
results = listener( 2 * 3, (result) => result + 1 )
```
## 📦 Collections Operators
Many operators can work on collection objects like arrays, structs, and queries. So let's start investigating them.
### 🛡️ Safe Navigation Operator
The [Safe Navigation operator](https://en.wikipedia.org/wiki/Safe_navigation_operator) avoids accessing a key in a structure or a value in an object that does `null` or doesn't exist. Typically when you have a reference to an object, you might need to verify that it exists before accessing the methods or properties of the object. To avoid this, the safe navigation operator will return `null` instead of throwing an exception, like so:
```javascript
var user = userService.findById( id )
// If user is not found, then this will still work but no exception is thrown.
echo( user?.getSalary() )
s = { name : "luis" }
echo( s.name )
echo( s?.name )
```
### 🌟 Spread Operator
{% hint style="info" %}
Since BoxLang 1.12.x
{% endhint %}
The spread operator expands arrays and structs into function calls and literals.
See [Spread Syntax](/boxlang-language/syntax/spread-syntax.md) for full coverage.
#### Function Calls
Spread an array as positional arguments.
```javascript
numbers = [ 1, 2, 3 ]
result = sum( ...numbers )
```
Spread a struct as named arguments.
```javascript
person = { first: "Jane", last: "Smith" }
result = greet( ...person )
```
#### Literals
Spread also works inside array and struct literals.
```javascript
myArray = [ 3, 4, ...numbers ]
mergedStruct = { ...defaults, ...overrides }
orderedStruct = [ ...defaults, retries: 5 ]
```
Declaration order wins. Later keys overwrite earlier keys.
```javascript
result = { ...left, ...right, shared: "literal" }
```
### 💤 Rest Operator
{% hint style="info" %}
Since BoxLang 1.12.x
{% endhint %}
The rest operator collects the remaining values into one binding.
It is available in function parameters and destructuring patterns.
```javascript
function findById( entityName, ...ids ){
return ids
}
findById( "User", 1, 2, 3 ) // [ 1, 2, 3 ]
```
It also works in destructuring:
```javascript
[ first, ...rest ] = values
({ id, ...rest } = payload)
```
See [Destructuring](/boxlang-language/syntax/destructuring.md) for nested patterns, defaults, and middle-rest behavior.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://boxlang.ortusbooks.com/boxlang-language/syntax/operators.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.