Replace method: Array class

Syntax

Replace(start, length[, paramlist])

Where paramlist is an arbitrary-length list of values in the form:

value1 [, value2] ...

Description

Replace replaces the length elements starting at start with the given values, if any. If length is zero, the insertion takes place before the element indicated by start. Otherwise, the replacement starts with start and continues up to and including length, replacing the existing values with paramlist.

If a negative number is used for start, it indicates the starting position relative to the last element in the array, such that −1 indicates the position just after the end of the array. To insert at the end of the array (equivalent to the Push method), use a start of −1 and a length of 0.

If a negative number is used for length, it indicates a length measuring downward to lower indexes. Both flattening and promotion can be applied to change the dimension of the supplied parameters to match the elements of the given array.

Similar to how the built-in function Replace is used to update a string, the Replace method is a general way to update an array, and can cause the array to grow or shrink.

See Using Flattening and Promotion.

Parameters

Parameter	Description
start	Specifies where to start replacing the given elements in the array. If a negative number is used for start, it indicates the starting position relative to the last element in the array.
length	Specifies the number of elements in the array to be replaced.
paramlist	Specifies values to be used to replace existing values in the array. This parameter is optional.

Returns

None.

Example

For example, given the following array:

Local array of string &AS;

&AS = CreateArray("AA", "BB", "CC");

After executing the next code, the array &AN will contain four elements, ZZ, YY, BB, CC:

&AS.Replace(1, 1, "ZZ", "YY");

After executing the next code, the array &AN will contain three elements, ZZ, MM, CC:

&AS.Replace(2, 2, "MM");

After executing the next code, the array &AN will contain three elements, ZZ, OO, CC.

&AS.Replace( - 2, - 1, "OO");

The following image is an example of &AS expanded in PeopleCode debugger.

Using Replace to Remove an Element

You can use the Replace method to remove an element from an array. Just specify the item you want replaces, with length equal to one.

The following example removes the item from &Index:

&Array.Replace(&Index, 1);