Make Vec::split_at_spare_mut public

[WaffleLapkin]

This PR introduces a new method to the public API, under
vec_split_at_spare feature gate:

impl<T, A: Allocator> impl Vec<T, A> {
    pub fn split_at_spare_mut(&mut self) -> (&mut [T], &mut [MaybeUninit<T>]);
}

The method returns 2 slices, one slice references the content of the vector,
and the other references the remaining spare capacity.

The method was previously implemented while adding Vec::extend_from_within in #79015,
and used to implement Vec::spare_capacity_mut (as the later is just a
subset of former one).

See also previous discussion in Vec::spare_capacity_mut tracking issue.

Unresolved questions

• Should we consider changing the name? split_at_spare_mut doesn't seem like an intuitive name
• Should we deprecate Vec::spare_capacity_mut? Any usecase of Vec::spare_capacity_mut can be replaced with Vec::split_at_spare_mut (but not vise-versa)

r? @KodrAus

[KodrAus]

Thanks @WaffleLapkin! It might be worth noting that this is a low-level API, and if all you want to do is append data to a Vec you can use push, extend etc.

[WaffleLapkin]

ping @KodrAus I've addressed your comment.

[KodrAus]

@bors r+ rollup

[bors]

📌 Commit 8ff7b75 has been approved by KodrAus

[kornelski]

🚲

I think this can replace spare_capacity_mut entirely, even reuse the same name.

It would be good if the function had capacity in its name, because spare alone isn't used anywhere else in Vec's docs, so it isn't part of the vocabulary.

Vec has split_off, so another split_ method that doesn't modify the Vec is slightly confusing.

[WaffleLapkin]

Yeah, I agree that it would be better to just have one method for getting spare capacity.

Though I'm not sure how to discuss this replacement properly...