Specification for JEP 325: Switch Expressions

This document proposes changes to the Java Language Specification to support extensions to the switch statement so that it can be used as either a statement or an expression, along with associated changes to the break statement. See JEP 325 for an overview.

5.6. Numeric Contexts

Numeric contexts apply to the operands of an arithmetic operator, or the result expressions of a switch expression.

A numeric promotion is a process by which, given either an arithmetic operator and its argument expressions, or a switch expression and its result expressions, the ~~arguments~~ subexpressions are converted to an inferred target type T. T is chosen during promotion such that each ~~argument expression~~ subexpression can be converted to T and, in the case of an ~~the~~ arithmetic operation, it is defined for values of type T.

The ~~two~~ three kinds of numeric promotion are unary numeric promotion (5.6.1), ~~and~~ binary numeric promotion (5.6.2), and switch numeric promotion (5.6.3).

5.6.1. Unary Numeric Promotion

Some operators apply unary numeric promotion to a single operand, which must produce a value of a numeric type:

Unary numeric promotion is performed on expressions in the following situations:

5.6.2. Binary Numeric Promotion

When an operator applies binary numeric promotion to a pair of operands, each of which must denote a value that is convertible to a numeric type, the following rules apply, in order:

After the conversion(s), if any, value set conversion (5.1.13) is then applied to each operand.

5.6.3 Switch Numeric Promotion

When a switch expression applies numeric promotion to a set of result expressions, each of which must denote a value that is convertible to a numeric type, the following rules apply, in order:

After the conversion(s), if any, value set conversion (5.1.13) is then applied to each result expression.

11.2.1. Exception Analysis of Expressions

A class instance creation expression (15.9) can throw an exception class E iff either:

A method invocation expression (15.12) can throw an exception class E iff either:

For every other kind of expression, the expression can throw an exception class E iff one of its immediate subexpressions can throw E.

11.2.2. Exception Analysis of Statements

A throw statement (14.18) whose thrown expression has static type E and is not a final or effectively final exception parameter can throw E or any exception class that the thrown expression can throw.

A throw statement whose thrown expression is a final or effectively final exception parameter of a catch clause C can throw an exception class E iff:

The try block can throw E, or an expression used to initialize a resource (in a try-with-resources statement) can throw E, or the automatic invocation of the close() method of a resource (in a try-with-resources statement) can throw E, and E is not assignment compatible with any catchable exception class of any catch clause of the try statement, and either no finally block is present or the finally block can complete normally; or
Some catch block of the try statement can throw E and either no finally block is present or the finally block can complete normally; or
A finally block is present and can throw E.

An explicit constructor invocation statement (8.8.7.1) can throw an exception class E iff either:

Any other statement S can throw an exception class E iff an expression or statement immediately contained in S can throw E.

14.1. Normal and Abrupt Completion of Statements

Every statement has a normal mode of execution in which certain computational steps are carried out. The following sections describe the normal mode of execution for each kind of statement.

If all the steps are carried out as described, with no indication of abrupt completion, the statement is said to complete normally. However, certain events may prevent a statement from completing normally:

If such an event occurs, then execution of one or more statements may be terminated before all steps of their normal mode of execution have completed; such statements are said to complete abruptly.

An abrupt completion always has an associated reason, which is one of the following:

The terms “complete normally” and “complete abruptly” also apply to the evaluation of expressions (15.6). The only reason an expression can complete abruptly is that an exception is thrown, because of either a throw with a given value (14.18) or a run-time exception or error ([11 (Exceptions)], 15.6).

If a statement evaluates an expression, abrupt completion of the expression always causes the immediate abrupt completion of the statement, with the same reason. All succeeding steps in the normal mode of execution are not performed.

Unless otherwise specified in this chapter, abrupt completion of a substatement causes the immediate abrupt completion of the statement itself, with the same reason, and all succeeding steps in the normal mode of execution of the statement are not performed.

Unless otherwise specified, a statement completes normally if all expressions it evaluates and all substatements it executes complete normally.

14.11. The switch Statement

The switch statement transfers control to one of several statements depending on the value of an expression. This expression is known as 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 block

The body of both a switch statement and a switch expression (15.29) is known as a switch block. This block can either be empty, or take one of two forms:

A switch label can be either a case label or a default label. Every case label has at least one case constant. case and default labels, and the case constants of case labels, are said to be associated with the switch block.

Every case constant associated with a given switch block must be either a constant expression (15.28) or the name of an enum constant, or a compile-time error occurs.

A switch block is said to be compatible with the type of the selector expression, T, if both of the following are true:

At run time, the value of the selector expression is compared with each case constant (if the selector expression is a reference type that is not the type String, then it is first subject to an unboxing conversion (5.1.8)):

The prohibition against using null as a case constant prevents code being written that can never be executed. If the selector expression is of a reference type, that is, String or a boxed primitive type or an enum type, then an exception will be thrown will occur if the Expression evaluates to null at run time. In the judgment of the designers of the Java programming language, this is a better outcome than either the switch block not matching or even the default label matching.

In C and C++ the body of a switch statement can be a statement and statements with case heads 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.

A case label can contain several case constants, and matches the value of a selector expression if any one of its case constants matches.

switch (day) {
    case SATURDAY, SUNDAY: 
        // matches if it is a Saturday OR a Sunday
        System.out.println("It's the weekend!");
}

14.11.2 The switch block of a switch statement

Given a switch statement, all of the following must be true or a compile-time error occurs:

14.11.3 Execution of a switch statement

When the switch statement is executed, first the selector expression is evaluated:

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

The case of abrupt completion because of a value break statement is prohibited by (14.15).

The case of abrupt completion because of a labeled break statement is handled by the general rule for labeled statements (14.7).

When a selector expression matches a switch label within a switch labeled rule, only the labeled expression or statement is executed and nothing else. In the other case, all the block statements in the switch block that follow the switch label are executed, including those that appear after subsequent switch labels. The effect is that, as in C and C++, execution of statements can “fall through labels.”

For example, the program:

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);
    }
}

contains a switch block in which the code for each case falls through into the code for the next case. As a result, the program prints:

many
too many
one too many

This fall through behaviour can be the cause of subtle bugs. If code is not to fall through case to case in this manner, switch labeled rules can be used, or empty break statements can be used to explicitly indicate where control should be transfered, as follows:

class TwoMany {
    static void howManyRule(int k) {
        switch (k) {
            case 1 -> System.out.println("one");
            case 2 -> System.out.println("two");
            case 3 -> System.out.println("many");
        }
    }
    static void howManyGroup(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
        }
    }
    public static void main(String args) {
        howManyRule(1);
        howManyRule(2);
        howManyRule(3);
        howManyGroup(1);
        howManyGroup(2);
        howManyGroup(3);
    }
}

This program prints:

one
two
many
one
two
many

14.15. The break Statement

A break statement transfers control out of an enclosing statement, or causes an enclosing switch expression to produce a specified value.

A break statement with no label attempts to transfer control to the innermost enclosing switch, while, do, or for statement of the immediately enclosing method or initializer; this statement, which is called the break target, then immediately completes normally.

~~To be precise, a break statement with no label always completes abruptly, the reason being a break with no label.~~

~~If no switch, while, do, or for statement in the immediately enclosing method, constructor, or initializer contains the break statement, a compile-time error occurs.~~

A break statement with label Identifier attempts to transfer control to the enclosing labeled statement (14.7) that has the same Identifier as its label; this statement, which is called the break target, then immediately completes normally. In this case, the break target need not be a switch, while, do, or for statement.

~~To be precise, a break statement with label Identifier always completes abruptly, the reason being a break with label Identifier.~~

A break statement must refer to a label within the immediately enclosing method, constructor, initializer, or lambda body. There are no non-local jumps. If no labeled statement with Identifier as its label in the immediately enclosing method, constructor, initializer, or lambda body contains the break statement, a compile-time error occurs.

An empty break statement attempts to transfer control to the innermost enclosing switch, while, do, or for statement; this statement, which is called the break target, then immediately completes normally.

A value break statement attempts to transfer control to the innermost enclosing switch expression; this expression, which is called the break target, then immediately completes normally and the value of the Expression becomes the value of the switch expression.

A labeled break statement with label Identifier attempts to transfer control to the enclosing labeled statement (14.7) that has the same Identifier as its label; this statement, which is called the break target, then immediately completes normally.

It is a compile-time error if a break statement has no break target, or if the break target contains any method, constructor, initializer, lambda expression, or switch expression that encloses the break statement.

It is a compile-time error if the break target of a value break statement contains any switch, while, do or for statement that encloses the value break statement.

It is a compile-time error if a value break statement is contained in a labeled statement, where Expression is a simple name (15.14.1) that is the same identifier as the label.

It is a compile-time error if the Expression of a value break statement is void (15.1).

Execution of an empty break statement always completes abruptly, the reason being a break with no label.

Execution of a value break statement first evaluates the Expression. If the evaluation of the Expression completes abruptly for some reason, then the break statement completes abruptly for that reason. If evaluation of the Expression completes normally, producing a value V, then the break statement completes abruptly, the reason being a break with value V.

Execution of a labeled break statement with label Identifier always completes abruptly, the reason being a break with label Identifier.

It can be seen, then, that a break statement always completes abruptly.

The preceding descriptions say “attempts to transfer control” rather than just “transfers control” because if there are any try statements (14.20) within the break target whose try blocks or catch clauses contain the break statement, then any finally clauses of those try statements are executed, in order, innermost to outermost, before control is transferred to the break target. Abrupt completion of a finally clause can disrupt the transfer of control initiated by a break statement.

Example 14.15-1. The break Statement

In the following example, a mathematical graph is represented by an array of arrays. A graph consists of a set of nodes and a set of edges; each edge is an arrow that points from some node to some other node, or from a node to itself. In this example it is assumed that there are no redundant edges; that is, for any two nodes P and Q, where Q may be the same as P, there is at most one edge from P to Q.

Nodes are represented by integers, and there is an edge from node i to node edges[i][j] for every i and j for which the array reference edges[i][j] does not throw an ArrayIndexOutOfBoundsException.

The task of the method loseEdges, given integers i and j, is to construct a new graph by copying a given graph but omitting the edge from node i to node j, if any, and the edge from node j to node i, if any:

class Graph {
    int edges;
    public Graph(int edges) { this.edges = edges; }

    public Graph loseEdges(int i, int j) {
        int n = edges.length;
        int newedges = new int[n];
        for (int k = 0; k < n; ++k) {
edgelist:
{
            int z;
search:
{
            if (k == i) {
                for (z = 0; z < edges[k].length; ++z) {
                    if (edges[k][z] == j) break search;
                }
            } else if (k == j) {
                for (z = 0; z < edges[k].length; ++z) {
                    if (edges[k][z] == i) break search;
                }
            }

            // No edge to be deleted; share this list.
            newedges[k] = edges[k];
            break edgelist;
} //search

            // Copy the list, omitting the edge at position z.
            int m = edges[k].length - 1;
            int ne = new int[m];
            System.arraycopy(edges[k], 0, ne, 0, z);
            System.arraycopy(edges[k], z+1, ne, z, m-z);
            newedges[k] = ne;
} //edgelist
        }
        return new Graph(newedges);
    }
}

Note the use of two statement labels, edgelist and search, and the use of break statements. This allows the code that copies a list, omitting one edge, to be shared between two separate tests, the test for an edge from node i to node j, and the test for an edge from node j to node i.

14.16. The continue Statement

A continue statement may occur only in a while, do, or for statement; statements of these three kinds are called iteration statements. Control passes to the loop-continuation point of an iteration statement.

A continue statement with no label attempts to transfer control to the innermost enclosing while, do, or for statement of the immediately enclosing method, constructor, or initializer; this statement, which is called the continue target, then immediately ends the current iteration and begins a new one.

~~To be precise, such a continue statement always completes abruptly, the reason being a continue with no label.~~

~~If no while, do, or for statement of the immediately enclosing method, constructor, or initializer contains the continue statement, a compile-time error occurs.~~

A continue statement with label Identifier attempts to transfer control to the enclosing labeled statement (14.7) that has the same Identifier as its label; that statement, which is called the continue target, then immediately ends the current iteration and begins a new one.

~~To be precise, a continue statement with label Identifier always completes abruptly, the reason being a continue with label Identifier.~~

~~The continue target must be a while, do, or for statement, or a compile-time error occurs.~~

A continue statement must refer to a label within the immediately enclosing method, constructor, initializer, or lambda body, . There are no non-local jumps. If no labeled statement with Identifier as its label in the immediately enclosing method, constructor, initializer, or lambda body, contains the continue statement, a compile-time error occurs.

An empty continue statement attempts to transfer control to the innermost enclosing while, do, or for statement; this statement, which is called the continue target, then immediately ends the current iteration and begins a new one.

A labeled continue statement with label Identifier attempts to transfer control to the enclosing labeled statement (14.7) that has the same Identifier as its label; that statement, which is called the continue target, then immediately ends the current iteration and begins a new one.

The continue target of a labeled continue must be a while, do, or for statement, or a compile-time error occurs.

It is a compile-time error if a continue statement has no continue target, or if the continue target contains any method, constructor, initializer, lambda expression, or switch expression that contains the continue statement.

Execution of an empty continue statement always completes abruptly, the reason being a continue with no label.

Execution of a labeled continue statement with label Identifier always completes abruptly, the reason being a continue with label Identifier.

It can be seen, then, that a continue statement always completes abruptly.

See the descriptions of the while statement (14.12), do statement (14.13), and for statement (14.14) for a discussion of the handling of abrupt termination because of continue.

The preceding descriptions say “attempts to transfer control” rather than just “transfers control” because if there are any try statements (14.20) within the continue target whose try blocks or catch clauses contain the continue statement, then any finally clauses of those try statements are executed, in order, innermost to outermost, before control is transferred to the continue target. Abrupt completion of a finally clause can disrupt the transfer of control initiated by a continue statement.

Example 14.16-1. The continue Statement

In the Graph class in (14.15), one of the break statements is used to finish execution of the entire body of the outermost for loop. This break can be replaced by a continue if the for loop itself is labeled:

class Graph {
    int edges[][];
    public Graph(int[][] edges) { this.edges = edges; }

    public Graph loseEdges(int i, int j) {
        int n = edges.length;
        int[][] newedges = new int[n][];
edgelists:
        for (int k = 0; k < n; ++k) {
            int z;
search:
{
            if (k == i) {
                for (z = 0; z < edges[k].length; ++z) {
                    if (edges[k][z] == j) break search;
                }
            } else if (k == j) {
                for (z = 0; z < edges[k].length; ++z) {
                    if (edges[k][z] == i) break search;
                }
            }

            // No edge to be deleted; share this list.
            newedges[k] = edges[k];
            continue edgelists;
} //search

            // Copy the list, omitting the edge at position z.
            int m = edges[k].length - 1;
            int ne[] = new int[m];
            System.arraycopy(edges[k], 0, ne, 0, z);
            System.arraycopy(edges[k], z+1, ne, z, m-z);
            newedges[k] = ne;
        } //edgelists
        return new Graph(newedges);
    }
}

Which to use, if either, is largely a matter of programming style.

14.17. The return Statement

A return statement returns control to the invoker of a method (8.4, 15.12), or constructor ([8.8], 15.9).

~~A return statement is contained in the innermost constructor, method, initializer, or lambda expression whose body encloses the return statement.~~

A return statement attempts to transfer control to the invoker of the innermost enclosing constructor, method, intializer, or lambda expression; this declaration is called the return target. In the case of a value return statement, the value of the Expression becomes the value of the invocation.

It is a compile-time error if a return statement has no return target, or if the return target contains any enclosing method, constructor, initializer, lambda expression, or switch expression that contains the return statement.

It is a compile-time error if the return target for a return statement is ~~contained in~~ an instance initializer or a static initializer ([8.6], [8.7]).

~~A return statement with no Expression must be contained in one of the following, or a compile-time error occurs:~~

A return statement with no Expression attempts to transfer control to the invoker of the method, constructor, or lambda body that contains it. To be precise, a return statement with no Expression always completes abruptly, the reason being a return with no value.

~~A return statement with an Expression must be contained in one of the following, or a compile-time error occurs:~~

~~The Expression must denote a variable or a value, or a compile-time error occurs.~~

~~When a return statement with an Expression appears in a method declaration, the Expression must be assignable (5.2) to the declared return type of the method, or a compile-time error occurs.~~

A return statement with an Expression attempts to transfer control to the invoker of the method or lambda body that contains it; the value of the Expression becomes the value of the method invocation. More precisely, execution of such a return statement first evaluates the Expression. If the evaluation of the Expression completes abruptly for some reason, then the return statement completes abruptly for that reason. If evaluation of the Expression completes normally, producing a value V, then the return statement completes abruptly, the reason being a return with value V.

It is a compile-time error if the return target of an empty return statement is a method, and that method is not declared ‘void’.

It is a compile-time error if the return target of a value return statement is a constructor or a method that is declared ‘void’; or if the return target is a method with declared return type T, and Expression is not assignable (5.2) to T.

Execution of an empty return statement always completes abruptly, the reason being a return with no value.

Execution of a value return statement first evaluates the Expression. If the evaluation of the Expression completes abruptly for some reason, then the return statement completes abruptly for that reason. If evaluation of the Expression completes normally, producing a value V, then the return statement completes abruptly, the reason being a return with value V.

If the expression is of type float and is not FP-strict (15.4), then the value may be an element of either the float value set or the float-extended-exponent value set (4.2.3). If the expression is of type double and is not FP-strict, then the value may be an element of either the double value set or the double-extended-exponent value set.

14.21. Unreachable Statements

It is a compile-time error if a statement cannot be executed because it is unreachable.

The definitions here allow a statement to complete normally only if it is reachable.

To shorten the description of the rules, the customary abbreviation “iff” is used to mean “if and only if.”

A reachable break statement exits a statement if, within the break target, either there are no try statements whose try blocks contain the break statement, or there are try statements whose try blocks contain the break statement and all finally clauses of those try statements can complete normally.

A continue statement continues a do statement if, within the do statement, either there are no try statements whose try blocks contain the continue statement, or there are try statements whose try blocks contain the continue statement and all finally clauses of those try statements can complete normally.

One might expect the if statement to be handled in the following manner:

An if-then statement can complete normally iff at least one of the following is true:
- The if-then statement is reachable and the condition expression is not a constant expression whose value is true.
- The then-statement can complete normally.
The then-statement is reachable iff the if-then statement is reachable and the condition expression is not a constant expression whose value is false.
An if-then-else statement can complete normally iff the then-statement can complete normally or the else-statement can complete normally.

The then-statement is reachable iff the if-then-else statement is reachable and the condition expression is not a constant expression whose value is false.

The else-statement is reachable iff the if-then-else statement is reachable and the condition expression is not a constant expression whose value is true.

This approach would be consistent with the treatment of other control structures. However, in order to allow the if statement to be used conveniently for “conditional compilation” purposes, the actual rules differ.

As an example, the following statement results in a compile-time error:

while (false) { x=3; }

because the statement x=3; is not reachable; but the superficially similar case:

if (false) { x=3; }

does not result in a compile-time error. An optimizing compiler may realize that the statement x=3; will never be executed and may choose to omit the code for that statement from the generated class file, but the statement x=3; is not regarded as “unreachable” in the technical sense specified here.

The rationale for this differing treatment is to allow programmers to define “flag variables” such as:

static final boolean DEBUG = false;

and then write code such as:

if (DEBUG) { x=3; }

The idea is that it should be possible to change the value of DEBUG from false to true or from true to false and then compile the code correctly with no other changes to the program text.

This ability to “conditionally compile” has no relationship to binary compatibility ([13 (Binary Compatibility)]). If a set of classes that use such a “flag” variable are compiled and conditional code is omitted, it does not suffice later to distribute just a new version of the class or interface that contains the definition of the flag. The classes that use the flag will not see its new value, so their behavior may be surprising, but no LinkageError will occur. A change to the value of a flag is, therefore, binary compatible with pre-existing binaries, but not behaviorally compatible.

15.1. Evaluation, Denotation, and Result

When an expression in a program is evaluated (executed), the result denotes one of three things:

If an expression denotes a variable, and a value is required for use in further evaluation, then the value of that variable is used. In this context, if the expression denotes a variable or a value, we may speak simply of the value of the expression.

Value set conversion (5.1.13) is applied to the result of every expression that produces a value, including when the value of a variable of type float or double is used.

An expression denotes nothing if and only if it is a method invocation (15.12) that invokes a method that does not return a value, that is, a method declared void (8.4). Such an expression can be used only as an expression statement (14.8) or as the single expression of a lambda body (15.27.2), because every other context in which an expression can appear requires the expression to denote something. An expression statement or lambda body that is a method invocation may also invoke a method that produces a result; in this case the value returned by the method is quietly discarded.

Evaluation of an expression can produce side effects, because expressions may contain embedded assignments, increment operators, decrement operators, and method or constructor invocations, as well as statements contained in switch expressions.

15.2. Forms of Expressions

Expressions can be broadly categorized into one of the following syntactic forms:

Precedence among operators is managed by a hierarchy of grammar productions. The lowest precedence operator is the arrow of a lambda expression (->), followed by the assignment operators. Thus, all expressions are syntactically included in the LambdaExpression and AssignmentExpression nonterminals:

When some expressions appear in certain contexts, they are considered poly expressions. The following forms of expressions may be poly expressions:

The rules determining whether an expression of one of these forms is a poly expression are given in the individual sections that specify these forms of expressions.

Expressions that are not poly expressions are standalone expressions. Standalone expressions are expressions of the forms above when determined not to be poly expressions, as well as all expressions of all other forms. Expressions of all other forms are said to have a standalone form.

Some expressions have a value that can be determined at compile time. These are constant expressions (15.28).

15.6. Normal and Abrupt Completion of Evaluation

Every expression has a normal mode of evaluation in which certain computational steps are carried out. The following sections describe the normal mode of evaluation for each kind of expression.

If all the steps are carried out without an exception being thrown, the expression is said to complete normally.

If, however, evaluation of an expression throws an exception, then the expression is said to complete abruptly. An abrupt completion always has an associated reason, which is always a throw with a given value.

A method invocation expression can also result in an exception being thrown if an exception occurs that causes execution of the method body to complete abruptly.

A class instance creation expression can also result in an exception being thrown if an exception occurs that causes execution of the constructor to complete abruptly.

Various linkage and virtual machine errors may also occur during the evaluation of an expression. By their nature, such errors are difficult to predict and difficult to handle.

If an exception occurs, then evaluation of one or more expressions may be terminated before all steps of their normal mode of evaluation are complete; such expressions are said to complete abruptly.

If evaluation of an expression requires evaluation of a subexpression, then abrupt completion of the subexpression always causes the immediate abrupt completion of the expression itself, with the same reason, and all succeeding steps in the normal mode of evaluation are not performed.

The terms “complete normally” and “complete abruptly” are also applied to the execution of statements (14.1). A statement may complete abruptly for a variety of reasons, not just because an exception is thrown.

15.12.2.1. Identify Potentially Applicable Methods

The class or interface determined by compile-time step 1 (15.12.1) is searched for all member methods that are potentially applicable to this method invocation; members inherited from superclasses and superinterfaces are included in this search.

In addition, if the form of the method invocation expression is MethodName - that is, a single Identifier - then the search for potentially applicable methods also examines all member methods that are imported by single-static-import declarations and static-import-on-demand declarations of the compilation unit where the method invocation occurs (7.5.3, 7.5.4) and that are not shadowed at the point where the method invocation appears.

A member method is potentially applicable to a method invocation if and only if all of the following are true:

If the search does not yield at least one method that is potentially applicable, then a compile-time error occurs.

An expression is potentially compatible with a target type according to the following rules:

15.12.2.5. Choosing the Most Specific Method

If more than one member method is both accessible and applicable to a method invocation, it is necessary to choose one to provide the descriptor for the run-time method dispatch. The Java programming language uses the rule that the most specific method is chosen.

The informal intuition is that one method is more specific than another if any invocation handled by the first method could be passed on to the other one without a compile-time error. In cases such as an explicitly typed lambda expression argument (15.27.1) or a variable arity invocation (15.12.2.4), some flexibility is allowed to adapt one signature to the other.

One applicable method m1 is more specific than another applicable method m2, for an invocation with argument expressions e1, …, ek, if any of the following are true:

The above conditions are the only circumstances under which one method may be more specific than another.

A type S is more specific than a type T for any expression if S <: T (4.10).

A functional interface type S is more specific than a functional interface type T for an expression e if T is not a subtype of S and one of the following is true (where U₁ … U_k and R₁ are the parameter types and return type of the function type of the capture of S, and V₁ … V_k and R₂ are the parameter types and return type of the function type of T):

A method m1 is strictly more specific than another method m2 if and only if m1 is more specific than m2 and m2 is not more specific than m1.

A method is said to be maximally specific for a method invocation if it is accessible and applicable and there is no other method that is applicable and accessible that is strictly more specific.

If there is exactly one maximally specific method, then that method is in fact the most specific method; it is necessarily more specific than any other accessible method that is applicable. It is then subjected to some further compile-time checks as specified in 15.12.3.

It is possible that no method is the most specific, because there are two or more methods that are maximally specific. In this case:

15.15 Unary ~~Operators~~ Expressions

The operators +, -, ++, --, ~, !, and the cast operator (15.16) are called the unary operators., which are used to form unary expressions. In addition, the switch expression (15.29) is treated grammatically as a unary expression.

This portion of the grammar contains some tricks to avoid two potential syntactic ambiguities.

The first potential ambiguity would arise in expressions such as (p)+q, which looks, to a C or C++ programmer, as though it could be either a cast to type p of a unary + operating on q, or a binary addition of two quantities p and q. In C and C++, the parser handles this problem by performing a limited amount of semantic analysis as it parses, so that it knows whether p is the name of a type or the name of a variable.

Java takes a different approach. The result of the + operator must be numeric, and all type names involved in casts on numeric values are known keywords. Thus, if p is a keyword naming a primitive type, then (p)+q can make sense only as a cast of a unary expression. However, if p is not a keyword naming a primitive type, then (p)+q can make sense only as a binary arithmetic operation. Similar remarks apply to the - operator. The grammar shown above splits CastExpression into two cases to make this distinction. The nonterminal UnaryExpression includes all unary operators, but the nonterminal UnaryExpressionNotPlusMinus excludes uses of all unary operators that could also be binary operators, which in Java are + and -.

The second potential ambiguity is that the expression (p)++ could, to a C or C++ programmer, appear to be either a postfix increment of a parenthesized expression or the beginning of a cast, for example, in (p)++q. As before, parsers for C and C++ know whether p is the name of a type or the name of a variable. But a parser using only one-token lookahead and no semantic analysis during the parse would not be able to tell, when ++ is the lookahead token, whether (p) should be considered a Primary expression or left alone for later consideration as part of a CastExpression.

In Java, the result of the ++ operator must be numeric, and all type names involved in casts on numeric values are known keywords. Thus, if p is a keyword naming a primitive type, then (p)++ can make sense only as a cast of a prefix increment expression, and there had better be an operand such as q following the ++. However, if p is not a keyword naming a primitive type, then (p)++ can make sense only as a postfix increment of p. Similar remarks apply to the -- operator. The nonterminal UnaryExpressionNotPlusMinus therefore also excludes uses of the prefix operators ++ and --.

15.25. Conditional Operator ? :

The conditional operator ? : uses the boolean value of one expression to decide which of two other expressions should be evaluated.

The conditional operator is syntactically right-associative (it groups right-to-left). Thus, a?b:c?d:e?f:g means the same as a?b:(c?d:(e?f:g)).

The conditional operator has three operand expressions. ? appears between the first and second expressions, and : appears between the second and third expressions.

The first expression must be of type boolean or Boolean, or a compile-time error occurs.

It is a compile-time error for either the second or the third operand expression to be an invocation of a void method.

There are three kinds of conditional expressions, classified according to the second and third operand expressions: boolean conditional expressions, numeric conditional expressions, and reference conditional expressions. The classification rules are as follows:

The process for determining the type of a conditional expression depends on the kind of conditional expression, as outlined in the following sections.

The following tables summarize the rules above by giving the type of a conditional expression for all possible types of its second and third operands. bnp(..) means to apply binary numeric promotion. The form “T | bnp(..)” is used where one operand is a constant expression of type int and may be representable in type T, where binary numeric promotion is used if the operand is not representable in type T. The operand type Object means any reference type other than the null type and the eight wrapper classes Boolean, Byte, Short, Character, Integer, Long, Float, Double.

At run time, the first operand expression of the conditional expression is evaluated first. If necessary, unboxing conversion is performed on the result.

The resulting boolean value is then used to choose either the second or the third operand expression:

The chosen operand expression is then evaluated and the resulting value is converted to the type of the conditional expression as determined by the rules stated below.

The operand expression not chosen is not evaluated for that particular evaluation of the conditional expression.

15.28. Constant Expressions

A constant expression is an expression denoting a value of primitive type or a String that does not complete abruptly and is composed using only the following:

Constant expressions of type String are always “interned” so as to share unique instances, using the method String.intern.

A constant expression is always treated as FP-strict (15.4), even if it occurs in a context where a non-constant expression would not be considered to be FP-strict.

15.29. switch Expressions

A switch expression is the expression analogue of the switch statement (14.11). It consists of a selector expression and a switch block (14.11.1). A switch expression matches the value of the selector expression against the switch labels associated with the switch block to determine which code contained in the switch block to execute to return a value. In contrast to a switch statement, the switch block is checked to ensure that the switch expression either completes normally with a value or completes abruptly.

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.

15.29.1 The switch block of a switch expression

Given a switch expression, all of the following must be true or a compile-time error occurs:

Given a switch expression, at least one of the following must be true, or a compile-time error occurs:

Given a switch expression, if the switch block consists of switch labeled rules, then it is a compile-time error if any switch labeled block can complete normally. If, on the other hand, the switch block consists of switch labeled statement groups, then it is a compile-time error if either the last statement in the switch block can complete normally, or the switch block includes one or more switch labels at the end.

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.

15.29.2 Execution of a switch expression

When the switch expression is executed, first the selector expression is evaluated; exactly one of three outcomes are possible.

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

16.1.7. switch Expression

Suppose that the switch expression has result expressions e1, …, en, all of which are boolean-valued.

The following rules apply only if the switch block of a switch expression (15.29) consists of switch labeled statement groups:

The following rules apply only if the switch block of a switch expression consists of switch labeled rules:

16.1.8 switch Expression

Suppose that the switch expression has result expressions e1, …, en, not all of which are boolean-valued.

The following rules apply only if the switch block of a switch expression (15.29) consists of switch labeled statement groups:

The following rules apply only if the switch block of a switch expression consists of switch labeled rules:

16.2.9. switch Statements

The following rules apply only if the switch block of a switch statement (14.11) is empty, consists of just switch labels, or consists of switch labeled statement groups:

If a switch block contains at least one ~~block-statement-group~~ switch labeled statement group, then the following rules also apply:

The following rules apply only if the switch block of the switch statement consists of switch labeled rules:

16.2.13. break, continue, return, and throw Statements

18.2.1. Expression Compatibility Constraints

A constraint formula of the form ‹Expression → T› is reduced as follows:

A constraint formula of the form ‹LambdaExpression → T›, where T mentions at least one inference variable, is reduced as follows:

The key piece of information to derive from a compatibility constraint involving a lambda expression is the set of bounds on inference variables appearing in the target function type’s return type. This is crucial, because functional interfaces are often generic, and many methods operating on these types are generic, too.

In the simplest case, a lambda expression may simply provide a lower bound for an inference variable:

<T> List<T> makeThree(Factory<T> factory) { ... }
String s = makeThree(() -> "abc").get(2);

In more complex cases, a result expression may be a poly expression - perhaps even another lambda expression - and so the inference variable might be passed through multiple constraint formulas with different target types before a bound is produced.

Most of the work described in this section precedes assertions about the result expressions; its purpose is to derive the lambda expression’s function type, and to check for expressions that are clearly disqualified from compatibility.

We do not attempt to produce bounds on inference variables that appear in the target function type’s throws clause. This is because exception containment is not part of compatibility (15.27.3) - in particular, it must not influence method applicability (18.5.1). However, we do get bounds on these variables later, because invocation type inference (18.5.2) produces exception containment constraint formulas ([18.2.5]).

Note that if the target type is an inference variable, or if the target type’s parameter types contain inference variables, we produce false. During invocation type inference (18.5.2), extra substitutions are performed in order to instantiate these inference variables, thus avoiding this scenario. (In other words, reduction will, in practice, never be “invoked” with a target type of one of these forms.)

Finally, note that the result expressions of a lambda expression are required by 15.27.3 to be compatible in an assignment context with the target type’s return type, R. If R is a proper type, such as Byte derived from Function<α,Byte``>, then assignability is easy enough to test, and reduction does so above. If R is not a proper type, such as α derived from Function<String,α>, then we make the simplifying assumption above that loose invocation compatibility will be sufficient. The difference between assignment compatibility and loose invocation compatibility is that only assignment allows narrowing of constant expressions, such as Byte b = 100;. Consequently, our simplifying assumption is not completeness-preserving: given target return type α and an integer literal result expression 100, it is conceivable that α could be instantiated to Byte, but reduction will not in fact produce such a bound.

A constraint formula of the form ‹MethodReference → T›, where T mentions at least one inference variable, is reduced as follows:

18.5.2. Invocation Type Inference

Given a method invocation that provides no explicit type arguments, and a corresponding most specific applicable generic method m, the process to infer the invocation type (15.12.2.6) of the chosen method is as follows:

Invocation type inference may require carefully sequencing the reduction of constraint formulas of the forms ‹Expression → T›, ‹LambdaExpression →_throws T›, and ‹MethodReference →_throws T›. To facilitate this sequencing, the input variables of these constraints are defined as follows:

The output variables of these constraints are all inference variables mentioned by the type on the right-hand side of the constraint, T, that are not input variables.

It is important to note that two “rounds” of inference are involved in finding the type of a method invocation. This is necessary to allow a target type to influence the type of the invocation without allowing it to influence the choice of an applicable method. The first round produces a bound set and tests that a resolution exists, but does not commit to that resolution. The second round reduces additional constraints and then performs a second resolution, this time “for real”.

Consider the example from the previous section:

List<Number> ln = Arrays.asList(1, 2.0);

The most specific applicable method was identified as:

public static <T> List<T> asList(T... a)

In order to complete type-checking of the method invocation, we must determine whether it is compatible with its target type, List<Number>.

The bound set used to demonstrate applicability in the previous section, B₂, was:

{ α <: Object, Integer <: α, Double <: α }

The new constraint formula set is as follows:

{ ‹List<α> → List<Number>› }

This compatibility constraint produces an equality bound for α, which is included in the new bound set, B₃:

{ α <: Object, Integer <: α, Double <: α, α = Number }

These bounds are trivially resolved:

α = Number

Finally, we perform a substitution on the declared return type of asList to determine that the method invocation has type List<Number>; clearly, this is compatible with the target type.

This inference strategy is different than the Java SE 7 Edition of The Java® Language Specification, which would have instantiated α based on its lower bounds (before even considering the invocation’s target type), as we did in the previous section. This would result in a type error, since the resulting type is not a subtype of List<Number>.

Under various special circumstances, based on the bounds appearing in B₂, we eagerly resolve an inference variable that appears as the return type of the invocation. This is to avoid unfortunate situations in which the usual constraint, ‹R θ → T›, is not completeness-preserving. It is, unfortunately, possible that by eagerly resolving the variable, we are unable to make use of bounds that would be inferred later. It is also possible that, in some cases, bounds that will later be inferred from the invocation arguments (such as implicitly typed lambda expressions) would have caused a different outcome if they had been present in B₂. Despite these limitations, the strategy allows for reasonable outcomes in typical use cases, and is backwards compatible with the algorithm in the Java SE 7 Edition of The Java® Language Specification.

18.5.4. More Specific Method Inference

When testing that one applicable method is more specific than another (15.12.2.5), where the second method is generic, it is necessary to test whether some instantiation of the second method’s type parameters can be inferred to make the first method more specific than the second.

Let m1 be the first method and m2 be the second method. Where m2 has type parameters P₁, …, P_p, let α₁, …, α_p be inference variables, and let θ be the substitution [P₁:=α₁, …, P_p:=α_p].

Let e1, …, ek be the argument expressions of the corresponding invocation. Then:

Note that no substitution is applied to S₁, …, S_k; even if m1 is generic, the type parameters of m1 are treated as type variables, not inference variables.

Legal Notice

Notice

The Specification is protected by copyright and the information described therein may be protected by one or more U.S. patents, foreign patents, or pending applications. Except as provided under the following license, no part of the Specification may be reproduced in any form by any means without the prior written authorization of Oracle America, Inc. (“Oracle”) and its licensors, if any. Any use of the Specification and the information described therein will be governed by the terms and conditions of this Agreement.

Subject to the terms and conditions of this license, including your compliance with Paragraphs 1 and 2 below, Oracle hereby grants you a fully-paid, non-exclusive, non-transferable, limited license (without the right to sublicense) under Oracle’s intellectual property rights to:

Review the Specification for the purposes of evaluation. This includes: (i) developing implementations of the Specification for your internal, non-commercial use; (ii) discussing the Specification with any third party; and (iii) excerpting brief portions of the Specification in oral or written communications which discuss the Specification provided that such excerpts do not in the aggregate constitute a significant portion of the Technology.
Distribute implementations of the Specification to third parties for their testing and evaluation use, provided that any such implementation:
1. does not modify, subset, superset or otherwise extend the Licensor Name Space, or include any public or protected packages, classes, Java interfaces, fields or methods within the Licensor Name Space other than those required/authorized by the Specification or Specifications being implemented;
2. is clearly and prominently marked with the word “UNTESTED” or “EARLY ACCESS” or “INCOMPATIBLE” or “UNSTABLE” or “BETA” in any list of available builds and in proximity to every link initiating its download, where the list or link is under Licensee’s control; and
3. includes the following notice: “This is an implementation of an early-draft specification developed under the Java Community Process (JCP) and is made available for testing and evaluation purposes only. The code is not compatible with any specification of the JCP.”

The grant set forth above concerning your distribution of implementations of the specification is contingent upon your agreement to terminate development and distribution of your “early draft” implementation as soon as feasible following final completion of the specification. If you fail to do so, the foregoing grant shall be considered null and void.

No provision of this Agreement shall be understood to restrict your ability to make and distribute to third parties applications written to the Specification.

Other than this limited license, you acquire no right, title or interest in or to the Specification or any other Oracle intellectual property, and the Specification may only be used in accordance with the license terms set forth herein. This license will expire on the earlier of: (a) two (2) years from the date of Release listed above; (b) the date on which the final version of the Specification is publicly released; or (c) the date on which the Java Specification Request (JSR) to which the Specification corresponds is withdrawn. In addition, this license will terminate immediately without notice from Oracle if you fail to comply with any provision of this license. Upon termination, you must cease use of or destroy the Specification.

“Licensor Name Space” means the public class or interface declarations whose names begin with “java”, “javax”, “com.oracle” or their equivalents in any subsequent naming convention adopted by Oracle through the Java Community Process, or any recognized successors or replacements thereof.

Trademarks

No right, title, or interest in or to any trademarks, service marks, or trade names of Oracle or Oracle’s licensors is granted hereunder. Oracle, the Oracle logo, Java are trademarks or registered trademarks of Oracle USA, Inc. in the U.S. and other countries.

Disclaimer of Warranties

THE SPECIFICATION IS PROVIDED “AS IS” AND IS EXPERIMENTAL AND MAY CONTAIN DEFECTS OR DEFICIENCIES WHICH CANNOT OR WILL NOT BE CORRECTED BY ORACLE. ORACLE MAKES NO REPRESENTATIONS OR WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT THAT THE CONTENTS OF THE SPECIFICATION ARE SUITABLE FOR ANY PURPOSE OR THAT ANY PRACTICE OR IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADE SECRETS OR OTHER RIGHTS. This document does not represent any commitment to release or implement any portion of the Specification in any product.

THE SPECIFICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION THEREIN; THESE CHANGES WILL BE INCORPORATED INTO NEW VERSIONS OF THE SPECIFICATION, IF ANY. ORACLE MAY MAKE IMPROVEMENTS AND/OR CHANGES TO THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THE SPECIFICATION AT ANY TIME. Any use of such changes in the Specification will be governed by the then-current license for the applicable version of the Specification.

Limitation of Liability

TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILL ORACLE OR ITS LICENSORS BE LIABLE FOR ANY DAMAGES, INCLUDING WITHOUT LIMITATION, LOST REVENUE, PROFITS OR DATA, OR FOR SPECIAL, INDIRECT, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF OR RELATED TO ANY FURNISHING, PRACTICING, MODIFYING OR ANY USE OF THE SPECIFICATION, EVEN IF ORACLE AND/OR ITS LICENSORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

You will hold Oracle (and its licensors) harmless from any claims based on your use of the Specification for any purposes other than the limited right of evaluation as described above, and from any claims that later versions or releases of any Specification furnished to you are incompatible with the Specification provided to you under this license.

Restricted Rights Legend

If this Software is being acquired by or on behalf of the U.S. Government or by a U.S. Government prime contractor or subcontractor (at any tier), then the Government’s rights in the Software and accompanying documentation shall be only as set forth in this license; this is in accordance with 48 C.F.R. 227.7201 through 227.7202-4 (for Department of Defense (DoD) acquisitions) and with 48 C.F.R. 2.101 and 12.212 (for non-DoD acquisitions).

Report

You may wish to report any ambiguities, inconsistencies or inaccuracies you may find in connection with your evaluation of the Specification (“Feedback”). To the extent that you provide Oracle with any Feedback, you hereby: (i) agree that such Feedback is provided on a non-proprietary and non-confidential basis, and (ii) grant Oracle a perpetual, non-exclusive, worldwide, fully paid-up, irrevocable license, with the right to sublicense through multiple levels of sublicensees, to incorporate, disclose, and use without limitation the Feedback for any purpose related to the Specification and future versions, implementations, and test suites thereof.

General Terms

Any action related to this Agreement will be governed by California law and controlling U.S. federal law. The U.N. Convention for the International Sale of Goods and the choice of law rules of any jurisdiction will not apply.

The Specification is subject to U.S. export control laws and may be subject to export or import regulations in other countries. Licensee agrees to comply strictly with all such laws and regulations and acknowledges that it has the responsibility to obtain such licenses to export, re-export or import as may be required after delivery to Licensee.

This Agreement is the parties’ entire agreement relating to its subject matter. It supersedes all prior or contemporaneous oral or written communications, proposals, conditions, representations and warranties and prevails over any conflicting or additional terms of any quote, order, acknowledgment, or other communication between the parties relating to its subject matter during the term of this Agreement. No modification to this Agreement will be binding, unless in writing and signed by an authorized representative of each party.

Specification for JEP 325: Switch Expressions

June 2018

5.6. Numeric Contexts

5.6.1. Unary Numeric Promotion

5.6.2. Binary Numeric Promotion

5.6.3 Switch Numeric Promotion

11.2.1. Exception Analysis of Expressions

11.2.2. Exception Analysis of Statements

14.1. Normal and Abrupt Completion of Statements

14.11. The switch Statement

14.11.1 Switch block

14.11.2 The switch block of a switch statement

14.11.3 Execution of a switch statement

14.15. The break Statement

14.16. The continue Statement

14.17. The return Statement

14.21. Unreachable Statements

15.1. Evaluation, Denotation, and Result

15.2. Forms of Expressions

15.6. Normal and Abrupt Completion of Evaluation

15.12.2.1. Identify Potentially Applicable Methods

15.12.2.5. Choosing the Most Specific Method

15.15 Unary Operators Expressions

15.25. Conditional Operator ? :

15.28. Constant Expressions

15.29. switch Expressions

15.29.1 The switch block of a switch expression

15.29.2 Execution of a switch expression

16.1.7. switch Expression

16.1.8 switch Expression

16.2.9. switch Statements

16.2.13. break, continue, return, and throw Statements

18.2.1. Expression Compatibility Constraints

18.5.2. Invocation Type Inference

18.5.4. More Specific Method Inference

Legal Notice

Notice

Trademarks

Disclaimer of Warranties

Limitation of Liability

Restricted Rights Legend

Report

General Terms

14.11. The `switch` Statement

14.11.2 The switch block of a `switch` statement

14.11.3 Execution of a `switch` statement

14.15. The `break` Statement

14.16. The `continue` Statement

14.17. The `return` Statement

15.25. Conditional Operator `? :`

15.29. `switch` Expressions

15.29.1 The switch block of a `switch` expression

15.29.2 Execution of a `switch` expression

16.1.7. `switch` Expression

16.1.8 `switch` Expression

16.2.9. `switch` Statements

16.2.13. `break`, `continue`, `return`, and `throw` Statements