Add To Array

Add to Array

Adds a single data value at the specified location in an array variable.

Use this action cell to populate new and existing array variables with data.

You cannot add a value to an array that already contains its maximum limit of values (see Array for the limit).

Properties

Option

Description

Array

Enter the array variable containing the array that will take the new value.

Position

Select the array position at which you want to insert the new value:

Note: the value will be inserted only if the array contains less than its maximum limit of values. You can use the Get Array Length action cell to check this.

Start	Inserts the new value at the start of the array (at the index position of 0) shifting all current values up by one index position.
End	(Default) Inserts the new value at the end of the array.
At Index	Inserts the new value at the index position specified in the Index property shifting all current values up by one index position.

Index

If you selected the 'At Index' option for the Position property, enter the index location (as a literal value or an integer variable) at which to insert the new value. For a maximum permitted array length of 50 values, the index must be in the range -50 and 49. A minus value counts backwards from the end of the array and facilitates adding values that are near the end of the array.

As an example, in an array containing 5 values, the indexing is as shown below:


Index	0	1	2	3	4
	-5	-4	-3	-2	-1
Array	Value A	Value B	Value C	Value D	Value E

Specifying an index of 2 or -3 has the effect of inserting a new value (X) immediately before that index location (shaded) to give the following longer array in which some of the indexes now refer to different values.


Index	0	1	2	3	4	5
	-6	-5	-4	-3	-2	-1
Array	Value A	Value B	Value X	Value C	Value D	Value E
			(new)

Note: if you provide a positive index that exceeds the number of values in the array, then the value is added to the end of the array. Similarly, if you provide a negative index that exceeds the number of array values, then the value is added to the start of the array.

Value

Enter the value to add to the array (a literal value or a variable matching the data type of the array).

Note: a date value must be provided as a variable and not as a literal.

Exit Points

Exit Point	Description
Complete	This is taken if the new value was added to the specified index location and the array had still NOT reached its maximum capacity.
Max Size Reached	This is taken if the new value was added to the specified index location and the array had then reached its maximum capacity.
Error	This is taken if the specified array index location was not found or if an error has occurred.