Patternia v0.8.2 Release Note

Release Date: March 3, 2026
Version: 0.8.2

---

Overview

Patternia v0.8.2 is a performance and API refinement release.

Compared with v0.8.0, this version introduces the lowering engine as the new optimization backbone, adds reusable pipeline matcher forms for hot paths, and formalizes the split between runtime literal factories and compile-time literal lowering.

---

Highlights

API Update

• Public examples now prefer:
• match(x) | on(...);
• Added reusable pipeline matcher forms:
• static_on(...)
• PTN_ON(...)
• Literal APIs are now explicitly split by purpose:
• lit(value) for general runtime matching
• lit_ci(value) for runtime case-insensitive string matching
• lit<value>() for lowering-friendly compile-time literal dispatch

Performance: Lowering Engine in v0.8.2

• Introduced a shared lowering legality model:
• full
• bucketed
• none
• Added a switch-oriented static literal dispatch path for keyed matches that fit the dense-span heuristics.
• Unified static literal and variant dispatch planning under the same dispatch_plan model.
• Added reusable cached matcher forms so pipeline syntax can avoid repeated matcher construction in hot loops.

Benchmark Snapshot

The release benchmark uses a 128-way static literal chain because it clearly separates two costs:

• dispatch quality
• matcher construction overhead

Raw pipeline matcher vs switch:

Cached matcher forms vs switch:

Representative local results:

Benchmark	Meaning	CPU time
BM_PatterniaPipe_LiteralMatch128StaticCases	prebuilt matcher object	1.74 ns
BM_PatterniaPipe_LiteralMatch128On	raw inline on(...)	17.9 ns
BM_PatterniaPipe_LiteralMatch128OnMacro	cached pipeline matcher via PTN_ON(...)	2.09 ns
BM_Switch_LiteralMatch128	hand-written switch baseline	1.52 ns

---

Migration Guide

This release does not require a forced source migration, but it changes the recommended style.

Before:

auto r = match(x) | on{
  lit(1) >> 1,
  __ >> 0
};

Recommended in v0.8.2:

auto r = match(x) | on(
  lit(1) >> 1,
  __ >> 0
);

For hot paths, prefer cached matcher forms.

Before:

auto r = match(x) | on(
  lit<1>() >> 1,
  lit<2>() >> 2,
  __ >> 0
);

After:

auto r = match(x) | PTN_ON(
  lit<1>() >> 1,
  lit<2>() >> 2,
  __ >> 0
);

---

Compatibility Notes

• API surface: additive in 0.8.2.
• Existing on{...} call sites remain source-compatible, but public examples now prefer on(...).
• lit(value) and lit_ci(value) remain available for runtime matching.
• lit<value>() is the new compile-time literal entry point for lowering.
• Runtime semantics remain first-match and fallback-compatible for equivalent case ordering.

---

Implementation Notes

• include/ptn/core/common/optimize.hpp
• Added lowering legality analysis and shared dispatch_plan selection.
• include/ptn/core/common/eval.hpp
• Added switch-oriented static literal dispatch execution and updated plan-driven evaluation.
• include/ptn/core/engine/match.hpp
• Added static_on(...) for cached pipeline matcher reuse.
• include/ptn/patternia.hpp
• Added PTN_ON(...) convenience sugar for cached pipeline syntax.

For algorithm-level discussion, see:

• Performance Notes