# insert() function

The insert() function inserts the element
referenced by *str.exp* into a specific attribute,
value, or subvalue location in *dyn.array.exp*.

## Syntax

```
insert(dyn.array.exp, ac.exp; str.exp)
insert(dyn.array.exp, ac.exp, vc.exp; str.exp)
insert(dyn.array.exp, ac.exp, vc.exp, sc.exp; str.exp)
```

## Parameter(s)

| dyn.array.exp | Dynamic array in which the element will be inserted. |
| --- | --- |
| ac.exp | Attribute in which the element will be inserted. |
| vc.exp | Value in which the element will be inserted. |
| sc.exp | Subvalue in which the element will be inserted. |
| str.exp | Element to insert in the dynamic array. |

## Description

-1 can be specified as the attribute
count expression, value count expression, or subvalue count expression.
Position -1 inserts the expression as the last element in the respective
location.

0 can be specified as the attribute count expression.
Position 0 inserts the expression as the first attribute. A 0 as the
value count expression, or the subvalue count expression is ignored.

Unlike the replace() function, which changes
the contents of a dynamic array element without changing its logical
position or any other element, the insert() function
inserts the results of str.exp at the specified
location and all following information at that dynamic array level
(attribute, value, or subvalue) is shifted one position higher in
the array. If an attribute count expression of 1 is specified, the
expression is inserted before attribute 1, shifting attribute 1 to
attribute 2.

The insert(), replace(), and delete() functions force the entire dynamic
array (string) to be rebuilt.

## Example(s)

These examples are exactly the
same. They insert the current value of `name` in attribute
1 of the array, `customer.item`. Every other value
in attribute 1 shifts right by one position. (Value `1` becomes value `2`, and so on.) The values of attribute
1 are shifted, but the other attributes in the item maintain their
relative position.

```
customer.item = insert(customer.item,1,1,0,name)
customer.item = insert(customer.item,1,1;name)
```

## See also

- [Array references](https://d3codex.com/pickbasic-flashbasic/array-references/)
- [Array variable](https://d3codex.com/pickbasic-flashbasic/array-variable/)
- [Assignment](https://d3codex.com/pickbasic-flashbasic/assignment/)
- [Attribute count expression](https://d3codex.com/pickbasic-flashbasic/attribute-count-expression/)
- [del statement](https://d3codex.com/pickbasic-flashbasic/del-statement/)
- [delete() function](https://d3codex.com/pickbasic-flashbasic/delete-function/)
- [extract() function](https://d3codex.com/pickbasic-flashbasic/extract-function/)
- [BASIC functions](https://d3codex.com/pickbasic-flashbasic/basic-functions/)
- [ins statement](https://d3codex.com/pickbasic-flashbasic/ins-statement/)
- [locate statement](https://d3codex.com/pickbasic-flashbasic/locate-statement/)
- [ereplace() function](https://d3codex.com/pickbasic-flashbasic/ereplace-function/)
- [Statements and functions](https://d3codex.com/pickbasic-flashbasic/statements-and-functions/)
- [String expressions](https://d3codex.com/pickbasic-flashbasic/string-expressions/)
- [Subvalue count expressions](https://d3codex.com/pickbasic-flashbasic/subvalue-count-expressions/)
- [Value count expression](https://d3codex.com/pickbasic-flashbasic/value-count-expression/)

---
Source: https://d3codex.com/pickbasic-flashbasic/insert-function/ - part of the D3Codex reference.