|
|
@@ -32,7 +32,7 @@ which it belongs and not vice versa.
|
|
|
|
|
|
# Names and identifiers
|
|
|
|
|
|
-The meta system doesn't force the user to use the tools provided by the library
|
|
|
+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/>
|
|
|
@@ -227,12 +227,27 @@ entt::meta_any any{std::ref(value)};
|
|
|
In other words, whenever `meta_any` intercepts a `reference_wrapper`, 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.
|
|
|
+exceeds that of the container.<br/>
|
|
|
+Similarly, to create a copy that works as a light reference for the managed
|
|
|
+object, it's possible to dereference a given `meta_any`:
|
|
|
+
|
|
|
+```cpp
|
|
|
+entt::meta_any ref = *any;
|
|
|
+```
|
|
|
+
|
|
|
+It doesn't matter if the starting container actually holds an object or acts as
|
|
|
+a reference for unmanaged elements, the new instance thus created won't create
|
|
|
+copies and will only serve as a reference for the original item.<br/>
|
|
|
+It means that, starting from the example above, both `ref` and` any` will point
|
|
|
+to the same object, whether it's initially contained in `any` or already an
|
|
|
+unmanaged one. This is particularly useful for passing instances of `meta_any`
|
|
|
+belonging to the external context by reference to a function or a constructor
|
|
|
+rather than making copies of them.
|
|
|
|
|
|
The `meta_any` class has also a `type` member function that returns the meta
|
|
|
type of the contained value, if any. The member functions `try_cast`, `cast` and
|
|
|
-`convert` are used to know if the underlying object has a given type as a base
|
|
|
-or if it can be converted implicitly to it.
|
|
|
+`convert` are then used to know if the underlying object has a given type as a
|
|
|
+base or if it can be converted implicitly to it.
|
|
|
|
|
|
## Enjoy the runtime
|
|
|
|
|
|
@@ -264,8 +279,8 @@ resolve([](auto type) {
|
|
|
|
|
|
In all cases, the returned value is an instance of `meta_type`. This kind of
|
|
|
objects offer an API to know their _runtime identifiers_, to iterate all the
|
|
|
-meta objects associated with them and even to build or destroy instances of the
|
|
|
-underlying type.<br/>
|
|
|
+meta objects associated with them and even to build instances of the underlying
|
|
|
+type.<br/>
|
|
|
Refer to the inline documentation for all the details.
|
|
|
|
|
|
The meta objects that compose a meta type are accessed in the following ways:
|
|
|
@@ -283,17 +298,6 @@ The meta objects that compose a meta type are accessed in the following ways:
|
|
|
expected meta types. Furthermor, it's possible to invoke it and therefore to
|
|
|
construct new instances of the underlying type.
|
|
|
|
|
|
-* _Meta destructor_. It's returned by a dedicated function:
|
|
|
-
|
|
|
- ```cpp
|
|
|
- auto dtor = entt::resolve<my_type>().dtor();
|
|
|
- ```
|
|
|
-
|
|
|
- The returned type is `meta_dtor` 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.
|
|
|
-
|
|
|
* _Meta data_. They are accessed by _name_:
|
|
|
|
|
|
```cpp
|
|
|
@@ -354,9 +358,8 @@ if(auto func = entt::resolve<my_type>().func("member"_hs); func) {
|
|
|
}
|
|
|
```
|
|
|
|
|
|
-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:
|
|
|
+Furthermore, all meta objects can be iterated through an overload that accepts a
|
|
|
+callback through which to return them. As an example:
|
|
|
|
|
|
```cpp
|
|
|
entt::resolve<my_type>().data([](auto data) {
|
|
|
@@ -364,17 +367,20 @@ entt::resolve<my_type>().data([](auto data) {
|
|
|
});
|
|
|
```
|
|
|
|
|
|
-A meta type can also be used to `construct` or `destroy` actual instances of the
|
|
|
-underlying type.<br/>
|
|
|
+A meta type can be used to `construct` actual instances of the underlying
|
|
|
+type.<br/>
|
|
|
In particular, the `construct` member function accepts a variable number of
|
|
|
-arguments and searches for a match. It returns a `meta_any` object that may or
|
|
|
-may not be initialized, depending on whether a suitable constructor has been
|
|
|
-found or not. On the other side, the `destroy` member function accepts instances
|
|
|
-of `meta_any` as well as actual objects by reference and invokes the registered
|
|
|
-destructor, if any.<br/>
|
|
|
-Be aware that the result of a call to `destroy` may not be what is expected. The
|
|
|
-purpose is to give users the ability to free up resources that require special
|
|
|
-treatment and **not** to actually destroy instances.
|
|
|
+arguments and searches for a match. It then returns a `meta_any` object that may
|
|
|
+or may not be initialized, depending on whether a suitable constructor has been
|
|
|
+found or not.
|
|
|
+
|
|
|
+There is no object that wraps the destructor of a meta type nor a `destroy`
|
|
|
+member function in its API. The reason is quickly explained: destructors are
|
|
|
+invoked implicitly by `meta_any` behind the scenes and users have not to deal
|
|
|
+with them explicitly. Furthermore, they have no name, cannot be searched and
|
|
|
+wouldn't have member functions to expose anyway.<br/>
|
|
|
+Therefore, exposing destructors would be pointless and would add nothing to the
|
|
|
+library itself.
|
|
|
|
|
|
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
|