Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8185499

Clarify that Pattern.matches() tries to match the WHOLE string

XMLWordPrintable

      A DESCRIPTION OF THE PROBLEM :
      The documentation of the String.matches() and Pattern.matches() method, respectively, should be clarified by stating the exact behavior of those methods. In fact, it should be mentioned that a given regular expression must match the WHOLE string in order to evaluate to true.

      One could argue that this behavior is already stated in the documentation which indeed is true (cf. Matcher.matches()) but not obvious when starting at the String.matches() method's JavaDoc. In that case one have to follow several links in the JavaDocs in order to understand the exact behavior: String.matches → Pattern.matches → Pattern.matcher → Matcher.matches.

      PS: Although specified I think this proposal affects all (future) releases on any platform.

      EXPECTED VERSUS ACTUAL BEHAVIOR :
      EXPECTED -
      A matches method is defined by this class as a convenience for when a regular expression is used just once. This method compiles an expression and matches an input sequence against it in a single invocation. The statement

           boolean b = Pattern.matches("a*b", "aaaaab");

      is equivalent to the three statements above, though for repeated matches it is less efficient since it does not allow the compiled pattern to be reused. Note, that the whole string must match to evaluate to true.
      ACTUAL -
      A matches method is defined by this class as a convenience for when a regular expression is used just once. This method compiles an expression and matches an input sequence against it in a single invocation. The statement

           boolean b = Pattern.matches("a*b", "aaaaab");

      is equivalent to the three statements above, though for repeated matches it is less efficient since it does not allow the compiled pattern to be reused.

      URL OF FAULTY DOCUMENTATION :
      https://docs.oracle.com/javase/8/docs/api/index.html?java/util/regex/Pattern.html

            Unassigned Unassigned
            webbuggrp Webbug Group
            Votes:
            0 Vote for this issue
            Watchers:
            3 Start watching this issue

              Created:
              Updated: