bevy_ecs/query/iter.rs
1use super::{QueryData, QueryFilter, ReadOnlyQueryData};
2use crate::{
3 archetype::{Archetype, ArchetypeEntity, Archetypes},
4 bundle::Bundle,
5 component::Tick,
6 entity::{ContainsEntity, Entities, Entity, EntityEquivalent, EntitySet, EntitySetIterator},
7 query::{ArchetypeFilter, DebugCheckedUnwrap, QueryState, StorageId},
8 storage::{Table, TableRow, Tables},
9 world::{
10 unsafe_world_cell::UnsafeWorldCell, EntityMut, EntityMutExcept, EntityRef, EntityRefExcept,
11 FilteredEntityMut, FilteredEntityRef,
12 },
13};
14use alloc::vec::Vec;
15use core::{
16 cmp::Ordering,
17 fmt::{self, Debug, Formatter},
18 iter::FusedIterator,
19 mem::MaybeUninit,
20 ops::Range,
21};
22use nonmax::NonMaxU32;
23
24/// An [`Iterator`] over query results of a [`Query`](crate::system::Query).
25///
26/// This struct is created by the [`Query::iter`](crate::system::Query::iter) and
27/// [`Query::iter_mut`](crate::system::Query::iter_mut) methods.
28pub struct QueryIter<'w, 's, D: QueryData, F: QueryFilter> {
29 world: UnsafeWorldCell<'w>,
30 tables: &'w Tables,
31 archetypes: &'w Archetypes,
32 query_state: &'s QueryState<D, F>,
33 cursor: QueryIterationCursor<'w, 's, D, F>,
34}
35
36impl<'w, 's, D: QueryData, F: QueryFilter> QueryIter<'w, 's, D, F> {
37 /// # Safety
38 /// - `world` must have permission to access any of the components registered in `query_state`.
39 /// - `world` must be the same one used to initialize `query_state`.
40 pub(crate) unsafe fn new(
41 world: UnsafeWorldCell<'w>,
42 query_state: &'s QueryState<D, F>,
43 last_run: Tick,
44 this_run: Tick,
45 ) -> Self {
46 QueryIter {
47 world,
48 query_state,
49 // SAFETY: We only access table data that has been registered in `query_state`.
50 tables: unsafe { &world.storages().tables },
51 archetypes: world.archetypes(),
52 // SAFETY: The invariants are upheld by the caller.
53 cursor: unsafe { QueryIterationCursor::init(world, query_state, last_run, this_run) },
54 }
55 }
56
57 /// Creates a new separate iterator yielding the same remaining items of the current one.
58 /// Advancing the new iterator will not advance the original one, which will resume at the
59 /// point it was left at.
60 ///
61 /// Differently from [`remaining_mut`](QueryIter::remaining_mut) the new iterator does not
62 /// borrow from the original one. However it can only be called from an iterator over read only
63 /// items.
64 ///
65 /// # Example
66 ///
67 /// ```
68 /// # use bevy_ecs::prelude::*;
69 /// #
70 /// # #[derive(Component)]
71 /// # struct ComponentA;
72 ///
73 /// fn combinations(query: Query<&ComponentA>) {
74 /// let mut iter = query.iter();
75 /// while let Some(a) = iter.next() {
76 /// for b in iter.remaining() {
77 /// // Check every combination (a, b)
78 /// }
79 /// }
80 /// }
81 /// ```
82 pub fn remaining(&self) -> QueryIter<'w, 's, D, F>
83 where
84 D: ReadOnlyQueryData,
85 {
86 QueryIter {
87 world: self.world,
88 tables: self.tables,
89 archetypes: self.archetypes,
90 query_state: self.query_state,
91 cursor: self.cursor.clone(),
92 }
93 }
94
95 /// Creates a new separate iterator yielding the same remaining items of the current one.
96 /// Advancing the new iterator will not advance the original one, which will resume at the
97 /// point it was left at.
98 ///
99 /// This method can be called on iterators over mutable items. However the original iterator
100 /// will be borrowed while the new iterator exists and will thus not be usable in that timespan.
101 ///
102 /// # Example
103 ///
104 /// ```
105 /// # use bevy_ecs::prelude::*;
106 /// #
107 /// # #[derive(Component)]
108 /// # struct ComponentA;
109 ///
110 /// fn combinations(mut query: Query<&mut ComponentA>) {
111 /// let mut iter = query.iter_mut();
112 /// while let Some(a) = iter.next() {
113 /// for b in iter.remaining_mut() {
114 /// // Check every combination (a, b)
115 /// }
116 /// }
117 /// }
118 /// ```
119 pub fn remaining_mut(&mut self) -> QueryIter<'_, 's, D, F> {
120 QueryIter {
121 world: self.world,
122 tables: self.tables,
123 archetypes: self.archetypes,
124 query_state: self.query_state,
125 cursor: self.cursor.reborrow(),
126 }
127 }
128
129 /// Executes the equivalent of [`Iterator::fold`] over a contiguous segment
130 /// from a storage.
131 ///
132 /// # Safety
133 /// - `range` must be in `[0, storage::entity_count)` or None.
134 #[inline]
135 pub(super) unsafe fn fold_over_storage_range<B, Func>(
136 &mut self,
137 mut accum: B,
138 func: &mut Func,
139 storage: StorageId,
140 range: Option<Range<u32>>,
141 ) -> B
142 where
143 Func: FnMut(B, D::Item<'w, 's>) -> B,
144 {
145 if self.cursor.is_dense {
146 // SAFETY: `self.cursor.is_dense` is true, so storage ids are guaranteed to be table ids.
147 let table_id = unsafe { storage.table_id };
148 // SAFETY: Matched table IDs are guaranteed to still exist.
149 let table = unsafe { self.tables.get(table_id).debug_checked_unwrap() };
150
151 let range = range.unwrap_or(0..table.entity_count());
152 accum =
153 // SAFETY:
154 // - The fetched table matches both D and F
155 // - caller ensures `range` is within `[0, table.entity_count)`
156 // - The if block ensures that the query iteration is dense
157 unsafe { self.fold_over_table_range(accum, func, table, range) };
158 } else {
159 // SAFETY: `self.cursor.is_dense` is false, so storage ids are guaranteed to be archetype ids.
160 let archetype_id = unsafe { storage.archetype_id };
161 // SAFETY: Matched archetype IDs are guaranteed to still exist.
162 let archetype = unsafe { self.archetypes.get(archetype_id).debug_checked_unwrap() };
163 // SAFETY: Matched table IDs are guaranteed to still exist.
164 let table = unsafe { self.tables.get(archetype.table_id()).debug_checked_unwrap() };
165
166 let range = range.unwrap_or(0..archetype.len());
167
168 // When an archetype and its table have equal entity counts, dense iteration can be safely used.
169 // this leverages cache locality to optimize performance.
170 if table.entity_count() == archetype.len() {
171 accum =
172 // SAFETY:
173 // - The fetched archetype matches both D and F
174 // - The provided archetype and its' table have the same length.
175 // - caller ensures `range` is within `[0, archetype.len)`
176 // - The if block ensures that the query iteration is not dense.
177 unsafe { self.fold_over_dense_archetype_range(accum, func, archetype,range) };
178 } else {
179 accum =
180 // SAFETY:
181 // - The fetched archetype matches both D and F
182 // - caller ensures `range` is within `[0, archetype.len)`
183 // - The if block ensures that the query iteration is not dense.
184 unsafe { self.fold_over_archetype_range(accum, func, archetype,range) };
185 }
186 }
187 accum
188 }
189
190 /// Executes the equivalent of [`Iterator::fold`] over a contiguous segment
191 /// from a table.
192 ///
193 /// # Safety
194 /// - all `rows` must be in `[0, table.entity_count)`.
195 /// - `table` must match D and F
196 /// - The query iteration must be dense (i.e. `self.query_state.is_dense` must be true).
197 #[inline]
198 pub(super) unsafe fn fold_over_table_range<B, Func>(
199 &mut self,
200 mut accum: B,
201 func: &mut Func,
202 table: &'w Table,
203 rows: Range<u32>,
204 ) -> B
205 where
206 Func: FnMut(B, D::Item<'w, 's>) -> B,
207 {
208 if table.is_empty() {
209 return accum;
210 }
211
212 D::set_table(&mut self.cursor.fetch, &self.query_state.fetch_state, table);
213 F::set_table(
214 &mut self.cursor.filter,
215 &self.query_state.filter_state,
216 table,
217 );
218
219 let entities = table.entities();
220 for row in rows {
221 // SAFETY: Caller assures `row` in range of the current archetype.
222 let entity = unsafe { entities.get_unchecked(row as usize) };
223 // SAFETY: This is from an exclusive range, so it can't be max.
224 let row = unsafe { TableRow::new(NonMaxU32::new_unchecked(row)) };
225
226 // SAFETY: set_table was called prior.
227 // Caller assures `row` in range of the current archetype.
228 let fetched = unsafe {
229 !F::filter_fetch(
230 &self.query_state.filter_state,
231 &mut self.cursor.filter,
232 *entity,
233 row,
234 )
235 };
236 if fetched {
237 continue;
238 }
239
240 // SAFETY: set_table was called prior.
241 // Caller assures `row` in range of the current archetype.
242 let item = D::fetch(
243 &self.query_state.fetch_state,
244 &mut self.cursor.fetch,
245 *entity,
246 row,
247 );
248
249 accum = func(accum, item);
250 }
251 accum
252 }
253
254 /// Executes the equivalent of [`Iterator::fold`] over a contiguous segment
255 /// from an archetype.
256 ///
257 /// # Safety
258 /// - all `indices` must be in `[0, archetype.len())`.
259 /// - `archetype` must match D and F
260 /// - The query iteration must not be dense (i.e. `self.query_state.is_dense` must be false).
261 #[inline]
262 pub(super) unsafe fn fold_over_archetype_range<B, Func>(
263 &mut self,
264 mut accum: B,
265 func: &mut Func,
266 archetype: &'w Archetype,
267 indices: Range<u32>,
268 ) -> B
269 where
270 Func: FnMut(B, D::Item<'w, 's>) -> B,
271 {
272 if archetype.is_empty() {
273 return accum;
274 }
275 let table = self.tables.get(archetype.table_id()).debug_checked_unwrap();
276 D::set_archetype(
277 &mut self.cursor.fetch,
278 &self.query_state.fetch_state,
279 archetype,
280 table,
281 );
282 F::set_archetype(
283 &mut self.cursor.filter,
284 &self.query_state.filter_state,
285 archetype,
286 table,
287 );
288
289 let entities = archetype.entities();
290 for index in indices {
291 // SAFETY: Caller assures `index` in range of the current archetype.
292 let archetype_entity = unsafe { entities.get_unchecked(index as usize) };
293
294 // SAFETY: set_archetype was called prior.
295 // Caller assures `index` in range of the current archetype.
296 let fetched = unsafe {
297 !F::filter_fetch(
298 &self.query_state.filter_state,
299 &mut self.cursor.filter,
300 archetype_entity.id(),
301 archetype_entity.table_row(),
302 )
303 };
304 if fetched {
305 continue;
306 }
307
308 // SAFETY: set_archetype was called prior, `index` is an archetype index in range of the current archetype
309 // Caller assures `index` in range of the current archetype.
310 let item = unsafe {
311 D::fetch(
312 &self.query_state.fetch_state,
313 &mut self.cursor.fetch,
314 archetype_entity.id(),
315 archetype_entity.table_row(),
316 )
317 };
318
319 accum = func(accum, item);
320 }
321 accum
322 }
323
324 /// Executes the equivalent of [`Iterator::fold`] over a contiguous segment
325 /// from an archetype which has the same entity count as its table.
326 ///
327 /// # Safety
328 /// - all `indices` must be in `[0, archetype.len())`.
329 /// - `archetype` must match D and F
330 /// - `archetype` must have the same length as its table.
331 /// - The query iteration must not be dense (i.e. `self.query_state.is_dense` must be false).
332 #[inline]
333 pub(super) unsafe fn fold_over_dense_archetype_range<B, Func>(
334 &mut self,
335 mut accum: B,
336 func: &mut Func,
337 archetype: &'w Archetype,
338 rows: Range<u32>,
339 ) -> B
340 where
341 Func: FnMut(B, D::Item<'w, 's>) -> B,
342 {
343 if archetype.is_empty() {
344 return accum;
345 }
346 let table = self.tables.get(archetype.table_id()).debug_checked_unwrap();
347 debug_assert!(
348 archetype.len() == table.entity_count(),
349 "archetype and its table must have the same length. "
350 );
351
352 D::set_archetype(
353 &mut self.cursor.fetch,
354 &self.query_state.fetch_state,
355 archetype,
356 table,
357 );
358 F::set_archetype(
359 &mut self.cursor.filter,
360 &self.query_state.filter_state,
361 archetype,
362 table,
363 );
364 let entities = table.entities();
365 for row in rows {
366 // SAFETY: Caller assures `row` in range of the current archetype.
367 let entity = unsafe { *entities.get_unchecked(row as usize) };
368 // SAFETY: This is from an exclusive range, so it can't be max.
369 let row = unsafe { TableRow::new(NonMaxU32::new_unchecked(row)) };
370
371 // SAFETY: set_table was called prior.
372 // Caller assures `row` in range of the current archetype.
373 let filter_matched = unsafe {
374 F::filter_fetch(
375 &self.query_state.filter_state,
376 &mut self.cursor.filter,
377 entity,
378 row,
379 )
380 };
381 if !filter_matched {
382 continue;
383 }
384
385 // SAFETY: set_table was called prior.
386 // Caller assures `row` in range of the current archetype.
387 let item = D::fetch(
388 &self.query_state.fetch_state,
389 &mut self.cursor.fetch,
390 entity,
391 row,
392 );
393
394 accum = func(accum, item);
395 }
396 accum
397 }
398
399 /// Sorts all query items into a new iterator, using the query lens as a key.
400 ///
401 /// This sort is stable (i.e., does not reorder equal elements).
402 ///
403 /// This uses [`slice::sort`] internally.
404 ///
405 /// Defining the lens works like [`transmute_lens`](crate::system::Query::transmute_lens).
406 /// This includes the allowed parameter type changes listed under [allowed transmutes].
407 /// However, the lens uses the filter of the original query when present.
408 ///
409 /// The sort is not cached across system runs.
410 ///
411 /// [allowed transmutes]: crate::system::Query#allowed-transmutes
412 ///
413 /// # Panics
414 ///
415 /// This will panic if `next` has been called on `QueryIter` before, unless the underlying `Query` is empty.
416 ///
417 /// # Examples
418 /// ```rust
419 /// # use bevy_ecs::prelude::*;
420 /// # use std::{ops::{Deref, DerefMut}, iter::Sum};
421 /// #
422 /// # #[derive(Component)]
423 /// # struct PartMarker;
424 /// #
425 /// # #[derive(Component, PartialEq, Eq, PartialOrd, Ord)]
426 /// # struct PartIndex(usize);
427 /// #
428 /// # #[derive(Component, Clone, Copy)]
429 /// # struct PartValue(f32);
430 /// #
431 /// # impl Deref for PartValue {
432 /// # type Target = f32;
433 /// #
434 /// # fn deref(&self) -> &Self::Target {
435 /// # &self.0
436 /// # }
437 /// # }
438 /// #
439 /// # #[derive(Component)]
440 /// # struct ParentValue(f32);
441 /// #
442 /// # impl Deref for ParentValue {
443 /// # type Target = f32;
444 /// #
445 /// # fn deref(&self) -> &Self::Target {
446 /// # &self.0
447 /// # }
448 /// # }
449 /// #
450 /// # impl DerefMut for ParentValue {
451 /// # fn deref_mut(&mut self) -> &mut Self::Target {
452 /// # &mut self.0
453 /// # }
454 /// # }
455 /// #
456 /// # #[derive(Component, Debug, PartialEq, Eq, PartialOrd, Ord)]
457 /// # struct Length(usize);
458 /// #
459 /// # #[derive(Component, Debug, PartialEq, Eq, PartialOrd, Ord)]
460 /// # struct Width(usize);
461 /// #
462 /// # #[derive(Component, Debug, PartialEq, Eq, PartialOrd, Ord)]
463 /// # struct Height(usize);
464 /// #
465 /// # #[derive(Component, PartialEq, Eq, PartialOrd, Ord)]
466 /// # struct ParentEntity(Entity);
467 /// #
468 /// # #[derive(Component, Clone, Copy)]
469 /// # struct ChildPartCount(usize);
470 /// #
471 /// # impl Deref for ChildPartCount {
472 /// # type Target = usize;
473 /// #
474 /// # fn deref(&self) -> &Self::Target {
475 /// # &self.0
476 /// # }
477 /// # }
478 /// # let mut world = World::new();
479 /// // We can ensure that a query always returns in the same order.
480 /// fn system_1(query: Query<(Entity, &PartIndex)>) {
481 /// let parts: Vec<(Entity, &PartIndex)> = query.iter().sort::<&PartIndex>().collect();
482 /// }
483 ///
484 /// // We can freely rearrange query components in the key.
485 /// fn system_2(query: Query<(&Length, &Width, &Height), With<PartMarker>>) {
486 /// for (length, width, height) in query.iter().sort::<(&Height, &Length, &Width)>() {
487 /// println!("height: {height:?}, width: {width:?}, length: {length:?}")
488 /// }
489 /// }
490 ///
491 /// // We can sort by Entity without including it in the original Query.
492 /// // Here, we match iteration orders between query iterators.
493 /// fn system_3(
494 /// part_query: Query<(&PartValue, &ParentEntity)>,
495 /// mut parent_query: Query<(&ChildPartCount, &mut ParentValue)>,
496 /// ) {
497 /// let part_values = &mut part_query
498 /// .into_iter()
499 /// .sort::<&ParentEntity>()
500 /// .map(|(&value, parent_entity)| *value);
501 ///
502 /// for (&child_count, mut parent_value) in parent_query.iter_mut().sort::<Entity>() {
503 /// **parent_value = part_values.take(*child_count).sum();
504 /// }
505 /// }
506 /// #
507 /// # let mut schedule = Schedule::default();
508 /// # schedule.add_systems((system_1, system_2, system_3));
509 /// # schedule.run(&mut world);
510 /// ```
511 pub fn sort<L: ReadOnlyQueryData + 'w>(
512 self,
513 ) -> QuerySortedIter<
514 'w,
515 's,
516 D,
517 F,
518 impl ExactSizeIterator<Item = Entity> + DoubleEndedIterator + FusedIterator + 'w,
519 >
520 where
521 for<'lw, 'ls> L::Item<'lw, 'ls>: Ord,
522 {
523 self.sort_impl::<L>(|keyed_query| keyed_query.sort())
524 }
525
526 /// Sorts all query items into a new iterator, using the query lens as a key.
527 ///
528 /// This sort is unstable (i.e., may reorder equal elements).
529 ///
530 /// This uses [`slice::sort_unstable`] internally.
531 ///
532 /// Defining the lens works like [`transmute_lens`](crate::system::Query::transmute_lens).
533 /// This includes the allowed parameter type changes listed under [allowed transmutes]..
534 /// However, the lens uses the filter of the original query when present.
535 ///
536 /// The sort is not cached across system runs.
537 ///
538 /// [allowed transmutes]: crate::system::Query#allowed-transmutes
539 ///
540 /// # Panics
541 ///
542 /// This will panic if `next` has been called on `QueryIter` before, unless the underlying `Query` is empty.
543 ///
544 /// # Example
545 /// ```
546 /// # use bevy_ecs::prelude::*;
547 /// #
548 /// # let mut world = World::new();
549 /// #
550 /// # #[derive(Component)]
551 /// # struct PartMarker;
552 /// #
553 /// #[derive(Component, PartialEq, Eq, PartialOrd, Ord)]
554 /// enum Flying {
555 /// Enabled,
556 /// Disabled
557 /// };
558 ///
559 /// // We perform an unstable sort by a Component with few values.
560 /// fn system_1(query: Query<&Flying, With<PartMarker>>) {
561 /// let part_values: Vec<&Flying> = query.iter().sort_unstable::<&Flying>().collect();
562 /// }
563 /// #
564 /// # let mut schedule = Schedule::default();
565 /// # schedule.add_systems((system_1));
566 /// # schedule.run(&mut world);
567 /// ```
568 pub fn sort_unstable<L: ReadOnlyQueryData + 'w>(
569 self,
570 ) -> QuerySortedIter<
571 'w,
572 's,
573 D,
574 F,
575 impl ExactSizeIterator<Item = Entity> + DoubleEndedIterator + FusedIterator + 'w,
576 >
577 where
578 for<'lw, 'ls> L::Item<'lw, 'ls>: Ord,
579 {
580 self.sort_impl::<L>(|keyed_query| keyed_query.sort_unstable())
581 }
582
583 /// Sorts all query items into a new iterator with a comparator function over the query lens.
584 ///
585 /// This sort is stable (i.e., does not reorder equal elements).
586 ///
587 /// This uses [`slice::sort_by`] internally.
588 ///
589 /// Defining the lens works like [`transmute_lens`](crate::system::Query::transmute_lens).
590 /// This includes the allowed parameter type changes listed under [allowed transmutes].
591 /// However, the lens uses the filter of the original query when present.
592 ///
593 /// The sort is not cached across system runs.
594 ///
595 /// [allowed transmutes]: crate::system::Query#allowed-transmutes
596 ///
597 /// # Panics
598 ///
599 /// This will panic if `next` has been called on `QueryIter` before, unless the underlying `Query` is empty.
600 ///
601 /// # Example
602 /// ```
603 /// # use bevy_ecs::prelude::*;
604 /// # use std::ops::Deref;
605 /// #
606 /// # impl Deref for PartValue {
607 /// # type Target = f32;
608 /// #
609 /// # fn deref(&self) -> &Self::Target {
610 /// # &self.0
611 /// # }
612 /// # }
613 /// #
614 /// # let mut world = World::new();
615 /// #
616 /// #[derive(Component)]
617 /// struct PartValue(f32);
618 ///
619 /// // We can use a cmp function on components do not implement Ord.
620 /// fn system_1(query: Query<&PartValue>) {
621 /// // Sort part values according to `f32::total_comp`.
622 /// let part_values: Vec<&PartValue> = query
623 /// .iter()
624 /// .sort_by::<&PartValue>(|value_1, value_2| value_1.total_cmp(*value_2))
625 /// .collect();
626 /// }
627 /// #
628 /// # let mut schedule = Schedule::default();
629 /// # schedule.add_systems((system_1));
630 /// # schedule.run(&mut world);
631 /// ```
632 pub fn sort_by<L: ReadOnlyQueryData + 'w>(
633 self,
634 mut compare: impl FnMut(&L::Item<'_, '_>, &L::Item<'_, '_>) -> Ordering,
635 ) -> QuerySortedIter<
636 'w,
637 's,
638 D,
639 F,
640 impl ExactSizeIterator<Item = Entity> + DoubleEndedIterator + FusedIterator + 'w,
641 > {
642 self.sort_impl::<L>(move |keyed_query| {
643 keyed_query.sort_by(|(key_1, _), (key_2, _)| compare(key_1, key_2));
644 })
645 }
646
647 /// Sorts all query items into a new iterator with a comparator function over the query lens.
648 ///
649 /// This sort is unstable (i.e., may reorder equal elements).
650 ///
651 /// This uses [`slice::sort_unstable_by`] internally.
652 ///
653 /// Defining the lens works like [`transmute_lens`](crate::system::Query::transmute_lens).
654 /// This includes the allowed parameter type changes listed under [allowed transmutes].
655 /// However, the lens uses the filter of the original query when present.
656 ///
657 /// The sort is not cached across system runs.
658 ///
659 /// [allowed transmutes]: crate::system::Query#allowed-transmutes
660 ///
661 /// # Panics
662 ///
663 /// This will panic if `next` has been called on `QueryIter` before, unless the underlying `Query` is empty.
664 pub fn sort_unstable_by<L: ReadOnlyQueryData + 'w>(
665 self,
666 mut compare: impl FnMut(&L::Item<'_, '_>, &L::Item<'_, '_>) -> Ordering,
667 ) -> QuerySortedIter<
668 'w,
669 's,
670 D,
671 F,
672 impl ExactSizeIterator<Item = Entity> + DoubleEndedIterator + FusedIterator + 'w,
673 > {
674 self.sort_impl::<L>(move |keyed_query| {
675 keyed_query.sort_unstable_by(|(key_1, _), (key_2, _)| compare(key_1, key_2));
676 })
677 }
678
679 /// Sorts all query items into a new iterator with a key extraction function over the query lens.
680 ///
681 /// This sort is stable (i.e., does not reorder equal elements).
682 ///
683 /// This uses [`slice::sort_by_key`] internally.
684 ///
685 /// Defining the lens works like [`transmute_lens`](crate::system::Query::transmute_lens).
686 /// This includes the allowed parameter type changes listed under [allowed transmutes].
687 /// However, the lens uses the filter of the original query when present.
688 ///
689 /// The sort is not cached across system runs.
690 ///
691 /// [allowed transmutes]: crate::system::Query#allowed-transmutes
692 ///
693 /// # Panics
694 ///
695 /// This will panic if `next` has been called on `QueryIter` before, unless the underlying `Query` is empty.
696 ///
697 /// # Example
698 /// ```
699 /// # use bevy_ecs::prelude::*;
700 /// # use std::ops::Deref;
701 /// #
702 /// # #[derive(Component)]
703 /// # struct PartMarker;
704 /// #
705 /// # impl Deref for PartValue {
706 /// # type Target = f32;
707 /// #
708 /// # fn deref(&self) -> &Self::Target {
709 /// # &self.0
710 /// # }
711 /// # }
712 /// #
713 /// # let mut world = World::new();
714 /// #
715 /// #[derive(Component)]
716 /// struct AvailableMarker;
717 ///
718 /// #[derive(Component, PartialEq, Eq, PartialOrd, Ord, Copy, Clone)]
719 /// enum Rarity {
720 /// Common,
721 /// Rare,
722 /// Epic,
723 /// Legendary
724 /// };
725 ///
726 /// #[derive(Component)]
727 /// struct PartValue(f32);
728 ///
729 /// // We can sort with the internals of components that do not implement Ord.
730 /// fn system_1(query: Query<(Entity, &PartValue)>) {
731 /// // Sort by the sines of the part values.
732 /// let parts: Vec<(Entity, &PartValue)> = query
733 /// .iter()
734 /// .sort_by_key::<&PartValue, _>(|value| value.sin() as usize)
735 /// .collect();
736 /// }
737 ///
738 /// // We can define our own custom comparison functions over an EntityRef.
739 /// fn system_2(query: Query<EntityRef, With<PartMarker>>) {
740 /// // Sort by whether parts are available and their rarity.
741 /// // We want the available legendaries to come first, so we reverse the iterator.
742 /// let parts: Vec<EntityRef> = query.iter()
743 /// .sort_by_key::<EntityRef, _>(|entity_ref| {
744 /// (
745 /// entity_ref.contains::<AvailableMarker>(),
746 /// entity_ref.get::<Rarity>().copied()
747 /// )
748 /// })
749 /// .rev()
750 /// .collect();
751 /// }
752 /// # let mut schedule = Schedule::default();
753 /// # schedule.add_systems((system_1, system_2));
754 /// # schedule.run(&mut world);
755 /// ```
756 pub fn sort_by_key<L: ReadOnlyQueryData + 'w, K>(
757 self,
758 mut f: impl FnMut(&L::Item<'_, '_>) -> K,
759 ) -> QuerySortedIter<
760 'w,
761 's,
762 D,
763 F,
764 impl ExactSizeIterator<Item = Entity> + DoubleEndedIterator + FusedIterator + 'w,
765 >
766 where
767 K: Ord,
768 {
769 self.sort_impl::<L>(move |keyed_query| keyed_query.sort_by_key(|(lens, _)| f(lens)))
770 }
771
772 /// Sorts all query items into a new iterator with a key extraction function over the query lens.
773 ///
774 /// This sort is unstable (i.e., may reorder equal elements).
775 ///
776 /// This uses [`slice::sort_unstable_by_key`] internally.
777 ///
778 /// Defining the lens works like [`transmute_lens`](crate::system::Query::transmute_lens).
779 /// This includes the allowed parameter type changes listed under [allowed transmutes].
780 /// However, the lens uses the filter of the original query when present.
781 ///
782 /// The sort is not cached across system runs.
783 ///
784 /// [allowed transmutes]: crate::system::Query#allowed-transmutes
785 ///
786 /// # Panics
787 ///
788 /// This will panic if `next` has been called on `QueryIter` before, unless the underlying `Query` is empty.
789 pub fn sort_unstable_by_key<L: ReadOnlyQueryData + 'w, K>(
790 self,
791 mut f: impl FnMut(&L::Item<'_, '_>) -> K,
792 ) -> QuerySortedIter<
793 'w,
794 's,
795 D,
796 F,
797 impl ExactSizeIterator<Item = Entity> + DoubleEndedIterator + FusedIterator + 'w,
798 >
799 where
800 K: Ord,
801 {
802 self.sort_impl::<L>(move |keyed_query| {
803 keyed_query.sort_unstable_by_key(|(lens, _)| f(lens));
804 })
805 }
806
807 /// Sort all query items into a new iterator with a key extraction function over the query lens.
808 ///
809 /// This sort is stable (i.e., does not reorder equal elements).
810 ///
811 /// This uses [`slice::sort_by_cached_key`] internally.
812 ///
813 /// Defining the lens works like [`transmute_lens`](crate::system::Query::transmute_lens).
814 /// This includes the allowed parameter type changes listed under [allowed transmutes].
815 /// However, the lens uses the filter of the original query when present.
816 ///
817 /// The sort is not cached across system runs.
818 ///
819 /// [allowed transmutes]: crate::system::Query#allowed-transmutes
820 ///
821 /// # Panics
822 ///
823 /// This will panic if `next` has been called on `QueryIter` before, unless the underlying `Query` is empty.
824 pub fn sort_by_cached_key<L: ReadOnlyQueryData + 'w, K>(
825 self,
826 mut f: impl FnMut(&L::Item<'_, '_>) -> K,
827 ) -> QuerySortedIter<
828 'w,
829 's,
830 D,
831 F,
832 impl ExactSizeIterator<Item = Entity> + DoubleEndedIterator + FusedIterator + 'w,
833 >
834 where
835 K: Ord,
836 {
837 self.sort_impl::<L>(move |keyed_query| keyed_query.sort_by_cached_key(|(lens, _)| f(lens)))
838 }
839
840 /// Shared implementation for the various `sort` methods.
841 /// This uses the lens to collect the items for sorting, but delegates the actual sorting to the provided closure.
842 ///
843 /// Defining the lens works like [`transmute_lens`](crate::system::Query::transmute_lens).
844 /// This includes the allowed parameter type changes listed under [allowed transmutes].
845 /// However, the lens uses the filter of the original query when present.
846 ///
847 /// The sort is not cached across system runs.
848 ///
849 /// [allowed transmutes]: crate::system::Query#allowed-transmutes
850 ///
851 /// # Panics
852 ///
853 /// This will panic if `next` has been called on `QueryIter` before, unless the underlying `Query` is empty.
854 fn sort_impl<L: ReadOnlyQueryData + 'w>(
855 self,
856 f: impl FnOnce(&mut Vec<(L::Item<'_, '_>, NeutralOrd<Entity>)>),
857 ) -> QuerySortedIter<
858 'w,
859 's,
860 D,
861 F,
862 impl ExactSizeIterator<Item = Entity> + DoubleEndedIterator + FusedIterator + 'w,
863 > {
864 // On the first successful iteration of `QueryIterationCursor`, `archetype_entities` or `table_entities`
865 // will be set to a non-zero value. The correctness of this method relies on this.
866 // I.e. this sort method will execute if and only if `next` on `QueryIterationCursor` of a
867 // non-empty `QueryIter` has not yet been called. When empty, this sort method will not panic.
868 if !self.cursor.archetype_entities.is_empty() || !self.cursor.table_entities.is_empty() {
869 panic!("it is not valid to call sort() after next()")
870 }
871
872 let world = self.world;
873
874 let query_lens_state = self.query_state.transmute_filtered::<(L, Entity), F>(world);
875
876 // SAFETY:
877 // `self.world` has permission to access the required components.
878 // The original query iter has not been iterated on, so no items are aliased from it.
879 // `QueryIter::new` ensures `world` is the same one used to initialize `query_state`.
880 let query_lens = unsafe { query_lens_state.query_unchecked_manual(world) }.into_iter();
881 let mut keyed_query: Vec<_> = query_lens
882 .map(|(key, entity)| (key, NeutralOrd(entity)))
883 .collect();
884 f(&mut keyed_query);
885 let entity_iter = keyed_query
886 .into_iter()
887 .map(|(.., entity)| entity.0)
888 .collect::<Vec<_>>()
889 .into_iter();
890 // SAFETY:
891 // `self.world` has permission to access the required components.
892 // Each lens query item is dropped before the respective actual query item is accessed.
893 unsafe {
894 QuerySortedIter::new(
895 world,
896 self.query_state,
897 entity_iter,
898 world.last_change_tick(),
899 world.change_tick(),
900 )
901 }
902 }
903}
904
905impl<'w, 's, D: QueryData, F: QueryFilter> Iterator for QueryIter<'w, 's, D, F> {
906 type Item = D::Item<'w, 's>;
907
908 #[inline(always)]
909 fn next(&mut self) -> Option<Self::Item> {
910 // SAFETY:
911 // `tables` and `archetypes` belong to the same world that the cursor was initialized for.
912 // `query_state` is the state that was passed to `QueryIterationCursor::init`.
913 unsafe {
914 self.cursor
915 .next(self.tables, self.archetypes, self.query_state)
916 }
917 }
918
919 fn size_hint(&self) -> (usize, Option<usize>) {
920 let max_size = self.cursor.max_remaining(self.tables, self.archetypes);
921 let archetype_query = F::IS_ARCHETYPAL;
922 let min_size = if archetype_query { max_size } else { 0 };
923 (min_size as usize, Some(max_size as usize))
924 }
925
926 #[inline]
927 fn fold<B, Func>(mut self, init: B, mut func: Func) -> B
928 where
929 Func: FnMut(B, Self::Item) -> B,
930 {
931 let mut accum = init;
932 // Empty any remaining uniterated values from the current table/archetype
933 while self.cursor.current_row != self.cursor.current_len {
934 let Some(item) = self.next() else { break };
935 accum = func(accum, item);
936 }
937
938 for id in self.cursor.storage_id_iter.clone().copied() {
939 // SAFETY:
940 // - The range(None) is equivalent to [0, storage.entity_count)
941 accum = unsafe { self.fold_over_storage_range(accum, &mut func, id, None) };
942 }
943 accum
944 }
945}
946
947// This is correct as [`QueryIter`] always returns `None` once exhausted.
948impl<'w, 's, D: QueryData, F: QueryFilter> FusedIterator for QueryIter<'w, 's, D, F> {}
949
950// SAFETY: [`QueryIter`] is guaranteed to return every matching entity once and only once.
951unsafe impl<'w, 's, F: QueryFilter> EntitySetIterator for QueryIter<'w, 's, Entity, F> {}
952
953// SAFETY: [`QueryIter`] is guaranteed to return every matching entity once and only once.
954unsafe impl<'w, 's, F: QueryFilter> EntitySetIterator for QueryIter<'w, 's, EntityRef<'_>, F> {}
955
956// SAFETY: [`QueryIter`] is guaranteed to return every matching entity once and only once.
957unsafe impl<'w, 's, F: QueryFilter> EntitySetIterator for QueryIter<'w, 's, EntityMut<'_>, F> {}
958
959// SAFETY: [`QueryIter`] is guaranteed to return every matching entity once and only once.
960unsafe impl<'w, 's, F: QueryFilter> EntitySetIterator
961 for QueryIter<'w, 's, FilteredEntityRef<'_, '_>, F>
962{
963}
964
965// SAFETY: [`QueryIter`] is guaranteed to return every matching entity once and only once.
966unsafe impl<'w, 's, F: QueryFilter> EntitySetIterator
967 for QueryIter<'w, 's, FilteredEntityMut<'_, '_>, F>
968{
969}
970
971// SAFETY: [`QueryIter`] is guaranteed to return every matching entity once and only once.
972unsafe impl<'w, 's, F: QueryFilter, B: Bundle> EntitySetIterator
973 for QueryIter<'w, 's, EntityRefExcept<'_, '_, B>, F>
974{
975}
976
977// SAFETY: [`QueryIter`] is guaranteed to return every matching entity once and only once.
978unsafe impl<'w, 's, F: QueryFilter, B: Bundle> EntitySetIterator
979 for QueryIter<'w, 's, EntityMutExcept<'_, '_, B>, F>
980{
981}
982
983impl<'w, 's, D: QueryData, F: QueryFilter> Debug for QueryIter<'w, 's, D, F> {
984 fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
985 f.debug_struct("QueryIter").finish()
986 }
987}
988
989impl<'w, 's, D: ReadOnlyQueryData, F: QueryFilter> Clone for QueryIter<'w, 's, D, F> {
990 fn clone(&self) -> Self {
991 self.remaining()
992 }
993}
994
995/// An [`Iterator`] over sorted query results of a [`Query`](crate::system::Query).
996///
997/// This struct is created by the [`QueryIter::sort`], [`QueryIter::sort_unstable`],
998/// [`QueryIter::sort_by`], [`QueryIter::sort_unstable_by`], [`QueryIter::sort_by_key`],
999/// [`QueryIter::sort_unstable_by_key`], and [`QueryIter::sort_by_cached_key`] methods.
1000pub struct QuerySortedIter<'w, 's, D: QueryData, F: QueryFilter, I>
1001where
1002 I: Iterator<Item = Entity>,
1003{
1004 entity_iter: I,
1005 entities: &'w Entities,
1006 tables: &'w Tables,
1007 archetypes: &'w Archetypes,
1008 fetch: D::Fetch<'w>,
1009 query_state: &'s QueryState<D, F>,
1010}
1011
1012impl<'w, 's, D: QueryData, F: QueryFilter, I: Iterator> QuerySortedIter<'w, 's, D, F, I>
1013where
1014 I: Iterator<Item = Entity>,
1015{
1016 /// # Safety
1017 /// - `world` must have permission to access any of the components registered in `query_state`.
1018 /// - `world` must be the same one used to initialize `query_state`.
1019 /// - `entity_list` must only contain unique entities or be empty.
1020 pub(crate) unsafe fn new<EntityList: IntoIterator<IntoIter = I>>(
1021 world: UnsafeWorldCell<'w>,
1022 query_state: &'s QueryState<D, F>,
1023 entity_list: EntityList,
1024 last_run: Tick,
1025 this_run: Tick,
1026 ) -> QuerySortedIter<'w, 's, D, F, I> {
1027 let fetch = D::init_fetch(world, &query_state.fetch_state, last_run, this_run);
1028 QuerySortedIter {
1029 query_state,
1030 entities: world.entities(),
1031 archetypes: world.archetypes(),
1032 // SAFETY: We only access table data that has been registered in `query_state`.
1033 // This means `world` has permission to access the data we use.
1034 tables: &world.storages().tables,
1035 fetch,
1036 entity_iter: entity_list.into_iter(),
1037 }
1038 }
1039
1040 /// # Safety
1041 /// `entity` must stem from `self.entity_iter`, and not have been passed before.
1042 #[inline(always)]
1043 unsafe fn fetch_next(&mut self, entity: Entity) -> D::Item<'w, 's> {
1044 let (location, archetype, table);
1045 // SAFETY:
1046 // `tables` and `archetypes` belong to the same world that the [`QueryIter`]
1047 // was initialized for.
1048 unsafe {
1049 location = self.entities.get(entity).debug_checked_unwrap();
1050 archetype = self
1051 .archetypes
1052 .get(location.archetype_id)
1053 .debug_checked_unwrap();
1054 table = self.tables.get(location.table_id).debug_checked_unwrap();
1055 }
1056
1057 // SAFETY: `archetype` is from the world that `fetch` was created for,
1058 // `fetch_state` is the state that `fetch` was initialized with
1059 unsafe {
1060 D::set_archetype(
1061 &mut self.fetch,
1062 &self.query_state.fetch_state,
1063 archetype,
1064 table,
1065 );
1066 }
1067
1068 // The entity list has already been filtered by the query lens, so we forego filtering here.
1069 // SAFETY:
1070 // - set_archetype was called prior, `location.archetype_row` is an archetype index in range of the current archetype
1071 // - fetch is only called once for each entity.
1072 unsafe {
1073 D::fetch(
1074 &self.query_state.fetch_state,
1075 &mut self.fetch,
1076 entity,
1077 location.table_row,
1078 )
1079 }
1080 }
1081}
1082
1083impl<'w, 's, D: QueryData, F: QueryFilter, I: Iterator> Iterator
1084 for QuerySortedIter<'w, 's, D, F, I>
1085where
1086 I: Iterator<Item = Entity>,
1087{
1088 type Item = D::Item<'w, 's>;
1089
1090 #[inline(always)]
1091 fn next(&mut self) -> Option<Self::Item> {
1092 let entity = self.entity_iter.next()?;
1093 // SAFETY: `entity` is passed from `entity_iter` the first time.
1094 unsafe { self.fetch_next(entity).into() }
1095 }
1096
1097 fn size_hint(&self) -> (usize, Option<usize>) {
1098 self.entity_iter.size_hint()
1099 }
1100}
1101
1102impl<'w, 's, D: QueryData, F: QueryFilter, I: Iterator> DoubleEndedIterator
1103 for QuerySortedIter<'w, 's, D, F, I>
1104where
1105 I: DoubleEndedIterator<Item = Entity>,
1106{
1107 #[inline(always)]
1108 fn next_back(&mut self) -> Option<Self::Item> {
1109 let entity = self.entity_iter.next_back()?;
1110 // SAFETY: `entity` is passed from `entity_iter` the first time.
1111 unsafe { self.fetch_next(entity).into() }
1112 }
1113}
1114
1115impl<'w, 's, D: QueryData, F: QueryFilter, I: Iterator> ExactSizeIterator
1116 for QuerySortedIter<'w, 's, D, F, I>
1117where
1118 I: ExactSizeIterator<Item = Entity>,
1119{
1120}
1121
1122// This is correct as [`QuerySortedIter`] returns `None` once exhausted if `entity_iter` does.
1123impl<'w, 's, D: QueryData, F: QueryFilter, I: Iterator> FusedIterator
1124 for QuerySortedIter<'w, 's, D, F, I>
1125where
1126 I: FusedIterator<Item = Entity>,
1127{
1128}
1129
1130// SAFETY:
1131// `I` stems from a collected and sorted `EntitySetIterator` ([`QueryIter`]).
1132// Fetching unique entities maintains uniqueness.
1133unsafe impl<'w, 's, F: QueryFilter, I: Iterator<Item = Entity>> EntitySetIterator
1134 for QuerySortedIter<'w, 's, Entity, F, I>
1135{
1136}
1137
1138impl<'w, 's, D: QueryData, F: QueryFilter, I: Iterator<Item = Entity>> Debug
1139 for QuerySortedIter<'w, 's, D, F, I>
1140{
1141 fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
1142 f.debug_struct("QuerySortedIter").finish()
1143 }
1144}
1145
1146/// An [`Iterator`] over the query items generated from an iterator of [`Entity`]s.
1147///
1148/// Items are returned in the order of the provided iterator.
1149/// Entities that don't match the query are skipped.
1150///
1151/// 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.
1152pub struct QueryManyIter<'w, 's, D: QueryData, F: QueryFilter, I: Iterator<Item: EntityEquivalent>>
1153{
1154 world: UnsafeWorldCell<'w>,
1155 entity_iter: I,
1156 entities: &'w Entities,
1157 tables: &'w Tables,
1158 archetypes: &'w Archetypes,
1159 fetch: D::Fetch<'w>,
1160 filter: F::Fetch<'w>,
1161 query_state: &'s QueryState<D, F>,
1162}
1163
1164impl<'w, 's, D: QueryData, F: QueryFilter, I: Iterator<Item: EntityEquivalent>>
1165 QueryManyIter<'w, 's, D, F, I>
1166{
1167 /// # Safety
1168 /// - `world` must have permission to access any of the components registered in `query_state`.
1169 /// - `world` must be the same one used to initialize `query_state`.
1170 pub(crate) unsafe fn new<EntityList: IntoIterator<IntoIter = I>>(
1171 world: UnsafeWorldCell<'w>,
1172 query_state: &'s QueryState<D, F>,
1173 entity_list: EntityList,
1174 last_run: Tick,
1175 this_run: Tick,
1176 ) -> QueryManyIter<'w, 's, D, F, I> {
1177 let fetch = D::init_fetch(world, &query_state.fetch_state, last_run, this_run);
1178 let filter = F::init_fetch(world, &query_state.filter_state, last_run, this_run);
1179 QueryManyIter {
1180 world,
1181 query_state,
1182 entities: world.entities(),
1183 archetypes: world.archetypes(),
1184 // SAFETY: We only access table data that has been registered in `query_state`.
1185 // This means `world` has permission to access the data we use.
1186 tables: &world.storages().tables,
1187 fetch,
1188 filter,
1189 entity_iter: entity_list.into_iter(),
1190 }
1191 }
1192
1193 /// # Safety
1194 /// All arguments must stem from the same valid `QueryManyIter`.
1195 ///
1196 /// The lifetime here is not restrictive enough for Fetch with &mut access,
1197 /// as calling `fetch_next_aliased_unchecked` multiple times can produce multiple
1198 /// references to the same component, leading to unique reference aliasing.
1199 ///
1200 /// It is always safe for shared access.
1201 #[inline(always)]
1202 unsafe fn fetch_next_aliased_unchecked(
1203 entity_iter: impl Iterator<Item: EntityEquivalent>,
1204 entities: &'w Entities,
1205 tables: &'w Tables,
1206 archetypes: &'w Archetypes,
1207 fetch: &mut D::Fetch<'w>,
1208 filter: &mut F::Fetch<'w>,
1209 query_state: &'s QueryState<D, F>,
1210 ) -> Option<D::Item<'w, 's>> {
1211 for entity_borrow in entity_iter {
1212 let entity = entity_borrow.entity();
1213 let Some(location) = entities.get(entity) else {
1214 continue;
1215 };
1216
1217 if !query_state
1218 .matched_archetypes
1219 .contains(location.archetype_id.index())
1220 {
1221 continue;
1222 }
1223
1224 let archetype = archetypes.get(location.archetype_id).debug_checked_unwrap();
1225 let table = tables.get(location.table_id).debug_checked_unwrap();
1226
1227 // SAFETY: `archetype` is from the world that `fetch/filter` were created for,
1228 // `fetch_state`/`filter_state` are the states that `fetch/filter` were initialized with
1229 unsafe {
1230 D::set_archetype(fetch, &query_state.fetch_state, archetype, table);
1231 }
1232 // SAFETY: `table` is from the world that `fetch/filter` were created for,
1233 // `fetch_state`/`filter_state` are the states that `fetch/filter` were initialized with
1234 unsafe {
1235 F::set_archetype(filter, &query_state.filter_state, archetype, table);
1236 }
1237
1238 // SAFETY: set_archetype was called prior.
1239 // `location.archetype_row` is an archetype index row in range of the current archetype, because if it was not, the match above would have `continue`d
1240 if unsafe {
1241 F::filter_fetch(
1242 &query_state.filter_state,
1243 filter,
1244 entity,
1245 location.table_row,
1246 )
1247 } {
1248 // SAFETY:
1249 // - set_archetype was called prior, `location.archetype_row` is an archetype index in range of the current archetype
1250 // - fetch is only called once for each entity.
1251 return Some(unsafe {
1252 D::fetch(&query_state.fetch_state, fetch, entity, location.table_row)
1253 });
1254 }
1255 }
1256 None
1257 }
1258
1259 /// Get next result from the query
1260 #[inline(always)]
1261 pub fn fetch_next(&mut self) -> Option<D::Item<'_, 's>> {
1262 // SAFETY:
1263 // All arguments stem from self.
1264 // We are limiting the returned reference to self,
1265 // making sure this method cannot be called multiple times without getting rid
1266 // of any previously returned unique references first, thus preventing aliasing.
1267 unsafe {
1268 Self::fetch_next_aliased_unchecked(
1269 &mut self.entity_iter,
1270 self.entities,
1271 self.tables,
1272 self.archetypes,
1273 &mut self.fetch,
1274 &mut self.filter,
1275 self.query_state,
1276 )
1277 .map(D::shrink)
1278 }
1279 }
1280
1281 /// Sorts all query items into a new iterator, using the query lens as a key.
1282 ///
1283 /// This sort is stable (i.e., does not reorder equal elements).
1284 ///
1285 /// This uses [`slice::sort`] internally.
1286 ///
1287 /// Defining the lens works like [`transmute_lens`](crate::system::Query::transmute_lens).
1288 /// This includes the allowed parameter type changes listed under [allowed transmutes].
1289 /// However, the lens uses the filter of the original query when present.
1290 ///
1291 /// The sort is not cached across system runs.
1292 ///
1293 /// [allowed transmutes]: crate::system::Query#allowed-transmutes
1294 ///
1295 /// Unlike the sort methods on [`QueryIter`], this does NOT panic if `next`/`fetch_next` has been
1296 /// called on [`QueryManyIter`] before.
1297 ///
1298 /// # Examples
1299 /// ```rust
1300 /// # use bevy_ecs::prelude::*;
1301 /// # use std::{ops::{Deref, DerefMut}, iter::Sum};
1302 /// #
1303 /// # #[derive(Component)]
1304 /// # struct PartMarker;
1305 /// #
1306 /// # #[derive(Component, PartialEq, Eq, PartialOrd, Ord)]
1307 /// # struct PartIndex(usize);
1308 /// #
1309 /// # #[derive(Component, Clone, Copy)]
1310 /// # struct PartValue(usize);
1311 /// #
1312 /// # impl Deref for PartValue {
1313 /// # type Target = usize;
1314 /// #
1315 /// # fn deref(&self) -> &Self::Target {
1316 /// # &self.0
1317 /// # }
1318 /// # }
1319 /// #
1320 /// # impl DerefMut for PartValue {
1321 /// # fn deref_mut(&mut self) -> &mut Self::Target {
1322 /// # &mut self.0
1323 /// # }
1324 /// # }
1325 /// #
1326 /// # #[derive(Component, Debug, PartialEq, Eq, PartialOrd, Ord)]
1327 /// # struct Length(usize);
1328 /// #
1329 /// # #[derive(Component, Debug, PartialEq, Eq, PartialOrd, Ord)]
1330 /// # struct Width(usize);
1331 /// #
1332 /// # #[derive(Component, Debug, PartialEq, Eq, PartialOrd, Ord)]
1333 /// # struct Height(usize);
1334 /// #
1335 /// # #[derive(Component, PartialEq, Eq, PartialOrd, Ord)]
1336 /// # struct ParentEntity(Entity);
1337 /// #
1338 /// # let mut world = World::new();
1339 /// // We can ensure that a query always returns in the same order.
1340 /// fn system_1(query: Query<(Entity, &PartIndex)>) {
1341 /// # let entity_list: Vec<Entity> = Vec::new();
1342 /// let parts: Vec<(Entity, &PartIndex)> = query.iter_many(entity_list).sort::<&PartIndex>().collect();
1343 /// }
1344 ///
1345 /// // We can freely rearrange query components in the key.
1346 /// fn system_2(query: Query<(&Length, &Width, &Height), With<PartMarker>>) {
1347 /// # let entity_list: Vec<Entity> = Vec::new();
1348 /// for (length, width, height) in query.iter_many(entity_list).sort::<(&Height, &Length, &Width)>() {
1349 /// println!("height: {height:?}, width: {width:?}, length: {length:?}")
1350 /// }
1351 /// }
1352 ///
1353 /// // You can use `fetch_next_back` to obtain mutable references in reverse order.
1354 /// fn system_3(
1355 /// mut query: Query<&mut PartValue>,
1356 /// ) {
1357 /// # let entity_list: Vec<Entity> = Vec::new();
1358 /// // We need to collect the internal iterator before iterating mutably
1359 /// let mut parent_query_iter = query.iter_many_mut(entity_list)
1360 /// .sort::<Entity>();
1361 ///
1362 /// let mut scratch_value = 0;
1363 /// while let Some(mut part_value) = parent_query_iter.fetch_next_back()
1364 /// {
1365 /// // some order-dependent operation, here bitwise XOR
1366 /// **part_value ^= scratch_value;
1367 /// scratch_value = **part_value;
1368 /// }
1369 /// }
1370 /// #
1371 /// # let mut schedule = Schedule::default();
1372 /// # schedule.add_systems((system_1, system_2, system_3));
1373 /// # schedule.run(&mut world);
1374 /// ```
1375 pub fn sort<L: ReadOnlyQueryData + 'w>(
1376 self,
1377 ) -> QuerySortedManyIter<
1378 'w,
1379 's,
1380 D,
1381 F,
1382 impl ExactSizeIterator<Item = Entity> + DoubleEndedIterator + FusedIterator + 'w,
1383 >
1384 where
1385 for<'lw, 'ls> L::Item<'lw, 'ls>: Ord,
1386 {
1387 self.sort_impl::<L>(|keyed_query| keyed_query.sort())
1388 }
1389
1390 /// Sorts all query items into a new iterator, using the query lens as a key.
1391 ///
1392 /// This sort is unstable (i.e., may reorder equal elements).
1393 ///
1394 /// This uses [`slice::sort_unstable`] internally.
1395 ///
1396 /// Defining the lens works like [`transmute_lens`](crate::system::Query::transmute_lens).
1397 /// This includes the allowed parameter type changes listed under [allowed transmutes]..
1398 /// However, the lens uses the filter of the original query when present.
1399 ///
1400 /// The sort is not cached across system runs.
1401 ///
1402 /// [allowed transmutes]: crate::system::Query#allowed-transmutes
1403 ///
1404 /// Unlike the sort methods on [`QueryIter`], this does NOT panic if `next`/`fetch_next` has been
1405 /// called on [`QueryManyIter`] before.
1406 ///
1407 /// # Example
1408 /// ```
1409 /// # use bevy_ecs::prelude::*;
1410 /// #
1411 /// # let mut world = World::new();
1412 /// #
1413 /// # #[derive(Component)]
1414 /// # struct PartMarker;
1415 /// #
1416 /// # let entity_list: Vec<Entity> = Vec::new();
1417 /// #[derive(Component, PartialEq, Eq, PartialOrd, Ord)]
1418 /// enum Flying {
1419 /// Enabled,
1420 /// Disabled
1421 /// };
1422 ///
1423 /// // We perform an unstable sort by a Component with few values.
1424 /// fn system_1(query: Query<&Flying, With<PartMarker>>) {
1425 /// # let entity_list: Vec<Entity> = Vec::new();
1426 /// let part_values: Vec<&Flying> = query.iter_many(entity_list).sort_unstable::<&Flying>().collect();
1427 /// }
1428 /// #
1429 /// # let mut schedule = Schedule::default();
1430 /// # schedule.add_systems((system_1));
1431 /// # schedule.run(&mut world);
1432 /// ```
1433 pub fn sort_unstable<L: ReadOnlyQueryData + 'w>(
1434 self,
1435 ) -> QuerySortedManyIter<
1436 'w,
1437 's,
1438 D,
1439 F,
1440 impl ExactSizeIterator<Item = Entity> + DoubleEndedIterator + FusedIterator + 'w,
1441 >
1442 where
1443 for<'lw, 'ls> L::Item<'lw, 'ls>: Ord,
1444 {
1445 self.sort_impl::<L>(|keyed_query| keyed_query.sort_unstable())
1446 }
1447
1448 /// Sorts all query items into a new iterator with a comparator function over the query lens.
1449 ///
1450 /// This sort is stable (i.e., does not reorder equal elements).
1451 ///
1452 /// This uses [`slice::sort_by`] internally.
1453 ///
1454 /// Defining the lens works like [`transmute_lens`](crate::system::Query::transmute_lens).
1455 /// This includes the allowed parameter type changes listed under [allowed transmutes].
1456 /// However, the lens uses the filter of the original query when present.
1457 ///
1458 /// The sort is not cached across system runs.
1459 ///
1460 /// [allowed transmutes]: crate::system::Query#allowed-transmutes
1461 ///
1462 /// Unlike the sort methods on [`QueryIter`], this does NOT panic if `next`/`fetch_next` has been
1463 /// called on [`QueryManyIter`] before.
1464 ///
1465 /// # Example
1466 /// ```
1467 /// # use bevy_ecs::prelude::*;
1468 /// # use std::ops::Deref;
1469 /// #
1470 /// # impl Deref for PartValue {
1471 /// # type Target = f32;
1472 /// #
1473 /// # fn deref(&self) -> &Self::Target {
1474 /// # &self.0
1475 /// # }
1476 /// # }
1477 /// #
1478 /// # let mut world = World::new();
1479 /// # let entity_list: Vec<Entity> = Vec::new();
1480 /// #
1481 /// #[derive(Component)]
1482 /// struct PartValue(f32);
1483 ///
1484 /// // We can use a cmp function on components do not implement Ord.
1485 /// fn system_1(query: Query<&PartValue>) {
1486 /// # let entity_list: Vec<Entity> = Vec::new();
1487 /// // Sort part values according to `f32::total_comp`.
1488 /// let part_values: Vec<&PartValue> = query
1489 /// .iter_many(entity_list)
1490 /// .sort_by::<&PartValue>(|value_1, value_2| value_1.total_cmp(*value_2))
1491 /// .collect();
1492 /// }
1493 /// #
1494 /// # let mut schedule = Schedule::default();
1495 /// # schedule.add_systems((system_1));
1496 /// # schedule.run(&mut world);
1497 /// ```
1498 pub fn sort_by<L: ReadOnlyQueryData + 'w>(
1499 self,
1500 mut compare: impl FnMut(&L::Item<'_, '_>, &L::Item<'_, '_>) -> Ordering,
1501 ) -> QuerySortedManyIter<
1502 'w,
1503 's,
1504 D,
1505 F,
1506 impl ExactSizeIterator<Item = Entity> + DoubleEndedIterator + FusedIterator + 'w,
1507 > {
1508 self.sort_impl::<L>(move |keyed_query| {
1509 keyed_query.sort_by(|(key_1, _), (key_2, _)| compare(key_1, key_2));
1510 })
1511 }
1512
1513 /// Sorts all query items into a new iterator with a comparator function over the query lens.
1514 ///
1515 /// This sort is unstable (i.e., may reorder equal elements).
1516 ///
1517 /// This uses [`slice::sort_unstable_by`] internally.
1518 ///
1519 /// Defining the lens works like [`transmute_lens`](crate::system::Query::transmute_lens).
1520 /// This includes the allowed parameter type changes listed under [allowed transmutes].
1521 /// However, the lens uses the filter of the original query when present.
1522 ///
1523 /// The sort is not cached across system runs.
1524 ///
1525 /// [allowed transmutes]: crate::system::Query#allowed-transmutes
1526 ///
1527 /// Unlike the sort methods on [`QueryIter`], this does NOT panic if `next`/`fetch_next` has been
1528 /// called on [`QueryManyIter`] before.
1529 pub fn sort_unstable_by<L: ReadOnlyQueryData + 'w>(
1530 self,
1531 mut compare: impl FnMut(&L::Item<'_, '_>, &L::Item<'_, '_>) -> Ordering,
1532 ) -> QuerySortedManyIter<
1533 'w,
1534 's,
1535 D,
1536 F,
1537 impl ExactSizeIterator<Item = Entity> + DoubleEndedIterator + FusedIterator + 'w,
1538 > {
1539 self.sort_impl::<L>(move |keyed_query| {
1540 keyed_query.sort_unstable_by(|(key_1, _), (key_2, _)| compare(key_1, key_2));
1541 })
1542 }
1543
1544 /// Sorts all query items into a new iterator with a key extraction function over the query lens.
1545 ///
1546 /// This sort is stable (i.e., does not reorder equal elements).
1547 ///
1548 /// This uses [`slice::sort_by_key`] internally.
1549 ///
1550 /// Defining the lens works like [`transmute_lens`](crate::system::Query::transmute_lens).
1551 /// This includes the allowed parameter type changes listed under [allowed transmutes].
1552 /// However, the lens uses the filter of the original query when present.
1553 ///
1554 /// The sort is not cached across system runs.
1555 ///
1556 /// [allowed transmutes]: crate::system::Query#allowed-transmutes
1557 ///
1558 /// Unlike the sort methods on [`QueryIter`], this does NOT panic if `next`/`fetch_next` has been
1559 /// called on [`QueryManyIter`] before.
1560 ///
1561 /// # Example
1562 /// ```
1563 /// # use bevy_ecs::prelude::*;
1564 /// # use std::ops::Deref;
1565 /// #
1566 /// # #[derive(Component)]
1567 /// # struct PartMarker;
1568 /// #
1569 /// # impl Deref for PartValue {
1570 /// # type Target = f32;
1571 /// #
1572 /// # fn deref(&self) -> &Self::Target {
1573 /// # &self.0
1574 /// # }
1575 /// # }
1576 /// #
1577 /// # let mut world = World::new();
1578 /// # let entity_list: Vec<Entity> = Vec::new();
1579 /// #
1580 /// #[derive(Component)]
1581 /// struct AvailableMarker;
1582 ///
1583 /// #[derive(Component, PartialEq, Eq, PartialOrd, Ord, Copy, Clone)]
1584 /// enum Rarity {
1585 /// Common,
1586 /// Rare,
1587 /// Epic,
1588 /// Legendary
1589 /// };
1590 ///
1591 /// #[derive(Component)]
1592 /// struct PartValue(f32);
1593 ///
1594 /// // We can sort with the internals of components that do not implement Ord.
1595 /// fn system_1(query: Query<(Entity, &PartValue)>) {
1596 /// # let entity_list: Vec<Entity> = Vec::new();
1597 /// // Sort by the sines of the part values.
1598 /// let parts: Vec<(Entity, &PartValue)> = query
1599 /// .iter_many(entity_list)
1600 /// .sort_by_key::<&PartValue, _>(|value| value.sin() as usize)
1601 /// .collect();
1602 /// }
1603 ///
1604 /// // We can define our own custom comparison functions over an EntityRef.
1605 /// fn system_2(query: Query<EntityRef, With<PartMarker>>) {
1606 /// # let entity_list: Vec<Entity> = Vec::new();
1607 /// // Sort by whether parts are available and their rarity.
1608 /// // We want the available legendaries to come first, so we reverse the iterator.
1609 /// let parts: Vec<EntityRef> = query.iter_many(entity_list)
1610 /// .sort_by_key::<EntityRef, _>(|entity_ref| {
1611 /// (
1612 /// entity_ref.contains::<AvailableMarker>(),
1613 // entity_ref.get::<Rarity>().copied()
1614 /// )
1615 /// })
1616 /// .rev()
1617 /// .collect();
1618 /// }
1619 /// # let mut schedule = Schedule::default();
1620 /// # schedule.add_systems((system_1, system_2));
1621 /// # schedule.run(&mut world);
1622 /// ```
1623 pub fn sort_by_key<L: ReadOnlyQueryData + 'w, K>(
1624 self,
1625 mut f: impl FnMut(&L::Item<'_, '_>) -> K,
1626 ) -> QuerySortedManyIter<
1627 'w,
1628 's,
1629 D,
1630 F,
1631 impl ExactSizeIterator<Item = Entity> + DoubleEndedIterator + FusedIterator + 'w,
1632 >
1633 where
1634 K: Ord,
1635 {
1636 self.sort_impl::<L>(move |keyed_query| keyed_query.sort_by_key(|(lens, _)| f(lens)))
1637 }
1638
1639 /// Sorts all query items into a new iterator with a key extraction function over the query lens.
1640 ///
1641 /// This sort is unstable (i.e., may reorder equal elements).
1642 ///
1643 /// This uses [`slice::sort_unstable_by_key`] internally.
1644 ///
1645 /// Defining the lens works like [`transmute_lens`](crate::system::Query::transmute_lens).
1646 /// This includes the allowed parameter type changes listed under [allowed transmutes].
1647 /// However, the lens uses the filter of the original query when present.
1648 ///
1649 /// The sort is not cached across system runs.
1650 ///
1651 /// [allowed transmutes]: crate::system::Query#allowed-transmutes
1652 ///
1653 /// Unlike the sort methods on [`QueryIter`], this does NOT panic if `next`/`fetch_next` has been
1654 /// called on [`QueryManyIter`] before.
1655 pub fn sort_unstable_by_key<L: ReadOnlyQueryData + 'w, K>(
1656 self,
1657 mut f: impl FnMut(&L::Item<'_, '_>) -> K,
1658 ) -> QuerySortedManyIter<
1659 'w,
1660 's,
1661 D,
1662 F,
1663 impl ExactSizeIterator<Item = Entity> + DoubleEndedIterator + FusedIterator + 'w,
1664 >
1665 where
1666 K: Ord,
1667 {
1668 self.sort_impl::<L>(move |keyed_query| {
1669 keyed_query.sort_unstable_by_key(|(lens, _)| f(lens));
1670 })
1671 }
1672
1673 /// Sort all query items into a new iterator with a key extraction function over the query lens.
1674 ///
1675 /// This sort is stable (i.e., does not reorder equal elements).
1676 ///
1677 /// This uses [`slice::sort_by_cached_key`] internally.
1678 ///
1679 /// Defining the lens works like [`transmute_lens`](crate::system::Query::transmute_lens).
1680 /// This includes the allowed parameter type changes listed under [allowed transmutes].
1681 /// However, the lens uses the filter of the original query when present.
1682 ///
1683 /// The sort is not cached across system runs.
1684 ///
1685 /// [allowed transmutes]: crate::system::Query#allowed-transmutes
1686 ///
1687 /// Unlike the sort methods on [`QueryIter`], this does NOT panic if `next`/`fetch_next` has been
1688 /// called on [`QueryManyIter`] before.
1689 pub fn sort_by_cached_key<L: ReadOnlyQueryData + 'w, K>(
1690 self,
1691 mut f: impl FnMut(&L::Item<'_, '_>) -> K,
1692 ) -> QuerySortedManyIter<
1693 'w,
1694 's,
1695 D,
1696 F,
1697 impl ExactSizeIterator<Item = Entity> + DoubleEndedIterator + FusedIterator + 'w,
1698 >
1699 where
1700 K: Ord,
1701 {
1702 self.sort_impl::<L>(move |keyed_query| keyed_query.sort_by_cached_key(|(lens, _)| f(lens)))
1703 }
1704
1705 /// Shared implementation for the various `sort` methods.
1706 /// This uses the lens to collect the items for sorting, but delegates the actual sorting to the provided closure.
1707 ///
1708 /// Defining the lens works like [`transmute_lens`](crate::system::Query::transmute_lens).
1709 /// This includes the allowed parameter type changes listed under [allowed transmutes].
1710 /// However, the lens uses the filter of the original query when present.
1711 ///
1712 /// The sort is not cached across system runs.
1713 ///
1714 /// [allowed transmutes]: crate::system::Query#allowed-transmutes
1715 ///
1716 /// Unlike the sort methods on [`QueryIter`], this does NOT panic if `next`/`fetch_next` has been
1717 /// called on [`QueryManyIter`] before.
1718 fn sort_impl<L: ReadOnlyQueryData + 'w>(
1719 self,
1720 f: impl FnOnce(&mut Vec<(L::Item<'_, '_>, NeutralOrd<Entity>)>),
1721 ) -> QuerySortedManyIter<
1722 'w,
1723 's,
1724 D,
1725 F,
1726 impl ExactSizeIterator<Item = Entity> + DoubleEndedIterator + FusedIterator + 'w,
1727 > {
1728 let world = self.world;
1729
1730 let query_lens_state = self.query_state.transmute_filtered::<(L, Entity), F>(world);
1731
1732 // SAFETY:
1733 // `self.world` has permission to access the required components.
1734 // The original query iter has not been iterated on, so no items are aliased from it.
1735 // `QueryIter::new` ensures `world` is the same one used to initialize `query_state`.
1736 let query_lens = unsafe { query_lens_state.query_unchecked_manual(world) }
1737 .iter_many_inner(self.entity_iter);
1738 let mut keyed_query: Vec<_> = query_lens
1739 .map(|(key, entity)| (key, NeutralOrd(entity)))
1740 .collect();
1741 f(&mut keyed_query);
1742 // Re-collect into a `Vec` to eagerly drop the lens items.
1743 // They must be dropped before `fetch_next` is called since they may alias
1744 // with other data items if there are duplicate entities in `entity_iter`.
1745 let entity_iter = keyed_query
1746 .into_iter()
1747 .map(|(.., entity)| entity.0)
1748 .collect::<Vec<_>>()
1749 .into_iter();
1750 // SAFETY:
1751 // `self.world` has permission to access the required components.
1752 // Each lens query item is dropped before the respective actual query item is accessed.
1753 unsafe {
1754 QuerySortedManyIter::new(
1755 world,
1756 self.query_state,
1757 entity_iter,
1758 world.last_change_tick(),
1759 world.change_tick(),
1760 )
1761 }
1762 }
1763}
1764
1765impl<'w, 's, D: QueryData, F: QueryFilter, I: DoubleEndedIterator<Item: EntityEquivalent>>
1766 QueryManyIter<'w, 's, D, F, I>
1767{
1768 /// Get next result from the back of the query
1769 #[inline(always)]
1770 pub fn fetch_next_back(&mut self) -> Option<D::Item<'_, 's>> {
1771 // SAFETY:
1772 // All arguments stem from self.
1773 // We are limiting the returned reference to self,
1774 // making sure this method cannot be called multiple times without getting rid
1775 // of any previously returned unique references first, thus preventing aliasing.
1776 unsafe {
1777 Self::fetch_next_aliased_unchecked(
1778 self.entity_iter.by_ref().rev(),
1779 self.entities,
1780 self.tables,
1781 self.archetypes,
1782 &mut self.fetch,
1783 &mut self.filter,
1784 self.query_state,
1785 )
1786 .map(D::shrink)
1787 }
1788 }
1789}
1790
1791impl<'w, 's, D: ReadOnlyQueryData, F: QueryFilter, I: Iterator<Item: EntityEquivalent>> Iterator
1792 for QueryManyIter<'w, 's, D, F, I>
1793{
1794 type Item = D::Item<'w, 's>;
1795
1796 #[inline(always)]
1797 fn next(&mut self) -> Option<Self::Item> {
1798 // SAFETY:
1799 // All arguments stem from self.
1800 // It is safe to alias for ReadOnlyWorldQuery.
1801 unsafe {
1802 Self::fetch_next_aliased_unchecked(
1803 &mut self.entity_iter,
1804 self.entities,
1805 self.tables,
1806 self.archetypes,
1807 &mut self.fetch,
1808 &mut self.filter,
1809 self.query_state,
1810 )
1811 }
1812 }
1813
1814 fn size_hint(&self) -> (usize, Option<usize>) {
1815 let (_, max_size) = self.entity_iter.size_hint();
1816 (0, max_size)
1817 }
1818}
1819
1820impl<
1821 'w,
1822 's,
1823 D: ReadOnlyQueryData,
1824 F: QueryFilter,
1825 I: DoubleEndedIterator<Item: EntityEquivalent>,
1826 > DoubleEndedIterator for QueryManyIter<'w, 's, D, F, I>
1827{
1828 #[inline(always)]
1829 fn next_back(&mut self) -> Option<Self::Item> {
1830 // SAFETY:
1831 // All arguments stem from self.
1832 // It is safe to alias for ReadOnlyWorldQuery.
1833 unsafe {
1834 Self::fetch_next_aliased_unchecked(
1835 self.entity_iter.by_ref().rev(),
1836 self.entities,
1837 self.tables,
1838 self.archetypes,
1839 &mut self.fetch,
1840 &mut self.filter,
1841 self.query_state,
1842 )
1843 }
1844 }
1845}
1846
1847// This is correct as [`QueryManyIter`] always returns `None` once exhausted.
1848impl<'w, 's, D: ReadOnlyQueryData, F: QueryFilter, I: Iterator<Item: EntityEquivalent>>
1849 FusedIterator for QueryManyIter<'w, 's, D, F, I>
1850{
1851}
1852
1853// SAFETY: Fetching unique entities maintains uniqueness.
1854unsafe impl<'w, 's, F: QueryFilter, I: EntitySetIterator> EntitySetIterator
1855 for QueryManyIter<'w, 's, Entity, F, I>
1856{
1857}
1858
1859impl<'w, 's, D: QueryData, F: QueryFilter, I: Iterator<Item: EntityEquivalent>> Debug
1860 for QueryManyIter<'w, 's, D, F, I>
1861{
1862 fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
1863 f.debug_struct("QueryManyIter").finish()
1864 }
1865}
1866
1867/// An [`Iterator`] over the query items generated from an iterator of unique [`Entity`]s.
1868///
1869/// Items are returned in the order of the provided iterator.
1870/// Entities that don't match the query are skipped.
1871///
1872/// In contrast with [`QueryManyIter`], this allows for mutable iteration without a [`fetch_next`] method.
1873///
1874/// This struct is created by the [`iter_many_unique`] and [`iter_many_unique_mut`] methods on [`Query`].
1875///
1876/// [`fetch_next`]: QueryManyIter::fetch_next
1877/// [`iter_many_unique`]: crate::system::Query::iter_many
1878/// [`iter_many_unique_mut`]: crate::system::Query::iter_many_mut
1879/// [`Query`]: crate::system::Query
1880pub struct QueryManyUniqueIter<'w, 's, D: QueryData, F: QueryFilter, I: EntitySetIterator>(
1881 QueryManyIter<'w, 's, D, F, I>,
1882);
1883
1884impl<'w, 's, D: QueryData, F: QueryFilter, I: EntitySetIterator>
1885 QueryManyUniqueIter<'w, 's, D, F, I>
1886{
1887 /// # Safety
1888 /// - `world` must have permission to access any of the components registered in `query_state`.
1889 /// - `world` must be the same one used to initialize `query_state`.
1890 pub(crate) unsafe fn new<EntityList: EntitySet<IntoIter = I>>(
1891 world: UnsafeWorldCell<'w>,
1892 query_state: &'s QueryState<D, F>,
1893 entity_list: EntityList,
1894 last_run: Tick,
1895 this_run: Tick,
1896 ) -> QueryManyUniqueIter<'w, 's, D, F, I> {
1897 QueryManyUniqueIter(QueryManyIter::new(
1898 world,
1899 query_state,
1900 entity_list,
1901 last_run,
1902 this_run,
1903 ))
1904 }
1905}
1906
1907impl<'w, 's, D: QueryData, F: QueryFilter, I: EntitySetIterator> Iterator
1908 for QueryManyUniqueIter<'w, 's, D, F, I>
1909{
1910 type Item = D::Item<'w, 's>;
1911
1912 #[inline(always)]
1913 fn next(&mut self) -> Option<Self::Item> {
1914 // SAFETY: Entities are guaranteed to be unique, thus do not alias.
1915 unsafe {
1916 QueryManyIter::<'w, 's, D, F, I>::fetch_next_aliased_unchecked(
1917 &mut self.0.entity_iter,
1918 self.0.entities,
1919 self.0.tables,
1920 self.0.archetypes,
1921 &mut self.0.fetch,
1922 &mut self.0.filter,
1923 self.0.query_state,
1924 )
1925 }
1926 }
1927
1928 fn size_hint(&self) -> (usize, Option<usize>) {
1929 let (_, max_size) = self.0.entity_iter.size_hint();
1930 (0, max_size)
1931 }
1932}
1933
1934// This is correct as [`QueryManyIter`] always returns `None` once exhausted.
1935impl<'w, 's, D: QueryData, F: QueryFilter, I: EntitySetIterator> FusedIterator
1936 for QueryManyUniqueIter<'w, 's, D, F, I>
1937{
1938}
1939
1940// SAFETY: Fetching unique entities maintains uniqueness.
1941unsafe impl<'w, 's, F: QueryFilter, I: EntitySetIterator> EntitySetIterator
1942 for QueryManyUniqueIter<'w, 's, Entity, F, I>
1943{
1944}
1945
1946impl<'w, 's, D: QueryData, F: QueryFilter, I: EntitySetIterator> Debug
1947 for QueryManyUniqueIter<'w, 's, D, F, I>
1948{
1949 fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
1950 f.debug_struct("QueryManyUniqueIter").finish()
1951 }
1952}
1953
1954/// An [`Iterator`] over sorted query results of a [`QueryManyIter`].
1955///
1956/// This struct is created by the [`sort`](QueryManyIter), [`sort_unstable`](QueryManyIter),
1957/// [`sort_by`](QueryManyIter), [`sort_unstable_by`](QueryManyIter), [`sort_by_key`](QueryManyIter),
1958/// [`sort_unstable_by_key`](QueryManyIter), and [`sort_by_cached_key`](QueryManyIter) methods of [`QueryManyIter`].
1959pub struct QuerySortedManyIter<'w, 's, D: QueryData, F: QueryFilter, I: Iterator<Item = Entity>> {
1960 entity_iter: I,
1961 entities: &'w Entities,
1962 tables: &'w Tables,
1963 archetypes: &'w Archetypes,
1964 fetch: D::Fetch<'w>,
1965 query_state: &'s QueryState<D, F>,
1966}
1967
1968impl<'w, 's, D: QueryData, F: QueryFilter, I: Iterator<Item = Entity>>
1969 QuerySortedManyIter<'w, 's, D, F, I>
1970{
1971 /// # Safety
1972 /// - `world` must have permission to access any of the components registered in `query_state`.
1973 /// - `world` must be the same one used to initialize `query_state`.
1974 /// - `entity_list` must only contain unique entities or be empty.
1975 pub(crate) unsafe fn new<EntityList: IntoIterator<IntoIter = I>>(
1976 world: UnsafeWorldCell<'w>,
1977 query_state: &'s QueryState<D, F>,
1978 entity_list: EntityList,
1979 last_run: Tick,
1980 this_run: Tick,
1981 ) -> QuerySortedManyIter<'w, 's, D, F, I> {
1982 let fetch = D::init_fetch(world, &query_state.fetch_state, last_run, this_run);
1983 QuerySortedManyIter {
1984 query_state,
1985 entities: world.entities(),
1986 archetypes: world.archetypes(),
1987 // SAFETY: We only access table data that has been registered in `query_state`.
1988 // This means `world` has permission to access the data we use.
1989 tables: &world.storages().tables,
1990 fetch,
1991 entity_iter: entity_list.into_iter(),
1992 }
1993 }
1994
1995 /// # Safety
1996 /// The lifetime here is not restrictive enough for Fetch with &mut access,
1997 /// as calling `fetch_next_aliased_unchecked` multiple times can produce multiple
1998 /// references to the same component, leading to unique reference aliasing.
1999 ///
2000 /// It is always safe for shared access.
2001 /// `entity` must stem from `self.entity_iter`, and not have been passed before.
2002 #[inline(always)]
2003 unsafe fn fetch_next_aliased_unchecked(&mut self, entity: Entity) -> D::Item<'w, 's> {
2004 let (location, archetype, table);
2005 // SAFETY:
2006 // `tables` and `archetypes` belong to the same world that the [`QueryIter`]
2007 // was initialized for.
2008 unsafe {
2009 location = self.entities.get(entity).debug_checked_unwrap();
2010 archetype = self
2011 .archetypes
2012 .get(location.archetype_id)
2013 .debug_checked_unwrap();
2014 table = self.tables.get(location.table_id).debug_checked_unwrap();
2015 }
2016
2017 // SAFETY: `archetype` is from the world that `fetch` was created for,
2018 // `fetch_state` is the state that `fetch` was initialized with
2019 unsafe {
2020 D::set_archetype(
2021 &mut self.fetch,
2022 &self.query_state.fetch_state,
2023 archetype,
2024 table,
2025 );
2026 }
2027
2028 // The entity list has already been filtered by the query lens, so we forego filtering here.
2029 // SAFETY:
2030 // - set_archetype was called prior, `location.archetype_row` is an archetype index in range of the current archetype
2031 // - fetch is only called once for each entity.
2032 unsafe {
2033 D::fetch(
2034 &self.query_state.fetch_state,
2035 &mut self.fetch,
2036 entity,
2037 location.table_row,
2038 )
2039 }
2040 }
2041
2042 /// Get next result from the query
2043 #[inline(always)]
2044 pub fn fetch_next(&mut self) -> Option<D::Item<'_, 's>> {
2045 let entity = self.entity_iter.next()?;
2046
2047 // SAFETY:
2048 // We have collected the entity_iter once to drop all internal lens query item
2049 // references.
2050 // We are limiting the returned reference to self,
2051 // making sure this method cannot be called multiple times without getting rid
2052 // of any previously returned unique references first, thus preventing aliasing.
2053 // `entity` is passed from `entity_iter` the first time.
2054 unsafe { D::shrink(self.fetch_next_aliased_unchecked(entity)).into() }
2055 }
2056}
2057
2058impl<'w, 's, D: QueryData, F: QueryFilter, I: DoubleEndedIterator<Item = Entity>>
2059 QuerySortedManyIter<'w, 's, D, F, I>
2060{
2061 /// Get next result from the query
2062 #[inline(always)]
2063 pub fn fetch_next_back(&mut self) -> Option<D::Item<'_, 's>> {
2064 let entity = self.entity_iter.next_back()?;
2065
2066 // SAFETY:
2067 // We have collected the entity_iter once to drop all internal lens query item
2068 // references.
2069 // We are limiting the returned reference to self,
2070 // making sure this method cannot be called multiple times without getting rid
2071 // of any previously returned unique references first, thus preventing aliasing.
2072 // `entity` is passed from `entity_iter` the first time.
2073 unsafe { D::shrink(self.fetch_next_aliased_unchecked(entity)).into() }
2074 }
2075}
2076
2077impl<'w, 's, D: ReadOnlyQueryData, F: QueryFilter, I: Iterator<Item = Entity>> Iterator
2078 for QuerySortedManyIter<'w, 's, D, F, I>
2079{
2080 type Item = D::Item<'w, 's>;
2081
2082 #[inline(always)]
2083 fn next(&mut self) -> Option<Self::Item> {
2084 let entity = self.entity_iter.next()?;
2085 // SAFETY:
2086 // It is safe to alias for ReadOnlyWorldQuery.
2087 // `entity` is passed from `entity_iter` the first time.
2088 unsafe { self.fetch_next_aliased_unchecked(entity).into() }
2089 }
2090
2091 fn size_hint(&self) -> (usize, Option<usize>) {
2092 self.entity_iter.size_hint()
2093 }
2094}
2095
2096impl<'w, 's, D: ReadOnlyQueryData, F: QueryFilter, I: DoubleEndedIterator<Item = Entity>>
2097 DoubleEndedIterator for QuerySortedManyIter<'w, 's, D, F, I>
2098{
2099 #[inline(always)]
2100 fn next_back(&mut self) -> Option<Self::Item> {
2101 let entity = self.entity_iter.next_back()?;
2102 // SAFETY:
2103 // It is safe to alias for ReadOnlyWorldQuery.
2104 // `entity` is passed from `entity_iter` the first time.
2105 unsafe { self.fetch_next_aliased_unchecked(entity).into() }
2106 }
2107}
2108
2109impl<'w, 's, D: ReadOnlyQueryData, F: QueryFilter, I: ExactSizeIterator<Item = Entity>>
2110 ExactSizeIterator for QuerySortedManyIter<'w, 's, D, F, I>
2111{
2112}
2113
2114impl<'w, 's, D: QueryData, F: QueryFilter, I: Iterator<Item = Entity>> Debug
2115 for QuerySortedManyIter<'w, 's, D, F, I>
2116{
2117 fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
2118 f.debug_struct("QuerySortedManyIter").finish()
2119 }
2120}
2121
2122/// An iterator over `K`-sized combinations of query items without repetition.
2123///
2124/// A combination is an arrangement of a collection of items where order does not matter.
2125///
2126/// `K` is the number of items that make up each subset, and the number of items returned by the iterator.
2127/// `N` is the number of total entities output by the query.
2128///
2129/// For example, given the list [1, 2, 3, 4], where `K` is 2, the combinations without repeats are
2130/// [1, 2], [1, 3], [1, 4], [2, 3], [2, 4], [3, 4].
2131/// And in this case, `N` would be defined as 4 since the size of the input list is 4.
2132///
2133/// The number of combinations depend on how `K` relates to the number of entities matching the [`Query`]:
2134/// - if `K = N`, only one combination exists,
2135/// - if `K < N`, there are <sub>N</sub>C<sub>K</sub> combinations (see the [performance section] of `Query`),
2136/// - if `K > N`, there are no combinations.
2137///
2138/// The output combination is not guaranteed to have any order of iteration.
2139///
2140/// # Usage
2141///
2142/// This type is returned by calling [`Query::iter_combinations`] or [`Query::iter_combinations_mut`].
2143///
2144/// It implements [`Iterator`] only if it iterates over read-only query items ([learn more]).
2145///
2146/// In the case of mutable query items, it can be iterated by calling [`fetch_next`] in a `while let` loop.
2147///
2148/// # Examples
2149///
2150/// The following example shows how to traverse the iterator when the query items are read-only.
2151///
2152/// ```
2153/// # use bevy_ecs::prelude::*;
2154/// # #[derive(Component)]
2155/// # struct ComponentA;
2156/// #
2157/// fn some_system(query: Query<&ComponentA>) {
2158/// for [a1, a2] in query.iter_combinations() {
2159/// // ...
2160/// }
2161/// }
2162/// ```
2163///
2164/// The following example shows how `fetch_next` should be called with a `while let` loop to traverse the iterator when the query items are mutable.
2165///
2166/// ```
2167/// # use bevy_ecs::prelude::*;
2168/// # #[derive(Component)]
2169/// # struct ComponentA;
2170/// #
2171/// fn some_system(mut query: Query<&mut ComponentA>) {
2172/// let mut combinations = query.iter_combinations_mut();
2173/// while let Some([a1, a2]) = combinations.fetch_next() {
2174/// // ...
2175/// }
2176/// }
2177/// ```
2178///
2179/// [`fetch_next`]: Self::fetch_next
2180/// [learn more]: Self#impl-Iterator
2181/// [performance section]: crate::system::Query#performance
2182/// [`Query`]: crate::system::Query
2183/// [`Query::iter_combinations`]: crate::system::Query::iter_combinations
2184/// [`Query::iter_combinations_mut`]: crate::system::Query::iter_combinations_mut
2185pub struct QueryCombinationIter<'w, 's, D: QueryData, F: QueryFilter, const K: usize> {
2186 tables: &'w Tables,
2187 archetypes: &'w Archetypes,
2188 query_state: &'s QueryState<D, F>,
2189 cursors: [QueryIterationCursor<'w, 's, D, F>; K],
2190}
2191
2192impl<'w, 's, D: QueryData, F: QueryFilter, const K: usize> QueryCombinationIter<'w, 's, D, F, K> {
2193 /// # Safety
2194 /// - `world` must have permission to access any of the components registered in `query_state`.
2195 /// - `world` must be the same one used to initialize `query_state`.
2196 pub(crate) unsafe fn new(
2197 world: UnsafeWorldCell<'w>,
2198 query_state: &'s QueryState<D, F>,
2199 last_run: Tick,
2200 this_run: Tick,
2201 ) -> Self {
2202 assert!(K != 0, "K should not equal to zero");
2203 // Initialize array with cursors.
2204 // There is no FromIterator on arrays, so instead initialize it manually with MaybeUninit
2205
2206 let mut array: MaybeUninit<[QueryIterationCursor<'w, 's, D, F>; K]> = MaybeUninit::uninit();
2207 let ptr = array
2208 .as_mut_ptr()
2209 .cast::<QueryIterationCursor<'w, 's, D, F>>();
2210 ptr.write(QueryIterationCursor::init(
2211 world,
2212 query_state,
2213 last_run,
2214 this_run,
2215 ));
2216 for slot in (1..K).map(|offset| ptr.add(offset)) {
2217 slot.write(QueryIterationCursor::init_empty(
2218 world,
2219 query_state,
2220 last_run,
2221 this_run,
2222 ));
2223 }
2224
2225 QueryCombinationIter {
2226 query_state,
2227 // SAFETY: We only access table data that has been registered in `query_state`.
2228 tables: unsafe { &world.storages().tables },
2229 archetypes: world.archetypes(),
2230 cursors: array.assume_init(),
2231 }
2232 }
2233
2234 /// # Safety
2235 /// The lifetime here is not restrictive enough for Fetch with &mut access,
2236 /// as calling `fetch_next_aliased_unchecked` multiple times can produce multiple
2237 /// references to the same component, leading to unique reference aliasing.
2238 /// .
2239 /// It is always safe for shared access.
2240 #[inline]
2241 unsafe fn fetch_next_aliased_unchecked(&mut self) -> Option<[D::Item<'w, 's>; K]> {
2242 // PERF: can speed up the following code using `cursor.remaining()` instead of `next_item.is_none()`
2243 // when D::IS_ARCHETYPAL && F::IS_ARCHETYPAL
2244 //
2245 // let `i` be the index of `c`, the last cursor in `self.cursors` that
2246 // returns `K-i` or more elements.
2247 // Make cursor in index `j` for all `j` in `[i, K)` a copy of `c` advanced `j-i+1` times.
2248 // If no such `c` exists, return `None`
2249 'outer: for i in (0..K).rev() {
2250 match self.cursors[i].next(self.tables, self.archetypes, self.query_state) {
2251 Some(_) => {
2252 for j in (i + 1)..K {
2253 self.cursors[j] = self.cursors[j - 1].clone();
2254 match self.cursors[j].next(self.tables, self.archetypes, self.query_state) {
2255 Some(_) => {}
2256 None if i > 0 => continue 'outer,
2257 None => return None,
2258 }
2259 }
2260 break;
2261 }
2262 None if i > 0 => continue,
2263 None => return None,
2264 }
2265 }
2266
2267 let mut values = MaybeUninit::<[D::Item<'w, 's>; K]>::uninit();
2268
2269 let ptr = values.as_mut_ptr().cast::<D::Item<'w, 's>>();
2270 for (offset, cursor) in self.cursors.iter_mut().enumerate() {
2271 ptr.add(offset)
2272 .write(cursor.peek_last(self.query_state).unwrap());
2273 }
2274
2275 Some(values.assume_init())
2276 }
2277
2278 /// Get next combination of queried components
2279 #[inline]
2280 pub fn fetch_next(&mut self) -> Option<[D::Item<'_, 's>; K]> {
2281 // SAFETY: we are limiting the returned reference to self,
2282 // making sure this method cannot be called multiple times without getting rid
2283 // of any previously returned unique references first, thus preventing aliasing.
2284 unsafe {
2285 self.fetch_next_aliased_unchecked()
2286 .map(|array| array.map(D::shrink))
2287 }
2288 }
2289}
2290
2291// Iterator type is intentionally implemented only for read-only access.
2292// Doing so for mutable references would be unsound, because calling `next`
2293// multiple times would allow multiple owned references to the same data to exist.
2294impl<'w, 's, D: ReadOnlyQueryData, F: QueryFilter, const K: usize> Iterator
2295 for QueryCombinationIter<'w, 's, D, F, K>
2296{
2297 type Item = [D::Item<'w, 's>; K];
2298
2299 #[inline]
2300 fn next(&mut self) -> Option<Self::Item> {
2301 // Safety: it is safe to alias for ReadOnlyWorldQuery
2302 unsafe { QueryCombinationIter::fetch_next_aliased_unchecked(self) }
2303 }
2304
2305 fn size_hint(&self) -> (usize, Option<usize>) {
2306 // binomial coefficient: (n ; k) = n! / k!(n-k)! = (n*n-1*...*n-k+1) / k!
2307 // See https://en.wikipedia.org/wiki/Binomial_coefficient
2308 // See https://blog.plover.com/math/choose.html for implementation
2309 // It was chosen to reduce overflow potential.
2310 fn choose(n: usize, k: usize) -> Option<usize> {
2311 if k > n || n == 0 {
2312 return Some(0);
2313 }
2314 let k = k.min(n - k);
2315 let ks = 1..=k;
2316 let ns = (n - k + 1..=n).rev();
2317 ks.zip(ns)
2318 .try_fold(1_usize, |acc, (k, n)| Some(acc.checked_mul(n)? / k))
2319 }
2320 // sum_i=0..k choose(cursors[i].remaining, k-i)
2321 let max_combinations = self
2322 .cursors
2323 .iter()
2324 .enumerate()
2325 .try_fold(0, |acc, (i, cursor)| {
2326 let n = cursor.max_remaining(self.tables, self.archetypes);
2327 Some(acc + choose(n as usize, K - i)?)
2328 });
2329
2330 let archetype_query = F::IS_ARCHETYPAL;
2331 let known_max = max_combinations.unwrap_or(usize::MAX);
2332 let min_combinations = if archetype_query { known_max } else { 0 };
2333 (min_combinations, max_combinations)
2334 }
2335}
2336
2337impl<'w, 's, D: QueryData, F: QueryFilter> ExactSizeIterator for QueryIter<'w, 's, D, F>
2338where
2339 F: ArchetypeFilter,
2340{
2341 fn len(&self) -> usize {
2342 self.size_hint().0
2343 }
2344}
2345
2346// This is correct as [`QueryCombinationIter`] always returns `None` once exhausted.
2347impl<'w, 's, D: ReadOnlyQueryData, F: QueryFilter, const K: usize> FusedIterator
2348 for QueryCombinationIter<'w, 's, D, F, K>
2349{
2350}
2351
2352impl<'w, 's, D: QueryData, F: QueryFilter, const K: usize> Debug
2353 for QueryCombinationIter<'w, 's, D, F, K>
2354{
2355 fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
2356 f.debug_struct("QueryCombinationIter").finish()
2357 }
2358}
2359
2360struct QueryIterationCursor<'w, 's, D: QueryData, F: QueryFilter> {
2361 // whether the query iteration is dense or not. Mirrors QueryState's `is_dense` field.
2362 is_dense: bool,
2363 storage_id_iter: core::slice::Iter<'s, StorageId>,
2364 table_entities: &'w [Entity],
2365 archetype_entities: &'w [ArchetypeEntity],
2366 fetch: D::Fetch<'w>,
2367 filter: F::Fetch<'w>,
2368 // length of the table or length of the archetype, depending on whether both `D`'s and `F`'s fetches are dense
2369 current_len: u32,
2370 // either table row or archetype index, depending on whether both `D`'s and `F`'s fetches are dense
2371 current_row: u32,
2372}
2373
2374impl<D: QueryData, F: QueryFilter> Clone for QueryIterationCursor<'_, '_, D, F> {
2375 fn clone(&self) -> Self {
2376 Self {
2377 is_dense: self.is_dense,
2378 storage_id_iter: self.storage_id_iter.clone(),
2379 table_entities: self.table_entities,
2380 archetype_entities: self.archetype_entities,
2381 fetch: self.fetch.clone(),
2382 filter: self.filter.clone(),
2383 current_len: self.current_len,
2384 current_row: self.current_row,
2385 }
2386 }
2387}
2388
2389impl<'w, 's, D: QueryData, F: QueryFilter> QueryIterationCursor<'w, 's, D, F> {
2390 /// # Safety
2391 /// - `world` must have permission to access any of the components registered in `query_state`.
2392 /// - `world` must be the same one used to initialize `query_state`.
2393 unsafe fn init_empty(
2394 world: UnsafeWorldCell<'w>,
2395 query_state: &'s QueryState<D, F>,
2396 last_run: Tick,
2397 this_run: Tick,
2398 ) -> Self {
2399 QueryIterationCursor {
2400 storage_id_iter: [].iter(),
2401 ..Self::init(world, query_state, last_run, this_run)
2402 }
2403 }
2404
2405 /// # Safety
2406 /// - `world` must have permission to access any of the components registered in `query_state`.
2407 /// - `world` must be the same one used to initialize `query_state`.
2408 unsafe fn init(
2409 world: UnsafeWorldCell<'w>,
2410 query_state: &'s QueryState<D, F>,
2411 last_run: Tick,
2412 this_run: Tick,
2413 ) -> Self {
2414 let fetch = D::init_fetch(world, &query_state.fetch_state, last_run, this_run);
2415 let filter = F::init_fetch(world, &query_state.filter_state, last_run, this_run);
2416 QueryIterationCursor {
2417 fetch,
2418 filter,
2419 table_entities: &[],
2420 archetype_entities: &[],
2421 storage_id_iter: query_state.matched_storage_ids.iter(),
2422 is_dense: query_state.is_dense,
2423 current_len: 0,
2424 current_row: 0,
2425 }
2426 }
2427
2428 fn reborrow(&mut self) -> QueryIterationCursor<'_, 's, D, F> {
2429 QueryIterationCursor {
2430 is_dense: self.is_dense,
2431 fetch: D::shrink_fetch(self.fetch.clone()),
2432 filter: F::shrink_fetch(self.filter.clone()),
2433 table_entities: self.table_entities,
2434 archetype_entities: self.archetype_entities,
2435 storage_id_iter: self.storage_id_iter.clone(),
2436 current_len: self.current_len,
2437 current_row: self.current_row,
2438 }
2439 }
2440
2441 /// Retrieve item returned from most recent `next` call again.
2442 ///
2443 /// # Safety
2444 /// The result of `next` and any previous calls to `peek_last` with this row must have been
2445 /// dropped to prevent aliasing mutable references.
2446 #[inline]
2447 unsafe fn peek_last(&mut self, query_state: &'s QueryState<D, F>) -> Option<D::Item<'w, 's>> {
2448 if self.current_row > 0 {
2449 let index = self.current_row - 1;
2450 if self.is_dense {
2451 // SAFETY: This must have been called previously in `next` as `current_row > 0`
2452 let entity = unsafe { self.table_entities.get_unchecked(index as usize) };
2453 // SAFETY:
2454 // - `set_table` must have been called previously either in `next` or before it.
2455 // - `*entity` and `index` are in the current table.
2456 unsafe {
2457 Some(D::fetch(
2458 &query_state.fetch_state,
2459 &mut self.fetch,
2460 *entity,
2461 // SAFETY: This is from an exclusive range, so it can't be max.
2462 TableRow::new(NonMaxU32::new_unchecked(index)),
2463 ))
2464 }
2465 } else {
2466 // SAFETY: This must have been called previously in `next` as `current_row > 0`
2467 let archetype_entity =
2468 unsafe { self.archetype_entities.get_unchecked(index as usize) };
2469 // SAFETY:
2470 // - `set_archetype` must have been called previously either in `next` or before it.
2471 // - `archetype_entity.id()` and `archetype_entity.table_row()` are in the current archetype.
2472 unsafe {
2473 Some(D::fetch(
2474 &query_state.fetch_state,
2475 &mut self.fetch,
2476 archetype_entity.id(),
2477 archetype_entity.table_row(),
2478 ))
2479 }
2480 }
2481 } else {
2482 None
2483 }
2484 }
2485
2486 /// How many values will this cursor return at most?
2487 ///
2488 /// Note that if `F::IS_ARCHETYPAL`, the return value
2489 /// will be **the exact count of remaining values**.
2490 fn max_remaining(&self, tables: &'w Tables, archetypes: &'w Archetypes) -> u32 {
2491 let ids = self.storage_id_iter.clone();
2492 let remaining_matched: u32 = if self.is_dense {
2493 // SAFETY: The if check ensures that storage_id_iter stores TableIds
2494 unsafe { ids.map(|id| tables[id.table_id].entity_count()).sum() }
2495 } else {
2496 // SAFETY: The if check ensures that storage_id_iter stores ArchetypeIds
2497 unsafe { ids.map(|id| archetypes[id.archetype_id].len()).sum() }
2498 };
2499 remaining_matched + self.current_len - self.current_row
2500 }
2501
2502 // NOTE: If you are changing query iteration code, remember to update the following places, where relevant:
2503 // QueryIter, QueryIterationCursor, QuerySortedIter, QueryManyIter, QuerySortedManyIter, QueryCombinationIter,
2504 // QueryState::par_fold_init_unchecked_manual, QueryState::par_many_fold_init_unchecked_manual,
2505 // QueryState::par_many_unique_fold_init_unchecked_manual
2506 /// # Safety
2507 /// `tables` and `archetypes` must belong to the same world that the [`QueryIterationCursor`]
2508 /// was initialized for.
2509 /// `query_state` must be the same [`QueryState`] that was passed to `init` or `init_empty`.
2510 #[inline(always)]
2511 unsafe fn next(
2512 &mut self,
2513 tables: &'w Tables,
2514 archetypes: &'w Archetypes,
2515 query_state: &'s QueryState<D, F>,
2516 ) -> Option<D::Item<'w, 's>> {
2517 if self.is_dense {
2518 loop {
2519 // we are on the beginning of the query, or finished processing a table, so skip to the next
2520 if self.current_row == self.current_len {
2521 let table_id = self.storage_id_iter.next()?.table_id;
2522 let table = tables.get(table_id).debug_checked_unwrap();
2523 if table.is_empty() {
2524 continue;
2525 }
2526 // SAFETY: `table` is from the world that `fetch/filter` were created for,
2527 // `fetch_state`/`filter_state` are the states that `fetch/filter` were initialized with
2528 unsafe {
2529 D::set_table(&mut self.fetch, &query_state.fetch_state, table);
2530 F::set_table(&mut self.filter, &query_state.filter_state, table);
2531 }
2532 self.table_entities = table.entities();
2533 self.current_len = table.entity_count();
2534 self.current_row = 0;
2535 }
2536
2537 // SAFETY: set_table was called prior.
2538 // `current_row` is a table row in range of the current table, because if it was not, then the above would have been executed.
2539 let entity =
2540 unsafe { self.table_entities.get_unchecked(self.current_row as usize) };
2541 // SAFETY: The row is less than the u32 len, so it must not be max.
2542 let row = unsafe { TableRow::new(NonMaxU32::new_unchecked(self.current_row)) };
2543 if !F::filter_fetch(&query_state.filter_state, &mut self.filter, *entity, row) {
2544 self.current_row += 1;
2545 continue;
2546 }
2547
2548 // SAFETY:
2549 // - set_table was called prior.
2550 // - `current_row` must be a table row in range of the current table,
2551 // because if it was not, then the above would have been executed.
2552 // - fetch is only called once for each `entity`.
2553 let item =
2554 unsafe { D::fetch(&query_state.fetch_state, &mut self.fetch, *entity, row) };
2555
2556 self.current_row += 1;
2557 return Some(item);
2558 }
2559 } else {
2560 loop {
2561 if self.current_row == self.current_len {
2562 let archetype_id = self.storage_id_iter.next()?.archetype_id;
2563 let archetype = archetypes.get(archetype_id).debug_checked_unwrap();
2564 if archetype.is_empty() {
2565 continue;
2566 }
2567 let table = tables.get(archetype.table_id()).debug_checked_unwrap();
2568 // SAFETY: `archetype` and `tables` are from the world that `fetch/filter` were created for,
2569 // `fetch_state`/`filter_state` are the states that `fetch/filter` were initialized with
2570 unsafe {
2571 D::set_archetype(
2572 &mut self.fetch,
2573 &query_state.fetch_state,
2574 archetype,
2575 table,
2576 );
2577 F::set_archetype(
2578 &mut self.filter,
2579 &query_state.filter_state,
2580 archetype,
2581 table,
2582 );
2583 }
2584 self.archetype_entities = archetype.entities();
2585 self.current_len = archetype.len();
2586 self.current_row = 0;
2587 }
2588
2589 // SAFETY: set_archetype was called prior.
2590 // `current_row` is an archetype index row in range of the current archetype, because if it was not, then the if above would have been executed.
2591 let archetype_entity = unsafe {
2592 self.archetype_entities
2593 .get_unchecked(self.current_row as usize)
2594 };
2595 if !F::filter_fetch(
2596 &query_state.filter_state,
2597 &mut self.filter,
2598 archetype_entity.id(),
2599 archetype_entity.table_row(),
2600 ) {
2601 self.current_row += 1;
2602 continue;
2603 }
2604
2605 // SAFETY:
2606 // - set_archetype was called prior.
2607 // - `current_row` must be an archetype index row in range of the current archetype,
2608 // because if it was not, then the if above would have been executed.
2609 // - fetch is only called once for each `archetype_entity`.
2610 let item = unsafe {
2611 D::fetch(
2612 &query_state.fetch_state,
2613 &mut self.fetch,
2614 archetype_entity.id(),
2615 archetype_entity.table_row(),
2616 )
2617 };
2618 self.current_row += 1;
2619 return Some(item);
2620 }
2621 }
2622 }
2623}
2624
2625// A wrapper struct that gives its data a neutral ordering.
2626#[derive(Copy, Clone)]
2627struct NeutralOrd<T>(T);
2628
2629impl<T> PartialEq for NeutralOrd<T> {
2630 fn eq(&self, _other: &Self) -> bool {
2631 true
2632 }
2633}
2634
2635impl<T> Eq for NeutralOrd<T> {}
2636
2637#[expect(
2638 clippy::non_canonical_partial_ord_impl,
2639 reason = "`PartialOrd` and `Ord` on this struct must only ever return `Ordering::Equal`, so we prefer clarity"
2640)]
2641impl<T> PartialOrd for NeutralOrd<T> {
2642 fn partial_cmp(&self, _other: &Self) -> Option<Ordering> {
2643 Some(Ordering::Equal)
2644 }
2645}
2646
2647impl<T> Ord for NeutralOrd<T> {
2648 fn cmp(&self, _other: &Self) -> Ordering {
2649 Ordering::Equal
2650 }
2651}
2652
2653#[cfg(test)]
2654#[expect(clippy::print_stdout, reason = "Allowed in tests.")]
2655mod tests {
2656 use alloc::vec::Vec;
2657 use std::println;
2658
2659 use crate::component::Component;
2660 use crate::entity::Entity;
2661 use crate::prelude::World;
2662
2663 #[derive(Component, Debug, PartialEq, PartialOrd, Clone, Copy)]
2664 struct A(f32);
2665 #[derive(Component, Debug, Eq, PartialEq, Clone, Copy)]
2666 #[component(storage = "SparseSet")]
2667 struct Sparse(usize);
2668
2669 #[test]
2670 fn query_iter_sorts() {
2671 let mut world = World::new();
2672 for i in 0..100 {
2673 world.spawn(A(i as f32));
2674 world.spawn((A(i as f32), Sparse(i)));
2675 world.spawn(Sparse(i));
2676 }
2677
2678 let mut query = world.query::<Entity>();
2679
2680 let sort = query.iter(&world).sort::<Entity>().collect::<Vec<_>>();
2681 assert_eq!(sort.len(), 300);
2682
2683 let sort_unstable = query
2684 .iter(&world)
2685 .sort_unstable::<Entity>()
2686 .collect::<Vec<_>>();
2687
2688 let sort_by = query
2689 .iter(&world)
2690 .sort_by::<Entity>(Ord::cmp)
2691 .collect::<Vec<_>>();
2692
2693 let sort_unstable_by = query
2694 .iter(&world)
2695 .sort_unstable_by::<Entity>(Ord::cmp)
2696 .collect::<Vec<_>>();
2697
2698 let sort_by_key = query
2699 .iter(&world)
2700 .sort_by_key::<Entity, _>(|&e| e)
2701 .collect::<Vec<_>>();
2702
2703 let sort_unstable_by_key = query
2704 .iter(&world)
2705 .sort_unstable_by_key::<Entity, _>(|&e| e)
2706 .collect::<Vec<_>>();
2707
2708 let sort_by_cached_key = query
2709 .iter(&world)
2710 .sort_by_cached_key::<Entity, _>(|&e| e)
2711 .collect::<Vec<_>>();
2712
2713 let mut sort_v2 = query.iter(&world).collect::<Vec<_>>();
2714 sort_v2.sort();
2715
2716 let mut sort_unstable_v2 = query.iter(&world).collect::<Vec<_>>();
2717 sort_unstable_v2.sort_unstable();
2718
2719 let mut sort_by_v2 = query.iter(&world).collect::<Vec<_>>();
2720 sort_by_v2.sort_by(Ord::cmp);
2721
2722 let mut sort_unstable_by_v2 = query.iter(&world).collect::<Vec<_>>();
2723 sort_unstable_by_v2.sort_unstable_by(Ord::cmp);
2724
2725 let mut sort_by_key_v2 = query.iter(&world).collect::<Vec<_>>();
2726 sort_by_key_v2.sort_by_key(|&e| e);
2727
2728 let mut sort_unstable_by_key_v2 = query.iter(&world).collect::<Vec<_>>();
2729 sort_unstable_by_key_v2.sort_unstable_by_key(|&e| e);
2730
2731 let mut sort_by_cached_key_v2 = query.iter(&world).collect::<Vec<_>>();
2732 sort_by_cached_key_v2.sort_by_cached_key(|&e| e);
2733
2734 assert_eq!(sort, sort_v2);
2735 assert_eq!(sort_unstable, sort_unstable_v2);
2736 assert_eq!(sort_by, sort_by_v2);
2737 assert_eq!(sort_unstable_by, sort_unstable_by_v2);
2738 assert_eq!(sort_by_key, sort_by_key_v2);
2739 assert_eq!(sort_unstable_by_key, sort_unstable_by_key_v2);
2740 assert_eq!(sort_by_cached_key, sort_by_cached_key_v2);
2741 }
2742
2743 #[test]
2744 #[should_panic]
2745 fn query_iter_sort_after_next() {
2746 let mut world = World::new();
2747 world.spawn((A(0.),));
2748 world.spawn((A(1.1),));
2749 world.spawn((A(2.22),));
2750
2751 {
2752 let mut query = world.query::<&A>();
2753 let mut iter = query.iter(&world);
2754 println!(
2755 "archetype_entities: {} table_entities: {} current_len: {} current_row: {}",
2756 iter.cursor.archetype_entities.len(),
2757 iter.cursor.table_entities.len(),
2758 iter.cursor.current_len,
2759 iter.cursor.current_row
2760 );
2761 _ = iter.next();
2762 println!(
2763 "archetype_entities: {} table_entities: {} current_len: {} current_row: {}",
2764 iter.cursor.archetype_entities.len(),
2765 iter.cursor.table_entities.len(),
2766 iter.cursor.current_len,
2767 iter.cursor.current_row
2768 );
2769 println!("{}", iter.sort::<Entity>().len());
2770 }
2771 }
2772
2773 #[test]
2774 #[should_panic]
2775 fn query_iter_sort_after_next_dense() {
2776 let mut world = World::new();
2777 world.spawn((Sparse(11),));
2778 world.spawn((Sparse(22),));
2779 world.spawn((Sparse(33),));
2780
2781 {
2782 let mut query = world.query::<&Sparse>();
2783 let mut iter = query.iter(&world);
2784 println!(
2785 "before_next_call: archetype_entities: {} table_entities: {} current_len: {} current_row: {}",
2786 iter.cursor.archetype_entities.len(),
2787 iter.cursor.table_entities.len(),
2788 iter.cursor.current_len,
2789 iter.cursor.current_row
2790 );
2791 _ = iter.next();
2792 println!(
2793 "after_next_call: archetype_entities: {} table_entities: {} current_len: {} current_row: {}",
2794 iter.cursor.archetype_entities.len(),
2795 iter.cursor.table_entities.len(),
2796 iter.cursor.current_len,
2797 iter.cursor.current_row
2798 );
2799 println!("{}", iter.sort::<Entity>().len());
2800 }
2801 }
2802
2803 #[test]
2804 fn empty_query_iter_sort_after_next_does_not_panic() {
2805 let mut world = World::new();
2806 {
2807 let mut query = world.query::<(&A, &Sparse)>();
2808 let mut iter = query.iter(&world);
2809 println!(
2810 "before_next_call: archetype_entities: {} table_entities: {} current_len: {} current_row: {}",
2811 iter.cursor.archetype_entities.len(),
2812 iter.cursor.table_entities.len(),
2813 iter.cursor.current_len,
2814 iter.cursor.current_row
2815 );
2816 _ = iter.next();
2817 println!(
2818 "after_next_call: archetype_entities: {} table_entities: {} current_len: {} current_row: {}",
2819 iter.cursor.archetype_entities.len(),
2820 iter.cursor.table_entities.len(),
2821 iter.cursor.current_len,
2822 iter.cursor.current_row
2823 );
2824 println!("{}", iter.sort::<Entity>().len());
2825 }
2826 }
2827
2828 #[test]
2829 fn query_iter_cursor_state_non_empty_after_next() {
2830 let mut world = World::new();
2831 world.spawn((A(0.), Sparse(11)));
2832 world.spawn((A(1.1), Sparse(22)));
2833 world.spawn((A(2.22), Sparse(33)));
2834 {
2835 let mut query = world.query::<(&A, &Sparse)>();
2836 let mut iter = query.iter(&world);
2837 println!(
2838 "before_next_call: archetype_entities: {} table_entities: {} current_len: {} current_row: {}",
2839 iter.cursor.archetype_entities.len(),
2840 iter.cursor.table_entities.len(),
2841 iter.cursor.current_len,
2842 iter.cursor.current_row
2843 );
2844 assert!(iter.cursor.table_entities.len() | iter.cursor.archetype_entities.len() == 0);
2845 _ = iter.next();
2846 println!(
2847 "after_next_call: archetype_entities: {} table_entities: {} current_len: {} current_row: {}",
2848 iter.cursor.archetype_entities.len(),
2849 iter.cursor.table_entities.len(),
2850 iter.cursor.current_len,
2851 iter.cursor.current_row
2852 );
2853 assert!(
2854 (
2855 iter.cursor.table_entities.len(),
2856 iter.cursor.archetype_entities.len()
2857 ) != (0, 0)
2858 );
2859 }
2860 }
2861
2862 #[test]
2863 fn query_iter_many_sorts() {
2864 let mut world = World::new();
2865
2866 let entity_list: &Vec<_> = &world
2867 .spawn_batch([A(0.), A(1.), A(2.), A(3.), A(4.)])
2868 .collect();
2869
2870 let mut query = world.query::<Entity>();
2871
2872 let sort = query
2873 .iter_many(&world, entity_list)
2874 .sort::<Entity>()
2875 .collect::<Vec<_>>();
2876
2877 let sort_unstable = query
2878 .iter_many(&world, entity_list)
2879 .sort_unstable::<Entity>()
2880 .collect::<Vec<_>>();
2881
2882 let sort_by = query
2883 .iter_many(&world, entity_list)
2884 .sort_by::<Entity>(Ord::cmp)
2885 .collect::<Vec<_>>();
2886
2887 let sort_unstable_by = query
2888 .iter_many(&world, entity_list)
2889 .sort_unstable_by::<Entity>(Ord::cmp)
2890 .collect::<Vec<_>>();
2891
2892 let sort_by_key = query
2893 .iter_many(&world, entity_list)
2894 .sort_by_key::<Entity, _>(|&e| e)
2895 .collect::<Vec<_>>();
2896
2897 let sort_unstable_by_key = query
2898 .iter_many(&world, entity_list)
2899 .sort_unstable_by_key::<Entity, _>(|&e| e)
2900 .collect::<Vec<_>>();
2901
2902 let sort_by_cached_key = query
2903 .iter_many(&world, entity_list)
2904 .sort_by_cached_key::<Entity, _>(|&e| e)
2905 .collect::<Vec<_>>();
2906
2907 let mut sort_v2 = query.iter_many(&world, entity_list).collect::<Vec<_>>();
2908 sort_v2.sort();
2909
2910 let mut sort_unstable_v2 = query.iter_many(&world, entity_list).collect::<Vec<_>>();
2911 sort_unstable_v2.sort_unstable();
2912
2913 let mut sort_by_v2 = query.iter_many(&world, entity_list).collect::<Vec<_>>();
2914 sort_by_v2.sort_by(Ord::cmp);
2915
2916 let mut sort_unstable_by_v2 = query.iter_many(&world, entity_list).collect::<Vec<_>>();
2917 sort_unstable_by_v2.sort_unstable_by(Ord::cmp);
2918
2919 let mut sort_by_key_v2 = query.iter_many(&world, entity_list).collect::<Vec<_>>();
2920 sort_by_key_v2.sort_by_key(|&e| e);
2921
2922 let mut sort_unstable_by_key_v2 = query.iter_many(&world, entity_list).collect::<Vec<_>>();
2923 sort_unstable_by_key_v2.sort_unstable_by_key(|&e| e);
2924
2925 let mut sort_by_cached_key_v2 = query.iter_many(&world, entity_list).collect::<Vec<_>>();
2926 sort_by_cached_key_v2.sort_by_cached_key(|&e| e);
2927
2928 assert_eq!(sort, sort_v2);
2929 assert_eq!(sort_unstable, sort_unstable_v2);
2930 assert_eq!(sort_by, sort_by_v2);
2931 assert_eq!(sort_unstable_by, sort_unstable_by_v2);
2932 assert_eq!(sort_by_key, sort_by_key_v2);
2933 assert_eq!(sort_unstable_by_key, sort_unstable_by_key_v2);
2934 assert_eq!(sort_by_cached_key, sort_by_cached_key_v2);
2935 }
2936
2937 #[test]
2938 fn query_iter_many_sort_doesnt_panic_after_next() {
2939 let mut world = World::new();
2940
2941 let entity_list: &Vec<_> = &world
2942 .spawn_batch([A(0.), A(1.), A(2.), A(3.), A(4.)])
2943 .collect();
2944
2945 let mut query = world.query::<Entity>();
2946 let mut iter = query.iter_many(&world, entity_list);
2947
2948 _ = iter.next();
2949
2950 iter.sort::<Entity>();
2951
2952 let mut query_2 = world.query::<&mut A>();
2953 let mut iter_2 = query_2.iter_many_mut(&mut world, entity_list);
2954
2955 _ = iter_2.fetch_next();
2956
2957 iter_2.sort::<Entity>();
2958 }
2959
2960 // This test should be run with miri to check for UB caused by aliasing.
2961 // The lens items created during the sort must not be live at the same time as the mutable references returned from the iterator.
2962 #[test]
2963 fn query_iter_many_sorts_duplicate_entities_no_ub() {
2964 #[derive(Component, Ord, PartialOrd, Eq, PartialEq)]
2965 struct C(usize);
2966
2967 let mut world = World::new();
2968 let id = world.spawn(C(10)).id();
2969 let mut query_state = world.query::<&mut C>();
2970
2971 {
2972 let mut query = query_state.iter_many_mut(&mut world, [id, id]).sort::<&C>();
2973 while query.fetch_next().is_some() {}
2974 }
2975 {
2976 let mut query = query_state
2977 .iter_many_mut(&mut world, [id, id])
2978 .sort_unstable::<&C>();
2979 while query.fetch_next().is_some() {}
2980 }
2981 {
2982 let mut query = query_state
2983 .iter_many_mut(&mut world, [id, id])
2984 .sort_by::<&C>(|l, r| Ord::cmp(l, r));
2985 while query.fetch_next().is_some() {}
2986 }
2987 {
2988 let mut query = query_state
2989 .iter_many_mut(&mut world, [id, id])
2990 .sort_unstable_by::<&C>(|l, r| Ord::cmp(l, r));
2991 while query.fetch_next().is_some() {}
2992 }
2993 {
2994 let mut query = query_state
2995 .iter_many_mut(&mut world, [id, id])
2996 .sort_by_key::<&C, _>(|d| d.0);
2997 while query.fetch_next().is_some() {}
2998 }
2999 {
3000 let mut query = query_state
3001 .iter_many_mut(&mut world, [id, id])
3002 .sort_unstable_by_key::<&C, _>(|d| d.0);
3003 while query.fetch_next().is_some() {}
3004 }
3005 {
3006 let mut query = query_state
3007 .iter_many_mut(&mut world, [id, id])
3008 .sort_by_cached_key::<&C, _>(|d| d.0);
3009 while query.fetch_next().is_some() {}
3010 }
3011 }
3012}