Added example of entity sorting by components (#1817)

We discussed with @alice-i-cecile privately on iterators and agreed that making a custom ordered iterator over query makes no sense since materialization is required anyway and it's better to reuse existing components or code. Therefore, just adding an example to the documentation as requested.

Fixes #1470.

Co-authored-by: Carter Anderson <[email protected]>

Author: YohDeadfall

crates/bevy_ecs/src/world/mod.rs

@@ -444,6 +444,26 @@ impl World {
     /// assert_eq!(world.get::<Position>(entities[0]).unwrap(), &Position { x: 1.0, y: 0.0 });
     /// assert_eq!(world.get::<Position>(entities[1]).unwrap(), &Position { x: 0.0, y: 1.0 });
     /// ```
+    ///
+    /// To iterate over entities in a deterministic order,
+    /// sort the results of the query using the desired component as a key.
+    /// Note that this requires fetching the whole result set from the query
+    /// and allocation of a [Vec] to store it.
+    ///
+    /// ```
+    /// use bevy_ecs::{entity::Entity, world::World};
+    /// let mut world = World::new();
+    /// let a = world.spawn().insert_bundle((2, 4.0)).id();
+    /// let b = world.spawn().insert_bundle((3, 5.0)).id();
+    /// let c = world.spawn().insert_bundle((1, 6.0)).id();
+    /// let mut entities = world.query::<(Entity, &i32, &f64)>()
+    ///     .iter(&world)
+    ///     .collect::<Vec<_>>();
+    /// // Sort the query results by their `i32` component before comparing
+    /// // to expected results. Query iteration order should not be relied on.
+    /// entities.sort_by_key(|e| e.1);
+    /// assert_eq!(entities, vec![(c, &1, &6.0), (a, &2, &4.0), (b, &3, &5.0)]);
+    /// ```
     #[inline]
     pub fn query<Q: WorldQuery>(&mut self) -> QueryState<Q, ()> {
         QueryState::new(self)