pub trait Entity: Debug {
// Required methods
fn type_name(&self) -> &'static str;
fn type_id(&self) -> TypeId;
// Provided methods
fn is_container(&self) -> bool { ... }
fn is_ordered(&self) -> bool { ... }
fn len(&self) -> usize { ... }
fn elements(&self) -> Box<dyn Iterator<Item = KeyVal>> { ... }
fn element(&self, i: usize) -> KeyVal { ... }
}Expand description
The Entity trait defines a common interface for entities within a system, enabling
runtime reflection, inspection, and manipulation of their properties and elements. It
serves as a foundational component for dynamic entity handling, where entities can
represent data structures, components, or other logical units with introspectable
and manipulable state.
§Usage
Implementing the Entity trait allows a type to be integrated into systems that require
dynamic type inspection and manipulation, such as serialization frameworks, object-relational
mapping (ORM) systems, or generic containers and algorithms that operate on heterogeneous
entity collections.
§Key Concepts
-
Containment: Entities can act as containers for other entities, enabling hierarchical or composite data models.
-
Ordering: The trait distinguishes between ordered and unordered entities, affecting how their elements are iterated over or accessed.
-
Reflection: Through type metadata and element access methods, entities support reflection, allowing programmatic querying and manipulation of their structure and state.
§Implementing Entity
To implement the Entity trait, a type must provide implementations for all non-default
methods (type_name, type_id). The default method implementations assume non-container
entities with no elements and predictable ordering. Implementers should override these
defaults as appropriate to accurately reflect their specific semantics and behavior.
§Example
#[ derive(Debug)]
struct MyEntity
{
// Entity fields
}
impl Entity for MyEntity
{
#[ inline ]
fn type_name( &self ) -> &'static str
{
"MyEntity"
}
#[ inline ]
fn type_id(&self) -> core::any::TypeId
{
core::any::TypeId::of::< MyEntity >()
}
// Additional method implementations as necessary...
}This trait is designed to be flexible and extensible, accommodating a wide variety of entity types and use cases. Implementers are encouraged to leverage Rust’s type system and trait mechanisms to provide rich, dynamic behavior in a type-safe manner.
Required Methods§
Provided Methods§
Sourcefn is_container(&self) -> bool
fn is_container(&self) -> bool
Determines if the entity acts as a container for other entities.
§Returns
Returns true if the entity can contain other entities (like a struct, vector, etc.),
otherwise false.
By default, this method returns false, assuming that the entity does not act as a container.
Sourcefn is_ordered(&self) -> bool
fn is_ordered(&self) -> bool
Determines if the elements of the container are maintained in a specific order.
This method indicates whether the container preserves a specific order of its elements. The concept of “order” can refer to:
- Sorted Order: Where elements are arranged based on a sorting criterion, typically through comparison operations.
- Insertion Order: Where elements retain the order in which they were added to the container.
It is important to distinguish this property in collections to understand how iteration over the elements will proceed and what expectations can be held about the sequence of elements when accessed.
§Returns
trueif the container maintains its elements in a predictable order. This is typically true for data structures like arrays, slices, and vectors, where elements are accessed sequentially or are sorted based on inherent or specified criteria.falsefor collections where the arrangement of elements does not follow a predictable sequence from the perspective of an observer, such as sets and maps implemented via hashing. In these structures, the order of elements is determined by their hash and internal state, rather than the order of insertion or sorting.
By default, this method returns true, assuming that the entity behaves like an array, slice,
or vector, where the order of elements is consistent and predictable. Implementers should override
this behavior for collections where element order is not maintained or is irrelevant.
Sourcefn len(&self) -> usize
fn len(&self) -> usize
Returns the number of elements contained in the entity.
§Returns
Returns the count of elements if the entity is a container, otherwise 0.
This method is particularly useful for collections or composite entities.
By default, this method returns 0, assuming the entity contains no elements.
Sourcefn elements(&self) -> Box<dyn Iterator<Item = KeyVal>>
fn elements(&self) -> Box<dyn Iterator<Item = KeyVal>>
Provides an iterator over the elements contained within the entity, if any.
§Returns
Returns a boxed iterator over KeyVal pairs representing the key-value mappings
of the entity’s elements. For non-container entities, an empty iterator is returned.
This method is crucial for traversing composite entities or collections at runtime, allowing for dynamic inspection and manipulation.