Java String.replaceFirst Method
Last modified: April 20, 2025
The String.replaceFirst method replaces the first substring of a
string that matches the given regular expression with the specified replacement.
It is part of Java's String class and provides regex-based string manipulation.
This method is useful when you need to modify only the first occurrence of a pattern in a string. It returns a new string with the replacement applied. The original string remains unchanged as strings are immutable in Java.
Method Signature
The method has two variants. The basic version takes a regex pattern and replacement string. The second version accepts regex flags for case-insensitive matching and other options.
public String replaceFirst(String regex, String replacement)
public String replaceFirst(String regex, String replacement, int flags)
Basic replaceFirst Example
This example demonstrates the simplest usage of replaceFirst. We
replace the first occurrence of a word in a sentence. The method returns a new
string with the replacement applied.
package com.zetcode;
public class ReplaceFirstBasic {
public static void main(String[] args) {
String text = "The quick brown fox jumps over the lazy dog";
String result = text.replaceFirst("the", "a");
System.out.println("Original: " + text);
System.out.println("Modified: " + result);
}
}
In this example, we replace the first occurrence of "the" with "a". Note that the replacement is case-sensitive. The original string remains unchanged while a new modified string is returned.
Case-Insensitive Replacement
This example shows how to perform case-insensitive replacement using regex
flags. We use Pattern.CASE_INSENSITIVE to match regardless of case.
package com.zetcode;
import java.util.regex.Pattern;
public class ReplaceFirstCaseInsensitive {
public static void main(String[] args) {
String text = "The quick brown fox jumps over the lazy dog";
String result = text.replaceFirst("(?i)the", "a");
System.out.println("Original: " + text);
System.out.println("Modified: " + result);
}
}
We use the (?i) regex flag to enable case-insensitive matching. This
makes the pattern match "The" at the start of the string. Without this flag, it
would only match lowercase "the".
Replacing Digits
This example demonstrates replacing the first sequence of digits in a string.
We use the \d+ regex pattern to match one or more digits.
package com.zetcode;
public class ReplaceFirstDigits {
public static void main(String[] args) {
String text = "Order 12345 with price 67.89 USD";
String result = text.replaceFirst("\\d+", "XXXXX");
System.out.println("Original: " + text);
System.out.println("Modified: " + result);
}
}
The pattern \\d+ matches the first sequence of digits (12345) and
replaces it with "XXXXX". Note that we need to escape the backslash in Java
strings, so \d becomes \\d.
Using Capturing Groups
This example shows how to use capturing groups in the replacement string. We can
reference matched groups using $n notation in the replacement.
package com.zetcode;
public class ReplaceFirstGroups {
public static void main(String[] args) {
String text = "John Doe, age 30";
String result = text.replaceFirst("(\\w+) (\\w+), age (\\d+)",
"Last: $2, First: $1, Years: $3");
System.out.println("Original: " + text);
System.out.println("Modified: " + result);
}
}
The pattern captures three groups: first name, last name, and age. In the
replacement string, we rearrange these groups with descriptive labels. $1
refers to the first group, $2 to the second, and so on.
Replacing Special Characters
This example demonstrates replacing special regex characters. We need to escape
them properly or use Pattern.quote for literal matching.
package com.zetcode;
import java.util.regex.Pattern;
public class ReplaceFirstSpecialChars {
public static void main(String[] args) {
String text = "Calculate 3 + 5 * 2";
// Using escaped characters
String result1 = text.replaceFirst("\\+", "plus");
System.out.println("Escaped: " + result1);
// Using Pattern.quote
String result2 = text.replaceFirst(Pattern.quote("*"), "times");
System.out.println("Quoted: " + result2);
}
}
The plus sign and asterisk are regex metacharacters. We either escape them with
backslashes or use Pattern.quote to treat them as literals. Both
methods safely replace the first occurrence of these special characters.
Replacing with Function
Java 9+ allows using a function to determine the replacement. This provides dynamic replacement based on the matched content.
package com.zetcode;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
public class ReplaceFirstFunction {
public static void main(String[] args) {
String text = "Prices: $10, $20, $30";
Pattern pattern = Pattern.compile("\\$\\d+");
String result = pattern.matcher(text)
.replaceFirst(m -> "USD " + m.group().substring(1));
System.out.println("Original: " + text);
System.out.println("Modified: " + result);
}
}
We use a lambda function that receives the match and returns the replacement string. In this case, we transform "$10" into "USD 10". This approach provides flexible replacement logic based on the matched content.
Replacing in Multiline Text
This example shows how to replace the first match in multiline text. We use the
Pattern.MULTILINE flag to make ^ and $
match line boundaries.
package com.zetcode;
import java.util.regex.Pattern;
public class ReplaceFirstMultiline {
public static void main(String[] args) {
String text = "First line\nSecond line\nThird line";
String result = text.replaceFirst("(?m)^.*$", "---");
System.out.println("Original:\n" + text);
System.out.println("Modified:\n" + result);
}
}
The (?m) flag enables multiline mode. The pattern ^.*$
matches entire lines. The replacement replaces only the first line with "---".
Without the flag, the pattern would match the entire string.
Source
Java String.replaceFirst Documentation
In this article, we've explored various uses of the String.replaceFirst
method. From basic replacements to advanced regex features, this method provides
powerful string manipulation capabilities.
Author
List all Java tutorials.