Skip to content

Patternia v0.9.6 Release Note

Release Date: November 2026 Version: 0.9.6


Overview

Patternia v0.9.6 makes case lists shorter and lets a match own its subject:

  • $ can end a case list without a trailing _.
  • The right-hand side of >> accepts the same expressions as guards: $(pt)[x > 0] >> (x - y).
  • A plain value can stand wherever a pattern is expected: any('a', 'e', 'i'), is<int>(0).
  • match(std::move(value)) and match(make_value()) own the subject. Patterns and guards observe it, and only the selected handler can consume it, so move-only subjects such as std::unique_ptr work.

The release also reworks dispatch. Every keyed match (dense val<N> literals, lit(...) literals, std::variant alternatives, borrowed and owned subjects) now selects its case through one switch, and the whole path is always inlined. The one exception is an owned variant with four or fewer alternatives, which is evaluated in source order. On GCC this makes literal and variant matches compile to the same code as a hand-written switch, where v0.9.5 used chains or trees of comparisons and, depending on the translation unit, wrote the case pack to the stack. With -g, GCC also writes about 8 times less debug information for the same code.

There are no breaking API changes. A few behaviors changed; see Behavior Changes.


New Features

$ as the final fallback

An unguarded $ (or $()) matches every value and binds the whole subject, so it can end a case list on its own:

// v0.9.5
match(roll) | on(
  lit(3) >> add_fancy_hat,
  lit(7) >> remove_fancy_hat,
  $      >> [](int r) { move_player(r); },
  _      >> [] {}                           // required, unreachable
);

// v0.9.6
match(roll) | on(
  lit(3) >> add_fancy_hat,
  lit(7) >> remove_fancy_hat,
  $      >> [](int r) { move_player(r); }   // already the fallback
);

A guarded binding such as $[_ > 0] or a binding with a subpattern such as $(is<int>) still needs a fallback. A trailing _ after $ remains valid.

Expression handlers

The right-hand side of >> accepts the expressions guards already use, evaluated only when the case is selected:

match(n) | on(
  $[_ > 0] >> (_ * 2 + 1),
  $        >> -_
);

constexpr auto pt = has<&Point::x, &Point::y>;
auto [x, y] = pt;
match(p) | on(
  $(pt)[x > 0 && y > 0] >> (x + y),
  $(pt)[x > 0]          >> (x - y),
  $(pt)                 >> (x * x + y * y),
  _                     >> 0
);
  • _ is the first bound value; structural names resolve against the case's own pattern.
  • Arithmetic results keep their type; comparisons and logical expressions return bool and short-circuit. Parenthesize them after >>, as in $ >> (_ > 0), because >> binds tighter. + and - bind tighter than >>, but GCC's -Wparentheses (in -Wall) asks for parentheses around them too.
  • Unary + and - are new, in handlers and in guards.
  • Results are returned by value, so $ >> _ does not hand out a reference to a temporary binding.

Plain values inside patterns

Wherever a pattern is expected as an argument, an arithmetic, enumeration or string-like value is treated as lit(value):

// v0.9.5
any(lit('a'), lit('e'), lit('i')) >> "vowel",
is<int>(lit(0))                   >> "int zero",

// v0.9.6
any('a', 'e', 'i')  >> "vowel",
is<int>(0)          >> "int zero",
alt<1>("hi")        >> "second is hi",
(lit(' ') || '\n')  >> "whitespace",
neg(0)              >> "nonzero",

any, all, neg, is<T>(p), alt<I>(p) and the right operand of the pattern-level || / && accept plain values. !v is unchanged, since ! on a built-in type cannot be overloaded.

Owning a subject

An rvalue subject is now owned by the match context instead of being referenced:

auto task = std::make_unique<Task>();
match(std::move(task)) | on(
  $[([](const auto &p) { return p && p->ready(); })]
    >> [](std::unique_ptr<Task> p) { run(std::move(p)); },
  $ >> [](std::unique_ptr<Task> p) { defer(std::move(p)); }
);
  • Constructing the context moves the subject. Patterns and guards see it through const references; a rejected case leaves it intact for later cases; only the selected handler receives consuming bindings.
  • The same holds for variant alternatives ($(is<T>) binds the alternative as an rvalue), structural members, nested guards and the any, all and neg combinators.
  • A context can be stored and evaluated later; it keeps the subject alive. Results of an owning match are materialized before the context is destroyed.
  • A temporary or moved on(...) pack can hold move-only handlers and operator() && handlers; a stored pack keeps its handlers as lvalues for reuse.
  • Guards on owned subjects must accept read-only bindings; a guard that takes a binding by non-const reference is a compile-time error that says to consume the value in the handler.

Lvalue subjects are still borrowed, with const reference bindings.

Constant case packs

A case pack may be const or constexpr and reused:

constexpr auto classify = on(val<1> >> 1, val<2> >> 2, _ >> 0);
int a = match(x) | classify;
int b = match(compute()) | classify;

PTN_ON and static_on now cache their cases as const when no handler keeps state, so the compiler treats them as constants.

Diagnostics for malformed cases

on(...) rejects an argument that is not a case before handler deduction and dispatch planning start, with one diagnostic instead of a cascade. on(0 >> 1, _ >> 0), where 0 >> 1 is C++'s built-in bit shift, now says so and suggests lit(0) >> 1.


Behavior Changes

$(alt<I>) binds the alternative on borrowed subjects

$(alt<I>) now binds the selected alternative, as $(is<T>) does and as it already did on owned subjects. Before, a borrowed match bound the whole variant, so a handler for the alternative did not compile:

std::variant<int, std::string> v = 5;

// v0.9.5: did not compile; the handler had to take the variant
// v0.9.6: x is the int alternative
match(v) | on($(alt<0>) >> [](int x) { return x; }, _ >> 0);

A handler written for the old binding, taking the whole variant, has to take the alternative instead.

Materialized bindings are forwarded

When a custom pattern's bind() returns a value (std::tuple<T>), the handler now receives T&& instead of T&, on borrowed subjects too. Handlers that take T, T&& or const T& are unaffected; a handler taking a non-const T& must change. Built-in borrowed bindings remain const references.

A valueless variant reaches the fallback

A borrowed match on a variant that is valueless_by_exception() used to call std::abort(). It now evaluates the cases in order: type patterns reject it and the _ or $ fallback runs.

static_on returns a const reference for stateless handlers

When no handler keeps state, static_on caches its cases as const and returns a const reference. auto &cases = static_on(...) keeps working; code that names a non-const reference type has to add const. A handler with state keeps a mutable cache, as before.

A bool on the right of || and && is a value

With plain values accepted, (neg(0) && flag) means all(neg(0), lit(flag)): the subject is compared with flag, which is not tested as a condition.


Performance

On GCC, literal and variant matches now compile to the same code as a hand-written switch. Instructions at -O2 on x86-64, v0.9.5 to v0.9.6:

Match GCC 13 Clang 18
64 dense val<N> literals (switch: 6) 134 to 7 144 to 6
15 sparse lit(...) literals 47 (14 branches) to 6 40 to 39 (unchanged, a table)
16 variant alternatives 59 (8 branches) to 8 80 to 7

In CI's GCC 13 benchmarks, mixed-alternative variant workloads went from about 2× the hand-written switch to parity. Owned subjects dispatch like borrowed ones and run as fast as hand-written code on Apple Clang. With GCC 13 at -O2 -g, the benchmark suite's object file shrank from 686 MB to 92 MB and compiles in 5.8 s instead of 18.4 s.

On Apple Clang (arm64), a two-alternative variant match now compiles to the same instructions as the hand-written switch and runs at its speed (1.31 ns in the benchmark loop); v0.9.5's different sequence ran at 0.92 ns there.

See the v0.9.6 performance note for the measurements, the methods and what did not improve.


Bug Fixes

  • $(p) compiles for any subpattern: $(pred(...)), $(lit(3)), $(val<3>), $(any(...)), $(neg(...)) and $(_) bind the subject. They failed with "alt_index is not a member".
  • A file whose first include is <ptn/patternia.hpp> compiles with MSVC in C++20: common_traits.hpp now includes <cstdlib>.
  • On GCC, whether a literal match compiled to a table depended on the order of functions in the translation unit; the case pack is now stored in a type whose access is always inlined.

Internal Improvements

  • Dispatch: one index_visit switch for dense literals, lit(...) plans and variant alternatives, replacing the variant comparison chain, comparison tree and function-pointer table; the dispatch path, the owned evaluation path and their continuations are always inlined.
  • Codegen gate: scripts/check_codegen.py and 15 probes in tests/codegen/ compile representative matches at -O2 in CTest and fail when a match makes a call, uses the stack, branches more than a limit or grows past a hand-written reference.
  • Benchmarks: owning and borrowed matches, rejected guards, structural bindings and consuming handlers (bench/bench_ownership.cpp); the PR benchmark comparison now includes LiteralMatch64 and LiteralMatchRDense.
  • Tests: 439 tests (up from 256 in v0.9.5), including the 15 codegen probes.
  • Docs: the roadmap is organized by version; the README and API reference describe the new features; agent instructions live in AGENTS.md and ai/skills/.
  • CI: docs-only pull requests skip the build steps.

Migration Guide

Nothing needs to change to upgrade, except for the behavior changes above. To use the shorter forms:

std::variant<int, std::string> v = 21;
char c = 'b';
int n = 4;

// v0.9.5
match(v) | on(
  $(is<int>)[([](int i) { return i > 0; })] >> [](int i) { return i * 2; },
  _ >> [] { return 0; }
);
match(c) | on(any(lit('a'), lit('b')) >> 1, _ >> 0);
match(n) | on(lit(0) >> 0, $ >> [](int i) { return i; }, _ >> -1);

// v0.9.6
match(v) | on($(is<int>)[_ > 0] >> _ * 2, _ >> 0);
match(c) | on(any('a', 'b') >> 1, _ >> 0);
match(n) | on(lit(0) >> 0, $ >> _);

To consume the subject instead of copying out of it, move it into the match: match(std::move(v)).


Pull Requests

Every pull request merged since v0.9.5:

  • #69 chore(release): add a release workflow skill
  • #70 chore(vcpkg): update portfile SHA512 for v0.9.5
  • #71 revert(release): remove the release workflow skill
  • #72 chore(release): add a release workflow skill
  • #73 docs: move the release skill to ai/skills and add AGENTS.md
  • #74 ci: skip build steps for docs-only pull requests
  • #76 docs: rewrite README and fix requirements in docs/index.md
  • #78 docs: reorganize the roadmap by version and tidy site navigation
  • #80 docs(roadmap): expand exhaustiveness checking planned for v0.10
  • #81 docs(roadmap): plan automatic enumerator detection for v0.10
  • #82 docs(roadmap): move shorter cases to v0.9.6
  • #83 fix(bind): allow non-type subpatterns inside $(...)
  • #84 docs(roadmap): clarify when has<...> counts as coverage
  • #85 feat(pattern): accept plain values inside patterns
  • #86 fix(core): include for std::abort in common_traits
  • #87 feat(match): allow dollar bindings as the final fallback
  • #88 feat(match): support expression handlers
  • #89 docs(roadmap): schedule moves and value domains
  • #90 fix(dsl): clarify invalid case diagnostics and expand coverage
  • #91 feat(match): add move-aware subject ownership
  • #92 test(bench): add owning and borrowed match benchmarks
  • #93 fix(match): keep dense literal dispatch inlined
  • #94 fix(match): use keyed dispatch for owned dense literals
  • #95 test(bench): add owned guard benchmarks
  • #96 fix(match): reach the fallback for a valueless variant
  • #97 perf(match): dispatch variant alternatives through a switch
  • #98 perf(match): cache stateless case packs as const
  • #99 perf(match): inline the literal chain for owned subjects
  • #100 perf(match): skip the alternative test inside a variant arm
  • #101 fix(bind): bind the alternative for $(alt) on borrowed subjects
  • #102 perf(match): keep literal dispatch keyed on GCC
  • #103 perf(match): dispatch dense literals through the index switch
  • #104 perf(match): switch on the active alternative of owned variants
  • #105 fix(match): always inline the owned evaluation path
  • #106 fix(match): shrink GCC debug information for keyed matches
  • #107 test(match): run the planner summaries at run time