Tracking Issue for `alloc::collections::fallible::Vec`

Feature gate: #![feature(fallible_vec)]

This is a tracking issue for alloc::collections::fallible::Vec. A Vec that can fail to allocate.

Public API

It is intended that the API eventually match Vec but for now it implements a smaller MVP.

// alloc::collections::fallible

// FIXME: figure out the error type we want.
// TryReserveError is what's used internally at the moment.
// We may want to use an associated type on Allocator instead. Or something else.
// Or we could make TryReserveError alias to something with a more appropriate name.
type AllocError = TryReserveError;

// ABI compatible with alloc::vec::Vec.
pub struct Vec<T, A: Allocator = Global>{ ,,, }
impl<T> Vec<T> {
    pub const fn new() -> Vec<T>
    pub fn with_capacity(capacity: usize) -> Result<Vec<T>, AllocError>
    pub const unsafe fn from_raw_parts(ptr: *mut T, length: usize, capacity: usize) -> Vec<T>
}

impl<T, A: Allocator> Vec<T, A> {
    // These are new
    pub const fn to_infallible(self) -> alloc::vec::Vec<T, A>
    pub fn with_capacity_in(capacity: usize, alloc: A) -> Result<Vec<T, A>, AllocError>
    pub fn reserve(&mut self, additional: usize) -> Result<(), AllocError>
    pub fn reserve_exact(&mut self, additional: usize) -> Result<(), AllocError>
    pub fn shrink_to_fit(&mut self) -> Result<(), AllocError>
    pub fn shrink_to(&mut self, min_capacity: usize) -> Result<(), AllocError>
    pub fn push(&mut self, value: T) -> Result<(), AllocError>
    pub fn push_mut(&mut self, value: T) -> Result<&mut T, AllocError>

    // These should match alloc::vec::Vec exactly
    pub const fn new_in(alloc: A) -> Vec<T, A>
    pub const unsafe fn from_raw_parts_in(ptr: *mut T, length: usize, capacity: usize, alloc: A) -> Vec<T, A>
    pub const fn into_raw_parts_with_alloc(self) -> (*mut T, usize, usize, A)
    pub const fn capacity(&self) -> usize
    pub fn truncate(&mut self, len: usize)
    pub const fn as_slice(&self) -> &[T];
    pub const fn as_mut_slice(&mut self) -> &mut [T];
    pub const fn as_ptr(&self) -> *const T
    pub const fn as_mut_ptr(&mut self) -> *mut T
    pub unsafe fn set_len(&mut self, new_len: usize)
    pub fn pop(&mut self) -> Option<T>
    pub fn pop_if(&mut self, predicate: impl FnOnce(&mut T) -> bool) -> Option<T>
    pub fn clear(&mut self)
    pub const fn len(&self) -> usize
    pub const fn is_empty(&self) -> bool
    pub fn leak<'a>(self) -> &'a mut [T];
    pub fn spare_capacity_mut(&mut self) -> &mut [MaybeUninit<T>]
}

And on vec::Vec:

// in alloc::vec
impl<T, A: Allocator> Vec<T, A> {
    pub const fn to_fallible(self) -> alloc::collections::fallible::Vec<T, A>
}

Steps / History

(Remember to update the S-tracking-* label when checking boxes.)

• ACP: https://github.com/rust-lang/libs-team/issues/798
• Implementation: #...
• Final comment period (FCP)^1
• Stabilization PR

Unresolved Questions

• What should the error type be?
• Should we exactly replicate the Vec API, including Try versions of traits (i.e. TryExtend, TryFromIterator)
• How should we keep alloc::vec::Vec and fallible::Vec in sync with each other?
• Figure out diagnostics. This type should not take precedence in situations where alloc::vec::Vec would be more appropriate (which is most of the time).

Read the proposed public API and unresolved questions in this issue, then review the ACP at rust-lang/libs-team#798 before choosing a bounded implementation task. Done is not yet defined: implementation, API and error-type decisions, synchronization with alloc::vec::Vec, diagnostics, FCP, and stabilization remain open.