1 Introduction

This paper proposes pattern matching for C++29. It is the next revision of [P2688R5], which was considered for C++26 at the February 2025 Hagenberg meeting but did not reach consensus for forwarding to CWG.

R6 is a substantial revision rather than merely a retargeting of [P2688R5] for C++29. It retains first-match semantics and recursive composition of patterns, while replacing let with ordinary declarations, adopting prefix match for statement and expression forms, making alternative matching explicit with braces, and requiring exhaustiveness and redundancy diagnostics.

2 The Proposal in Examples

Let’s start with examples with light commentary. It will be a good test for how intuitive the proposal is, without having to read the full specification. This is intentionally lighter than what would be a tutorial.

2.1 Using Pattern Matching

The following coin example is adapted from The Rust Programming Language book, Chapter 6.2:

enum class Coin { Penny, Nickel, Dime, Quarter };

int value_in_cents(Coin coin) {
  return match (coin) {
    case Coin::Penny => 1;
    //   ^^^^^^^^^^^  value pattern
    case Coin::Nickel => 5;
    case Coin::Dime => 10;
    case Coin::Quarter => 25;
  };
}

This is a match expression, so the expression in the selected handler provides its value. A value pattern such as Coin::Penny matches if the subject has the same value. Exhaustiveness checking is required in general. For an enum, every enumerator value is required to be covered. Therefore, omitting the Coin::Quarter case is ill-formed:

error: match expression is not exhaustive; example of a missing case: Quarter

Next, let’s consider a dice roll example from the same chapter:

int dice_roll();

void take_turn() {
  match (dice_roll()) {
    case 3 => add_fancy_hat();
    case 7 => remove_fancy_hat();
    case int roll => move_player(roll);
    //   ^^^^^^^^  declaration pattern
  }
}

This is a match statement, so the statement in the selected handler is executed. dice_roll() is evaluated exactly once. The declaration pattern (int roll) matches every other result and initializes roll from it.

If every result other than 3 or 7 should simply be re-rolled, its value can be ignored with a wildcard pattern (_):

match (dice_roll()) {
  case 3 => add_fancy_hat();
  case 7 => remove_fancy_hat();
  case _ => reroll();
  //   ^  wildcard pattern
}

Patterns can also be combined with or. An or-pattern tries its alternatives against the same subject from left to right and matches when one succeeds:

match (dice_roll()) {
  case 1 or 2 => lose_turn();
  //   ^^^^^^  or-pattern
  case 3 => add_fancy_hat();
  case 7 => remove_fancy_hat();
  case int roll => move_player(roll);
}

Suppose now that we roll two dice and return them as a std::pair:

std::pair<int, int> roll_two_dice();

match (roll_two_dice()) {
  case [1, 1] => snake_eyes();
  //   ^^^^^^  decomposition pattern
  case [6, 6] => boxcars();
  case [int r1, int r2] if (r1 == r2) => {
    play_doubles(r1);
  }
  case [int r1, int r2] => {
    move_player(r1 + r2);
  }
}

[P1, P2] is a decomposition pattern. It recursively matches the two elements. After a pattern matches, if there is an if guard present, the handler is taken if the guard evaluates to true. Otherwise, the next match case is considered.

Alternatively, a match can match two separately produced values directly:

match (dice_roll(), dice_roll()) {
  case [1, 1] => snake_eyes();
  case [6, 6] => boxcars();
  case [int r1, int r2] if (r1 == r2) => {
    play_doubles(r1);
  }
  case [int r1, int r2] => {
    move_player(r1 + r2);
  }
}

Multiple subjects form an unnamed type and are matched together.

Let’s shift gears and look at alternative types. Suppose our die may roll off the table, and its result therefore is a std::optional:

std::optional<int> try_dice_roll();

match (try_dice_roll()) {
  case { int roll } => move_player(roll);
  //   ^^^^^^^^^^^^  alternative pattern
  case {} => roll_again();
}

{ P } projects the int inside the optional, if present, and recursively applies P to it. In this example, P is the declaration pattern int roll. {} matches the optional’s empty state.

A std::variant can have several different alternatives:

using SearchResult = std::variant<File, Directory>;

void open(const SearchResult& result) {
  match (result) {
    case { const File& file } => open_file(file);
    case { const Directory& directory } => open_directory(directory);
  }
}

Each declaration pattern matches an alternative whose payload has the corresponding type and introduces a name for that payload in the handler.

A std::expected result can be matched similarly to a variant:

std::expected<int, std::string> parse_port(std::string_view text);

match (parse_port(text)) {
  case { int port } => connect(port);
  case { const std::string& message } => report(message);
}

Note that the value and error types of expected can be the same. std::expected<std::string, std::string> in particular comes up often in practice. In that case, named selectors can be used to distinguish the alternatives:

std::expected<std::string, std::string> read_file(std::string_view path);

auto result = read_file(path);

match (result) {
  case { .value: const auto& contents } => process(contents);
  //     ^^^^^^  named selector
  case { .error: const auto& message } => report(message);
}

A declaration pattern can use dynamic_cast semantics when applied to a polymorphic class subject.

struct Shape { virtual ~Shape() = default; };

struct Circle : Shape { double radius() const; };

struct Rectangle : Shape {
  double width() const;
  double height() const;
};

double compute_area(const Shape& shape) {
  return match (shape) {
    case const Circle& c => std::numbers::pi * c.radius() * c.radius();
    case const Rectangle& r => r.width() * r.height();
    case _ => throw std::invalid_argument("unknown shape");
  };
}

The wildcard covers other classes that may derive from Shape.

Patterns can also be used in boolean tests and control-flow conditions:

SearchResult result = search(path);

// boolean-yielding single-pattern test expression
bool is_file = match(result, case { const File& });

// pattern condition
if (case { const Directory& directory } = result) {
  open_directory(directory);
}

const File& is a declaration pattern with an omitted name. It tests whether the corresponding declaration could be initialized, but does not perform that initialization.

A single-pattern test produces bool whether the pattern matched or not. A pattern condition additionally makes names introduced by its pattern available in subsequent conditions and the successful branch.

2.2 Customizing an Alternative Type

The standard-library types above use std::alternative_traits. Your custom library alternative type can opt into the same protocol. Suppose my::Result<T, E> has an expected-like interface with has_value(), value(), and error().

The smallest useful specialization advertises its two projected types, identifies the active state via index(), and provides the projections for each state via get<>():

template <class T, class E>
struct std::alternative_traits<my::Result<T, E>> {
  static constexpr std::alternative_info alternatives[] = {^^T, ^^E};
  static constexpr bool has_residual_states = false;

  static constexpr std::size_t index(const my::Result<T, E>& result) noexcept {
    return result.has_value() ? 0 : 1;
  }

  template <std::size_t I, class Self>
  static constexpr decltype(auto) get(Self&& self) noexcept {
    if constexpr (I == 0) return std::forward<Self>(self).value();
    else if constexpr (I == 1) return std::forward<Self>(self).error();
    else static_assert(false);
  }
};

Each element of alternatives describes one state. Here, ^^T and ^^E construct alternative_info values that advertise projectable states with declared types T and E.

This is enough to support the alternative pattern { P } and exhaustiveness checking. The protocol operations on the right are illustrative rather than a specified lowering:

my::Result<int, std::string> number =
  read_number();

match (number) {
  case { int v } => {
    use(v);
  }
  case { const std::string& e } => {
    report(e);
  }
}

my::Result<int, std::string> number = read_number();

using AltTraits = std::alternative_traits<decltype(number)>;
switch (AltTraits::index(number)) {
  case 0: {
    int v = AltTraits::get<0>(number);
    use(v);
    break;
  }
  case 1: {
    const std::string& e = AltTraits::get<1>(number);
    report(e);
    break;
  }
}

The number of alternatives is the size of the AltTraits::alternatives array. has_residual_states records whether runtime states may exist outside that array. Its role in usefulness checking is discussed in Required and Residual Domains.

The name in { .name: P } is looked up in the return type of index(). We can change the return type of index() from std::size_t to an enum class:

enum class state : bool { value, error };

static constexpr state index(const my::Result<T, E>& result) noexcept {
  return result.has_value() ? state::value : state::error;
}

template <state State, class Self>
static constexpr decltype(auto) get(Self&& self) {
  if constexpr (State == state::value)
    return std::forward<Self>(self).value();
  else if constexpr (State == state::error)
    return std::forward<Self>(self).error();
  else static_assert(false);
}

With this, the user can now write named selectors. The corresponding protocol operations use state::value and state::error instead of numeric indices:

my::Result<std::string, std::string> file =
  read_file(path);

match (file) {
  case { .value: const auto& contents } => {
    process(contents);
  }
  case { .error: const auto& message } => {
    report(message);
  }
}

my::Result<std::string, std::string> file = read_file(path);

using AltTraits = std::alternative_traits<decltype(file)>;
switch (auto idx = AltTraits::index(file)) {
  using state = decltype(idx);
  case state::value: {
    const auto& contents = AltTraits::get<state::value>(file);
    process(contents);
    break;
  }
  case state::error: {
    const auto& message = AltTraits::get<state::error>(file);
    report(message);
    break;
  }
}

The complete protocol also describes empty states, canonical value states, residual states, templated names, and open alternative types. Those facilities are specified in The alternative_traits Protocol.

3 Motivation and Scope

C++ provides the operations underlying pattern matching through separate language and library facilities: switch for integral and enumeration values, if for arbitrary predicates, structured bindings for decomposing tuples, std::visit for selecting alternatives of std::variant, and dynamic_cast for class hierarchies. These facilities do not compose declaratively. Code that needs more than one generally spreads its tests, decompositions, declarations, and control flow across several statements.

This proposal brings those operations into one pattern language used by selections, tests, and conditions. A pattern describes what a value looks like and introduces names for the relevant pieces. A match selection dispatches to the corresponding handler when that pattern succeeds.

The changes in R6 have two primary goals:

• using familiar C++ syntax such as match (E) { /* cases */ } and ordinary declarations, instead of dedicated syntax such as let and ? pattern;
• increasing safety by requiring diagnostics for non-exhaustive selections and redundant cases.

The design also preserves the following directions from earlier EWG discussions:

• Patterns compose recursively rather than forming a chain of separate matching operations. EWG expressed a preference for this direction at the Kona meeting in November 2022.
• Pattern matching is available generally in the language. At the July 7, 2021 EWG teleconference, EWG expressed support for matching outside a dedicated inspect construct (match in this paper).
• Expressions retain their ordinary meaning. Earlier EWG feedback emphasized that declarations should visibly introduce names and that an identifier should not silently declare or shadow a variable merely because it appears in a pattern.

[P2688R5] used let to make name introduction explicit. This paper retains that distinction between declarations and expressions while using ordinary declaration syntax to express type, ownership, references, and forwarding. A bare identifier remains an expression that refers to an existing name.

The library portion introduces a new customization point, std::alternative_traits, and standard specializations for nullable, alternatives, type-erased, comparison-category, and calendar types. The alternative_traits Protocol presents the protocol and representative specializations. The full set of definitions will be a separate paper targeted for LEWG.

Extractors, range patterns, named-member decomposition, matching types themselves as subjects, and pattern combinators such as and and not remain future work.

4 Design Overview

The proposal introduces several contexts where pattern matching can be used.

Let’s start with match selection, both statement and expression forms:

match (subjects) {
  case pattern => statement
  // ...
}

auto result = match (subjects) {
  case pattern => expr-or-braced-init-listopt ;
  // ...
};

While a match-selection-statement can simply have a compound-statement on the right of =>, a match-selection-expression continues to rely on [P2806R5] (do expressions) to do statement things.

A match selection considers its cases in source order and selects the first case whose pattern and guard, if present, succeed. Every match selection must be exhaustive, and every case must be useful.

A match-test-expression is a boolean expression that is ill-formed if the pattern is not viable for the subject(s). Otherwise, it produces true if the pattern matches and false if it does not. It does not export names.

match(subjects, case pattern)

It can be used wherever boolean expressions can be used, including requires clauses.

A pattern-condition is a condition and can appear anywhere condition can appear, except within a switch:

if (case P = E) {
  // ...
}

while (case P = E) {
  // ...
}

for (init; case P = E; incr) {
  // ...
}

A pattern condition has the same matching result as match(subject, case pattern), but keeps its hidden subject alive through the enclosing control statement, including an else branch.

Pattern conditions participate in a left-to-right && chain. Names introduced by one condition are available to subsequent conditions and the successful controlled statement:

if (case { const Directory& directory } = search(path) &&
    should_open(directory)) {
  open_directory(directory);
}

The patterns proposed are:

Every pattern has one current subject. A decomposition pattern [P1, /* ... */, Pn] passes each element of its subject as the subject for the corresponding Pi. An alternative pattern { P } selects an alternative and passes its projection as the current subject for P. Matching then continues recursively. Parentheses and or-patterns compose patterns without changing the current subject.

A declaration pattern always applies directly to its current subject; it does not implicitly project an alternative. Braces request alternative projection. Runtime polymorphic class matching also applies a declaration pattern directly to its current subject rather than selecting a stored alternative.

A decomposition pattern can contain one arity-inferred pack. A bare ... ignores the corresponding elements, while auto&& ...elements introduces a local pack name. An enclosing expression or type pack instead expands to a fixed number of subpatterns.

A decomposition pattern uses the structured-binding protocol to obtain its elements. The language directly supplies the matching domains for bool, enumeration types, and pointers, including nullable projection for pointers. For class types, braces explicitly request an alternative interface whose states, selectors, and projections are described by std::alternative_traits.

A single top-level subject expression supplies the initial current subject directly. Multiple subject expressions form an unnamed product type, and a decomposition pattern matches its elements. Each subject expression is evaluated exactly once.

An ordinary declaration introduces a new name. Without one, an identifier names an existing entity:

constexpr int x = 42;

match (E) {
  case x =>      // match against existing `x`
  case auto x => // introduce a new `x`
}

Declaration patterns do not accept general implicit conversion. Ordinary declaration matching admits standard conversion sequences of Exact Match rank and direct derived-to-base reference binding. If that does not apply, a class declaration can use the corresponding pointer-form dynamic_cast against a polymorphic class subject. Once the pattern matches, a named declaration is copy-initialized from the current subject. Omitting the name still requires that initialization to be well-formed, but does not perform it.

5 Pattern Matching Constructs

5.1 Syntax Overview

The following is a simplified, informal overview of the proposed grammar.

First, the new constructs enter the existing grammar at these locations:

selection-statement:
    if constexpropt ( init-statementopt condition ) statement
    // ...
    switch ( init-statementopt condition ) statement
+   match-selection-statement

primary-expression:
    literal
    // ...
    splice-expression
+   match-selection-expression
+   match-test-expression

condition:
    expression
    condition-declaration
+   pattern-condition-chain

Next, the grammar of the various match constructs:

match-selection-statement:
    match constexpropt ( expression-list ) {
        match-preamble-declaration-seqopt
        attribute-specifier-seqopt case pattern guardopt => statement
        // ...
    }

match-selection-expression:
    match constexpropt ( expression-list ) trailing-return-typeopt {
        match-preamble-declaration-seqopt
        attribute-specifier-seqopt case pattern guardopt => match-selection-expr-handler
        // ...
    }

match-test-expression:
    match( expression-list , case pattern )

match-selection-expr-handler:
    expr-or-braced-init-listopt ;
    ! return expression ;
    static_assert-declaration
    jump-statement

match-preamble-declaration:
    using-declaration
    using-enum-declaration
    using-directive
    alias-declaration
    namespace-alias-definition
    static_assert-declaration

guard:
    if ( init-statementopt condition )

Next, the syntax of the recursively composable patterns:

pattern:
    or-pattern

or-pattern:
    primary-pattern
    or-pattern || primary-pattern

primary-pattern:
    _
    inclusive-or-expression
    declaration-pattern
    ( pattern )
    [ decomposition-pattern-listopt ]
    { pattern }
    { type-id : pattern }
    { type-constraint : pattern }
    { named-selector : pattern }
    { named-selector }
    { }

named-selector:
    . identifier
    . simple-template-id

decomposition-pattern-list:
    decomposition-pattern-element
    decomposition-pattern-list , decomposition-pattern-element

decomposition-pattern-element:
    pattern
    ...
    inclusive-or-expression ...

Within a decomposition pattern, a bare ... infers its arity from the subject. A placeholder declaration pack such as auto&& ...xs or auto&& ... does the same. At most one arity-inferred element is permitted. An expression pack such as xs..., or a declaration whose type contains an unexpanded pack such as Ts..., instead expands that enclosing template pack into a fixed number of patterns. A concrete declaration such as Widget ... does not form a pack and is ill-formed.

Finally, the pattern condition chain:

pattern-condition:
    case pattern = inclusive-or-expression

pattern-condition-chain:
    pattern-condition-operand
    pattern-condition-chain && pattern-condition-operand

pattern-condition-operand:
    inclusive-or-expression
    pattern-condition

match in these productions denotes an identifier token whose spelling is match; it is not reserved as a keyword. A pattern-condition-chain contains at least one pattern-condition. The remaining overlap with ordinary C++ syntax is resolved as described in Contextual Parsing of match.

5.2 Match Selection Statements and Expressions

In a statement-or-expression context, the prefix introduces a match selection statement. Otherwise, in an expression context, it introduces a match selection expression.

The parenthesized expression-list is non-empty. With one expression, it selects that expression directly. With more than one, it forms the unnamed product described in Multiple Subjects and Single-Pattern Tests. A pack expansion keeps the product interpretation even when an instantiation expands it to zero or one element.

match constexpr requires the tests and guards used to select a case to be constant expressions and discards the unselected handlers. Its detailed rules are described in match constexpr.

The optional preamble is a sequence of using-declarations, using-enum-declarations, using-directives, alias-declarations, namespace-alias-definitions, and static_assert-declarations. It must appear before the first case. Each declaration is in scope from its point of declaration through the remainder of the match selection. A case does not make its names visible to the preamble or to another case.

No semicolon follows the closing brace of a match selection statement. Parentheses force expression form where a match selection statement would otherwise be recognized.

For example:

// expression
(match (value) -> int {
  case 0 => 1;
  case _ => -1;
});

// statement
match (value) {
  case 0 => record_zero();
  case _ => record_other();
}

5.3 Handlers and Result Types

A match selection statement has no result type, and each handler is any statement. This includes declaration statements, compound statements, control statements, and jump statements. An expression used as a statement has its value discarded in the ordinary way.

For a match selection expression, a handler can be:

• an expr-or-braced-init-list followed by ;;
• a null statement, written => ;;
• a static_assert declaration;
• a jump statement where that action is valid;
• a non-returning expression, written not return expression.

The participating handlers need a consistent result type unless an explicit trailing return type is provided. A null handler and a successful static_assert handler contribute void. A jump statement, a not return handler, and a handler discarded by match constexpr do not participate in result type deduction.

[P2806R5] (do expressions) would be used with match when a handler needs a statement block that yields a value:

return match (var) -> int {
  case { int x } => do {
    log(x);
    do_return x;
  };
  case _ => -1;
};

Result deduction is performed separately for each enclosing specialization:

constexpr auto result(auto value) {
  return match (value) {
    case int integer  => integer;
    case string& text => text.size();
    case _ => static_assert(false, "unsupported type");
  };
}

The assertion is instantiated only for a specialization not matched by any of the earlier cases.

5.4 Guards

A match case guard is introduced by if and requires parentheses. It can contain an init-statement and a condition declaration:

match (value) {
  case const Widget& widget if (auto status = validate(widget); status.ok()) => {
    process(widget, status);
  }
  case _ => reject();
}

A name introduced by a match case’s pattern is visible in that case’s guard and handler, and nowhere else. A guard init-statement declaration is visible in the guard condition and selected handler. Neither kind of declaration is visible in later cases.

Guarded cases do not contribute to exhaustiveness, even when a guard is manifestly true. This keeps coverage independent of arbitrary constant evaluation and avoids changing exhaustiveness when a guard expression is refactored.

5.5 Single-Pattern Tests and Pattern Conditions

A single-pattern test is:

match(E, case P)

The case keyword marks the final comma-separated operand as a pattern rather than another subject. The expression does not export names. A non-viable pattern makes the expression ill-formed rather than false. In a dependent context, viability is checked after substitution. Strict Viability discusses this choice and the corresponding use of a requires-expression for detection.

For a viable pattern, the expression evaluates its subject once and produces true if the pattern matches and false otherwise.

Pattern conditions are used in if, while, and traditional for statements:

if (case pattern = subject) statement
while (case pattern = subject) statement
for (init-statement; case pattern = subject; expression) statement

Pattern conditions can participate in a left-to-right built-in conjunction:

if (ready && case [int x, int y] = first &&
    x < y && case { string text } = second && !text.empty()) {
  use(x, y, text);
} else {
  // x, y, and text are not in scope
}

Names introduced by one pattern condition are visible in later && elements and the successful controlled statement, but not in else. A pattern name is introduced before its subject is parsed, so using the same name on the right is self-initialization:

int x = 42;

void test() {
  if (case int x = x) { }   // error: self-initialization
  if (case int x = ::x) { } // explicitly names the global object
}

The first top-level = separates the pattern from the subject. This is unambiguous because an assignment expression is not a pattern. An if pattern guard is not accepted in this form; a later && condition is the guard.

if constexpr (case P = E) also requires P to be viable. The constexpr applies after the condition has been formed; it does not turn the pattern condition into a detection operation.

5.6 Contextual Parsing of match

match remains an identifier and can already name a type, function, or object. A parser therefore recognizes a prefix match selection tentatively and returns to ordinary C++ parsing if the prefix does not select the match grammar. This classification does not build the subject, perform overload resolution, or emit diagnostics.

For valid programs, the recognition flow is:

start at 'match'
|
+- next token is 'constexpr' => match selection
+- next token is not '('     => ordinary parsing 
`- scan through the balanced non-empty '( tokens )'
   |
   +- no matching ')' => ordinary parsing
   +- next token is '{'
   |  |
   |  +- in expr-only context => match selection expression
   |  `- in stmt-or-expr context
   |     +- next token is 'case', '[[', or a preamble declaration
   |     |  => match selection statement
   |     +- 'match' is not a type name => match selection statement
   |     `- tentatively parse '( E )' as a declarator
   |        |
   |        +- is a declarator => ordinary parsing
   |        +- not a declarator => match selection statement
   |
   +- next token is '->'
   |  |
   |  +- in stmt-or-expr context => ordinary parsing
   |  `- in expr-only context
   |     +- tentatively parse type-id followed by '{' => match selection expression
   |     `- otherwise => ordinary parsing
   |
   `- anything else => ordinary parsing

This algorithm is more complicated to describe than it is likely to be in practice. A survey of Chromium and LLVM found no types named match and hundreds of functions named match, mostly in LLVM matching libraries. It found no existing statement or expression using either match-shaped match (...) { or match (...) -> syntax. The ordinary function calls leave the classifier before reaching the difficult declaration and trailing-result type cases.

The tentative declarator branch preserves existing declarations such as:

struct match { match(int); };

match first(0);
match (second) { 0 };

In an expression-only context, match (subject) { is unambiguously a match selection expression. At the start of a statement, the body introducer and ordinary lookup distinguish it from the declaration case. A single [ does not commit to a match selection because a braced initializer can begin with a lambda. [[ does commit because it begins an attributed match case.

A trailing result type is recognized only when a complete type-id is followed by {. This preserves ordinary member access:

return match (value) -> Result { case _ => Result{}; }; // match selection
return match(value)->result;                            // member access

The single-pattern form is simpler. A top-level comma followed by case separates the subject list from the pattern:

match(value, case a * b) // expression pattern
match(value, case T * x) // declaration pattern if T names a type
match(value, case a) * b // multiplication outside the test

6 Patterns

6.1 Wildcard Pattern

_

A wildcard pattern always matches any subject.

The choice of _ is discussed in Wildcard and Value Patterns.

6.2 Value and Predicate Patterns

inclusive-or-expression

An expression pattern E has to be constant: a literal, constexpr variable, enumerator, function name, or constexpr function object, for example. Its value is not recomputed each time the case is attempted. Matching proceeds as follows:

1. If std::alternative_traits advertises E as a state, test its discriminator.
2. Otherwise, if bool(subject == E) is well-formed, use that comparison.
3. Otherwise, if bool(E(subject)) is well-formed, invoke E as a predicate.
4. Otherwise, the pattern is not viable.

Equality has priority over invocation, so an ordinarily comparable constant remains a value pattern even if its type also has a call operator.

constexpr int not_found = 404;

match (status) {
  case 200 => success();
  case not_found => report_missing();
  case _ => report_failure(status);
}

A closed alternative type can advertise constants as its complete domain. The proposed specialization for std::partial_ordering, for example, makes this selection exhaustive without calling operator==:

std::string_view describe(std::partial_ordering order) {
  return match (order) {
    case std::partial_ordering::less => "less";
    case std::partial_ordering::equivalent => "equivalent";
    case std::partial_ordering::greater => "greater";
    case std::partial_ordering::unordered => "unordered";
  };
}

A named function can provide a predicate pattern:

constexpr bool is_at_least_five(int subject) {
  return subject >= 5;
}

match (value) {
  case is_at_least_five => large_value();
  case _ => smaller();
}

Predicate patterns are particularly useful with classification APIs such as reflection:

consteval std::string_view classify(std::meta::info entity) {
  return match (entity) {
    case std::meta::is_type => "type";
    case std::meta::is_variable => "variable";
    case std::meta::is_function => "function";
    case _ => "other";
  };
}

static_assert(classify(^^int) == "type");

A predicate does not contribute to exhaustiveness. The predicate object is a constant, but its result is generally a runtime property.

The use of ordinary expressions for value and predicate patterns is discussed in Wildcard and Value Patterns.

6.3 Declaration Patterns

A declaration pattern first tests whether its declaration is applicable to the current subject. If the pattern matches and the declaration has a name, it is copy-initialized from that subject:

case int value
case const Widget& reference
case auto&& forwarded
case int Owner::* member
case int (*function)()
case int (&array)[5]
case std::integral auto integer
case auto&& [first, second]

A declared name is introduced immediately for lookup, but using it from the same pattern is ill-formed. Pattern names are results of a successful match and are available to its guard and handler; they are not inputs to other parts of the pattern.

Declaration patterns generally use the ordinary declaration-versus-expression disambiguation. The exception is that a parenthesized declarator is accepted only when an array or function suffix makes the parentheses structurally meaningful. Thus T(value), bool(value), and auto(value) are expression patterns, while int (*function)() remains a declaration pattern. The grammar also admits structured-binding declarations, but not storage-class forms such as static and thread_local. The disambiguation is discussed further in Declaration-Pattern Syntax.

We generally restrict applicability to exact-match standard conversion sequences: identity, lvalue transformations, qualification adjustment, and function pointer conversion. A declaration of reference type can additionally bind directly through a derived-to-base conversion to a base-class subobject of the current subject. Promotions, other conversion-rank standard conversions, and user-defined conversions do not make a declaration pattern applicable.

The derived-to-base case is ordinary static reference binding. It does not require a polymorphic type, perform a runtime test, or permit by-value slicing.

If static declaration matching does not apply, a class declaration can use the runtime polymorphic cast described in Polymorphic Class Matching. Runtime polymorphic matching does not apply to pointer declarations; matching a pointee requires the explicit nullable projection described in Pointer Subjects.

Cases remain source-ordered. Overload ranking defines the conversions admitted by declaration matching; it does not reorder cases as an overload set would.

6.3.1 Applicability Versus Failed Initialization

There are three possible outcomes for a named declaration pattern:

1. It is not applicable to its current subject.
2. It is applicable and initialization succeeds.
3. It is applicable, but the selected initialization is ill-formed.

Reference binding can produce (1):

template <class T>
int classify(variant<T> value) {
  return match (std::move(value)) {
    case { T& reference } => 1;
    case _                => 2;
  };
}

For an ordinary variant<T>, projecting from std::move(value) produces T&&. The T& declaration is not applicable, so its case is omitted for that specialization and the wildcard is selected.

Only (1) can discard a case in a dependent match. For (3), the declaration is applicable but its initialization is an error:

struct Job {
  Job(Job&&) = default;
  Job(const Job&) = delete;
};

void process(auto&& value) {
  match (std::forward<decltype(value)>(value)) {
    case Job job => execute(std::move(job));
    case _      => report_unsupported();
  }
}

Job job;
process(Job{}); // moves
process(job);   // error: selected Job initialization requires a copy

Silently choosing the wildcard case in the second call would turn an ownership error into different program behavior.

6.3.2 Omitted-Name Declaration Patterns

A declaration pattern can omit its identifier. It has the same applicability and well-formedness requirements as the corresponding named declaration, including access, deleted constructors, and reference binding, but does not perform the initialization:

case Widget          // checks whether `Widget _` would be valid
case Widget _        // initializes and destroys an ignored object
case const Widget&   // checks whether the reference could bind
case std::integral auto
case [auto&&, auto&&]

Because the initialization is not evaluated, no object is created or destroyed, the subject cannot be moved from, and the hypothetical operation does not contribute to the exception specification. An invalid initialization is nevertheless a hard error rather than a failed match.

void and cv-void are explicitly supported. This matters for dependent void expressions and expected<void, E> projections.

The identifier can also be omitted from a constrained placeholder declaration:

case std::integral auto
case std::ranges::viewable_range auto&&

6.4 Parenthesized Pattern

( pattern )

A parenthesized pattern groups any pattern. It has the same matching semantics and introduces the same names as its nested pattern.

match (direction) {
  case (north or south) => vertical();
  case _ => horizontal();
}

Parentheses around _ or [P1, /* ... */, Pn] are not normally useful when written directly, but permit uniform substitution and future composition with other pattern operators.

The reasons for general pattern grouping are discussed in Parentheses and Or-pattern Syntax.

6.5 Or-pattern

pattern or pattern

An or-pattern applies every subpattern to the same subject from left to right and succeeds on the first match:

match (direction) {
  case Direction::north or Direction::south => vertical();
  case Direction::east or Direction::west   => horizontal();
}

It composes recursively, so several values can share one projection:

match (response) {
  case { .error: timeout or cancelled } => retry();
  case _ => fail();
}

The punctuator || has the same grammatical meaning as the alternative token or. Parentheses still group a pattern, so matching the result of an ordinary logical expression requires an unambiguous expression spelling:

case first or second       => either_pattern();
case (first or second)     => grouped_pattern();
case bool(first || second) => boolean_expression();

Every subpattern must introduce the same ordered names and pack structure. The corresponding declarations need not have the same type. The selected subpattern determines their types, and the declaration, guard, and handler are instantiated together for that subpattern:

match (value) {
  case { int value } or { const std::string& value } => use(value);
}

Exactly one subpattern’s named declarations are initialized. If its guard fails, matching continues with the next source case, not with another subpattern of the same or-pattern.

The choice of or and its interaction with expression syntax are discussed in Parentheses and Or-pattern Syntax.

6.6 Decomposition Patterns

[P1, /* ... */, Pn] decomposes the current subject using the structured-binding rules, then matches each component recursively:

match (point) {
  case [0, 0] => origin();
  case [int x, 0] => on_x_axis(x);
  case [0, int y] => on_y_axis(y);
  case [int x, int y] => elsewhere(x, y);
}

Elements are forwarded as the current subjects of their nested patterns with the correct cv-qualifications and value categories. This is discussed further in Decomposition and Forwarding.

Empty decomposition is the zero-element structural pattern:

case [] => empty_product();

6.6.1 Packs

One arity-inferred subpattern pack is permitted:

case [auto&& first, auto&& ...middle, auto&& last]
case [auto&& first, auto&& ..., auto&& last]
case [auto&& first, ..., auto&& last]

The first form introduces a local pack name. The second is an omitted-name placeholder declaration pack, following ordinary parameter syntax such as void f(auto&&...); it checks each declaration but performs no initialization. A bare ... is a wildcard pack and ignores an arity-inferred sequence of elements. This is essentially the pack version of the wildcard pattern _. Each pack can be empty, and its size is the decomposition arity minus the fixed prefix and suffix. These forms are decomposition-list elements rather than patterns in their own right, so they cannot be parenthesized or used outside a decomposition pattern. The same restriction applies to a fixed expression or type expansion such as Values... or Types....

An enclosing expression pack expands to a fixed number of value patterns:

template <int... Values>
void classify(const auto& tup) {
  match (tup) {
    case [Values...] => exact_sequence();
    case _ => different();
  }
}

An enclosing type pack similarly expands to a fixed number of omitted-name declaration patterns:

template <typename... Types>
void classify(const auto& tup) {
  match (tup) {
    case [Types...] => typed_sequence();
    case _ => different();
  }
}

Each expanded declaration checks its corresponding element without performing the initialization. An omitted-name declaration pack whose type contains no unexpanded template pack, such as [Widget ...], is not proposed. A future revision can add that arity-inferred form without changing existing programs.

An or-pattern can combine complete decomposition patterns containing packs, but cannot combine a pack element itself:

case [0, auto&& ...values] or [auto&& ...values, 0] => use(values...);
case [auto&& ...values or _] => use(values...); // error

Declaration patterns can themselves contain structured-binding packs:

case auto [...elements] => (... + elements);

The declaration, guard, and handler share a dedicated case scope where the pack can be expanded.

6.7 Alternative Pattern

{ pattern }
{ type-id : pattern }
{ type-constraint : pattern }
{ . identifier : pattern }
{ . identifier }
{ . simple-template-id : pattern }
{ . simple-template-id }
{ }

For an alternative type, braces select from the alternatives advertised by that type. The nested pattern then applies normally to the selected projection.

• { P } considers each projectable state and applies P to its projection.
• { T: P } considers each projectable state whose advertised alternative type is exactly T, then applies P to the selected projection. Repeated alternatives are considered independently. Selection is by the exact advertised type; T is not itself a declaration pattern.
• { C: P }, where C is a type-constraint, considers each projectable state whose declared alternative type satisfies C, then applies P to its projection.
• { .name: P } selects a named state and applies P to its projection.
• { .name } selects a named state without requiring its projection.
• A provider can expose parameterized names. For example, variant provides .index<I> for each declared index I; { .index<I>: P } applies P to that alternative’s projection, while { .index<I> } selects the state without requiring a projection.
• {} matches an advertised state for which no projection exists.

optional<int> value;

match (value) {
  case { int integer } => use(integer);
  case {} => empty();
}

expected<int, Error> result;

match (result) {
  case { .value: int value } => use(value);
  case { .error: Error& error } => report(error);
}

Type selectors distinguish alternatives when their behavior differs. When alternatives share behavior, the selectors can be omitted and one nested pattern can cover every applicable projection:

variant<tuple<int, int>, pair<int, int>> value;

match (value) {
  case { tuple<int, int>: auto& [x, y] } => use_tuple(x, y);
  case { pair<int, int>: auto& [x, y] } => use_pair(x, y);
}

variant<tuple<int, int>, pair<int, int>> value;

match (value) {
  case { auto& [x, y] } => use_product(x, y);
}

The protocol for closed and open alternative types is described in The alternative_traits Protocol. The syntax and alternatives considered are discussed in Alternative Projection and Polymorphic Casts.

7 Polymorphic Class Matching

7.1 Static Matching and Runtime Polymorphic Casts

A declaration pattern first tries static declaration matching: an exact-match standard conversion, or direct derived-to-base binding for a reference declaration. If that does not apply, a class declaration can apply the corresponding pointer-form dynamic_cast to a polymorphic class subject:

void draw(Shape& shape) {
  match (shape) {
    case Circle& circle       => draw_circle(circle);
    case Triangle& triangle   => draw_triangle(triangle);
    case Rectangle& rectangle => draw_rectangle(rectangle);
    case _                    => draw_unknown(shape);
  }
}

This includes casts to public derived targets, virtual inheritance, pointer adjustment, and valid cross-casts. A failed cast is a non-match. After a successful cast, the declaration’s cv/ref spelling has its ordinary effect: Circle& binds the adjusted object, while Circle copies or moves from it. auto&& exactly matches the current Shape subject; it does not somehow acquire the unknown most-derived type.

This is an open-world operation. If Square derives from Rectangle in another translation unit or shared library, a Square passed as Shape& must still match Rectangle&. Comparing exact dynamic types or vtable pointers is not enough. Listing every currently known derived class is not exhaustive, so a base-class or wildcard fallback is still required.

A generic declaration can consequently be exact in one instantiation and a runtime-checked polymorphic cast in another:

void dispatch(auto& value) {
  match (value) {
    case Circle& circle => use(circle);
    case _              => fallback(value);
  }
}

Circle circle;
dispatch(circle);                       // ordinary exact binding
dispatch(static_cast<Shape&>(circle));  // runtime polymorphic cast succeeds

This may seem surprising, but a generic use of typeid similarly changes from static to dynamic behavior based on its instantiated operand type. typeid(expression) observes the dynamic type only when the expression is a glvalue of polymorphic class type:

const std::type_info& get_type_info(auto& value) { return typeid(value); }

int integer;
Circle another_circle;
get_type_info(integer);                              // static type `int`
get_type_info(static_cast<Shape&>(another_circle));  // dynamic type `Circle`

A generic function can constrain the static types that it accepts:

void dispatch_statically(auto& value) {
  match (value) {
    case std::same_as<Circle> auto& circle => use(circle);
    case _                                 => fallback(value);
  }
}

The constrained placeholder deduces Circle from a Circle& subject and Shape from a Shape& subject. The latter fails the constraint rather than requesting a runtime polymorphic cast.

Matching a type directly is discussed as a possible future extension.

7.2 Pointer Subjects

The same rule does not work for pointers. Consider an ordinary generic pointer match:

template <class T>
int classify(T* pointer) {
  return match (pointer) {
    case int* value    => value ? 1 : 2;
    case double* value => value ? 3 : 4;
    case _             => 5;
  };
}

This is static dispatch on T. classify<int>(nullptr) should select the int* case and initialize value with a null pointer.

Now what should Circle* mean when the subject is a Shape*? dynamic_cast<Circle*>(pointer) returns null when the object is not a Circle, but it also returns null when pointer is null. If that is a successful match, we enter a Circle* case with a null pointer. If it is a failed match, an exact Shape* declaration and a runtime-checked Circle* declaration behave differently for null despite looking the same. In a template, the same pattern could also change from static type selection to a nullable runtime test as T changes.

We therefore do not perform runtime polymorphic casts from one pointer type to another. Pointer declarations keep their ordinary exact-match behavior. To test the pointee’s runtime type, first match the non-null state and then match the resulting object:

void draw_shape(Shape* shape) {
  match (shape) {
    case {}                  => null_shape();
    case { Circle& circle }  => draw_circle(circle);
    case { Square& square }  => draw_square(square);
    case { Shape& unknown }  => draw_unknown(unknown);
  }
}

The braces above only perform the pointer’s null/non-null projection. Circle& then matches the resulting Shape& using the ordinary polymorphic object rule. There is no special pointer-plus-polymorphism operation. If the pointer is itself stored inside another alternative type, both projections are visible:

variant<Shape*, int> value;

match (value) {
  case { { Circle& circle } } => draw_circle(circle);
  case { int integer }        => use(integer);
  case _                      => other();
}

For a known Shape* subject, a bare Circle* pattern is not an exact match and is ill-formed. In a dependent match it follows the general rules for a potentially applicable declaration case; it does not acquire runtime polymorphic pointer-cast semantics:

template <class T>
int match_pointer(T* pointer) {
  return match (pointer) {
    case Circle* circle => 1;
    case _              => 0;
  };
}

Circle circle;
match_pointer(&circle);                    // 1: exact Circle* declaration
match_pointer(static_cast<Shape*>(&circle)); // 0: no polymorphic pointer cast

This difference is intentional. { Circle& } asks about the runtime type of the pointee. References do not have the null problem because a reference always denotes an object.

8 Alternative Matching

8.1 Alternative Projection

For a non-polymorphic type, a declaration pattern has only its normal declaration meaning. With a variant, matching against a auto&& name therefore binds the whole variant. Braces project an alternative which is then recursively matched by the pattern within.

void consume_whole(variant<int, string>&);

void consume_payload(int&);
void consume_payload(string&);

variant<int, string> value;

match (value) {
  case auto&& whole => consume_whole(whole);
}

match (value) {
  case { auto&& payload } => consume_payload(payload);
}

The auto&& payload is instantiated with int and string.

The projection of the alternative being performed by the braces can be illustrated like this:

match (var) {
  case { P1 } => E1;
  case { P2 } => E2;
}

std::visit([](auto&& alt) {
  match (FWD(alt)) {
    case P1 => E1;
    case P2 => E2;
  }
}, var);

On the right, std::visit explicitly projects the alternative and match applies P1 and P2 directly to that projection. Braces perform both steps without introducing a library call or requiring the user to write the generic visitor.

8.2 Closed Alternative Types

For a closed alternative type, { P } considers every projectable state for which P is viable. At runtime, it tests the active state and uses the corresponding case instantiation.

The match inside the generic lambda above is dependent. A non-dependent closed type has the additional requirement that each case be capable of matching at least one advertised projection:

variant<int, std::string> value;

match (value) {
  case { int i }         => use(i);
  case { std::string s } => use(s);
  case { double d }      => use(d); // error: matches no projectable state
}

The same case in a match on variant<Ts...> remains potentially useful and is simply omitted from a specialization whose alternatives do not include double:

template <class... Ts>
void dependent_projection(variant<Ts...> value) {
  match (value) {
    case { int i }         => use(i);
    case { std::string s } => use(s);
    case { double d }      => use(d);
  }
}

dependent_projection(variant<int, std::string>{42}); // `double` case omitted
dependent_projection(variant<int, double>{2.5});     // `string` case omitted

A pattern may cover more than one index:

variant<int, int> value;

match (value) {
  case { const int& integer } => use(integer); // covers both indices
}

Qualification adjustments can also make one declaration apply to several alternatives. Usefulness is checked against the actual indices and nested value patterns, not just the type written in the source.

{ auto&& value } is the generic case. Its declaration, guard, and handler are checked separately for every remaining alternative type.

A projectable state can even have declared type void. This is useful to match the alternatives of an std::expected<void, E>:

expected<void, Error> result;

match (result) {
  case { void } => completed();
  case { Error& error } => report(error);
}

8.3 Named and Non-Projectable States

Named projection chooses an advertised state before matching its projection:

expected<int, Error> result;

match (result) {
  case { .value: int value }    => use(value);
  case { .error: Error& error } => report(error);
}

{} matches a state that has no value to project:

optional<int> value;

match (value) {
  case { int integer } => use(integer);
  case {}              => empty();
}

expected<T, E> is modeled as value/error, not value/empty. Both states are projectable.

Raw pointers have a built-in null/non-null alternative model:

Widget* pointer = find_widget();

match (pointer) {
  case { Widget& widget } => use(widget);
  case {}                 => absent();
}

nullptr and nullopt retain ordinary value-pattern syntax. A closed specialization can identify either value as the canonical label of an advertised state. Such a pattern tests the subject’s active state rather than calling operator==, and participates in exhaustiveness analysis. The pointer and optional models do so: nullptr and {} cover the same pointer state, and nullopt and {} cover the same optional state.

The visit comparison above covers only advertised alternatives. The rare valueless state of variant has no projection syntax and is not required for exhaustiveness. A match can handle it with a whole-subject case; visit has its own behavior:

match (value) {
  case auto&& whole if (whole.valueless_by_exception()) => recover();
  case { auto&& alternative } => use(alternative);
}

8.4 Open Alternative Types and any

An open alternative type such as any cannot enumerate all of its possible types. It still uses braces to make the runtime access explicit:

any value;

match (value) {
  case {}                     => empty();
  case { int: auto& integer } => use(integer);
  case { const string& text } => print(text);
  case _                      => unknown();
}

• A bare case int integer does not look inside the any; it tries to match the any object itself and fails.
• { T: P } calls try_cast<T>(a).
• A direct declaration such as { const string& text } calls try_init<const string&>(a).
• {} calls the optional has_value operation and matches when it returns false.
• { auto&& value } and { _ } are ill-formed because there is no C++ type for a generic projection of the open remainder.

9 The alternative_traits Protocol

We need one protocol for closed alternative types such as variant and another form of the same protocol for open alternative types such as any. The name alternative_traits, as well as some of its member names, remains open to change.

9.1 Closed Indexed Protocol

A complete closed customization for the expected-like my::Result<T, E> looks as follows:

template <class T>
struct alternative_traits;

struct alternative_info {
  meta::info info;
  bool empty;

  consteval alternative_info(meta::info info = {}, bool empty = false);
};

template <class T, class E>
struct alternative_traits<my::Result<T, E>> {
  static constexpr alternative_info alternatives[] = {^^T, ^^E};
  static constexpr bool has_residual_states = false;

  enum class state : bool { value, error };

  static constexpr state index(my::Result<T, E> const& value) noexcept {
    return value.has_value() ? state::value : state::error;
  }

  template <state State, class Self>
  static constexpr decltype(auto) get(Self&& self) {
    if constexpr (State == state::value)
      return std::forward<Self>(self).value();
    else
      return std::forward<Self>(self).error();
  }
};

The alternatives array describes the required state domain. Element I describes state I. Its info is one of:

• null, for a state selected only by index or name;
• a reflected type, for a projectable state selected by { T: P }; or
• a reflected constant value, for a state selected by that value pattern.

The alternative_info constructor canonicalizes reflected constant values. A type can be void. A typed state requires a compatible projection and must have empty == false. A state with null info can also provide a projection for a named or indexed selector. A value-selected state is not projectable. {} selects a state with empty == true. Such a state can also advertise a value, as for nullopt, or it can be anonymous.

The remaining members have the following contracts:

• index(subject) identifies the active state and is noexcept.
• get<State>(subject) provides the projection for a projectable state. It is called only when that state is active and preserves the cv-qualification and value category specified by the customization.
• has_residual_states states whether runtime states can exist outside the advertised set. Such states are residual rather than required.

The type returned by index(subject) also provides named selectors. For a scoped enumeration, .name names an enumerator. For a class type, .name or .name<I> names a constant state value supplied by that type. An integral discriminator provides no named selectors. All selectors for a projectable state use its get operation.

An advertised constant value is matched by testing whether the subject is in the corresponding state, without invoking operator==. If several states advertise the same canonical value, the value pattern selects and covers all of them. A value pattern that is not advertised retains its ordinary equality semantics, but does not cover an advertised state for exhaustiveness analysis.

9.2 Open Type-Indexed Protocol

An open alternative type omits the finite state list:

template <>
struct alternative_traits<any> {
  static bool has_value(const any& value) noexcept;

  template <class T, class Self>
  static auto try_cast(Self&& self) noexcept;

  template <class T, class Self>
  static auto try_init(Self&& self) noexcept;
};

For { T: P }, matching calls try_cast<T>(subject), preserving T exactly. For a direct declaration pattern { T name }, matching instead calls try_init<T>(subject), again preserving T exactly. This distinction lets a specialization interpret T as a selected type in the first form and as a declaration type in the second. For example, any can reject the selector { int&: P } while supporting the declaration { int& value }.

The result must be contextually convertible to bool and dereferenceable. It is materialized once and tested as an lvalue. A false result is a non-match; otherwise the result is dereferenced with the value category of the original call expression and the projection is matched. This permits a carrier to preserve the subject’s cv-qualification and value category.

No overlap is inferred between try_cast<T> and try_init<T>. They are separate open views unless the specialization gives them equivalent behavior. Repeated uses of the same operation and type can still share one materialized result.

An open specialization can additionally provide has_value(subject). If present, {} calls that operation and matches when its result is contextually false. The empty state is distinct from every successful try_cast and try_init. Repeated empty tests can share one result.

An open alternative type has no generic projection because it cannot give the unknown remainder one static type. Consequently generic non-declaration { P }, named selectors, and indexed selectors are ill-formed. {} is ill-formed when the specialization omits has_value. A top-level _ handles all values not recognized by preceding typed projections. It remains necessary for exhaustiveness even when has_value is present.

For any, both operations can share a small carrier:

template <>
struct alternative_traits<any> {
  template <class Self, class Pointer>
  struct result {
    Pointer pointer;

    explicit operator bool() const noexcept { return pointer != nullptr; }

    decltype(auto) operator*() && noexcept {
      return forward_like<Self>(*pointer);
    }
  };

  static bool has_value(const any& value) noexcept {
    return value.has_value();
  }

  template <class T, class Self>
  static auto try_cast(Self&& self) noexcept {
    auto* pointer = any_cast<T>(addressof(self));
    return result<Self, decltype(pointer)>{pointer};
  }

  template <class T, class Self>
  static auto try_init(Self&& self) noexcept {
    auto* pointer = any_cast<remove_reference_t<T>>(addressof(self));
    return result<Self, decltype(pointer)>{pointer};
  }
};

try_cast preserves the explicit selector. try_init removes only the reference used by the declaration before querying any_cast; cv-qualification continues to constrain the resulting projection.

The exception_ptr_cast proposed by [P2927R3] makes the corresponding exception_ptr specialization smaller:

template <>
struct alternative_traits<exception_ptr> {
  static bool has_value(const exception_ptr& value) noexcept {
    return bool(value);
  }

  template <class T>
  static const auto* try_cast(const exception_ptr& value) noexcept {
    return exception_ptr_cast<T>(value);
  }

  template <class T>
  static const auto* try_init(const exception_ptr& value) noexcept {
    return exception_ptr_cast<remove_cvref_t<T>>(value);
  }
};

The prototype implements the any specialization. Its library does not yet contain that facility, so the exception_ptr specialization remains a design sketch.

9.3 Standard Specializations

With both protocol forms established, the proposed standard specializations are:

Raw pointers use built-in language semantics. We still provide an alternative_traits<T*> specialization so that a smart pointer with exactly the same state mapping can explicitly reuse it. Merely looking pointer-like does not opt a user-defined type into an exhaustive two-state promise. The non-array unique_ptr and shared_ptr specializations inherit this model.

If a polymorphic class also provides alternative_traits, syntax selects the operation rather than an implicit precedence rule: a bare class declaration performs a runtime polymorphic cast, while { P } enters its advertised alternatives.

variant uses its index and a projection whose precondition is the selected index. optional advertises null index 0 and value index 1. expected advertises value index 0 and error index 1. A binary alternative type with named states can use a bool-backed enumeration as its index type.

The built-in pointer behavior is equivalent to the following specialization. Again, the specialization exists for explicit reuse; the compiler does not need it to recognize a raw pointer:

template <class T>
struct alternative_traits<T*> {
  static constexpr alternative_info alternatives[] = {
    {meta::reflect_constant(nullptr), /*empty=*/true},
    ^^T,
  };
  static constexpr bool has_residual_states = false;

  enum class state : bool { null = false, value = true };

  static constexpr state index(auto const& value) noexcept {
    return value ? state::value : state::null;
  }

  template <state State, class Self>
    requires (State == state::value)
  static constexpr decltype(auto) get(Self&& self) noexcept {
    if constexpr (is_void_v<T>)
      return;
    else
      return *std::forward<Self>(self);
  }

};

template <class T>
struct alternative_traits<optional<T>> {
  static constexpr alternative_info alternatives[] = {
    {^^nullopt, /*empty=*/true},
    ^^T,
  };

  enum class state : bool { null = false, value = true };

  static constexpr state index(optional<T> const& value) noexcept {
    return value.has_value() ? state::value : state::null;
  }

  template <state State, class Self>
    requires (State == state::value)
  static constexpr decltype(auto) get(Self&& self) noexcept {
    return *std::forward<Self>(self);
  }
};

The pointer specialization templates the parameter of index so that a smart pointer with the same state mapping can inherit the implementation. For a non-void pointee, the return type of get comes from dereferencing the actual subject and therefore preserves cv/ref. For void*, the non-null state has type void; { void } selects it without dereferencing the pointer.

optional defines its own specialization because its null state is spelled nullopt. An ordinary case 0 still asks whether an engaged optional<int> contains zero.

expected advertises two projectable states, including void for a successful expected<void, E>:

template <class T, class E>
struct alternative_traits<expected<T, E>> {
  static constexpr alternative_info alternatives[] = {^^T, ^^E};
  static constexpr bool has_residual_states = false;

  enum class state : bool { value = false, error = true };

  static constexpr state index(expected<T, E> const& value) noexcept {
    return value.has_value() ? state::value : state::error;
  }

  template <state State, class Self>
  static constexpr decltype(auto) get(Self&& self) {
    if constexpr (State == state::value)
      return *std::forward<Self>(self);
    else
      return std::forward<Self>(self).error();
  }
};

Both names provide a state value. { .value: P } projects the value and { .error: P } projects the error. expected does not expose .index<I>; its state names are the better interface.

Variant advertises every declared index, exposes those indices through the parameterized name .index<I>, and has a residual valueless state:

template <class... Types>
struct alternative_traits<variant<Types...>> {
  static constexpr alternative_info alternatives[] = { ^^Types... };
  static constexpr bool has_residual_states = true;

  struct state {
    size_t value;

    template <size_t I>
    static constexpr size_t index = I;

    friend constexpr bool operator==(state, state) = default;
  };

  static constexpr state index(variant<Types...> const& value) noexcept {
    return {value.index()};
  }

  template <state State, class Self>
  static constexpr decltype(auto) get(Self&& self) noexcept {
    return /* unchecked projection of alternative State.value */;
  }
};

The discriminator is a structural class, so the selected state is passed directly to get<State>. It has no integral conversion; matching compares state values directly, and an implementation remains free to lower the dispatch to a switch.

.index<I> exists because variant’s discriminator provides a variable template mapping I to its state, not because positional selection is implicit in every alternative_traits specialization. Since the language has already checked and saved the index, the standard-library specialization can use a private operation with that precondition without adding a new public variant API.

Names do not introduce a second state machine. Plain names can be enumerators in the discriminator type returned by index, and a type that wants synonyms defines them directly.

enum class state : bool {
  value = false, ok = false,
  error = true, err = true,
};

Because these names denote the same indexed states, usefulness, exhaustiveness, and projection treat them identically:

match (state_value) {
  case state::value => handle_value();
  case state::error => handle_error();
  case state::err => handle_err(); // error: redundant
}

The first two cases are exhaustive because the enum’s full value range is false and true. Replacing error with err has the same coverage.

The same applies to named selectors. Both .error and .err select state true, so { .err } makes a later .error case redundant. Either name can select the state without projection or select its projection with : P. expected avoids the misleading synonym and exposes only value and error.

10 Dependence and Case Instantiation

10.1 Dependent Case Matching

A dependent match selection can contain a case that applies in one specialization and not another:

template <class T>
int classify_value(T value) {
  return match (value) {
    case int         => 0;
    case std::string => 1;
    case _           => 2;
  };
}

For T equal to int, the std::string case is omitted; for T equal to std::string, the int case is omitted. Each source case remains potentially useful because it can apply in another specialization.

The same rule applies recursively after alternative projection:

template <class V>
int classify_variant(V value) {
  return match (value) {
    case { int }         => 0;
    case { std::string } => 1;
    case { char }        => 2;
  };
}

For variant<int, std::string>, the char case is not instantiated. It remains maybe useful because another specialization could contain char. The same case on a non-dependent variant<int, std::string> is ill-formed because it cannot match anything.

As shown in Applicability Versus Failed Initialization, reference binding can also make a case apply only in some specializations. This does not make a T& case generally useless for an rvalue alternative type. In C++26, optional<T&> is valid and dereferencing it produces T& even when the optional itself is an rvalue:

template <class T>
int classify(optional<T> value) {
  return match (std::move(value)) {
    case { T& reference } => 1;
    case _                => 2;
  };
}

int value = 42;
classify(optional<int>{42});     // 2
classify(optional<int&>{value}); // 1

Some dependent patterns are nevertheless provably useless. A built-in array has a fixed, non-customizable decomposition arity:

template <class T>
int classify(T (&value)[2]) {
  return match (value) {
    case [T first, T second, T third] => 1;
    case _                            => 2;
  };
}

No substitution can make this three-element pattern match the two-element array. The prototype currently calls it maybe useful because it is dependent. Whether we should require this diagnostic remains an open question. We cannot infer the same answer for variant<T> without making assumptions about possible specializations and their projection behavior.

Exhaustiveness is checked for each concrete specialization:

constexpr size_t arity(auto value) {
  return match (value) {
    case auto&& [...elements] => sizeof...(elements);
  };
}

static_assert(arity(tuple(1, 2)) == 2);
// arity(0); // error: the instantiated match is not exhaustive

10.2 Case-Local Instantiation

In a dependent match selection, the preamble is instantiated once for the enclosing specialization, before any applicable source case is instantiated for alternative projections. It is not duplicated for each such case instantiation.

The pattern declarations, guard, and handler form one syntactically bounded case instantiation context. Each instantiation separately handles result deduction, decltype, constraints, local statics, diagnostics, and structured-binding packs.

An earlier unguarded irrefutable semantic case closes only its own domain and prevents later handlers for that domain from being instantiated:

variant<int, string, vector<int>> value;

auto result = match (value) {
  case { int integer } => integer;
  case { auto&& data } => static_cast<int>(data.size());
};

The second handler is instantiated for string and vector<int>, not for int. This gives us the useful instantiation behavior of an overloaded visitor without turning the cases into an overload set.