Repository: rust
Issue: Tracking Issue for `vec::Drain{,Filter}::keep_rest`
Labels: T-libs-api,C-tracking-issue

<!--
Thank you for creating a tracking issue!

Tracking issues are for tracking a feature from implementation to stabilization.

Make sure to include the relevant RFC for the feature if it has one.

If the new feature is small, it may be fine to skip the RFC process. In that
case, you can use use `issue = "none"` in your initial implementation PR. The
reviewer will ask you to open a tracking issue if they agree your feature can be
added without an RFC.
-->

Feature gate: `#![feature(drain_keep_rest)]`

This is a tracking issue for `vec::Drain::keep_rest`, methods allowing to keep elements in a `Vec` after draining some of them.

<!--
Include a short description of the feature.
-->

### Public API

<!--
For most library features, it'd be useful to include a summarized version of the public API.
(E.g. just the public function signatures without their doc comments or implementation.)
-->

```rust
// mod alloc::vec

impl<T, A: Allocator> Drain<'_, T, A> {
    pub fn keep_rest(self);
}
```

### Steps / History

<!--
For larger features, more steps might be involved.
If the feature is changed later, please add those PRs here as well.
-->

- [x] Implementation: #95376
- [ ] Final comment period (FCP)[^1]
- [ ] Stabilization PR

<!--
Once the feature has gone through a few release cycles and there are no
unresolved questions left, the feature might be ready for stabilization.

If this feature didn't go through the RFC process, a final comment period
(FCP) is always needed before stabilization. This works as follows:

A library API team member can kick off the stabilization process, at which point
the rfcbot will ask all the team members to verify they agree with
stabilization. Once enough members agree and there are no concerns, the final
comment period begins: this issue will be marked as such and will be listed
in the next This Week in Rust newsletter. If no blocking concerns are raised in
that period of 10 days, a stabilzation PR can be opened by anyone.
-->

### Unresolved Questions

<!--
Include any open questions that need to be answered before the feature can be
stabilised. If multiple (unrelated) big questions come up, it can be a good idea
to open a separate issue for each, to make it easier to keep track of the
discussions.

It's useful to link any relevant discussions and conclusions (whether on GitHub,
Zulip, or the internals forum) here.
-->
- Just change the not-yet-stable Drop for DrainFilter to keep rest?
  - Advantage: usually what you want (??)
    - e.g. `.drain_filter(f).take(N)` works as expected
  - Disadvantage: inconsistent with stable `Drop` for `Drain`
  - If you want to remove rest (matching the current unstable behavior of `drain_filter`) then you'd need to write `.foreach(drop)` to explicitly drop all the rest of the range that matches the filter.
- `&mut self` instead of `self`?
  - If you're holding a `Drain` inside a struct and are operating on it from a `&mut self` method of the struct, `keep_rest(self)` is impossible to use. :(
    - You'd want something like `mem::replace(&mut self.drain_filter, Vec::new().drain(..)).keep_rest()` but the borrow checker won't like that.
    - Failing that, you'd need to change your `Drain` field to `Option<Drain>` and use `self.drain_filter.take().unwrap().keep_rest()` along with `unwrap()` everywhere else that the drain is used. Not good.
  - We'd need to define behavior of calling .next() after .keep_rest(). Presumably one of:
    - `.next()` returns `None`
    - this is considered incorrect usage and so `.next()` `panic!`s
    - `.keep_rest()` sets a flag inside the `Drain` which `Drop` will use to decide its behavior, and you're free to continue accessing iterator elements in between.
  - Another alternative: add a `const EXHAUST_ON_DROP: bool = true` const generic parameter
    - It's still impossible to set the flag without ownership
    - You can store `&mut Drain<'a, T, A, false>` from the beginning
    - Works better with iterator APIs, i.e.
       ```rust
       vec.drain_filter(f).keeping_rest().take(N).for_each(g);
       ```
       Instead of
       ```rust
       let mut iter = vec.drain_filter(f);
       iter.by_ref().take(N).for_each(g);
       iter.keep_rest()
       ```

[^1]: https://std-dev-guide.rust-lang.org/feature-lifecycle/stabilization.html