1 // SPDX-License-Identifier: Apache-2.0 OR MIT
30 /// A low-level utility for more ergonomically allocating, reallocating, and deallocating
35 /// * Produces `Unique::dangling()` on zero-sized types.
36 /// * Produces `Unique::dangling()` on zero-length allocations.
39 /// * Guards against 32-bit systems allocating more than isize::MAX bytes.
49 /// Note that the excess of a zero-sized types is always infinite, so `capacity()` always returns
50 /// `usize::MAX`. This means that you need to be careful when round-tripping this type with a
64     /// that would truly const-call something unstable.
69     /// `RawVec` with capacity `0`. If `T` is zero-sized, then it makes a
70     /// `RawVec` with capacity `usize::MAX`. Useful for implementing
73     pub const fn new() -> Self {  in new()
80     /// zero-sized. Note that if `T` is zero-sized this means you will
85     /// Panics if the requested capacity exceeds `isize::MAX` bytes.
93     pub fn with_capacity(capacity: usize) -> Self {  in with_capacity()
101     pub fn with_capacity_zeroed(capacity: usize) -> Self {  in with_capacity_zeroed()
108     // - 8 if the element size is 1, because any heap allocators is likely
110     // - 4 if elements are moderate-sized (<= 1 KiB).
111     // - 1 otherwise, to avoid wasting too much space for very short Vecs.
122     pub const fn new_in(alloc: A) -> Self {  in new_in()
123         // `cap: 0` means "unallocated". zero-sized types are ignored.  in new_in()
131     pub fn with_capacity_in(capacity: usize, alloc: A) -> Self {  in with_capacity_in()
138     pub fn try_with_capacity_in(capacity: usize, alloc: A) -> Result<Self, TryReserveError> {  in try_with_capacity_in()
146     pub fn with_capacity_zeroed_in(capacity: usize, alloc: A) -> Self {  in with_capacity_zeroed_in()
150     /// Converts the entire buffer into `Box<[MaybeUninit<T>]>` with the specified `len`.
157     /// * `len` must be greater than or equal to the most recently requested capacity, and
158     /// * `len` must be less than or equal to `self.capacity()`.
162     pub unsafe fn into_box(self, len: usize) -> Box<[MaybeUninit<T>], A> {  in into_box()
163         // Sanity-check one half of the safety requirement (we cannot check the other half).  in into_box()
165             len <= self.capacity(),  in into_box()
166             "`len` must be smaller than or equal to `self.capacity()`"  in into_box()
171             let slice = slice::from_raw_parts_mut(me.ptr() as *mut MaybeUninit<T>, len);  in into_box()
177     fn allocate_in(capacity: usize, init: AllocInit, alloc: A) -> Self {  in allocate_in()
203             // here should change to `ptr.len() / mem::size_of::<T>()`.  in allocate_in()
212 …  fn try_allocate_in(capacity: usize, init: AllocInit, alloc: A) -> Result<Self, TryReserveError> {  in try_allocate_in()
228         // here should change to `ptr.len() / mem::size_of::<T>()`.  in try_allocate_in()
242     /// The `capacity` cannot exceed `isize::MAX` for sized types. (only a concern on 32-bit
243     /// systems). ZST vectors may have a capacity up to `usize::MAX`.
247     pub unsafe fn from_raw_parts_in(ptr: *mut T, capacity: usize, alloc: A) -> Self {  in from_raw_parts_in()
252     /// `Unique::dangling()` if `capacity == 0` or `T` is zero-sized. In the former case, you must
255     pub fn ptr(&self) -> *mut T {  in ptr()
261     /// This will always be `usize::MAX` if `T` is zero-sized.
263     pub fn capacity(&self) -> usize {  in capacity()
264         if T::IS_ZST { usize::MAX } else { self.cap }  in capacity()
268     pub fn allocator(&self) -> &A {  in allocator()
272     fn current_memory(&self) -> Option<(NonNull<u8>, Layout)> {  in current_memory()
290     /// Ensures that the buffer contains at least enough space to hold `len +
296     /// If `len` exceeds `self.capacity()`, this may fail to actually allocate
300     /// This is ideal for implementing a bulk-push operation like `extend`.
304     /// Panics if the new capacity exceeds `isize::MAX` bytes.
311     pub fn reserve(&mut self, len: usize, additional: usize) {  in reserve()
313         // Therefore, we move all the resizing and error-handling logic from grow_amortized and  in reserve()
319             len: usize,  in reserve()
322             handle_reserve(slf.grow_amortized(len, additional));  in reserve()
325         if self.needs_to_grow(len, additional) {  in reserve()
326             do_reserve_and_handle(self, len, additional);  in reserve()
331     /// oft-instantiated `Vec::push()`, which does its own capacity check.
334     pub fn reserve_for_push(&mut self, len: usize) {  in reserve_for_push()
335         handle_reserve(self.grow_amortized(len, 1));  in reserve_for_push()
339     pub fn try_reserve(&mut self, len: usize, additional: usize) -> Result<(), TryReserveError> {  in try_reserve()
340         if self.needs_to_grow(len, additional) {  in try_reserve()
341             self.grow_amortized(len, additional)  in try_reserve()
349     pub fn try_reserve_for_push(&mut self, len: usize) -> Result<(), TryReserveError> {  in try_reserve_for_push()
350         self.grow_amortized(len, 1)  in try_reserve_for_push()
353     /// Ensures that the buffer contains at least enough space to hold `len +
359     /// If `len` exceeds `self.capacity()`, this may fail to actually allocate
365     /// Panics if the new capacity exceeds `isize::MAX` bytes.
371     pub fn reserve_exact(&mut self, len: usize, additional: usize) {  in reserve_exact()
372         handle_reserve(self.try_reserve_exact(len, additional));  in reserve_exact()
378         len: usize,  in try_reserve_exact()
380     ) -> Result<(), TryReserveError> {  in try_reserve_exact()
381         if self.needs_to_grow(len, additional) { self.grow_exact(len, additional) } else { Ok(()) }  in try_reserve_exact()
402     /// Mainly used to make inlining reserve-calls possible without inlining `grow`.
403     fn needs_to_grow(&self, len: usize, additional: usize) -> bool {  in needs_to_grow()
404         additional > self.capacity().wrapping_sub(len)  in needs_to_grow()
410         // change to `ptr.len() / mem::size_of::<T>()`.  in set_ptr_and_cap()
421     // are non-generic over `T`.
422     fn grow_amortized(&mut self, len: usize, additional: usize) -> Result<(), TryReserveError> {  in grow_amortized()
427             // Since we return a capacity of `usize::MAX` when `elem_size` is  in grow_amortized()
433         let required_cap = len.checked_add(additional).ok_or(CapacityOverflow)?;  in grow_amortized()
436         // because `cap <= isize::MAX` and the type of `cap` is `usize`.  in grow_amortized()
437         let cap = cmp::max(self.cap * 2, required_cap);  in grow_amortized()
438         let cap = cmp::max(Self::MIN_NON_ZERO_CAP, cap);  in grow_amortized()
442         // `finish_grow` is non-generic over `T`.  in grow_amortized()
451     fn grow_exact(&mut self, len: usize, additional: usize) -> Result<(), TryReserveError> {  in grow_exact()
453             // Since we return a capacity of `usize::MAX` when the type size is  in grow_exact()
458         let cap = len.checked_add(additional).ok_or(CapacityOverflow)?;  in grow_exact()
461         // `finish_grow` is non-generic over `T`.  in grow_exact()
468     fn shrink(&mut self, cap: usize) -> Result<(), TryReserveError> {  in shrink()
507 ) -> Result<NonNull<[u8]>, TryReserveError>  in finish_grow()
551 // * We don't ever allocate `> isize::MAX` byte-size objects.
552 // * We don't overflow `usize::MAX` and actually allocate too little.
554 // On 64-bit we just need to check for overflow since trying to allocate
555 // `> isize::MAX` bytes will surely fail. On 32-bit and 16-bit we need to add
557 // all 4GB in user-space, e.g., PAE or x32.
560 fn alloc_guard(alloc_size: usize) -> Result<(), TryReserveError> {  in alloc_guard()
561     if usize::BITS < 64 && alloc_size > isize::MAX as usize {  in alloc_guard()
572 fn capacity_overflow() -> ! {  in capacity_overflow()