Function: replace-regexp-in-region

replace-regexp-in-region is a byte-compiled function defined in subr.el.gz.

Signature

(replace-regexp-in-region REGEXP REPLACEMENT &optional START END)

Documentation

Replace REGEXP with REPLACEMENT in the region from START to END.

The number of replaced occurrences are returned, or nil if REGEXP doesn't exist in the region.

If START is nil, use the current point. If END is nil, use point-max.

Comparisons and replacements are done with fixed case.

REPLACEMENT can use the following special elements:

  \& in NEWTEXT means substitute original matched text.
  \N means substitute what matched the Nth \(...\).
       If Nth parens didn't match, substitute nothing.
  \\ means insert one \.
  \? is treated literally.

Other relevant functions are documented in the regexp group.

View in manual

Probably introduced at or before Emacs version 28.1.

Shortdoc

;; regexp
(replace-regexp-in-region "[0-9]+" "Num \\&")

Aliases

tramp-compat-replace-regexp-in-region

Source Code

;; Defined in /usr/src/emacs/lisp/subr.el.gz
(defun replace-regexp-in-region (regexp replacement &optional start end)
  "Replace REGEXP with REPLACEMENT in the region from START to END.
The number of replaced occurrences are returned, or nil if REGEXP
doesn't exist in the region.

If START is nil, use the current point.  If END is nil, use `point-max'.

Comparisons and replacements are done with fixed case.

REPLACEMENT can use the following special elements:

  `\\&' in NEWTEXT means substitute original matched text.
  `\\N' means substitute what matched the Nth `\\(...\\)'.
       If Nth parens didn't match, substitute nothing.
  `\\\\' means insert one `\\'.
  `\\?' is treated literally."
  (if start
      (when (< start (point-min))
        (error "Start before start of buffer"))
    (setq start (point)))
  (if end
      (when (> end (point-max))
        (error "End after end of buffer"))
    (setq end (point-max)))
  (save-excursion
    (goto-char start)
    (save-restriction
      (narrow-to-region start end)
      (let ((matches 0)
            (case-fold-search nil))
          (while (re-search-forward regexp nil t)
          (replace-match replacement t)
          (setq matches (1+ matches)))
        (and (not (zerop matches))
             matches)))))