# `structura` — Compile-Time Structural Reflection for C++26 Here's a library I've been sketching that leans hard on P2996 reflection to provide *automatic structural interfaces* — things you'd normally hand-write or generate with macros. The core idea: **one header gives you serialization, structural diffing, field-path addressing, ORM-style column mapping, and structural pattern matching, with zero annotations on your types.** ```cpp #include struct Address { std::string city; std::string zip; }; struct Person { std::string name; int age; Address home; std::vector scores; }; ``` That's it. No macros, no `BOOST_FUSION_ADAPT_STRUCT`, no `REFLECT(...)`. --- ## 1. Foundation: the member walker Everything builds on one primitive — a `constexpr` list of non-static data members, and a generic recursive walk. ```cpp namespace structura { namespace meta = std::meta; template consteval auto members_of_type() { return meta::nonstatic_data_members_of(^^T, meta::access_context::unchecked()); } template constexpr std::size_t member_count = members_of_type().size(); // A structural aggregate we can decompose. template concept Reflectable = std::is_class_v && !std::is_polymorphic_v && requires { members_of_type(); }; } // namespace structura ``` The workhorse is `for_each_member`, which uses `template for` (P1306) to expand over the member list: ```cpp namespace structura { template constexpr void for_each_member(T&& obj, F&& f) { template for (constexpr auto m : define_static_array(members_of_type>())) { f(meta::identifier_of(m), obj.[:m:]); } } // Index-aware variant: passes a compile-time index too. template constexpr void for_each_member_indexed(T&& obj, F&& f) { constexpr auto ms = define_static_array(members_of_type>()); [&](std::index_sequence) { (f(std::integral_constant{}, meta::identifier_of(ms[Is]), obj.[:ms[Is]:]), ...); }(std::make_index_sequence{}); } } // namespace structura ``` `define_static_array` promotes the consteval `vector` into a static array so its elements are usable as constant expressions inside `template for` — the standard idiom for this in P2996. --- ## 2. Structural diffing This is the feature I actually wanted the library for. Given two values of the same type, produce a list of *paths* that differ, recursing into nested structs, vectors, and optionals. ```cpp namespace structura { struct Diff { std::string path; std::string before; std::string after; }; namespace detail { template constexpr bool is_vector_like = requires (T t) { t.begin(); t.end(); t.size(); } && !std::same_as, std::string>; template constexpr bool is_optional_like = requires (T t) { t.has_value(); *t; }; template void diff_into(std::vector& out, std::string path, T const& a, T const& b); template void diff_struct(std::vector& out, std::string const& path, T const& a, T const& b) { constexpr auto ms = define_static_array(members_of_type()); template for (constexpr auto m : ms) { std::string child = path.empty() ? std::string(meta::identifier_of(m)) : path + "." + std::string(meta::identifier_of(m)); diff_into(out, std::move(child), a.[:m:], b.[:m:]); } } template void diff_into(std::vector& out, std::string path, T const& a, T const& b) { if constexpr (Reflectable && !is_vector_like && !is_optional_like) { diff_struct(out, path, a, b); } else if constexpr (is_optional_like) { if (a.has_value() != b.has_value()) { out.push_back({std::move(path), a.has_value() ? "" : "", b.has_value() ? "" : ""}); } else if (a.has_value()) { diff_into(out, std::move(path), *a, *b); } } else if constexpr (is_vector_like) { std::size_t n = std::min(a.size(), b.size()); auto ia = a.begin(); auto ib = b.begin(); for (std::size_t i = 0; i < n; ++i, ++ia, ++ib) diff_into(out, path + "[" + std::to_string(i) + "]", *ia, *ib); if (a.size() != b.size()) out.push_back({path + ".size()", std::to_string(a.size()), std::to_string(b.size())}); } else { if (!(a == b)) out.push_back({std::move(path), to_display(a), to_display(b)}); } } } // namespace detail template std::vector diff(T const& a, T const& b) { std::vector out; detail::diff_into(out, "", a, b); return out; } } // namespace structura ``` Usage: ```cpp Person p1{"Ada", 36, {"London", "NW1"}, {90, 85}}; Person p2{"Ada", 37, {"London", "SW3"}, {90, 88, 70}}; for (auto const& d : structura::diff(p1, p2)) std::println("{}: {} -> {}", d.path, d.before, d.after); ``` ``` age: 36 -> 37 home.zip: NW1 -> SW3 scores[1]: 85 -> 88 scores.size(): 2 -> 3 ``` Getting this without reflection means either writing it by hand per type or generating it. Here it's free. --- ## 3. Typed field paths Diffing produces string paths; it would be nice to *consume* them too. `field_path` resolves a dotted string at compile time into a chain of member accesses, yielding a strongly typed accessor. ```cpp namespace structura { namespace detail { // Split "home.zip" into ["home", "zip"] at consteval time. consteval std::vector split_path(std::string_view p) { std::vector parts; std::size_t start = 0; while (true) { auto dot = p.find('.', start); if (dot == std::string_view::npos) { parts.push_back(p.substr(start)); break; } parts.push_back(p.substr(start, dot - start)); start = dot + 1; } return parts; } consteval meta::info find_member(meta::info type, std::string_view name) { for (auto m : meta::nonstatic_data_members_of(type, meta::access_context::unchecked())) if (meta::identifier_of(m) == name) return m; throw std::runtime_error("no such member"); // consteval throw = hard error } // Resolve the whole chain, returning the reflection sequence. consteval std::vector resolve_chain(meta::info root, std::string_view path) { std::vector chain; meta::info cur = root; for (auto part : split_path(path)) { auto m = find_member(cur, part); chain.push_back(m); cur = meta::type_of(m); } return chain; } } // namespace detail // A compile-time path object. template struct field_path_t { using root_type = Root; static constexpr decltype(auto) get(Root& r) { return (r.[:Chain:] ... ); // conceptually: fold member access } }; } // namespace structura ``` The fold-of-member-access needs a helper since `.[:...:]` doesn't pack-expand as a chain: ```cpp namespace structura::detail { template constexpr decltype(auto) apply_chain(Obj&& o, std::index_sequence<>) { return std::forward(o); } template constexpr decltype(auto) apply_chain_impl(Obj&& o) { // Recursive splicing via a lambda ladder. constexpr auto arr = std::array{Chain...}; return [&](this auto&& self, auto&& cur) -> decltype(auto) { if constexpr (I == arr.size()) return std::forward(cur); else return self.template operator()(cur.[:arr[I]:]); }.template operator()<0>(std::forward(o)); } } ``` Now the user-facing macro-free API — a fixed-string template parameter: ```cpp namespace structura { template struct fixed_string { char data[N]{}; constexpr fixed_string(char const (&s)[N]) { std::copy_n(s, N, data); } constexpr operator std::string_view() const { return {data, N - 1}; } }; template constexpr decltype(auto) at(Root&& r) { constexpr auto chain = define_static_array( detail::resolve_chain(^^std::remove_cvref_t, std::string_view(Path))); return detail::apply_chain_ladder(std::forward(r)); } } // namespace structura ``` ```cpp Person p{"Ada", 36, {"London", "NW1"}, {}}; structura::at(p) = "Cambridge"; static_assert(std::same_as< decltype(structura::at(p)), int&>); // Typo is a compile error, not a runtime lookup failure: // structura::at(p); // error: no such member ``` Typed, compile-checked, no runtime string parsing. --- ## 4. Automatic ORM column mapping Reflection makes schema generation genuinely pleasant. Types map to columns; nested structs flatten with prefixes. ```cpp namespace structura::sql { template struct sql_type; template <> struct sql_type { static constexpr auto name = "INTEGER"; }; template <> struct sql_type { static constexpr auto name = "BIGINT"; }; template <> struct sql_type { static constexpr auto name = "REAL"; }; template <> struct sql_type { static constexpr auto name = "BOOLEAN"; }; template <> struct sql_type { static constexpr auto name = "TEXT"; }; struct column { std::string name; std::string type; bool nullable; }; template void collect_columns(std::vector& out, std::string prefix) { constexpr auto ms = define_static_array(members_of_type()); template for (constexpr auto m : ms) { using M = typename [:meta::type_of(m):]; std::string name = prefix + std::string(meta::identifier_of(m)); if constexpr (detail::is_optional_like) { using Inner = std::remove_cvref_t())>; out.push_back({name, sql_type::name, true}); } else if constexpr (requires { sql_type::name; }) { out.push_back({name, sql_type::name, false}); } else if constexpr (Reflectable) { collect_columns(out, name + "_"); } // vectors etc. would become a child table; omitted here } } template std::string create_table(std::string_view table) { std::vector cols; collect_columns(cols, ""); std::string s = std::format("CREATE TABLE {} (\n", table); for (std::size_t i = 0; i < cols.size(); ++i) { s += std::format(" {} {}{}{}\n", cols[i].name, cols[i].type, cols[i].nullable ? "" : " NOT NULL", i + 1 < cols.size() ? "," : ""); } return s + ");"; } } // namespace structura::sql ``` ```cpp struct Employee { long long id; std::string name; std::optional salary; Address office; }; std::println("{}", structura::sql::create_table("employees")); ``` ```sql CREATE TABLE employees ( id BIGINT NOT NULL, name TEXT NOT NULL, salary REAL, office_city TEXT NOT NULL, office_zip TEXT NOT NULL ); ``` The matching row-binder writes itself: ```cpp template void bind_row(sqlite3_stmt* st, T const& row) { int idx = 1; bind_recursive(st, idx, row); } template void bind_recursive(sqlite3_stmt* st, int& idx, T const& v) { if constexpr (Reflectable && !detail::is_optional_like) { for_each_member(v, [&](std::string_view, auto const& field) { bind_recursive(st, idx, field); }); } else { bind_scalar(st, idx++, v); } } ``` Column order is guaranteed to match `collect_columns` because both walk members in declaration order. --- ## 5. Structural pattern matching The most speculative piece. Given a struct, generate a matcher that destructures by *name*, so you write predicates against named fields rather than positional tuples. ```cpp namespace structura { // A predicate bound to a named field. template struct field_pred { Pred pred; template constexpr bool operator()(T const& obj) const { return pred(at(obj)); } }; template constexpr auto field(Pred p) { return field_pred{std::move(p)}; } template struct all_of { std::tuple ps; template constexpr bool operator()(T const& obj) const { return std::apply([&](auto const&... p) { return (p(obj) && ...); }, ps); } }; template constexpr auto pattern(Ps... ps) { return all_of{{std::move(ps)...}}; } // match(value, case(pattern, handler)...) template constexpr decltype(auto) match(T const& v, Cases&&... cases) { std::optional...>> result; ((!result && cases.pat(v) ? (result = cases.handler(v), true) : false) || ...); return *result; } } // namespace structura ``` ```cpp using structura::field, structura::pattern; auto classify = [](Person const& p) { return structura::match(p, structura::case_(pattern(field<"age">([](int a){ return a < 18; })), [](auto const&){ return "minor"; }), structura::case_(pattern(field<"home.city">([](auto const& c){ return c == "London"; }), field<"age">([](int a){ return a >= 65; })), [](auto const&){ return "london-senior"; }), structura::case_(pattern(), [](auto const&){ return "other"; })); }; ``` Field names are checked at compile time by `at<>`, so a renamed field breaks every pattern that referenced it — which is exactly what you want. --- ## 6. Bonus: schema hashing for wire compatibility A cute trick: hash the structural layout at compile time so two binaries can detect incompatible message definitions. ```cpp namespace structura { consteval std::uint64_t fnv1a(std::string_view s, std::uint64_t h = 14695981039346656037ull) { for (char c : s) { h ^= static_cast(c); h *= 1099511628211ull; } return h; } template consteval std::uint64_t schema_hash(std::uint64_t h = 14695981039346656037ull) { h = fnv1a(meta::identifier_of(^^T), h); for (auto m : members_of_type()) { h = fnv1a(meta::identifier_of(m), h); auto mt = meta::type_of(m); if (meta::is_class_type(mt) && !meta::is_polymorphic(mt)) h = extract( meta::substitute(^^schema_hash, {mt, meta::reflect_constant(h)})); else h = fnv1a(meta::display_string_of(mt), h); } return h; } template constexpr std::uint64_t schema_id = schema_hash(); } // namespace structura ``` ```cpp static_assert(structura::schema_id != structura::schema_id); // Prepend to every serialized message: void send(Person const& p) { write_u64(structura::schema_id); serialize(p); } ``` Rename a field, reorder members, change a type — the hash changes and the peer rejects the message. No `.proto` file, no version numbers to forget to bump. --- ## Notes on the design **Why `template for` and not recursion?** The P1306 expansion statement keeps `m` a genuine constant expression inside the body, which is required for `.[:m:]` splicing. Index-sequence folds work too but read worse and hit template instantiation depth on wide structs. **Access control.** I use `access_context::unchecked()` deliberately — a serializer needs private members. A stricter variant taking `access_context::current()` would only see what the caller could legally touch, which is the right default for a general-purpose walker. Both are worth exposing. **The `throw` in `find_member`.** Throwing from a `consteval` function is how P2996 code reports errors: the throw makes the call non-constant, so the compiler emits a diagnostic pointing at the bad path. It's crude but it works, and it's how the reference implementations do it. **What I'd add next.** Annotation-driven customization via `[[=serde::rename("id")]]` (P3394 annotations), which would let types opt into renaming and skipping without polluting the type with tag members. That's the piece that turns this from a demo into something you'd actually deploy. **Caveats.** All of this depends on P2996 plus P1306 plus `define_static_array`, and syntax across implementations is still in flux — the `^^`/`[::]` spellings settled late. Treat the code above as a faithful sketch rather than something that compiles unmodified on any shipping toolchain today; Bloomberg's Clang fork and EDG's implementation are the places to try it. I've also glossed over the `apply_chain` recursion (the version I sketched has a name mismatch between `apply_chain_impl` and `apply_chain_ladder`) and the `case_` helper in the matcher, both of which need a bit more care than shown.

C++ Reflection