Mirrors/bevy
2
0
Fork 0
mirror of https://github.com/bevyengine/bevy synced 2024-11-10 15:14:50 +00:00
Code Issues Projects Releases Packages Wiki Activity

Document QueryState (#2298)

Browse source 
# Objective

- QueryState is lacking documentation.

Fixes #2090 

## Solution

- Provide documentation that mirrors Query (as suggested in #2090) and modify as needed.


Co-authored-by: James Leflang <59455417+jleflang@users.noreply.github.com>
This commit is contained in:
James Leflang 2021-08-25 23:56:24 +00:00
parent b47217bfab
commit f38a6e670b
1 changed files with 84 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

84
crates/bevy_ecs/src/query/state.rs
View file

@ -13,6 +13,7 @@ use bevy_tasks::TaskPool;
use fixedbitset::FixedBitSet;
use thiserror::Error;
/// Provides scoped access to a [`World`] state according to a given [`WorldQuery`] and query filter.
pub struct QueryState<Q: WorldQuery, F: WorldQuery = ()>
where
F::Fetch: FilterFetch,
@ -35,6 +36,7 @@ impl<Q: WorldQuery, F: WorldQuery> QueryState<Q, F>
where
F::Fetch: FilterFetch,
{
/// Creates a new [`QueryState`] from a given [`World`] and inherits the result of `world.id()`.
pub fn new(world: &mut World) -> Self {
let fetch_state = <Q::State as FetchState>::init(world);
let filter_state = <F::State as FetchState>::init(world);
@ -68,6 +70,7 @@ where
state
}
/// Checks if the query is empty for the given [`World`], where the last change and current tick are given.
#[inline]
pub fn is_empty(&self, world: &World, last_change_tick: u32, change_tick: u32) -> bool {
// SAFE: the iterator is instantly consumed via `none_remaining` and the implementation of
@ -78,6 +81,12 @@ where
}
}
/// Takes a query for the given [`World`], checks if the given world is the same as the query, and
/// generates new archetypes for the given world.
///
/// # Panics
///
/// Panics if the `world.id()` does not equal the current [`QueryState`] internal id.
pub fn validate_world_and_update_archetypes(&mut self, world: &World) {
if world.id() != self.world_id {
panic!("Attempted to use {} with a mismatched World. QueryStates can only be used with the World they were created from.",
@ -93,6 +102,7 @@ where
}
}
/// Creates a new [`Archetype`].
pub fn new_archetype(&mut self, archetype: &Archetype) {
if self.fetch_state.matches_archetype(archetype)
&& self.filter_state.matches_archetype(archetype)
@ -116,6 +126,9 @@ where
}
}
/// Gets the query result for the given [`World`] and [`Entity`].
///
/// This can only be called for read-only queries, see [`Self::get_mut`] for write-queries.
#[inline]
pub fn get<'w, 's>(
&'s mut self,
@ -129,6 +142,7 @@ where
unsafe { self.get_unchecked(world, entity) }
}
/// Gets the query result for the given [`World`] and [`Entity`].
#[inline]
pub fn get_mut<'w, 's>(
&'s mut self,
@ -139,6 +153,8 @@ where
unsafe { self.get_unchecked(world, entity) }
}
/// Gets the query result for the given [`World`] and [`Entity`].
///
/// # Safety
///
/// This does not check for mutable query correctness. To be safe, make sure mutable queries
@ -158,7 +174,11 @@ where
)
}
/// Gets the query result for the given [`World`] and [`Entity`], where the last change and
/// the current change tick are given.
///
/// # Safety
///
/// This does not check for mutable query correctness. To be safe, make sure mutable queries
/// have unique access to the components they query.
pub unsafe fn get_unchecked_manual<'w, 's>(
@ -193,6 +213,9 @@ where
}
}
/// Returns an [`Iterator`] over the query results for the given [`World`].
///
/// This can only be called for read-only queries, see [`Self::iter_mut`] for write-queries.
#[inline]
pub fn iter<'w, 's>(&'s mut self, world: &'w World) -> QueryIter<'w, 's, Q, F>
where
@ -202,12 +225,23 @@ where
unsafe { self.iter_unchecked(world) }
}
/// Returns an [`Iterator`] over the query results for the given [`World`].
#[inline]
pub fn iter_mut<'w, 's>(&'s mut self, world: &'w mut World) -> QueryIter<'w, 's, Q, F> {
// SAFETY: query has unique world access
unsafe { self.iter_unchecked(world) }
}
/// 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
/// - if K < N: all possible K-sized combinations of query results, without repetition
/// - if K > N: empty set (no K-sized combinations exist)
///
/// This can only be called for read-only queries, see [`Self::iter_combinations_mut`] for
/// write-queries.
#[inline]
pub fn iter_combinations<'w, 's, const K: usize>(
&'s mut self,
@ -220,6 +254,13 @@ where
unsafe { self.iter_combinations_unchecked(world) }
}
/// Iterates over all possible combinations of `K` query results for the given [`World`]
/// without repetition.
///
/// For permutations of size K of query returning N results, you will get:
/// - if K == N: one permutation 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)
#[inline]
pub fn iter_combinations_mut<'w, 's, const K: usize>(
&'s mut self,
@ -229,6 +270,8 @@ where
unsafe { self.iter_combinations_unchecked(world) }
}
/// Returns an [`Iterator`] over the query results for the given [`World`].
///
/// # Safety
///
/// This does not check for mutable query correctness. To be safe, make sure mutable queries
@ -242,6 +285,10 @@ where
self.iter_unchecked_manual(world, world.last_change_tick(), world.read_change_tick())
}
/// Returns an [`Iterator`] over all possible combinations of `K` query results for the
/// given [`World`] without repetition.
/// This can only be called for read-only queries.
///
/// # Safety
///
/// This does not check for mutable query correctness. To be safe, make sure mutable queries
@ -259,7 +306,11 @@ where
)
}
/// Returns an [`Iterator`] for the given [`World`], where the last change and
/// the current change tick are given.
///
/// # Safety
///
/// This does not check for mutable query correctness. To be safe, make sure mutable queries
/// have unique access to the components they query.
/// This does not validate that `world.id()` matches `self.world_id`. Calling this on a `world`
@ -274,7 +325,12 @@ where
QueryIter::new(world, self, last_change_tick, change_tick)
}
/// Returns an [`Iterator`] over all possible combinations of `K` query results for the
/// given [`World`] without repetition.
/// This can only be called for read-only queries.
///
/// # Safety
///
/// This does not check for mutable query correctness. To be safe, make sure mutable queries
/// have unique access to the components they query.
/// This does not validate that `world.id()` matches `self.world_id`. Calling this on a `world`
@ -289,6 +345,10 @@ where
QueryCombinationIter::new(world, self, last_change_tick, change_tick)
}
/// Runs `func` on each query result for the given [`World`]. This is faster than the equivalent
/// iter() method, but cannot be chained like a normal [`Iterator`].
///
/// This can only be called for read-only queries, see [`Self::for_each_mut`] for write-queries.
#[inline]
pub fn for_each<'w, 's>(
&'s mut self,
@ -303,6 +363,8 @@ where
}
}
/// Runs `func` on each query result for the given [`World`]. This is faster than the equivalent
/// iter_mut() method, but cannot be chained like a normal [`Iterator`].
#[inline]
pub fn for_each_mut<'w, 's>(
&'s mut self,
@ -315,6 +377,11 @@ where
}
}
/// Runs `func` on each query result for the given [`World`]. This is faster than the equivalent
/// iter() method, but cannot be chained like a normal [`Iterator`].
///
/// This can only be called for read-only queries.
///
/// # Safety
///
/// This does not check for mutable query correctness. To be safe, make sure mutable queries
@ -334,6 +401,10 @@ where
);
}
/// Runs `func` on each query result in parallel using the given `task_pool`.
///
/// This can only be called for read-only queries, see [`Self::par_for_each_mut`] for
/// write-queries.
#[inline]
pub fn par_for_each<'w, 's>(
&'s mut self,
@ -350,6 +421,7 @@ where
}
}
/// Runs `func` on each query result in parallel using the given `task_pool`.
#[inline]
pub fn par_for_each_mut<'w, 's>(
&'s mut self,
@ -364,6 +436,10 @@ where
}
}
/// Runs `func` on each query result in parallel using the given `task_pool`.
///
/// This can only be called for read-only queries.
///
/// # Safety
///
/// This does not check for mutable query correctness. To be safe, make sure mutable queries
@ -387,6 +463,10 @@ where
);
}
/// Runs `func` on each query result for the given [`World`], where the last change and
/// the current change tick are given. This is faster than the equivalent
/// iter() method, but cannot be chained like a normal [`Iterator`].
///
/// # Safety
///
/// This does not check for mutable query correctness. To be safe, make sure mutable queries
@ -439,6 +519,10 @@ where
}
}
/// Runs `func` on each query result in parallel for the given [`World`], where the last change and
/// the current change tick are given. This is faster than the equivalent
/// iter() method, but cannot be chained like a normal [`Iterator`].
///
/// # Safety
///
/// This does not check for mutable query correctness. To be safe, make sure mutable queries