InsertArrayItem

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:

This function supersedes the System Library's InsertListItem. This function is intended for use on dynamically allocated arrays, that is, arrays that have been created via the New function. If used with an array that has been statically declared, 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.