meta: updated doc (see #361)

This commit is contained in:
Michele Caini
2019-11-21 16:03:04 +01:00
parent 63bc0b2ba1
commit 22b93cdd0a
2 changed files with 37 additions and 30 deletions

1
TODO
View File

@@ -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

View File

@@ -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