summaryrefslogtreecommitdiff
path: root/rust/alloc
diff options
context:
space:
mode:
Diffstat (limited to 'rust/alloc')
-rw-r--r--rust/alloc/alloc.rs6
-rw-r--r--rust/alloc/boxed.rs4
-rw-r--r--rust/alloc/lib.rs7
-rw-r--r--rust/alloc/raw_vec.rs13
-rw-r--r--rust/alloc/slice.rs4
-rw-r--r--rust/alloc/vec/into_iter.rs108
-rw-r--r--rust/alloc/vec/mod.rs101
7 files changed, 157 insertions, 86 deletions
diff --git a/rust/alloc/alloc.rs b/rust/alloc/alloc.rs
index abb791cc2371..b1204f87227b 100644
--- a/rust/alloc/alloc.rs
+++ b/rust/alloc/alloc.rs
@@ -5,7 +5,7 @@
#![stable(feature = "alloc_module", since = "1.28.0")]
#[cfg(not(test))]
-use core::intrinsics;
+use core::hint;
#[cfg(not(test))]
use core::ptr::{self, NonNull};
@@ -210,7 +210,7 @@ impl Global {
let new_size = new_layout.size();
// `realloc` probably checks for `new_size >= old_layout.size()` or something similar.
- intrinsics::assume(new_size >= old_layout.size());
+ hint::assert_unchecked(new_size >= old_layout.size());
let raw_ptr = realloc(ptr.as_ptr(), old_layout, new_size);
let ptr = NonNull::new(raw_ptr).ok_or(AllocError)?;
@@ -301,7 +301,7 @@ unsafe impl Allocator for Global {
// SAFETY: `new_size` is non-zero. Other conditions must be upheld by the caller
new_size if old_layout.align() == new_layout.align() => unsafe {
// `realloc` probably checks for `new_size <= old_layout.size()` or something similar.
- intrinsics::assume(new_size <= old_layout.size());
+ hint::assert_unchecked(new_size <= old_layout.size());
let raw_ptr = realloc(ptr.as_ptr(), old_layout, new_size);
let ptr = NonNull::new(raw_ptr).ok_or(AllocError)?;
diff --git a/rust/alloc/boxed.rs b/rust/alloc/boxed.rs
index c93a22a5c97f..5fc39dfeb8e7 100644
--- a/rust/alloc/boxed.rs
+++ b/rust/alloc/boxed.rs
@@ -26,6 +26,7 @@
//! Creating a recursive data structure:
//!
//! ```
+//! ##[allow(dead_code)]
//! #[derive(Debug)]
//! enum List<T> {
//! Cons(T, Box<List<T>>),
@@ -194,8 +195,7 @@ mod thin;
#[fundamental]
#[stable(feature = "rust1", since = "1.0.0")]
// The declaration of the `Box` struct must be kept in sync with the
-// `alloc::alloc::box_free` function or ICEs will happen. See the comment
-// on `box_free` for more details.
+// compiler or ICEs will happen.
pub struct Box<
T: ?Sized,
#[unstable(feature = "allocator_api", issue = "32838")] A: Allocator = Global,
diff --git a/rust/alloc/lib.rs b/rust/alloc/lib.rs
index 36f79c075593..39afd55ec074 100644
--- a/rust/alloc/lib.rs
+++ b/rust/alloc/lib.rs
@@ -105,7 +105,6 @@
#![feature(allocator_api)]
#![feature(array_chunks)]
#![feature(array_into_iter_constructors)]
-#![feature(array_methods)]
#![feature(array_windows)]
#![feature(ascii_char)]
#![feature(assert_matches)]
@@ -122,7 +121,6 @@
#![feature(const_size_of_val)]
#![feature(const_waker)]
#![feature(core_intrinsics)]
-#![feature(core_panic)]
#![feature(deprecated_suggestion)]
#![feature(dispatch_from_dyn)]
#![feature(error_generic_member_access)]
@@ -132,6 +130,7 @@
#![feature(fmt_internals)]
#![feature(fn_traits)]
#![feature(hasher_prefixfree_extras)]
+#![feature(hint_assert_unchecked)]
#![feature(inline_const)]
#![feature(inplace_iteration)]
#![feature(iter_advance_by)]
@@ -141,6 +140,8 @@
#![feature(maybe_uninit_slice)]
#![feature(maybe_uninit_uninit_array)]
#![feature(maybe_uninit_uninit_array_transpose)]
+#![feature(non_null_convenience)]
+#![feature(panic_internals)]
#![feature(pattern)]
#![feature(ptr_internals)]
#![feature(ptr_metadata)]
@@ -149,7 +150,6 @@
#![feature(set_ptr_value)]
#![feature(sized_type_properties)]
#![feature(slice_from_ptr_range)]
-#![feature(slice_group_by)]
#![feature(slice_ptr_get)]
#![feature(slice_ptr_len)]
#![feature(slice_range)]
@@ -182,6 +182,7 @@
#![feature(const_ptr_write)]
#![feature(const_trait_impl)]
#![feature(const_try)]
+#![feature(decl_macro)]
#![feature(dropck_eyepatch)]
#![feature(exclusive_range_pattern)]
#![feature(fundamental)]
diff --git a/rust/alloc/raw_vec.rs b/rust/alloc/raw_vec.rs
index 98b6abf30af6..1839d1c8ee7a 100644
--- a/rust/alloc/raw_vec.rs
+++ b/rust/alloc/raw_vec.rs
@@ -4,7 +4,7 @@
use core::alloc::LayoutError;
use core::cmp;
-use core::intrinsics;
+use core::hint;
use core::mem::{self, ManuallyDrop, MaybeUninit, SizedTypeProperties};
use core::ptr::{self, NonNull, Unique};
use core::slice;
@@ -317,7 +317,7 @@ impl<T, A: Allocator> RawVec<T, A> {
///
/// # Panics
///
- /// Panics if the new capacity exceeds `isize::MAX` bytes.
+ /// Panics if the new capacity exceeds `isize::MAX` _bytes_.
///
/// # Aborts
///
@@ -358,7 +358,7 @@ impl<T, A: Allocator> RawVec<T, A> {
}
unsafe {
// Inform the optimizer that the reservation has succeeded or wasn't needed
- core::intrinsics::assume(!self.needs_to_grow(len, additional));
+ hint::assert_unchecked(!self.needs_to_grow(len, additional));
}
Ok(())
}
@@ -381,7 +381,7 @@ impl<T, A: Allocator> RawVec<T, A> {
///
/// # Panics
///
- /// Panics if the new capacity exceeds `isize::MAX` bytes.
+ /// Panics if the new capacity exceeds `isize::MAX` _bytes_.
///
/// # Aborts
///
@@ -402,7 +402,7 @@ impl<T, A: Allocator> RawVec<T, A> {
}
unsafe {
// Inform the optimizer that the reservation has succeeded or wasn't needed
- core::intrinsics::assume(!self.needs_to_grow(len, additional));
+ hint::assert_unchecked(!self.needs_to_grow(len, additional));
}
Ok(())
}
@@ -553,7 +553,7 @@ where
debug_assert_eq!(old_layout.align(), new_layout.align());
unsafe {
// The allocator checks for alignment equality
- intrinsics::assume(old_layout.align() == new_layout.align());
+ hint::assert_unchecked(old_layout.align() == new_layout.align());
alloc.grow(ptr, old_layout, new_layout)
}
} else {
@@ -591,7 +591,6 @@ fn handle_reserve(result: Result<(), TryReserveError>) {
// `> isize::MAX` bytes will surely fail. On 32-bit and 16-bit we need to add
// an extra guard for this in case we're running on a platform which can use
// all 4GB in user-space, e.g., PAE or x32.
-
#[inline]
fn alloc_guard(alloc_size: usize) -> Result<(), TryReserveError> {
if usize::BITS < 64 && alloc_size > isize::MAX as usize {
diff --git a/rust/alloc/slice.rs b/rust/alloc/slice.rs
index 1181836da5f4..a36b072c9519 100644
--- a/rust/alloc/slice.rs
+++ b/rust/alloc/slice.rs
@@ -53,14 +53,14 @@ pub use core::slice::{from_mut, from_ref};
pub use core::slice::{from_mut_ptr_range, from_ptr_range};
#[stable(feature = "rust1", since = "1.0.0")]
pub use core::slice::{from_raw_parts, from_raw_parts_mut};
+#[stable(feature = "slice_group_by", since = "1.77.0")]
+pub use core::slice::{ChunkBy, ChunkByMut};
#[stable(feature = "rust1", since = "1.0.0")]
pub use core::slice::{Chunks, Windows};
#[stable(feature = "chunks_exact", since = "1.31.0")]
pub use core::slice::{ChunksExact, ChunksExactMut};
#[stable(feature = "rust1", since = "1.0.0")]
pub use core::slice::{ChunksMut, Split, SplitMut};
-#[unstable(feature = "slice_group_by", issue = "80552")]
-pub use core::slice::{GroupBy, GroupByMut};
#[stable(feature = "rust1", since = "1.0.0")]
pub use core::slice::{Iter, IterMut};
#[stable(feature = "rchunks", since = "1.31.0")]
diff --git a/rust/alloc/vec/into_iter.rs b/rust/alloc/vec/into_iter.rs
index 136bfe94af6c..0f11744c44b3 100644
--- a/rust/alloc/vec/into_iter.rs
+++ b/rust/alloc/vec/into_iter.rs
@@ -20,6 +20,17 @@ use core::ops::Deref;
use core::ptr::{self, NonNull};
use core::slice::{self};
+macro non_null {
+ (mut $place:expr, $t:ident) => {{
+ #![allow(unused_unsafe)] // we're sometimes used within an unsafe block
+ unsafe { &mut *(ptr::addr_of_mut!($place) as *mut NonNull<$t>) }
+ }},
+ ($place:expr, $t:ident) => {{
+ #![allow(unused_unsafe)] // we're sometimes used within an unsafe block
+ unsafe { *(ptr::addr_of!($place) as *const NonNull<$t>) }
+ }},
+}
+
/// An iterator that moves out of a vector.
///
/// This `struct` is created by the `into_iter` method on [`Vec`](super::Vec)
@@ -43,10 +54,12 @@ pub struct IntoIter<
// the drop impl reconstructs a RawVec from buf, cap and alloc
// to avoid dropping the allocator twice we need to wrap it into ManuallyDrop
pub(super) alloc: ManuallyDrop<A>,
- pub(super) ptr: *const T,
- pub(super) end: *const T, // If T is a ZST, this is actually ptr+len. This encoding is picked so that
- // ptr == end is a quick test for the Iterator being empty, that works
- // for both ZST and non-ZST.
+ pub(super) ptr: NonNull<T>,
+ /// If T is a ZST, this is actually ptr+len. This encoding is picked so that
+ /// ptr == end is a quick test for the Iterator being empty, that works
+ /// for both ZST and non-ZST.
+ /// For non-ZSTs the pointer is treated as `NonNull<T>`
+ pub(super) end: *const T,
}
#[stable(feature = "vec_intoiter_debug", since = "1.13.0")]
@@ -70,7 +83,7 @@ impl<T, A: Allocator> IntoIter<T, A> {
/// ```
#[stable(feature = "vec_into_iter_as_slice", since = "1.15.0")]
pub fn as_slice(&self) -> &[T] {
- unsafe { slice::from_raw_parts(self.ptr, self.len()) }
+ unsafe { slice::from_raw_parts(self.ptr.as_ptr(), self.len()) }
}
/// Returns the remaining items of this iterator as a mutable slice.
@@ -99,7 +112,7 @@ impl<T, A: Allocator> IntoIter<T, A> {
}
fn as_raw_mut_slice(&mut self) -> *mut [T] {
- ptr::slice_from_raw_parts_mut(self.ptr as *mut T, self.len())
+ ptr::slice_from_raw_parts_mut(self.ptr.as_ptr(), self.len())
}
/// Drops remaining elements and relinquishes the backing allocation.
@@ -126,7 +139,7 @@ impl<T, A: Allocator> IntoIter<T, A> {
// this creates less assembly
self.cap = 0;
self.buf = unsafe { NonNull::new_unchecked(RawVec::NEW.ptr()) };
- self.ptr = self.buf.as_ptr();
+ self.ptr = self.buf;
self.end = self.buf.as_ptr();
// Dropping the remaining elements can panic, so this needs to be
@@ -138,9 +151,9 @@ impl<T, A: Allocator> IntoIter<T, A> {
/// Forgets to Drop the remaining elements while still allowing the backing allocation to be freed.
pub(crate) fn forget_remaining_elements(&mut self) {
- // For th ZST case, it is crucial that we mutate `end` here, not `ptr`.
+ // For the ZST case, it is crucial that we mutate `end` here, not `ptr`.
// `ptr` must stay aligned, while `end` may be unaligned.
- self.end = self.ptr;
+ self.end = self.ptr.as_ptr();
}
#[cfg(not(no_global_oom_handling))]
@@ -162,7 +175,7 @@ impl<T, A: Allocator> IntoIter<T, A> {
// say that they're all at the beginning of the "allocation".
0..this.len()
} else {
- this.ptr.sub_ptr(buf)..this.end.sub_ptr(buf)
+ this.ptr.sub_ptr(this.buf)..this.end.sub_ptr(buf)
};
let cap = this.cap;
let alloc = ManuallyDrop::take(&mut this.alloc);
@@ -189,29 +202,35 @@ impl<T, A: Allocator> Iterator for IntoIter<T, A> {
#[inline]
fn next(&mut self) -> Option<T> {
- if self.ptr == self.end {
- None
- } else if T::IS_ZST {
- // `ptr` has to stay where it is to remain aligned, so we reduce the length by 1 by
- // reducing the `end`.
- self.end = self.end.wrapping_byte_sub(1);
-
- // Make up a value of this ZST.
- Some(unsafe { mem::zeroed() })
+ if T::IS_ZST {
+ if self.ptr.as_ptr() == self.end as *mut _ {
+ None
+ } else {
+ // `ptr` has to stay where it is to remain aligned, so we reduce the length by 1 by
+ // reducing the `end`.
+ self.end = self.end.wrapping_byte_sub(1);
+
+ // Make up a value of this ZST.
+ Some(unsafe { mem::zeroed() })
+ }
} else {
- let old = self.ptr;
- self.ptr = unsafe { self.ptr.add(1) };
+ if self.ptr == non_null!(self.end, T) {
+ None
+ } else {
+ let old = self.ptr;
+ self.ptr = unsafe { old.add(1) };
- Some(unsafe { ptr::read(old) })
+ Some(unsafe { ptr::read(old.as_ptr()) })
+ }
}
}
#[inline]
fn size_hint(&self) -> (usize, Option<usize>) {
let exact = if T::IS_ZST {
- self.end.addr().wrapping_sub(self.ptr.addr())
+ self.end.addr().wrapping_sub(self.ptr.as_ptr().addr())
} else {
- unsafe { self.end.sub_ptr(self.ptr) }
+ unsafe { non_null!(self.end, T).sub_ptr(self.ptr) }
};
(exact, Some(exact))
}
@@ -219,7 +238,7 @@ impl<T, A: Allocator> Iterator for IntoIter<T, A> {
#[inline]
fn advance_by(&mut self, n: usize) -> Result<(), NonZeroUsize> {
let step_size = self.len().min(n);
- let to_drop = ptr::slice_from_raw_parts_mut(self.ptr as *mut T, step_size);
+ let to_drop = ptr::slice_from_raw_parts_mut(self.ptr.as_ptr(), step_size);
if T::IS_ZST {
// See `next` for why we sub `end` here.
self.end = self.end.wrapping_byte_sub(step_size);
@@ -261,7 +280,7 @@ impl<T, A: Allocator> Iterator for IntoIter<T, A> {
// Safety: `len` indicates that this many elements are available and we just checked that
// it fits into the array.
unsafe {
- ptr::copy_nonoverlapping(self.ptr, raw_ary.as_mut_ptr() as *mut T, len);
+ ptr::copy_nonoverlapping(self.ptr.as_ptr(), raw_ary.as_mut_ptr() as *mut T, len);
self.forget_remaining_elements();
return Err(array::IntoIter::new_unchecked(raw_ary, 0..len));
}
@@ -270,7 +289,7 @@ impl<T, A: Allocator> Iterator for IntoIter<T, A> {
// Safety: `len` is larger than the array size. Copy a fixed amount here to fully initialize
// the array.
return unsafe {
- ptr::copy_nonoverlapping(self.ptr, raw_ary.as_mut_ptr() as *mut T, N);
+ ptr::copy_nonoverlapping(self.ptr.as_ptr(), raw_ary.as_mut_ptr() as *mut T, N);
self.ptr = self.ptr.add(N);
Ok(raw_ary.transpose().assume_init())
};
@@ -288,7 +307,7 @@ impl<T, A: Allocator> Iterator for IntoIter<T, A> {
// Also note the implementation of `Self: TrustedRandomAccess` requires
// that `T: Copy` so reading elements from the buffer doesn't invalidate
// them for `Drop`.
- unsafe { if T::IS_ZST { mem::zeroed() } else { ptr::read(self.ptr.add(i)) } }
+ unsafe { if T::IS_ZST { mem::zeroed() } else { self.ptr.add(i).read() } }
}
}
@@ -296,18 +315,25 @@ impl<T, A: Allocator> Iterator for IntoIter<T, A> {
impl<T, A: Allocator> DoubleEndedIterator for IntoIter<T, A> {
#[inline]
fn next_back(&mut self) -> Option<T> {
- if self.end == self.ptr {
- None
- } else if T::IS_ZST {
- // See above for why 'ptr.offset' isn't used
- self.end = self.end.wrapping_byte_sub(1);
-
- // Make up a value of this ZST.
- Some(unsafe { mem::zeroed() })
+ if T::IS_ZST {
+ if self.end as *mut _ == self.ptr.as_ptr() {
+ None
+ } else {
+ // See above for why 'ptr.offset' isn't used
+ self.end = self.end.wrapping_byte_sub(1);
+
+ // Make up a value of this ZST.
+ Some(unsafe { mem::zeroed() })
+ }
} else {
- self.end = unsafe { self.end.sub(1) };
+ if non_null!(self.end, T) == self.ptr {
+ None
+ } else {
+ let new_end = unsafe { non_null!(self.end, T).sub(1) };
+ *non_null!(mut self.end, T) = new_end;
- Some(unsafe { ptr::read(self.end) })
+ Some(unsafe { ptr::read(new_end.as_ptr()) })
+ }
}
}
@@ -333,7 +359,11 @@ impl<T, A: Allocator> DoubleEndedIterator for IntoIter<T, A> {
#[stable(feature = "rust1", since = "1.0.0")]
impl<T, A: Allocator> ExactSizeIterator for IntoIter<T, A> {
fn is_empty(&self) -> bool {
- self.ptr == self.end
+ if T::IS_ZST {
+ self.ptr.as_ptr() == self.end as *mut _
+ } else {
+ self.ptr == non_null!(self.end, T)
+ }
}
}
diff --git a/rust/alloc/vec/mod.rs b/rust/alloc/vec/mod.rs
index 220fb9d6f45b..0be27fff4554 100644
--- a/rust/alloc/vec/mod.rs
+++ b/rust/alloc/vec/mod.rs
@@ -360,7 +360,7 @@ mod spec_extend;
///
/// `vec![x; n]`, `vec![a, b, c, d]`, and
/// [`Vec::with_capacity(n)`][`Vec::with_capacity`], will all produce a `Vec`
-/// with exactly the requested capacity. If <code>[len] == [capacity]</code>,
+/// with at least the requested capacity. If <code>[len] == [capacity]</code>,
/// (as is the case for the [`vec!`] macro), then a `Vec<T>` can be converted to
/// and from a [`Box<[T]>`][owned slice] without reallocating or moving the elements.
///
@@ -447,7 +447,7 @@ impl<T> Vec<T> {
///
/// # Panics
///
- /// Panics if the new capacity exceeds `isize::MAX` bytes.
+ /// Panics if the new capacity exceeds `isize::MAX` _bytes_.
///
/// # Examples
///
@@ -690,7 +690,7 @@ impl<T, A: Allocator> Vec<T, A> {
///
/// # Panics
///
- /// Panics if the new capacity exceeds `isize::MAX` bytes.
+ /// Panics if the new capacity exceeds `isize::MAX` _bytes_.
///
/// # Examples
///
@@ -1013,7 +1013,7 @@ impl<T, A: Allocator> Vec<T, A> {
///
/// # Panics
///
- /// Panics if the new capacity exceeds `isize::MAX` bytes.
+ /// Panics if the new capacity exceeds `isize::MAX` _bytes_.
///
/// # Examples
///
@@ -1043,7 +1043,7 @@ impl<T, A: Allocator> Vec<T, A> {
///
/// # Panics
///
- /// Panics if the new capacity exceeds `isize::MAX` bytes.
+ /// Panics if the new capacity exceeds `isize::MAX` _bytes_.
///
/// # Examples
///
@@ -1140,8 +1140,11 @@ impl<T, A: Allocator> Vec<T, A> {
/// Shrinks the capacity of the vector as much as possible.
///
- /// It will drop down as close as possible to the length but the allocator
- /// may still inform the vector that there is space for a few more elements.
+ /// The behavior of this method depends on the allocator, which may either shrink the vector
+ /// in-place or reallocate. The resulting vector might still have some excess capacity, just as
+ /// is the case for [`with_capacity`]. See [`Allocator::shrink`] for more details.
+ ///
+ /// [`with_capacity`]: Vec::with_capacity
///
/// # Examples
///
@@ -1191,10 +1194,10 @@ impl<T, A: Allocator> Vec<T, A> {
/// Converts the vector into [`Box<[T]>`][owned slice].
///
- /// If the vector has excess capacity, its items will be moved into a
- /// newly-allocated buffer with exactly the right capacity.
+ /// Before doing the conversion, this method discards excess capacity like [`shrink_to_fit`].
///
/// [owned slice]: Box
+ /// [`shrink_to_fit`]: Vec::shrink_to_fit
///
/// # Examples
///
@@ -2017,7 +2020,7 @@ impl<T, A: Allocator> Vec<T, A> {
///
/// # Panics
///
- /// Panics if the new capacity exceeds `isize::MAX` bytes.
+ /// Panics if the new capacity exceeds `isize::MAX` _bytes_.
///
/// # Examples
///
@@ -2133,7 +2136,7 @@ impl<T, A: Allocator> Vec<T, A> {
} else {
unsafe {
self.len -= 1;
- core::intrinsics::assume(self.len < self.capacity());
+ core::hint::assert_unchecked(self.len < self.capacity());
Some(ptr::read(self.as_ptr().add(self.len())))
}
}
@@ -2143,7 +2146,7 @@ impl<T, A: Allocator> Vec<T, A> {
///
/// # Panics
///
- /// Panics if the new capacity exceeds `isize::MAX` bytes.
+ /// Panics if the new capacity exceeds `isize::MAX` _bytes_.
///
/// # Examples
///
@@ -2315,6 +2318,12 @@ impl<T, A: Allocator> Vec<T, A> {
/// `[at, len)`. After the call, the original vector will be left containing
/// the elements `[0, at)` with its previous capacity unchanged.
///
+ /// - If you want to take ownership of the entire contents and capacity of
+ /// the vector, see [`mem::take`] or [`mem::replace`].
+ /// - If you don't need the returned vector at all, see [`Vec::truncate`].
+ /// - If you want to take ownership of an arbitrary subslice, or you don't
+ /// necessarily want to store the removed items in a vector, see [`Vec::drain`].
+ ///
/// # Panics
///
/// Panics if `at > len`.
@@ -2346,14 +2355,6 @@ impl<T, A: Allocator> Vec<T, A> {
assert_failed(at, self.len());
}
- if at == 0 {
- // the new vector can take over the original buffer and avoid the copy
- return mem::replace(
- self,
- Vec::with_capacity_in(self.capacity(), self.allocator().clone()),
- );
- }
-
let other_len = self.len - at;
let mut other = Vec::with_capacity_in(other_len, self.allocator().clone());
@@ -3027,6 +3028,50 @@ impl<T, I: SliceIndex<[T]>, A: Allocator> IndexMut<I> for Vec<T, A> {
}
}
+/// Collects an iterator into a Vec, commonly called via [`Iterator::collect()`]
+///
+/// # Allocation behavior
+///
+/// In general `Vec` does not guarantee any particular growth or allocation strategy.
+/// That also applies to this trait impl.
+///
+/// **Note:** This section covers implementation details and is therefore exempt from
+/// stability guarantees.
+///
+/// Vec may use any or none of the following strategies,
+/// depending on the supplied iterator:
+///
+/// * preallocate based on [`Iterator::size_hint()`]
+/// * and panic if the number of items is outside the provided lower/upper bounds
+/// * use an amortized growth strategy similar to `pushing` one item at a time
+/// * perform the iteration in-place on the original allocation backing the iterator
+///
+/// The last case warrants some attention. It is an optimization that in many cases reduces peak memory
+/// consumption and improves cache locality. But when big, short-lived allocations are created,
+/// only a small fraction of their items get collected, no further use is made of the spare capacity
+/// and the resulting `Vec` is moved into a longer-lived structure, then this can lead to the large
+/// allocations having their lifetimes unnecessarily extended which can result in increased memory
+/// footprint.
+///
+/// In cases where this is an issue, the excess capacity can be discarded with [`Vec::shrink_to()`],
+/// [`Vec::shrink_to_fit()`] or by collecting into [`Box<[T]>`][owned slice] instead, which additionally reduces
+/// the size of the long-lived struct.
+///
+/// [owned slice]: Box
+///
+/// ```rust
+/// # use std::sync::Mutex;
+/// static LONG_LIVED: Mutex<Vec<Vec<u16>>> = Mutex::new(Vec::new());
+///
+/// for i in 0..10 {
+/// let big_temporary: Vec<u16> = (0..1024).collect();
+/// // discard most items
+/// let mut result: Vec<_> = big_temporary.into_iter().filter(|i| i % 100 == 0).collect();
+/// // without this a lot of unused capacity might be moved into the global
+/// result.shrink_to_fit();
+/// LONG_LIVED.lock().unwrap().push(result);
+/// }
+/// ```
#[cfg(not(no_global_oom_handling))]
#[stable(feature = "rust1", since = "1.0.0")]
impl<T> FromIterator<T> for Vec<T> {
@@ -3069,14 +3114,8 @@ impl<T, A: Allocator> IntoIterator for Vec<T, A> {
begin.add(me.len()) as *const T
};
let cap = me.buf.capacity();
- IntoIter {
- buf: NonNull::new_unchecked(begin),
- phantom: PhantomData,
- cap,
- alloc,
- ptr: begin,
- end,
- }
+ let buf = NonNull::new_unchecked(begin);
+ IntoIter { buf, phantom: PhantomData, cap, alloc, ptr: buf, end }
}
}
}
@@ -3598,8 +3637,10 @@ impl<T, A: Allocator> From<Box<[T], A>> for Vec<T, A> {
impl<T, A: Allocator> From<Vec<T, A>> for Box<[T], A> {
/// Convert a vector into a boxed slice.
///
- /// If `v` has excess capacity, its items will be moved into a
- /// newly-allocated buffer with exactly the right capacity.
+ /// Before doing the conversion, this method discards excess capacity like [`Vec::shrink_to_fit`].
+ ///
+ /// [owned slice]: Box
+ /// [`Vec::shrink_to_fit`]: Vec::shrink_to_fit
///
/// # Examples
///
generated by cgit v1.2.3-58-ga151 (git 2.39.0) at 2024-11-22 09:12:47 +0000