1 Revision History

Since [P2996R2]:

• many wording changes, additions, and improvements
• elaborated on equivalence among reflections and linkage of templated entities specialized by reflections
• added accessible_members_of variants to restore a TS-era agreement
• renamed function previously called value_of to extract, and expanded it to operate on functions
• clarified support for reflections of values and objects rather than constant expressions
• added Godbolt links to Clang/P2996 implementation
• added can_substitute, is_value, is_object, and (new) value_of
• added explanation of a naming issue with the type traits
• added an alternative named tuple implementation
• made default/value/zero-initializing a meta::info yield a null reflection
• added addressed splicing, which is implemented but was omitted from the paper
• added another overload to reflect_invoke to support template arguments
• renamed all the type traits to start with type_ to avoid name clashes. added more generalized is_const, is_final, and is_volatile
• added is_noexcept and fixed is_explicit to only apply to member functions, not member function templates
• added section on handling text
• added a section discussing ODR concerns

Since [P2996R1], several changes to the overall library API:

• added qualified_name_of (to partner with name_of)
• removed is_static for being ambiguous, added has_internal_linkage (and has_linkage and has_external_linkage) and is_static_member instead
• added is_class_member, is_namespace_member, and is_concept
• added reflect_invoke
• added all the type traits

Other paper changes:

• some updates to examples, including a new examples which add a named tuple and emulate typeful reflection.
• more discussion of syntax, constant evaluation order, aliases, and freestanding.
• adding lots of wording

Since [P2996R0]:

• added links to Compiler Explorer demonstrating just about all of the examples
• respecified synth_struct to define_class
• respecified a few metafunctions to be functions instead of function templates
• introduced section on error handling mechanism and our preference for exceptions (removing invalid reflections)
• added ticket counter and variant examples
• collapsed entity_ref and pointer_to_member into value_of

2 Introduction

This is a proposal for a reduced initial set of features to support static reflection in C++. Specifically, we are mostly proposing a subset of features suggested in [P1240R2]:

• the representation of program elements via constant-expressions producing reflection values — reflections for short — of an opaque type std::meta::info,
• a reflection operator (prefix ^) that produces a reflection value for its operand construct,
• a number of consteval metafunctions to work with reflections (including deriving other reflections), and
• constructs called splicers to produce grammatical elements from reflections (e.g., [: refl :]).

(Note that this aims at something a little broader than pure “reflection”. We not only want to observe the structure of the program: We also want to ease generating code that depends on those observations. That combination is sometimes referred to as “reflective metaprogramming”, but within WG21 discussion the term “reflection” has often been used informally to refer to the same general idea.)

This proposal is not intended to be the end-game as far as reflection and compile-time metaprogramming are concerned. Instead, we expect it will be a useful core around which more powerful features will be added incrementally over time. In particular, we believe that most or all the remaining features explored in P1240R2 and that code injection (along the lines described in [P2237R0]) are desirable directions to pursue.

Our choice to start with something smaller is primarily motivated by the belief that that improves the chances of these facilities making it into the language sooner rather than later.

2.1 Notable Additions to P1240

While we tried to select a useful subset of the P1240 features, we also made a few additions and changes. Most of those changes are minor. For example, we added a std::meta::test_type interface that makes it convenient to use existing standard type predicates (such as is_class_v) in reflection computations.

One addition does stand out, however: We have added metafunctions that permit the synthesis of simple struct and union types. While it is not nearly as powerful as generalized code injection (see [P2237R0]), it can be remarkably effective in practice.

2.2 Why a single opaque reflection type?

Perhaps the most common suggestion made regarding the framework outlined in P1240 is to switch from the single std::meta::info type to a family of types covering various language elements (e.g., std::meta::variable, std::meta::type, etc.).

We believe that doing so would be a mistake with very serious consequences for the future of C++.

Specifically, it would codify the language design into the type system. We know from experience that it has been quasi-impossible to change the semantics of standard types once they were standardized, and there is no reason to think that such evolution would become easier in the future. Suppose for example that we had standardized a reflection type std::meta::variable in C++03 to represent what the standard called “variables” at the time. In C++11, the term “variable” was extended to include “references”. Such an change would have been difficult to do given that C++ by then likely would have had plenty of code that depended on a type arrangement around the more restricted definition of “variable”. That scenario is clearly backward-looking, but there is no reason to believe that similar changes might not be wanted in the future and we strongly believe that it behooves us to avoid adding undue constraints on the evolution of the language.

Other advantages of a single opaque type include:

• it makes no assumptions about the representation used within the implementation (e.g., it doesn’t advantage one compiler over another),
• it is trivially extensible (no types need to be added to represent additional language elements and meta-elements as the language evolves), and
• it allows convenient collections of heterogeneous constructs without having to surface reference semantics (e.g., a std::vector<std::meta::info> can easily represent a mixed template argument list — containing types and nontypes — without fear of slicing values).

2.3 Implementation Status

Lock3 implemented the equivalent of much that is proposed here in a fork of Clang (specifically, it worked with the P1240 proposal, but also included several other capabilities including a first-class injection mechanism).

EDG has an ongoing implementation of this proposal that is currently available on Compiler Explorer (thank you, Matt Godbolt).

Additionally, Bloomberg has open sourced a fork of Clang which provides a second implementation of this proposal, also available on Compiler Explorer (again thank you, Matt Godbolt), which can be found here: https://github.com/bloomberg/clang-p2996.

Neither implementation is complete, but all significant features proposed by this paper have been implemented by at least one implementation (including namespace and template splicers). Both implementations have their “quirks” and continue to evolve alongside this paper.

Nearly all of the examples below have links to Compiler Explorer demonstrating them in both EDG and Clang.

The implementations notably lack some of the other proposed language features that dovetail well with reflection; most notably, expansion statements are absent. A workaround that will be used in the linked implementations of examples is the following facility:

Used like:

template <typename E>
  requires std::is_enum_v<E>
constexpr std::string enum_to_string(E value) {
  template for (constexpr auto e : std::meta::enumerators_of(^E)) {
    if (value == [:e:]) {
      return std::string(std::meta::name_of(e));
    }
  }

  return "<unnamed>";
}

template<typename E>
  requires std::is_enum_v<E>
constexpr std::string enum_to_string(E value) {
  std::string result = "<unnamed>";
  [:expand(std::meta::enumerators_of(^E)):] >> [&]<auto e>{
    if (value == [:e:]) {
      result = std::meta::name_of(e);
    }
  };
  return result;
}

3 Examples

We start with a number of examples that show off what is possible with the proposed set of features. It is expected that these are mostly self-explanatory. Read ahead to the next sections for a more systematic description of each element of this proposal.

A number of our examples here show a few other language features that we hope to progress at the same time. This facility does not strictly rely on these features, and it is possible to do without them - but it would greatly help the usability experience if those could be adopted as well:

• expansion statements [P1306R2]
• non-transient constexpr allocation [P0784R7] [P1974R0] [P2670R1]

3.1 Back-And-Forth

Our first example is not meant to be compelling but to show how to go back and forth between the reflection domain and the grammatical domain:

The typename prefix can be omitted in the same contexts as with dependent qualified names (i.e., in what the standard calls type-only contexts). For example:

On Compiler Explorer: EDG, Clang.

3.2 Selecting Members

Our second example enables selecting a member “by number” for a specific type:

This example also illustrates that bit fields are not beyond the reach of this proposal.

On Compiler Explorer: EDG, Clang.

Note that a “member access splice” like s.[:member_number(1):] is a more direct member access mechanism than the traditional syntax. It doesn’t involve member name lookup, access checking, or — if the spliced reflection value denotes a member function — overload resolution.

This proposal includes a number of consteval “metafunctions” that enable the introspection of various language constructs. Among those metafunctions is std::meta::nonstatic_data_members_of which returns a vector of reflection values that describe the nonstatic members of a given type. We could thus rewrite the above example as:

On Compiler Explorer: EDG, Clang.

This proposal specifies that namespace std::meta is associated with the reflection type (std::meta::info); the std::meta:: qualification can therefore be omitted in the example above.

Another frequently-useful metafunction is std::meta::name_of, which returns a std::string_view describing the unqualified name of an entity denoted by a given reflection value. With such a facility, we could conceivably access nonstatic data members “by string”:

On Compiler Explorer: EDG, Clang.

3.3 List of Types to List of Sizes

Here, sizes will be a std::array<std::size_t, 3> initialized with {sizeof(int), sizeof(float), sizeof(double)}:

Compare this to the following type-based approach, which produces the same array sizes:

On Compiler Explorer: EDG, Clang.

3.4 Implementing make_integer_sequence

We can provide a better implementation of make_integer_sequence than a hand-rolled approach using regular template metaprogramming (although standard libraries today rely on an intrinsic for this):

On Compiler Explorer: EDG, Clang.

Note that the memoization implicit in the template substitution process still applies. So having multiple uses of, e.g., make_integer_sequence<int, 20> will only involve one evaluation of make_integer_seq_refl<int>(20).

3.5 Getting Class Layout

On Compiler Explorer: EDG, Clang.

3.6 Enum to String

One of the most commonly requested facilities is to convert an enum value to a string (this example relies on expansion statements):

We can also do the reverse in pretty much the same way:

But we don’t have to use expansion statements - we can also use algorithms. For instance, enum_to_string can also be implemented this way (this example relies on non-transient constexpr allocation), which also demonstrates choosing a different algorithm based on the number of enumerators:

Note that this last version has lower complexity: While the versions using an expansion statement use an expected O(N) number of comparisons to find the matching entry, a std::map achieves the same with O(log(N)) complexity (where N is the number of enumerator constants).

On Compiler Explorer: EDG, Clang.

Many many variations of these functions are possible and beneficial depending on the needs of the client code. For example:

• the “” case could instead output a valid cast expression like “E(5)”
• a more sophisticated lookup algorithm could be selected at compile time depending on the length of enumerators_of(^E)
• a compact two-way persistent data structure could be generated to support both enum_to_string and string_to_enum with a minimal footprint
• etc.

3.7 Parsing Command-Line Options

Our next example shows how a command-line option parser could work by automatically inferring flags based on member names. A real command-line parser would of course be more complex, this is just the beginning.

This example is based on a presentation by Matúš Chochlík.

On Compiler Explorer: EDG, Clang.

3.8 A Simple Tuple Type

This example uses a “magic” std::meta::define_class template along with member reflection through the nonstatic_data_members_of metafunction to implement a std::tuple-like type without the usual complex and costly template metaprogramming tricks that that involves when these facilities are not available. define_class takes a reflection for an incomplete class or union plus a vector of nonstatic data member descriptions, and completes the give class or union type to have the described members.

On Compiler Explorer: EDG, Clang.

3.9 A Simple Variant Type

Similarly to how we can implement a tuple using define_class to create on the fly a type with one member for each Ts..., we can implement a variant that simply defines a union instead of a struct. One difference here is how the destructor of a union is currently defined:

U1 has a trivial destructor, but U2’s destructor is defined as deleted (because std::string has a non-trivial destructor). This is a problem because we need to define this thing… somehow. However, for the purposes of define_class, there really is only one reasonable option to choose here:

If we make define_class for a union have this behavior, then we can implement a variant in a much more straightforward way than in current implementations. This is not a complete implementation of std::variant (and cheats using libstdc++ internals, and also uses Boost.Mp11’s mp_with_index) but should demonstrate the idea:

Effectively, Variant<T, U> synthesizes a union type Storage which looks like this:

The question here is whether we should be should be able to directly initialize members of a defined union using a splicer, as in:

Arguably, the answer should be yes - this would be consistent with how other accesses work. This is instead proposed in [P3293R0].

On Compiler Explorer: EDG, Clang.

3.10 Struct to Struct of Arrays

Example:

Again, the combination of nonstatic_data_members_of and define_class is put to good use.

On Compiler Explorer: EDG, Clang.

3.11 Parsing Command-Line Options II

Now that we’ve seen a couple examples of using std::meta::define_class to create a type, we can create a more sophisticated command-line parser example.

This is the opening example for clap (Rust’s Command Line Argument Parser):

Which we can implement like this:

On Compiler Explorer: EDG, Clang.

3.12 A Universal Formatter

This example is taken from Boost.Describe:

On Compiler Explorer: Clang.

Note that currently, we do not have the ability to access a base class subobject using the t.[: base :] syntax - which means that the only way to get at the base is to use a cast:

• static_cast<[: type_of(base) const& :]>(t), or
• (typename [: type_of(base) :] const&)t

Both have to explicitly specify the const-ness of the type in the cast. The static_cast additionally has to check access. The C-style cast is one many people find unsavory, though in this case it avoids checking access - but requires writing typename since this isn’t a type-only context.

3.13 Implementing member-wise hash_append

Based on the [N3980] API:

3.14 Converting a Struct to a Tuple

This approach requires allowing packs in structured bindings [P1061R5], but can also be written using std::make_index_sequence:

An alternative approach is:

Here, type_struct_to_tuple takes a reflection of a type like struct { T t; U const& u; V v; } and returns a reflection of the type std::tuple<T, U, V>. That gives us the return type. Then, struct_to_tuple_helper is a function template that does the actual conversion — which it can do by having all the reflections of the members as a non-type template parameter pack. This is a constexpr function and not a consteval function because in the general case the conversion is a run-time operation. However, determining the instance of struct_to_tuple_helper that is needed is a compile-time operation and has to be performed with a consteval function (because the function invokes nonstatic_data_members_of), hence the separate function template get_struct_to_tuple_helper().

Everything is put together by using substitute to create the instantiation of struct_to_tuple_helper that we need, and a compile-time reference to that instance is obtained with extract. Thus f is a function reference to the correct specialization of struct_to_tuple_helper, which we can simply invoke.

On Compiler Explorer (with a different implementation than either of the above): EDG, Clang.

3.15 Implementing tuple_cat

Courtesy of Tomasz Kaminski, on compiler explorer:

3.16 Named Tuple

The tricky thing with implementing a named tuple is actually strings as non-type template parameters. Because you cannot just pass "x" into a non-type template parameter of the form auto V, that leaves us with two ways of specifying the constituents:

1. Can introduce a pair type so that we can write make_named_tuple<pair<int, "x">, pair<double, "y">>(), or
2. Can just do reflections all the way down so that we can write

make_named_tuple<^int, std::meta::reflect_result("x"),
                 ^double, std::meta::reflect_result("y")>()

We do not currently support splicing string literals, and the pair approach follows the similar pattern already shown with define_class (given a suitable fixed_string type):

On Compiler Explorer: EDG, Clang.

Alternatively, can side-step the question of non-type template parameters entirely by keeping everything in the value domain:

On Compiler Explorer: EDG and Clang (the EDG and Clang implementations differ only in Clang having the updated data_member_spec API that returns an info).

3.17 Compile-Time Ticket Counter

The features proposed here make it a little easier to update a ticket counter at compile time. This is not an ideal implementation (we’d prefer direct support for compile-time —– i.e., consteval — variables), but it shows how compile-time mutable state surfaces in new ways.

On Compiler Explorer: EDG, Clang.

3.18 Emulating typeful reflection

Although we believe a single opaque std::meta::info type to be the best and most scalable foundation for reflection, we acknowledge the desire expressed by SG7 for future support for “typeful reflection”. The following demonstrates one possible means of assembling a typeful reflection library, in which different classes of reflections are represented by distinct types, on top of the facilities proposed here.

We can leverage this machinery to select different function overloads based on the “type” of reflection provided as an argument.

Note that the metatype class can be generalized to wrap values of any literal type, or to wrap multiple values of possibly different types. This has been used, for instance, to select compile-time overloads based on: whether two integers share the same parity, the presence or absence of a value in an optional, the type of the value held by a variant or an any, or the syntactic form of a compile-time string.

Achieving the same in C++23, with the same generality, would require spelling the argument(s) twice: first to obtain a “classification tag” to use as a template argument, and again to call the function, i.e.,

On Compiler Explorer: Clang.

4 Proposed Features

4.1 The Reflection Operator (^)

The reflection operator produces a reflection value from a grammatical construct (its operand):

unary-expression:
      …
      ^ ::
      ^ namespace-name
      ^ type-id
      ^ id-expression

The expression ^:: evaluates to a reflection of the global namespace. When the operand is a namespace-name or type-id, the resulting value is a reflection of the designated namespace or type.

When the operand is an id-expression, the resulting value is a reflection of the designated entity found by lookup. This might be any of:

• a variable, static data member, or structured binding
• a function or member function
• a non-static data member
• a template or member template
• an enumerator

For all other operands, the expression is ill-formed. In a SFINAE context, a failure to substitute the operand of a reflection operator construct causes that construct to not evaluate to constant.

Earlier revisions of this paper allowed for taking the reflection of any cast-expression that could be evaluated as a constant expression, as we believed that a constant expression could be internally “represented” by just capturing the value to which it evaluated. However, the possibility of side effects from constant evaluation (introduced by this very paper) renders this approach infeasible: even a constant expression would have to be evaluated every time it’s spliced. It was ultimately decided to defer all support for expression reflection, but we intend to introduce it through a future paper using the syntax ^(expr).

This paper does, however, support reflections of values and of objects (including subobjects). One way to obtain such reflections is using the std::meta::reflect_result metafunction, which returns a reflection of the result of once evaluating its argument. The std::meta::value_of metafunction can also be used to obtain a reflection of the value stored by an entity (if the entity is usable in constant expressions). While it’s possible to support direct reflection of expression results (e.g., ^fn()), we aren’t convinced that this syntax provided enough value to justify its introduction at this time.

4.1.1 Syntax discussion

The original TS landed on reflexpr(...) as the syntax to reflect source constructs and [P1240R0] adopted that syntax as well. As more examples were discussed, it became clear that that syntax was both (a) too “heavy” and (b) insufficiently distinct from a function call. SG7 eventually agreed upon the prefix ^ operator. The “upward arrow” interpretation of the caret matches the “lift” or “raise” verbs that are sometimes used to describe the reflection operation in other contexts.

The caret already has a meaning as a binary operator in C++ (“exclusive OR”), but that is clearly not conflicting with a prefix operator. In C++/CLI (a Microsoft C++ dialect) the caret is also used as a new kind of ptr-operator (9.3.1 [dcl.decl.general]) to declare “handles”. That is also not conflicting with the use of the caret as a unary operator because C++/CLI uses the usual prefix * operator to dereference handles.

Apple also uses the caret in syntax “blocks” and unfortunately we believe that does conflict with our proposed use of the caret.

Since the syntax discussions in SG7 landed on the use of the caret, new basic source characters have become available: @, `, and $. While we have since discussed some alternatives (e.g., @ for lifting, \ and / for “raising” and “lowering”), we have grown quite fond of the existing syntax.

4.2 Splicers ([:…:])

A reflection can be “spliced” into source code using one of several splicer forms:

• [: r :] produces an expression evaluating to the entity represented by r in grammatical contexts that permit expressions. In type-only contexts (13.8.1 [temp.res.general]/4), [: r :] produces a type (and r must be the reflection of a type). In contexts that only permit a namespace name, [: r :] produces a namespace (and r must be the reflection of a namespace or alias thereof).
• typename[: r :] produces a simple-type-specifier corresponding to the type represented by r.
• template[: r :] produces a template-name corresponding to the template represented by r.
• [:r:]:: produces a nested-name-specifier corresponding to the namespace, enumeration type, or class type represented by r.

The operand of a splicer is implicitly converted to a std::meta::info prvalue (i.e., if the operand expression has a class type that with a conversion function to convert to std::meta::info, splicing can still work).

Attempting to splice a reflection value that does not meet the requirement of the splice is ill-formed. For example:

4.2.1 Addressed Splicing

In the same way that &C::mem can produce a pointer, pointer to member data, pointer to function, or pointer to member function depending on what mem refers to, &[: r :] can likewise produce the same set of pointers if r is a reflection of a suitable entity:

• If r is a reflection of a static data member or a variable, &[:r:] is a pointer.
• Otherwise if r is a reflection of a non-static data member, &[:r:] is a pointer to data member.
• Otherwise, if r is a reflection of a static member function, a function, or a non-static member function with an explicit object parameter, &[:r:] is a pointer to function
• Otherwise, if r is a reflection of a non-static member function with an implicit object parameter, &[:r:] is a pointer to member function.
• Otherwise, if r is a reflection of a function template or member function template, &[:r:] is the address of that overload set - which would then require external context to resolve as usual.

For most members, this doesn’t even require any additional wording since that’s just what you get when you take the address of the splice based on the current rules we have today.

Now, there are a couple interesting cases to point out when &[:r:] isn’t just the same as &X::f.

When r is a reflection of a function or function template that is part of an overload set, overload resolution will not consider the whole overload set, just the specific function or function template that r reflects:

Another interesting question is what does this mean when r is the reflection of a constructor or destructor? Consider the type:

And let rc be a reflection of the constructor and rd be a reflection of the destructor. The sensible syntax and semantics for how you would use rc and rd should be as follows:

Or, with pointers:

That is, splicing a constructor behaves like a free function that produces an object of that type, so &[: rc :] has type X(*)(int, int). On the other hand, splicing a destructor behaves like a regular member function, so &[: rd :] has type void (X::*)().

However, we are not proposing splicing constructors or destructors at the moment.

4.2.2 Limitations

Splicers can appear in many contexts, but our implementation experience has uncovered a small set of circumstances in which a splicer must be disallowed. Mostly these are because any entity designated by a splicer can be dependent on a template argument, so any context in which the language already disallows a dependent name must also disallow a dependent splicer. It also becomes possible for the first time to have the “name” of a namespace or concept become dependent on a template argument. Our implementation experience has helped to sort through which uses of these dependent names pose no difficulties, and which must be disallowed.

This proposal places the following limitations on splicers.

4.2.2.1 Splicing reflections of constructors

Iterating over the members of a class (e.g., using std::meta::members_of) allows one, for the first time, to obtain “handles” representing constructors. An immediate question arises of whether it’s possible to reify these constructors to construct objects, or even to take their address. While we are very interested in exploring these ideas, we defer their discussion to a future paper; this proposal disallows splicing a reflection of a constructor (or constructor template) in any context.

4.2.2.2 Splicing namespaces in namespace definitions

namespace A {}
constexpr std::meta::info NS_A = ^A;

namespace B {
  namespace [:NS_A:] {
    void fn();  // Is this '::A::fn' or '::B::A::fn' ?
  }
}

We found no satisfying answer as to how to interpret examples like the one given above. Neither did we find motivating use cases: many of the “interesting” uses for reflections of namespaces are either to introspect their members, or to pass them as template arguments - but the above example does nothing to help with introspection, and neither can namespaces be reopened within any dependent context. Rather than choose between unintuitive options for a syntax without a motivating use case, we are disallowing splicers from appearing in the opening of a namespace.

4.2.2.3 Splicing namespaces in using-directives and using-enum-declarators

template <std::meta::info R> void fn1() {
  using enum [:R:]::EnumCls;  // #1
  // ...
}
template <std::meta::info R> void fn2() {
  using namespace [:R:];      // #2
  // ...
}

C++20 already disallowed dependent enumeration types from appearing in using-enum-declarators (as in #1), as it would otherwise force the parser to consider every subsequent identifier as possibly a member of the substituted enumeration type. We extend this limitation to splices of dependent reflections of enumeration types, and further disallow the use of dependent reflections of namespaces in using-directives (as in #2) following the same principle.

4.2.2.4 Splicing concepts in declarations of template parameters

template <typename T> concept C = requires { requires true; };

template <std::meta::info R> struct Outer {
  template <template [:R:] S> struct Inner { /* ... */ };
};

What kind of parameter is S? If R reflects a class template, then it is a non-type template parameter of deduced type, but if R reflects a concept, it is a type template parameter. There is no other circumstance in the language for which it is not possible to decide at parse time whether a template parameter is a type or a non-type, and we don’t wish to introduce one for this use case.

The most obvious solution would be to introduce a concept [:R:] syntax that requires that R reflect a concept, and while this could be added going forward, we weren’t convinced of its value at this time - especially since the above can easily be rewritten:

template <std::meta::info R> struct Outer {
  template <typename T> requires template [:R:]<T> { /* ... */ };
};

We are resolving this ambiguity by simply disallowing a reflection of a concept, whether dependent or otherwise, from being spliced in the declaration of a template parameter (thus in the above example, the parser can assume that S is a non-type parameter).

4.2.2.5 Splicing class members as designators in designated-initializer-lists

struct S { int a; };

constexpr S s = {.[:^S::a:] = 2};

Although we would like for splices of class members to be usable as designators in an initializer-list, we lack implementation experience with the syntax and would first like to verify that there are no issues with dependent reflections. We are very likely to propose this as an extension in a future paper.

4.2.3 Range Splicers

The splicers described above all take a single object of type std::meta::info (described in more detail below). However, there are many cases where we don’t have a single reflection, we have a range of reflections - and we want to splice them all in one go. For that, the predecessor to this paper, [P1240R0], proposed an additional form of splicer: a range splicer.

Construct the struct-to-tuple example from above. It was demonstrated using a single splice, but it would be simpler if we had a range splice:

template <typename T>
constexpr auto struct_to_tuple(T const& t) {
  constexpr auto members = nonstatic_data_members_of(^T);

  constexpr auto indices = []{
    std::array<int, members.size()> indices;
    std::ranges::iota(indices, 0);
    return indices;
  }();

  constexpr auto [...Is] = indices;
  return std::make_tuple(t.[: members[Is] :]...);
}

template <typename T>
constexpr auto struct_to_tuple(T const& t) {
  constexpr auto members = nonstatic_data_members_of(^T);
  return std::make_tuple(t.[: ...members :]...);
}

A range splice, [: ... r :], would accept as its argument a constant range of meta::info, r, and would behave as an unexpanded pack of splices. So the above expression

would evaluate as

This is a very useful facility indeed!

However, range splicing of dependent arguments is at least an order of magnitude harder to implement than ordinary splicing. We think that not including range splicing gives us a better chance of having reflection in C++26. Especially since, as this paper’s examples demonstrate, a lot can be done without them.

Another way to work around a lack of range splicing would be to implement with_size<N>(f), which would behave like f(integral_constant<size_t, 0>{}, integral_constant<size_t, 1>{}, ..., integral_constant<size_t, N-1>{}). Which is enough for a tolerable implementation:

4.2.4 Syntax discussion

Early discussions of splice-like constructs (related to the TS design) considered using unreflexpr(...) for that purpose. [P1240R0] adopted that option for expression splicing, observing that a single splicing syntax could not viably be parsed (some disambiguation is needed to distinguish types and templates). SG-7 eventually agreed to adopt the [: ... :] syntax — with disambiguating tokens such as typename where needed — which is a little lighter and more distinctive.

We propose [: and :] be single tokens rather than combinations of [, ], and :. Among others, it simplifies the handling of expressions like arr[[:refl():]]. On the flip side, it requires a special rule like the one that was made to handle <:: to leave the meaning of arr[::N] unchanged and another one to avoid breaking a (somewhat useless) attribute specifier of the form [[using ns:]].

A syntax that is delimited on the left and right is useful here because spliced expressions may involve lower-precedence operators. Additionally, it’s important that the left- and right-hand delimiters are different so as to allow nested splices when that comes up.

However, there are other possibilities. For example, now that $ or @ are available in the basic source character set, we might consider those. One option that was recently brought up was @ primary-expression which would allow writing @e for the simple identifier splices but for the more complex operations still require parenthesizing for readability. $<expr> is somewhat natural to those of us that have used systems where $ is used to expand placeholders in document templates:

There are two other pieces of functionality that we will probably need syntax for in the future:

• code injection (of whatever form), and
• annotations (reflectable attributes, as values. [P1887R1] suggested + as an annotation introducer, but + can begin an expression so another token is probably better. See also: this thread).

So any syntax discussion needs to consider the entirety of the feature.

The prefixes typename and template are only strictly needed in some cases where the operand of the splice is a dependent expression. In our proposal, however, we only make typename optional in the same contexts where it would be optional for qualified names with dependent name qualifiers. That has the advantage to catch unfortunate errors while keeping a single rule and helping human readers parse the intended meaning of otherwise ambiguous constructs.

4.3 std::meta::info

The type std::meta::info can be defined as follows:

In our initial proposal a value of type std::meta::info can represent:

• any (C++) type and type alias
• any function or member function
• any variable, static data member, or structured binding
• any non-static data member
• any enumerator
• any template
• any namespace (including the global namespace) or namespace alias
• any object that is a permitted result of a constant expression
• any value with structural type that is a permitted result of a constant expression
• the null reflection (when default-constructed)

We for now restrict the space of reflectable values to those of structural type in order to meet two requirements:

1. The compiler must know how to mangle any reflectable value (i.e., when a reflection thereof is used as a template argument).
2. The compiler must know how to compare any two reflectable values, ideally without interpreting user-defined comparison operators (i.e., to implement comparison between reflections).

Values of structural types can already be used as template arguments (so implementations must already know how to mangle them), and the notion of template-argument-equivalent values defined on the class of structural types helps guarantee that &fn<^value1> == &fn<^value2> if and only if &fn<value1> == &fn<value2>.

Notably absent at this time are reflections of expressions. For example, one might wish to walk over the subexpressions of a function call:

Previous revisions of this proposal suggested limited support for reflections of constant expressions. The introduction of side effects from constant evaluations (by this very paper), however, renders this roughly as difficult for constant expressions as it is for non-constant expressions. We instead defer all expression reflection to a future paper, and only present value and object reflection in the present proposal.

4.3.1 Comparing reflections

The type std::meta::info is a scalar type for which equality and inequality are meaningful, but for which no ordering relation is defined.

When the ^ operator is followed by an id-expression, the resulting std::meta::info reflects the entity named by the expression. Such reflections are equivalent only if they reflect the same entity.

For any other expression expr, the value ^expr is a reflection of the result of the expression. The expression is ill-formed if expr is a parenthesized expression.

4.3.2 Templates specialized by reflections

Nontype template arguments of type std::meta::info are permitted (and frequently useful!), but a specialized template whose argument reflects an entity local to a translation unit must itself necessarily have internal linkage. For example:

4.3.3 The associated std::meta namespace

The namespace std::meta is an associated type of std::meta::info, which allows standard library meta functions to be invoked without explicit qualification. For example:

Default constructing or value-initializing an object of type std::meta::info gives it a null reflection value. A null reflection value is equal to any other null reflection value and is different from any other reflection that refers to one of the mentioned entities. For example:

4.4 Metafunctions

We propose a number of metafunctions declared in namespace std::meta to operator on reflection values. Adding metafunctions to an implementation is expected to be relatively “easy” compared to implementing the core language features described previously. However, despite offering a normal consteval C++ function interface, each on of these relies on “compiler magic” to a significant extent.

4.4.1 Constant evaluation order

In C++23, “constant evaluation” produces pure values without observable side-effects and thus the order in which constant-evaluation occurs is immaterial. In fact, while the language is designed to permit constant evaluation to happen at compile time, an implementation is not strictly required to take advantage of that possibility.

Some of the proposed metafunctions, however, have side-effects that have an effect on the remainder of the program. For example, we provide a define_class metafunction that provides a definition for a given class. Clearly, we want the effect of calling that metafunction to be “prompt” in a lexical-order sense. For example:

Hence this proposal also introduces constraints on constant evaluation as follows…

First, we identify a subset of manifestly constant-evaluated expressions and conversions characterized by the fact that their evaluation must occur and must succeed in a valid C++ program: We call these plainly constant-evaluated. We require that a programmer can count on those evaluations occurring exactly once and completing at translation time.

Second, we sequence plainly constant-evaluated expressions and conversions within the lexical order. Specifically, we require that the evaluation of a plainly constant-evaluated expression or conversion occurs before the implementation checks the validity of source constructs lexically following that expression or conversion.

Those constraints are mostly intuitive, but they are a significant change to the underlying principles of the current standard in this respect.

[P2758R1] (“Emitting messages at compile time”) also has to deal with side effects during constant evaluation. However, those effects (“output”) are of a slightly different nature in the sense that they can be buffered until a manifestly constant-evaluated expression/conversion has completed. “Buffering” a class type completion is not practical (e.g., because other metafunctions may well depend on the completed class type). Still, we are not aware of incompatibilities between our proposal and [P2758R1].

4.4.2 Error-Handling in Reflection

Earlier revisions of this proposal suggested several possible approaches to handling errors in reflection metafunctions. This question arises naturally when considering, for instance, examples like template_of(^int): the argument is a reflection of a type, but that type is not a specialization of a template, so there is no valid reflected template for us to return.

Some of the possibilities that we have considered include:

1. Returning an invalid reflection (similar to NaN for floating point) which carries source location info and some useful message (i.e., the approach suggested by P1240)
2. Returning a std::expected<std::meta::info, E> for some reflection-specific error type E, which carries source location info and some useful message
3. Failing to be a constant expression
4. Throwing an exception of type E, which requires a language extension for such exceptions to be catchable during constexpr evaluation

We found that we disliked (1) since there is no satisfying value that can be returned for a call like template_arguments_of(^int): We could return a std::vector<std::meta::info> having a single invalid reflection, but this makes for awkward error handling. The experience offered by (3) is at least consistent, but provides no immediate means for a user to “recover” from an error.

Either std::expected or constexpr exceptions would allow for a consistent and straightforward interface. Deciding between the two, we noticed that many of usual concerns about exceptions do not apply during translation:

• concerns about runtime performance, object file size, etc. do not exist, and
• concerns about code evolving to add new uncaught exception types do not apply

An interesting example illustrates one reason for our preference for exceptions over std::expected:

• If template_of returns an expected<info, E>, then foo<int> is a substitution failure — expected<T, E> is equality-comparable to T, that comparison would evaluate to false but still be a constant expression.

• If template_of returns info but throws an exception, then foo<int> would cause that exception to be uncaught, which would make the comparison not a constant expression. This actually makes the constraint ill-formed - not a substitution failure. In order to have foo<int> be a substitution failure, either the constraint would have to first check that T is a template or we would have to change the language rule that requires constraints to be constant expressions (we would of course still keep the requirement that the constraint is a bool).

Since the R2 revision of this paper, [P3068R1] has proposed the introduction of constexpr exceptions. The proposal addresses hurdles like compiler modes that disable exception support, and a Clang-based implementation is underway. We believe this to be the most desirable error-handling mechanism for reflection metafunctions.

Because constexpr exceptions have not yet been adopted into the working draft, we do not specify any functions in this paper that throw exceptions. Rather, we propose that they fail to be constant expressions (i.e., case 3 above), and note that this approach will allow us to forward-compatibly add exceptions at a later time. In the interim period, implementations should have all of the information needed to issue helpful diagnostics (e.g., “note: R does not reflect a template specialization”) to improve the experience of writing reflection code.

4.4.3 Range-Based Metafunctions

There are a number of functions, both in the “core” reflection API that we intend to provide as well as converting some of the standard library type traits that can accept or return a range of std::meta::info.

For example:

• template_arguments_of(^std::tuple<int>) is {^int}
• substitute(^std::tuple, {^int}) is ^std::tuple<int>

This requires us to answer the question: how do we accept a range parameter and how do we provide a range return.

For return, we intend on returning std::vector<std::meta::info> from all such APIs. This is by far the easiest for users to deal with. We definitely don’t want to return a std::span<std::meta::info const>, since this requires keeping all the information in the compiler memory forever (unlike std::vector which could free its allocation). The only other option would be a custom container type which is optimized for compile-time by being able to produce elements lazily on demand - i.e. so that nonstatic_data_members_of(^T)[3] wouldn’t have to populate all the data members, just do enough work to be able to return the 4th one. But that adds a lot of complexity that’s probably not worth the effort.

For parameters, there are basically three options:

1. Accept std::span<std::meta::info const>, which now accepts braced-init-list arguments so it’s pretty convenient in this regard.
2. Accept std::vector<std::meta::info>
3. Accept any range whose type_value is std::meta::info.

Now, for compiler efficiency reasons, it’s definitely better to have all the arguments contiguously. So the compiler wants span. There’s really no reason to prefer vector over span. Accepting any range would look something like this:

This API is more user friendly than accepting span<info const> by virtue of simply accepting more kinds of ranges. The default template argument allows for braced-init-lists to still work. Example.

Specifically, if the user is doing anything with range adaptors, they will either end up with a non-contiguous or non-sized range, which will no longer be convertible to span - so they will have to manually convert their range to a vector<info> in order to pass it to the algorithm. Because the implementation wants contiguity anyway, that conversion to vector will happen either way - so it’s just a matter of whether every call needs to do it manually or the implementation can just do it once.

For example, converting a struct to a tuple type:

consteval auto type_struct_to_tuple(info type) -> meta::info {
    return substitute(
        ^tuple,
        nonstatic_data_members_of(type)
        | views::transform(meta::type_of)
        | views::transform(meta::type_remove_cvref)
        | ranges::to<vector>());
}

consteval auto type_struct_to_tuple(info type) -> meta::info {
    return substitute(
        ^tuple,
        nonstatic_data_members_of(type)
        | views::transform(meta::type_of)
        | views::transform(meta::type_remove_cvref)
        );
}

This shouldn’t cause much compilation overhead. Checking convertibility to span already uses Ranges machinery. And implementations can just do the right thing interally:

As such, we propose that all the range-accepting algorithms accept any range.

4.4.4 Handling Aliases

Consider

In C++ today, A and int can be used interchangeably and there is no distinction between the two types. With reflection as proposed in this paper, that will no longer be the case. ^A yields a reflection of an alias to int, while ^int yields a reflection of int. ^A == ^int evaluates to false, but there will be a way to strip aliases - so dealias(^A) == ^int evaluates to true.

This opens up the question of how various other metafunctions handle aliases and it is worth going over a few examples:

This paper is proposing that:

• is_type(^A) is true. ^A is an alias, but it’s an alias to a type, and if this evaluated as false then everyone would have to dealias everything all the time.
• has_template_arguments(^B) is false while has_template_arguments(^C<int>) is true. Even though B is an alias to a type that itself has template arguments (unique_ptr<int>), B itself is simply a type alias and does not. This reflects the actual usage.
• Meanwhile, template_arguments_of(^C<int>) yields {^int} while template_arguments_of(^std::unique_ptr<int>) yields {^int, ^std::default_deleter<int>}. This is C has its own template arguments that can be reflected on.

4.4.5 Reflecting source text

One of the most “obvious” abilities of reflection — retrieving the name of an entity — turns out to raise issues that aren’t obvious at all: How do we represent source text in a C++ program.

Thanks to recent work originating in SG16 (the “Unicode” study group) we can assume that all source code is ultimately representable as Unicode code points. C++ now also has types to represent UTF-8-encoded text (incl. char8_t, u8string, and u8string_view) and corresponding literals like u8"Hi". Unfortunately, what can be done with those types is still limited at the time of this writing. For example,