Matcher appendReplacement(StringBuffer, String) method in Java with Examples

The appendReplacement(StringBuffer, String) method of the Matcher class is used to replace each matched substring while constructing a new result string. It appends the text before the current match to a StringBuffer, replaces the matched text with the specified replacement string, and continues processing the remaining input.

• Processes one match at a time, giving fine-grained control over replacements.
• Requires the find() method to locate matches before performing replacement.
• Does not modify the original input string; instead, it builds a new result in a StringBuffer.

import java.util.regex.*;

public class Geeks {

    public static void main(String[] args) {

        String input = "Java is powerful. Java is popular.";

        Pattern pattern = Pattern.compile("Java");
        Matcher matcher = pattern.matcher(input);

        StringBuffer result = new StringBuffer();

        while (matcher.find()) {

            // Replace each occurrence
            matcher.appendReplacement(result, "Spring");
        }

        // Append remaining text
        matcher.appendTail(result);

        System.out.println(result);
    }
}

Spring is powerful. Spring is popular.

Explanation: The find() method locates each occurrence of "Java". The appendReplacement() method appends the text before each match and replaces the matched word with "Spring". Finally, appendTail() appends the remaining part of the input string.

Syntax

public Matcher appendReplacement(
StringBuffer sb, String replacement)

Parameters

• sb: The StringBuffer used to build the resulting string.
• replacement: The string that replaces the current matched substring.

Return Value: Returns the same Matcher object.

Exception

• IllegalStateException: If no successful match exists before calling the method.
• IllegalArgumentException: If the replacement string refers to an invalid named capturing group.
• IndexOutOfBoundsException: If the replacement string refers to an invalid numbered capturing group.

Example 1: Replace Every Occurrence

import java.util.regex.*;

public class Geeks {

    public static void main(String[] args) {

        String input = "Java Java Python Java";

        Pattern pattern = Pattern.compile("Java");
        Matcher matcher = pattern.matcher(input);

        StringBuffer result = new StringBuffer();

        while (matcher.find()) {

            // Replace each matched word
            matcher.appendReplacement(result, "Spring");
        }

        // Append remaining characters
        matcher.appendTail(result);

        System.out.println("Original: " + input);
        System.out.println("Modified: " + result);
    }
}

Original: Java Java Python Java
Modified: Spring Spring Python Spring

Explanation: Each occurrence of "Java" is replaced with "Spring" while preserving the remaining text.

Example: Replace Numbers with '#'

import java.util.regex.*;

public class Geeks {

    public static void main(String[] args) {

        String input = "Order123 Price500 Qty20";

        Pattern pattern = Pattern.compile("\\d+");
        Matcher matcher = pattern.matcher(input);

        StringBuffer result = new StringBuffer();

        while (matcher.find()) {

            // Replace every number
            matcher.appendReplacement(result, "#");
        }

        matcher.appendTail(result);

        System.out.println(result);
    }
}

Order# Price# Qty#

Explanation: The regular expression \\d+ matches every sequence of digits. Each numeric value is replaced with # using appendReplacement()

Difference Between appendReplacement() and replaceAll()

Advantages of appendReplacement() Method

• Replaces matches one at a time instead of all at once.
• Supports dynamic and customized replacement logic.
• Preserves unmatched portions of the input automatically.
• Works seamlessly with capturing groups.
• Useful for advanced text processing and data transformation.
• Used together with appendTail() to construct the complete output string.