Java Reference ยท Text, Formatting and Regex
replaceAll() and appendReplacement()
Reference for regex replacement in Java: String.replaceAll, Matcher.replaceAll with a function, appendReplacement, group references, quoteReplacement and dollar-sign pitfalls.
Java offers several ways to replace regex matches. String.replaceAll(regex, replacement) and replaceFirst are the shortcuts. Matcher.replaceAll and replaceFirst do the same with a compiled pattern, and since Java 9 they also accept a Function<MatchResult,String>, which computes each replacement from the match. For full control there is the loop-based pair appendReplacement and appendTail.
The replacement string is not plain text: a $ introduces a group reference ($1, ${name}) and a backslash escapes the next character. This is the number one source of bugs and of IllegalArgumentException and IndexOutOfBoundsException when the replacement comes from user input.
"2026-03-14".replaceAll("(\\d+)-(\\d+)-(\\d+)", "$3/$2/$1"); // 14/03/2026
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.
Syntax
String.replaceAll(String regex, String replacement) String.replaceFirst(String regex, String replacement) Matcher.replaceAll(String replacement) Matcher.replaceAll(Function<MatchResult, String> replacer) // Java 9 Matcher.replaceFirst(String replacement) Matcher.replaceFirst(Function<MatchResult, String> replacer) // Java 9 Matcher.appendReplacement(StringBuilder sb, String replacement) // Java 9 (also StringBuffer) Matcher.appendTail(StringBuilder sb) static Matcher.quoteReplacement(String s)
| Replacement syntax | Meaning |
|---|---|
$1 ... $9 |
Text of that capturing group. More digits are read while the group number stays valid. |
${name} |
Text of a named group. |
$0 |
The entire match. |
\$, \\ |
A literal dollar sign or backslash. |
Returns: the new string. appendReplacement returns the matcher so calls can chain.
Throws: IllegalArgumentException for a stray $ or a malformed group reference; IndexOutOfBoundsException when the group number does not exist; IllegalStateException if appendReplacement is called without a current match.
Usage notes
replacevsreplaceAll.String.replace(CharSequence, CharSequence)is literal;replaceAlltreats both arguments as regex syntax. Usereplacewhen no pattern is needed.- Quote untrusted text. Wrap user-supplied replacement strings with
Matcher.quoteReplacement(and patterns withPattern.quote). - The function form receives a
MatchResult; its return value is used literally, with no$processing, which avoids the escaping problem. - Strings are immutable; all variants return a new string and leave the input unchanged. If nothing matches you get an equal string back.
- Compile once for repeated replacements:
String.replaceAllrecompiles the pattern each call. appendReplacementneeds both parts: forgettingappendTaildrops the text after the last match. TheStringBuilderoverloads arrived in Java 9; older code usesStringBuffer.- Empty matches such as
x*also produce replacements between characters:"ab".replaceAll("x*", "-")is-a-b-.