Skip to content
Tutorials Center
My learning

Topics

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.

Java
"2026-03-14".replaceAll("(\\d+)-(\\d+)-(\\d+)", "$3/$2/$1");   // 14/03/2026

Try it

Java Group references and functions

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.

Java appendReplacement, quoteReplacement and errors

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

Java
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

  • replace vs replaceAll. String.replace(CharSequence, CharSequence) is literal; replaceAll treats both arguments as regex syntax. Use replace when no pattern is needed.
  • Quote untrusted text. Wrap user-supplied replacement strings with Matcher.quoteReplacement (and patterns with Pattern.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.replaceAll recompiles the pattern each call.
  • appendReplacement needs both parts: forgetting appendTail drops the text after the last match. The StringBuilder overloads arrived in Java 9; older code uses StringBuffer.
  • Empty matches such as x* also produce replacements between characters: "ab".replaceAll("x*", "-") is -a-b-.