# Arithmetic Expressions

An arithmetic expression combines numeric values, variables, and arithmetic operators in a way that the computer then evaluates to produce a single numeric value.

- [Divide](#division)
- [Multiply](#multiplication)
- [Subtract](#subtraction)
- [Sum](#addition)

Arithmetic Expressions are not supported as root level expressions since those must evaluate to a boolean. But arithmetic expressions can be used nested within [Comparisson Expressions](./comparison-expressions.md).

> Note: Any non-present operand is discarded. This means that if a reference is missing, the expression will return FALSE. Also, all operands that ARE present must be either numbers or an ISO date string followed by valid date durations, otherwise an error is thrown.

## Division

The arithmetical operator for division calculates how many times one number is contained within another number. The expression denotes the left-most operand as the dividend (the number being divided up) and the subsequent operand as the divisor (the number that we're attempting to repeatedly contain in the dividend).

Expression format: `["/", First Operand, Second Operand, ... , Nth Operand]`.

> Valid operand types: [Arithmetic Expressions](./arithmetic-expressions.md) or [Operands](./operand-types.md).

```json
["==", ["/", 100, 10], 10]
```

```js
engine.evaluate(['==', ['/', 100, 10], 10]) // true
```

## Multiplication

The arithmetical operator for multiplication produces the product of the operands, evaluating "First operand value added to itself second operand value number of times".

Expression format: `["*", First Operand, Second Operand, ... , Nth Operand]`.

> Valid operand types: [Arithmetic Expressions](./arithmetic-expressions.md) or [Operands](./operand-types.md).

```json
["==", ["*", 100, 10], 10]
```

```js
engine.evaluate(['==', ['*', 10, 10], 100]) // true
```

## Subtraction

The arithmetical operator for subtraction subtracts the operands, producing their difference.

Expression format: `["-", First Operand, Second Operand, ... , Nth Operand]`.

> Valid operand types: [Arithmetic Expressions](./arithmetic-expressions.md) or [Operands](./operand-types.md).

```json
["==", ["-", 20, 10], 10]
```

```js
engine.evaluate(['==', ['-', 20, 10], 10]) // true
```

Subtraction can also mutate a date by subtracting a time duration.

Expression format: `["-", First Operand, "7d", "1m", ...]`.

Valid format for the time is a combination of an integer and a time unit. Valid time units are:

- `d` days
- `m` months
- `y` years

```js
engine.evaluate(['==', ['-', '2026-01-01', '5d'], '2025-12-27']) // true
engine.evaluate(['==', ['-', '2010-03-31', '1m'], '2010-02-28']) // true
engine.evaluate(['==', ['-', '2024-02-29', '1y'], '2023-02-28']) // true
engine.evaluate(['==', ['-', '2024-02-29', '1y', '1m'], '2023-01-28']) // true
```

## Addition

The arithmetical operator for addition produces the sum of the operands.

Expression format: `["+", First Operand, Second Operand, ... , Nth Operand]`.

> Valid operand types: [Arithmetic Expressions](./arithmetic-expressions.md) or [Operands](./operand-types.md).

```json
["==", ["+", 5, 5], 10]
```

```js
engine.evaluate(['==', ['+', 5, 5], 10]) // true
```

Addition can also mutate a date by adding a time duration.

Expression format: `["+", First Operand, "7d", "1m", ...]`.

```js
engine.evaluate(['==', ['+', '2026-01-01', '5d'], '2026-01-06']) // true
engine.evaluate(['==', ['+', '2010-01-31', '3m'], '2010-04-30']) // true
engine.evaluate(['==', ['+', '2024-02-29', '2y'], '2026-02-28']) // true
engine.evaluate(['==', ['+', '2024-02-29', '2y', '2d'], '2026-03-02']) // true
```