InsertArrayItem

(Engine-Level Function)

Description:	Insert Array Item. This function inserts an element into a dynamically allocated array and returns the modified array.
Returns:	Array
Usage:	Script Only.
Function Groups:	Array
Related to:	DeleteArrayItem \| New
Format:	InsertArrayItem(Array [, Index, Value])
Parameters:

Array

Required. Any variable whose value is invalid or contains a dynamically allocated array (one created via a New function call). This should be a single dimension array or unexpected results may occur.

Index

An optional parameter that is any numeric expression for the index at which to insert a new element. If this value is invalid, the new element will be inserted at the end of the array.

Value

An optional parameter that is any expression for the value to assign to the new array element.

Comments:

Building an array in this fashion has O(n^2) complexity, meaning it is an extremely slow way to build an array of any size.
It is far more efficient to add elements to a Dictionary and use ListKeys to make an array

This function is intended for use on dynamically allocated arrays, created via the New function. If used with an array that has been statically declared, then unless otherwise specified in the Array parameter, the first element of the array will be used, and a dynamically allocated array will be created/added-to in this element.

Examples:

  If 1 Next;
  [
    Data = InsertArrayItem(Data { Array to use }, 
                           Invalid { Insert at end }, 
                           32 { Value of element }); 
    Names = InsertArrayItem(Names { Array to use  }); 
  ]

The first statement inserts an element with a value of 32 at the end of array Data, while the second statement inserts an invalid element at the end of array Names.