|string||The source string. It can be a numeric value, a string literal, the name of a variable, or any valid ObjectScript expression. If string is an empty string (""), $REPLACE returns an empty string.|
|searchstr||The substring to search for in string. It can be a numeric value, a string literal, the name of a variable, or any valid ObjectScript expression. If searchstr is an empty string (""), $REPLACE returns string.|
|replacestr||The replacement substring substituted for instances of searchstr in string. It can be a numeric value, a string literal, the name of a variable, or any valid ObjectScript expression. If replacestr is an empty string (""), $REPLACE returns string with the occurrences of searchstr removed.|
|start||Optional — Character count position within string where substring search is to begin. String characters are counted from 1. A value of 0, a negative number, a nonnumeric string or an empty string are equivalent to 1. If omitted, 1 is assumed. If start > 1, the substring of string beginning with that character is returned, with substring substitutions (if any) performed. If start > $LENGTH(string), $REPLACE returns the empty string ("").|
|count||Optional — Number of substring substitutions to perform. If omitted, the default value is -1, which means perform all possible substitutions. A value of 0, a negative number other than -1, a nonnumeric string or an empty string are equivalent to 0 which means perform no substitutions. If start is specified, count begins substring substitutions from the start position.|
|case||Optional — Boolean flag indicating whether matching of searchstr in string is to be case-sensitive. 0 = case-sensitive (the default). 1 = not case-sensitive. Any nonzero number is equivalent to 1. Any nonnumeric value is equivalent to 0. Placeholder commas can be supplied when start or count are not specified.|
The $REPLACE 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 $REPLACE finds one or more matches, it replaces the searchstr substring with replacestr and returns the resulting string. The replacestr argument value may be long or shorter than searchstr. To remove searchstr substrings, specify the empty string ("") for replacestr.
By default, $REPLACE begins at the start of string and replaces every instance of searchstr. You can use the optional start argument to begin comparisons at a specified character count location within the string. The returned string is a substring of string that begins at the start location and replaces every instance of searchstr from that point.
You can use the optional count argument to replace only a specified number of matching substrings.
By default, $REPLACE substring matching is case-sensitive. You can use the optional case argument to specify not case-sensitive matching.
Because $REPLACE can change the length of a string, you should not use $REPLACE on encoded string values, such as an ObjectScript $List or a %List object property.
$REPLACE, $CHANGE, and $TRANSLATE
$REPLACE and $CHANGE 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.
The following example shows two ways of using $REPLACE. The first $REPLACE does not change the input string value. The second $REPLACE changes the input string value by setting it equal to the function’s return value:
SET str="The quick brown fox" // creates a new string, does not change str value SET newstr=$REPLACE(str,"brown","red") WRITE "source string: ",str,!,"new string: ",newstr,!! // creates a new string and replaces str with new string value SET str=$REPLACE(str,"brown","silver") WRITE "revised string: ",str
In the following example, invocations of $REPLACE match and substitute for the all instances of a substring, and the first two instances of a substring:
SET str="1110/1110/1100/1110" WRITE !,"before conversion ",str SET newall=$REPLACE(str,"111","AAA") WRITE !,"after replacement ",newall SET newsome=$REPLACE(str,"111","AAA",1,2) WRITE !,"after replacement ",newsome
In the following example, invocations of $REPLACE perform case-sensitive and not case-sensitive matching and replacement of all occurrences in the string:
SET str="Yes/yes/Y/YES/Yes" WRITE !,"before conversion ",str SET case=$REPLACE(str,"Yes","NO") WRITE !,"after replacement ",case SET nocase=$REPLACE(str,"Yes","NO",1,-1,1) WRITE !,"after replacement ",nocase
The following example compares the $REPLACE and $TRANSLATE functions:
SET str="A mom, o plom, o comal, Pomama" WRITE !,"before conversion ",str SET s4s=$REPLACE(str,"om","an") WRITE !,"after replacement ",s4s SET c4c=$TRANSLATE(str,"om","an") WRITE !,"after translation ",c4c
$REPLACE returns "A man, o plan, o canal, Panama"
$TRANSLATE returns "A nan, a plan, a canal, Panana"
In the following example, the four-argument form of $REPLACE returns only the part of the string beginning with the start point, with the string-for-string replacements performed:
SET str="A mon, a plon, a conal, Ponama" WRITE !,"before start replacement ",str SET newstr=$REPLACE(str,"on","an",8) WRITE !,"after start replacement ",newstr
$REPLACE returns "a plan, a canal, Panama"