Java String API matches​() Method Example

1. Java String API matches​(String regex) Overview

In this tutorial, We'll learn about Java String API matches​() Method with Example programs. And also will explain how this method works internally.

matches() method tells whether or not this string matches the given regular expression.

In simple words, First regular expression is a pattern which tells string should have only alphabetic's or numbers. This pattern can be anything or specified character set.

If the string fits into the specified regular expression pattern then matches() method returns true. Otherwise returns false.

1.1 Syntax

public boolean matches​(String regex)

This is a public method and can be invoked directly on instance.

1.2 Parameters

This takes only one parameter and it is String regex.

This should be a valid regex parameter.

1.3 Returns

boolean. true or false.

1.4 Since

Java 1.4

1.5 Throws Exception

This method throws PatternSyntaxException if the regular expression provided is invalid.

Read article on Java 12 String new Additions.

2. String matches​() Method Example

We will write example programs on matches method.

2.1 Check String has "java" word using matches()

Below java program to check the string has "java" word in it using matches() method. We should pass a valid regex pattern to this method.

// Example 1 to check word 'java'
String str1 = "Welcome to java-w3schools";
boolean isMatch = str1.matches("(.*)java(.*)");
System.out.println(" Does input str1 has 'java' word : "+isMatch);

Here, Passed regex checks for 'java' word.
       
Output:

Does input str1 has 'java' word : true

Now, will change the pattern to find word 'world'. But, input is not having word 'world'.

isMatch = str1.matches("(.*)world(.*)");
System.out.println("Does input str1 has 'world' word : "+isMatch);

Output:

Does input str1 has 'world' word : false

This program returned false because input did not have word 'world'

2.2 Example to Check if a string contains only alphabets

Now, We will write a program to check if string is having only alphabetic's or not.

For this we should pass a regex which covers a to z and A to Z as well one blank space ' '. Because string may have multiple words,

// Example 2: Checking only alphabets -
String str2 = "Google is very popular search engine";
isMatch = str2.matches("[a-zA-Z ]+");
System.out.println("Does input str2 has only alphabetics: "+isMatch);

Output:

Does input str2 has only alphabetics: true

If input has numeric like below along with alphabetic's.

String str3 = "Google is very popular search engine and it is No 1";
isMatch = str3.matches("[a-zA-Z ]+");

Output:

Does input str3 has only alphabetics: false

It returned false because input str3 has digit '1'.

 2.3 Example program to check if String contains only numbers

The below program checks for only digits from 0 to 9. If it finds any character other than that will return false.

// Example 3: Checking only numerics
String str4 = "16784311299";
isMatch = str4.matches("[0-9]+");
System.out.println("Does input str4 has only numerics: "+isMatch);

Output:

Does input str4 has only numerics: true

2.4 Example to throw PatternSyntaxException

Just need to pass the invalid regex. This should be good to see the exception.

isMatch = str4.matches("[0-**9]+($$");

Full Exception Stack:

Exception in thread "main" java.util.regex.PatternSyntaxException: Illegal character range near index 3
[0-**9]+($$
   ^
 at java.base/java.util.regex.Pattern.error(Pattern.java:2015)
 at java.base/java.util.regex.Pattern.range(Pattern.java:2813)
 at java.base/java.util.regex.Pattern.clazz(Pattern.java:2701)
 at java.base/java.util.regex.Pattern.sequence(Pattern.java:2126)
 at java.base/java.util.regex.Pattern.expr(Pattern.java:2056)
 at java.base/java.util.regex.Pattern.compile(Pattern.java:1778)
 at java.base/java.util.regex.Pattern.(Pattern.java:1427)
 at java.base/java.util.regex.Pattern.compile(Pattern.java:1068)
 at java.base/java.util.regex.Pattern.matches(Pattern.java:1173)
 at java.base/java.lang.String.matches(String.java:2033)
 at com.java.w3schools.blog.string.StringMatchesExample.main(StringMatchesExample.java:36)

3. matches() Internal Code

matches() method internal code is below.

public boolean matches(String regex) {
    return Pattern.matches(regex, this);
}

Step 1: It calls simply Pattern.matches() method. It will pass regex and input string.

Step 2: It invokes Pattern.compile(regex) method to check the given regex is valid or not. If it is not valid then will throw PatternSyntaxException exception. If valid then it creates Pattern object.
Step 3: Next, Creates Matcher object by calling p.matcher(input).
Step 4: At last, invokes matches() on Matcher object which created in above step. matches() method returns true if ok. Otherwise, it returns false.

Note: An invocation of this method of the form str.matches(regex) yields exactly the same result as the expression

Pattern.matches(regex, str) 

4. Conclusion

In this article, We've learn about Java String API matches() method. How to validate a string against a valid regular expression.

Written example programs to check string has only alphabetics or numerics.

Discussed detailed on how matches() method works internally and how it is implemented.

Example code snippets shown in this article is available on GitHub.