44.6.2 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 strbuffer

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 the fourth argument string is a string, fifth argument strbuffer specifies the buffer to be used for syntax-table and case-table lookup and defaults to the current buffer. When string is not a string, the buffer that the match occurred in has automatically been remembered and you do not need to specify it.

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 case-replace is nil, then case conversion is not done, regardless of the value of fixedcase. See Searching and 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.