Files
entt/md_docs_md_meta.html
2019-12-19 15:16:07 +01:00

334 lines
36 KiB
HTML

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.16"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>EnTT: Crash Course: runtime reflection system</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">EnTT
&#160;<span id="projectnumber">3.2.2</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.16 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
</div><!-- top -->
<div class="PageDoc"><div class="header">
<div class="headertitle">
<div class="title">Crash Course: runtime reflection system </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="autotoc_md72"></a>
Introduction</h1>
<p>Reflection (or rather, its lack) is a trending topic in the C++ world and, in the specific case of <code>EnTT</code>, a tool that can unlock a lot of other features. I looked for a third-party library that met my needs on the subject, but I always came across some details that I didn't like: macros, being intrusive, too many allocations. In one word: unsatisfactory.<br />
I finally decided to write a built-in, non-intrusive and macro-free runtime reflection system for <code>EnTT</code>. Maybe I didn't do better than others or maybe yes, time will tell me, but at least I can model this tool around the library to which it belongs and not vice versa.</p>
<h1><a class="anchor" id="autotoc_md73"></a>
Names and identifiers</h1>
<p>The meta system doesn't force the user to use the tools provided by the library when it comes to working with names and identifiers. It does this by offering an API that works with opaque identifiers that may or may not be generated by means of a hashed string.<br />
This means that users can assign any type of identifier to the meta objects, as long as they are numeric. It doesn't matter if they are generated at runtime, at compile-time or with custom functions.</p>
<p>However, the examples in the following sections are all based on the <code>hashed_string</code> class as provided by this library. Therefore, where an identifier is required, it's likely that a user defined literal is used as follows:</p>
<div class="fragment"><div class="line"><span class="keyword">auto</span> factory = entt::meta&lt;my_type&gt;().type(<span class="stringliteral">&quot;reflected_type&quot;</span>_hs);</div>
</div><!-- fragment --><p>For what it's worth, this is likely completely equivalent to:</p>
<div class="fragment"><div class="line"><span class="keyword">auto</span> factory = entt::meta&lt;my_type&gt;().type(42);</div>
</div><!-- fragment --><p>Obviously, human-readable identifiers are more convenient to use and highly recommended.</p>
<h1><a class="anchor" id="autotoc_md74"></a>
Reflection in a nutshell</h1>
<p>Reflection always starts from real types (users cannot reflect imaginary types and it would not make much sense, we wouldn't be talking about reflection anymore).<br />
To create a meta node, the library provides the <code>meta</code> function that accepts a type to reflect as a template parameter:</p>
<div class="fragment"><div class="line"><span class="keyword">auto</span> factory = entt::meta&lt;my_type&gt;();</div>
</div><!-- fragment --><p>This isn't enough to <em>export</em> the given type and make it visible though.<br />
The returned value is a factory object to use to continue building the meta type. In order to make the type <em>visible</em>, users can assign it an identifier:</p>
<div class="fragment"><div class="line"><span class="keyword">auto</span> factory = entt::meta&lt;my_type&gt;().type(<span class="stringliteral">&quot;reflected_type&quot;</span>_hs);</div>
</div><!-- fragment --><p>When working with named types, it isn't even necessary to specify the identifier. In fact, it isn't allowed and it will trigger a compilation error.<br />
Identifiers are important because users can retrieve meta types at runtime by searching for them by <em>name</em> other than by type. On the other hand, there are cases in which users can be interested in adding features to a reflected type so that the reflection system can use it correctly under the hood, but they don't want to allow searching the type by <em>name</em>. In this case, it's sufficient not to invoke <code>type</code> and the type will not be searchable <em>by name</em>.</p>
<p>A factory is such that all its member functions returns the factory itself or a decorated version of it. This object can be used to add the following:</p>
<ul>
<li><em>Constructors</em>. Actual constructors can be assigned to a reflected type by specifying their list of arguments. Free functions (namely, factories) can be used as well, as long as the return type is the expected one. From a client's point of view, nothing changes if a constructor is a free function or an actual constructor.<br />
Use the <code>ctor</code> member function for this purpose:</li>
</ul>
<div class="fragment"><div class="line">entt::meta&lt;my_type&gt;().ctor&lt;int, <span class="keywordtype">char</span>&gt;().ctor&lt;&amp;factory&gt;();</div>
</div><!-- fragment --><ul>
<li><em>Destructors</em>. Free functions can be set as destructors of reflected types. The purpose is to give users the ability to free up resources that require special treatment before an object is actually destroyed.<br />
Use the <code>dtor</code> member function for this purpose:</li>
</ul>
<div class="fragment"><div class="line">entt::meta&lt;my_type&gt;().dtor&lt;&amp;destroy&gt;();</div>
</div><!-- fragment --><p>A function should neither delete nor explicitly invoke the destructor of a given instance.</p>
<ul>
<li><em>Data members</em>. Both real data members of the underlying type and static and global variables, as well as constants of any kind, can be attached to a meta type. From a client's point of view, all the variables associated with the reflected type will appear as if they were part of the type itself.<br />
Use the <code>data</code> member function for this purpose:</li>
</ul>
<div class="fragment"><div class="line">entt::meta&lt;my_type&gt;()</div>
<div class="line"> .data&lt;&amp;my_type::static_variable&gt;(<span class="stringliteral">&quot;static&quot;</span>_hs)</div>
<div class="line"> .data&lt;&amp;my_type::data_member&gt;(<span class="stringliteral">&quot;member&quot;</span>_hs)</div>
<div class="line"> .data&lt;&amp;global_variable&gt;(<span class="stringliteral">&quot;global&quot;</span>_hs);</div>
</div><!-- fragment --><p>This function requires as an argument the identifier to give to the meta data once created. Users can then access meta data at runtime by searching for them by <em>name</em>.<br />
Data members can be set also by means of a couple of functions, namely a setter and a getter. Setters and getters can be either free functions, member functions or mixed ones, as long as they respect the required signatures.<br />
Refer to the inline documentation for all the details.</p>
<ul>
<li><em>Member functions</em>. Both real member functions of the underlying type and free functions can be attached to a meta type. From a client's point of view, all the functions associated with the reflected type will appear as if they were part of the type itself.<br />
Use the <code>func</code> member function for this purpose:</li>
</ul>
<div class="fragment"><div class="line">entt::meta&lt;my_type&gt;()</div>
<div class="line"> .func&lt;&amp;my_type::static_function&gt;(<span class="stringliteral">&quot;static&quot;</span>_hs)</div>
<div class="line"> .func&lt;&amp;my_type::member_function&gt;(<span class="stringliteral">&quot;member&quot;</span>_hs)</div>
<div class="line"> .func&lt;&amp;free_function&gt;(<span class="stringliteral">&quot;free&quot;</span>_hs);</div>
</div><!-- fragment --><p>This function requires as an argument the identifier to give to the meta function once created. Users can then access meta functions at runtime by searching for them by <em>name</em>.</p>
<ul>
<li><em>Base classes</em>. A base class is such that the underlying type is actually derived from it. In this case, the reflection system tracks the relationship and allows for implicit casts at runtime when required.<br />
Use the <code>base</code> member function for this purpose:</li>
</ul>
<div class="fragment"><div class="line">entt::meta&lt;derived_type&gt;().base&lt;base_type&gt;();</div>
</div><!-- fragment --><p>From now on, wherever a <code>base_type</code> is required, an instance of <code>derived_type</code> will also be accepted.</p>
<ul>
<li><em>Conversion functions</em>. Actual types can be converted, this is a fact. Just think of the relationship between a <code>double</code> and an <code>int</code> to see it. Similar to bases, conversion functions allow users to define conversions that will be implicitly performed by the reflection system when required.<br />
Use the <code>conv</code> member function for this purpose:</li>
</ul>
<div class="fragment"><div class="line">entt::meta&lt;double&gt;().conv&lt;<span class="keywordtype">int</span>&gt;();</div>
</div><!-- fragment --><p>That's all, everything users need to create meta types and enjoy the reflection system. At first glance it may not seem that much, but users usually learn to appreciate it over time.<br />
Also, do not forget what these few lines hide under the hood: a built-in, non-intrusive and macro-free system for reflection in C++. Features that are definitely worth the price, at least for me.</p>
<h2><a class="anchor" id="autotoc_md75"></a>
Any as in any type</h2>
<p>The reflection system comes with its own <code>meta_any</code> type. It may seem redundant since C++17 introduced <code>std::any</code>, but it is not.<br />
In fact, the <em>type</em> returned by an <code>std::any</code> is a const reference to an <code>std::type_info</code>, an implementation defined class that's not something everyone wants to see in a software. Furthermore, the class <code>std::type_info</code> suffers from some design flaws and there is even no way to <em>convert</em> an <code>std::type_info</code> into a meta type, thus linking the two worlds.</p>
<p>The class <code>meta_any</code> offers an API similar to that of its most famous counterpart and serves the same purpose of being an opaque container for any type of value.<br />
It minimizes the allocations required, which are almost absent thanks to <em>SBO</em> techniques. In fact, unless users deal with <em>fat types</em> and create instances of them through the reflection system, allocations are at zero.</p>
<p>Creating instances of <code>meta_any</code>, whether empty or from existing objects, is trivial:</p>
<div class="fragment"><div class="line"><span class="comment">// a container for an int</span></div>
<div class="line"><a class="code" href="classentt_1_1meta__any.html">entt::meta_any</a> any{0};</div>
<div class="line"> </div>
<div class="line"><span class="comment">// an empty container</span></div>
<div class="line"><a class="code" href="classentt_1_1meta__any.html">entt::meta_any</a> empty{};</div>
</div><!-- fragment --><p>The <code>meta_any</code> class takes also the burden of destroying the contained object when required.<br />
Furthermore, an instance of <code>meta_any</code> is not tied to a specific type. Therefore, the wrapper will be reconfigured by assigning it an object of a different type than the one contained, so as to be able to handle the new instance.</p>
<p>A particularly interesting feature of this class is that it can also be used as an opaque container for unmanaged objects:</p>
<div class="fragment"><div class="line"><span class="keywordtype">int</span> value;</div>
<div class="line"><a class="code" href="classentt_1_1meta__any.html">entt::meta_any</a> any{std::ref(value)};</div>
</div><!-- fragment --><p>In other words, whenever <code>meta_any</code> intercepts a <code>reference_wrapper</code>, it acts as a reference to the original instance rather than making a copy of it. The contained object is never destroyed and users must ensure that its lifetime exceeds that of the container.</p>
<p>The <code>meta_any</code> class has also a <code>type</code> member function that returns the meta type of the contained value, if any. The member functions <code>try_cast</code>, <code>cast</code> and <code>convert</code> are used to know if the underlying object has a given type as a base or if it can be converted implicitly to it.</p>
<h2><a class="anchor" id="autotoc_md76"></a>
Enjoy the runtime</h2>
<p>Once the web of reflected types has been constructed, it's a matter of using it at runtime where required.<br />
All this has the great merit that, unlike the vast majority of the things present in this library and closely linked to the compile-time, the reflection system stands in fact as a non-intrusive tool for the runtime.</p>
<p>To search for a reflected type there are two options: by type or by <em>name</em>. In both cases, the search can be done by means of the <code>resolve</code> function:</p>
<div class="fragment"><div class="line"><span class="comment">// search for a reflected type by type</span></div>
<div class="line"><span class="keyword">auto</span> by_type = entt::resolve&lt;my_type&gt;();</div>
<div class="line"> </div>
<div class="line"><span class="comment">// search for a reflected type by name</span></div>
<div class="line"><span class="keyword">auto</span> by_name = <a class="code" href="namespaceentt.html#a2129cb8668f5dcbc11854be6a4a0b6e5">entt::resolve</a>(<span class="stringliteral">&quot;reflected_type&quot;</span>_hs);</div>
</div><!-- fragment --><p>There exits also a third overload of the <code>resolve</code> function to use to iterate all the reflected types at once:</p>
<div class="fragment"><div class="line"><a class="code" href="namespaceentt.html#a2129cb8668f5dcbc11854be6a4a0b6e5">resolve</a>([](<span class="keyword">auto</span> type) {</div>
<div class="line"> <span class="comment">// ...</span></div>
<div class="line">});</div>
</div><!-- fragment --><p>In all cases, the returned value is an instance of <code>meta_type</code>. This kind of objects offer an API to know their <em>runtime identifiers</em>, to iterate all the meta objects associated with them and even to build or destroy instances of the underlying type.<br />
Refer to the inline documentation for all the details.</p>
<p>The meta objects that compose a meta type are accessed in the following ways:</p>
<ul>
<li><em>Meta constructors</em>. They are accessed by types of arguments:</li>
</ul>
<div class="fragment"><div class="line"><span class="keyword">auto</span> ctor = entt::resolve&lt;my_type&gt;().ctor&lt;int, <span class="keywordtype">char</span>&gt;();</div>
</div><!-- fragment --><p>The returned type is <code>meta_ctor</code> and may be invalid if there is no constructor that accepts the supplied arguments or at least some types from which they are derived or to which they can be converted.<br />
A meta constructor offers an API to know the number of arguments, the expected meta types and to invoke it, therefore to construct a new instance of the underlying type.</p>
<ul>
<li><em>Meta destructor</em>. It's returned by a dedicated function:</li>
</ul>
<div class="fragment"><div class="line"><span class="keyword">auto</span> dtor = entt::resolve&lt;my_type&gt;().dtor();</div>
</div><!-- fragment --><p>The returned type is <code>meta_dtor</code> and may be invalid if there is no custom destructor set for the given meta type.<br />
All what a meta destructor has to offer is a way to invoke it on a given instance. Be aware that the result may not be what is expected.</p>
<ul>
<li><em>Meta data</em>. They are accessed by <em>name</em>:</li>
</ul>
<div class="fragment"><div class="line"><span class="keyword">auto</span> data = entt::resolve&lt;my_type&gt;().data(<span class="stringliteral">&quot;member&quot;</span>_hs);</div>
</div><!-- fragment --><p>The returned type is <code>meta_data</code> and may be invalid if there is no meta data object associated with the given identifier.<br />
A meta data object offers an API to query the underlying type (for example, to know if it's a const or a static one), to get the meta type of the variable and to set or get the contained value.</p>
<ul>
<li><em>Meta functions</em>. They are accessed by <em>name</em>:</li>
</ul>
<div class="fragment"><div class="line"><span class="keyword">auto</span> func = entt::resolve&lt;my_type&gt;().func(<span class="stringliteral">&quot;member&quot;</span>_hs);</div>
</div><!-- fragment --><p>The returned type is <code>meta_func</code> and may be invalid if there is no meta function object associated with the given identifier.<br />
A meta function object offers an API to query the underlying type (for example, to know if it's a const or a static function), to know the number of arguments, the meta return type and the meta types of the parameters. In addition, a meta function object can be used to invoke the underlying function and then get the return value in the form of a <code>meta_any</code> object.</p>
<ul>
<li><em>Meta bases</em>. They are accessed through the <em>name</em> of the base types:</li>
</ul>
<div class="fragment"><div class="line"><span class="keyword">auto</span> base = entt::resolve&lt;derived_type&gt;().base(<span class="stringliteral">&quot;base&quot;</span>_hs);</div>
</div><!-- fragment --><p>The returned type is <code>meta_base</code> and may be invalid if there is no meta base object associated with the given identifier.<br />
Meta bases aren't meant to be used directly, even though they are freely accessible. They expose only a few methods to use to know the meta type of the base class and to convert a raw pointer between types.</p>
<ul>
<li><em>Meta conversion functions</em>. They are accessed by type:</li>
</ul>
<div class="fragment"><div class="line"><span class="keyword">auto</span> conv = entt::resolve&lt;double&gt;().conv&lt;<span class="keywordtype">int</span>&gt;();</div>
</div><!-- fragment --><p>The returned type is <code>meta_conv</code> and may be invalid if there is no meta conversion function associated with the given type.<br />
The meta conversion functions are as thin as the meta bases and with a very similar interface. The sole difference is that they return a newly created instance wrapped in a <code>meta_any</code> object when they convert between different types.</p>
<p>All the objects thus obtained as well as the meta types can be explicitly converted to a boolean value to check if they are valid:</p>
<div class="fragment"><div class="line"><span class="keywordflow">if</span>(<span class="keyword">auto</span> func = entt::resolve&lt;my_type&gt;().func(<span class="stringliteral">&quot;member&quot;</span>_hs); func) {</div>
<div class="line"> <span class="comment">// ...</span></div>
<div class="line">}</div>
</div><!-- fragment --><p>Furthermore, all meta objects with the exception of meta destructors can be iterated through an overload that accepts a callback through which to return them. As an example:</p>
<div class="fragment"><div class="line">entt::resolve&lt;my_type&gt;().data([](<span class="keyword">auto</span> data) {</div>
<div class="line"> <span class="comment">// ...</span></div>
<div class="line">});</div>
</div><!-- fragment --><p>A meta type can also be used to <code>construct</code> or <code>destroy</code> actual instances of the underlying type.<br />
In particular, the <code>construct</code> member function accepts a variable number of arguments and searches for a match. It returns a <code>meta_any</code> object that may or may not be initialized, depending on whether a suitable constructor has been found or not. On the other side, the <code>destroy</code> member function accepts instances of <code>meta_any</code> as well as actual objects by reference and invokes the registered destructor, if any.<br />
Be aware that the result of a call to <code>destroy</code> may not be what is expected. The purpose is to give users the ability to free up resources that require special treatment and <b>not</b> to actually destroy instances.</p>
<p>Meta types and meta objects in general contain much more than what is said: a plethora of functions in addition to those listed whose purposes and uses go unfortunately beyond the scope of this document.<br />
I invite anyone interested in the subject to look at the code, experiment and read the inline documentation to get the best out of this powerful tool.</p>
<h2><a class="anchor" id="autotoc_md77"></a>
Policies: the more, the less</h2>
<p>Policies are a kind of compile-time directives that can be used when recording reflection information.<br />
Their purpose is to require slightly different behavior than the default in some specific cases. For example, when reading a given data member, its value is returned wrapped in a <code>meta_any</code> object which, by default, makes a copy of it. For large objects or if the caller wants to access the original instance, this behavior isn't desirable. Policies are there to offer a solution to this and other problems.</p>
<p>There are a few alternatives available at the moment:</p>
<ul>
<li>The <em>as-is</em> policy, associated with the type <code><a class="el" href="structentt_1_1as__is__t.html" title="Empty class type used to request the as-is policy.">entt::as_is_t</a></code>.<br />
This is the default policy. In general, it should never be used explicitly, since it's implicitly selected if no other policy is specified.<br />
In this case, the return values of the functions as well as the properties exposed as data members are always returned by copy in a dedicated wrapper and therefore associated with their original meta types.</li>
<li><p class="startli">The <em>as-void</em> policy, associated with the type <code><a class="el" href="structentt_1_1as__void__t.html" title="Empty class type used to request the as void policy.">entt::as_void_t</a></code>.<br />
Its purpose is to discard the return value of a meta object, whatever it is, thus making it appear as if its type were <code>void</code>.<br />
If the use with functions is obvious, it must be said that it's also possible to use this policy with constructors and data members. In the first case, the constructor will be invoked but the returned wrapper will actually be empty. In the second case, instead, the property will not be accessible for reading.</p>
<p class="startli">As an example of use:</p>
</li>
</ul>
<div class="fragment"><div class="line">entt::meta&lt;my_type&gt;().func&lt;&amp;my_type::member_function, <a class="code" href="structentt_1_1as__void__t.html">entt::as_void_t</a>&gt;(<span class="stringliteral">&quot;member&quot;</span>_hs);</div>
</div><!-- fragment --><ul>
<li><p class="startli">The <em>as-alias</em> policy, associated with the type <code><a class="el" href="structentt_1_1as__alias__t.html" title="Empty class type used to request the as alias policy.">entt::as_alias_t</a></code>.<br />
It allows to build wrappers that act as aliases for the objects used to initialize them. Modifying the object contained in the wrapper for which the <em>aliasing</em> was requested will make it possible to directly modify the instance used to initialize the wrapper itself.<br />
This policy works with constructors (for example, when objects are taken from an external container rather than created on demand), data members and functions in general (as long as their return types are lvalue references).</p>
<p class="startli">As an example of use:</p>
</li>
</ul>
<div class="fragment"><div class="line">entt::meta&lt;my_type&gt;().data&lt;&amp;my_type::data_member, <a class="code" href="structentt_1_1as__alias__t.html">entt::as_alias_t</a>&gt;(<span class="stringliteral">&quot;member&quot;</span>_hs);</div>
</div><!-- fragment --><p>Some uses are rather trivial, but it's useful to note that there are some less obvious corner cases that can in turn be solved with the use of policies.</p>
<h2><a class="anchor" id="autotoc_md78"></a>
Named constants and enums</h2>
<p>A special mention should be made for constant values and enums. It wouldn't be necessary, but it will help distracted readers.</p>
<p>As mentioned, the <code>data</code> member function can be used to reflect constants of any type among the other things.<br />
This allows users to create meta types for enums that will work exactly like any other meta type built from a class. Similarly, arithmetic types can be enriched with constants of special meaning where required.<br />
Personally, I find it very useful not to export what is the difference between enums and classes in C++ directly in the space of the reflected types.</p>
<p>All the values thus exported will appear to users as if they were constant data members of the reflected types.</p>
<p>Exporting constant values or elements from an enum is as simple as ever:</p>
<div class="fragment"><div class="line">entt::meta&lt;my_enum&gt;()</div>
<div class="line"> .data&lt;my_enum::a_value&gt;(<span class="stringliteral">&quot;a_value&quot;</span>_hs)</div>
<div class="line"> .data&lt;my_enum::another_value&gt;(<span class="stringliteral">&quot;another_value&quot;</span>_hs);</div>
<div class="line"> </div>
<div class="line">entt::meta&lt;int&gt;().data&lt;2048&gt;(<span class="stringliteral">&quot;max_int&quot;</span>_hs);</div>
</div><!-- fragment --><p>It goes without saying that accessing them is trivial as well. It's a matter of doing the following, as with any other data member of a meta type:</p>
<div class="fragment"><div class="line"><span class="keyword">auto</span> value = entt::resolve&lt;my_enum&gt;().data(<span class="stringliteral">&quot;a_value&quot;</span>_hs).get({}).cast&lt;my_enum&gt;();</div>
<div class="line"><span class="keyword">auto</span> max = entt::resolve&lt;int&gt;().data(<span class="stringliteral">&quot;max_int&quot;</span>_hs).get({}).cast&lt;int&gt;();</div>
</div><!-- fragment --><p>As a side note, remember that all this happens behind the scenes without any allocation because of the small object optimization performed by the <code>meta_any</code> class.</p>
<h2><a class="anchor" id="autotoc_md79"></a>
Properties and meta objects</h2>
<p>Sometimes (for example, when it comes to creating an editor) it might be useful to attach properties to the meta objects created. Fortunately, this is possible for most of them.<br />
For the meta objects that support properties, the member functions of the factory used for registering them will return a decorated version of the factory itself. The latter can be used to attach properties to the last created meta object.<br />
Apparently, it's more difficult to say than to do:</p>
<div class="fragment"><div class="line">entt::meta&lt;my_type&gt;().type(<span class="stringliteral">&quot;reflected_type&quot;</span>_hs).prop(<span class="stringliteral">&quot;tooltip&quot;</span>_hs, <span class="stringliteral">&quot;message&quot;</span>);</div>
</div><!-- fragment --><p>Properties are always in the key/value form. There are no restrictions on the type of the key or value, as long as they are copy constructible objects.<br />
Multiple formats are supported when it comes to defining a property:</p>
<ul>
<li>Properties as key/value pairs:</li>
</ul>
<div class="fragment"><div class="line">entt::meta&lt;my_type&gt;().type(<span class="stringliteral">&quot;reflected_type&quot;</span>_hs).prop(<span class="stringliteral">&quot;tooltip&quot;</span>_hs, <span class="stringliteral">&quot;message&quot;</span>);</div>
</div><!-- fragment --><ul>
<li>Properties as <code>std::pair</code>s:</li>
</ul>
<div class="fragment"><div class="line">entt::meta&lt;my_type&gt;().type(<span class="stringliteral">&quot;reflected_type&quot;</span>_hs).prop(std::make_pair(<span class="stringliteral">&quot;tooltip&quot;</span>_hs, <span class="stringliteral">&quot;message&quot;</span>));</div>
</div><!-- fragment --><ul>
<li>Key only properties:</li>
</ul>
<div class="fragment"><div class="line">entt::meta&lt;my_type&gt;().type(<span class="stringliteral">&quot;reflected_type&quot;</span>_hs).prop(my_enum::key_only);</div>
</div><!-- fragment --><ul>
<li>Properties as <code>std::tuple</code>s:</li>
</ul>
<div class="fragment"><div class="line">entt::meta&lt;my_type&gt;().type(<span class="stringliteral">&quot;reflected_type&quot;</span>_hs)</div>
<div class="line"> .prop(std::make_tuple(std::make_pair(<span class="stringliteral">&quot;tooltip&quot;</span>_hs, <span class="stringliteral">&quot;message&quot;</span>), my_enum::key_only));</div>
</div><!-- fragment --><p>A tuple contains one or more properties. All of them are treated individually.</p>
<ul>
<li>Annotations:</li>
</ul>
<div class="fragment"><div class="line">entt::meta&lt;my_type&gt;().type(<span class="stringliteral">&quot;reflected_type&quot;</span>_hs).prop(&amp;property_generator);</div>
</div><!-- fragment --><p>An annotation is an invocable object that returns one or more properties. All of them are treated individually.</p>
<p>It's possible to invoke the <code>prop</code> function several times if needed, one for each property to associate with the last meta object created:</p>
<div class="fragment"><div class="line">entt::meta&lt;my_type&gt;()</div>
<div class="line"> .type(<span class="stringliteral">&quot;reflected_type&quot;</span>_hs)</div>
<div class="line"> .prop(<a class="code" href="classentt_1_1basic__hashed__string.html">entt::hashed_string</a>{<span class="stringliteral">&quot;Name&quot;</span>}, <span class="stringliteral">&quot;Reflected Type&quot;</span>)</div>
<div class="line"> .data&lt;&amp;my_type::data_member&gt;(<span class="stringliteral">&quot;member&quot;</span>_hs)</div>
<div class="line"> .prop(std::make_pair(<span class="stringliteral">&quot;tooltip&quot;</span>_hs, <span class="stringliteral">&quot;Member&quot;</span>))</div>
<div class="line"> .prop(my_enum::a_value, 42);</div>
</div><!-- fragment --><p>Alternatively, the <code>props</code> function is available to associate several properties at a time. However, in this case properties in the key/value form aren't allowed, since they would be interpreted as two different properties rather than a single one.</p>
<p>The meta objects for which properties are supported are currently the meta types, meta constructors, meta data and meta functions. It's not possible to attach properties to other types of meta objects and the factory returned as a result of their construction won't allow such an operation.</p>
<p>These types offer a couple of member functions named <code>prop</code> to iterate all properties at once or to search a specific property by key:</p>
<div class="fragment"><div class="line"><span class="comment">// iterate all properties of a meta type</span></div>
<div class="line">entt::resolve&lt;my_type&gt;().prop([](<span class="keyword">auto</span> prop) {</div>
<div class="line"> <span class="comment">// ...</span></div>
<div class="line">});</div>
<div class="line"> </div>
<div class="line"><span class="comment">// search for a given property by name</span></div>
<div class="line"><span class="keyword">auto</span> prop = entt::resolve&lt;my_type&gt;().prop(<span class="stringliteral">&quot;tooltip&quot;</span>_hs);</div>
</div><!-- fragment --><p>Meta properties are objects having a fairly poor interface, all in all. They only provide the <code>key</code> and the <code>value</code> member functions to be used to retrieve the key and the value contained in the form of <code>meta_any</code> objects, respectively.</p>
<h2><a class="anchor" id="autotoc_md80"></a>
Unregister types</h2>
<p>A type registered with the reflection system can also be unregistered. This means unregistering all its data members, member functions, conversion functions and so on. However, the base classes won't be unregistered, since they don't necessarily depend on it. Similarly, implicitly generated types (as an example, the meta types implicitly generated for function parameters when needed) won't be unregistered.<br />
Roughly speaking, unregistering a type means disconnecting all associated meta objects from it and making its identifier no longer visible. The underlying node will remain available though, as if it were implicitly generated:</p>
<div class="fragment"><div class="line">entt::meta&lt;my_type&gt;().reset();</div>
</div><!-- fragment --><p>The type can be re-registered later with a completely different name and form. </p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
<div class="ttc" id="aclassentt_1_1meta__any_html"><div class="ttname"><a href="classentt_1_1meta__any.html">entt::meta_any</a></div><div class="ttdoc">Opaque container for values of any type.</div><div class="ttdef"><b>Definition:</b> <a href="meta_8hpp_source.html#l00311">meta.hpp:311</a></div></div>
<div class="ttc" id="astructentt_1_1as__void__t_html"><div class="ttname"><a href="structentt_1_1as__void__t.html">entt::as_void_t</a></div><div class="ttdoc">Empty class type used to request the as void policy.</div><div class="ttdef"><b>Definition:</b> <a href="policy_8hpp_source.html#l00021">policy.hpp:21</a></div></div>
<div class="ttc" id="anamespaceentt_html_a2129cb8668f5dcbc11854be6a4a0b6e5"><div class="ttname"><a href="namespaceentt.html#a2129cb8668f5dcbc11854be6a4a0b6e5">entt::resolve</a></div><div class="ttdeci">meta_type resolve() ENTT_NOEXCEPT</div><div class="ttdoc">Returns the meta type associated with a given type.</div><div class="ttdef"><b>Definition:</b> <a href="factory_8hpp_source.html#l00826">factory.hpp:826</a></div></div>
<div class="ttc" id="aclassentt_1_1basic__hashed__string_html"><div class="ttname"><a href="classentt_1_1basic__hashed__string.html">entt::basic_hashed_string</a></div><div class="ttdoc">Zero overhead unique identifier.</div><div class="ttdef"><b>Definition:</b> <a href="hashed__string_8hpp_source.html#l00060">hashed_string.hpp:60</a></div></div>
<div class="ttc" id="astructentt_1_1as__alias__t_html"><div class="ttname"><a href="structentt_1_1as__alias__t.html">entt::as_alias_t</a></div><div class="ttdoc">Empty class type used to request the as alias policy.</div><div class="ttdef"><b>Definition:</b> <a href="policy_8hpp_source.html#l00009">policy.hpp:9</a></div></div>
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.16
</small></address>
</body>
</html>