meta: updated doc (see #361)
This commit is contained in:
1
TODO
1
TODO
@@ -38,5 +38,6 @@
|
||||
* stomp -> merge (naming is hard as heck, it's known thing)
|
||||
* observer: user defined filters (eg .replace<T, &function> or .group<T, U, &func>)
|
||||
* any-of rule for views/groups (eg entity has A and any of B/C/D)
|
||||
* sparse set: there exists an alternative to paginated sparse arrays?
|
||||
* meta
|
||||
- update doc
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user