---
url: >-
  /statelake/scripting-reference/functions-and-procedures/string-functions/insert.md
---

# Insert

The procedure **Insert** merges two strings together.

**Substr** is merged into **Dest** at the position given by **Index**.

* **Substr** is the string or array elements to insert into **Dest**. If **Substr** is empty, then **Dest** is not changed.

* **Dest** is the destination string or array, which is changed if the operation succeeds. **Dest** must be a variable.

* **Index** is the insertion position:

  * For a string, if **Index** is less than 1, it is set to 1. If it is past the end of **Dest**, is set to the length of **Dest**, turning the operation into an append.
  * For an array, **Insert** inserts a dynamic array at the beginning at the position **Index**, and returns the modified array.

::: info
**Index** is a character index and not a byte index. But it must be incremented by 2 to pass over a **surrogate pair**. When iterating or counting the characters in a Unicode string, a surrogate pair is considered to be two characters.
:::

**Insert** throws an exception error if it is unable to allocate enough memory to accommodate the new returned string or array.

**Declaration**: Procedure Insert(Substr: string; var Dest: string; Index: Integer);

Example

```pascal
procedure OnMapEvent(var Value:Variant);
var
  aStr, bStr, cStr, dStr : string;
begin
  aStr := 'one three';
  bStr := 'two ';
  cStr := 'One fish, red fish, blue fish.'
  dStr := 'two fish, '

 //Returns 'one two three'
  Insert('two ',aStr, 5);
 //Returns 'One fish, two fish, red fish, blue fish.'
  Insert(dStr, cStr, 11);

  LogInfo(aStr);
  LogInfo(cStr);
end;
```