java.util.regex.Matcher defines followings methods for replacing matched substrings with new strings.
Append and Replace Operation
This is a multi-steps operation. It basically appends the unmatched parts of the input string to a provided StringBuffer instance and at the same time replaces the matched parts with the provided replacement string and then appends to the same StringBuffer object. Here are two methods we have to be familiar with.
StringBuffer appendReplacement(StringBuffer sb, String replacement): This method first appends the input string to the provided StringBuffer starting from end index position of the last match (if there's no last match then starts from 0 index) to the current match position, given by matcher#start(). Second thing this method does is to append the replacement string instead of the current match.
StringBuffer appendTail(StringBuffer sb): This is the very last method to be called during 'append-and-replace' operation. It is called only once. It appends the remaining unmatched part of the input string to the provided StringBuffer.
Example:
Pattern p = Pattern.compile("\\b\\d+\\b");
Matcher m = p.matcher("There are 200 items in 500 boxes.");
StringBuffer sb = new StringBuffer();
while (m.find()) {
m.appendReplacement(sb, "multiple");
}
m.appendTail(sb);
System.out.println(sb.toString()); /*Regex breakdown: \\b\\d+\\b
\\b
The word boundary.
\\d+
One or more digits.
\\b
The word boundary.
*/
Output
There are multiple items in multiple boxes.
Other Methods
Matcher#replaceAll(String replacement): Replaces every match (given by matcher#group() or matcher#group(0)) of the input string with the provided replacement string:
Example:
Pattern p = Pattern.compile("\\b\\d+\\b");
Matcher m = p.matcher("There are 200 items in 500 boxes.");
String s = m.replaceAll("multiple");
System.out.println(s); /*Regex breakdown: \\b\\d+\\b
\\b
The word boundary.
\\d+
One or more digits.
\\b
The word boundary.
*/
Output
There are multiple items in multiple boxes.
Looking at the source code, the method replaceAll does the same thing as the two methods appendReplacement and appendTail do together as we saw in our second last example. So it's actually a wrapper method.
Matcher#replaceFirst(String replacement): Replaces the first matched substring of the input string with the provided replacement string. It's same as using appendReplacement and appendTail except that the replacement is done only first time. The other times the original match is appended as it is.
Example
Pattern p = Pattern.compile("\\b\\d+\\b");
Matcher m = p.matcher("There are 200 items in 500 boxes.");
String s = m.replaceFirst("multiple");
System.out.println(s); /*Regex breakdown: \\b\\d+\\b
\\b
The word boundary.
\\d+
One or more digits.
\\b
The word boundary.
*/
Output
There are multiple items in 500 boxes.
java.lang.String Equivalents
String#replaceAll is equivalent to matcher#replaceAll. That is String's replaceAll creates a Matcher instance in the background
String#replaceFirst is equivalent to matcher#replaceFirst.
