add .include_entity() helper on query iterators

[Nathan-Fenner]

Objective

Adds a helper method to the QueryIter struct called .include_entity(), which automatically adds (Entity, _) around whatever is currently being iterated. Since the underlying Entity is always tracked anyway, this can be done "for free" at zero additional runtime cost.

This helper makes it more ergonomic to evolve systems over time. For example, as we write a complex system, we encounter a case where we need the Entity that we're iterating over:

fn example(q_data: Query<(&mut Player, &Transform, &Health)>) {
   for (player, transform, _health) in q_data.iter() {
       do_thing1(player, transform);
    }

   for (mut player, transform, health) in q_data.iter_mut() {
       do_thing2(player, transform, health);
    }

   for (mut player, transform, _health) in q_data.iter() {
       do_thing3(todo!() /* need entity! */, player, transform);
    }
}

Despite the Entity already being tracked at runtime, we then need to go back and update multiple lines of code to request it:

fn example(q_data: Query<(Entity, &mut Player, &Transform, &Health)>) {   // changed
   for (_entity, player, transform, _health) in q_data.iter() {           // changed
       do_thing1(player, transform);
    }

   for (_entity, mut player, transform, _health) in q_data.iter_mut() {   // changed
       do_thing2(player, transform, health);
    }

   for (entity, mut player, transform, _health) in q_data.iter_mut() {    // changed
       do_thing3(entity, player, transform);                              // changed
    }
}

Of the 5 changed lines, only the last 2 are essential to the change we actually want to make. If we use include_entity() instead, then we get the much-more-explicit delta:

fn example(q_data: Query<(&mut Player, &Transform, &Health)>) {
   for (player, transform, _health) in q_data.iter() {
       do_thing1(player, transform);
    }

   for (mut player, transform, _health) in q_data.iter_mut() {
       do_thing2(player, transform, health);
    }

   for (entity, (mut player, transform, _health)) in q_data.iter_mut().include_entity() { // changed
       do_thing3(entity, player, transform);                                              // changed
    }
}

Testing

• Needs tests before merging

[Nathan-Fenner]

I consider this a better alternative to a previous PR I opened at #13764, which might be independently useful but is not as general

[hymm]

Definitely prefer this pr to the previous one as the call to transmute_lens in that pr allocates.

I lean towards not wanting this functionality as I prefer the simplicity of having only one way of adding entity to a query. But I don't feel too strongly about it if someone really wants it.