Struct allocator_api::raw_vec::RawVec

pub struct RawVec<T, A: Alloc = Global> { /* fields omitted */ }

Methods

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

pub fn new_in(a: A) -> Self

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

pub fn with_capacity_in(cap: usize, a: A) -> Self

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

pub fn with_capacity_zeroed_in(cap: usize, a: A) -> Self

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

impl<T> RawVec<T, Global>

pub 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 has 0 size, then it makes a RawVec with capacity usize::MAX. Useful for implementing delayed allocation.

pub fn with_capacity(cap: usize) -> Self

Creates a RawVec (on the system heap) with exactly the capacity and alignment requirements for a [T; cap]. This is equivalent to calling RawVec::new when cap 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!

Panics

• Panics if the requested capacity exceeds usize::MAX bytes.
• Panics on 32-bit platforms if the requested capacity exceeds isize::MAX bytes.

Aborts

Aborts on OOM

pub fn with_capacity_zeroed(cap: usize) -> Self

Like with_capacity but guarantees the buffer is zeroed.

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

pub unsafe fn from_raw_parts_in(ptr: *mut T, cap: usize, a: A) -> Self

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

Undefined Behavior

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

impl<T> RawVec<T, Global>

pub unsafe fn from_raw_parts(ptr: *mut T, cap: usize) -> Self

Reconstitutes a RawVec from a pointer, capacity.

Undefined Behavior

The ptr must be allocated (on the system heap), and with the given capacity. The capacity cannot exceed isize::MAX (only a concern on 32-bit systems). If the ptr and capacity come from a RawVec, then this is guaranteed.

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

pub fn from_box(slice: Box<[T], A>) -> Self

Converts a Box<[T], A> into a RawVec<T, A>.

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

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

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

pub fn cap(&self) -> usize

Gets the capacity of the allocation.

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

pub fn alloc(&self) -> &A

Returns a shared reference to the allocator backing this RawVec.

pub fn alloc_mut(&mut self) -> &mut A

Returns a mutable reference to the allocator backing this RawVec.

pub fn double(&mut self)

Doubles the size of the type's backing allocation. This is common enough to want to do that it's easiest to just have a dedicated method. Slightly more efficient logic can be provided for this than the general case.

This function is ideal for when pushing elements one-at-a-time because you don't need to incur the costs of the more general computations reserve needs to do to guard against overflow. You do however need to manually check if your len == cap.

Panics

• Panics if T is zero-sized on the assumption that you managed to exhaust all usize::MAX slots in your imaginary buffer.
• Panics on 32-bit platforms if the requested capacity exceeds isize::MAX bytes.

Aborts

Aborts on OOM

Examples

use allocator_api::RawVec;
struct MyVec<T> {
    buf: RawVec<T>,
    len: usize,
}

impl<T> MyVec<T> {
    pub fn push(&mut self, elem: T) {
        if self.len == self.buf.cap() { self.buf.double(); }
        // double would have aborted or panicked if the len exceeded
        // `isize::MAX` so this is safe to do unchecked now.
        unsafe {
            ptr::write(self.buf.ptr().add(self.len), elem);
        }
        self.len += 1;
    }
}

pub fn double_in_place(&mut self) -> bool

Attempts to double the size of the type's backing allocation in place. This is common enough to want to do that it's easiest to just have a dedicated method. Slightly more efficient logic can be provided for this than the general case.

Returns true if the reallocation attempt has succeeded.

Panics

• Panics if T is zero-sized on the assumption that you managed to exhaust all usize::MAX slots in your imaginary buffer.
• Panics on 32-bit platforms if the requested capacity exceeds isize::MAX bytes.

pub fn try_reserve_exact(
    &mut self,
    used_cap: usize,
    needed_extra_cap: usize
) -> Result<(), CollectionAllocErr>

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

pub fn reserve_exact(&mut self, used_cap: usize, needed_extra_cap: usize)

Ensures that the buffer contains at least enough space to hold used_cap + needed_extra_cap 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 used_cap exceeds self.cap(), 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 requested capacity exceeds usize::MAX bytes.
• Panics on 32-bit platforms if the requested capacity exceeds isize::MAX bytes.

Aborts

Aborts on OOM

pub fn try_reserve(
    &mut self,
    used_cap: usize,
    needed_extra_cap: usize
) -> Result<(), CollectionAllocErr>

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

pub fn reserve(&mut self, used_cap: usize, needed_extra_cap: usize)

Ensures that the buffer contains at least enough space to hold used_cap + needed_extra_cap 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 used_cap exceeds self.cap(), 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 requested capacity exceeds usize::MAX bytes.
• Panics on 32-bit platforms if the requested capacity exceeds isize::MAX bytes.

Aborts

Aborts on OOM

Examples

use allocator_api::RawVec;
struct MyVec<T> {
    buf: RawVec<T>,
    len: usize,
}

impl<T: Clone> MyVec<T> {
    pub fn push_all(&mut self, elems: &[T]) {
        self.buf.reserve(self.len, elems.len());
        // reserve would have aborted or panicked if the len exceeded
        // `isize::MAX` so this is safe to do unchecked now.
        for x in elems {
            unsafe {
                ptr::write(self.buf.ptr().add(self.len), x.clone());
            }
            self.len += 1;
        }
    }
}

pub fn reserve_in_place(
    &mut self,
    used_cap: usize,
    needed_extra_cap: usize
) -> bool

Attempts to ensure that the buffer contains at least enough space to hold used_cap + needed_extra_cap elements. If it doesn't already have enough capacity, will reallocate in place enough space plus comfortable slack space to get amortized O(1) behavior. Will limit this behaviour if it would needlessly cause itself to panic.

If used_cap exceeds self.cap(), 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.

Returns true if the reallocation attempt has succeeded.

Panics

• Panics if the requested capacity exceeds usize::MAX bytes.
• Panics on 32-bit platforms if the requested capacity exceeds isize::MAX bytes.

pub fn shrink_to_fit(&mut self, amount: usize)

Shrinks the allocation down to the specified amount. 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.

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

Important traits for Box<I, A>

impl<I: Iterator + ?Sized, A: Alloc> Iterator for Box<I, A> type Item = I::Item;

pub unsafe fn into_box(self) -> Box<[T], A>

Converts the entire buffer into Box<[T], A>.

While it is not strictly Undefined Behavior to call this procedure while some of the RawVec is uninitialized, it certainly makes it trivial to trigger it.

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

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

pub unsafe fn dealloc_buffer(&mut self)

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

Trait Implementations

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

fn drop(&mut self)

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