---
name: "insert"
type: command
status: ok
groups: ["HashMap", "Arrays", "Strings"]
arma3_since: "2.02"
locality: {"argument": null, "effect": null, "server_exec": false}
source: https://community.bistudio.com/wiki/insert
revid: 377154
updated: 2026-01-01T10:37:44Z
---

# insert

*Command · HashMap, Arrays, Strings · Arma 3 v2.02*

## Description

Inserts multiple values into [Array](../topics/Array.md)/[String](../topics/String.md)/[HashMap](../topics/HashMap.md).

The [String](../topics/String.md) variant also supports [forceUnicode](../commands/forceUnicode.md). In the event of a [HashMap](../topics/HashMap.md), values, if they already exist, are replaced.

## Syntax

### Syntax 1

```sqf
array insert [index, valuesToInsert, onlyIfUnique]
```

**Parameters:**

- `array` : [Array](../topics/Array.md) of [Anything](../topics/Anything.md)
- `index`: [Number](../topics/Number.md) - index at which the values will be inserted, -1 for append, Arma 3 v2.14 -2 for inserting at the second-to-last position, -3 before that, etc.
- `valuesToInsert`: [Array](../topics/Array.md) of [Anything](../topics/Anything.md) - values to insert at the specified index
- `onlyIfUnique`: [Boolean](../topics/Boolean.md) - (Optional, default [false](../commands/false.md)) only insert if the value is unique in the array, like [pushBackUnique](../commands/pushBackUnique.md)

**Returns:** [Nothing](../topics/Nothing.md)

### Syntax 2

```sqf
string insert [index, substring]
```

**Parameters:**

- `string` : [String](../topics/String.md)
- `index`: [Number](../topics/Number.md) - index at which the values will be inserted, -1 for append
- `substring`: [String](../topics/String.md) - string to insert

**Returns:** [String](../topics/String.md) - the new string

### Syntax 3

*since arma3 2.04*

```sqf
hashMap insert [[key1, value1], [key2, value2], ...]
```

**Parameters:**

- `hashMap`: [HashMap](../topics/HashMap.md)
- `keyN`: [HashMapKey](../topics/HashMapKey.md)
- `valueN`: [Anything](../topics/Anything.md)

**Returns:** [Nothing](../topics/Nothing.md)

### Syntax 4

*since arma3 2.04*

```sqf
hashMap insert [splitArray, [keysAndValues]]
```

**Parameters:**

- `hashMap`: [HashMap](../topics/HashMap.md)
- `splitArray`: [Boolean](../topics/Boolean.md) - determines *keysAndValues* format (see *keysAndValues*'s description)
- `keysAndValues`: [Array](../topics/Array.md) - in format depending on *splitArray*'s value:
  - [true](../commands/true.md) - `[[key1, key2, ...], [value1, value2, ...]]`
  - [false](../commands/false.md) - `[[key1, value1], [key2, value2], ...]` (same as [#Syntax 3](../commands/insert.md#syntax-3), see [#Example 3](../commands/insert.md#example-3) for the correct format)

**Returns:** [Nothing](../topics/Nothing.md)

## Examples

### Example 1

```sqf
"Test" insert [0, "Radio"];        // returns "RadioTest"
"Test" insert [2, "Radio"];        // returns "TeRadiost"
"Test" insert [-1, "Radio"];    // returns "TestRadio"
```

### Example 2

```sqf
private _array = ["a", "b", "c"];
_array insert [0, ["w"]]; // _array is now ["w", "a", "b", "c"]

private _array = ["a", "b", "c"];
_array insert [-1, ["w"]]; // _array is now ["a", "b", "c", "w"]

private _array = ["a", "b", "c"];
_array insert [-2, ["w"]]; // _array is now ["a", "b", "w", "c"] // Arma 3 v2.14
```

### Example 3

```sqf
// Notice how the size of the right array changes depending on the format of keysAndValues format
private _map = createHashMap;
_map insert [false, ["one", 1]];

private _map = createHashMap;
_map insert [true, ["one"], [1]];
```

## See also

[HashMap](../topics/HashMap.md) · [pushBack](../commands/pushBack.md) · [pushBackUnique](../commands/pushBackUnique.md) · [append](../commands/append.md) · [+](../commands/~2B.md) · [merge](../commands/merge.md)

<sub>Source: [BI Community Wiki — insert](https://community.bistudio.com/wiki/insert) (revision 377154).</sub>