Pattern Matching for Java — Semantics

Type checking

Certain pattern matches can be rejected at compile time based strictly on static checks, such as:

String s = "Hello";
if (s instanceof Integer i) { ... }

The target s is a String and the pattern Integer i only matches expressions of type Integer. Since both are final classes, we know statically that the match cannot succeed and it is rejected, just as we would reject an attempt to cast an Integer to a String.

We can define an applicability relation between a pattern and a static type, which determines if the pattern is applicable to a target of that type. (In all the rules that follow, “castable” means “cast-convertible without an unchecked warning.”)

• The ignore pattern and the var pattern are applicable to all types.

• The null constant pattern is applicable to all reference types.

• A numeric literal constant pattern for n without a type suffix is applicable to any primitive type P to which n is assignable (within the numeric range of P), and to P’s box type, and its supertypes.

• Other constant patterns of primitive type P are applicable to P and to types U which are castable to P’s box type, and its supertypes.

• Constant patterns of reference type T are applicable to types U which are castable to T.

• The type pattern P p for a primitive type P is applicable to P.

• The type pattern T t for a reference type T is applicable to types U which are castable to T.

• A deconstruction pattern D(P*) [d], is applicable to types U which are castable to D.

• A declared pattern p(P*) is applicable to types U which are castable to the target type of p. (An example of a declared pattern is Optional.of(var x), which would be declared in Optional and has a target type of Optional<T>.)

If a pattern is not applicable to the target type, a compilation error results. Generic type patterns are permitted; this is a relaxation of the current semantics of the instanceof operator, which requires that the type operand is reifiable. However, when determining applicability involves cast conversions, the pattern is not applicable if the cast conversion would be unchecked. So it is allowable to say

List<Integer> list = ...
if (list instanceof ArrayList<Integer> a) { ... }

but not

List<?> list = ...
if (list instanceof ArrayList<String> a) { ... }

as a cast conversion from List<?> to ArrayList<String> would be unchecked.

For deconstruction and declared patterns, which contain nested sub-patterns, we further required that the nested sub-patterns are applicable to the static type of the corresponding binding variables of the enclosing pattern. So if class D has a deconstructor D(String s, int y), a pattern D(P, Q) is only applicable if P is applicable to String and Q is applicable to int.

It may appear we are being unnecessarily unfriendly to numeric constant patterns here, by not being more liberal about widening and boxing conversions. However, we wish to avoid situations where an Object operand is matched against a literal constant 0; one could mistakenly expect this to match all of Integer zero, Short zero, etc. Instead, when matching against broad operand types (which are necessarily reference types), we should be explicit and either use typed constants or use destructuring patterns on the box type, such as Integer(0) or Short(0). We reserve the numeric literal patterns for matching primitives and their boxes only where there is no possible type ambiguity.

For numeric literal constants without type suffixes, when attempting to match against an operand of primitive type P or the box type for a primitive type P, then the constant is interpreted as being of type P. This means that we can speak of every constant pattern having an unambiguous type.

Matching

Some patterns are total on certain target types, which means no dynamic type test is required to determine matching. The “ignore” and “var” patterns are total on all types. A type pattern T t is total on any type U <: T. A deconstruction D(P*) is total on U if U <: T and each Pi is total on the type of the corresponding binding variable of D.

We define a matches relation between patterns and expressions as follows.

• The “ignore” and var patterns match anything, including null.

• A type pattern T t matches e if e instanceof T, and additionally matches null if the type pattern is total on the target type.

• The null constant pattern matches e if e == null.

• A primitive constant pattern c of type P matches e : P if c is equal to e, and matches e : T if e is an instance of P’s box type, and c equals unbox(e). Equality is determined by the appropriate primitive == operator, except for float and double, where equality is determined by the semantics of Float::equals and Double::equals.

• A reference constant pattern c of type T matches e if c.equals(e).

• A deconstruction pattern D(Pi...) matches e if e instanceof T, and for all i, Pi matches the i’th component extracted by D.

The only patterns that are nullable are the null constant pattern, the “ignore” and var patterns, and total type patterns. (The latter three are actually equivalent — they are all variants of “any” patterns.)

Deconstruction (and declared) patterns can contain nested sub-patterns. If a deconstructor D has a single binding variables of type T, then x matches D(P) if and only if x matches D(var alpha) and alpha matches P. In such a match, the target of D(P) is x, but the target of P is the synthetic variable alpha.

Binding variables

Some patterns define variables which will be bound to components extracted from the target if the match succeeds. These variables have types defined as follows:

• For a type pattern T t, the binding variable t has type T.

• For a deconstruction pattern D(P*) d, the binding variable d has type D.

• For a pattern var x on a target of type U, the binding variable x has type U. (Patterns in nested context get their target types from the type of the corresponding binding variable in the declaration of the enclosing pattern.)

In each of these cases, the pattern variable is initialized to the match target, after casting or converting to the target type, when a successful match is made.

Scoping and statements

We have defined which expressions produce bindings, but we have not yet tied their scopes to statements. The obvious extension of the above rules to if statements would yield:

if (x instanceof Foo f) {
    // f is in scope here
}
else {
    // if is not in scope here
}

But, what about this:

if (!(x instanceof Foo(var y, var z)))
    throw new NotFooException();
// Are y and z in scope here?

Because the body of the if always completes abruptly, it is as if the remainder of the scope was an implicit else block, and it would be desirable for y and z to be in scope (and DA) in the remainder of the scope. On the other hand, in this example:

if (!(x instanceof Foo(var y, var z)))
    System.out.println("not a Foo, saddenz");
// Are y and z in scope here?

If y and z were in scope after the if, they would definitely not be DA. And, as per the argument above about reuse, we only want bindings to be in scope where they are DA, so we can reuse the names elsewhere. We can accomplish this by incorporating additional results from the existing flow analysis into the scoping rules for pattern variables.

We define several additional predicates on statements: AA(x) is true when x always completes abruptly; NB(x) is true when x never completes abruptly because of break; MF(x) is true when x may “fall through” into the following case label. (These are already computed by existing flow analysis.) We can now add in the effects of nonlocal control flow to our scoping rules:

With these rules, we are able to get the full desired scoping with awareness of whether we throw out of if blocks, break out of while loops, or fall out of case groups.

As mentioned already, the motivation for flow-sensitive scoping is so we can reuse pattern variable names when they are not in scope:

switch (e) {
    case RedBox(int height) -> System.out.printf("Red(%d)", height);
    case BlueBox(int height) -> System.out.printf("Blue(%d)", height);
}

And we can even (if we want to) merge pattern variables in switch fallthrough:

switch (e) {
    case RedBox(int height):
        System.out.println("It's red");
        // fall through
    case Box(int height):
        System.out.println("It's a box of height: " height);
}

While these rules may look complicated at first, the rules are derived strictly from the flow analysis rules (such as DA/DU) already in the language. So the result is that a pattern variable is in scope wherever it would be DA, and not in scope wherever it would not be DA. (In informal focus-testing with experienced Java programmers, we asked “is it reasonable to be able to use variable x here” for various examples, and there were no surprises, because they were already familiar with when a variable is guaranteed to have a value, and when not.)

Shadowing

Because the scoping of pattern bindings is not exactly the same as for local variables, we must describe the interaction between pattern bindings and other kinds of variables (locals, fields.) We adopt the same rules for shadowing as we do for locals — binding variables may not shadow other binding variables or locals (or vice-versa), but they may shadow fields. The unusual shape of the scopes of binding variables may occasionally lead to scoping confusion such as the following, but it was deemed that “curing” this “problem” was probably worse than the disease.

class Swiss {
    String s;

    void cheese(Object o) {
        // pattern variable s "declared" here
        if (!(o instanceof String s)) {
            // But s not in scope here!
            // So s here would refer to the field
        }
        else {
            // And s here would refer to the pattern variable
        }
    }

Because pattern variable names are strictly local, we can always choose names that do not conflict with locals or fields in scope.

Nullity — some false starts

Our path for determining the semantics of various patterns with respect to null has been a fairly winding one. While it is impractical to rehash the entire journey, let’s look at some specific examples.

We initially liked the idea that a type pattern T t would match anything that is assignment-compatible to T, including null. But this runs into a few problems.

First, it means that refactoring between switch and instanceof is painful, because instanceof T t would not be consistent with instanceof T for any T. (Some might assume the problem here is that we’re trying to reuse instanceof, but having a matches T t that behaves similarly but subtly differently from instanceof T is no better.)

Further, having type patterns match nulls would result in surprising order dependency. If we have:

switch (box) {
    case Box(String s): ...
    case Box(Integer i): ...
    case Box(_): ...
}

and type patterns matched null, the nulls would fall into the first case. Not only is this surprising and arbitrary, but its even more surprising that if we reordered the first two cases — which surely look disjoint and therefore safely reorderable — it would subtly change the behavior of the program, because now Box(Integer) would get the nulls.

Additionally, if T t were to match nulls for arbitrary T, this would likely lead to many unexpected NPEs. For example, it would be easy to forget that one can’t safely use s in the following example:

if (x instanceof String s)
    printf("String of length %d%n", s.length());

If the type pattern String s matched null, this code would NPE in the body of the if, since we’d be dereferencing a null String reference. This would be a sharp edge that cuts over and over, because the intent of the code above is to perform a dynamic type test.

At this point, readers should ask: why would it be different for total patterns? And the reason is: we don’t use total patterns in instanceof at all (so it doesn’t matter there), and when we use them in switch, we are not using them as dynamic type tests — we are using them as catch-alls.

Another idea that didn’t work out is to say var x is nullable but Object x never is. This is doable, but it has a big cost — it violates the sensible intuition that var is “just” type inference, not a semantically different thing. We want the rules for nullity to be robust to a variety of refactorings that seem like they should be the same thing — so we want them to be the same thing:

• That var x is just type inference for some type pattern T t;

• A chain of if (x instanceof P) … else if (x instanceof Q) can be refactored to or from a switch with cases P and Q;

• A sequence of switch cases P(Q), P(R) can be refactored to a single case P p with a nested switch on p with cases Q and R.

Each of the ideas discussed and rejected in this section would have fallen afoul of one of these goals.