Info Catalog elisp: Match Data elisp: Simple Match Data

elisp: Replacing Match

 
 33.6.1 Replacing the Text that Matched
 --------------------------------------
 
 This function replaces all or part of the text matched by the last
 search.  It works by means of the match data.
 
  -- Function: replace-match replacement &optional fixedcase literal
           string subexp
      This function performs a replacement operation on a buffer or
      string.
 
      If you did the last search in a buffer, you should omit the STRING
      argument or specify ‘nil’ for it, and make sure that the current
      buffer is the one in which you performed the last search.  Then
      this function edits the buffer, replacing the matched text with
      REPLACEMENT.  It leaves point at the end of the replacement text.
 
      If you performed the last search on a string, pass the same string
      as STRING.  Then this function returns a new string, in which the
      matched text is replaced by REPLACEMENT.
 
      If FIXEDCASE is non-‘nil’, then ‘replace-match’ uses the
      replacement text without case conversion; otherwise, it converts
      the replacement text depending upon the capitalization of the text
      to be replaced.  If the original text is all upper case, this
      converts the replacement text to upper case.  If all words of the
      original text are capitalized, this capitalizes all the words of
      the replacement text.  If all the words are one-letter and they are
      all upper case, they are treated as capitalized words rather than
      all-upper-case words.
 
      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:
 
      ‘\&’
           This stands for the entire text being replaced.
 
      ‘\N’, where N is a digit
           This stands for the text that matched the Nth subexpression in
           the original regexp.  Subexpressions are those expressions
           grouped inside ‘\(...\)’.  If the Nth subexpression never
           matched, an empty string is substituted.
 
      ‘\\’
           This stands for a single ‘\’ in the replacement text.
 
      ‘\?’
           This stands for itself (for compatibility with
           ‘replace-regexp’ and related commands; (emacs)Regexp
           Replace).
 
      Any other character following ‘\’ signals an error.
 
      The substitutions performed by ‘\&’ and ‘\N’ occur after case
      conversion, if any.  Therefore, the strings they substitute are
      never case-converted.
 
      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\)’.
 
  -- Function: match-substitute-replacement replacement &optional
           fixedcase literal string subexp
      This function returns the text that would be inserted into the
      buffer by ‘replace-match’, but without modifying the buffer.  It is
      useful if you want to present the user with actual replacement
      result, with constructs like ‘\N’ or ‘\&’ substituted with matched
      groups.  Arguments REPLACEMENT and optional FIXEDCASE, LITERAL,
      STRING and SUBEXP have the same meaning as for ‘replace-match’.
 

Info Catalog elisp: Match Data elisp: Simple Match Data