From 7e30574af4c2950e47e9d06da5c7834f108e3d8b Mon Sep 17 00:00:00 2001 From: Hennadii Chernyshchyk Date: Wed, 6 Jul 2022 19:49:21 +0300 Subject: [PATCH 1/3] Improve EntityMap API * Add len() and is_empty() methods. * Return previously mapped entity from insert() as in the regular HashMap. * Add documentation to all methods. --- crates/bevy_ecs/src/entity/map_entities.rs | 29 +++++++++++++++++++--- 1 file changed, 25 insertions(+), 4 deletions(-) diff --git a/crates/bevy_ecs/src/entity/map_entities.rs b/crates/bevy_ecs/src/entity/map_entities.rs index a4b9ea9f97960..5bf2b45e1888a 100644 --- a/crates/bevy_ecs/src/entity/map_entities.rs +++ b/crates/bevy_ecs/src/entity/map_entities.rs @@ -23,24 +23,33 @@ pub trait MapEntities { fn map_entities(&mut self, entity_map: &EntityMap) -> Result<(), MapEntitiesError>; } +/// A hash map adapter for mapping entities. #[derive(Default, Debug)] pub struct EntityMap { map: HashMap, } impl EntityMap { - pub fn insert(&mut self, from: Entity, to: Entity) { - self.map.insert(from, to); + /// Inserts an entities pair into the map. + /// + /// If the map did not have `from` present, [`None`] is returned. + /// + /// If the map did have `from` present, the value is updated, and the old value is returned. + pub fn insert(&mut self, from: Entity, to: Entity) -> Option { + self.map.insert(from, to) } - pub fn remove(&mut self, entity: Entity) { - self.map.remove(&entity); + /// Removes an `entity` from the map, returning the mapped value of it if the `entity` was previously in the map. + pub fn remove(&mut self, entity: Entity) -> Option { + self.map.remove(&entity) } + /// Gets the given entity's corresponding entry in the map for in-place manipulation. pub fn entry(&mut self, entity: Entity) -> Entry<'_, Entity, Entity> { self.map.entry(entity) } + /// Returns the corresponding mapped entity. pub fn get(&self, entity: Entity) -> Result { self.map .get(&entity) @@ -48,11 +57,23 @@ impl EntityMap { .ok_or(MapEntitiesError::EntityNotFound(entity)) } + /// An iterator visiting all keys in arbitrary order. pub fn keys(&self) -> impl Iterator + '_ { self.map.keys().cloned() } + /// An iterator visiting all values in arbitrary order. pub fn values(&self) -> impl Iterator + '_ { self.map.values().cloned() } + + /// Returns the number of elements in the map. + pub fn len(&self) -> usize { + self.map.len() + } + + /// Returns true if the map contains no elements. + pub fn is_empty(&self) -> bool { + self.map.is_empty() + } } From 124aa3fb9b0e1d7658620f5312ebaaf06b2f0116 Mon Sep 17 00:00:00 2001 From: Hennadii Chernyshchyk Date: Thu, 7 Jul 2022 18:32:05 +0300 Subject: [PATCH 2/3] Update crates/bevy_ecs/src/entity/map_entities.rs Co-authored-by: Alice Cecile --- crates/bevy_ecs/src/entity/map_entities.rs | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/crates/bevy_ecs/src/entity/map_entities.rs b/crates/bevy_ecs/src/entity/map_entities.rs index 5bf2b45e1888a..2ec67f2b9e447 100644 --- a/crates/bevy_ecs/src/entity/map_entities.rs +++ b/crates/bevy_ecs/src/entity/map_entities.rs @@ -23,7 +23,12 @@ pub trait MapEntities { fn map_entities(&mut self, entity_map: &EntityMap) -> Result<(), MapEntitiesError>; } -/// A hash map adapter for mapping entities. +/// A mapping from one set of entities to another. +/// +/// The API generally follows [`HashMap`], but each [`Entity`] is returned by value, as they are [`Copy`]. +/// +/// This is typically used to coordinate data transfer between sets of entities, such as between a scene and the world or over the network. +/// This is required as [`Entity`] identifiers are opaque; you cannot and do not want to reuse identifiers directly. #[derive(Default, Debug)] pub struct EntityMap { map: HashMap, From 9b96ec5e5cc8f79b95fde4b3549860a5cf4399ea Mon Sep 17 00:00:00 2001 From: Hennadii Chernyshchyk Date: Thu, 7 Jul 2022 19:35:15 +0300 Subject: [PATCH 3/3] Fix formatting --- crates/bevy_ecs/src/entity/map_entities.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/bevy_ecs/src/entity/map_entities.rs b/crates/bevy_ecs/src/entity/map_entities.rs index 2ec67f2b9e447..ae2d0476c44bc 100644 --- a/crates/bevy_ecs/src/entity/map_entities.rs +++ b/crates/bevy_ecs/src/entity/map_entities.rs @@ -28,7 +28,7 @@ pub trait MapEntities { /// The API generally follows [`HashMap`], but each [`Entity`] is returned by value, as they are [`Copy`]. /// /// This is typically used to coordinate data transfer between sets of entities, such as between a scene and the world or over the network. -/// This is required as [`Entity`] identifiers are opaque; you cannot and do not want to reuse identifiers directly. +/// This is required as [`Entity`] identifiers are opaque; you cannot and do not want to reuse identifiers directly. #[derive(Default, Debug)] pub struct EntityMap { map: HashMap,