Skip to content

Commit

Permalink
Clarify the behaviour of iter_many in the docs (bevyengine#5973)
Browse files Browse the repository at this point in the history
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 <justthecooldude@gmail.com>
  • Loading branch information
2 people authored and Pietrek14 committed Dec 17, 2022
1 parent d6bbc11 commit 2983361
Show file tree
Hide file tree
Showing 3 changed files with 21 additions and 6 deletions.
5 changes: 4 additions & 1 deletion crates/bevy_ecs/src/query/iter.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
14 changes: 10 additions & 4 deletions crates/bevy_ecs/src/query/state.rs
Original file line number Diff line number Diff line change
Expand Up @@ -605,11 +605,14 @@ impl<Q: WorldQuery, F: ReadOnlyWorldQuery> QueryState<Q, F> {
}
}

/// 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,
Expand All @@ -631,7 +634,10 @@ impl<Q: WorldQuery, F: ReadOnlyWorldQuery> QueryState<Q, F> {
}
}

/// 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,
Expand Down
8 changes: 7 additions & 1 deletion crates/bevy_ecs/src/system/query.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
///
/// ```
Expand Down Expand Up @@ -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
///
Expand Down

0 comments on commit 2983361

Please sign in to comment.