From 298336138aec4a364c12f7a41f1f0f5ae1630cdd Mon Sep 17 00:00:00 2001 From: ira Date: Mon, 24 Oct 2022 13:46:38 +0000 Subject: [PATCH] Clarify the behaviour of `iter_many` in the docs (#5973) Add the following message: ``` Items are returned in the order of the list of entities. Entities that don't match the query are skipped. ``` Additionally, the docs in `iter.rs` and `state.rs` were updated to match those in `query.rs`. Co-authored-by: devil-ira --- crates/bevy_ecs/src/query/iter.rs | 5 ++++- crates/bevy_ecs/src/query/state.rs | 14 ++++++++++---- crates/bevy_ecs/src/system/query.rs | 8 +++++++- 3 files changed, 21 insertions(+), 6 deletions(-) diff --git a/crates/bevy_ecs/src/query/iter.rs b/crates/bevy_ecs/src/query/iter.rs index 9cda2013cd979..34d1763aecc63 100644 --- a/crates/bevy_ecs/src/query/iter.rs +++ b/crates/bevy_ecs/src/query/iter.rs @@ -72,7 +72,10 @@ impl<'w, 's, Q: WorldQuery, F: ReadOnlyWorldQuery> Iterator for QueryIter<'w, 's // This is correct as [`QueryIter`] always returns `None` once exhausted. impl<'w, 's, Q: WorldQuery, F: ReadOnlyWorldQuery> FusedIterator for QueryIter<'w, 's, Q, F> {} -/// An [`Iterator`] over [`Query`](crate::system::Query) results of a list of [`Entity`]s. +/// An [`Iterator`] over the query items generated from an iterator of [`Entity`]s. +/// +/// Items are returned in the order of the provided iterator. +/// Entities that don't match the query are skipped. /// /// This struct is created by the [`Query::iter_many`](crate::system::Query::iter_many) and [`Query::iter_many_mut`](crate::system::Query::iter_many_mut) methods. pub struct QueryManyIter<'w, 's, Q: WorldQuery, F: ReadOnlyWorldQuery, I: Iterator> diff --git a/crates/bevy_ecs/src/query/state.rs b/crates/bevy_ecs/src/query/state.rs index 8be0d0c80b419..0f77b03a3b3f9 100644 --- a/crates/bevy_ecs/src/query/state.rs +++ b/crates/bevy_ecs/src/query/state.rs @@ -605,11 +605,14 @@ impl QueryState { } } - /// Returns an [`Iterator`] over the query results of a list of [`Entity`]'s. + /// Returns an [`Iterator`] over the read-only query items generated from an [`Entity`] list. /// - /// This can only return immutable data (mutable data will be cast to an immutable form). - /// See [`Self::iter_many_mut`] for queries that contain at least one mutable component. + /// Items are returned in the order of the list of entities. + /// Entities that don't match the query are skipped. /// + /// # See also + /// + /// - [`iter_many_mut`](Self::iter_many_mut) to get mutable query items. #[inline] pub fn iter_many<'w, 's, EntityList: IntoIterator>( &'s mut self, @@ -631,7 +634,10 @@ impl QueryState { } } - /// Returns an iterator over the query results of a list of [`Entity`]'s. + /// Returns an iterator over the query items generated from an [`Entity`] list. + /// + /// Items are returned in the order of the list of entities. + /// Entities that don't match the query are skipped. #[inline] pub fn iter_many_mut<'w, 's, EntityList: IntoIterator>( &'s mut self, diff --git a/crates/bevy_ecs/src/system/query.rs b/crates/bevy_ecs/src/system/query.rs index 43542e0f114a7..fcd4039a7983d 100644 --- a/crates/bevy_ecs/src/system/query.rs +++ b/crates/bevy_ecs/src/system/query.rs @@ -467,6 +467,9 @@ impl<'w, 's, Q: WorldQuery, F: ReadOnlyWorldQuery> Query<'w, 's, Q, F> { /// Returns an [`Iterator`] over the read-only query items generated from an [`Entity`] list. /// + /// Items are returned in the order of the list of entities. + /// Entities that don't match the query are skipped. + /// /// # Example /// /// ``` @@ -518,7 +521,10 @@ impl<'w, 's, Q: WorldQuery, F: ReadOnlyWorldQuery> Query<'w, 's, Q, F> { } } - /// Returns an [`Iterator`] over the query items generated from an [`Entity`] list. + /// Returns an iterator over the query items generated from an [`Entity`] list. + /// + /// Items are returned in the order of the list of entities. + /// Entities that don't match the query are skipped. /// /// # Examples ///