[Merged by Bors] - Added example of entity sorting by components

crates/bevy_ecs/src/world/mod.rs

@@ -444,6 +444,32 @@ 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 it 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, &f32)>()
+    ///     .iter(&world)
+    ///     .collect::<Vec<_>>();
+    /// // Sort by `i32` component
+    /// entities.sort_by(|x, y| x.1.cmp(&y.1));
+    /// for (index, entity) in entities.iter().enumerate() {
+    ///     match index {
+    ///         0 => assert_eq!(entity, &(c, &1, &6.0)),
+    ///         1 => assert_eq!(entity, &(a, &2, &4.0)),
+    ///         2 => assert_eq!(entity, &(b, &3, &5.0)),
+    ///         _ => panic!("not expected"),
+    ///     }
+    /// }
+    /// ```
     #[inline]
     pub fn query<Q: WorldQuery>(&mut self) -> QueryState<Q, ()> {
         QueryState::new(self)