Struct RawVec

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

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:

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>
_marker: PhantomData<T>

Implementations

impl<T> RawVec<T, Global>

const fn new() -> Self

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.

fn with_capacity(capacity: usize) -> Self

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.

fn with_capacity_zeroed(capacity: usize) -> Self

Like with_capacity, but guarantees the buffer is zeroed.

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

const MIN_NON_ZERO_CAP: usize = _;
const fn new_in(alloc: A) -> Self

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

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

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

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

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

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

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.

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

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.

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

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

Safety

See RawVec::from_raw_parts_in.

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

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.

const fn non_null(&self) -> NonNull<T>
const fn capacity(&self) -> usize

Gets the capacity of the allocation.

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

const fn allocator(&self) -> &A

Returns a shared reference to the allocator backing this RawVec.

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

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.

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

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

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

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.

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

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

fn shrink_to_fit(&mut self, cap: usize)

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.

fn try_shrink_to_fit(&mut self, cap: usize) -> Result<(), TryReserveError>

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

Errors

This function returns an error if the allocator cannot shrink the allocation.

Panics

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

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

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

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

const fn grow_one(&mut self)

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

Trait Implementations

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

fn drop(&mut self)

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

Auto Trait Implementations

impl<T, A> Freeze for RawVec<T, A> where RawVecInner<A>: Freeze, PhantomData<T>: Freeze,

impl<T, A> RefUnwindSafe for RawVec<T, A> where RawVecInner<A>: RefUnwindSafe, PhantomData<T>: RefUnwindSafe,

impl<T, A> Send for RawVec<T, A> where RawVecInner<A>: Send, PhantomData<T>: Send,

impl<T, A> Sync for RawVec<T, A> where RawVecInner<A>: Sync, PhantomData<T>: Sync,

impl<T, A> Unpin for RawVec<T, A> where RawVecInner<A>: Unpin, PhantomData<T>: Unpin,

impl<T, A> UnsafeUnpin for RawVec<T, A> where RawVecInner<A>: UnsafeUnpin, PhantomData<T>: UnsafeUnpin,

impl<T, A> UnwindSafe for RawVec<T, A> where RawVecInner<A>: UnwindSafe, PhantomData<T>: UnwindSafe,

Blanket Implementations

impl<T> Any for RawVec<T, A> where T: 'static + ?Sized,

fn type_id(&self) -> TypeId

impl<T> Borrow<T> for RawVec<T, A> where T: ?Sized,

fn borrow(&self) -> &T

impl<T> BorrowMut<T> for RawVec<T, A> where T: ?Sized,

fn borrow_mut(&mut self) -> &mut T

impl<T> From<T> for RawVec<T, A>

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> SizeHint for RawVec<T, A> where T: ?Sized,

fn lower_bound(&self) -> usize
fn upper_bound(&self) -> Option<usize>

impl<T> SizedTypeProperties for RawVec<T, A>

impl<T, U> Into<U> for RawVec<T, A> where U: From<T>,

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

impl<T, U> TryFrom<U> for RawVec<T, A> where U: Into<T>,

type Error = Infallible;
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

impl<T, U> TryInto<U> for RawVec<T, A> where U: TryFrom<T>,

type Error = <U as TryFrom<T>>::Error;
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>