|string||The string in which substring substitutions are made. Any expression that resolves to a valid string or numeric.|
|searchstr||The substring to be replaced. Any expression that resolves to a valid string or numeric.|
|replacestr||The substring to be inserted in place of searchstr. Any expression that resolves to a valid string or numeric.|
|occurrences||Optional — A positive integer specifying the number of occurrences of searchstr to replace with replacestr. If omitted, all occurrences are replaced. If used with begin, you can specify an occurrences value of -1 indicating that all occurrences of searchstr from the begin point to the end of the string are to be replaced. occurrences can be larger than the number of occurrences in string.|
|begin||Optional — An integer specifying which occurrence of searchstr to begin replacement with. If omitted, or specified as 0 or 1, replacement begins with the first occurrence of searchstr.|
The $CHANGE function returns a new string that consists of a string-for-string replacement of the input string. It searches string for the searchstr substring. If $CHANGE finds one or more matches, it replaces the searchstr substring with replacestr and returns the resulting string. The replacestr parameter value may be long or shorter than searchstr. To remove searchstr substrings, specify the empty string ("") for replacestr.
$CHANGE and $REPLACE both perform substring replacement. Both allow you to replace all substring matches or only a specified number of substring matches. $CHANGE determines where to begin replacements based on a count of searchstr substring occurrences. $REPLACE determines where to begin replacements based on a character count from the beginning of string. $CHANGE returns the full string (with substring replacements) regardless of where it begins performing replacements. $REPLACE only returns the portion of string from the begin character count position.
Because $CHANGE can change the length of a string, you should not use $CHANGE on encoded string values, such as an ObjectScript $List or a %List object property.
$CHANGE, $REPLACE, and $TRANSLATE
$CHANGE and $REPLACE perform string-for-string matching and replacement. They can replace a single specified substring of one or more characters with another substring of any length. $TRANSLATE performs character-for-character matching and replacement. $TRANSLATE can replace multiple specified single characters with corresponding replacement single characters. All three functions can remove matching characters or substrings — replacing with null.
$CHANGE is always case-sensitive. $REPLACE matching is case-sensitive by default, but can be invoked as not case-sensitive. $TRANSLATE matching is always case-sensitive.
$REPLACE and $CHANGE can specify the starting point for matching and/or the number of replacements to perform. $REPLACE and $CHANGE differ in how they define the starting point. $TRANSLATE always replaces all matches in the source string.