# ARRAY

Zero-indexed array that stores values of any type. Full support for serialisation and arithmetic operations is provided for the four primitive types: [`INTEGER`](INTEGER.md), [`DOUBLE`](DOUBLE.md), [`STRING`](STRING.md), and [`BOOL`](BOOL.md). Mixed-type arrays are allowed, but some methods interpret elements in non-obvious ways (see the notes on [`FIND`](#find), [`CONTAINS`](#contains), and [`GETSUMVALUE`](#getsumvalue)).

## Fields

### TOINI

```
BOOL TOINI
```

Controls whether the array's contents are serialised to an INI file and restored on the next run.

## Methods

### ADD

```
void ADD(mixed value1, [mixed value2, ..., mixed valueN])
```

Appends the given values to the end of the array. The argument types do not have to match.

**Parameters**

- `value1, …, valueN` — values to append.

**Examples**

```
G_ARRSETTINGS^ADD(0, 600);
G_ARRDATAS^ADD("PODWIECZOREK1", "PODWIECZOREK2", "PODWIECZOREK3");
ARRFLAMESDIR^ADD("R", "R", "R", "L", "L");
ARR_JOINTS^ADD(FALSE, 6, "B", 10, "A", 4);
```

### ADDAT

```
void ADDAT(INTEGER index, mixed value)
```

Adds the argument to the element at position `index`. Internally, the element and the argument are converted to `DOUBLE`, summed, and stored as [`DOUBLE`](DOUBLE.md) — after this call the element at that position is always of type `DOUBLE`. Calling with `index` out of range leaves the array unchanged.

**Parameters**

- `index` — element position (`0`-based).
- `value` — value to add.

**Examples**

```
ARRIDLETIME^ADDAT(0, 1);
ARRENEMYY^ADDAT(VARITMPINDEX, VARITMP1);
ARRSPEED^ADDAT(0, 2.0);
```

### CHANGEAT

```
void CHANGEAT(INTEGER index, mixed value)
```

Replaces the element at position `index` with the given value. The type of the new element is preserved exactly as passed. Calling with `index` out of range leaves the array unchanged.

**Parameters**

- `index` — element position (`0`-based).
- `value` — the new value.

**Examples**

```
ARRIDLETIME^CHANGEAT(0, 0);
G_ARRREXSPELLS^CHANGEAT(VARIREPEATSPELL, 1);
ARRAYPLAYERSSTATE^CHANGEAT([VARCLONE-1], "NULL");
```

### CLAMPAT

```
void CLAMPAT(INTEGER index, mixed rangeMin, mixed rangeMax)
```

Clamps the value at position `index` to the inclusive range `[rangeMin, rangeMax]`. The element's type is preserved — `INTEGER` stays `INTEGER`, `DOUBLE` stays `DOUBLE`. For elements of any other type (and for `index` out of range) the call leaves the array unchanged.

**Parameters**

- `index` — element position (`0`-based).
- `rangeMin` — lower bound (inclusive).
- `rangeMax` — upper bound (inclusive).

**Examples**

```
ARRSPEED^CLAMPAT(VARPLAYER, 0.0, 100.0);
ARRSPEED^CLAMPAT(0, 0.0, 17.0);
```

### CONTAINS

```
BOOL CONTAINS(mixed needle)
```

Checks whether the array contains an element matching the given value. The comparison is done on the textual representation — `needle` is cast to [`STRING`](STRING.md) and compared with the `toDisplayString` result of each element. This differs from `FIND`, which compares values according to the [engine's typing rules](../engine/arithmetic.md#typing-rule).

**Parameters**

- `needle` — the value to search for.

**Returns**: [`BOOL`](BOOL.md) — `TRUE` if a matching element was found.

**Examples**

```
ART0^CONTAINS(ICIK);
ARRAYWARSZTATPRZEDMIOTY^CONTAINS(ARRAYTEMP^GET($1));
```

### COPYTO

```
void COPYTO(STRING arrayVarName)
```

Appends the contents of this array to the end of the array named in the argument. The target array must already exist and be of type `ARRAY`. The target array is **not** cleared before copying.

**Parameters**

- `arrayVarName` — the name of the destination array variable.

**Examples**

```
ARAG^COPYTO("ARTMP");
```

### FIND

```
INTEGER FIND(mixed needle)
```

Searches the array for the first element equal to the given value. The comparison follows the [engine's typing rules](../engine/arithmetic.md#typing-rule) — the type of the array element in each iteration determines what type `needle` is cast to. This yields counterintuitive results in mixed-type arrays: for example, searching for `240` in an array containing `TRUE` will return the index of `TRUE`, because `240` is cast to `BOOL` (a non-zero value, which becomes `TRUE`).

**Parameters**

- `needle` — the value to search for.

**Returns**: the index of the first matching element, or `-1` if no match was found.

**Examples**

```
G_ARRCUTSCENES^FIND(G_SCUTSCENE);
ARRSTARTNAME0^FIND("NULL");
ARRCLONES^FIND(-1);
```

### GET

```
mixed GET(INTEGER index)
```

Returns the element at position `index`. For `index` out of range, returns `NULL`.

**Parameters**

- `index` — element position (`0`-based).

**Returns**: the element's value or `NULL`.

**Examples**

```
ARRIDLETIME^GET(0);
ARRACTIVESPELLS^GET(_I_);
ARRAYPLAYERSSTATE^GET([VARCLONE-1]);
```

### GETSIZE

```
INTEGER GETSIZE()
```

Returns the number of elements in the array.

**Returns**: the array's size.

**Examples**

```
G_ARRSETTINGS^GETSIZE();
ARRENEMYROUTEX^GETSIZE();
```

### GETSUMVALUE

```
DOUBLE GETSUMVALUE()
```

Returns the sum of all element values. Each element is cast to `DOUBLE` per the [conversion rules](../engine/arithmetic.md#type-conversions); non-numeric elements can contribute unexpected values (`BOOL` → `1.0` or `0.0`, a non-numeric [`STRING`](STRING.md) → `0.0`).

**Returns**: the sum as a [`DOUBLE`](DOUBLE.md).

**Examples**

```
ARCONTAINER^GETSUMVALUE();
```

### INSERTAT

```
void INSERTAT(INTEGER index, mixed value)
```

Inserts the value at position `index`, shifting existing elements to the right. Valid values of `index` are in `[0, size]` — inserting at the array's size appends the element at the end. Calling outside this range leaves the array unchanged.

**Parameters**

- `index` — insertion position.
- `value` — the value to insert.

**Examples**

```
ARRTURNIEJ^INSERTAT(I3, I1);
ARRTURNIEJ^INSERTAT(4, I1);
```

### LOAD

```
void LOAD(STRING path)
```

Replaces the array's contents with data read from a binary `.ARR` file. The file is little-endian: a 4-byte element count, followed by, for each element, a 4-byte type tag (`1`=`INTEGER`, `2`=`STRING`, `3`=`BOOL`, `4`=`DOUBLE`) and the corresponding value representation.

**Parameters**

- `path` — the `.ARR` file path in the game's VFS.

**Examples**

```
G_ARRSETTINGS^LOAD("$COMMON\SETTINGS.ARR");
ARRPATH^LOAD(["MAPA"+ILEVEL+".ARR"]);
```

### LOADINI

```
void LOADINI()
```

Replaces the array's contents with data deserialised from the game's INI file under the key matching this variable's name. The INI format is a comma-separated list of values:

```
ARRAY_NAME=value1,value2,value3,...
```

Each element is interpreted in order as [`INTEGER`](INTEGER.md), [`DOUBLE`](DOUBLE.md), [`BOOL`](BOOL.md), or [`STRING`](STRING.md) — the first matching type is used.

**Examples**

```
ARRAYWARSZTATMENUPRZEDMIOTY^LOADINI();
```

### MODAT

```
void MODAT(INTEGER index, mixed divisor)
```

Stores the remainder of dividing the element at position `index` by the argument. Internally, the element and the argument are converted to `DOUBLE`, modulo is computed, and the result is stored as [`DOUBLE`](DOUBLE.md). Division by zero, or calling with `index` out of range, leaves the array unchanged.

**Parameters**

- `index` — element position.
- `divisor` — the divisor.

**Examples**

```
ARRANGLE^MODAT(VARPLAYER, 360);
```

### MULAT

```
void MULAT(INTEGER index, mixed multiplier)
```

Multiplies the element at position `index` by the argument. Internally, the element and the argument are converted to `DOUBLE`, multiplied, and the result is stored as [`DOUBLE`](DOUBLE.md). Calling with `index` out of range leaves the array unchanged.

**Parameters**

- `index` — element position.
- `multiplier` — the multiplier.

**Examples**

```
ARRDIRY^MULAT(VARPLAYER, -1.0);
ARRDIRX^MULAT(VARPLAYER, -1);
```

### REMOVEALL

```
void REMOVEALL()
```

Removes all elements from the array.

**Examples**

```
G_ARRSETTINGS^REMOVEALL();
ARRTEMP^REMOVEALL();
```

### REMOVEAT

```
void REMOVEAT(INTEGER index)
```

Removes the element at position `index`, shifting the remaining elements to the left. Calling with `index` out of range leaves the array unchanged.

**Parameters**

- `index` — position of the element to remove.

**Examples**

```
ARRTEMP^REMOVEAT(VARITEMP2);
ARRENEMYROUTEX^REMOVEAT(0);
```

### REVERSEFIND

```
INTEGER REVERSEFIND(mixed needle)
```

Works like [`FIND`](#find), but scans the array from the end. The same type-dependent comparison rules apply.

**Parameters**

- `needle` — the value to search for.

**Returns**: the index of the last matching element, or `-1` if no match was found.

**Examples**

```
ARRAYKURNIKFREESLOTS^REVERSEFIND(0);
```

### SAVE

```
void SAVE(STRING path)
```

Writes the array's contents to a binary `.ARR` file in the format described in [`LOAD`](#load).

**Parameters**

- `path` — the destination `.ARR` file path in the game's VFS.

**Examples**

```
G_ARRSETTINGS^SAVE("$COMMON\SETTINGS.ARR");
ARRPATH^SAVE(["MAPA"+ILEVEL+".ARR"]);
```

### SAVEINI

```
void SAVEINI()
```

Serialises the array's contents to the game's INI file under the key matching this variable's name, as a comma-separated list of values (the format described in [`LOADINI`](#loadini)).

**Examples**

```
ARRAYPLATFORMOWKAPRZEDMIOTY^SAVEINI();
```

### SUB

```
void SUB(mixed value)
```

Subtracts the argument from every element of the array. Each element is converted to `DOUBLE` before the subtraction; all elements after the call are of type `DOUBLE`.

**Parameters**

- `value` — the value to subtract.

**Examples**

```
ARRAYBKGA^SUB([0-VARINT2]);
```

### SUBAT

```
void SUBAT(INTEGER index, mixed value)
```

Subtracts the argument from the element at position `index`. Internally, the element and the argument are converted to `DOUBLE`, subtracted, and the result is stored as [`DOUBLE`](DOUBLE.md). Calling with `index` out of range leaves the array unchanged.

**Parameters**

- `index` — element position.
- `value` — the value to subtract.

**Examples**

```
ARRBUTTONPRESSED^SUBAT(IBUTTONNR, 1);
ARRSPEED^SUBAT(VARPLAYER, 0.15);
```

### SUM

```
void SUM(mixed value)
```

Adds the argument to every element of the array. Each element is converted to `DOUBLE` before the addition; all elements after the call are of type `DOUBLE`.

**Parameters**

- `value` — the value to add.

**Examples**

```
ARRCHICKENX^SUM(-60);
ARRCHICKENY^SUM(-110);
```

## Signals

### ONCHANGE

Fired after a modification has been made to the array.

### ONINIT

Fired when the variable is initialised.

### ONDONE

Fired when leaving the scene that owns the variable.

### ONSIGNAL

Fired when a signal arrives (sent via the `SEND` method — see [Events and signals](../engine/events.md#onsignal)).