# VisiMark function reference

**Generated from `packages/visimark/src/lang/reference.ts` by
`bun run gen:docs`. Do not edit this file by hand — edit the registry.**

Every example below is executed against the evaluator in CI
(`packages/visimark/test/lang/reference-examples.test.ts`), so an example
that stops being true fails the build.

The narrative account of the language is
[`visimark-design.md`](visimark-design.md); why each function exists is in
[`vocab/`](vocab/). This file answers only what each one does.

A reduce example is shown against a three-row table `t` whose `Amount`
column holds `10.00`, `20.00` and `30.00`.

## Reduces

A reduce is column → scalar and takes a bare column reference, never an
expression.

### `SUM(col)`

Total of a column; `0` over an empty column.

**Shape:** reduce, 1 argument.

| Parameter | Type | Meaning |
|---|---|---|
| `col` | column | the column to total |

**Returns:** number.

**Precision:** the width of `col`.

**Examples**

| Expression | Is |
|---|---|
| `SUM(t.Amount)` | `60` |
| `SUM(t.Amount) * 2` | `120` |

**See also:** `AVG`, `COUNT`

### `MIN(col)`

Least value.

**Shape:** reduce, 1 argument.

| Parameter | Type | Meaning |
|---|---|---|
| `col` | column | a column of numbers, or of dates |

**Returns:** number or date, matching the column.

**Precision:** the width of `col`.

**Errors**

- A column mixing numbers and dates — `TYPE`

**Examples**

| Expression | Is |
|---|---|
| `MIN(t.Amount)` | `10` |

**See also:** `MAX`

### `MAX(col)`

Greatest value.

**Shape:** reduce, 1 argument.

| Parameter | Type | Meaning |
|---|---|---|
| `col` | column | a column of numbers, or of dates |

**Returns:** number or date, matching the column.

**Precision:** the width of `col`.

**Errors**

- A column mixing numbers and dates — `TYPE`

**Examples**

| Expression | Is |
|---|---|
| `MAX(t.Amount)` | `30` |

**See also:** `MIN`

### `AVG(col)`

Arithmetic mean.

**Shape:** reduce, 1 argument.

| Parameter | Type | Meaning |
|---|---|---|
| `col` | column | the column to average |

**Returns:** number.

**Precision:** must be declared.

**Errors**

- An empty column — `TYPE`

**Examples**

| Expression | Is |
|---|---|
| `AVG(t.Amount)` | `20` |

**See also:** `SUM`, `COUNT`

### `COUNT(col)`

Number of rows.

**Shape:** reduce, 1 argument.

| Parameter | Type | Meaning |
|---|---|---|
| `col` | column | the column whose rows are counted |

**Returns:** number.

**Precision:** always 0.

**Examples**

| Expression | Is |
|---|---|
| `COUNT(t.Amount)` | `3` |

**See also:** `SUM`

### `NPV(rate, flows)`

Present value of a cash-flow column; row 0 is undiscounted; an empty column is a TYPE error.

**Shape:** reduce, 2 arguments.

| Parameter | Type | Meaning |
|---|---|---|
| `rate` | number | the rate for one period; must be greater than -1 |
| `flows` | column | cash flows in time order; the first row is period 0 |

**Returns:** number.

**Precision:** must be declared.

**Errors**

- A non-numeric `rate` — `TYPE`
- A `rate` of -1 or below — `TYPE`
- An empty column — `TYPE`
- A non-numeric cell — `TYPE`
- A non-column `flows` argument — `TYPE`

**Examples**

| Expression | Is |
|---|---|
| `NPV(0, t.Cash)` | `12000` |
| `NPV(0.08, t.Cash)` | `-48000` |
| `NPV(-0.5, t.Cash)` | `300` |

**See also:** `SUM`, `AVG`

### `IRR(flows)`

Rate at which a cash-flow column has present value zero; row 0 is undiscounted.

**Shape:** reduce, 1 argument.

| Parameter | Type | Meaning |
|---|---|---|
| `flows` | column | cash flows in time order; the first row is period 0; exactly one sign change |

**Returns:** number.

**Precision:** must be declared.

**Errors**

- An empty column — `TYPE`
- A non-numeric cell — `TYPE`
- An all-zero column — `TYPE`
- A column with no sign change — `TYPE`
- A column with more than one sign change — `TYPE`
- A rate not determined at the declared width — `PRECISION`
- A non-column `flows` argument — `TYPE`

**Examples**

| Expression | Is |
|---|---|
| `IRR(t.Cash)` | `0.1` |
| `IRR(t.Cash)` | `0.1` |
| `IRR(t.Cash)` | `0` |

**See also:** `NPV`, `PMT`

## Maps

A map is scalar → scalar and runs once per row inside a column rule.

### `ROUND(x, places)`

Half-up to `places` decimals.

**Shape:** map, 2 arguments.

| Parameter | Type | Meaning |
|---|---|---|
| `x` | number | the value to round |
| `places` | number | how many decimal places to keep |

**Returns:** number.

**Precision:** the value of `places`.

**Rounding:** Ties round away from zero (half-up), not to even.

**Examples**

| Expression | Is |
|---|---|
| `ROUND(2.345, 2)` | `2.35` |
| `ROUND(2.5, 0)` | `3` |
| `ROUND(-2.5, 0)` | `-3` |

**See also:** `FLOOR`, `CEILING`

### `ABS(x)`

Absolute value.

**Shape:** map, 1 argument.

**Also written:** `|x|`

| Parameter | Type | Meaning |
|---|---|---|
| `x` | number | the value whose sign is discarded |

**Returns:** number.

**Precision:** the width of `x`.

**Examples**

| Expression | Is |
|---|---|
| `ABS(-7)` | `7` |
| `ABS(7)` | `7` |

### `MOD(x, y)`

Remainder.

**Shape:** map, 2 arguments.

| Parameter | Type | Meaning |
|---|---|---|
| `x` | number | the dividend |
| `y` | number | the divisor |

**Returns:** number.

**Precision:** the wider of `x` and `y`.

**Errors**

- A zero divisor — `TYPE`

**Examples**

| Expression | Is |
|---|---|
| `MOD(7, 3)` | `1` |
| `MOD(9, 3)` | `0` |

**See also:** `FLOOR`

### `SQRT(x)`

Non-negative square root.

**Shape:** map, 1 argument.

**Also written:** `√(x)`

| Parameter | Type | Meaning |
|---|---|---|
| `x` | number | a non-negative number |

**Returns:** number.

**Precision:** must be declared.

**Errors**

- A negative operand — `TYPE`

**Examples**

| Expression | Is |
|---|---|
| `SQRT(9)` | `3` |
| `SQRT(0)` | `0` |

### `FLOOR(x, s)`

Greatest multiple of `s` that does not exceed `x`, toward −∞.

**Shape:** map, 2 arguments.

**Also written:** `⌊x⌋`

| Parameter | Type | Meaning |
|---|---|---|
| `x` | number | the value to round down |
| `s` | number | the positive step to round to |

**Returns:** number.

**Precision:** the width of `s`.

**Errors**

- A non-positive `s` — `TYPE`

**Examples**

| Expression | Is |
|---|---|
| `FLOOR(7, 3)` | `6` |
| `FLOOR(-7, 3)` | `-9` |

**See also:** `CEILING`, `ROUND`

### `CEILING(x, s)`

Least multiple of `s` that is not less than `x`, toward +∞.

**Shape:** map, 2 arguments.

**Also written:** `⌈x⌉`

| Parameter | Type | Meaning |
|---|---|---|
| `x` | number | the value to round up |
| `s` | number | the positive step to round to |

**Returns:** number.

**Precision:** the width of `s`.

**Errors**

- A non-positive `s` — `TYPE`

**Examples**

| Expression | Is |
|---|---|
| `CEILING(7, 3)` | `9` |
| `CEILING(-7, 3)` | `-6` |

**See also:** `FLOOR`, `ROUND`

### `IF(cond, a, b)`

Returns `a` or `b`.

**Shape:** map, 3 arguments.

| Parameter | Type | Meaning |
|---|---|---|
| `cond` | bool | the condition; must be a boolean |
| `a` | number | the value when `cond` holds |
| `b` | number | the value when it does not |

**Returns:** whichever of `a` or `b` was selected.

**Precision:** the wider of `a` and `b`.

**Errors**

- A non-boolean `cond` — `TYPE`

**Examples**

| Expression | Is |
|---|---|
| `IF(1 < 2, 10, 20)` | `10` |
| `IF(1 > 2, 10, 20)` | `20` |

### `EOMONTH(d, months)`

Last day of the month `months` calendar months from `d`; `d`'s day is discarded.

**Shape:** map, 2 arguments.

| Parameter | Type | Meaning |
|---|---|---|
| `d` | date | the date whose month starts the count |
| `months` | number | whole number of months to move; may be negative |

**Returns:** date.

**Precision:** not applicable — the result is a date.

**Errors**

- A non-whole `months` — `TYPE`
- A result outside years 1–9999 — `DATE`

**Examples**

| Expression | Is |
|---|---|
| `EOMONTH(2026-01-15, 0)` | `2026-01-31` |
| `EOMONTH(2026-01-31, 1)` | `2026-02-28` |
| `EOMONTH(2024-01-31, 1)` | `2024-02-29` |
| `EOMONTH(2026-01-15, -1)` | `2025-12-31` |

**See also:** `MIN`, `MAX`

### `PMT(rate, nper, pv)`

Instalment that repays `pv` to zero over `nper` periods at per-period rate `rate`.

**Shape:** map, 3 arguments.

| Parameter | Type | Meaning |
|---|---|---|
| `rate` | number | the rate for one period; must be greater than -1 |
| `nper` | number | a positive whole number of periods |
| `pv` | number | the present amount repaid down to zero |

**Returns:** number.

**Precision:** must be declared.

**Errors**

- A non-numeric `rate`, `nper`, or `pv` — `TYPE`
- A non-positive or non-whole `nper` — `TYPE`
- A `rate` of -1 or below — `TYPE`

**Examples**

| Expression | Is |
|---|---|
| `PMT(0, 12, 1200)` | `100` |
| `PMT(0.10, 1, 1000)` | `1100` |
| `PMT(0, 4, 0)` | `0` |

<!--vmark:no-formulas-->