Struct RawVec

pub(crate) struct RawVec<T, A: Allocator = Global> {
    inner: RawVecInner<A>,
    _marker: PhantomData<T>,
}

🔬This is a nightly-only experimental API. (raw_vec_internals)

A low-level utility for more ergonomically allocating, reallocating, and deallocating a buffer of memory on the heap without having to worry about all the corner cases involved. This type is excellent for building your own data structures like Vec and VecDeque. In particular:

• Produces Unique::dangling() on zero-sized types.
• Produces Unique::dangling() on zero-length allocations.
• Avoids freeing Unique::dangling().
• Catches all overflows in capacity computations (promotes them to “capacity overflow” panics).
• Guards against 32-bit systems allocating more than isize::MAX bytes.
• Guards against overflowing your length.
• Calls handle_alloc_error for fallible allocations.
• Contains a ptr::Unique and thus endows the user with all related benefits.
• Uses the excess returned from the allocator to use the largest available capacity.

This type does not in anyway inspect the memory that it manages. When dropped it will free its memory, but it won’t try to drop its contents. It is up to the user of RawVec to handle the actual things stored inside of a RawVec.

Note that the excess of a zero-sized types is always infinite, so capacity() always returns usize::MAX. This means that you need to be careful when round-tripping this type with a Box<[T]>, since capacity() won’t yield the length.

Fields

inner: RawVecInner<A>

🔬This is a nightly-only experimental API. (raw_vec_internals)

_marker: PhantomData<T>

🔬This is a nightly-only experimental API. (raw_vec_internals)

Implementations

impl<T> RawVec<T, Global>

pub(crate) const fn new() -> Self

🔬This is a nightly-only experimental API. (raw_vec_internals)

Creates the biggest possible RawVec (on the system heap) without allocating. If T has positive size, then this makes a RawVec with capacity 0. If T is zero-sized, then it makes a RawVec with capacity usize::MAX. Useful for implementing delayed allocation.

pub(crate) fn with_capacity(capacity: usize) -> Self

🔬This is a nightly-only experimental API. (raw_vec_internals)

Creates a RawVec (on the system heap) with exactly the capacity and alignment requirements for a [T; capacity]. This is equivalent to calling RawVec::new when capacity is 0 or T is zero-sized. Note that if T is zero-sized this means you will not get a RawVec with the requested capacity.

Non-fallible version of try_with_capacity

Panics

Panics if the requested capacity exceeds isize::MAX bytes.

Aborts

Aborts on OOM.

pub(crate) fn with_capacity_zeroed(capacity: usize) -> Self

🔬This is a nightly-only experimental API. (raw_vec_internals)

Like with_capacity, but guarantees the buffer is zeroed.

impl<T, A: Allocator> RawVec<T, A>

pub(crate) const MIN_NON_ZERO_CAP: usize

🔬This is a nightly-only experimental API. (raw_vec_internals)

pub(crate) const fn new_in(alloc: A) -> Self

🔬This is a nightly-only experimental API. (raw_vec_internals)

Like new, but parameterized over the choice of allocator for the returned RawVec.

pub(crate) fn with_capacity_in(capacity: usize, alloc: A) -> Self

🔬This is a nightly-only experimental API. (raw_vec_internals)

Like with_capacity, but parameterized over the choice of allocator for the returned RawVec.

pub(crate) fn try_with_capacity_in( capacity: usize, alloc: A, ) -> Result<Self, TryReserveError>

🔬This is a nightly-only experimental API. (raw_vec_internals)

Like try_with_capacity, but parameterized over the choice of allocator for the returned RawVec.

pub(crate) fn with_capacity_zeroed_in(capacity: usize, alloc: A) -> Self

🔬This is a nightly-only experimental API. (raw_vec_internals)

Like with_capacity_zeroed, but parameterized over the choice of allocator for the returned RawVec.

pub(crate) unsafe fn into_box(self, len: usize) -> Box<[MaybeUninit<T>], A>

🔬This is a nightly-only experimental API. (raw_vec_internals)

Converts the entire buffer into Box<[MaybeUninit<T>]> with the specified len.

Note that this will correctly reconstitute any cap changes that may have been performed. (See description of type for details.)

Safety

• len must be greater than or equal to the most recently requested capacity, and
• len must be less than or equal to self.capacity().

Note, that the requested capacity and self.capacity() could differ, as an allocator could overallocate and return a greater memory block than requested.

pub(crate) unsafe fn from_raw_parts_in( ptr: *mut T, capacity: usize, alloc: A, ) -> Self

🔬This is a nightly-only experimental API. (raw_vec_internals)

Reconstitutes a RawVec from a pointer, capacity, and allocator.

Safety

The ptr must be allocated (via the given allocator alloc), and with the given capacity. The capacity cannot exceed isize::MAX for sized types. (only a concern on 32-bit systems). For ZSTs capacity is ignored. If the ptr and capacity come from a RawVec created via alloc, then this is guaranteed.

pub(crate) unsafe fn from_nonnull_in( ptr: NonNull<T>, capacity: usize, alloc: A, ) -> Self

🔬This is a nightly-only experimental API. (raw_vec_internals)

A convenience method for hoisting the non-null precondition out of RawVec::from_raw_parts_in.

Safety

See RawVec::from_raw_parts_in.

pub(crate) const fn ptr(&self) -> *mut T

🔬This is a nightly-only experimental API. (raw_vec_internals)

Gets a raw pointer to the start of the allocation. Note that this is Unique::dangling() if capacity == 0 or T is zero-sized. In the former case, you must be careful.

pub(crate) fn non_null(&self) -> NonNull<T>

🔬This is a nightly-only experimental API. (raw_vec_internals)

pub(crate) const fn capacity(&self) -> usize

🔬This is a nightly-only experimental API. (raw_vec_internals)

Gets the capacity of the allocation.

This will always be usize::MAX if T is zero-sized.

pub(crate) fn allocator(&self) -> &A

🔬This is a nightly-only experimental API. (raw_vec_internals)

Returns a shared reference to the allocator backing this RawVec.

pub(crate) fn reserve(&mut self, len: usize, additional: usize)

🔬This is a nightly-only experimental API. (raw_vec_internals)

Ensures that the buffer contains at least enough space to hold len + additional elements. If it doesn’t already have enough capacity, will reallocate enough space plus comfortable slack space to get amortized O(1) behavior. Will limit this behavior if it would needlessly cause itself to panic.

If len exceeds self.capacity(), this may fail to actually allocate the requested space. This is not really unsafe, but the unsafe code you write that relies on the behavior of this function may break.

This is ideal for implementing a bulk-push operation like extend.

Panics

Panics if the new capacity exceeds isize::MAX bytes.

Aborts

Aborts on OOM.

pub(crate) fn grow_one(&mut self)

🔬This is a nightly-only experimental API. (raw_vec_internals)

A specialized version of self.reserve(len, 1) which requires the caller to ensure len == self.capacity().

pub(crate) fn try_reserve( &mut self, len: usize, additional: usize, ) -> Result<(), TryReserveError>

🔬This is a nightly-only experimental API. (raw_vec_internals)

The same as reserve, but returns on errors instead of panicking or aborting.

pub(crate) fn reserve_exact(&mut self, len: usize, additional: usize)

🔬This is a nightly-only experimental API. (raw_vec_internals)

Ensures that the buffer contains at least enough space to hold len + additional elements. If it doesn’t already, will reallocate the minimum possible amount of memory necessary. Generally this will be exactly the amount of memory necessary, but in principle the allocator is free to give back more than we asked for.

If len exceeds self.capacity(), this may fail to actually allocate the requested space. This is not really unsafe, but the unsafe code you write that relies on the behavior of this function may break.

Panics

Panics if the new capacity exceeds isize::MAX bytes.

Aborts

Aborts on OOM.

pub(crate) fn try_reserve_exact( &mut self, len: usize, additional: usize, ) -> Result<(), TryReserveError>

🔬This is a nightly-only experimental API. (raw_vec_internals)

The same as reserve_exact, but returns on errors instead of panicking or aborting.

pub(crate) fn shrink_to_fit(&mut self, cap: usize)

🔬This is a nightly-only experimental API. (raw_vec_internals)

Shrinks the buffer down to the specified capacity. If the given amount is 0, actually completely deallocates.

Panics

Panics if the given amount is larger than the current capacity.

Aborts

Aborts on OOM.

Trait Implementations

impl<T, A: Allocator> Drop for RawVec<T, A>

fn drop(&mut self)

Frees the memory owned by the RawVec without trying to drop its contents.