ixa/entity/
entity.rs

1/*!
2
3An implementor of [`Entity`] is a type that names a collection of related properties in
4analogy to a table in a database. The properties are analogous to the columns in the table,
5and the [`EntityId<E>`] type is analogous to the primary key of the table, the row number.
6
7[`Entity`]s are declared with the [`define_entity!`] macro:
8
9```rust
10use ixa::define_entity;
11define_entity!(Person);
12```
13
14Once an [`Entity`] is defined, [`Property`]s can be defined for the [`Entity`]. See the
15[`property`](crate::entity::property) module.
16
17Right now an `Entity` type is just a zero-sized marker type. The static data associated with the type isn't used yet.
18
19*/
20
21use std::any::{Any, TypeId};
22use std::fmt::{Debug, Display, Formatter};
23use std::hash::{Hash, Hasher};
24use std::marker::PhantomData;
25
26use serde::{Deserialize, Serialize};
27
28use super::entity_store::get_entity_metadata_static;
29
30/// A type that can be named and used (copied, cloned) but not created outside of this crate.
31/// In the `define_entity!` macro we define the alias `pub type MyEntityId = EntityId<MyEntity>`.
32#[derive(Serialize, Deserialize)]
33#[serde(transparent)]
34pub struct EntityId<E: Entity>(pub(crate) usize, PhantomData<E>);
35// Note: The generics on `EntityId<E>` prevent the compiler from "seeing" the derived traits in some client code,
36//       so we provide blanket implementations below.
37
38// Otherwise the compiler isn't smart enough to know `EntityId<E>` is always `PartialEq`/`Eq`
39impl<E: Entity> PartialEq for EntityId<E> {
40    fn eq(&self, other: &Self) -> bool {
41        self.0 == other.0
42    }
43}
44impl<E: Entity> Eq for EntityId<E> {}
45
46// Otherwise the compiler isn't smart enough to know `EntityId<E>` is always `Clone`
47impl<E: Entity> Clone for EntityId<E> {
48    #[inline]
49    fn clone(&self) -> Self {
50        *self
51    }
52}
53
54// Otherwise the compiler isn't smart enough to know `EntityId<E>` is always `Copy`
55impl<E: Entity> Copy for EntityId<E> {}
56
57// The value `EntityId<Person>(7, PhantomData<Person>)` has `Debug` display "PersonId(7)".
58impl<E: Entity> Debug for EntityId<E> {
59    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
60        let name = format!("{}Id", E::name());
61        f.debug_tuple(name.as_str()).field(&self.0).finish()
62    }
63}
64// The value `EntityId<Person>(7, PhantomData<Person>)` will display as "7".
65impl<E: Entity> Display for EntityId<E> {
66    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
67        write!(f, "{}", self.0)
68    }
69}
70
71// Otherwise the compiler isn't smart enough to know `EntityId<E>` is always `Hash`
72impl<E: Entity> Hash for EntityId<E> {
73    fn hash<H: Hasher>(&self, state: &mut H) {
74        self.0.hash(state);
75    }
76}
77
78impl<E: Entity> EntityId<E> {
79    /// Only constructible from this crate.
80    pub(crate) fn new(index: usize) -> Self {
81        Self(index, PhantomData)
82    }
83}
84
85/// All entities must implement this trait using the `define_entity!` macro.
86pub trait Entity: Any + Default {
87    fn name() -> &'static str {
88        let full = std::any::type_name::<Self>();
89        full.rsplit("::").next().unwrap()
90    }
91
92    fn type_id() -> TypeId {
93        TypeId::of::<Self>()
94    }
95
96    /// Get a list of all properties this `Entity` has. This list is static, computed in with `ctor` magic.
97    fn property_ids() -> &'static [TypeId] {
98        let (property_ids, _) = get_entity_metadata_static(<Self as Entity>::type_id());
99        property_ids
100    }
101
102    /// Get a list of all properties of this `Entity` that _must_ be supplied when a new entity is created.
103    fn required_property_ids() -> &'static [TypeId] {
104        let (_, required_property_ids) = get_entity_metadata_static(<Self as Entity>::type_id());
105        required_property_ids
106    }
107
108    /// The index of this item in the owner, which is initialized globally per type
109    /// upon first access. We explicitly initialize this in a `ctor` in order to know
110    /// how many [`Entity`] types exist globally when we construct any `EntityStore`.
111    fn id() -> usize;
112
113    /// Creates a new boxed instance of the item.
114    fn new_boxed() -> Box<Self> {
115        Box::default()
116    }
117
118    /// Standard pattern for downcasting to concrete types.
119    fn as_any(&self) -> &dyn Any;
120    fn as_any_mut(&mut self) -> &mut dyn Any;
121}
122
123pub type BxEntity = Box<dyn Entity>;
124
125/// An iterator over the total population of `EntityId<E>`s at the time of iterator creation.
126///
127/// If entities are added _after_ this iterator has been created, this iterator will _not_ produce the `EntityId<E>`s
128/// of the newly added entities.
129#[derive(Copy, Clone)]
130pub struct PopulationIterator<E: Entity> {
131    /// The total count of all entities of this type at the time this iterator was created
132    population: usize,
133    /// The next `EntityId<E>` this iterator will produce (assuming `entity_id < population`)
134    entity_id: usize,
135
136    _phantom: PhantomData<E>,
137}
138
139impl<E: Entity> PopulationIterator<E> {
140    // Only internal ixa code can create a new `PopulationIterator<E>` in order to guarantee only valid
141    // `EntityId<E>` values are ever created.
142    pub(crate) fn new(population: usize) -> Self {
143        PopulationIterator::<E> {
144            population,
145            entity_id: 0,
146            _phantom: PhantomData,
147        }
148    }
149
150    #[must_use]
151    pub(crate) fn population(&self) -> usize {
152        self.population
153    }
154}
155
156impl<E: Entity> Iterator for PopulationIterator<E> {
157    type Item = EntityId<E>;
158
159    fn next(&mut self) -> Option<Self::Item> {
160        if self.entity_id < self.population {
161            let current_id = self.entity_id;
162            // `self.entity_id` saturates to `self.population`.
163            self.entity_id += 1;
164            Some(EntityId::new(current_id))
165        } else {
166            None
167        }
168    }
169
170    // This iterator knows how many elements it will iterate over.
171    fn size_hint(&self) -> (usize, Option<usize>) {
172        let remaining = self.len();
173        (remaining, Some(remaining))
174    }
175
176    // Fast consuming count
177    fn count(self) -> usize {
178        self.len()
179    }
180
181    // Fast "seeking" operation.
182    fn nth(&mut self, n: usize) -> Option<Self::Item> {
183        // `self.entity_id` saturates to `self.population`.
184        self.entity_id = (self.entity_id + n).min(self.population);
185        self.next()
186    }
187}
188
189impl<E: Entity> ExactSizeIterator for PopulationIterator<E> {
190    fn len(&self) -> usize {
191        // Safety: Since `self.entity_id` saturates to `self.population`, we do not need `saturating_sub` here.
192        self.population - self.entity_id
193    }
194}
195// Once `PopulationIterator<E>` returns `None`, it will always return `None`.
196impl<E: Entity> std::iter::FusedIterator for PopulationIterator<E> {}
197
198#[cfg(test)]
199mod tests {
200    use super::*;
201    use crate::define_entity;
202
203    define_entity!(DummyEntity);
204
205    #[test]
206    fn entity_id_debug_display() {
207        let entity_id = DummyEntityId::new(137);
208        assert_eq!(format!("{:?}", entity_id), "DummyEntityId(137)");
209        assert_eq!(format!("{}", entity_id), "137");
210    }
211
212    #[test]
213    fn test_entity_iterator_basic() {
214        let mut iter = PopulationIterator::<DummyEntity>::new(3);
215
216        assert_eq!(iter.len(), 3);
217        assert_eq!(iter.next(), Some(EntityId::new(0)));
218        assert_eq!(iter.len(), 2);
219        assert_eq!(iter.next(), Some(EntityId::new(1)));
220        assert_eq!(iter.len(), 1);
221        assert_eq!(iter.next(), Some(EntityId::new(2)));
222        assert_eq!(iter.len(), 0);
223        assert_eq!(iter.next(), None);
224        assert_eq!(iter.len(), 0);
225        assert_eq!(iter.next(), None); // FusedIterator behavior
226    }
227
228    #[test]
229    fn test_entity_iterator_nth() {
230        let mut iter = PopulationIterator::<DummyEntity>::new(10);
231
232        // Seek to 3rd element (index 2)
233        assert_eq!(iter.nth(2), Some(EntityId::new(2)));
234        assert_eq!(iter.len(), 7);
235
236        // Seek relative to current position (+1 means skip index 3, return 4)
237        assert_eq!(iter.nth(1), Some(EntityId::new(4)));
238
239        // Seek past end
240        assert_eq!(iter.nth(10), None);
241        assert_eq!(iter.len(), 0);
242        assert_eq!(iter.next(), None);
243    }
244
245    #[test]
246    fn test_entity_iterator_size_hint() {
247        let mut iter = PopulationIterator::<DummyEntity>::new(5);
248        assert_eq!(iter.size_hint(), (5, Some(5)));
249
250        iter.next();
251        assert_eq!(iter.size_hint(), (4, Some(4)));
252
253        // Seek past end
254        assert_eq!(iter.nth(10), None);
255        assert_eq!(iter.size_hint(), (0, Some(0)));
256    }
257
258    #[test]
259    fn test_entity_iterator_clonable() {
260        let mut iter = PopulationIterator::<DummyEntity>::new(5);
261        iter.next();
262
263        let mut cloned = iter;
264        assert_eq!(iter.next(), cloned.next());
265        assert_eq!(iter.size_hint(), cloned.size_hint());
266    }
267}
ixa/entity/entity.rs

ixa/entity/
entity.rs
