Function: replace-string

replace-string is an interactive and byte-compiled function defined in replace.el.gz.

Signature

(replace-string FROM-STRING TO-STRING &optional DELIMITED START END BACKWARD REGION-NONCONTIGUOUS-P)

Documentation

Replace occurrences of FROM-STRING with TO-STRING.

Preserve case in each match if case-replace and case-fold-search are non-nil and FROM-STRING has no uppercase letters.
(Preserving case means that if the string matched is all caps, or capitalized,
then its replacement is upcased or capitalized.)

Ignore read-only matches if query-replace-skip-read-only is non-nil, ignore hidden matches if search-invisible is nil, and ignore more matches using isearch-filter-predicate.

If replace-lax-whitespace is non-nil, a space or spaces in the string to be replaced will match a sequence of whitespace chars defined by the regexp in search-whitespace-regexp.

If replace-char-fold is non-nil, matching uses character folding, i.e. it ignores diacritics and other differences between equivalent character strings.

Third arg DELIMITED (prefix arg if interactive), if non-nil, means replace only matches surrounded by word boundaries. A negative prefix arg means replace backward.

Operates on the region between START and END (if both are nil, from point to the end of the buffer). Interactively, if Transient Mark mode is enabled and the mark is active, operates on the contents of the region; otherwise from point to the end of the buffer's accessible portion.

Arguments BACKWARD and REGION-NONCONTIGUOUS-P are passed to perform-replace (which see).

Use M-n (next-history-element) to pull the last incremental search string to the minibuffer that reads FROM-STRING.

This function is usually the wrong thing to use in a Lisp program. What you probably want is a loop like this:
  (while (search-forward FROM-STRING nil t)
    (replace-match TO-STRING nil t))
which will run faster and will not set the mark or print anything.
(You may need a more complex loop if FROM-STRING can match the null string
and TO-STRING is also null.)

View in manual

Probably introduced at or before Emacs version 21.1.

Key Bindings

Source Code

;; Defined in /usr/src/emacs/lisp/replace.el.gz
(defun replace-string (from-string to-string &optional delimited start end backward region-noncontiguous-p)
  "Replace occurrences of FROM-STRING with TO-STRING.
Preserve case in each match if `case-replace' and `case-fold-search'
are non-nil and FROM-STRING has no uppercase letters.
\(Preserving case means that if the string matched is all caps, or capitalized,
then its replacement is upcased or capitalized.)

Ignore read-only matches if `query-replace-skip-read-only' is non-nil,
ignore hidden matches if `search-invisible' is nil, and ignore more
matches using `isearch-filter-predicate'.

If `replace-lax-whitespace' is non-nil, a space or spaces in the string
to be replaced will match a sequence of whitespace chars defined by the
regexp in `search-whitespace-regexp'.

If `replace-char-fold' is non-nil, matching uses character folding,
i.e. it ignores diacritics and other differences between equivalent
character strings.

Third arg DELIMITED (prefix arg if interactive), if non-nil, means replace
only matches surrounded by word boundaries.  A negative prefix arg means
replace backward.

Operates on the region between START and END (if both are nil, from point
to the end of the buffer).  Interactively, if Transient Mark mode is
enabled and the mark is active, operates on the contents of the region;
otherwise from point to the end of the buffer's accessible portion.

Arguments BACKWARD and REGION-NONCONTIGUOUS-P are passed
to `perform-replace' (which see).

Use \\<minibuffer-local-map>\\[next-history-element] \
to pull the last incremental search string to the minibuffer
that reads FROM-STRING.

This function is usually the wrong thing to use in a Lisp program.
What you probably want is a loop like this:
  (while (search-forward FROM-STRING nil t)
    (replace-match TO-STRING nil t))
which will run faster and will not set the mark or print anything.
\(You may need a more complex loop if FROM-STRING can match the null string
and TO-STRING is also null.)"
  (declare (interactive-only
	    "use `search-forward' and `replace-match' instead.")
	   (interactive-args
	    (start (use-region-beginning))
	    (end (use-region-end))
	    (region-noncontiguous-p (use-region-noncontiguous-p))))
  (interactive
   (let ((common
	  (query-replace-read-args
	   (concat "Replace"
		   (if current-prefix-arg
		       (if (eq current-prefix-arg '-) " backward" " word")
		     "")
		   " string"
		   (if (use-region-p) " in region" ""))
	   nil)))
     (list (nth 0 common) (nth 1 common) (nth 2 common)
	   (use-region-beginning) (use-region-end)
	   (nth 3 common)
	   (use-region-noncontiguous-p))))
  (perform-replace from-string to-string nil nil delimited nil nil start end backward region-noncontiguous-p))