forestia/bevy
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add More Description to the Iter Combinations Documentation (#6260)

Browse Source 
# Objective

I was trying to implement a collision system for my game, and believed that the iter_combinations method might be what I need. But I couldn't find a simple explanation of what a combination was in Bevy and thought it could use some more explanation. 

## Solution

I added some description to the documentation that can hopefully further elaborate on what a combination is. 

I also changed up the docs for the method because a combination is a different thing than a permutation but the Bevy docs seemed to use them interchangeably.
This commit is contained in:
Carter Weinberg 2022-10-25 00:19:23 +00:00
parent 45e5eb1db3
commit c6f27eb054
2 changed files with 39 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
crates/bevy_ecs/src/query/iter.rs
View File

@ -219,12 +219,22 @@ where
/// An iterator over `K`-sized combinations of query items without repetition.
///
/// In this context, a combination is an unordered subset of `K` elements.
/// The number of combinations depend on how `K` relates to the number of entities matching the [`Query`] (called `N`):
/// A combination is an arrangement of a collection of items where order does not matter.
///
/// `K` is the number of items that make up each subset, and the number of items returned by the iterator.
/// `N` is the number of total entities output by the query.
///
/// For example, given the list [1, 2, 3, 4], where `K` is 2, the combinations without repeats are
/// [1, 2], [1, 3], [1, 4], [2, 3], [2, 4], [3, 4].
/// And in this case, `N` would be defined as 4 since the size of the input list is 4.
///
/// The number of combinations depend on how `K` relates to the number of entities matching the [`Query`]:
/// - if `K = N`, only one combination exists,
/// - if `K < N`, there are <sub>N</sub>C<sub>K</sub> combinations (see the [performance section] of `Query`),
/// - if `K > N`, there are no combinations.
///
/// The output combination is not guaranteed to have any order of iteration.
///
/// # Usage
///
/// This type is returned by calling [`Query::iter_combinations`] or [`Query::iter_combinations_mut`].

33
crates/bevy_ecs/src/query/state.rs
View File

@ -559,11 +559,22 @@ impl<Q: WorldQuery, F: ReadOnlyWorldQuery> QueryState<Q, F> {
/// Returns an [`Iterator`] over all possible combinations of `K` query results without repetition.
/// This can only be called for read-only queries.
///
/// For permutations of size `K` of query returning `N` results, you will get:
/// - if `K == N`: one permutation of all query results
/// A combination is an arrangement of a collection of items where order does not matter.
///
/// `K` is the number of items that make up each subset, and the number of items returned by the iterator.
/// `N` is the number of total entities output by query.
///
/// For example, given the list [1, 2, 3, 4], where `K` is 2, the combinations without repeats are
/// [1, 2], [1, 3], [1, 4], [2, 3], [2, 4], [3, 4].
/// And in this case, `N` would be defined as 4 since the size of the input list is 4.
///
/// For combinations of size `K` of query taking `N` inputs, you will get:
/// - if `K == N`: one combination of all query results
/// - if `K < N`: all possible `K`-sized combinations of query results, without repetition
/// - if `K > N`: empty set (no `K`-sized combinations exist)
///
/// The `iter_combinations` method does not guarantee order of iteration.
///
/// This can only be called for read-only queries, see [`Self::iter_combinations_mut`] for
/// write-queries.
#[inline]
@ -582,13 +593,23 @@ impl<Q: WorldQuery, F: ReadOnlyWorldQuery> QueryState<Q, F> {
}
}
/// Iterates over all possible combinations of `K` query results for the given [`World`]
/// without repetition.
/// Returns an [`Iterator`] over all possible combinations of `K` query results without repetition.
///
/// For permutations of size `K` of query returning `N` results, you will get:
/// - if `K == N`: one permutation of all query results
/// A combination is an arrangement of a collection of items where order does not matter.
///
/// `K` is the number of items that make up each subset, and the number of items returned by the iterator.
/// `N` is the number of total entities output by query.
///
/// For example, given the list [1, 2, 3, 4], where `K` is 2, the combinations without repeats are
/// [1, 2], [1, 3], [1, 4], [2, 3], [2, 4], [3, 4].
/// And in this case, `N` would be defined as 4 since the size of the input list is 4.
///
/// For combinations of size `K` of query taking `N` inputs, you will get:
/// - if `K == N`: one combination of all query results
/// - if `K < N`: all possible `K`-sized combinations of query results, without repetition
/// - if `K > N`: empty set (no `K`-sized combinations exist)
///
/// The `iter_combinations_mut` method does not guarantee order of iteration.
#[inline]
pub fn iter_combinations_mut<'w, 's, const K: usize>(
&'s mut self,