Tracking Issue for `Vec::push_mut`

[balt-dev]

Feature gate: #![feature(push_mut)]

This is a tracking issue for Vec::push_mut and similar methods, as discussed in the comments of this ACP. This adds a way to get a reference to the just-pushed value, which can eliminate having to .unwrap() or access the back of the list twice.

Public API

// All are `#[must_use]` to suggest using `.push(...)` if you don't need the reference

impl<T> Vec<T> {
    #[must_use]
    pub fn push_mut(&mut self, value: T) -> &mut T;
    #[must_use]
    pub fn insert_mut(&mut self, index: usize, element: T) -> &mut T;
    #[must_use]
    pub fn push_mut_within_capacity(&mut self, value: T) -> Result<&mut T, T>;
}

impl<T> VecDeque<T> {
    #[must_use]
    pub fn push_front_mut(&mut self, value: T) -> &mut T;
    #[must_use]
    pub fn push_back_mut(&mut self, value: T) -> &mut T;
    #[must_use]
    pub fn insert_mut(&mut self, index: usize, value: T) -> &mut T;
}

impl<T> LinkedList<T> {
    #[must_use]
    pub fn push_front_mut(&mut self, elt: T) -> &mut T;
    #[must_use]
    pub fn push_back_mut(&mut self, elt: T) -> &mut T
}

Steps / History

• Implementation: Implement push_mut #135975
• Final comment period (FCP)
• Stabilization PR

Unresolved Questions

• Does must_use make sense? Are there downsides of push_mut vs. push?

[balt-dev]

Here's an example from the documentation:

#![feature(push_mut)]

let mut vec = vec![];
// Polonius moment.
let last = if let Some(v) = vec.last_mut() { v } else { vec.push_mut(0) };
*last += 6;
assert_eq!(vec, [6]);

[balt-dev]

(Note: I did go back and change the // Polonius moment. comment to something more descriptive.)

[balt-dev]

Thoughts on an unsafe push_raw that returns a *mut T?
Actually, wait, that's unnecessary since you can just downgrade the reference to a pointer in all cases.

[balt-dev]

I saw @traviscross talking about a push_ref in rust-lang/rfcs#3712, and... that's not really necessary?
It needs to be &mut self to push, and an &mut T can always just be coerced to a &T anyways.

[traviscross]

It was just a citation handle in a parenthetical, not a proposal.