Function: replace-regexp-in-string

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

Signature

(replace-regexp-in-string REGEXP REP STRING &optional FIXEDCASE LITERAL SUBEXP START)

Documentation

Replace all matches for REGEXP with REP in STRING.

Return a new string containing the replacements.

Optional arguments FIXEDCASE, LITERAL and SUBEXP are like the arguments with the same names of function replace-match. If START is non-nil, start replacements at that index in STRING, and omit the first START characters of STRING from the return value.

REP is either a string used as the NEWTEXT arg of replace-match or a function. If it is a function, it is called with the actual text of each match, and its value is used as the replacement text. When REP is called, the match data are the result of matching REGEXP against a substring of STRING, the same substring that is the actual text of the match which is passed to REP as its argument.

To replace only the first match (if any), make REGEXP match up to \' and replace a sub-expression, e.g.
  (replace-regexp-in-string "\\\\(foo\\\\).*\\\\\\='" "bar" " foo foo" nil nil 1)
    => " bar foo"

Other relevant functions are documented in the regexp and string groups.

View in manual

Probably introduced at or before Emacs version 21.1.

Shortdoc

;; string
(replace-regexp-in-string "[a-z]+" "_" "*foo*")
    => "*_*"
;; regexp
(replace-regexp-in-string "[a-z]+" "_" "*foo*")
    => "*_*"

Aliases

s-replace-regexp erc-replace-regexp-in-string (obsolete since 28.1) mh-replace-regexp-in-string (obsolete since 29.1) icalendar--rris (obsolete since 27.1)

Source Code

;; Defined in /usr/src/emacs/lisp/subr.el.gz
(defun replace-regexp-in-string (regexp rep string &optional
					fixedcase literal subexp start)
  "Replace all matches for REGEXP with REP in STRING.

Return a new string containing the replacements.

Optional arguments FIXEDCASE, LITERAL and SUBEXP are like the
arguments with the same names of function `replace-match'.  If START
is non-nil, start replacements at that index in STRING, and omit
the first START characters of STRING from the return value.

REP is either a string used as the NEWTEXT arg of `replace-match' or a
function.  If it is a function, it is called with the actual text of each
match, and its value is used as the replacement text.  When REP is called,
the match data are the result of matching REGEXP against a substring
of STRING, the same substring that is the actual text of the match which
is passed to REP as its argument.

To replace only the first match (if any), make REGEXP match up to \\\\='
and replace a sub-expression, e.g.
  (replace-regexp-in-string \"\\\\(foo\\\\).*\\\\\\='\" \"bar\" \" foo foo\" nil nil 1)
    => \" bar foo\""
  (declare (important-return-value t))

  ;; To avoid excessive consing from multiple matches in long strings,
  ;; don't just call `replace-match' continually.  Walk down the
  ;; string looking for matches of REGEXP and building up a (reversed)
  ;; list MATCHES.  This comprises segments of STRING that weren't
  ;; matched interspersed with replacements for segments that were.
  ;; [For a `large' number of replacements it's more efficient to
  ;; operate in a temporary buffer; we can't tell from the function's
  ;; args whether to choose the buffer-based implementation, though it
  ;; might be reasonable to do so for long enough STRING.]
  (let ((l (length string))
	(start (or start 0))
	matches str mb me)
    (save-match-data
      (while (and (< start l) (string-match regexp string start))
	(setq mb (match-beginning 0)
	      me (match-end 0))
	;; If we matched the empty string, make sure we advance by one char
	(when (= me mb) (setq me (min l (1+ mb))))
	;; Generate a replacement for the matched substring.
	;; Operate on only the substring to minimize string consing.
        ;; Translate the match data so that it applies to the matched substring.
        (match-data--translate (- mb))
        (setq str (substring string mb me))
	(setq matches
	      (cons (replace-match (if (stringp rep)
				       rep
				     (funcall rep (match-string 0 str)))
				   fixedcase literal str subexp)
		    (cons (substring string start mb) ; unmatched prefix
			  matches)))
	(setq start me))
      ;; Reconstruct a string from the pieces.
      (setq matches (cons (substring string start l) matches)) ; leftover
      (apply #'concat (nreverse matches)))))