replace

added
1.2

ns
clojure.string

type
function

(replace s match replacement)

Replaces all instance of match with replacement in s.

match/replacement can be:

string / string
char / char
pattern / (string or function of match).

See also replace-first.

The replacement is literal (i.e. none of its characters are treated
specially) for all cases above except pattern / string.

For pattern / string, $1, $2, etc. in the replacement string are
substituted with the string that matched the corresponding
parenthesized group in the pattern.  If you wish your replacement
string r to be used literally, use (re-quote-replacement r) as the
replacement argument.  See also documentation for
java.util.regex.Matcher's appendReplacement method.

Example:
(clojure.string/replace "Almost Pig Latin" #"\\b(\\w)(\\w+)\\b" "$2$1ay")
-> "lmostAay igPay atinLay"

                (clojure.string/replace "The color is red" #"red" "blue")
;=> "The color is blue"
            
                clojure.string/replace "The color is red." #"[aeiou]"  #(str %1 %1))
;=> "Thee cooloor iis reed."

            
                ;; Note: When replace-first or replace have a regex pattern as their
;; match argument, dollar sign ($) and backslash (\\) characters in
;; the replacement string are treated specially.

;; Example: first substring that the pattern matches is "fodder", with
;; (o+) matching "o" and (\\S+) matching "dder".  Replacement string
;; says to replace the entire match "fodder" with $2, the string
;; matched by the second parenthesized group, "dder", followed by $1,
;; "o".
(str/replace "fabulous fodder foo food" #"f(o+)(\\S+)" "$2$1")
;=> "fabulous ddero oo doo"

;; To avoid this special treatment of $ and \\, you must escape them with
;; \\.  Because it is in a Clojure string, to get one \\ we must escape
;; *that* with its own \\.
(str/replace "fabulous fodder foo food" #"f(o+)(\\S+)" "\\\\$2\\\\$1")
;=> "fabulous $2$1 $2$1 $2$1"

;; To ensure the replacement is treated literally, call
;; java.util.regex.Matcher/quoteReplacement on it.  A shorter name
;; like re-qr can be handy.
(import '(java.util.regex Matcher))
;=> java.util.regex.Matcher

(defn re-qr [replacement]
    (Matcher/quoteReplacement replacement))
;=> #'user/re-qr

(str/replace "fabulous fodder foo food" #"f(o+)(\\S+)" (re-qr "$2$1"))
;=> "fabulous $2$1 $2$1 $2$1"

            
                ;; replaces all a's with 1 and all b's with 2
(clojure.string/replace "a b a" #"a|b" {"a" "1" "b" "2"})
;=> "1 2 1"
            
                ;; Note: See clojure.core/subs for discussion of behavior of substrings
;; holding onto references of the original strings, which can
;; significantly affect your memory usage in some cases.
            
                ;; To title case
(clojure.string/replace "hello world" #"\\b." #(.toUpperCase %1))
"Hello World"

;; Note that a vector is passed to your replacement function
;; when pattern contains capturing groups (see re-groups)
(clojure.string/replace "hello world" #"\\b(.)" #(.toUpperCase (%1 1)))
"Hello World"

            
                ;; Note that the s "Vegeta" is returned as is, because there is no matching.
(clojure.string/replace "Vegeta" #"Goku" "Gohan")
"Vegeta"