# Array Tags

Source: https://rungs.dev/docs/tags/arrays

> Use array tags in rungs.dev to store lists of BOOL, DINT, REAL, TIMER, COUNTER, FBD_TIMER, or FBD_COUNTER values under one name and reference elements with Tag[index].

An array tag holds a list of values of the same data type under a single name. Reference an element with `Tag[index]`.

## Creating an array [#creating-an-array]

In the tag editor, create a tag with usage **Local** and set its **array size** to a positive number. Rungs stores the elements as `Tag[0]`, `Tag[1]`, …, `Tag[size - 1]`.

Every data type can be an array element — `BOOL`, `DINT`, `REAL`, `TIMER`, `COUNTER`, `FBD_TIMER`, `FBD_COUNTER`. For example, `DelayTimer` with size `12` gives you 12 independent TIMER structures reachable as `DelayTimer[0].PRE`, `DelayTimer[0].DN`, `DelayTimer[1].PRE`, …

## Referencing an element [#referencing-an-element]

Use `Tag[index]` anywhere a tag name is accepted — instruction operands, expressions, comparisons:

- `Sensors[0]` — the first element of `Sensors`
- `Samples[3]` — the fourth element of `Samples`
- `DelayTimer[2].PRE` — the `PRE` member of the third `TIMER` in `DelayTimer`
- `Samples[i]` — index with a `DINT` tag to read or write the element at runtime

In Ladder Logic, array references drop directly into instruction operands:

```ladder
XIC(Sensors[0])GT(Samples[3],100)OTE(Alarm)
```

Every reference must include an integer or integer tag in square brackets. Missing the index on an array tag produces:

> `Tag 'Samples' is an array and requires an index, use Samples[0]`

Using an index on a scalar (non-array) tag produces:

> `Tag 'Count' is not an array and cannot be indexed`

## Index expressions [#index-expressions]

The index inside `[…]` must produce an integer. The compiler accepts these forms:

- integer literals — `Samples[0]`, `Samples[3]`
- DINT tags — `Samples[i]`
- DINT struct members — `Samples[Tmr.ACC]`
- integer arithmetic with `+`, `-`, `*`, `/`, `MOD` — `Samples[i + 1]`, `Samples[(i - 1) MOD 8]`
- bitwise `AND`, `OR`, `XOR`, `NOT` over integers — `Samples[i AND 1]`, `Samples[i XOR 1]`
- `ABS()` over an integer argument — `Samples[ABS(offset)]`

DINT division truncates toward zero, so `Samples[i / 2]` with `i = 7` reads index `3` (not `3.5`).

The compiler rejects:

- REAL values — `Samples[1.5]`, `Samples[realTag]`
- BOOL values — `Samples[boolTag]`
- whole-array indexes — `Samples[OtherArray]` (read an array element into a DINT tag first, then use that tag)
- nested array access in the index — `Samples[Inner[i]]`
- bit access in the index — `Samples[i.0]`
- non-integer math functions — `SQRT()`, `SIN()`, `COS()`, `TAN()`
- unary `+` — write `Samples[i]`, not `Samples[+i]`
- statically out-of-range literals — `Samples[5]` when `Samples` has 3 elements

If the index is a tag or expression the compiler cannot evaluate, an out-of-range access at runtime raises `Runtime error: Array index out of bounds` and halts the scan.

## Counting Elements [#counting-elements]

In Structured Text, the [`SIZE` instruction](https://rungs.dev/docs/structured-text/instructions/size) writes
an array's element count into a `DINT` tag, so loops over the array never hardcode its
length.

## Restrictions [#restrictions]

- **Single-dimension only.** Multi-dimensional arrays (`Tag[row][col]`) are not supported.
- **Local or InOut usage only.** Input and Output tags are always single values. Use **Local** for an array the instruction owns, or **InOut** for one the caller owns — see [Tag Usage](https://rungs.dev/docs/tags/tag-usage#inout-parameters).
- **`BOOL` arrays come in blocks of 32** — 32, 64, 96 and so on. They are stored packed into 32-bit words, so if you ask for 24 you get 32.
- **Indices must be in range.** Writing `Samples[5]` when `Samples` has only 3 elements is a compile-time error. If the index is itself a tag (`Samples[i]`), the compiler cannot check it — an out-of-range access at runtime raises `Runtime error: Array index out of bounds` and halts the scan.