alloc::raw_vec::RawVec - Rust
Description: API documentation for the Rust `RawVec` struct in crate `alloc`.
Keywords: rust, rustlang, rust-lang, RawVec

# Struct alloc::raw_vec::RawVec [−] [src]

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

🔬 This is a nightly-only experimental API. (`alloc` #27783)

this library is unlikely to be stabilized in its current form or name

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::empty() on zero-sized types
- Produces Unique::empty() on zero-length allocations
- 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
- Aborts on OOM
- Avoids freeing Unique::empty()
- Contains a ptr::Unique and thus endows the user with all related benefits

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 a RawVec always forces its capacity to be usize::MAX for zero-sized types. This enables you to use capacity growing logic catch the overflows in your length that might occur with zero-sized types.

However this means that you need to be careful when roundtripping this type with a `Box<[T]>`: `cap()` won't yield the len. However `with_capacity`, `shrink_to_fit`, and `from_box` will actually set RawVec's private capacity field. This allows zero-sized types to not be special-cased by consumers of this type.

## Methods

### `impl<T, A: Alloc> RawVec<T, A>`
[src]

#### `fn new_in(a: A) -> Self`
[src]

🔬 This is a nightly-only experimental API. (`alloc` #27783)

this library is unlikely to be stabilized in its current form or name

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

#### `fn with_capacity_in(cap: usize, a: A) -> Self`
[src]

🔬 This is a nightly-only experimental API. (`alloc` #27783)

this library is unlikely to be stabilized in its current form or name

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

#### `fn with_capacity_zeroed_in(cap: usize, a: A) -> Self`
[src]

🔬 This is a nightly-only experimental API. (`alloc` #27783)

this library is unlikely to be stabilized in its current form or name

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

### `impl<T> RawVec<T, Heap>`
[src]

#### `fn new() -> Self`
[src]

🔬 This is a nightly-only experimental API. (`alloc` #27783)

this library is unlikely to be stabilized in its current form or name

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 it makes a RawVec with capacity `usize::MAX`. Useful for implementing delayed allocation.

#### `fn with_capacity(cap: usize) -> Self`
[src]

🔬 This is a nightly-only experimental API. (`alloc` #27783)

this library is unlikely to be stabilized in its current form or name

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

#### `fn with_capacity_zeroed(cap: usize) -> Self`
[src]

🔬 This is a nightly-only experimental API. (`alloc` #27783)

this library is unlikely to be stabilized in its current form or name

Like `with_capacity` but guarantees the buffer is zeroed.

### `impl<T, A: Alloc> RawVec<T, A>`
[src]

#### `unsafe fn from_raw_parts_in(ptr: *mut T, cap: usize, a: A) -> Self`
[src]

🔬 This is a nightly-only experimental API. (`alloc` #27783)

this library is unlikely to be stabilized in its current form or name

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, Heap>`
[src]

#### `unsafe fn from_raw_parts(ptr: *mut T, cap: usize) -> Self`
[src]

🔬 This is a nightly-only experimental API. (`alloc` #27783)

this library is unlikely to be stabilized in its current form or name

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.

#### `fn from_box(slice: Box<[T]>) -> Self`
[src]

🔬 This is a nightly-only experimental API. (`alloc` #27783)

this library is unlikely to be stabilized in its current form or name

Converts a `Box<[T]>` into a `RawVec<T>`.

### `impl<T, A: Alloc> RawVec<T, A>`
[src]

#### `fn ptr(&self) -> *mut T`
[src]

🔬 This is a nightly-only experimental API. (`alloc` #27783)

this library is unlikely to be stabilized in its current form or name

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

#### `fn cap(&self) -> usize`
[src]

🔬 This is a nightly-only experimental API. (`alloc` #27783)

this library is unlikely to be stabilized in its current form or name

Gets the capacity of the allocation.

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

#### `fn alloc(&self) -> &A`
[src]

🔬 This is a nightly-only experimental API. (`alloc` #27783)

this library is unlikely to be stabilized in its current form or name

Returns a shared reference to the allocator backing this RawVec.

#### `fn alloc_mut(&mut self) -> &mut A`
[src]

🔬 This is a nightly-only experimental API. (`alloc` #27783)

this library is unlikely to be stabilized in its current form or name

Returns a mutable reference to the allocator backing this RawVec.

#### `fn double(&mut self)`
[src]

🔬 This is a nightly-only experimental API. (`alloc` #27783)

this library is unlikely to be stabilized in its current form or name

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

    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().offset(self.len as isize), elem);
            }
            self.len += 1;
        }
    }

#### `fn double_in_place(&mut self) -> bool`
[src]

🔬 This is a nightly-only experimental API. (`alloc` #27783)

this library is unlikely to be stabilized in its current form or name

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, or false otherwise.

# 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.

#### `fn reserve_exact(&mut self, used_cap: usize, needed_extra_cap: usize)`
[src]

🔬 This is a nightly-only experimental API. (`alloc` #27783)

this library is unlikely to be stabilized in its current form or name

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

#### `fn reserve(&mut self, used_cap: usize, needed_extra_cap: usize)`
[src]

🔬 This is a nightly-only experimental API. (`alloc` #27783)

this library is unlikely to be stabilized in its current form or name

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

    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().offset(self.len as isize), x.clone());
                }
                self.len += 1;
            }
        }
    }

#### `fn reserve_in_place(&mut self, used_cap: usize, needed_extra_cap: usize) -> bool`
[src]

🔬 This is a nightly-only experimental API. (`alloc` #27783)

this library is unlikely to be stabilized in its current form or name

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, or false otherwise.

# Panics

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

#### `fn shrink_to_fit(&mut self, amount: usize)`
[src]

🔬 This is a nightly-only experimental API. (`alloc` #27783)

this library is unlikely to be stabilized in its current form or name

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> RawVec<T, Heap>`
[src]

#### `unsafe fn into_box(self) -> Box<[T]>`
[src]

🔬 This is a nightly-only experimental API. (`alloc` #27783)

this library is unlikely to be stabilized in its current form or name

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

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>`
[src]

#### `unsafe fn dealloc_buffer(&mut self)`
[src]

🔬 This is a nightly-only experimental API. (`alloc` #27783)

this library is unlikely to be stabilized in its current form or name

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

## Trait Implementations

### `impl<T, A: Alloc> Drop for RawVec<T, A>`
[src]

#### `fn drop(&mut self)`
[src]

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

# Help

## Keyboard Shortcuts

?
  Show this help dialog
S
  Focus the search field
⇤
  Move up in search results
⇥
  Move down in search results
⏎
  Go to active search result
+
  Collapse/expand all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)