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))andmatch(make_value())own the subject. Patterns and guards observe it, and only the selected handler can consume it, so move-only subjects such asstd::unique_ptrwork.
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
booland 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
constreferences; 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 theany,allandnegcombinators. - 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 andoperator() &&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_indexis not a member".- A file whose first include is
<ptn/patternia.hpp>compiles with MSVC in C++20:common_traits.hppnow 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_visitswitch 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.pyand 15 probes intests/codegen/compile representative matches at-O2in 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 includesLiteralMatch64andLiteralMatchRDense. - 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.mdandai/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