This function replaces all or part of the text matched by the last search. It works by means of the match data.
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
nilfor string and make sure that the current buffer when you call
replace-matchis the one in which you did the searching or matching. Then
replace-matchdoes the replacement by editing the buffer; it leaves point at the end of the replacement text, and returns
If you did the search in a string, pass the same string as string. Then
replace-matchdoes the replacement by constructing and returning a new string.
If fixedcase is non-
replace-matchuses 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:
- ‘\&’ stands for the entire text being replaced.
- ‘\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 ‘\(...\)’. If the nth subexpression never matched, an empty string is substituted.
- ‘\\’ stands for a single ‘\’ in the replacement text.
These substitutions occur after case conversion, if any, so 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-matchwith 1 as subexp means to replace just the text that matched ‘\(ba*r\)’.
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