Michele Caini пре 6 година
родитељ
комит
22b93cdd0a
2 измењених фајлова са 37 додато и 30 уклоњено
  1. 1 0
      TODO
  2. 36 30
      docs/md/meta.md

+ 1 - 0
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

+ 36 - 30
docs/md/meta.md

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