handle: added support for destroy (close #598)

docs/md/entity.md

@@ -692,8 +692,8 @@ copyable). An implication of this is that mutability becomes part of the
 type.
 
 There are two aliases that use `entt::entity` as their default entity:
-`entt::handle` and `entt::const_handle`. Users can also easily create their own
-aliases for custom identifiers as:
+`entt::handle` and `entt::const_handle`.<br/>
+Users can also easily create their own aliases for custom identifiers as:
 
 ```cpp
 using my_handle = entt::basic_handle<my_identifier>;

src/entt/entity/handle.hpp

@@ -86,7 +86,7 @@ struct basic_handle {
      * @return True if the handle refers to non-null registry and entity, false otherwise.
      */
     [[nodiscard]] explicit operator bool() const ENTT_NOEXCEPT {
-        return reg && entt != null;
+        return reg && reg->valid(entt);
     }
 
     /**
@@ -113,6 +113,23 @@ struct basic_handle {
         return entt;
     }
 
+    /**
+     * @brief Destroys the entity associated with a handle.
+     * @sa basic_registry::destroy
+     */
+    void destroy() {
+        reg->destroy(entt);
+    }
+
+    /**
+     * @brief Destroys the entity associated with a handle.
+     * @sa basic_registry::destroy
+     * @param version A desired version upon destruction.
+     */
+    void destroy(const typename registry_type::version_type version) {
+        reg->destroy(entt, version);
+    }
+
     /**
      * @brief Assigns the given component to a handle.
      * @sa basic_registry::emplace

test/entt/entity/handle.cpp

@@ -63,6 +63,40 @@ TEST(BasicHandle, Invalidation) {
     ASSERT_EQ(handle.entity(), entt::entity{entt::null});
 }
 
+TEST(BasicHandle, Destruction) {
+    entt::registry registry;
+    const auto entity = registry.create();
+    entt::handle handle{registry, entity};
+
+    ASSERT_TRUE(handle);
+    ASSERT_TRUE(handle.valid());
+    ASSERT_NE(handle.registry(), nullptr);
+    ASSERT_EQ(handle.entity(), entity);
+
+    handle.destroy(registry.version(entity));
+
+    ASSERT_FALSE(handle);
+    ASSERT_FALSE(handle.valid());
+    ASSERT_NE(handle.registry(), nullptr);
+    ASSERT_EQ(handle.entity(), entity);
+    ASSERT_EQ(registry.current(entity), typename entt::registry::version_type{});
+
+    handle = entt::handle{registry, registry.create()};
+
+    ASSERT_TRUE(handle);
+    ASSERT_TRUE(handle.valid());
+    ASSERT_NE(handle.registry(), nullptr);
+    ASSERT_EQ(handle.entity(), entity);
+
+    handle.destroy();
+
+    ASSERT_FALSE(handle);
+    ASSERT_FALSE(handle.valid());
+    ASSERT_NE(handle.registry(), nullptr);
+    ASSERT_EQ(handle.entity(), entity);
+    ASSERT_NE(registry.current(entity), typename entt::registry::version_type{});
+}
+
 TEST(BasicHandle, Comparison) {
     entt::registry registry;
     const auto entity = registry.create();