Share via


replace Method

Returns a copy of a string with text replaced using a regular expression or search string.

function replace(rgExp : RegExp, replaceText : String) : String

Arguments

  • rgExp
    Required. An instance of a Regular Expression object containing the regular expression pattern and applicable flags. Can also be a String object or literal. If rgExp is not an instance of a Regular Expression object, it is converted to a string, and an exact search is made for the results; no attempt is made to convert the string into a regular expression.

  • replaceText
    Required. A String object or string literal containing the text to replace for every successful match of rgExp in the current string object. In JScript 5.5 or later, the replaceText argument can also be a function that returns the replacement text.

Remarks

The result of the replace method is a copy of the current string object after the specified replacements have been made.

Any of the following match variables can be used to identify the most recent match and the string from which it came. The match variables can be used in text replacement where the replacement string has to be determined dynamically.

Characters

Meaning

$$

$ (JScript 5.5 or later)

$&

Specifies that portion of the current string object that the entire pattern matched. (JScript 5.5 or later)

$`

Specifies that portion of the current string object that precedes the match described by $&. (JScript 5.5 or later)

$'

Specifies that portion of the current string object that follows the match described by $&. (JScript 5.5 or later)

$n

The nth captured submatch, where n is a single decimal digit from 1 through 9. (JScript 5.5 or later)

$nn

The nnth captured submatch, where nn is a two-digit decimal number from 01 through 99. (JScript 5.5 or later)

If replaceText is a function, for each matched substring the function is called with the following m + 3 arguments where m is the number of left capturing parentheses in the rgExp. The first argument is the substring that matched. The next m arguments are all of the captures that resulted from the search. Argument m + 2 is the offset within the current string object where the match occurred, and argument m + 3 is the current string object. The result is the string value that results from replacing each matched substring with the corresponding return value of the function call.

The replace method updates the properties of the global RegExp object.

Example

The following example illustrates the use of the replace method to replace all instances of "the" with "a".

function ReplaceDemo()
{
    var s = "The batter hit the ball with the bat ";
    s += "and the fielder caught the ball with the glove.";

    // Replace "the" with "a".
    var re = /the/g;
    var r = s.replace(re, "a");
    return(r);
}

In addition, the replace method can also replace subexpressions in the pattern. The following example exchanges each pair of words in the string.

function ReplaceDemo(){
    var s = "The quick brown fox jumps over the lazy dog.";
    // Create regular expression pattern.
    var re = /(\S+)(\s+)(\S+)/g;
    // Exchange each pair of words.
    var r = s.replace(re, "$3$2$1");
    return(r);
}
    // Output:  quick The fox brown over jumps lazy the dog.

The following example, which works in JScript 5.5 and later, performs a Fahrenheit to Celsius conversion. It illustrates how to use a function that returns the replacement text. To see how this function works, pass in a string that contains a number followed immediately by an "F" (for example, "Water boils at 212C").

function f2c(s1) {
    // Initialize pattern.
    var test = /(\d+(\.\d*)?)F\b/g;

    // Use a function for the replacement.    
    var s2 = s1.replace(test,
       function($0,$1,$2)
           { 
           return((($1-32) * 5/9) + "C");
           }
      )
  return s2;
}
print(f2c("Water freezes at 32F and boils at 212F."));

Requirements

Version 1

Applies To:

String Object

See Also

Reference

exec Method

match Method

RegExp Object

search Method

test Method