Add Events<T>::retain implementation through existing drain with send_batch

[GMcMichael]

Objective

• Addresses open issue #12204 'Add Events::retain'
• Sometimes it's useful to not drain all events from Events, but by a specific predicate.
• There is Vec::retain and it would be convenient to have something like this in Events too.
• Allow code reuse by unifying it into the repository

Solution

I added Events<T>::retain(predicate: Fn(&Event) -> bool) to bevy_ecs/src/event/collections.rs. It uses the existing Events::drain along with Iterator::partition to filter the events into two vectors with the passed predicate. The ‘kept’ events are resent back into the queue with Events::send_batch() as it is more efficient than using send individually.

A more optimized solution would modify the queue in place without breaking the cursor position of any instanced EventReaders but I am unsure if that is possible without simply replacing the 'filtered' events with a 'None' or similar. Any input or criticism would be appreciated!

Testing

I did some testing to validate the logic would work, but might need some help with whether I should include examples or tests for this.

[github-actions]

Welcome, new contributor!

Please make sure you've read our contributing guide and we look forward to reviewing your pull request shortly ✨

[alice-i-cecile]

Can you also expose this method on EventMutator? :) Good idea and clean implementation though.