Skip to main content

$REPLACE (ObjectScript)

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)

Arguments

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

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, $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.

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

See Also

Feedback