Tracking Issue for `Vec::peek_mut`

[avandesa]

Feature gate: #![feature(vec_peek_mut)]

This feature adds Vec::peek_mut, which returns a PeekMut struct. It is analogous to [BinaryHeap::peek_mut] and enables users to conditionally modify and remove the last element of a Vec without having to call unwrap.

Public API

impl<T> Vec<T> {
    pub fn peek_mut(&mut self) -> Option<PeekMut<'_, T>>;
}

pub struct PeekMut<'a, T>;

impl<'a, T> PeekMut<'a, T> {
    pub fn pop(self) -> T;
}

// impl `Deref`/`DerefMut` for `PeekMut`

Steps / History

• ACP: pop_if or Entry/Peek-like API for Vec and VecDeque libs-team#208
• Implementation: pending
• Final comment period (FCP)¹
• Stabilization PR

Unresolved Questions

• Should this be named peek or peek_mut?

Footnotes

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

[GrigorenkoPV]

Even though FCP has not started yet, I would like to express a couple of concerns regarding the name. I am not very pleased with either peek or peek_mut for two reasons:

1. All the other std APIs with peek in name usually revolve around Option<&T> and not an Entry-style API similar to Map's Entry.
2. The name does not reflect which element it operates on. After some thinking you can probably guess that it means the last element for Vec, similarly to push and pop, but I would argue that peek sounds closer to get, which is not tied to a specific position.

I would personally prefer something along the lines of "last_entry".

[alex-700]

The BinaryHeap's PeekMut::pop has this-named parameter on puprose. See comment for the reason.

Should we avoid the same problem here in Vec's PeekMut::pop?