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
151impl<E: Entity> Iterator for PopulationIterator<E> {
152    type Item = EntityId<E>;
153
154    fn next(&mut self) -> Option<Self::Item> {
155        if self.entity_id < self.population {
156            let current_id = self.entity_id;
157            // `self.entity_id` saturates to `self.population`.
158            self.entity_id += 1;
159            Some(EntityId::new(current_id))
160        } else {
161            None
162        }
163    }
164
165    // This iterator knows how many elements it will iterate over.
166    fn size_hint(&self) -> (usize, Option<usize>) {
167        let remaining = self.len();
168        (remaining, Some(remaining))
169    }
170
171    // Fast consuming count
172    fn count(self) -> usize {
173        self.len()
174    }
175
176    // Fast "seeking" operation.
177    fn nth(&mut self, n: usize) -> Option<Self::Item> {
178        // `self.entity_id` saturates to `self.population`.
179        self.entity_id = (self.entity_id + n).min(self.population);
180        self.next()
181    }
182}
183
184impl<E: Entity> ExactSizeIterator for PopulationIterator<E> {
185    fn len(&self) -> usize {
186        // Safety: Since `self.entity_id` saturates to `self.population`, we do not need `saturating_sub` here.
187        self.population - self.entity_id
188    }
189}
190// Once `PopulationIterator<E>` returns `None`, it will always return `None`.
191impl<E: Entity> std::iter::FusedIterator for PopulationIterator<E> {}
192
193#[cfg(test)]
194mod tests {
195    use super::*;
196    use crate::define_entity;
197
198    define_entity!(DummyEntity);
199
200    #[test]
201    fn entity_id_debug_display() {
202        let entity_id = DummyEntityId::new(137);
203        assert_eq!(format!("{:?}", entity_id), "DummyEntityId(137)");
204        assert_eq!(format!("{}", entity_id), "137");
205    }
206
207    #[test]
208    fn test_entity_iterator_basic() {
209        let mut iter = PopulationIterator::<DummyEntity>::new(3);
210
211        assert_eq!(iter.len(), 3);
212        assert_eq!(iter.next(), Some(EntityId::new(0)));
213        assert_eq!(iter.len(), 2);
214        assert_eq!(iter.next(), Some(EntityId::new(1)));
215        assert_eq!(iter.len(), 1);
216        assert_eq!(iter.next(), Some(EntityId::new(2)));
217        assert_eq!(iter.len(), 0);
218        assert_eq!(iter.next(), None);
219        assert_eq!(iter.len(), 0);
220        assert_eq!(iter.next(), None); // FusedIterator behavior
221    }
222
223    #[test]
224    fn test_entity_iterator_nth() {
225        let mut iter = PopulationIterator::<DummyEntity>::new(10);
226
227        // Seek to 3rd element (index 2)
228        assert_eq!(iter.nth(2), Some(EntityId::new(2)));
229        assert_eq!(iter.len(), 7);
230
231        // Seek relative to current position (+1 means skip index 3, return 4)
232        assert_eq!(iter.nth(1), Some(EntityId::new(4)));
233
234        // Seek past end
235        assert_eq!(iter.nth(10), None);
236        assert_eq!(iter.len(), 0);
237        assert_eq!(iter.next(), None);
238    }
239
240    #[test]
241    fn test_entity_iterator_size_hint() {
242        let mut iter = PopulationIterator::<DummyEntity>::new(5);
243        assert_eq!(iter.size_hint(), (5, Some(5)));
244
245        iter.next();
246        assert_eq!(iter.size_hint(), (4, Some(4)));
247
248        // Seek past end
249        assert_eq!(iter.nth(10), None);
250        assert_eq!(iter.size_hint(), (0, Some(0)));
251    }
252
253    #[test]
254    fn test_entity_iterator_clonable() {
255        let mut iter = PopulationIterator::<DummyEntity>::new(5);
256        iter.next();
257
258        let mut cloned = iter;
259        assert_eq!(iter.next(), cloned.next());
260        assert_eq!(iter.size_hint(), cloned.size_hint());
261    }
262}
ixa/entity/entity.rs

ixa/entity/
entity.rs
