Merge `Vec::push_mut_within_capacity` and `Vec::push_within_capacity`

[WaffleLapkin]

Proposal

Problem statement

rust-lang/rust#135974 is tracking the addition of push-like methods which return a reference to the pushed element. We had to add separate methods for this, since the () returning versions were stable for a while now. However, push_within_capacity is unstable and could be changed.

Current signatures:

impl<T> Vec<T> {
    #[unstable(feature = "vec_push_within_capacity", issue = "100486")]
    pub fn push_within_capacity(&mut self, value: T) -> Result<(), T>;

    #[unstable(feature = "push_mut", issue = "135974")]
    // #[unstable(feature = "vec_push_within_capacity", issue = "100486")]
    #[must_use = "if you don't need a reference to the value, use `Vec::push_within_capacity` instead"]
    pub fn push_mut_within_capacity(&mut self, value: T) -> Result<&mut T, T>;
}

Motivating examples or use cases

Solution sketch

Change the signature of push_within_capacity to return Result<&mut T, T>, remove push_mut_within_capacity:

impl<T> Vec<T> {
    #[unstable(feature = "vec_push_within_capacity", issue = "100486")]
    pub fn push_within_capacity(&mut self, value: T) -> Result<&mut T, T>;
}

Alternatives

Leave methods separate as-is.

Links and related work

• Comment proposing this on the tracking issue: Tracking Issue for Vec::push_mut rust#135974 (comment)
• ACP lead to push_mut, etc being added: Add Vec::last_or_push and friends #465

What happens now?

This issue contains an API change proposal (or ACP) and is part of the libs-api team feature lifecycle. Once this issue is filed, the libs-api team will review open proposals as capability becomes available. Current response times do not have a clear estimate, but may be up to several months.

Possible responses

The libs team may respond in various different ways. First, the team will consider the problem (this doesn't require any concrete solution or alternatives to have been proposed):

• We think this problem seems worth solving, and the standard library might be the right place to solve it.
• We think that this probably doesn't belong in the standard library.

Second, if there's a concrete solution:

• We think this specific solution looks roughly right, approved, you or someone else should implement this. (Further review will still happen on the subsequent implementation PR.)
• We're not sure this is the right solution, and the alternatives or other materials don't give us enough information to be sure about that. Here are some questions we have that aren't answered, or rough ideas about alternatives we'd want to see discussed.

[Amanieu]

Discussed and immediately accepted in the @rust-lang/libs-api meeting!