GNU Info

(elisp)Replacing Match

---

Next: Simple Match Data Up: Match Data

---

Enter node , (file) or (file)node

Replacing the Text that Matched
-------------------------------

   This function replaces the text matched by the last search with
REPLACEMENT.

 - Function: replace-match replacement &optional fixedcase literal
          string subexp
     This function replaces the text in the buffer (or in STRING) that
     was matched by the last search.  It replaces that text with
     REPLACEMENT.

     If you did the last search in a buffer, you should specify `nil'
     for STRING.  Then `replace-match' does the replacement by editing
     the buffer; it leaves point at the end of the replacement text,
     and returns `t'.

     If you did the search in a string, pass the same string as STRING.
     Then `replace-match' does the replacement by constructing and
     returning a new string.

     If FIXEDCASE is non-`nil', then the case of the replacement text
     is not changed; otherwise, the replacement text is converted to a
     different case depending upon the capitalization of the text to be
     replaced.  If the original text is all upper case, the replacement
     text is converted to upper case.  If the first word of the
     original text is capitalized, then the first word of the
     replacement text is capitalized.  If the original text contains
     just one word, and that word is a capital letter, `replace-match'
     considers this a capitalized first word rather than all upper case.

     If LITERAL is non-`nil', then REPLACEMENT is inserted exactly as
     it is, the only alterations being case changes as needed.  If it
     is `nil' (the default), then the character `\' is treated
     specially.  If a `\' appears in REPLACEMENT, then it must be part
     of one of the following sequences:

    `\&'
          `\&' stands for the entire text being replaced.

    `\N'
          `\N', where N is a digit, stands for the text that matched
          the Nth subexpression in the original regexp.  Subexpressions
          are those expressions grouped inside `\(...\)'.

    `\\'
          `\\' stands for a single `\' in the replacement text.

     If SUBEXP is non-`nil', that says to replace just subexpression
     number SUBEXP of the regexp that was matched, not the entire
     match.  For example, after matching `foo \(ba*r\)', calling
     `replace-match' with 1 as SUBEXP means to replace just the text
     that matched `\(ba*r\)'.