Add a variant of Events::update that returns the removed events

[JoJoJet]

Objective

Every frame, Events::update gets called, which clears out any old events from the buffer. There should be a way of taking ownership of these old events instead of throwing them away. My use-case is dumping old events into a debug menu so they can be inspected later.

One potential workaround is to just have a system that clones any incoming events and stores them in a list -- however, this requires the events to implement Clone.

Solution

Add Events::update_drain, which returns an iterator of the events that were removed from the buffer.

[alice-i-cecile]

I'd like a bit of reassurance that this compiles down to the same code as a naive "duplicate the code" solution, but I won't block on it.

A doc test would be good too.

[JoJoJet]

I'd like a bit of reassurance that this compiles down to the same code as a naive "duplicate the code" solution, but I won't block on it.

Calling .drain() doesn't actually move any memory around. All of the drained elements remain the vector's original buffer, until they get removed by Iterator::next. When the iterator gets dropped, any unyielded elements get dropped (if you're only draining part of the iterator, any un-drained elements at the end get ptr::copy-ed back into place at this point. Since we're draining the entire vec with .., this step gets skipped). So, if you call .drain(..) and then drop the returned iterator, it doesn't do any more actual work than calling .clear(), save for some cheap glue code that should be trivial to optimize away.

I will add a test or two.

[alice-i-cecile]

@JoJoJet this needs to have merge conflicts resolved, then I'll merge :)