512 lines
63 KiB
HTML
512 lines
63 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" lang="en-US">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
|
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
|
|
<meta name="generator" content="Doxygen 1.9.6"/>
|
|
<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-awesome.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 id="projectrow">
|
|
<td id="projectalign">
|
|
<div id="projectname">EnTT<span id="projectnumber"> 3.12.0</span>
|
|
</div>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<!-- end header part -->
|
|
<!-- Generated by Doxygen 1.9.6 -->
|
|
<script type="text/javascript">
|
|
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
|
|
var searchBox = new SearchBox("searchBox", "search/",'.html');
|
|
/* @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:d3d9a9a6595521f9666a5e94cc830dab83b65699&dn=expat.txt MIT */
|
|
$(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">
|
|
<div id="MSearchResults">
|
|
<div class="SRPage">
|
|
<div id="SRIndex">
|
|
<div id="SRResults"></div>
|
|
<div class="SRStatus" id="Loading">Loading...</div>
|
|
<div class="SRStatus" id="Searching">Searching...</div>
|
|
<div class="SRStatus" id="NoMatches">No Matches</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
</div><!-- top -->
|
|
<div><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_md152"></a>
|
|
Introduction</h1>
|
|
<p>Reflection (or rather, its lack) is a trending topic in the C++ world and a tool that can unlock a lot of interesting features in the specific case of <code>EnTT</code>. 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, and so on.<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 the opposite.</p>
|
|
<h1><a class="anchor" id="autotoc_md153"></a>
|
|
Names and identifiers</h1>
|
|
<p>The meta system doesn't force users to rely on 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're numeric. It doesn't matter if they're generated at runtime, at compile-time or with custom functions.</p>
|
|
<p>That being said, 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<my_type>().type(<span class="stringliteral">"reflected_type"</span>_hs);</div>
|
|
</div><!-- fragment --><p>For what it's worth, this is completely equivalent to:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">auto</span> factory = entt::meta<my_type>().type(42u);</div>
|
|
</div><!-- fragment --><p>Obviously, human-readable identifiers are more convenient to use and highly recommended.</p>
|
|
<h1><a class="anchor" id="autotoc_md154"></a>
|
|
Reflection in a nutshell</h1>
|
|
<p>Reflection always starts from actual C++ types. Users cannot reflect <em>imaginary</em> types.<br />
|
|
The <code>meta</code> function is where it all starts:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">auto</span> factory = entt::meta<my_type>();</div>
|
|
</div><!-- fragment --><p>The returned value is a <em>factory object</em> to use to continue building the meta type.</p>
|
|
<p>By default, a meta type is associated with the identifier returned by the runtime type identification system built-in in <code>EnTT</code>.<br />
|
|
However, it's also possible to assign custom identifiers to meta types:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">auto</span> factory = entt::meta<my_type>().type(<span class="stringliteral">"reflected_type"</span>_hs);</div>
|
|
</div><!-- fragment --><p>Identifiers are used to <em>retrieve</em> meta types at runtime by <em>name</em> other than by type.<br />
|
|
However, users can be interested in adding features to a reflected type so that the reflection system can use it correctly under the hood, while they don't want to also make the type <em>searchable</em>. In this case, it's sufficient not to invoke <code>type</code>.</p>
|
|
<p>A factory is such that all its member functions return the factory itself. It's generally used to create the following:</p>
|
|
<ul>
|
|
<li><p class="startli"><em>Constructors</em>. A constructors is assigned to a reflected type by specifying its <em>list of arguments</em>. Free functions are also accepted if the return type is the expected one. From a client perspective, nothing changes between a free function or an actual constructor:</p>
|
|
<div class="fragment"><div class="line">entt::meta<my_type>().ctor<int, <span class="keywordtype">char</span>>().ctor<&factory>();</div>
|
|
</div><!-- fragment --><p class="startli">Meta default constructors are implicitly generated, if possible.</p>
|
|
</li>
|
|
<li><p class="startli"><em>Destructors</em>. Both free functions and member functions are valid destructors:</p>
|
|
<div class="fragment"><div class="line">entt::meta<my_type>().dtor<&destroy>();</div>
|
|
</div><!-- fragment --><p class="startli">The purpose is to offer the possibility to free up resources that require <em>special treatment</em> before an object is actually destroyed.<br />
|
|
A function should neither delete nor explicitly invoke the destructor of a given instance.</p>
|
|
</li>
|
|
<li><p class="startli"><em>Data members</em>. Meta data members are actual data members of the underlying type but also static and global variables or constants of any kind. From the point of view of the client, all the variables associated with the reflected type appear as if they were part of the type itself:</p>
|
|
<div class="fragment"><div class="line">entt::meta<my_type>()</div>
|
|
<div class="line"> .data<&my_type::static_variable>(<span class="stringliteral">"static"</span>_hs)</div>
|
|
<div class="line"> .data<&my_type::data_member>(<span class="stringliteral">"member"</span>_hs)</div>
|
|
<div class="line"> .data<&global_variable>(<span class="stringliteral">"global"</span>_hs);</div>
|
|
</div><!-- fragment --><p class="startli">The <code>data</code> function requires the identifier to use for the meta data member. Users can then access it by <em>name</em> at runtime.<br />
|
|
Data members are also defined by means of a setter and getter pair. These are either free functions, class members or a mix of them. This approach is also convenient to create read-only properties from a non-const data member:</p>
|
|
<div class="fragment"><div class="line">entt::meta<my_type>().data<<span class="keyword">nullptr</span>, &my_type::data_member>(<span class="stringliteral">"member"</span>_hs);</div>
|
|
</div><!-- fragment --><p class="startli">Multiple setters are also supported by means of a <code>value_list</code> object:</p>
|
|
<div class="fragment"><div class="line">entt::meta<my_type>().data<<a class="code hl_struct" href="structentt_1_1value__list.html">entt::value_list<&from_int, &from_string></a>, &my_type::data_member>(<span class="stringliteral">"member"</span>_hs);</div>
|
|
<div class="ttc" id="astructentt_1_1value__list_html"><div class="ttname"><a href="structentt_1_1value__list.html">entt::value_list</a></div><div class="ttdoc">A class to use to push around lists of constant values, nothing more.</div><div class="ttdef"><b>Definition:</b> <a href="core_2type__traits_8hpp_source.html#l00361">type_traits.hpp:361</a></div></div>
|
|
</div><!-- fragment --></li>
|
|
<li><p class="startli"><em>Member functions</em>. Meta member functions are actual member functions of the underlying type but also plain free functions. From the point of view of the client, all the functions associated with the reflected type appear as if they were part of the type itself:</p>
|
|
<div class="fragment"><div class="line">entt::meta<my_type>()</div>
|
|
<div class="line"> .func<&my_type::static_function>(<span class="stringliteral">"static"</span>_hs)</div>
|
|
<div class="line"> .func<&my_type::member_function>(<span class="stringliteral">"member"</span>_hs)</div>
|
|
<div class="line"> .func<&free_function>(<span class="stringliteral">"free"</span>_hs);</div>
|
|
</div><!-- fragment --><p class="startli">The <code>func</code> function requires the identifier to use for the meta data function. Users can then access it by <em>name</em> at runtime.<br />
|
|
Overloading of meta functions is supported. Overloaded functions are resolved at runtime by the reflection system according to the types of the arguments.</p>
|
|
</li>
|
|
<li><p class="startli"><em>Base classes</em>. A base class is such that the underlying type is actually derived from it:</p>
|
|
<div class="fragment"><div class="line">entt::meta<derived_type>().base<base_type>();</div>
|
|
</div><!-- fragment --><p class="startli">The reflection system tracks the relationship and allows for implicit casts at runtime when required. In other terms, wherever a <code>base_type</code> is required, an instance of <code>derived_type</code> is also accepted.</p>
|
|
</li>
|
|
<li><p class="startli"><em>Conversion functions</em>. Conversion functions allow users to define conversions that are implicitly performed by the reflection system when required:</p>
|
|
<div class="fragment"><div class="line">entt::meta<double>().conv<<span class="keywordtype">int</span>>();</div>
|
|
</div><!-- fragment --></li>
|
|
</ul>
|
|
<p>This is everything users need to create meta types. Refer to the inline documentation for further details.</p>
|
|
<h2><a class="anchor" id="autotoc_md155"></a>
|
|
Any to the rescue</h2>
|
|
<p>The reflection system offers a kind of <em>extended version</em> of the <code><a class="el" href="namespaceentt.html#a4846741b8f485584c196304f588b94ad" title="Alias declaration for the most common use case.">entt::any</a></code> class (see the core module for more details).<br />
|
|
The purpose is to add some feature on top of those already present, so as to integrate it with the meta type system without having to duplicate the code.</p>
|
|
<p>The API is very similar to that of the <code>any</code> type. The class <code>meta_any</code> <em>wraps</em> many of the feature to infer a meta node, before forwarding some or all of the arguments to the underlying storage.<br />
|
|
Among the few relevant differences, <code>meta_any</code> adds support for containers and pointer-like types, while <code>any</code> doesn't.<br />
|
|
Similar to <code>any</code>, this class is also used to create <em>aliases</em> for unmanaged objects either with <code>forward_as_meta</code> or using the <code>std::in_place_type<T &></code> disambiguation tag, as well as from an existing object by means of the <code>as_ref</code> member function.<br />
|
|
Unlike <code>any</code> instead, <code>meta_any</code> treats an empty instance and one initialized with <code>void</code> differently:</p>
|
|
<div class="fragment"><div class="line"><a class="code hl_class" href="classentt_1_1meta__any.html">entt::meta_any</a> empty{};</div>
|
|
<div class="line"><a class="code hl_class" href="classentt_1_1meta__any.html">entt::meta_any</a> other{std::in_place_type<void>};</div>
|
|
<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 wrapper for values of any type.</div><div class="ttdef"><b>Definition:</b> <a href="meta_8hpp_source.html#l00150">meta.hpp:150</a></div></div>
|
|
</div><!-- fragment --><p>While <code>any</code> considers both as empty, <code>meta_any</code> treats objects initialized with <code>void</code> as if they were <em>valid</em> ones. This allows to differentiate between failed function calls and function calls that are successful but return nothing.</p>
|
|
<p>Finally, the member functions <code>try_cast</code>, <code>cast</code> and <code>allow_cast</code> are used to cast the underlying object to a given type (either a reference or a value type) or to <em>convert</em> a <code>meta_any</code> in such a way that a cast becomes viable for the resulting object.<br />
|
|
There is in fact no <code>any_cast</code> equivalent for <code>meta_any</code>.</p>
|
|
<h2><a class="anchor" id="autotoc_md156"></a>
|
|
Enjoy the runtime</h2>
|
|
<p>Once the web of reflected types is constructed, it's a matter of using it at runtime where required.<br />
|
|
There are a few options to search for a reflected type:</p>
|
|
<div class="fragment"><div class="line"><span class="comment">// direct access to a reflected type</span></div>
|
|
<div class="line"><span class="keyword">auto</span> by_type = entt::resolve<my_type>();</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// look up a reflected type by identifier</span></div>
|
|
<div class="line"><span class="keyword">auto</span> by_id = <a class="code hl_function" href="namespaceentt.html#a9dc2ece8ba5dafc463abdceb1f55eaea">entt::resolve</a>(<span class="stringliteral">"reflected_type"</span>_hs);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="comment">// look up a reflected type by type info</span></div>
|
|
<div class="line"><span class="keyword">auto</span> by_type_id = <a class="code hl_function" href="namespaceentt.html#a9dc2ece8ba5dafc463abdceb1f55eaea">entt::resolve</a>(entt::type_id<my_type>());</div>
|
|
<div class="ttc" id="anamespaceentt_html_a9dc2ece8ba5dafc463abdceb1f55eaea"><div class="ttname"><a href="namespaceentt.html#a9dc2ece8ba5dafc463abdceb1f55eaea">entt::resolve</a></div><div class="ttdeci">meta_type resolve() noexcept</div><div class="ttdoc">Returns the meta type associated with a given type.</div><div class="ttdef"><b>Definition:</b> <a href="resolve_8hpp_source.html#l00032">resolve.hpp:32</a></div></div>
|
|
</div><!-- fragment --><p>There exists also an overload of the <code>resolve</code> function to use to iterate all reflected types at once. It returns an iterable object to be used in a range-for loop:</p>
|
|
<div class="fragment"><div class="line"><span class="keywordflow">for</span>(<span class="keyword">auto</span> &&[<span class="keywordtype">id</span>, type]: <a class="code hl_function" href="namespaceentt.html#a9dc2ece8ba5dafc463abdceb1f55eaea">entt::resolve</a>()) {</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> (possibly with its id). 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 instances of the underlying type.<br />
|
|
Meta data members and functions are accessed by name:</p>
|
|
<ul>
|
|
<li><p class="startli">Meta data members:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">auto</span> data = entt::resolve<my_type>().data(<span class="stringliteral">"member"</span>_hs);</div>
|
|
</div><!-- fragment --><p class="startli">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>
|
|
</li>
|
|
<li><p class="startli">Meta function members:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">auto</span> func = entt::resolve<my_type>().func(<span class="stringliteral">"member"</span>_hs);</div>
|
|
</div><!-- fragment --><p class="startli">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 is used to invoke the underlying function and then get the return value in the form of a <code>meta_any</code> object.</p>
|
|
</li>
|
|
</ul>
|
|
<p>All the meta objects thus obtained as well as the meta types explicitly convert to a boolean value to check for validity:</p>
|
|
<div class="fragment"><div class="line"><span class="keywordflow">if</span>(<span class="keyword">auto</span> func = entt::resolve<my_type>().func(<span class="stringliteral">"member"</span>_hs); func) {</div>
|
|
<div class="line"> <span class="comment">// ...</span></div>
|
|
<div class="line">}</div>
|
|
</div><!-- fragment --><p>Furthermore, all them (and a few more, like meta basis) are returned by a bunch of overloads that provide the caller with iterable ranges of top-level elements. As an example:</p>
|
|
<div class="fragment"><div class="line"><span class="keywordflow">for</span>(<span class="keyword">auto</span> &&[<span class="keywordtype">id</span>, type]: entt::resolve<my_type>().base()) {</div>
|
|
<div class="line"> <span class="comment">// ...</span></div>
|
|
<div class="line">}</div>
|
|
</div><!-- fragment --><p>Meta type are also used to <code>construct</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 then returns a <code>meta_any</code> object that may or may not be initialized, depending on whether a suitable constructor was found or not.</p>
|
|
<p>There is no object that wraps the destructor of a meta type nor a <code>destroy</code> member function in its API. Destructors are invoked implicitly by <code>meta_any</code> behind the scenes and users have not to deal with them explicitly. Furthermore, they've no name, cannot be searched and wouldn't have member functions to expose anyway.<br />
|
|
Similarly, conversion functions aren't directly accessible. They're used internally by <code>meta_any</code> and the meta objects when needed.</p>
|
|
<p>Meta types and meta objects in general contain much more than what was said. Refer to the inline documentation for further details.</p>
|
|
<h2><a class="anchor" id="autotoc_md157"></a>
|
|
Container support</h2>
|
|
<p>The runtime reflection system also supports containers of all types.<br />
|
|
Moreover, <em>containers</em> doesn't necessarily mean those offered by the C++ standard library. In fact, user defined data structures can also work with the meta system in many cases.</p>
|
|
<p>To make a container be recognized as such by the meta system, users are required to provide specializations for either the <code>meta_sequence_container_traits</code> class or the <code>meta_associative_container_traits</code> class, according to the actual <em>type</em> of the container.<br />
|
|
<code>EnTT</code> already exports the specializations for some common classes. In particular:</p>
|
|
<ul>
|
|
<li><code>std::vector</code>, <code>std::array</code>, <code>std::deque</code> and <code>std::list</code> (but not <code>std::forward_list</code>) are supported as <em>sequence containers</em>.</li>
|
|
<li><code>std::map</code>, <code>std::set</code> and their unordered counterparts are supported as <em>associative containers</em>.</li>
|
|
</ul>
|
|
<p>It's important to include the header file <code><a class="el" href="container_8hpp_source.html">container.hpp</a></code> to make these specializations available to the compiler when needed.<br />
|
|
The same file also contains many examples for the users that are interested in making their own containers available to the meta system.</p>
|
|
<p>When a specialization of the <code>meta_sequence_container_traits</code> class exists, the meta system treats the wrapped type as a sequence container. In a similar way, a type is treated as an associative container if a specialization of the <code>meta_associative_container_traits</code> class is found for it.<br />
|
|
Proxy objects are returned by dedicated members of the <code>meta_any</code> class. The following is a deliberately verbose example of how users can access a proxy object for a sequence container:</p>
|
|
<div class="fragment"><div class="line">std::vector<int> vec{1, 2, 3};</div>
|
|
<div class="line"><a class="code hl_class" href="classentt_1_1meta__any.html">entt::meta_any</a> any = <a class="code hl_function" href="namespaceentt.html#abf59d78f99cd7f20904c2129088bfd7e">entt::forward_as_meta</a>(vec);</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keywordflow">if</span>(any.<a class="code hl_function" href="classentt_1_1basic__any.html#a63c48ddb1677383ba12752ffa387139b">type</a>().is_sequence_container()) {</div>
|
|
<div class="line"> <span class="keywordflow">if</span>(<span class="keyword">auto</span> view = any.as_sequence_container(); view) {</div>
|
|
<div class="line"> <span class="comment">// ...</span></div>
|
|
<div class="line"> }</div>
|
|
<div class="line">}</div>
|
|
<div class="ttc" id="aclassentt_1_1basic__any_html_a63c48ddb1677383ba12752ffa387139b"><div class="ttname"><a href="classentt_1_1basic__any.html#a63c48ddb1677383ba12752ffa387139b">entt::basic_any::type</a></div><div class="ttdeci">const type_info & type() const noexcept</div><div class="ttdoc">Returns the object type if any, type_id<void>() otherwise.</div><div class="ttdef"><b>Definition:</b> <a href="any_8hpp_source.html#l00272">any.hpp:272</a></div></div>
|
|
<div class="ttc" id="anamespaceentt_html_abf59d78f99cd7f20904c2129088bfd7e"><div class="ttname"><a href="namespaceentt.html#abf59d78f99cd7f20904c2129088bfd7e">entt::forward_as_meta</a></div><div class="ttdeci">meta_any forward_as_meta(const meta_ctx &ctx, Type &&value)</div><div class="ttdoc">Forwards its argument and avoids copies for lvalue references.</div><div class="ttdef"><b>Definition:</b> <a href="meta_8hpp_source.html#l00616">meta.hpp:616</a></div></div>
|
|
</div><!-- fragment --><p>The method to use to get a proxy object for associative containers is <code>as_associative_container</code> instead.<br />
|
|
It's not necessary to perform a double check actually. Instead, it's enough to query the meta type or verify that the proxy object is valid. In fact, proxies are contextually convertible to bool to check for validity. For example, invalid proxies are returned when the wrapped object isn't a container.<br />
|
|
In all cases, users aren't expected to <em>reflect</em> containers explicitly. It's sufficient to assign a container for which a specialization of the traits classes exists to a <code>meta_any</code> object to be able to get its proxy object.</p>
|
|
<p>The interface of the <code>meta_sequence_container</code> proxy object is the same for all types of sequence containers, although the available features differ from case to case. In particular:</p>
|
|
<ul>
|
|
<li>The <code>value_type</code> member function returns the meta type of the elements.</li>
|
|
<li>The <code>size</code> member function returns the number of elements in the container as an unsigned integer value.</li>
|
|
<li>The <code>resize</code> member function allows to resize the wrapped container and returns true in case of success.<br />
|
|
For example, it's not possible to resize fixed size containers.</li>
|
|
<li>The <code>clear</code> member function allows to clear the wrapped container and returns true in case of success.<br />
|
|
For example, it's not possible to clear fixed size containers.</li>
|
|
<li><p class="startli">The <code>begin</code> and <code>end</code> member functions return opaque iterators that is used to iterate the container directly:</p>
|
|
<div class="fragment"><div class="line"><span class="keywordflow">for</span>(<a class="code hl_class" href="classentt_1_1meta__any.html">entt::meta_any</a> element: view) {</div>
|
|
<div class="line"> <span class="comment">// ...</span></div>
|
|
<div class="line">}</div>
|
|
</div><!-- fragment --><p class="startli">In all cases, given an underlying container of type <code>C</code>, the returned element contains an object of type <code>C::value_type</code> which therefore depends on the actual container.<br />
|
|
All meta iterators are input iterators and don't offer an indirection operator on purpose.</p>
|
|
</li>
|
|
<li><p class="startli">The <code>insert</code> member function is used to add elements to the container. It accepts a meta iterator and the element to insert:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">auto</span> last = view.end();</div>
|
|
<div class="line"><span class="comment">// appends an integer to the container</span></div>
|
|
<div class="line">view.insert(last, 42);</div>
|
|
</div><!-- fragment --><p class="startli">This function returns a meta iterator pointing to the inserted element and a boolean value to indicate whether the operation was successful or not. A call to <code>insert</code> may silently fail in case of fixed size containers or whether the arguments aren't at least convertible to the required types.<br />
|
|
Since meta iterators are contextually convertible to bool, users can rely on them to know if the operation failed on the actual container or upstream, for example due to an argument conversion problem.</p>
|
|
</li>
|
|
<li><p class="startli">The <code>erase</code> member function is used to remove elements from the container. It accepts a meta iterator to the element to remove:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">auto</span> first = view.begin();</div>
|
|
<div class="line"><span class="comment">// removes the first element from the container</span></div>
|
|
<div class="line">view.erase(first);</div>
|
|
</div><!-- fragment --><p class="startli">This function returns a meta iterator following the last removed element and a boolean value to indicate whether the operation was successful or not. A call to <code>erase</code> may silently fail in case of fixed size containers.</p>
|
|
</li>
|
|
<li><p class="startli">The <code>operator[]</code> is used to access container elements. It accepts a single argument, the position of the element to return:</p>
|
|
<div class="fragment"><div class="line"><span class="keywordflow">for</span>(std::size_t pos{}, last = view.size(); pos < last; ++pos) {</div>
|
|
<div class="line"> <a class="code hl_class" href="classentt_1_1meta__any.html">entt::meta_any</a> value = view[pos];</div>
|
|
<div class="line"> <span class="comment">// ...</span></div>
|
|
<div class="line">}</div>
|
|
</div><!-- fragment --><p class="startli">The function returns instances of <code>meta_any</code> that directly refer to the actual elements. Modifying the returned object directly modifies the element inside the container.<br />
|
|
Depending on the underlying sequence container, this operation may not be as efficient. For example, in the case of an <code>std::list</code>, a positional access translates to a linear visit of the list itself (probably not what the user expects).</p>
|
|
</li>
|
|
</ul>
|
|
<p>Similarly, also the interface of the <code>meta_associative_container</code> proxy object is the same for all types of associative containers. However, there are some differences in behavior in the case of key-only containers. In particular:</p>
|
|
<ul>
|
|
<li>The <code>key_only</code> member function returns true if the wrapped container is a key-only one.</li>
|
|
<li>The <code>key_type</code> member function returns the meta type of the keys.</li>
|
|
<li>The <code>mapped_type</code> member function returns an invalid meta type for key-only containers and the meta type of the mapped values for all other types of containers.</li>
|
|
<li>The <code>value_type</code> member function returns the meta type of the elements.<br />
|
|
For example, it returns the meta type of <code>int</code> for <code>std::set<int></code> while it returns the meta type of <code>std::pair<const int, char></code> for <code>std::map<int, char></code>.</li>
|
|
<li>The <code>size</code> member function returns the number of elements in the container as an unsigned integer value.</li>
|
|
<li>The <code>clear</code> member function allows to clear the wrapped container and returns true in case of success.</li>
|
|
<li><p class="startli">The <code>begin</code> and <code>end</code> member functions return opaque iterators that are used to iterate the container directly:</p>
|
|
<div class="fragment"><div class="line"><span class="keywordflow">for</span>(std::pair<entt::meta_any, entt::meta_any> element: view) {</div>
|
|
<div class="line"> <span class="comment">// ...</span></div>
|
|
<div class="line">}</div>
|
|
</div><!-- fragment --><p class="startli">In all cases, given an underlying container of type <code>C</code>, the returned element is a key-value pair where the key has type <code>C::key_type</code> and the value has type <code>C::mapped_type</code>. Since key-only containers don't have a mapped type, their <em>value</em> is nothing more than an invalid <code>meta_any</code> object.<br />
|
|
All meta iterators are input iterators and don't offer an indirection operator on purpose.</p>
|
|
<p class="startli">While the accessed key is usually constant in the associative containers and is therefore returned by copy, the value (if any) is wrapped by an instance of <code>meta_any</code> that directly refers to the actual element. Modifying it directly modifies the element inside the container.</p>
|
|
</li>
|
|
<li><p class="startli">The <code>insert</code> member function is used to add elements to a container. It gets two arguments, respectively the key and the value to insert:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">auto</span> last = view.end();</div>
|
|
<div class="line"><span class="comment">// appends an integer to the container</span></div>
|
|
<div class="line">view.insert(last.handle(), 42, <span class="charliteral">'c'</span>);</div>
|
|
</div><!-- fragment --><p class="startli">This function returns a boolean value to indicate whether the operation was successful or not. A call to <code>insert</code> may fail when the arguments aren't at least convertible to the required types.</p>
|
|
</li>
|
|
<li><p class="startli">The <code>erase</code> member function is used to remove elements from a container. It gets a single argument, the key to remove:</p>
|
|
<div class="fragment"><div class="line">view.erase(42);</div>
|
|
</div><!-- fragment --><p class="startli">This function returns a boolean value to indicate whether the operation was successful or not. A call to <code>erase</code> may fail when the argument isn't at least convertible to the required type.</p>
|
|
</li>
|
|
<li><p class="startli">The <code>operator[]</code> is used to access elements in a container. It gets a single argument, the key of the element to return:</p>
|
|
<div class="fragment"><div class="line"><a class="code hl_class" href="classentt_1_1meta__any.html">entt::meta_any</a> value = view[42];</div>
|
|
</div><!-- fragment --><p class="startli">The function returns instances of <code>meta_any</code> that directly refer to the actual elements. Modifying the returned object directly modifies the element inside the container.</p>
|
|
</li>
|
|
</ul>
|
|
<p>Container support is minimal but likely sufficient to satisfy all needs.</p>
|
|
<h2><a class="anchor" id="autotoc_md158"></a>
|
|
Pointer-like types</h2>
|
|
<p>As with containers, it's also possible to <em>tell</em> to the meta system which types are <em>pointers</em>. This makes it possible to dereference instances of <code>meta_any</code>, thus obtaining light <em>references</em> to pointed objects that are also correctly associated with their meta types.<br />
|
|
To make the meta system recognize a type as <em>pointer-like</em>, users can specialize the <code>is_meta_pointer_like</code> class. <code>EnTT</code> already exports the specializations for some common classes. In particular:</p>
|
|
<ul>
|
|
<li>All types of raw pointers.</li>
|
|
<li><code>std::unique_ptr</code> and <code>std::shared_ptr</code>.</li>
|
|
</ul>
|
|
<p>It's important to include the header file <code><a class="el" href="pointer_8hpp_source.html">pointer.hpp</a></code> to make these specializations available to the compiler when needed.<br />
|
|
The same file also contains many examples for the users that are interested in making their own pointer-like types available to the meta system.</p>
|
|
<p>When a type is recognized as a pointer-like one by the meta system, it's possible to dereference the instances of <code>meta_any</code> that contain these objects. The following is a deliberately verbose example to show how to use this feature:</p>
|
|
<div class="fragment"><div class="line"><span class="keywordtype">int</span> value = 42;</div>
|
|
<div class="line"><span class="comment">// meta type equivalent to that of int *</span></div>
|
|
<div class="line"><a class="code hl_class" href="classentt_1_1meta__any.html">entt::meta_any</a> any{&value};</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keywordflow">if</span>(any.<a class="code hl_function" href="classentt_1_1basic__any.html#a63c48ddb1677383ba12752ffa387139b">type</a>().is_pointer_like()) {</div>
|
|
<div class="line"> <span class="comment">// meta type equivalent to that of int</span></div>
|
|
<div class="line"> <span class="keywordflow">if</span>(<a class="code hl_class" href="classentt_1_1meta__any.html">entt::meta_any</a> ref = *any; ref) {</div>
|
|
<div class="line"> <span class="comment">// ...</span></div>
|
|
<div class="line"> }</div>
|
|
<div class="line">}</div>
|
|
</div><!-- fragment --><p>It's not necessary to perform a double check. Instead, it's enough to query the meta type or verify that the returned object is valid. For example, invalid instances are returned when the wrapped object isn't a pointer-like type.<br />
|
|
Dereferencing a pointer-like object returns an instance of <code>meta_any</code> which <em>refers</em> to the pointed object. Modifying it means modifying the pointed object directly (unless the returned element is const).</p>
|
|
<p>In general, <em>dereferencing</em> a pointer-like type boils down to a <code>*ptr</code>. However, <code>EnTT</code> also supports classes that don't offer an <code>operator*</code>. In particular:</p>
|
|
<ul>
|
|
<li><p class="startli">It's possible to exploit a solution based on ADL lookup by offering a function (also a template one) named <code>dereference_meta_pointer_like</code>:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">template</span><<span class="keyword">typename</span> Type></div>
|
|
<div class="line">Type & dereference_meta_pointer_like(<span class="keyword">const</span> custom_pointer_type<Type> &ptr) {</div>
|
|
<div class="line"> <span class="keywordflow">return</span> ptr.deref();</div>
|
|
<div class="line">}</div>
|
|
</div><!-- fragment --></li>
|
|
<li><p class="startli">When not in control of the type's namespace, it's possible to inject into the <code>entt</code> namespace a specialization of the <code>adl_meta_pointer_like</code> class template to bypass the adl lookup as a whole:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">template</span><<span class="keyword">typename</span> Type></div>
|
|
<div class="line"><span class="keyword">struct </span><a class="code hl_struct" href="structentt_1_1adl__meta__pointer__like.html">entt::adl_meta_pointer_like</a><custom_pointer_type<Type>> {</div>
|
|
<div class="line"> <span class="keyword">static</span> <span class="keyword">decltype</span>(<span class="keyword">auto</span>) <a class="code hl_function" href="structentt_1_1adl__meta__pointer__like.html#afa27f416e32b351d85ab1a061c4597bd">dereference</a>(<span class="keyword">const</span> custom_pointer_type<Type> &ptr) {</div>
|
|
<div class="line"> <span class="keywordflow">return</span> ptr.deref();</div>
|
|
<div class="line"> }</div>
|
|
<div class="line">};</div>
|
|
<div class="ttc" id="astructentt_1_1adl__meta__pointer__like_html"><div class="ttname"><a href="structentt_1_1adl__meta__pointer__like.html">entt::adl_meta_pointer_like</a></div><div class="ttdoc">Fake ADL based lookup function for meta pointer-like types.</div><div class="ttdef"><b>Definition:</b> <a href="adl__pointer_8hpp_source.html#l00022">adl_pointer.hpp:22</a></div></div>
|
|
<div class="ttc" id="astructentt_1_1adl__meta__pointer__like_html_afa27f416e32b351d85ab1a061c4597bd"><div class="ttname"><a href="structentt_1_1adl__meta__pointer__like.html#afa27f416e32b351d85ab1a061c4597bd">entt::adl_meta_pointer_like::dereference</a></div><div class="ttdeci">static decltype(auto) dereference(const Type &value)</div><div class="ttdoc">Uses the default ADL based lookup method to resolve the call.</div><div class="ttdef"><b>Definition:</b> <a href="adl__pointer_8hpp_source.html#l00028">adl_pointer.hpp:28</a></div></div>
|
|
</div><!-- fragment --></li>
|
|
</ul>
|
|
<p>In all other cases and when dereferencing a pointer works as expected regardless of the pointed type, no user intervention is required.</p>
|
|
<h2><a class="anchor" id="autotoc_md159"></a>
|
|
Template information</h2>
|
|
<p>Meta types also provide a minimal set of information about the <em>nature</em> of the original type in case it's a class template.<br />
|
|
By default, this works out of the box and requires no user action. However, it's important to include the header file <code><a class="el" href="template_8hpp_source.html">template.hpp</a></code> to make this information available to the compiler when needed.</p>
|
|
<p>Meta template information are easily found:</p>
|
|
<div class="fragment"><div class="line"><span class="comment">// this method returns true if the type is recognized as a class template specialization</span></div>
|
|
<div class="line"><span class="keywordflow">if</span>(<span class="keyword">auto</span> type = <a class="code hl_function" href="namespaceentt.html#a9dc2ece8ba5dafc463abdceb1f55eaea">entt::resolve</a><std::shared_ptr<my_type>>(); type.<a class="code hl_function" href="classentt_1_1meta__type.html#ad837ecee0d13f2291c715d62bf642353">is_template_specialization</a>()) {</div>
|
|
<div class="line"> <span class="comment">// meta type of the class template conveniently wrapped by entt::meta_class_template_tag</span></div>
|
|
<div class="line"> <span class="keyword">auto</span> class_type = type.template_type();</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="comment">// number of template arguments</span></div>
|
|
<div class="line"> std::size_t arity = type.template_arity();</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> <span class="comment">// meta type of the i-th argument</span></div>
|
|
<div class="line"> <span class="keyword">auto</span> arg_type = type.template_arg(0u);</div>
|
|
<div class="line">}</div>
|
|
<div class="ttc" id="aclassentt_1_1meta__type_html_ad837ecee0d13f2291c715d62bf642353"><div class="ttname"><a href="classentt_1_1meta__type.html#ad837ecee0d13f2291c715d62bf642353">entt::meta_type::is_template_specialization</a></div><div class="ttdeci">bool is_template_specialization() const noexcept</div><div class="ttdoc">Checks whether a type refers to a recognized class template specialization or not.</div><div class="ttdef"><b>Definition:</b> <a href="meta_8hpp_source.html#l01276">meta.hpp:1276</a></div></div>
|
|
</div><!-- fragment --><p>Typically, when template information for a type are required, what the library provides is sufficient. However, there are some cases where a user may want more details or a different set of information.<br />
|
|
Consider the case of a class template that is meant to wrap function types:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">template</span><<span class="keyword">typename</span>></div>
|
|
<div class="line"><span class="keyword">struct </span>function_type;</div>
|
|
<div class="line"> </div>
|
|
<div class="line"><span class="keyword">template</span><<span class="keyword">typename</span> Ret, <span class="keyword">typename</span>... Args></div>
|
|
<div class="line"><span class="keyword">struct </span>function_type<Ret(Args...)> {};</div>
|
|
</div><!-- fragment --><p>In this case, rather than the function type, it might be useful to provide the return type and unpacked arguments as if they were different template parameters for the original class template.<br />
|
|
To achieve this, users must enter the library internals and provide their own specialization for the class template <code><a class="el" href="structentt_1_1meta__template__traits.html" title="Traits class template to be specialized to enable support for meta template information.">entt::meta_template_traits</a></code>, such as:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">template</span><<span class="keyword">typename</span> Ret, <span class="keyword">typename</span>... Args></div>
|
|
<div class="line"><span class="keyword">struct </span><a class="code hl_struct" href="structentt_1_1meta__template__traits.html">entt::meta_template_traits</a><function_type<Ret(Args...)>> {</div>
|
|
<div class="line"> <span class="keyword">using </span>class_type = meta_class_template_tag<function_type>;</div>
|
|
<div class="line"> <span class="keyword">using </span>args_type = type_list<Ret, Args...>;</div>
|
|
<div class="line">};</div>
|
|
<div class="ttc" id="astructentt_1_1meta__template__traits_html"><div class="ttname"><a href="structentt_1_1meta__template__traits.html">entt::meta_template_traits</a></div><div class="ttdoc">Traits class template to be specialized to enable support for meta template information.</div><div class="ttdef"><b>Definition:</b> <a href="meta_2type__traits_8hpp_source.html#l00014">type_traits.hpp:14</a></div></div>
|
|
</div><!-- fragment --><p>The reflection system doesn't verify the accuracy of the information nor infer a correspondence between real types and meta types.<br />
|
|
Therefore, the specialization is used as is and the information it contains is associated with the appropriate type when required.</p>
|
|
<h2><a class="anchor" id="autotoc_md160"></a>
|
|
Automatic conversions</h2>
|
|
<p>In C++, there are a number of conversions allowed between arithmetic types that make it convenient to work with this kind of data.<br />
|
|
If this were to be translated into explicit registrations with the reflection system, it would result in a long series of instructions such as the following:</p>
|
|
<div class="fragment"><div class="line">entt::meta<int>()</div>
|
|
<div class="line"> .conv<<span class="keywordtype">bool</span>>()</div>
|
|
<div class="line"> .conv<char>()</div>
|
|
<div class="line"> <span class="comment">// ...</span></div>
|
|
<div class="line"> .conv<<span class="keywordtype">double</span>>();</div>
|
|
</div><!-- fragment --><p>Repeated for each type eligible to undergo this type of conversions. This is both error-prone and repetitive.<br />
|
|
Similarly, the language allows users to silently convert unscoped enums to their underlying types and offers what it takes to do the same for scoped enums. It would result in the following if it were to be done explicitly:</p>
|
|
<div class="fragment"><div class="line">entt::meta<my_enum>()</div>
|
|
<div class="line"> .conv<std::underlying_type_t<my_enum>>();</div>
|
|
</div><!-- fragment --><p>Fortunately, all of this can also be avoided. <code>EnTT</code> offers implicit support for these types of conversions:</p>
|
|
<div class="fragment"><div class="line"><a class="code hl_class" href="classentt_1_1meta__any.html">entt::meta_any</a> any{42};</div>
|
|
<div class="line">any.allow_cast<<span class="keywordtype">double</span>>();</div>
|
|
<div class="line"><span class="keywordtype">double</span> value = any.cast<<span class="keywordtype">double</span>>();</div>
|
|
</div><!-- fragment --><p>With no need for registration, the conversion takes place automatically under the hood. The same goes for a call to <code>allow_cast</code> involving a meta type:</p>
|
|
<div class="fragment"><div class="line"><a class="code hl_class" href="classentt_1_1meta__type.html">entt::meta_type</a> type = entt::resolve<int>();</div>
|
|
<div class="line"><a class="code hl_class" href="classentt_1_1meta__any.html">entt::meta_any</a> any{my_enum::a_value};</div>
|
|
<div class="line">any.allow_cast(type);</div>
|
|
<div class="line"><span class="keywordtype">int</span> value = any.cast<<span class="keywordtype">int</span>>();</div>
|
|
<div class="ttc" id="aclassentt_1_1meta__type_html"><div class="ttname"><a href="classentt_1_1meta__type.html">entt::meta_type</a></div><div class="ttdoc">Opaque wrapper for types.</div><div class="ttdef"><b>Definition:</b> <a href="meta_8hpp_source.html#l01077">meta.hpp:1077</a></div></div>
|
|
</div><!-- fragment --><p>This makes working with arithmetic types and scoped or unscoped enums as easy as it is in C++.<br />
|
|
It's still possible to set up conversion functions manually and these are always preferred over the automatic ones.</p>
|
|
<h2><a class="anchor" id="autotoc_md161"></a>
|
|
Implicitly generated default constructor</h2>
|
|
<p>Creating objects of default constructible types through the reflection system while not having to explicitly register the meta type or its default constructor is also possible.<br />
|
|
For example, in the case of primitive types like <code>int</code> or <code>char</code>, but not just them.</p>
|
|
<p>For default constructible types only, default constructors are automatically defined and associated with their meta types, whether they are explicitly or implicitly generated.<br />
|
|
Therefore, this is all is needed to construct an integer from its meta type:</p>
|
|
<div class="fragment"><div class="line">entt::resolve<int>().construct();</div>
|
|
</div><!-- fragment --><p>Where the meta type is for example the one returned from a meta container, useful for building keys without knowing or having to register the actual types.</p>
|
|
<p>In all cases, when users register default constructors, they are preferred both during searches and when the <code>construct</code> member function is invoked.</p>
|
|
<h2><a class="anchor" id="autotoc_md162"></a>
|
|
From void to any</h2>
|
|
<p>Sometimes all a user has is an opaque pointer to an object of a known meta type. It would be handy in this case to be able to construct a <code>meta_any</code> element from it.<br />
|
|
For this purpose, the <code>meta_type</code> class offers a <code>from_void</code> member function designed to convert an opaque pointer into a <code>meta_any</code>:</p>
|
|
<div class="fragment"><div class="line"><a class="code hl_class" href="classentt_1_1meta__any.html">entt::meta_any</a> any = <a class="code hl_function" href="namespaceentt.html#a9dc2ece8ba5dafc463abdceb1f55eaea">entt::resolve</a>(<span class="keywordtype">id</span>).<a class="code hl_function" href="classentt_1_1meta__type.html#ae84495b2c93e1a73237d9e036af999dd">from_void</a>(element);</div>
|
|
<div class="ttc" id="aclassentt_1_1meta__type_html_ae84495b2c93e1a73237d9e036af999dd"><div class="ttname"><a href="classentt_1_1meta__type.html#ae84495b2c93e1a73237d9e036af999dd">entt::meta_type::from_void</a></div><div class="ttdeci">meta_any from_void(void *element) const</div><div class="ttdoc">Wraps an opaque element of the underlying type.</div><div class="ttdef"><b>Definition:</b> <a href="meta_8hpp_source.html#l01426">meta.hpp:1426</a></div></div>
|
|
</div><!-- fragment --><p>Unfortunately, it's not possible to do a check on the actual type. Therefore, this call can be considered as a <em>static cast</em> with all its <em>problems</em>.<br />
|
|
On the other hand, the ability to construct a <code>meta_any</code> from an opaque pointer opens the door to some pretty interesting uses that are worth exploring.</p>
|
|
<h2><a class="anchor" id="autotoc_md163"></a>
|
|
Policies: the more, the less</h2>
|
|
<p>Policies are a kind of compile-time directives that can be used when registering 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>:</p>
|
|
<div class="fragment"><div class="line">entt::meta<my_type>().func<&my_type::member_function, <a class="code hl_struct" href="structentt_1_1as__void__t.html">entt::as_void_t</a>>(<span class="stringliteral">"member"</span>_hs);</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#l00051">policy.hpp:51</a></div></div>
|
|
</div><!-- fragment --><p class="startli">If the use with functions is obvious, perhaps less so is use with constructors and data members. In the first case, the returned wrapper is always empty even though the constructor is still invoked. In the second case, the property isn't accessible for reading instead.</p>
|
|
</li>
|
|
<li><p class="startli">The <em>as-ref</em> and <em>as-cref</em> policies, associated with the types <code><a class="el" href="structentt_1_1as__ref__t.html" title="Empty class type used to request the as ref policy.">entt::as_ref_t</a></code> and <code><a class="el" href="structentt_1_1as__cref__t.html" title="Empty class type used to request the as cref policy.">entt::as_cref_t</a></code>.<br />
|
|
They allow to build wrappers that act as references to unmanaged objects. Accessing the object contained in the wrapper for which the <em>reference</em> was requested makes it possible to directly access the instance used to initialize the wrapper itself:</p>
|
|
<div class="fragment"><div class="line">entt::meta<my_type>().data<&my_type::data_member, <a class="code hl_struct" href="structentt_1_1as__ref__t.html">entt::as_ref_t</a>>(<span class="stringliteral">"member"</span>_hs);</div>
|
|
<div class="ttc" id="astructentt_1_1as__ref__t_html"><div class="ttname"><a href="structentt_1_1as__ref__t.html">entt::as_ref_t</a></div><div class="ttdoc">Empty class type used to request the as ref policy.</div><div class="ttdef"><b>Definition:</b> <a href="policy_8hpp_source.html#l00009">policy.hpp:9</a></div></div>
|
|
</div><!-- fragment --><p class="startli">These policies work with constructors (for example, when objects are taken from an external container rather than created on demand), data members and functions in general.<br />
|
|
If on the one hand <code>as_cref_t</code> always forces the return type to be const, <code>as_ref_t</code> <em>adapts</em> to the constness of the passed object and to that of the return type if any.</p>
|
|
</li>
|
|
</ul>
|
|
<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_md164"></a>
|
|
Named constants and enums</h2>
|
|
<p>As mentioned, the <code>data</code> member function is used to reflect constants of any type.<br />
|
|
This allows users to create meta types for enums that work exactly like any other meta type built from a class. Similarly, arithmetic types are <em>enriched</em> with constants of special meaning where required.<br />
|
|
All values thus exported appear to users as if they were constant data members of the reflected types. This avoids the need to <em>export</em> what is the difference between enums and classes in C++ directly in the space of the reflected types.</p>
|
|
<p>Exposing constant values or elements from an enum is quite simple:</p>
|
|
<div class="fragment"><div class="line">entt::meta<my_enum>()</div>
|
|
<div class="line"> .data<my_enum::a_value>(<span class="stringliteral">"a_value"</span>_hs)</div>
|
|
<div class="line"> .data<my_enum::another_value>(<span class="stringliteral">"another_value"</span>_hs);</div>
|
|
<div class="line"> </div>
|
|
<div class="line">entt::meta<int>().data<2048>(<span class="stringliteral">"max_int"</span>_hs);</div>
|
|
</div><!-- fragment --><p>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<my_enum>().data(<span class="stringliteral">"a_value"</span>_hs).get({}).cast<my_enum>();</div>
|
|
<div class="line"><span class="keyword">auto</span> max = entt::resolve<int>().data(<span class="stringliteral">"max_int"</span>_hs).get({}).cast<int>();</div>
|
|
</div><!-- fragment --><p>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_md165"></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:</p>
|
|
<div class="fragment"><div class="line">entt::meta<my_type>().type(<span class="stringliteral">"reflected_type"</span>_hs).prop(<span class="stringliteral">"tooltip"</span>_hs, <span class="stringliteral">"message"</span>);</div>
|
|
</div><!-- fragment --><p>Properties are always in the key/value form. The key is a numeric identifier, mostly similar to the identifier used to register meta objects. There are no restrictions on the type of the value instead, as long as it's movable.<br />
|
|
Key only properties are also supported out of the box:</p>
|
|
<div class="fragment"><div class="line">entt::meta<my_type>().type(<span class="stringliteral">"reflected_type"</span>_hs).prop(my_enum::key_only);</div>
|
|
</div><!-- fragment --><p>To attach multiple properties to a meta object, just invoke <code>prop</code> more than once.<br />
|
|
It's also possible to call <code>prop</code> at different times, as long as the factory is reset to the meta object of interest.</p>
|
|
<p>The meta objects for which properties are supported are currently meta types, meta data and meta functions.<br />
|
|
These types also 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"><span class="keywordflow">for</span>(<span class="keyword">auto</span> &&[<span class="keywordtype">id</span>, prop]: entt::resolve<my_type>().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<my_type>().prop(<span class="stringliteral">"tooltip"</span>_hs);</div>
|
|
</div><!-- fragment --><p>Meta properties are objects having a fairly poor interface, all in all. They only provide the <code>value</code> member function to retrieve the contained value in the form of a <code>meta_any</code> object.</p>
|
|
<h2><a class="anchor" id="autotoc_md166"></a>
|
|
Unregister types</h2>
|
|
<p>A type registered with the reflection system can also be <em>unregistered</em>. This means unregistering all its data members, member functions, conversion functions and so on. However, base classes aren't unregistered as well, since they don't necessarily depend on it.<br />
|
|
Roughly speaking, unregistering a type means disconnecting all associated meta objects from it and making its identifier no longer available:</p>
|
|
<div class="fragment"><div class="line">entt::meta_reset<my_type>();</div>
|
|
</div><!-- fragment --><p>It's also possible to reset types by their unique identifiers:</p>
|
|
<div class="fragment"><div class="line"><a class="code hl_function" href="namespaceentt.html#abe9a45bd7c93035354ec03dc7f196482">entt::meta_reset</a>(<span class="stringliteral">"my_type"</span>_hs);</div>
|
|
<div class="ttc" id="anamespaceentt_html_abe9a45bd7c93035354ec03dc7f196482"><div class="ttname"><a href="namespaceentt.html#abe9a45bd7c93035354ec03dc7f196482">entt::meta_reset</a></div><div class="ttdeci">void meta_reset() noexcept</div><div class="ttdoc">Resets a type and all its parts.</div><div class="ttdef"><b>Definition:</b> <a href="factory_8hpp_source.html#l00556">factory.hpp:556</a></div></div>
|
|
</div><!-- fragment --><p>Finally, there exists a non-template overload of the <code>meta_reset</code> function that doesn't accept arguments and resets all meta types at once:</p>
|
|
<div class="fragment"><div class="line"><a class="code hl_function" href="namespaceentt.html#abe9a45bd7c93035354ec03dc7f196482">entt::meta_reset</a>();</div>
|
|
</div><!-- fragment --><p>A type can be re-registered later with a completely different name and form.</p>
|
|
<h2><a class="anchor" id="autotoc_md167"></a>
|
|
Meta context</h2>
|
|
<p>All meta types and their parts are created at runtime and stored in a default <em>context</em>. This is obtained via a service locator as:</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">auto</span> &&context = <a class="code hl_function" href="classentt_1_1locator.html#ad7a9c3555e6ff2b67f9ad3af7f99a728">entt::locator<entt::meta_context>::value_or</a>();</div>
|
|
<div class="ttc" id="aclassentt_1_1locator_html_ad7a9c3555e6ff2b67f9ad3af7f99a728"><div class="ttname"><a href="classentt_1_1locator.html#ad7a9c3555e6ff2b67f9ad3af7f99a728">entt::locator::value_or</a></div><div class="ttdeci">static Service & value_or(Args &&...args)</div><div class="ttdoc">Returns a service if available or sets it from a fallback type.</div><div class="ttdef"><b>Definition:</b> <a href="locator_8hpp_source.html#l00078">locator.hpp:78</a></div></div>
|
|
</div><!-- fragment --><p>By itself, a context is an opaque object that the user cannot do much with. However, users can replace an existing context with another at any time:</p>
|
|
<div class="fragment"><div class="line">entt::meta_context other{};</div>
|
|
<div class="line"><span class="keyword">auto</span> &&context = <a class="code hl_function" href="classentt_1_1locator.html#ad7a9c3555e6ff2b67f9ad3af7f99a728">entt::locator<entt::meta_context>::value_or</a>();</div>
|
|
<div class="line">std::swap(context, other);</div>
|
|
</div><!-- fragment --><p>This is useful for testing purposes or to define multiple context objects with different meta type to use as appropriate.</p>
|
|
<p>If <em>replacing</em> the default context isn't enough, <code>EnTT</code> also offers the ability to use multiple and externally managed contexts with the runtime reflection system.<br />
|
|
For example, to create new meta types within a context other than the default one, simply pass it as an argument to the <code>meta</code> call:</p>
|
|
<div class="fragment"><div class="line"><a class="code hl_class" href="classentt_1_1meta__ctx.html">entt::meta_ctx</a> context{};</div>
|
|
<div class="line"><span class="keyword">auto</span> factory = entt::meta<my_type>(context).type(<span class="stringliteral">"reflected_type"</span>_hs);</div>
|
|
<div class="ttc" id="aclassentt_1_1meta__ctx_html"><div class="ttname"><a href="classentt_1_1meta__ctx.html">entt::meta_ctx</a></div><div class="ttdoc">Opaque meta context type.</div><div class="ttdef"><b>Definition:</b> <a href="context_8hpp_source.html#l00042">context.hpp:42</a></div></div>
|
|
</div><!-- fragment --><p>By doing so, the new meta type isn't available in the default context but is usable by passing around the new context when needed, such as when creating a new <code>meta_any</code> object:</p>
|
|
<div class="fragment"><div class="line"><a class="code hl_class" href="classentt_1_1meta__any.html">entt::meta_any</a> any{context, std::in_place_type<my_type>};</div>
|
|
</div><!-- fragment --><p>Similarly, to search for meta types in a context other than the default one, it's necessary to pass it to the <code>resolve</code> function:</p>
|
|
<div class="fragment"><div class="line"><a class="code hl_class" href="classentt_1_1meta__type.html">entt::meta_type</a> type = <a class="code hl_function" href="namespaceentt.html#a9dc2ece8ba5dafc463abdceb1f55eaea">entt::resolve</a>(context, <span class="stringliteral">"reflected_type"</span>_hs)</div>
|
|
</div><!-- fragment --><p>More generally, when using externally managed contexts, it's always required to provide the system with the context to use, at least at the <em>entry point</em>.<br />
|
|
For example, once the <code>meta_type</code> instant is obtained, it's no longer necessary to pass the context around as the meta type takes the information with it and eventually propagates it to all its parts.<br />
|
|
On the other hand, it's necessary to instruct the library on where meta types are to be fetched when <code>meta_any</code>s and <code>meta_handle</code>s are constructed, a factory created or a meta type resolved. </p>
|
|
</div></div><!-- contents -->
|
|
</div><!-- PageDoc -->
|
|
<!-- start footer part -->
|
|
<hr class="footer"/><address class="footer"><small>
|
|
Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.6
|
|
</small></address>
|
|
</body>
|
|
</html>
|