Struct allocator_api::raw_vec::RawVec
source · Implementations§
source§impl<T, A: Alloc> RawVec<T, A>
impl<T, A: Alloc> RawVec<T, A>
sourcepub fn new_in(a: A) -> Self
pub fn new_in(a: A) -> Self
Like new
but parameterized over the choice of allocator for
the returned RawVec.
sourcepub fn with_capacity_in(cap: usize, a: A) -> Self
pub fn with_capacity_in(cap: usize, a: A) -> Self
Like with_capacity
but parameterized over the choice of
allocator for the returned RawVec.
sourcepub fn with_capacity_zeroed_in(cap: usize, a: A) -> Self
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.
source§impl<T> RawVec<T, Global>
impl<T> RawVec<T, Global>
sourcepub fn new() -> Self
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.
sourcepub fn with_capacity(cap: usize) -> Self
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
sourcepub fn with_capacity_zeroed(cap: usize) -> Self
pub fn with_capacity_zeroed(cap: usize) -> Self
Like with_capacity
but guarantees the buffer is zeroed.
source§impl<T, A: Alloc> RawVec<T, A>
impl<T, A: Alloc> RawVec<T, A>
sourcepub unsafe fn from_raw_parts_in(ptr: *mut T, cap: usize, a: A) -> Self
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.
source§impl<T> RawVec<T, Global>
impl<T> RawVec<T, Global>
sourcepub unsafe fn from_raw_parts(ptr: *mut T, cap: usize) -> Self
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.
source§impl<T, A: Alloc> RawVec<T, A>
impl<T, A: Alloc> RawVec<T, A>
sourcepub fn ptr(&self) -> *mut T
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.
sourcepub fn cap(&self) -> usize
pub fn cap(&self) -> usize
Gets the capacity of the allocation.
This will always be usize::MAX
if T
is zero-sized.
sourcepub fn alloc_mut(&mut self) -> &mut A
pub fn alloc_mut(&mut self) -> &mut A
Returns a mutable reference to the allocator backing this RawVec.
sourcepub fn double(&mut self)
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
extern crate allocator_api;
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().offset(self.len as isize), elem);
}
self.len += 1;
}
}
sourcepub fn double_in_place(&mut self) -> bool
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, 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.
sourcepub fn try_reserve_exact(
&mut self,
used_cap: usize,
needed_extra_cap: usize
) -> Result<(), CollectionAllocErr>
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.
sourcepub fn reserve_exact(&mut self, used_cap: usize, needed_extra_cap: usize)
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
sourcepub fn try_reserve(
&mut self,
used_cap: usize,
needed_extra_cap: usize
) -> Result<(), CollectionAllocErr>
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.
sourcepub fn reserve(&mut self, used_cap: usize, needed_extra_cap: usize)
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
extern crate allocator_api;
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().offset(self.len as isize), x.clone());
}
self.len += 1;
}
}
}
sourcepub fn reserve_in_place(
&mut self,
used_cap: usize,
needed_extra_cap: usize
) -> bool
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, 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.
sourcepub fn shrink_to_fit(&mut self, amount: usize)
pub fn shrink_to_fit(&mut self, amount: usize)
source§impl<T, A: Alloc> RawVec<T, A>
impl<T, A: Alloc> RawVec<T, A>
sourcepub unsafe fn into_box(self) -> Box<[T], A> ⓘ
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)