$REPLACE

Returns a new string that consists of a string-for-string substring replacement from an input string.

Synopsis

$REPLACE(string,searchstr,replacestr,start,count,case)

Parameters

Argument	Description
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.

Description

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 parameter value may be long or shorter than searchstr; replacestr may be an empty string.

By default, $REPLACE begins at the start of string and replaces every instance of searchstr. You can use the optional start parameter 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 parameter to replace only a specified number of matching substrings.

By default, $REPLACE substring matching is case-sensitive. You can use the optional case parameter to specify not case-sensitive matching.

Note:

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 and $TRANSLATE

$REPLACE performs string-for-string matching and replacement. $TRANSLATE performs character-for-character matching and replacement. $REPLACE can replace a single specified substring of one or more characters with another substring. $TRANSLATE can replace multiple specified characters with corresponding specified new characters. By default, both functions replace all matching instances in the string.

$REPLACE matching is case-sensitive by default, but can be invoked as not case-sensitive; $TRANSLATE matching is always case-sensitive. $REPLACE can specify the starting point for matching and/or the number of replacements to perform; $TRANSLATE replaces all matches in the source string.

Examples

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-parameter 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"