Pattern Matching for switch (Third Preview) and Record Patterns (Preview)

This document describes changes to the Java Language Specification to support Pattern Matching for switch, and Record Patterns, which are both preview features of Java SE 19. See JEP 427 and JEP 405 respectively for overviews of the features.

Changes are described with respect to existing sections of the JLS. New text is indicated like this and deleted text is indicated like this. Explanation and discussion, as needed, is set aside in grey boxes.

Chapter 3: Lexical Structure

3.9 Keywords

51 character sequences, formed from ASCII characters, are reserved for use as keywords and cannot be used as identifiers (3.8). Another 16 character sequences, also formed from ASCII characters, may be interpreted as keywords or as other tokens, depending on the context in which they appear.

Keyword:

ReservedKeyword

ContextualKeyword

ReservedKeyword:

(one of)

abstract continue for new switch
assert default if package synchronized
boolean do goto private this
break double implements protected throw
byte else import public throws
case enum instanceof return transient
catch extends int short try
char final interface static void
class finally long strictfp volatile
const float native super while
_ (underscore)

ContextualKeyword:

(one of)

exports permits to with
module provides transitive yield
non-sealed record uses
open requires var
opens sealed when

The keywords const and goto are reserved, even though they are not currently used. This may allow a Java compiler to produce better error messages if these C++ keywords incorrectly appear in programs.

The keyword strictfp is obsolete and should not be used in new code.

The keyword _ (underscore) is reserved for possible future use in parameter declarations.

true and false are not keywords, but rather boolean literals (3.10.3).

null is not a keyword, but rather the null literal (3.10.8).

During the reduction of input characters to input elements (3.5), a sequence of input characters that notionally matches a contextual keyword is reduced to a contextual keyword if and only if both of the following conditions hold:

1. The sequence is recognized as a terminal specified in a suitable context of the syntactic grammar (2.3), as follows:

   • For module and open, when recognized as a terminal in a ModuleDeclaration (7.7).

   • For exports, opens, provides, requires, to, uses, and with, when recognized as a terminal in a ModuleDirective.

   • For transitive, when recognized as a terminal in a RequiresModifier.

     For example, recognizing the sequence requires transitive ; does not make use of RequiresModifier, so the term transitive is reduced here to an identifier and not a contextual keyword.

   • For var, when recognized as a terminal in a LocalVariableType (14.4) or a LambdaParameterType (15.27.1).

     In other contexts, attempting to use var as an identifier will cause an error, because var is not a TypeIdentifier (3.8).

   • For yield, when recognized as a terminal in a YieldStatement (14.21).

     In other contexts, attempting to use the yield as an identifier will cause an error, because yield is neither a TypeIdentifier nor a UnqualifiedMethodIdentifier.

   • For record, when recognized as a terminal in a RecordDeclaration (8.10).

   • For non-sealed, permits, and sealed, when recognized as a terminal in a NormalClassDeclaration (8.1) or a NormalInterfaceDeclaration (9.1).

   • For when, when recognized as a terminal in a SwitchBlock (14.11.1).

2. The sequence is not immediately preceded or immediately followed by an input character that matches JavaLetterOrDigit.

In general, accidentally omitting white space in source code will cause a sequence of input characters to be tokenized as an identifier, due to the "longest possible translation" rule (3.2). For example, the sequence of twelve input characters p u b l i c s t a t i c is always tokenized as the identifier publicstatic, rather than as the reserved keywords public and static. If two tokens are intended, they must be separated by white space or a comment.

The rule above works in tandem with the "longest possible translation" rule to produce an intuitive result in contexts where contextual keywords may appear. For example, the sequence of eleven input characters v a r f i l e n a m e is usually tokenized as the identifier varfilename, but in a local variable declaration, the first three input characters are tentatively recognized as the contextual keyword var by the first condition of the rule above. However, it would be confusing to overlook the lack of white space in the sequence by recognizing the next eight input characters as the identifier filename. (This would mean that the sequence undergoes different tokenization in different contexts: an identifier in most contexts, but a contextual keyword and an identifier in local variable declarations.) Accordingly, the second condition prevents recognition of the contextual keyword var on the grounds that the immediately following input character f is a JavaLetterOrDigit. The sequence v a r f i l e n a m e is therefore tokenized as the identifier varfilename in a local variable declaration.

As another example of the careful recognition of contextual keywords, consider the sequence of 15 input characters n o n - s e a l e d c l a s s. This sequence is usually translated to three tokens - the identifier non, the operator -, and the identifier sealedclass - but in a normal class declaration, where the first condition holds, the first ten input characters are tentatively recognized as the contextual keyword non-sealed. To avoid translating the sequence to two keyword tokens (non-sealed and class) rather than three non-keyword tokens, and to avoid rewarding the programmer for omitting white space before class, the second condition prevents recognition of the contextual keyword. The sequence n o n - s e a l e d c l a s s is therefore tokenized as three tokens in a class declaration.

In the rule above, the first condition depends on details of the syntactic grammar, but a compiler for the Java programming language can implement the rule without fully parsing the input program. For example, a heuristic could be used to track the contextual state of the tokenizer, as long as the heuristic guarantees that valid uses of contextual keywords are tokenized as keywords, and valid uses of identifiers are tokenized as identifiers. Alternatively, a compiler could always tokenize a contextual keyword as an identifier, leaving it to a later phase to recognize special uses of these identifiers.

Chapter 5: Conversions and Contexts

5.5 Casting Contexts

Casting contexts allow the operand of a cast expression (15.16) to be converted to the type explicitly named by the cast operator. Compared to assignment contexts and invocation contexts, casting contexts allow the use of more of the conversions defined in 5.1, and allow more combinations of those conversions.

If the expression is of a primitive type, then a casting context allows the use of one of the following:

• an identity conversion (5.1.1)

• a widening primitive conversion (5.1.2)

• a narrowing primitive conversion (5.1.3)

• a widening and narrowing primitive conversion (5.1.4)

• a boxing conversion (5.1.7)

• a boxing conversion followed by a widening reference conversion (5.1.5)

If the expression is of a reference type, then a casting context allows the use of one of the following:

• an identity conversion (5.1.1)

• a widening reference conversion (5.1.5)

• a widening reference conversion followed by an unboxing conversion

• a widening reference conversion followed by an unboxing conversion, then followed by a widening primitive conversion

• a narrowing reference conversion (5.1.6)

• a narrowing reference conversion followed by an unboxing conversion

• an unboxing conversion (5.1.8)

• an unboxing conversion followed by a widening primitive conversion

If the expression has the null type, then the expression may be cast to any reference type.

If a casting context makes use of a narrowing reference conversion that is checked or partially unchecked (5.1.6.2, 5.1.6.3), then a run time check will be performed on the class of the expression's value, possibly causing a ClassCastException. Otherwise, no run time check is performed.

If an expression can be converted to a reference type by a casting conversion other than a narrowing reference conversion which is unchecked, we say the expression (or its value) is downcast compatible with the reference type.

The following tables enumerate which conversions are used in certain casting contexts. Each conversion is signified by a symbol:

• - signifies no conversion allowed

• ≈ signifies identity conversion (5.1.1)

• ω signifies widening primitive conversion (5.1.2)

• η signifies narrowing primitive conversion (5.1.3)

• ωη signifies widening and narrowing primitive conversion (5.1.4)

• ⇑ signifies widening reference conversion (5.1.5)

• ⇓ signifies narrowing reference conversion (5.1.6)

• ⊕ signifies boxing conversion (5.1.7)

• ⊗ signifies unboxing conversion (5.1.8)

In the tables, a comma between symbols indicates that a casting context uses one conversion followed by another. The type Object means any reference type other than the eight wrapper classes Boolean, Byte, Short, Character, Integer, Long, Float, Double.

class Point { int x, y; }
interface Colorable { void setColor(int color); }
class ColoredPoint extends Point implements Colorable {
    int color;
    public void setColor(int color) { this.color = color; }
}
final class EndPoint extends Point {}

class Test {
    public static void main(String[] args) {
        Point p = new Point();
        ColoredPoint cp = new ColoredPoint();
        Colorable c;
        // The following may cause errors at run time because
        // we cannot be sure they will succeed; this possibility
        // is suggested by the casts:
        cp = (ColoredPoint)p;  // p might not reference an
                               // object which is a ColoredPoint
                               // or a subclass of ColoredPoint
        c = (Colorable)p;      // p might not be Colorable
        // The following are incorrect at compile time because
        // they can never succeed as explained in the text:
        Long l = (Long)p;            // compile-time error #1
        EndPoint e = new EndPoint();
        c = (Colorable)e;            // compile-time error #2
    }
}

class Point {
    int x, y;
    Point(int x, int y) { this.x = x; this.y = y; }
    public String toString() { return "("+x+","+y+")"; }
}
interface Colorable { void setColor(int color); }
class ColoredPoint extends Point implements Colorable {
    int color;
    ColoredPoint(int x, int y, int color) {
        super(x, y); setColor(color);
    }
    public void setColor(int color) { this.color = color; }
    public String toString() {
        return super.toString() + "@" + color;
    }
}

class Test {
    public static void main(String[] args) {
        Point[] pa = new ColoredPoint[4];
        pa[0] = new ColoredPoint(2, 2, 12);
        pa[1] = new ColoredPoint(4, 5, 24);
        ColoredPoint[] cpa = (ColoredPoint[])pa;
        System.out.print("cpa: {");
        for (int i = 0; i < cpa.length; i++)
            System.out.print((i == 0 ? " " : ", ") + cpa[i]);
        System.out.println(" }");
    }
}

cpa: { (2,2)@12, (4,5)@24, null, null }

class Point { int x, y; }
interface Colorable { void setColor(int color); }
class ColoredPoint extends Point implements Colorable {
    int color;
    public void setColor(int color) { this.color = color; }
}

class Test {
    public static void main(String[] args) {
        Point[] pa = new Point[100];

        // The following line will throw a ClassCastException:
        ColoredPoint[] cpa = (ColoredPoint[])pa;
        System.out.println(cpa[0]);
        int[] shortvec = new int[2];
        Object o = shortvec;

        // The following line will throw a ClassCastException:
        Colorable c = (Colorable)o;
        c.setColor(0);
    }
}

Chapter 6: Names

6.3 Scope of a Declaration

6.3.1 Scope for Pattern Variables in Expressions

6.3.1.6 switch Expressions

The following rule applies rules apply to a switch expression (15.28) with a switch block consisting of switch rules (14.11.1):

• A pattern variable introduced by a statement S contained in a switch labeled statement group (14.11.1) is definitely matched at all the statements following S, if any, in the switch labeled statement group.

6.3.2 Scope for Pattern Variables in Statements

6.3.2.6 switch Statements

The following rule applies rules apply to a switch statement (14.11) with a switch block consisting of switch rules (14.11.1):

• A pattern variable introduced by a labeled statement S contained in a switch block statement group (14.11.1) is definitely matched at all the statements following S, if any, in the switch block statement group.

6.3.3 Scope for Pattern Variables in Patterns

6.3.3.1 Record Patterns

6.3.4 Scope for Pattern Variables in Switch Labels

Chapter 13: Binary Compatibility

13.4 Evolution of Classes

13.4.2 sealed, non-sealed, and final Classes

13.4.2.1 sealed Classes

If a class that was freely extensible (8.1.1.2) is changed to be declared sealed, then an IncompatibleClassChangeError is thrown if a binary of a pre-existing subclass of this class is loaded and is not a permitted direct subclass of this class (8.1.6); such a change is not recommended for widely distributed classes.

Changing a class that was declared final to be declared sealed does not break compatibility with pre-existing binaries.

Adding a class to the set of permitted direct subclasses of a sealed class will not break compatibility with pre-existing binaries.

If a class is removed from the set of permitted direct subclasses of a sealed class, then an IncompatibleClassChangeError is thrown if the pre-existing binary of the removed class is loaded.

Deleting the sealed modifier from a class that does not have a sealed direct superclass or a sealed direct superinterface does not break compatibility with pre-existing binaries.

If a sealed class C did have a sealed direct superclass or a sealed direct superinterface, then deleting the sealed modifier would prevent C from being recompiled, as every class with a sealed direct superclass or a sealed direct superinterface must be either final, sealed, or non-sealed.

13.4.26 Evolution of Enum Classes

Adding or reordering enum constants in an enum class will not break compatibility with pre-existing binaries.

Deleting an enum constant from an enum class will delete the public field that corresponds to the enum constant (8.9.3). The consequences are specified in 13.4.8. Such a change is not recommended for widely distributed enum classes.

In all other respects, the binary compatibility rules for enum classes are identical to those for normal classes.

13.5 Evolution of Interfaces

13.5.2 sealed and non-sealed Interfaces

If an interface that was freely extensible (9.1.1.4) is changed to be declared sealed, then an IncompatibleClassChangeError is thrown if a binary of a pre-existing subclass or subinterface of this interface is loaded and is not a permitted direct subclass or subinterface of this interface (9.1.4); such a change is not recommended for widely distributed classes.

Adding a class or interface to the set of permitted direct subclasses or subinterfaces, respectively, of a sealed interface will not break compatibility with pre-existing binaries.

If a class or interface is removed from the set of permitted direct subclasses or subinterfaces of a sealed interface, then an IncompatibleClassChangeError is thrown if the pre-existing binary of the removed class or interface is loaded.

Changing an interface that was declared sealed to be declared non-sealed does not break compatibility with pre-existing binaries.

A non-sealed interface I must have a sealed direct superinterface. Deleting the non-sealed modifier would prevent I from being recompiled, as every interface with a sealed direct superinterface must be sealed or non-sealed.

Deleting the sealed modifier from an interface that does not have a sealed direct superinterface does not break compatibility with pre-existing binaries.

If a sealed interface I did have a sealed direct superinterface, then deleting the sealed modifier would prevent I from being recompiled, as every interface with a sealed direct superinterface must be sealed or non-sealed.

Chapter 14: Blocks, Statements, and Patterns

14.11 The switch Statement

The switch statement transfers control to one of several statements or expressions, depending on the value of an expression.

SwitchStatement:

switch ( Expression ) SwitchBlock

The Expression is called the selector expression. The type of the selector expression must be char, byte, short, int, Character, Byte, Short, Integer, String, or an enum type (8.9), or a compile-time error occurs.

14.11.1 Switch Blocks

The body of both a switch statement and a switch expression (15.28) is called a switch block. This subsection presents general rules which apply to all switch blocks, whether they appear in switch statements or switch expressions. Other subsections present additional rules which apply either to switch blocks in switch statements (14.11.2) or to switch blocks in switch expressions (15.28.1).

SwitchBlock:

{ SwitchRule {SwitchRule} }

{ {SwitchBlockStatementGroup} {SwitchLabel :} }

SwitchRule:

SwitchLabel -> Expression ;

SwitchLabel -> Block

SwitchLabel -> ThrowStatement

SwitchBlockStatementGroup:

SwitchLabel : {SwitchLabel :} BlockStatements

CaseConstant:

ConditionalExpression

A switch block can consist of either:

• Switch rules, which use -> to introduce either a switch rule expression, a switch rule block, or a switch rule throw statement; or

• Switch labeled statement groups, which use : to introduce switch labeled block statements.

The switch block of a switch statement or a switch expression must be switch compatible with the type of the selector expression, or a compile-time error occurs.

14.11.1.1 Exhaustive Switch Blocks

14.11.1.2 Executable Switch Blocks and Determining which Switch Label Applies at Run-Time

Both the execution of a an executable switch statement (14.11.3) and the evaluation of a an executable switch expression (15.28.2) need to determine if a switch label matches applies to the value of the selector expression. To determine Determining whether a switch label in a switch block matches applies to a given value, the value is compared with the case constants associated with the switch block is proceeds as follows: Then:

• If the value is not the null reference, then we determine the first (if any) switch label in the switch block that applies to the value as follows:

  1. A switch label that supports a case constant c applies to a value of type Character, Byte, Short, or Integer, if the value is first subjected to unboxing conversion (5.1.8) and the constant c is equal to the unboxed value. If one of the case constants is equal to the value, then we say that the case label which contains the case constant matches.

     Any unboxing conversion must complete normally as the value being unboxed is guaranteed not to be the null reference.

     Equality is defined in terms of the == operator (15.21).

  2. A switch label that supports a case constant c applies to a value that is not of type Character, Byte, Short, or Integer, if the constant c is equal to the value.

     Equality is defined in terms of the == operator (15.21) unless the value is a String, in which case equality is defined in terms of the equals method of class String.

  3. Determining that a switch label that supports a pattern p applies to a value proceeds first by checking if the value matches the pattern p (14.30.2).

     If pattern matching completes abruptly then the process of determining which switch label applies completes abruptly for the same reason.

     If pattern matching succeeds and the pattern does not have an associated when expression then this switch label applies.

     If pattern matching succeeds and the pattern has an associated when expression, then the when expression is evaluated. If the result is of type Boolean, it is subjected to unboxing conversion (5.1.8).

     If evaluation of the when expression or the subsequent unboxing conversion (if any) completes abruptly for some reason, the process of determining which switch label applies completes abruptly for the same reason.

     Otherwise, if the resulting value is true then the switch label applies.

  4. If no case label matches but there is a default label, then the default label matches. If none of the preceding rules apply to any of the switch labels in the switch block, then a default switch label applies.

     A switch block may have at most one default switch label.

A case switch label can contain support several case constants. The label matches applies to the value of the selector expression if any one of its constants matches is equal to the value of the selector expression. For example, in the following code, the case switch label matches if the enum variable day is either one of the enum constants shown:

switch (day) {
    ...
    case SATURDAY, SUNDAY :
        System.out.println("It's the weekend!");
        break;
    ...
}

If a switch label that supports a pattern applies, then this is because the process of pattern matching the value against the pattern has succeeded (14.30.2). If a value successfully matches a pattern then the process of pattern matching initializes any pattern variables declared by the pattern.

In C and C++ the body of a switch statement can be a statement and statements with case labels do not have to be immediately contained by that statement. Consider the simple loop:

for (i = 0; i < n; ++i) foo();

where n is known to be positive. A trick known as Duff's device can be used in C or C++ to unroll the loop, but this is not valid code in the Java programming language:

int q = (n+7)/8;
switch (n%8) {
    case 0: do { foo();    // Great C hack, Tom,
    case 7:      foo();    // but it's not valid here.
    case 6:      foo();
    case 5:      foo();
    case 4:      foo();
    case 3:      foo();
    case 2:      foo();
    case 1:      foo();
            } while (--q > 0);
}

Fortunately, this trick does not seem to be widely known or used. Moreover, it is less needed nowadays; this sort of code transformation is properly in the province of state-of-the-art optimizing compilers.

14.11.2 The Switch Block of a switch Statement

In addition to the general rules for switch blocks (14.11.1), there are further rules for switch blocks in switch statements.

An enhanced switch statement is one where either (i) the type of the selector expression is not char, byte, short, int, Character, Byte, Short, Integer, String, or an enum type, or (ii) at least one of the switch labels supports a pattern or a null.

Namely, all All of the following must be true for the switch block of a switch statement, or a compile-time error occurs:

• No more than one default label is associated with the switch block.

• Every switch rule expression in the switch block is a statement expression (14.8).

  switch statements differ from switch expressions in terms of which expressions may appear to the right of an arrow (->) in the switch block, that is, which expressions may be used as switch rule expressions. In a switch statement, only a statement expression may be used as a switch rule expression, but in a switch expression, any expression may be used (15.28.1).

• If the switch statement is an enhanced switch statement, then it must be exhaustive.

14.11.3 Execution of a switch Statement

An executable A switch statement (14.11.1.2) is executed by first evaluating the selector expression. Then:

• If evaluation of the selector expression completes abruptly, then the entire switch statement completes abruptly for the same reason.

• Otherwise, if the result of evaluating the selector expression is null, and no switch label in the resolved switch block applies then a NullPointerException is thrown and the entire switch statement completes abruptly for that reason. If the process of determining which switch label applies completes abruptly, then the entire switch statement completes abruptly for the same reason.

If evaluation of the selector expression completes normally and the result is non-null, and the subsequent unboxing conversion (if any) completes normally, then execution of the switch statement continues by determining if a switch label associated with in the resolved switch block matches applies to the value of the selector expression (14.11.1.2). Then:

• If the process of determining which switch label applies completes abruptly, then the entire switch statement completes abruptly for the same reason.

• If no switch label matches, the entire switch statement completes normally. applies then one of the following holds:

  1. If the switch statement is an enhanced switch statement and the result of evaluating the selector expression is of an enum type then an IncompatibleClassChangeError is thrown and the entire switch statement completes abruptly for that reason.

  2. If the switch statement is an enhanced switch statement and the result of evaluating the selector expression is not of an enum type then a MatchException is thrown and the entire switch statement completes abruptly for that reason.

  3. If the switch statement is not an enhanced switch statement then the entire switch statement completes normally.

• If a switch label matches applies, then one of the following applies holds:

  • If it is the switch label for a switch rule expression, then the switch rule expression is necessarily a statement expression (14.11.2). The statement expression is evaluated. If the evaluation completes normally, then the switch statement completes normally. If the result of evaluation is a value, it is discarded.

  • If it is the switch label for a switch rule block, then the block is executed. If this block completes normally, then the switch statement completes normally.

  • If it is the switch label for a switch rule throw statement, then the throw statement is executed.

  • If it is the switch label for a switch labeled statement group, then all the statements in the switch block that follow the switch label are executed in order. If these statements complete normally, then the switch statement completes normally.

  • Otherwise, there are no statements that follow the matched switch label that applies in the switch block, and the switch statement completes normally.

If execution of any statement or expression in the switch block completes abruptly, it is handled as follows:

• If execution of a statement completes abruptly because of a break with no label, then no further action is taken and the switch statement completes normally.

  Abrupt completion because of a break with a label is handled by the general rule for labeled statements (14.7).

• If execution of a statement or expression completes abruptly for any other reason, then the switch statement completes abruptly for the same reason.

  Abrupt completion because of a yield statement is handled by the general rule for switch expressions (15.28.2).

class TooMany {
    static void howMany(int k) {
        switch (k) {
            case 1: System.out.print("one ");
            case 2: System.out.print("too ");
            case 3: System.out.println("many");
        }
    }
    public static void main(String[] args) {
        howMany(3);
        howMany(2);
        howMany(1);
    }
}

many
too many
one too many

class TwoMany {
    static void howMany(int k) {
        switch (k) {
            case 1: System.out.println("one");
                    break;  // exit the switch
            case 2: System.out.println("two");
                    break;  // exit the switch
            case 3: System.out.println("many");
                    break;  // not needed, but good style
        }
    }
    static void howManyAgain(int k) {
        switch (k) {
            case 1 -> System.out.println("one");
            case 2 -> System.out.println("two");
            case 3 -> System.out.println("many");
        }
    }
    public static void main(String[] args) {
        howMany(1);
        howMany(2);
        howMany(3);
        howManyAgain(1);
        howManyAgain(2);
        howManyAgain(3);    
    }
}

one
two
many
one
two
many

14.30 Patterns

A pattern describes a test that can be performed on a value. Patterns appear as operands of statements and expressions, which provide the values to be tested. Patterns may declare local variables, known as pattern variables.

The process of testing a value against a pattern is known as pattern matching. If a value successfully matches a pattern, then the process of pattern matching initializes the pattern variable variables, if any, declared by the pattern.

Pattern variables are only in scope (6.3) where pattern matching succeeds and thus the pattern variables will have been initialized. It is not possible to use a pattern variable that has not been initialized.

14.30.1 Kinds of Patterns

A type pattern is used to test whether a value is an instance of the type appearing in the pattern. A pattern may be parenthesized to assist in readability. A record pattern is used to test whether a value is an instance of a record class type and, if it is, to recursively perform pattern matching on the record component values.

Pattern:

TypePattern

ParenthesizedPattern

RecordPattern

TypePattern:

LocalVariableDeclaration

The following productions from 4.3, 8.3, 8.4.1, and 14.4 are shown here for convenience:

LocalVariableDeclaration:

{VariableModifier} LocalVariableType VariableDeclaratorList

VariableModifier:

Annotation

final

LocalVariableType:

UnannType

var

VariableDeclaratorList:

VariableDeclarator {, VariableDeclarator}

VariableDeclarator:

VariableDeclaratorId [= VariableInitializer]

VariableDeclaratorId:

Identifier [Dims]

Dims:

{Annotation} [ ] {{Annotation} [ ]}

See 8.3 for UnannType.

A type pattern declares one local variable, known as a pattern variable. The Identifier in the local variable declaration specifies the name of the pattern variable.

The rules for a local variable declared in a type pattern are specified in 14.4. In addition, all of the following must be true, or a compile-time error occurs:

• The LocalVariableType in a top-level type pattern denotes a reference type (and furthermore is not var).

• The VariableDeclaratorList consists of a single VariableDeclarator.

• The VariableDeclarator has no initializer.

• The VariableDeclaratorId has no bracket pairs.

The declared type of a pattern variable declared in a top-level type pattern is the reference type denoted by LocalVariableType.

The type of a type pattern is the type of its pattern variable.

14.30.2 Pattern Matching

Pattern matching is the process of testing a value against a pattern at run time. Pattern matching is distinct from statement execution (14.1) and expression evaluation (15.1). If a value successfully matches a pattern, then the process of pattern matching will initialize all the pattern variables declared by the pattern, if any.

The rules for determining whether a value matches a pattern, and for initializing pattern variables, are as follows:

• A value v that is not the null reference matches a type pattern of type T if v can be cast to T without raising a ClassCastException; and does not match otherwise.

  If v matches, then the pattern variable declared by the type pattern is initialized to v.

  If v does not match, then the pattern variable declared by the type pattern is not initialized.

14.30.3 Properties of Patterns

Chapter 15: Expressions

15.20 Relational Operators

15.20.2 The instanceof Operator

An instanceof expression may perform either type comparison or pattern matching.

InstanceofExpression:

RelationalExpression instanceof ReferenceType

RelationalExpression instanceof Pattern

If the operand to the right of the instanceof keyword is a ReferenceType, then the instanceof keyword is the type comparison operator.

If the operand to the right of the instanceof keyword is a Pattern, then the instanceof keyword is the pattern match operator.

The following rules apply when instanceof is the type comparison operator:

• The type of the expression RelationalExpression must be a reference type or the null type, or a compile-time error occurs.

• The RelationalExpression must be downcast compatible with the ReferenceType (5.5), or a compile-time error occurs.

• At run time, the result of the type comparison operator is determined as follows:

  • If the value of the RelationalExpression is the null reference (4.1), then the result is false.

  • If the value of the RelationalExpression is not the null reference, then the result is true if the value could be cast to the ReferenceType without raising a ClassCastException, and false otherwise.

The following rules apply when instanceof is the pattern match operator:

• The type of the expression RelationalExpression must be a reference type or the null type, or a compile-time error occurs.

• The RelationalExpression must be compatible with the Pattern (14.30.1), or a compile-time error occurs. The Pattern must be applicable at the type of the expression RelationalExpression (14.30.3), or a compile-time error occurs.

• If the type of the RelationalExpression is a subtype of the type of the Pattern, then a compile-time error occurs.

• Before pattern matching is performed, all patterns are first resolved (14.30.2). An executable pattern match operator is one where the Pattern has been resolved at the type of the RelationalExpression.

• At run time, the result of the executable pattern match operator is determined as follows:

  • If the value of the RelationalExpression is the null reference, then the result is false.

  • If the value of the RelationalExpression is not the null reference, then the result is true if the value matches the Pattern (14.30.2), and false otherwise.

    A side effect of a true result is that all the pattern variables declared in Pattern, if any, will be initialized.

class Point   { int x, y; }
class Element { int atomicNumber; }
class Test {
    public static void main(String[] args) {
        Point   p = new Point();
        Element e = new Element();
        if (e instanceof Point) {  // compile-time error
            System.out.println("I get your point!");
            p = (Point)e;  // compile-time error
        }
    }
}

class Point extends Element { int x, y; }

import java.util.ArrayList;
import java.util.List;

class Test2 {
    public static void main(String[] args) {
        List<Integer> x = new ArrayList<Integer>();
    
        if (x instanceof ArrayList<Integer>) {  // OK
            System.out.println("ArrayList of Integers");
        }
        if (x instanceof ArrayList<String>) {  // error
            System.out.println("ArrayList of Strings");
        }
        if (x instanceof ArrayList<Object>) {  // error
            System.out.println("ArrayList of Objects");
        }
    }
}

15.28 switch Expressions

A switch expression transfers control to one of several statements or expressions, depending on the value of an expression; all possible values of that expression must be handled, and all of the several statements and expressions must produce a value for the result of the switch expression.

SwitchExpression:

switch ( Expression ) SwitchBlock

The Expression is called the selector expression. The type of the selector expression must be char, byte, short, int, Character, Byte, Short, Integer, String, or an enum type (8.9), or a compile-time error occurs.

The body of both a switch expression and a switch statement (14.11) is called a switch block. General rules which apply to all switch blocks, whether they appear in switch expressions or switch statements, are given in 14.11.1. The following productions from 14.11.1 are shown here for convenience:

SwitchBlock:

{ SwitchRule {SwitchRule} }

{ {SwitchBlockStatementGroup} {SwitchLabel :} }

SwitchRule:

SwitchLabel -> Expression ;

SwitchLabel -> Block

SwitchLabel -> ThrowStatement

SwitchBlockStatementGroup:

SwitchLabel : {SwitchLabel :} BlockStatements

SwitchLabel:

case CaseConstant {, CaseConstant}

default

SwitchLabel:

CaseOrDefaultLabel {: CaseOrDefaultLabel }

CaseOrDefaultLabel:

case CaseElement {, CaseElement }

default

CaseElement:

CaseConstant

Pattern { Guard }

null

default

CaseConstant:

ConditionalExpression

Guard:

when Expression

15.28.1 The Switch Block of a switch Expression

In addition to the general rules for switch blocks (14.11.1), there are further rules for switch blocks in switch expressions. Namely, all of the following must be true for the switch block of a switch expression, or a compile-time error occurs:

• If the switch block consists of switch rules, then any switch rule block cannot complete normally (14.22).

• If the switch block consists of switch labeled statement groups, then the last statement in the switch block cannot complete normally, and the switch block does not have any switch labels after the last switch labeled statement group.

switch expressions cannot have empty switch blocks, unlike switch statements. Furthermore, switch expressions differ from switch statements in terms of which expressions may appear to the right of an arrow (->) in the switch block, that is, which expressions may be used as switch rule expressions. In a switch expression, any expression may be used as a switch rule expression, but in a switch statement, only a statement expression may be used (14.11.1).

A switch expression must be exhaustive (14.11.1.1), or a compile-time error occurs.

The result expressions of a switch expression are determined as follows:

• If the switch block consists of switch rules, then each switch rule is considered in turn:

  • If the switch rule is of the form ... -> Expression then Expression is a result expression of the switch expression.

  • If the switch rule is of the form ... -> Block then every expression which is immediately contained in a yield statement in Block whose yield target is the given switch expression, is a result expression of the switch expression.

• If the switch block consists of switch labeled statement groups, then every expression immediately contained in a yield statement in the switch block whose yield target is the given switch expression, is a result expression of the switch expression.

It is a compile-time error if a switch expression has no result expressions.

A switch expression is a poly expression if it appears in an assignment context or an invocation context (5.2, 5.3). Otherwise, it is a standalone expression.

Where a poly switch expression appears in a context of a particular kind with target type T, its result expressions similarly appear in a context of the same kind with target type T.

A poly switch expression is compatible with a target type T if each of its result expressions is compatible with T.

The type of a poly switch expression is the same as its target type.

The type of a standalone switch expression is determined as follows:

• If the result expressions all have the same type (which may be the null type (4.1)), then that is the type of the switch expression.

• Otherwise, if the type of each result expression is boolean or Boolean, then an unboxing conversion (5.1.8) is applied to each result expression of type Boolean, and the switch expression has type boolean.

• Otherwise, if the type of each result expression is convertible to a numeric type (5.1.8), then the type of the switch expression is the result of general numeric promotion (5.6) applied to the result expressions.

• Otherwise, boxing conversion (5.1.7) is applied to each result expression that has a primitive type, after which the type of the switch expression is the result of applying capture conversion (5.1.10) to the least upper bound (4.10.4) of the types of the result expressions.

15.28.2 Run-Time Evaluation of switch Expressions

An executable A switch expression (14.11.1.2) is evaluated by first evaluating the selector expression. Then:

• If evaluation of the selector expression completes abruptly, then the switch expression completes abruptly for the same reason.

• Otherwise, if the result of evaluating the selector expression is null, and no switch label in the resolved switch block applies then a NullPointerException is thrown and the entire switch expression completes abruptly for that reason. If the process of determining which switch label applies completes abruptly, then the entire switch expression completes abruptly for the same reason.

If evaluation of the selector expression completes normally and the result is non-null, and the subsequent unboxing conversion (if any) completes normally, then evaluation of the switch expression continues by determining if a switch label associated with in the resolved switch block matches applies to the value of the selector expression (14.11.1.2). Then:

• If the process of determining which switch label applies completes abruptly, then the entire switch expression completes abruptly for the same reason.

• If no switch label matches applies, and the result of evaluating the selector expression is of an enum type then an IncompatibleClassChangeError is thrown and the entire switch expression completes abruptly for that reason.

• If no switch label applies, and the result of evaluating the selector expression is not of an enum type then a MatchException is thrown and the entire switch expression completes abruptly for that reason.

• If a switch label matches applies, then one of the following applies holds:

  • If it is the switch label for a switch rule expression, then the expression is evaluated. If the result of evaluation is a value, then the switch expression completes normally with the same value.

  • If it is the switch label for a switch rule block, then the block is executed. If this block completes normally, then the switch expression completes normally.

  • If it is the switch label for a switch rule throw statement, then the throw statement is executed.

  • Otherwise, all the statements in the switch block after the matching switch label that applies are executed in order. If these statements complete normally, then the switch expression completes normally.

If execution of any statement or expression in the switch block completes abruptly, it is handled as follows:

• If execution of an expression completes abruptly, then the switch expression completes abruptly for the same reason.

• If execution of a statement completes abruptly because of a yield with value V, then the switch expression completes normally and the value of the switch expression is V.

• If execution of a statement completes abruptly for any reason other than a yield with a value, then the switch expression completes abruptly for the same reason.

Chapter 16: Definite Assignment

16.2 Definite Assignment and Statements

16.2.9 switch Statements

• V is [un]assigned after a switch statement (14.11) iff all of the following are true:

  • V is [un]assigned before every break statement (14.15) that may exit the switch statement.

  • For each switch rule (14.11.1) in the switch block, V is [un]assigned after the switch rule expression, switch rule block, or switch rule throw statement introduced by the switch rule.

  • If there is a switch labeled statement group in the switch block, then V is [un]assigned after the last block statement of the last switch labeled statement group.

  • If there is no default label in the switch block the switch statement is not exhaustive, or if the switch block ends with a switch label followed by the } separator, then V is [un]assigned after the selector expression.

• V is [un]assigned before the selector expression of a switch statement iff V is [un]assigned before the switch statement.

• V is [un]assigned before the switch rule expression, switch rule block, or switch rule throw statement introduced by a switch rule in the switch block iff V is [un]assigned after the selector expression of the switch statement.

• V is [un]assigned before the first block statement of a switch labeled statement group in the switch block iff both of the following are true:

  • V is [un]assigned after the selector expression of the switch statement.

  • If the switch labeled statement group is not the first in the switch block, V is [un]assigned after the last block statement of the preceding switch labeled statement group.

• V is [un]assigned before a block statement that is not the first of a switch labeled statement group in the switch block iff V is [un]assigned after the preceding block statement.