ArrayReplace function (LotusScript® Language)
Performs a search and replace routine for multiple values within an array.
Syntax
ArrayReplace( sourceArray, compareArray, replaceArray )
Elements
sourceArray
The source array from which a copy, with possible modifications, will be produced.
compareArray
An array containing the elements to be compared to the elements in sourceArray (can be a scalar which is treated as a single-element array).
replaceArray
An array containing the elements to be used to replace elements from sourceArray (can be a scalar which is treated as a single-element array).
Return value
A Variant containing an array which is constructed by these rules (the answer array).
Usage
Each element in sourceArray is prepared to be copied into the answer array. The resulting array is the same size as the array contained in parameter sourceArray. If the source and replace arrays are arrays of matching types, the answer array will be of that type. Otherwise, the answer array will be an array of Variants.
For each element in sourceArray, compareArray is scanned. If no elements match, the element from sourceArray is copied into the next available index in the answer array. However, if an element of compareArray matches an element from sourceArray, the index of the compareArray element is used to find a value in the array replaceArray. This value is then copied into the answer array instead of the value from sourceArray.
For example:
sourceArray = [1,2,3,4,5]
compareArray = [2,4,6,8,10,12,14,16,18,20]
replaceArray = [8,6,25,0,0,11,17]
Element 1 from sourceArray is compared to the elements in compareArray. Since no match is found, the first element from sourceArray is copied into the answer array in the first element.
answer array = [1,...]
Element 2 from sourceArray is compared to the elements in compareArray. The first element in compareArray matches the second element from sourceArray, so the index to the first element in compareArray, which is 1, is used to find a value in replaceArray, which is [8]. This value is then copied into the answer array.
answer array = [1,8,...]
Element 3 from sourceArray is compared to the elements in compareArray. Since no match is found, the third element from sourceArray is copied into the answer array.
answer array = [1,8,3,...]
Element 4 from sourceArray is compared to the elements in compareArray. The second element in compareArray matches the fourth element from sourceArray, so the index to the second element in compareArray, which is 2, is used to find a value in replaceArray, which is [6]. This value is then copied into the answer array.
answer array = [1,8,3,6,...]
The last element from sourceArray is compared to the elements in compareArray. Since no match is found, the fifth element from sourceArray is copied into the answer array.
answer array = [1,8,3,6,5]
If the index from compareArray cannot be used as an index into replaceArray (that is, the index is out of bounds), a 0 or type equivalent is copied into the answer array for that element.
Indices into the arrays are calculated from their base. Assume that compareArray is an array from (-10 to 0), and replaceArray is an array from (1 to 5). If the -10th element of compareArray, which is the first element in that array, is a match for a given element in sourceArray, then the first element of replaceArray is used as a replacement.
For example:
sourceArray(1 to 10) = [the,quick,sleek,cat,jumped,over,the,fat,sleeping,dog]
compareArray(-10 to 0) = [sleek,cat,jumped,fat,sleeping,under,ball,purple,tree,slow,over]
replaceArray(1 to 5) = [red,fox,hurdled,lazy,brown]
The first element in sourceArray is compared to the elements in compareArray. No match is found, so the first element from souceArray is copied to the answer array.
answer array=[the,...]
2. The second element in sourceArray is compared to the elements in compareArray. No match is found, so the first element from souceArray is copied to the answer array.
answer array=[the,quick,...]
The third element in sourceArray is compared to the elements in compareArray. A match is found at the first element of compareArray, but rather than trying to access the -10th index of replaceArray, which would be invalid, instead the equivalent index of the matching element of compareArray is calculated for replaceArray. As a result, the first element in replaceArray is then copied into the answer array.
answer array=[the,quick,red...]
Note that the 0th element of compareArray is a match for an element in sourceArray. Since this translates to 11 for replaceArray, which is out of bounds, a null value is used for the replacement value instead.
answer array=[the,quick,red,fox,hurdled,{null},...]
In this way "the quick sleek cat jumped over the fat sleeping dog" becomes "the quick red fox hurdled the lazy brown dog."
Each element type must match for a conversion to take place. For example, if sourceArray contains the value 1 of data type integer, and compareArray contains the value 1 of data type long, then these elements would not match.