InsertInArray

Purpose

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

Return Type

Syntax

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

Parameters

{ArrayId}: The source array. This must be a dynamic array that can be resized accordingly.
{index}: 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, as this is a very inefficient way of adding an element to an array. Use Move {value} to {ArrayId}[-1] instead.
{value}: 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 one 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

Additional 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.

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