Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / Java

String.matches: match an entire string against a regex

Test whether an entire string matches a regular expression. Learn how `(?s)` changes the dot, which character classes default to ASCII, and how to write regex backslashes in Java string literals.

Version: Java SE 21

Syntax

public boolean matches(String regex)

String.matches is an instance method on java.lang.String. The call text.matches(regex) treats its argument as a regular expression and returns true only if the whole text matches, not just a substring. You do not need ^ and $ anchors. To search for a matching substring, use Pattern.compile(regex).matcher(text).find().

Put (?s) at the start of the pattern to enable DOTALL: . then matches line terminators too. By default, the dot does not match them. Do not confuse (?s) with (?m): MULTILINE changes how the ^ and $ anchors work, not how the dot works.

In a regex, [A-Z] is the range of uppercase ASCII letters from A through Z. By default, \d means [0-9] and \w means [a-zA-Z_0-9]. The (?U) flag (UNICODE_CHARACTER_CLASS) enables Unicode versions of these predefined classes, but it does not widen the explicit range [A-Z].

Java string literals and regular expressions are parsed separately. Write "\\d" to pass \d to the regex engine and "\\." to pass \. and match a literal dot. An invalid pattern throws PatternSyntaxException, and a null argument throws NullPointerException; neither case returns false. If you use the same regex repeatedly, compile it once with Pattern.compile(regex) and call pattern.matcher(text).matches() for each string.

Examples

import java.util.regex.Pattern;

public class Main {
    public static void main(String[] args) {
        String code = "[A-Z]{2}\\.\\d{2}";
        String withPrefix = "XAB.42";
        String nonAsciiDigits = "AB.\u0664\u0662";
        String twoLines = "start\nend";

        System.out.println("whole: " + "AB.42".matches(code));
        System.out.println("prefixed whole: " + withPrefix.matches(code));
        System.out.println("prefixed find: " + Pattern.compile(code).matcher(withPrefix).find());
        System.out.println("wrong separator: " + "AB-42".matches(code));
        System.out.println("default digits: " + nonAsciiDigits.matches(code));
        System.out.println("Unicode digits: " + nonAsciiDigits.matches("(?U)" + code));
        System.out.println("default dot: " + twoLines.matches("start.*end"));
        System.out.println("DOTALL dot: " + twoLines.matches("(?s)start.*end"));
    }
}

Result

whole: true
prefixed whole: false
prefixed find: true
wrong separator: false
default digits: false
Unicode digits: true
default dot: false
DOTALL dot: true

`AB.42` matches in full, while `find()` locates a matching substring in `XAB.42`. The hyphen cannot replace the literal dot. The Arabic-Indic digits match only with `(?U)`, and the dot matches the line break only with `(?s)`.

Related lessons

  • Java · Lesson 1 · Intermediate · Version: 2

Sources