diff --git a/benches/benches/bevy_ecs/world/world_get.rs b/benches/benches/bevy_ecs/world/world_get.rs index 283b984186150..57dcf5c17b6b3 100644 --- a/benches/benches/bevy_ecs/world/world_get.rs +++ b/benches/benches/bevy_ecs/world/world_get.rs @@ -325,10 +325,7 @@ pub fn query_get_many(criterion: &mut Criterion) { bencher.iter(|| { let mut count = 0; - for comp in entity_groups - .iter() - .filter_map(|&ids| query.get_many(ids).ok()) - { + for comp in entity_groups.iter().filter_map(|&ids| query.many(ids).ok()) { black_box(comp); count += 1; black_box(count); @@ -348,10 +345,7 @@ pub fn query_get_many(criterion: &mut Criterion) { bencher.iter(|| { let mut count = 0; - for comp in entity_groups - .iter() - .filter_map(|&ids| query.get_many(ids).ok()) - { + for comp in entity_groups.iter().filter_map(|&ids| query.many(ids).ok()) { black_box(comp); count += 1; black_box(count); diff --git a/crates/bevy_ecs/compile_fail/tests/ui/system_query_get_many_lifetime_safety.rs b/crates/bevy_ecs/compile_fail/tests/ui/system_query_get_many_lifetime_safety.rs index 522d4628f65f1..e2ac17a2c6fa6 100644 --- a/crates/bevy_ecs/compile_fail/tests/ui/system_query_get_many_lifetime_safety.rs +++ b/crates/bevy_ecs/compile_fail/tests/ui/system_query_get_many_lifetime_safety.rs @@ -4,7 +4,7 @@ use bevy_ecs::prelude::*; struct A(usize); fn system(mut query: Query<&mut A>, e: Entity) { - let a1 = query.get_many([e, e]).unwrap(); + let a1 = query.many([e, e]).unwrap(); let a2 = query.get_mut(e).unwrap(); //~^ E0502 println!("{} {}", a1[0].0, a2.0); diff --git a/crates/bevy_ecs/compile_fail/tests/ui/system_query_get_many_lifetime_safety.stderr b/crates/bevy_ecs/compile_fail/tests/ui/system_query_get_many_lifetime_safety.stderr index 91e8b81509e05..ca9d2ee2447e0 100644 --- a/crates/bevy_ecs/compile_fail/tests/ui/system_query_get_many_lifetime_safety.stderr +++ b/crates/bevy_ecs/compile_fail/tests/ui/system_query_get_many_lifetime_safety.stderr @@ -1,7 +1,7 @@ error[E0502]: cannot borrow `query` as mutable because it is also borrowed as immutable --> tests/ui/system_query_get_many_lifetime_safety.rs:8:14 | -7 | let a1 = query.get_many([e, e]).unwrap(); +7 | let a1 = query.many([e, e]).unwrap(); | ----- immutable borrow occurs here 8 | let a2 = query.get_mut(e).unwrap(); | ^^^^^^^^^^^^^^^^ mutable borrow occurs here diff --git a/crates/bevy_ecs/compile_fail/tests/ui/system_query_get_many_mut_lifetime_safety.rs b/crates/bevy_ecs/compile_fail/tests/ui/system_query_get_many_mut_lifetime_safety.rs index 5a45ffd65e062..7e732b52c924b 100644 --- a/crates/bevy_ecs/compile_fail/tests/ui/system_query_get_many_mut_lifetime_safety.rs +++ b/crates/bevy_ecs/compile_fail/tests/ui/system_query_get_many_mut_lifetime_safety.rs @@ -4,7 +4,7 @@ use bevy_ecs::prelude::*; struct A(usize); fn system(mut query: Query<&mut A>, e: Entity) { - let a1 = query.get_many_mut([e, e]).unwrap(); + let a1 = query.many_mut([e, e]).unwrap(); let a2 = query.get_mut(e).unwrap(); //~^ E0499 println!("{} {}", a1[0].0, a2.0); diff --git a/crates/bevy_ecs/compile_fail/tests/ui/system_query_get_many_mut_lifetime_safety.stderr b/crates/bevy_ecs/compile_fail/tests/ui/system_query_get_many_mut_lifetime_safety.stderr index 567a1da1a683e..11a7c5653f8c3 100644 --- a/crates/bevy_ecs/compile_fail/tests/ui/system_query_get_many_mut_lifetime_safety.stderr +++ b/crates/bevy_ecs/compile_fail/tests/ui/system_query_get_many_mut_lifetime_safety.stderr @@ -1,7 +1,7 @@ error[E0499]: cannot borrow `query` as mutable more than once at a time --> tests/ui/system_query_get_many_mut_lifetime_safety.rs:8:14 | -7 | let a1 = query.get_many_mut([e, e]).unwrap(); +7 | let a1 = query.many_mut([e, e]).unwrap(); | ----- first mutable borrow occurs here 8 | let a2 = query.get_mut(e).unwrap(); | ^^^^^ second mutable borrow occurs here diff --git a/crates/bevy_ecs/src/lib.rs b/crates/bevy_ecs/src/lib.rs index 612e32b492b54..ff0ea7c95308a 100644 --- a/crates/bevy_ecs/src/lib.rs +++ b/crates/bevy_ecs/src/lib.rs @@ -1830,7 +1830,7 @@ mod tests { world.insert_batch(values); let mut query = world.query::<(Option<&A>, &B, &C)>(); - let component_values = query.get_many(&world, [e0, e1, e2]).unwrap(); + let component_values = query.many(&world, [e0, e1, e2]).unwrap(); assert_eq!( component_values, diff --git a/crates/bevy_ecs/src/query/error.rs b/crates/bevy_ecs/src/query/error.rs index 6d0b149b86058..4eb2f9db67312 100644 --- a/crates/bevy_ecs/src/query/error.rs +++ b/crates/bevy_ecs/src/query/error.rs @@ -17,7 +17,7 @@ pub enum QueryEntityError { EntityDoesNotExist(EntityDoesNotExistError), /// The [`Entity`] was requested mutably more than once. /// - /// See [`Query::get_many_mut`](crate::system::Query::get_many_mut) for an example. + /// See [`Query::many_mut`](crate::system::Query::many_mut) for an example. AliasedMutability(Entity), } diff --git a/crates/bevy_ecs/src/query/mod.rs b/crates/bevy_ecs/src/query/mod.rs index c1744cbf24211..1722572f6b074 100644 --- a/crates/bevy_ecs/src/query/mod.rs +++ b/crates/bevy_ecs/src/query/mod.rs @@ -439,14 +439,14 @@ mod tests { } #[test] - fn get_many_only_mut_checks_duplicates() { + fn many_only_mut_checks_duplicates() { let mut world = World::new(); let id = world.spawn(A(10)).id(); let mut query_state = world.query::<&mut A>(); let mut query = query_state.query_mut(&mut world); - let result = query.get_many([id, id]); + let result = query.many([id, id]); assert_eq!(result, Ok([&A(10), &A(10)])); - let mut_result = query.get_many_mut([id, id]); + let mut_result = query.many_mut([id, id]); assert!(mut_result.is_err()); } @@ -763,7 +763,7 @@ mod tests { let _: Option<&Foo> = q.get(&world, e).ok(); let _: Option<&Foo> = q.get_manual(&world, e).ok(); - let _: Option<[&Foo; 1]> = q.get_many(&world, [e]).ok(); + let _: Option<[&Foo; 1]> = q.many(&world, [e]).ok(); let _: Option<&Foo> = q.single(&world).ok(); let _: &Foo = q.single(&world).unwrap(); @@ -776,7 +776,7 @@ mod tests { q.iter().for_each(|_: &Foo| ()); let _: Option<&Foo> = q.get(e).ok(); - let _: Option<[&Foo; 1]> = q.get_many([e]).ok(); + let _: Option<[&Foo; 1]> = q.many([e]).ok(); let _: Option<&Foo> = q.single().ok(); let _: &Foo = q.single().unwrap(); } diff --git a/crates/bevy_ecs/src/query/state.rs b/crates/bevy_ecs/src/query/state.rs index 393971c4ac2ed..8bdd39c59ae7e 100644 --- a/crates/bevy_ecs/src/query/state.rs +++ b/crates/bevy_ecs/src/query/state.rs @@ -961,7 +961,7 @@ impl QueryState { /// In case of a nonexisting entity or mismatched component, a [`QueryEntityError`] is /// returned instead. /// - /// Note that the unlike [`QueryState::get_many_mut`], the entities passed in do not need to be unique. + /// Note that the unlike [`QueryState::many_mut`], the entities passed in do not need to be unique. /// /// # Examples /// @@ -980,21 +980,32 @@ impl QueryState { /// /// let mut query_state = world.query::<&A>(); /// - /// let component_values = query_state.get_many(&world, entities).unwrap(); + /// let component_values = query_state.many(&world, entities).unwrap(); /// /// assert_eq!(component_values, [&A(0), &A(1), &A(2)]); /// /// let wrong_entity = Entity::from_raw(365); /// - /// assert_eq!(match query_state.get_many(&mut world, [wrong_entity]).unwrap_err() {QueryEntityError::EntityDoesNotExist(error) => error.entity, _ => panic!()}, wrong_entity); + /// assert_eq!(match query_state.many(&mut world, [wrong_entity]).unwrap_err() {QueryEntityError::EntityDoesNotExist(error) => error.entity, _ => panic!()}, wrong_entity); /// ``` #[inline] + pub fn many<'w, const N: usize>( + &mut self, + world: &'w World, + entities: [Entity; N], + ) -> Result<[ROQueryItem<'w, D>; N], QueryEntityError> { + self.query(world).many_inner(entities) + } + + /// A deprecated alias for [`many`](Self::many). + #[inline] + #[deprecated(since = "0.16.0", note = "Please use `many` instead")] pub fn get_many<'w, const N: usize>( &mut self, world: &'w World, entities: [Entity; N], ) -> Result<[ROQueryItem<'w, D>; N], QueryEntityError> { - self.query(world).get_many_inner(entities) + self.many(world, entities) } /// Returns the read-only query results for the given [`UniqueEntityArray`]. @@ -1005,8 +1016,8 @@ impl QueryState { /// # Examples /// /// ``` - /// use bevy_ecs::{prelude::*, query::QueryEntityError, entity::{EntitySetIterator, unique_array::UniqueEntityArray, unique_vec::UniqueEntityVec}}; - /// + /// # use bevy_ecs::{prelude::*, query::QueryEntityError, entity::{EntitySetIterator, unique_array::UniqueEntityArray, unique_vec::UniqueEntityVec}}; + /// # /// #[derive(Component, PartialEq, Debug)] /// struct A(usize); /// @@ -1018,21 +1029,30 @@ impl QueryState { /// /// let mut query_state = world.query::<&A>(); /// - /// let component_values = query_state.get_many_unique(&world, entity_set).unwrap(); + /// let component_values = query_state.many_unique(&world, entity_set).unwrap(); /// /// assert_eq!(component_values, [&A(0), &A(1), &A(2)]); /// /// let wrong_entity = Entity::from_raw(365); /// - /// assert_eq!(match query_state.get_many_unique(&mut world, UniqueEntityArray::from([wrong_entity])).unwrap_err() {QueryEntityError::EntityDoesNotExist(error) => error.entity, _ => panic!()}, wrong_entity); + /// assert_eq!( + /// match query_state + /// .many_unique(&mut world, UniqueEntityArray::from([wrong_entity])) + /// .unwrap_err() + /// { + /// QueryEntityError::EntityDoesNotExist(error) => error.entity, + /// _ => panic!(), + /// }, + /// wrong_entity, + /// ); /// ``` #[inline] - pub fn get_many_unique<'w, const N: usize>( + pub fn many_unique<'w, const N: usize>( &mut self, world: &'w World, entities: UniqueEntityArray, ) -> Result<[ROQueryItem<'w, D>; N], QueryEntityError> { - self.query(world).get_many_unique_inner(entities) + self.query(world).many_unique_inner(entities) } /// Gets the query result for the given [`World`] and [`Entity`]. @@ -1068,30 +1088,41 @@ impl QueryState { /// /// let mut query_state = world.query::<&mut A>(); /// - /// let mut mutable_component_values = query_state.get_many_mut(&mut world, entities).unwrap(); + /// let mut mutable_component_values = query_state.many_mut(&mut world, entities).unwrap(); /// /// for mut a in &mut mutable_component_values { /// a.0 += 5; /// } /// - /// let component_values = query_state.get_many(&world, entities).unwrap(); + /// let component_values = query_state.many(&world, entities).unwrap(); /// /// assert_eq!(component_values, [&A(5), &A(6), &A(7)]); /// /// let wrong_entity = Entity::from_raw(57); /// let invalid_entity = world.spawn_empty().id(); /// - /// assert_eq!(match query_state.get_many(&mut world, [wrong_entity]).unwrap_err() {QueryEntityError::EntityDoesNotExist(error) => error.entity, _ => panic!()}, wrong_entity); - /// assert_eq!(match query_state.get_many_mut(&mut world, [invalid_entity]).unwrap_err() {QueryEntityError::QueryDoesNotMatch(entity, _) => entity, _ => panic!()}, invalid_entity); - /// assert_eq!(query_state.get_many_mut(&mut world, [entities[0], entities[0]]).unwrap_err(), QueryEntityError::AliasedMutability(entities[0])); + /// assert_eq!(match query_state.many(&mut world, [wrong_entity]).unwrap_err() {QueryEntityError::EntityDoesNotExist(error) => error.entity, _ => panic!()}, wrong_entity); + /// assert_eq!(match query_state.many_mut(&mut world, [invalid_entity]).unwrap_err() {QueryEntityError::QueryDoesNotMatch(entity, _) => entity, _ => panic!()}, invalid_entity); + /// assert_eq!(query_state.many_mut(&mut world, [entities[0], entities[0]]).unwrap_err(), QueryEntityError::AliasedMutability(entities[0])); /// ``` #[inline] + pub fn many_mut<'w, const N: usize>( + &mut self, + world: &'w mut World, + entities: [Entity; N], + ) -> Result<[D::Item<'w>; N], QueryEntityError> { + self.query_mut(world).many_mut_inner(entities) + } + + /// A deprecated alias for [`many_mut`](Self::many_mut). + #[inline] + #[deprecated(since = "0.16.0", note = "Please use `many_mut` instead")] pub fn get_many_mut<'w, const N: usize>( &mut self, world: &'w mut World, entities: [Entity; N], ) -> Result<[D::Item<'w>; N], QueryEntityError> { - self.query_mut(world).get_many_mut_inner(entities) + self.many_mut(world, entities) } /// Returns the query results for the given [`UniqueEntityArray`]. @@ -1100,8 +1131,8 @@ impl QueryState { /// returned instead. /// /// ``` - /// use bevy_ecs::{prelude::*, query::QueryEntityError, entity::{EntitySetIterator, unique_array::UniqueEntityArray, unique_vec::UniqueEntityVec}}; - /// + /// # use bevy_ecs::{prelude::*, query::QueryEntityError, entity::{EntitySetIterator, unique_array::UniqueEntityArray, unique_vec::UniqueEntityVec}}; + /// # /// #[derive(Component, PartialEq, Debug)] /// struct A(usize); /// @@ -1114,29 +1145,47 @@ impl QueryState { /// /// let mut query_state = world.query::<&mut A>(); /// - /// let mut mutable_component_values = query_state.get_many_unique_mut(&mut world, entity_set).unwrap(); + /// let mut mutable_component_values = query_state.many_unique_mut(&mut world, entity_set).unwrap(); /// /// for mut a in &mut mutable_component_values { /// a.0 += 5; /// } /// - /// let component_values = query_state.get_many_unique(&world, entity_set).unwrap(); + /// let component_values = query_state.many_unique(&world, entity_set).unwrap(); /// /// assert_eq!(component_values, [&A(5), &A(6), &A(7)]); /// /// let wrong_entity = Entity::from_raw(57); /// let invalid_entity = world.spawn_empty().id(); /// - /// assert_eq!(match query_state.get_many_unique(&mut world, UniqueEntityArray::from([wrong_entity])).unwrap_err() {QueryEntityError::EntityDoesNotExist(error) => error.entity, _ => panic!()}, wrong_entity); - /// assert_eq!(match query_state.get_many_unique_mut(&mut world, UniqueEntityArray::from([invalid_entity])).unwrap_err() {QueryEntityError::QueryDoesNotMatch(entity, _) => entity, _ => panic!()}, invalid_entity); + /// assert_eq!( + /// match query_state + /// .many_unique(&mut world, UniqueEntityArray::from([wrong_entity])) + /// .unwrap_err() + /// { + /// QueryEntityError::EntityDoesNotExist(error) => error.entity, + /// _ => panic!(), + /// }, + /// wrong_entity, + /// ); + /// assert_eq!( + /// match query_state + /// .many_unique_mut(&mut world, UniqueEntityArray::from([invalid_entity])) + /// .unwrap_err() + /// { + /// QueryEntityError::QueryDoesNotMatch(entity, _) => entity, + /// _ => panic!(), + /// }, + /// invalid_entity, + /// ); /// ``` #[inline] - pub fn get_many_unique_mut<'w, const N: usize>( + pub fn many_unique_mut<'w, const N: usize>( &mut self, world: &'w mut World, entities: UniqueEntityArray, ) -> Result<[D::Item<'w>; N], QueryEntityError> { - self.query_mut(world).get_many_unique_inner(entities) + self.query_mut(world).many_unique_inner(entities) } /// Gets the query result for the given [`World`] and [`Entity`]. @@ -1448,16 +1497,16 @@ impl QueryState { /// a.0 += 5; /// }); /// - /// # let component_values = query_state.get_many(&world, entities).unwrap(); + /// # let component_values = query_state.many(&world, entities).unwrap(); /// /// # assert_eq!(component_values, [&A(5), &A(6), &A(7)]); /// /// # let wrong_entity = Entity::from_raw(57); /// # let invalid_entity = world.spawn_empty().id(); /// - /// # assert_eq!(match query_state.get_many(&mut world, [wrong_entity]).unwrap_err() {QueryEntityError::EntityDoesNotExist(error) => error.entity, _ => panic!()}, wrong_entity); - /// assert_eq!(match query_state.get_many_mut(&mut world, [invalid_entity]).unwrap_err() {QueryEntityError::QueryDoesNotMatch(entity, _) => entity, _ => panic!()}, invalid_entity); - /// # assert_eq!(query_state.get_many_mut(&mut world, [entities[0], entities[0]]).unwrap_err(), QueryEntityError::AliasedMutability(entities[0])); + /// # assert_eq!(match query_state.many(&mut world, [wrong_entity]).unwrap_err() {QueryEntityError::EntityDoesNotExist(error) => error.entity, _ => panic!()}, wrong_entity); + /// assert_eq!(match query_state.many_mut(&mut world, [invalid_entity]).unwrap_err() {QueryEntityError::QueryDoesNotMatch(entity, _) => entity, _ => panic!()}, invalid_entity); + /// # assert_eq!(query_state.many_mut(&mut world, [entities[0], entities[0]]).unwrap_err(), QueryEntityError::AliasedMutability(entities[0])); /// ``` /// /// # Panics @@ -1899,22 +1948,22 @@ mod tests { #[test] #[should_panic] - fn right_world_get_many() { + fn right_world_many() { let mut world_1 = World::new(); let world_2 = World::new(); let mut query_state = world_1.query::(); - let _panics = query_state.get_many(&world_2, []); + let _panics = query_state.many(&world_2, []); } #[test] #[should_panic] - fn right_world_get_many_mut() { + fn right_world_many_mut() { let mut world_1 = World::new(); let mut world_2 = World::new(); let mut query_state = world_1.query::(); - let _panics = query_state.get_many_mut(&mut world_2, []); + let _panics = query_state.many_mut(&mut world_2, []); } #[derive(Component, PartialEq, Debug)] diff --git a/crates/bevy_ecs/src/system/mod.rs b/crates/bevy_ecs/src/system/mod.rs index fbb4a458d58b9..f2df8a1ae1e81 100644 --- a/crates/bevy_ecs/src/system/mod.rs +++ b/crates/bevy_ecs/src/system/mod.rs @@ -402,7 +402,7 @@ mod tests { } #[test] - fn get_many_is_ordered() { + fn many_is_ordered() { use crate::resource::Resource; const ENTITIES_COUNT: usize = 1000; @@ -417,7 +417,7 @@ mod tests { let entities_array: [Entity; ENTITIES_COUNT] = entities_array.0.clone().try_into().unwrap(); - for (i, w) in (0..ENTITIES_COUNT).zip(q.get_many(entities_array).unwrap()) { + for (i, w) in (0..ENTITIES_COUNT).zip(q.many(entities_array).unwrap()) { assert_eq!(i, w.0); } @@ -432,7 +432,7 @@ mod tests { let entities_array: [Entity; ENTITIES_COUNT] = entities_array.0.clone().try_into().unwrap(); - for (i, w) in (0..ENTITIES_COUNT).zip(q.get_many_mut(entities_array).unwrap()) { + for (i, w) in (0..ENTITIES_COUNT).zip(q.many_mut(entities_array).unwrap()) { assert_eq!(i, w.0); } diff --git a/crates/bevy_ecs/src/system/query.rs b/crates/bevy_ecs/src/system/query.rs index 16cc8546d0ef1..e6c37cb2fe62d 100644 --- a/crates/bevy_ecs/src/system/query.rs +++ b/crates/bevy_ecs/src/system/query.rs @@ -271,8 +271,8 @@ use core::{ /// |[`iter_many`]\[[`_mut`][`iter_many_mut`]]|Iterates or runs a specified function over query items generated by a list of entities.| /// |[`iter_combinations`]\[[`_mut`][`iter_combinations_mut`]]|Returns an iterator over all combinations of a specified number of query items.| /// |[`get`]\[[`_mut`][`get_mut`]]|Returns the query item for the specified entity.| -/// |[`many`]\[[`_mut`][`many_mut`]],
[`get_many`]\[[`_mut`][`get_many_mut`]]|Returns the query items for the specified entities.| -/// |[`single`]\[[`_mut`][`single_mut`]],
[`single`]\[[`_mut`][`single_mut`]]|Returns the query item while verifying that there aren't others.| +/// |[`many`]\[[`_mut`][`many_mut`]]|Returns the query items for the specified entities.| +/// |[`single`]\[[`_mut`][`single_mut`]]|Returns the query item while verifying that there aren't others.| /// /// There are two methods for each type of query operation: immutable and mutable (ending with `_mut`). /// When using immutable methods, the query items returned are of type [`ROQueryItem`], a read-only version of the query item. @@ -307,9 +307,9 @@ use core::{ /// |[`iter_many`]\[[`_mut`][`iter_many_mut`]]|O(k)| /// |[`iter_combinations`]\[[`_mut`][`iter_combinations_mut`]]|O(nCr)| /// |[`get`]\[[`_mut`][`get_mut`]]|O(1)| -/// |([`get_`][`get_many`])[`many`]|O(k)| -/// |([`get_`][`get_many_mut`])[`many_mut`]|O(k2)| -/// |[`single`]\[[`_mut`][`single_mut`]],
[`single`]\[[`_mut`][`single_mut`]]|O(a)| +/// |[`many`]|O(k)| +/// |[`many_mut`]|O(k2)| +/// |[`single`]\[[`_mut`][`single_mut`]]|O(a)| /// |Archetype based filtering ([`With`], [`Without`], [`Or`])|O(a)| /// |Change detection filtering ([`Added`], [`Changed`])|O(a + n)| /// @@ -350,8 +350,6 @@ use core::{ /// [`EntityRef`]: crate::world::EntityRef /// [`for_each`]: #iterator-for-each /// [`get`]: Self::get -/// [`get_many`]: Self::get_many -/// [`get_many_mut`]: Self::get_many_mut /// [`get_mut`]: Self::get_mut /// [`single`]: Self::single /// [`single_mut`]: Self::single_mut @@ -1287,7 +1285,7 @@ impl<'w, 's, D: QueryData, F: QueryFilter> Query<'w, 's, D, F> { /// /// The returned query items are in the same order as the input. /// In case of a nonexisting entity or mismatched component, a [`QueryEntityError`] is returned instead. - /// The elements of the array do not need to be unique, unlike `get_many_mut`. + /// The elements of the array do not need to be unique, unlike `many_mut`. /// /// # Examples /// @@ -1307,14 +1305,14 @@ impl<'w, 's, D: QueryData, F: QueryFilter> Query<'w, 's, D, F> { /// let mut query_state = world.query::<&A>(); /// let query = query_state.query(&world); /// - /// let component_values = query.get_many(entities).unwrap(); + /// let component_values = query.many(entities).unwrap(); /// /// assert_eq!(component_values, [&A(0), &A(1), &A(2)]); /// /// let wrong_entity = Entity::from_raw(365); /// /// assert_eq!( - /// match query.get_many([wrong_entity]).unwrap_err() { + /// match query.many([wrong_entity]).unwrap_err() { /// QueryEntityError::EntityDoesNotExist(error) => error.entity, /// _ => panic!(), /// }, @@ -1324,17 +1322,26 @@ impl<'w, 's, D: QueryData, F: QueryFilter> Query<'w, 's, D, F> { /// /// # See also /// - /// - [`get_many_mut`](Self::get_many_mut) to get mutable query items. - /// - [`get_many_unique`](Self::get_many_unique) to only handle unique inputs. - /// - [`many`](Self::many) for the panicking version. + /// - [`many_mut`](Self::many_mut) to get mutable query items. + /// - [`many_unique`](Self::many_unique) to only handle unique inputs. #[inline] - pub fn get_many( + pub fn many( &self, entities: [Entity; N], ) -> Result<[ROQueryItem<'_, D>; N], QueryEntityError> { - // Note that we call a separate `*_inner` method from `get_many_mut` + // Note that we call a separate `*_inner` method from `many_mut` // because we don't need to check for duplicates. - self.as_readonly().get_many_inner(entities) + self.as_readonly().many_inner(entities) + } + + /// A deprecated alias for [`many`](Self::many). + #[inline] + #[deprecated(since = "0.16.0", note = "Please use `many` instead")] + pub fn get_many( + &self, + entities: [Entity; N], + ) -> Result<[ROQueryItem<'_, D>; N], QueryEntityError> { + self.many(entities) } /// Returns the read-only query items for the given [`UniqueEntityArray`]. @@ -1345,8 +1352,8 @@ impl<'w, 's, D: QueryData, F: QueryFilter> Query<'w, 's, D, F> { /// # Examples /// /// ``` - /// use bevy_ecs::{prelude::*, query::QueryEntityError, entity::{EntitySetIterator, unique_array::UniqueEntityArray, unique_vec::UniqueEntityVec}}; - /// + /// # use bevy_ecs::{prelude::*, query::QueryEntityError, entity::{EntitySetIterator, unique_array::UniqueEntityArray, unique_vec::UniqueEntityVec}}; + /// # /// #[derive(Component, PartialEq, Debug)] /// struct A(usize); /// @@ -1359,14 +1366,14 @@ impl<'w, 's, D: QueryData, F: QueryFilter> Query<'w, 's, D, F> { /// let mut query_state = world.query::<&A>(); /// let query = query_state.query(&world); /// - /// let component_values = query.get_many_unique(entity_set).unwrap(); + /// let component_values = query.many_unique(entity_set).unwrap(); /// /// assert_eq!(component_values, [&A(0), &A(1), &A(2)]); /// /// let wrong_entity = Entity::from_raw(365); /// /// assert_eq!( - /// match query.get_many_unique(UniqueEntityArray::from([wrong_entity])).unwrap_err() { + /// match query.many_unique(UniqueEntityArray::from([wrong_entity])).unwrap_err() { /// QueryEntityError::EntityDoesNotExist(error) => error.entity, /// _ => panic!(), /// }, @@ -1376,65 +1383,14 @@ impl<'w, 's, D: QueryData, F: QueryFilter> Query<'w, 's, D, F> { /// /// # See also /// - /// - [`get_many_unique_mut`](Self::get_many_mut) to get mutable query items. - /// - [`get_many`](Self::get_many) to handle inputs with duplicates. + /// - [`many_unique_mut`](Self::many_mut) to get mutable query items. + /// - [`many`](Self::many) to handle inputs with duplicates. #[inline] - pub fn get_many_unique( + pub fn many_unique( &self, entities: UniqueEntityArray, ) -> Result<[ROQueryItem<'_, D>; N], QueryEntityError> { - self.as_readonly().get_many_unique_inner(entities) - } - - /// Returns the read-only query items for the given array of [`Entity`]. - /// - /// # Panics - /// - /// This method panics if there is a query mismatch or a non-existing entity. - /// - /// # Examples - /// ``` no_run - /// use bevy_ecs::prelude::*; - /// - /// #[derive(Component)] - /// struct Targets([Entity; 3]); - /// - /// #[derive(Component)] - /// struct Position{ - /// x: i8, - /// y: i8 - /// }; - /// - /// impl Position { - /// fn distance(&self, other: &Position) -> i8 { - /// // Manhattan distance is way easier to compute! - /// (self.x - other.x).abs() + (self.y - other.y).abs() - /// } - /// } - /// - /// fn check_all_targets_in_range(targeting_query: Query<(Entity, &Targets, &Position)>, targets_query: Query<&Position>){ - /// for (targeting_entity, targets, origin) in &targeting_query { - /// // We can use "destructuring" to unpack the results nicely - /// let [target_1, target_2, target_3] = targets_query.many(targets.0); - /// - /// assert!(target_1.distance(origin) <= 5); - /// assert!(target_2.distance(origin) <= 5); - /// assert!(target_3.distance(origin) <= 5); - /// } - /// } - /// ``` - /// - /// # See also - /// - /// - [`get_many`](Self::get_many) for the non-panicking version. - #[inline] - #[track_caller] - #[deprecated(note = "Use `get_many` instead and handle the Result.")] - pub fn many(&self, entities: [Entity; N]) -> [ROQueryItem<'_, D>; N] { - match self.get_many(entities) { - Ok(items) => items, - Err(error) => panic!("Cannot get query results: {error}"), - } + self.as_readonly().many_unique_inner(entities) } /// Returns the query item for the given [`Entity`]. @@ -1566,19 +1522,19 @@ impl<'w, 's, D: QueryData, F: QueryFilter> Query<'w, 's, D, F> { /// let mut query_state = world.query::<&mut A>(); /// let mut query = query_state.query_mut(&mut world); /// - /// let mut mutable_component_values = query.get_many_mut(entities).unwrap(); + /// let mut mutable_component_values = query.many_mut(entities).unwrap(); /// /// for mut a in &mut mutable_component_values { /// a.0 += 5; /// } /// - /// let component_values = query.get_many(entities).unwrap(); + /// let component_values = query.many(entities).unwrap(); /// /// assert_eq!(component_values, [&A(5), &A(6), &A(7)]); /// /// assert_eq!( /// match query - /// .get_many_mut([wrong_entity]) + /// .many_mut([wrong_entity]) /// .unwrap_err() /// { /// QueryEntityError::EntityDoesNotExist(error) => error.entity, @@ -1588,7 +1544,7 @@ impl<'w, 's, D: QueryData, F: QueryFilter> Query<'w, 's, D, F> { /// ); /// assert_eq!( /// match query - /// .get_many_mut([invalid_entity]) + /// .many_mut([invalid_entity]) /// .unwrap_err() /// { /// QueryEntityError::QueryDoesNotMatch(entity, _) => entity, @@ -1598,21 +1554,31 @@ impl<'w, 's, D: QueryData, F: QueryFilter> Query<'w, 's, D, F> { /// ); /// assert_eq!( /// query - /// .get_many_mut([entities[0], entities[0]]) + /// .many_mut([entities[0], entities[0]]) /// .unwrap_err(), /// QueryEntityError::AliasedMutability(entities[0]) /// ); /// ``` /// # See also /// - /// - [`get_many`](Self::get_many) to get read-only query items without checking for duplicate entities. + /// - [`many`](Self::many) to get read-only query items without checking for duplicate entities. /// - [`many_mut`](Self::many_mut) for the panicking version. #[inline] + pub fn many_mut( + &mut self, + entities: [Entity; N], + ) -> Result<[D::Item<'_>; N], QueryEntityError> { + self.reborrow().many_mut_inner(entities) + } + + /// A deprecated alias for [`many_mut`](Self::many_mut). + #[inline] + #[deprecated(since = "0.16.0", note = "Please use `many_mut` instead")] pub fn get_many_mut( &mut self, entities: [Entity; N], ) -> Result<[D::Item<'_>; N], QueryEntityError> { - self.reborrow().get_many_mut_inner(entities) + self.many_mut(entities) } /// Returns the query items for the given [`UniqueEntityArray`]. @@ -1623,8 +1589,8 @@ impl<'w, 's, D: QueryData, F: QueryFilter> Query<'w, 's, D, F> { /// # Examples /// /// ``` - /// use bevy_ecs::{prelude::*, query::QueryEntityError, entity::{EntitySetIterator, unique_array::UniqueEntityArray, unique_vec::UniqueEntityVec}}; - /// + /// # use bevy_ecs::{prelude::*, query::QueryEntityError, entity::{EntitySetIterator, unique_array::UniqueEntityArray, unique_vec::UniqueEntityVec}}; + /// # /// #[derive(Component, PartialEq, Debug)] /// struct A(usize); /// @@ -1641,19 +1607,19 @@ impl<'w, 's, D: QueryData, F: QueryFilter> Query<'w, 's, D, F> { /// let mut query_state = world.query::<&mut A>(); /// let mut query = query_state.query_mut(&mut world); /// - /// let mut mutable_component_values = query.get_many_unique_mut(entity_set).unwrap(); + /// let mut mutable_component_values = query.many_unique_mut(entity_set).unwrap(); /// /// for mut a in &mut mutable_component_values { /// a.0 += 5; /// } /// - /// let component_values = query.get_many_unique(entity_set).unwrap(); + /// let component_values = query.many_unique(entity_set).unwrap(); /// /// assert_eq!(component_values, [&A(5), &A(6), &A(7)]); /// /// assert_eq!( /// match query - /// .get_many_unique_mut(UniqueEntityArray::from([wrong_entity])) + /// .many_unique_mut(UniqueEntityArray::from([wrong_entity])) /// .unwrap_err() /// { /// QueryEntityError::EntityDoesNotExist(error) => error.entity, @@ -1663,7 +1629,7 @@ impl<'w, 's, D: QueryData, F: QueryFilter> Query<'w, 's, D, F> { /// ); /// assert_eq!( /// match query - /// .get_many_unique_mut(UniqueEntityArray::from([invalid_entity])) + /// .many_unique_mut(UniqueEntityArray::from([invalid_entity])) /// .unwrap_err() /// { /// QueryEntityError::QueryDoesNotMatch(entity, _) => entity, @@ -1674,13 +1640,13 @@ impl<'w, 's, D: QueryData, F: QueryFilter> Query<'w, 's, D, F> { /// ``` /// # See also /// - /// - [`get_many_unique`](Self::get_many) to get read-only query items. + /// - [`many_unique`](Self::many_unique) to get read-only query items. #[inline] - pub fn get_many_unique_mut( + pub fn many_unique_mut( &mut self, entities: UniqueEntityArray, ) -> Result<[D::Item<'_>; N], QueryEntityError> { - self.reborrow().get_many_unique_inner(entities) + self.reborrow().many_unique_inner(entities) } /// Returns the query items for the given array of [`Entity`]. @@ -1691,11 +1657,11 @@ impl<'w, 's, D: QueryData, F: QueryFilter> Query<'w, 's, D, F> { /// /// # See also /// - /// - [`get_many`](Self::get_many) to get read-only query items without checking for duplicate entities. - /// - [`get_many_mut`](Self::get_many_mut) to get items using a mutable reference. - /// - [`get_many_inner`](Self::get_many_mut_inner) to get read-only query items with the actual "inner" world lifetime. + /// - [`many`](Self::many) to get read-only query items without checking for duplicate entities. + /// - [`many_mut`](Self::many_mut) to get items using a mutable reference. + /// - [`many_inner`](Self::many_mut_inner) to get read-only query items with the actual "inner" world lifetime. #[inline] - pub fn get_many_mut_inner( + pub fn many_mut_inner( self, entities: [Entity; N], ) -> Result<[D::Item<'w>; N], QueryEntityError> { @@ -1708,7 +1674,7 @@ impl<'w, 's, D: QueryData, F: QueryFilter> Query<'w, 's, D, F> { } } // SAFETY: All entities are unique, so the results don't alias. - unsafe { self.get_many_impl(entities) } + unsafe { self.many_impl(entities) } } /// Returns the query items for the given array of [`Entity`]. @@ -1719,11 +1685,11 @@ impl<'w, 's, D: QueryData, F: QueryFilter> Query<'w, 's, D, F> { /// /// # See also /// - /// - [`get_many`](Self::get_many) to get read-only query items without checking for duplicate entities. - /// - [`get_many_mut`](Self::get_many_mut) to get items using a mutable reference. - /// - [`get_many_mut_inner`](Self::get_many_mut_inner) to get mutable query items with the actual "inner" world lifetime. + /// - [`many`](Self::many) to get read-only query items without checking for duplicate entities. + /// - [`many_mut`](Self::many_mut) to get items using a mutable reference. + /// - [`many_mut_inner`](Self::many_mut_inner) to get mutable query items with the actual "inner" world lifetime. #[inline] - pub fn get_many_inner( + pub fn many_inner( self, entities: [Entity; N], ) -> Result<[D::Item<'w>; N], QueryEntityError> @@ -1731,7 +1697,7 @@ impl<'w, 's, D: QueryData, F: QueryFilter> Query<'w, 's, D, F> { D: ReadOnlyQueryData, { // SAFETY: The query results are read-only, so they don't conflict if there are duplicate entities. - unsafe { self.get_many_impl(entities) } + unsafe { self.many_impl(entities) } } /// Returns the query items for the given [`UniqueEntityArray`]. @@ -1742,15 +1708,15 @@ impl<'w, 's, D: QueryData, F: QueryFilter> Query<'w, 's, D, F> { /// /// # See also /// - /// - [`get_many_unique`](Self::get_many_unique) to get read-only query items without checking for duplicate entities. - /// - [`get_many_unique_mut`](Self::get_many_unique_mut) to get items using a mutable reference. + /// - [`many_unique`](Self::many_unique) to get read-only query items without checking for duplicate entities. + /// - [`many_unique_mut`](Self::many_unique_mut) to get items using a mutable reference. #[inline] - pub fn get_many_unique_inner( + pub fn many_unique_inner( self, entities: UniqueEntityArray, ) -> Result<[D::Item<'w>; N], QueryEntityError> { // SAFETY: All entities are unique, so the results don't alias. - unsafe { self.get_many_impl(entities.into_inner()) } + unsafe { self.many_impl(entities.into_inner()) } } /// Returns the query items for the given array of [`Entity`]. @@ -1760,7 +1726,7 @@ impl<'w, 's, D: QueryData, F: QueryFilter> Query<'w, 's, D, F> { /// /// The caller must ensure that the query data returned for the entities does not conflict, /// either because they are all unique or because the data is read-only. - unsafe fn get_many_impl( + unsafe fn many_impl( self, entities: [Entity; N], ) -> Result<[D::Item<'w>; N], QueryEntityError> { @@ -1776,64 +1742,6 @@ impl<'w, 's, D: QueryData, F: QueryFilter> Query<'w, 's, D, F> { Ok(values.map(|x| unsafe { x.assume_init() })) } - /// Returns the query items for the given array of [`Entity`]. - /// - /// # Panics - /// - /// This method panics if there is a query mismatch, a non-existing entity, or the same `Entity` is included more than once in the array. - /// - /// # Examples - /// - /// ``` no_run - /// use bevy_ecs::prelude::*; - /// - /// #[derive(Component)] - /// struct Spring{ - /// connected_entities: [Entity; 2], - /// strength: f32, - /// } - /// - /// #[derive(Component)] - /// struct Position { - /// x: f32, - /// y: f32, - /// } - /// - /// #[derive(Component)] - /// struct Force { - /// x: f32, - /// y: f32, - /// } - /// - /// fn spring_forces(spring_query: Query<&Spring>, mut mass_query: Query<(&Position, &mut Force)>){ - /// for spring in &spring_query { - /// // We can use "destructuring" to unpack our query items nicely - /// let [(position_1, mut force_1), (position_2, mut force_2)] = mass_query.many_mut(spring.connected_entities); - /// - /// force_1.x += spring.strength * (position_1.x - position_2.x); - /// force_1.y += spring.strength * (position_1.y - position_2.y); - /// - /// // Silence borrow-checker: I have split your mutable borrow! - /// force_2.x += spring.strength * (position_2.x - position_1.x); - /// force_2.y += spring.strength * (position_2.y - position_1.y); - /// } - /// } - /// ``` - /// - /// # See also - /// - /// - [`get_many_mut`](Self::get_many_mut) for the non panicking version. - /// - [`many`](Self::many) to get read-only query items. - #[inline] - #[track_caller] - #[deprecated(note = "Use `get_many_mut` instead and handle the Result.")] - pub fn many_mut(&mut self, entities: [Entity; N]) -> [D::Item<'_>; N] { - match self.get_many_mut(entities) { - Ok(items) => items, - Err(error) => panic!("Cannot get query result: {error}"), - } - } - /// Returns the query item for the given [`Entity`]. /// /// In case of a nonexisting entity or mismatched component, a [`QueryEntityError`] is returned instead. @@ -2648,26 +2556,26 @@ mod tests { use alloc::vec::Vec; #[test] - fn get_many_uniqueness() { + fn many_uniqueness() { let mut world = World::new(); let entities: Vec = (0..10).map(|_| world.spawn_empty().id()).collect(); let mut query_state = world.query::(); - // It's best to test get_many_mut_inner directly, as it is shared + // It's best to test many_mut_inner directly, as it is shared // We don't care about aliased mutability for the read-only equivalent // SAFETY: Query does not access world data. assert!(query_state .query_mut(&mut world) - .get_many_mut_inner::<10>(entities.clone().try_into().unwrap()) + .many_mut_inner::<10>(entities.clone().try_into().unwrap()) .is_ok()); assert_eq!( query_state .query_mut(&mut world) - .get_many_mut_inner([entities[0], entities[0]]) + .many_mut_inner([entities[0], entities[0]]) .unwrap_err(), QueryEntityError::AliasedMutability(entities[0]) ); @@ -2675,7 +2583,7 @@ mod tests { assert_eq!( query_state .query_mut(&mut world) - .get_many_mut_inner([entities[0], entities[1], entities[0]]) + .many_mut_inner([entities[0], entities[1], entities[0]]) .unwrap_err(), QueryEntityError::AliasedMutability(entities[0]) ); @@ -2683,7 +2591,7 @@ mod tests { assert_eq!( query_state .query_mut(&mut world) - .get_many_mut_inner([entities[9], entities[9]]) + .many_mut_inner([entities[9], entities[9]]) .unwrap_err(), QueryEntityError::AliasedMutability(entities[9]) ); diff --git a/crates/bevy_ecs/src/world/entity_ref.rs b/crates/bevy_ecs/src/world/entity_ref.rs index ab2788898fd69..15dd26a988f78 100644 --- a/crates/bevy_ecs/src/world/entity_ref.rs +++ b/crates/bevy_ecs/src/world/entity_ref.rs @@ -810,7 +810,7 @@ impl<'w> EntityMut<'w> { /// let mut entity_mut = world.entity_mut(entity); /// let mut ptrs = entity_mut.get_mut_by_id(&HashSet::from_iter([x_id, y_id])) /// # .unwrap(); - /// # let [Some(mut x_ptr), Some(mut y_ptr)] = ptrs.get_many_mut([&x_id, &y_id]) else { unreachable!() }; + /// # let [Some(mut x_ptr), Some(mut y_ptr)] = ptrs.many_mut([&x_id, &y_id]) else { unreachable!() }; /// # assert_eq!((unsafe { x_ptr.as_mut().deref_mut::() }, unsafe { y_ptr.as_mut().deref_mut::() }), (&mut X(42), &mut Y(10))); /// ``` #[inline] diff --git a/crates/bevy_scene/src/scene_spawner.rs b/crates/bevy_scene/src/scene_spawner.rs index 4acfac93a9dd3..afa988d86cf95 100644 --- a/crates/bevy_scene/src/scene_spawner.rs +++ b/crates/bevy_scene/src/scene_spawner.rs @@ -660,7 +660,7 @@ mod tests { // verify this new entity contains the same data as the original entity let [old_a, new_a] = world .query::<&A>() - .get_many(&world, [entity, new_entity]) + .many(&world, [entity, new_entity]) .unwrap(); assert_eq!(old_a, new_a); }