Better ecs::entity_container documentation

libs/ecs/include/psemek/ecs/entity_accessor.hpp

@@ -1,50 +0,0 @@
-#pragma once
-
-#include <psemek/ecs/detail/table.hpp>
-#include <psemek/util/assert.hpp>
-
-namespace psemek::ecs
-{
-
-	struct entity_accessor
-	{
-		entity_accessor(detail::table * table, std::uint32_t row)
-			: table_(table)
-			, row_(row)
-		{}
-
-		template <typename Component>
-		Component * get_if()
-		{
-			util::uuid const uuid = Component::uuid();
-
-			auto const component_uuids = table_->get_component_uuids();
-
-			for (std::size_t i = 0; i < component_uuids.size(); ++i)
-				if (uuid == component_uuids[i])
-					return reinterpret_cast<Component *>(table_->get_component_pointers()[i].data + detail::stride<Component>() * row_);
-
-			return nullptr;
-		}
-
-		template <typename Component>
-		Component & get()
-		{
-			if (auto ptr = get_if<Component>())
-				return *ptr;
-			assert(false);
-			__builtin_unreachable();
-		}
-
-		template <typename Component>
-		bool contains() const
-		{
-			return get_if<Component>() != nullptr;
-		}
-
-	private:
-		detail::table * table_;
-		std::uint32_t row_;
-	};
-
-}

libs/ecs/include/psemek/ecs/entity_container.hpp

@@ -6,79 +6,183 @@
 #include <psemek/ecs/detail/query_cache_container.hpp>
 #include <psemek/ecs/detail/apply_helper.hpp>
 #include <psemek/ecs/detail/all_different_types.hpp>
-#include <psemek/ecs/entity_accessor.hpp>
 #include <psemek/util/span.hpp>
 #include <psemek/util/range.hpp>
+#include <psemek/util/exception.hpp>
+#include <psemek/util/type_name.hpp>
+#include <psemek/util/to_string.hpp>
+
+#include <typeindex>
 
 namespace psemek::ecs
 {
 
 	using query_cache = std::shared_ptr<detail::query_cache>;
 
+	struct component_exception
+		: util::exception
+	{
+		component_exception(std::type_info const & type, entity_handle const & handle, boost::stacktrace::stacktrace stacktrace = {})
+			: util::exception(util::to_string("Component ", util::type_name(type), " not found for entity ", handle), std::move(stacktrace))
+			, type_(type)
+			, handle_(handle)
+		{}
+
+		std::type_info const & type() const
+		{
+			return type_;
+		}
+
+		entity_handle const & handle() const
+		{
+			return handle_;
+		}
+
+	private:
+		std::type_info const & type_;
+		entity_handle handle_;
+	};
+
+	struct entity_accessor
+	{
+		entity_accessor() = default;
+		entity_accessor(entity_accessor const &) = default;
+
+		explicit operator bool() const;
+
+		/** Obtain a pointer to the specified component type
+		 *    of the accessed entity, or a null pointer if
+		 *    the entity doesn't contain this component type.
+		 */
+		template <typename Component>
+		Component * get_if();
+
+		/** Obtain a reference to the specified component type
+		 *    of the accessed entity.
+		 *  If the entity doesn't contain this component type,
+		 *    an exception of type `component_exception` is thrown.
+		 */
+		template <typename Component>
+		Component & get();
+
+		/** Check if the entity contains this component type.
+		 */
+		template <typename Component>
+		bool contains() const;
+
+	private:
+		detail::table * table_ = nullptr;
+		std::uint32_t row_ = 0;
+
+		friend struct entity_container;
+
+		entity_accessor(detail::table * table, std::uint32_t row);
+	};
+
 	struct entity_container
 	{
-		// Create an entity with the specified components
+		/** Create an entity with the specified components.
-		// NB: equivalent to create() followed by a
+		 *  It is faster to create an entity with all the components at once, than to
-		// series of attach() calls, but faster
+		 *    create it with no components and `attach()` them one-by-one.
-		// All components must be unique
+		 *  If any two of the passed component types are equal, the call fails with
+		 *    a compilation error.
+		 *  After the function returns, the new entity is considered alive (`alive(handle)` returns true).
+		 *  Creating a new entity invalidates all previously created entity accessors.
+		 *  If the entity is created during iteration (inside an `apply()` call), it is unspecified
+		 *    whether the created entity will be visited by iteration or not.
+		 */
 		template <typename ... Components>
 		entity_handle create(Components && ... components);
 
-		// Check if an entity handle refers to an active entity
+		/** Check if an entity handle refers to an alive entity (i.e. one that wasn't
-		// UB if the handle wasn't obtained by a create() call
+		 *    destroyed yet.
+		 *  Destroying an entity invalidates all previously created entity accessors.
+		 *  If the handle wasn't previously obtained by a `create()` call, the
+		 *    behavior is undefined.
+		 */
 		bool alive(entity_handle const & entity) const;
 
-		// Destroy an entity
+		/** Destroy an entity specified by a handle. After the call, `alive()`
-		// UB if the handle wasn't obtained by a create() call
+		 *    returns false for this handle.
-		// or if the entity was already destroyed
+		 *  If the entity is destroyed during iteration (inside an `apply()` call), the iteration
+		 *    is guaranteed not to visit the destroyed entity (unless it did so before the entity
+		 *    was destroyed).
+		 *  If the handle wasn't previously obtained by a `create()` call, or
+		 *    the refered entity was already destroyed, the behavior is undefined.
+		 */
 		void destroy(entity_handle const & entity);
 
-		// Get an entity accessor for an entity
+		/** Get an entity accessor for an entity, which provides access to
-		// UB if the handle wasn't obtained by a create() call
+		 *    the entitie's components.
-		// or if the entity isn't active
+		 *  If the handle wasn't previously obtained by a `create()` call, or
+		 *    the refered entity was already destroyed, the behavior is undefined.
+		 *  Creating or destroying entities invalidates all previously created
+		 *    entity accessors.
+		 */
 		entity_accessor get(entity_handle const & entity);
 
-		// Attach new components to an existing entity
+		/** Attach new components to an existing entity, or update existing
-		// If the entity already has a component, its value
+		 *    components with new values.
-		// is replaced with a new one
+		 *  If any two of the passed component types are equal, the call fails with
+		 *    a compilation error.
+		 *  Attaching components invalidates all previously created entity accessors.
+		 *  If the handle wasn't previously obtained by a `create()` call, or
+		 *    the refered entity was already destroyed, the behavior is undefined.
+		 */
 		// TODO: implement
 		template <typename ... Components>
 		void attach(entity_handle const & entity, Components && ... components);
 
-		// Remove components from an existing entity
+		/** Detach (remove) components from an existing entity.
+		 *  Detaching components invalidates all previously created entity accessors.
+		 *  If the handle wasn't previously obtained by a `create()` call, or
+		 *    the refered entity was already destroyed, the behavior is undefined.
+		 */
 		// TODO: implement
 		template <typename ... Components>
 		void detach(entity_handle const & entity);
 
-		// Create a query cache that can be used for the
+		/** Create a query cache that can be used for speeding up
-		// apply() call to speed it up
+		 *    the `apply()` calls.
+		 */
 		template <typename ... Components>
 		query_cache cache();
 
-		// Apply a function to all entities having the specified
+		/** Apply a function to all entities having the specified components,
-		// components. The function signature is one of
+		 *    in unspecified order.
-		//    void(components...)
+		 *  The function must have one of the following signatures:
-		//    void(entity_handle, components...)
+		 *      void(components...)
-		//    void(entity_container, components...)
+		 *      void(entity_handle, components...)
-		//    void(entity_container, entity_handle, components...)
+		 *      void(entity_container, components...)
-		// The function can create or destroy any entities.
+		 *      void(entity_container, entity_handle, components...)
-		// An optional query cache can be supplied to speed up the call
+		 *  The function can freely create or destroy entities. It is unspecified
-		// UB if the cache wasn't created with the exact same component sequence
+		 *    whether the function will or will not visit newly created entities
-		// UB if accessing the entitie's component after destroying it
+		 *    during this `apply()` call. The function is guaranteed not to visit
+		 *    destroyed entities (unless it did so before the entity was destroyed).
+		 *  An optional query cache can be supplied to speed up iteration.
+		 *  If the query cache wasn't created with the exact sequence of component
+		 *    types, the behavior is undefined.
+		 *  If the function accesses passed components after destroying the
+		 *    currently visited entity, the behavior is undefined.
+		 *  If the function recursively calls `apply()`, the behavior is undefined.
+		 */
 		template <typename ... Components, typename Function>
 		void apply(Function && function, query_cache cache = {});
 
-		// Apply a function to all entities having the specified
+		/** Apply a function to all entities having the specified components,
-		// components. Instead of applying the function to each entity,
+		 *    in unspecified order. Instead of applying the function to each
-		// the function is applied in "batch" mode, i.e. to array views
+		 *    entity separately, it is applied in "batch" mode, i.e. to array
-		// of components. The function signature is one of
+		 *    views of respective components.
-		//    void(span<components>...)
+		 *  The function must have one of the following signatures:
-		//    void(span<entity_handle const>, span<components>...)
+		 *      void(span<components>...)
-		//    void(entity_container, span<components>...)
+		 *      void(span<entity_handle const>, span<components>...)
-		//    void(entity_container, span<entity_handle const>, span<components>...)
+		 *      void(entity_container, span<components>...)
-		// An optional query cache can be supplied to speed up the call
+		 *      void(entity_container, span<entity_handle const>, span<components>...)
-		// UB if the cache wasn't created with the exact same component sequence
+		 *  An optional query cache can be supplied to speed up iteration.
-		// UB if the function tries to create or destroy entities
+		 *  If the query cache wasn't created with the exact sequence of component
+		 *    types, the behavior is undefined.
+		 *  If the function creates or destroyes entities, the behavior is undefined.
+		 */
 		template <typename ... Components, typename Function>
 		void batch_apply(Function && function, query_cache cache = {});
 
@@ -195,4 +299,43 @@ namespace psemek::ecs
 		}
 	}
 
+	inline entity_accessor::operator bool() const
+	{
+		return table_ != nullptr;
+	}
+
+	template <typename Component>
+	Component * entity_accessor::get_if()
+	{
+		util::uuid const uuid = Component::uuid();
+
+		auto const component_uuids = table_->get_component_uuids();
+
+		for (std::size_t i = 0; i < component_uuids.size(); ++i)
+			if (uuid == component_uuids[i])
+				return reinterpret_cast<Component *>(table_->get_component_pointers()[i].data + detail::stride<Component>() * row_);
+
+		return nullptr;
+	}
+
+	template <typename Component>
+	Component & entity_accessor::get()
+	{
+		if (auto ptr = get_if<Component>())
+			return *ptr;
+		assert(false);
+		__builtin_unreachable();
+	}
+
+	template <typename Component>
+	bool entity_accessor::contains() const
+	{
+		return get_if<Component>() != nullptr;
+	}
+
+	inline entity_accessor::entity_accessor(detail::table * table, std::uint32_t row)
+		: table_(table)
+		, row_(row)
+	{}
+
 }