CHANGE
Synopsis
CHANGE(string,subout,subin[,occurrences[,begin]])
Arguments
| string | The string in which substring substitutions are made. An expression that resolves to a string or numeric. string may be a dynamic array. |
| subout | The substring to be replaced. An expression that resolves to a string or numeric. |
| subin | The substring to be inserted in place of subout. An expression that resolves to a string or numeric. |
| occurrences | Optional — The number of occurrences of subout to replace with subin. An expression that resolves to a positive integer. If omitted, all occurrences are replaced. If used with begin, you can specify an occurrences value of -1 indicating that all occurrences of subout from the begin point to the end of the string are to be replaced. |
| begin | Optional — Which occurrence of subout to begin replacement with. An expression that resolves to a positive integer. If omitted, or specified as 0 or 1, replacement begins with the first occurrence of subout. |
Description
The CHANGE function edits the value of string by replacing some or all instances of subout with subin. The subout and subin values may be of different lengths. Matching of strings is case-sensitive.
The value of subout and subin can be a string or a numeric. If numeric, the value is converted to canonical form (plus sign, leading and trailing zeros removed) before performing the CHANGE operation.
To remove all instances of subout from string, specify the null string ("") as the subin value. The null string ("") cannot be used as the subout value.
The value of occurrences may be larger than the actual number of occurrences. If occurrences is omitted, or set to a value of 0, a negative number, the null string, or a non-numeric string, all occurrences are replaced. If occurrences is set to a decimal number, it is truncated to an integer; if set to a mixed numeric string, it resolves to the numeric portion of the string.
Caché MVBasic supports both the UniVerse CHANGE function and the UniData SWAP statement, both of which perform substring replacement.
You can use the CONVERT function to perform character-for-character substitutions.
Examples
The following example illustrates use of the CHANGE function, replacing a substring value in all the elements of a dynamic array:
cities="Pittsburg Penn.":@VM:"Philadephia Penn."
CHANGE(cities,"Penn.","PA")
The following example illustrates use of the CHANGE function, replacing the third and fourth occurrences of a substring value:
teststr=123test123test123test123test123test123test
CHANGE(teststr,"test","RETRY",2,3)
! Returns "123test123test123RETRY123RETRY123test123test"
