Add Vec::retain_mut

[jonas-schievink]

Take 2 of #34265, since I needed this today.

[rust-highfive]

r? @Mark-Simulacrum

(rust-highfive has picked a reviewer for you, use r? to override)

[Mark-Simulacrum]

I think the interaction with drain_filter and the (to me) very similar API surface is interesting here; I'm not sure whether one is definitively easier than the other to stabilize, and while both are unstable it feels like drain_filter already gives basically the same API? (Potentially at higher cost but hopefully not...)

r? @m-ou-se for T-libs member approval of unstable API

[m-ou-se]

@jonas-schievink I'd like to hear your opinion on the (unstable) drain_filter as an alternative, since this already works:

#![feature(drain_filter)]

let mut vec = vec![1, 2, 3, 4];
vec.drain_filter(|x| if *x > 3 {
    true
} else {
    *x += 1;
    false
});
assert_eq!(vec, [2, 3, 4]);

That function is still unstable, so if there is a specific reason you don't consider it suitable for this use case, maybe we can come up with a way to change it such that it would suffice.

[jonas-schievink]

Yeah, drain_filter would work as well here, that's true. I don't think there's any reason retain_mut would be required there.

[m-ou-se]

@jonas-schievink So, should we close this? Or is there a reason you'd still prefer retain_mut over drain_filter?

[jonas-schievink]

Yeah, I guess let's close

[GuillaumeGomez]

I would love to have retain_mut because in my case, I'm not interested by the removed items. Would it be fine to re-open this PR or should I open another one (with this code I think, doesn't seem to need to have something else). Or do I need to open an issue or something along the line before?

[Mark-Simulacrum]

Even if you don't need the removed items, drain_filter still provides a near-equivalent API, so it's not clear that it's any worse to me. Having two APIs doing the same thing with slightly different interfaces seems worse, though.

That said, I think just a new PR here is fine, if you want to discuss that.

[GuillaumeGomez]

Well, it would be coherent with the rest. For example we have chunks and chunks_mut or get and get_mut or iter and iter_mut, etc. When looking for mutable retain, I would expect retain_mut to exist. It took me a while to find out about drain_filter. So even if it provides an API close to drain_filter, just for the discoverability, I think it's worth it.