Function

insert( array, value, index )

Inserts a value into the given array and returns the resulting array.

Parameters

Returns

Any Type Array

Usage considerations

Index values

When the index value is greater than the array length or is less than 1, the value is appended to the right side of the array.

Data types of array items

The array to be modified can contain items of one or more types. When all array items are of a single type, the value must be the same type as the current items. The updated array will be a list of that type. For example, insert({10, 20}, 30, 2) returns 10, 30, 20, a List of Number (Integer).

Any values that are not the same type will not be added. For example, insert({10, 20, 30, 40}, "fifty", 2) returns 10, null, 20, 30, 40 because the text value ("fifty") cannot be added to an array of numbers.

An array with values of more than one type returns a List of Variant. For example, insert({10, "twenty"}, 30, 3) returns 10, "twenty", 30, , a List of Variant with a Number (Integer), Text, and Number (Integer).

You can append values of any type to these mixed-type arrays. For example, insert({10, "twenty"}, 30.15, 3) returns 10, "twenty", 30.15, a List of Variant with a Number (Integer), Text, and Number (Decimal).

Match the length of the value and index parameters

When using a list as the index parameter, the value must be a scalar value or a list of matching length.

If the index list is longer, a null is inserted at each index where there is not a corresponding value element.

For example, insert({10,20,30}, {100,2}, {1,2,3,4}) returns {100, 10, 2, 20, null, 30, null} because the value list has a length of 2. Once the values from the list are inserted, nulls are inserted at any remaining indexes.

Examples

Insert a value as the first array item

1
insert({10, 20, 30, 40}, 100, 1)

Returns {100, 10, 20, 30, 40}.

Insert a value as the last array item

1
insert({10, 20, 30, 40}, 100, 5)

Returns {10, 20, 30, 40, 100} because the index is greater than the length of the array.

Insert multiple values at the start of the array

1
insert({10, 20, 30, 40}, {100, 200}, 1)

Returns {100, 200, 10, 20, 30, 40}.

Insert a value at multiple array indexes

1
insert({10, 20, 30, 40}, 100, {1, 2})

Returns {100, 10, 100, 20, 30, 40}.

Insert a value from a list at a specific index

When using a list for the index parameter, Appian uses the existing index positions of the array to insert new values.

1
insert({10, 20, 30, 40}, {100, 200}, {1, 2})

Returns {100, 10, 200, 20, 30, 40}. The first change inserts 100 at index 1 and 200 at index 2 (after 10).

Feature compatibility