InsertInArray

Purpose

Returns an expanded copy of the specified array that includes one new element inserted at the specified index.

Return Type

Array

Syntax

InsertInArray( {ArrayId}, {index}, {value} )

Where:

{ArrayId} is the source array. This must be a dynamic array that can be resized accordingly.
{index} is the zero based index where the insertion is to take place. This must be a valid index in {ArrayId}. You may pass the size of the array as your index, which will append the item at the end. If -1 is passed as the index, the item will be "inserted" at the end of the array, making it an append as well. We advise against using -1 as an index for this is a very inneficient way of adding an element to an array. Use "Move {value} to {ArrayId}[-1]" instead.
{value} is the value that should be inserted at the specified {index}.

What it Does

Returns an expanded copy of the specified array that includes one new element inserted at the specified index. The returned array is an expanded copy of {ArrayId} containing one more element with the specified {value} inserted at the specified {index}, such that the corresponding index of all remaining elements from {index} in the source {ArrayId} is shifted +1.

Use AppendArray to append one or more elements from on array to another array.

Use RemoveFromArray to remove elements from an array.

Example

This sample code will return an array with the values 1,9,2,3,4.

Integer[] myArray

Move 1 to myArray[0]

Move 2 to myArray[1]

Move 3 to myArray[2]

Move 4 to myArray[3]

Move (InsertInArray(myArray, 1, 9)) to myArray

Examples

This sample code will return an array of 4 tFriend structs where new friend Amanda Edwards is inserted before Frank Jones as the second array element (at index 1).

Struct tFriend

String First

String Last

End_Struct

Procedure Test

tFriend[] myFriends

Move "Joe" to myFriends[0].First

Move "Cool" to myFriends[0].Last

Move "Frank" to myFriends[1].First

Move "Jones" to myFriends[1].Last

Move "Susie" to myFriends[2].First

Move "Smith" to myFriends[2].Last

tFriend newFriend

Move "Amanda" to newFriend.First

Move "Edwards" to newFriend.Last

Move (InsertInArray(myFriends, 1, newFriend)) to myFriends

End_Procedure

This sample is identical to the prior sample, with the exception that -1 is passed as the index, thus appending the new element (Amanda Edwards) to the end of the array.