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

# Tables

> One- or two-dimensional collections of values with per-cell units. How tables are written in equations, stored and returned, and combined with element-wise operations.

A **table** is a collection of values arranged in rows and columns — a single column (one-dimensional) or a two-dimensional grid. In software terms, a table is TrueMath's array type: a one-dimensional table is a list (or vector), and a two-dimensional table is a matrix. Tables hold series and matrices: a list of cash flows, an amortization schedule, a lookup grid. They are **1-indexed** (the first row and column are index `1`) — unlike arrays in most languages — and each **cell holds a value with its own optional unit**. Cells may carry different units, or none.

The same table can appear in three places — written in an equation, returned by the API, or sent as input. The notation differs; the table is the same.

## In equations

In an [activity](/concepts/activities) equation, a table is a bracketed literal with **semicolons** separating entries (commas are never used as they can be confused with decimal or thousands separators). A bare list is a single column — `[3; 4; 5]` is three rows of one column — and nesting a bracketed list adds columns:

```
[3; 4; 5]                  # 3 rows, 1 column
[[3; 100]; [4; 200]]       # 2 rows, 2 columns
```

Cells may carry units, may mix units, and may be left empty:

```
[3 ft; 4 ft; 5 ft]         # every cell a length
[3 ft; 4 USD]              # mixed units may coexist in a table
[1; ; 3]                   # the middle cell is empty
```

Mixed units are allowed to *coexist* in a table, but arithmetic across cells with incompatible dimensions still errors — see [Combining types](/authoring/writing-equations#combining-types).

### Element-wise operations

* **With a scalar** — applies to every cell: `[1; 2; 3] * 2` → `[2; 4; 6]`.
* **With another table** — element-wise; shapes must match: `[1; 2] + [3; 4]` → `[4; 6]`.

Read and reshape tables with [table functions](/math/functions/tables) (`item`, `row`, `column`, `subset`, `lookup`, `sort`, `append`, `length`, `width`) or aggregate them with [statistics functions](/math/functions/statistics) (`sum`, `avg`, `stddev`).

## As a stored value

When a table is returned by the API or held in a [scenario](/concepts/scenarios), it is represented as an **array of strings** — one per cell, each combining the value and its unit. Because the unit lives inside each cell, a table variable's own `unit` is empty.

```json theme={null}
["1500 USD", "1600 USD", "1700 USD"]              // a 1-D table
[["1500 USD", "12"], ["1600 USD", "12"]]          // a 2-D table
["3", "4", "5"]                                   // cells without units
```

## As input

To provide a table as input, write it in **structured text** — semicolons separate cells, and brackets or new lines separate rows, with optional per-cell or outer units. See [structured text](/concepts/input-formats#tables).

## Display

In a [domain](/concepts/domains), a table-valued [variable](/concepts/variables) can be displayed as a table or as a [bar or pie chart](/authoring/charts).