308

I am trying to understand the difference between matches() and find().

According to the Javadoc, (from what I understand), matches() will search the entire string even if it finds what it is looking for, and find() will stop when it finds what it is looking for.

If that assumption is correct, I cannot see whenever you would want to use matches() instead of find(), unless you want to count the number of matches it finds.

In my opinion the String class should then have find() instead of matches() as an inbuilt method.

So to summarize:

  1. Is my assumption correct?
  2. When is it useful to use matches() instead of find()?
evandrix
  • 6,041
  • 4
  • 27
  • 38
Shervin Asgari
  • 23,901
  • 30
  • 103
  • 143
  • 7
    Be aware that calling `find()` multiple times may return different results for the same `Matcher`. See my answer below. – L. Holanda Aug 23 '13 at 18:02
  • This question is about `java.util.regex.Pattern.compile(regex).matcher(input).matches()` and `java.util.regex.Pattern.compile(regex).matcher(input).find()`. – Jens Piegsa Oct 22 '21 at 11:48

5 Answers5

359

matches tries to match the expression against the entire string and implicitly add a ^ at the start and $ at the end of your pattern, meaning it will not look for a substring. Hence the output of this code:

public static void main(String[] args) throws ParseException {
    Pattern p = Pattern.compile("\\d\\d\\d");
    Matcher m = p.matcher("a123b");
    System.out.println(m.find());
    System.out.println(m.matches());

    p = Pattern.compile("^\\d\\d\\d$");
    m = p.matcher("123");
    System.out.println(m.find());
    System.out.println(m.matches());
}

/* output:
true
false
true
true
*/

123 is a substring of a123b so the find() method outputs true. matches() only 'sees' a123b which is not the same as 123 and thus outputs false.

Jon Lawton
  • 890
  • 3
  • 14
  • 33
Sanjay T. Sharma
  • 22,857
  • 4
  • 59
  • 71
  • 34
    This answer is misleading. `matchers()` is not simply a `find()` with implied surrounding ^ and $. Be aware that calling `.find()` more than once may have different results if not preceeded by `reset()`, while `matches()` will always return same result. See my answer below. – L. Holanda Nov 20 '15 at 22:35
104

matches returns true if the whole string matches the given pattern. find tries to find a substring that matches the pattern.

khachik
  • 28,112
  • 9
  • 59
  • 94
  • 57
    You could say that `matches(p)` is the same as `find("^" + p + "$")` if that's any clearer. – jensgram Dec 15 '10 at 12:56
  • 7
    Just an example to clarify the answer: "[a-z]+" with string "123abc123" will fail using matches() but will succeed using find(). – bezmax Dec 15 '10 at 12:57
  • 4
    @Max Exactly, `"123abc123".matches("[a-z]+")` will fail just as `"123abc123".find("^[a-z]+$")` would. My point was, that `matches()` goes for a complete match, just as `find()` with both start and end anchors. – jensgram Dec 15 '10 at 12:59
  • 5
    `Pattern.compile("some pattern").matcher(str).matches()` is equal to `Pattern.compile("^some pattern$").matcher(str).find()` – AlexR Dec 15 '10 at 13:09
  • @AlexR What I was trying to say (using a highly abbreviated syntax) :) – jensgram Dec 15 '10 at 13:14
  • @jensgram, @AlexR: almost, but not exactly: `^` and `$` can be used to refer to the start and end of a line instead of the start and line of the complete input (in case of multi-line) input when [multiline mode](http://download.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html#MULTILINE) is activated. – Joachim Sauer Dec 15 '10 at 13:29
  • 3
    @AlexR / @jensgram: `...("some pattern").matcher(str).matches()` is *not* exactly equal to `...("^some pattern$").matcher(str).find()` that's only true in the first call. See my answer below. – L. Holanda Aug 11 '16 at 17:55
84
  • matches() - will only return true if the full string is matched
  • find() - will try to find the next occurrence within the substring that matches the regex.

Note the emphasis on "the next" in case of find(). That means, the result of calling find() multiple times might not be the same. In addition, by using find() you can call start() to return the position the substring was matched.

Example

final Matcher subMatcher = Pattern.compile("\\d+").matcher("skrf35kesruytfkwu4ty7sdfs");
System.out.println("Found: " + subMatcher.matches());
System.out.println("Found: " + subMatcher.find() + " - position " + subMatcher.start());
System.out.println("Found: " + subMatcher.find() + " - position " + subMatcher.start());
System.out.println("Found: " + subMatcher.find() + " - position " + subMatcher.start());
System.out.println("Found: " + subMatcher.find());
System.out.println("Found: " + subMatcher.find());
System.out.println("Matched: " + subMatcher.matches());

System.out.println("-----------");
final Matcher fullMatcher = Pattern.compile("^\\w+$").matcher("skrf35kesruytfkwu4ty7sdfs");
System.out.println("Found: " + fullMatcher.find() + " - position " + fullMatcher.start());
System.out.println("Found: " + fullMatcher.find());
System.out.println("Found: " + fullMatcher.find());
System.out.println("Matched: " + fullMatcher.matches());
System.out.println("Matched: " + fullMatcher.matches());
System.out.println("Matched: " + fullMatcher.matches());
System.out.println("Matched: " + fullMatcher.matches());

Output

Found: false
Found: true - position 4
Found: true - position 17
Found: true - position 20
Found: false
Found: false
Matched: false
-----------
Found: true - position 0
Found: false
Found: false
Matched: true
Matched: true
Matched: true
Matched: true

So, be careful when calling find() multiple times if the Matcher object was not reset, even when the regex is surrounded with ^ and $ to match the full string.

informatik01
  • 16,038
  • 10
  • 74
  • 104
L. Holanda
  • 4,432
  • 1
  • 36
  • 44
7

find() will consider the sub-string against the regular expression where as matches() will consider complete expression.

find() will returns true only if the sub-string of the expression matches the pattern.

public static void main(String[] args) {
        Pattern p = Pattern.compile("\\d");
        String candidate = "Java123";
        Matcher m = p.matcher(candidate);

        if (m != null){
            System.out.println(m.find());//true
            System.out.println(m.matches());//false
        }
    }
Jaap
  • 81,064
  • 34
  • 182
  • 193
Sumanth Varada
  • 1,122
  • 1
  • 16
  • 17
3

matches(); does not buffer, but find() buffers. find() searches to the end of the string first, indexes the result, and return the boolean value and corresponding index.

That is why when you have a code like 

1:Pattern.compile("[a-z]");

2:Pattern.matcher("0a1b1c3d4");

3:int count = 0;

4:while(matcher.find()){

5:count++: }

At 4: The regex engine using the pattern structure will read through the whole of your code (index to index as specified by the regex[single character] to find at least one match. If such match is found, it will be indexed then the loop will execute based on the indexed result else if it didn't do ahead calculation like which matches(); does not. The while statement would never execute since the first character of the matched string is not an alphabet.