alloc/vec/mod.rs
1//! A contiguous growable array type with heap-allocated contents, written
2//! `Vec<T>`.
3//!
4//! Vectors have *O*(1) indexing, amortized *O*(1) push (to the end) and
5//! *O*(1) pop (from the end).
6//!
7//! Vectors ensure they never allocate more than `isize::MAX` bytes.
8//!
9//! # Examples
10//!
11//! You can explicitly create a [`Vec`] with [`Vec::new`]:
12//!
13//! ```
14//! let v: Vec<i32> = Vec::new();
15//! ```
16//!
17//! ...or by using the [`vec!`] macro:
18//!
19//! ```
20//! let v: Vec<i32> = vec![];
21//!
22//! let v = vec![1, 2, 3, 4, 5];
23//!
24//! let v = vec![0; 10]; // ten zeroes
25//! ```
26//!
27//! You can [`push`] values onto the end of a vector (which will grow the vector
28//! as needed):
29//!
30//! ```
31//! let mut v = vec![1, 2];
32//!
33//! v.push(3);
34//! ```
35//!
36//! Popping values works in much the same way:
37//!
38//! ```
39//! let mut v = vec![1, 2];
40//!
41//! let two = v.pop();
42//! ```
43//!
44//! Vectors also support indexing (through the [`Index`] and [`IndexMut`] traits):
45//!
46//! ```
47//! let mut v = vec![1, 2, 3];
48//! let three = v[2];
49//! v[1] = v[1] + 5;
50//! ```
51//!
52//! # Memory layout
53//!
54//! When the type is non-zero-sized and the capacity is nonzero, [`Vec`] uses the [`Global`]
55//! allocator for its allocation. It is valid to convert both ways between such a [`Vec`] and a raw
56//! pointer allocated with the [`Global`] allocator, provided that the [`Layout`] used with the
57//! allocator is correct for a sequence of `capacity` elements of the type, and the first `len`
58//! values pointed to by the raw pointer are valid. More precisely, a `ptr: *mut T` that has been
59//! allocated with the [`Global`] allocator with [`Layout::array::<T>(capacity)`][Layout::array] may
60//! be converted into a vec using
61//! [`Vec::<T>::from_raw_parts(ptr, len, capacity)`](Vec::from_raw_parts). Conversely, the memory
62//! backing a `value: *mut T` obtained from [`Vec::<T>::as_mut_ptr`] may be deallocated using the
63//! [`Global`] allocator with the same layout.
64//!
65//! For zero-sized types (ZSTs), or when the capacity is zero, the `Vec` pointer must be non-null
66//! and sufficiently aligned. The recommended way to build a `Vec` of ZSTs if [`vec!`] cannot be
67//! used is to use [`ptr::NonNull::dangling`].
68//!
69//! [`push`]: Vec::push
70//! [`ptr::NonNull::dangling`]: NonNull::dangling
71//! [`Layout`]: crate::alloc::Layout
72//! [Layout::array]: crate::alloc::Layout::array
73
74#![stable(feature = "rust1", since = "1.0.0")]
75
76#[cfg(not(no_global_oom_handling))]
77use core::cmp;
78use core::cmp::Ordering;
79use core::hash::{Hash, Hasher};
80#[cfg(not(no_global_oom_handling))]
81use core::iter;
82use core::marker::PhantomData;
83use core::mem::{self, ManuallyDrop, MaybeUninit, SizedTypeProperties};
84use core::ops::{self, Index, IndexMut, Range, RangeBounds};
85use core::ptr::{self, NonNull};
86use core::slice::{self, SliceIndex};
87use core::{fmt, intrinsics, ub_checks};
88
89#[stable(feature = "extract_if", since = "1.87.0")]
90pub use self::extract_if::ExtractIf;
91use crate::alloc::{Allocator, Global};
92use crate::borrow::{Cow, ToOwned};
93use crate::boxed::Box;
94use crate::collections::TryReserveError;
95use crate::raw_vec::RawVec;
96
97mod extract_if;
98
99#[cfg(not(no_global_oom_handling))]
100#[stable(feature = "vec_splice", since = "1.21.0")]
101pub use self::splice::Splice;
102
103#[cfg(not(no_global_oom_handling))]
104mod splice;
105
106#[stable(feature = "drain", since = "1.6.0")]
107pub use self::drain::Drain;
108
109mod drain;
110
111#[cfg(not(no_global_oom_handling))]
112mod cow;
113
114#[cfg(not(no_global_oom_handling))]
115pub(crate) use self::in_place_collect::AsVecIntoIter;
116#[stable(feature = "rust1", since = "1.0.0")]
117pub use self::into_iter::IntoIter;
118
119mod into_iter;
120
121#[cfg(not(no_global_oom_handling))]
122use self::is_zero::IsZero;
123
124#[cfg(not(no_global_oom_handling))]
125mod is_zero;
126
127#[cfg(not(no_global_oom_handling))]
128mod in_place_collect;
129
130mod partial_eq;
131
132#[unstable(feature = "vec_peek_mut", issue = "122742")]
133pub use self::peek_mut::PeekMut;
134
135mod peek_mut;
136
137#[cfg(not(no_global_oom_handling))]
138use self::spec_from_elem::SpecFromElem;
139
140#[cfg(not(no_global_oom_handling))]
141mod spec_from_elem;
142
143#[cfg(not(no_global_oom_handling))]
144use self::set_len_on_drop::SetLenOnDrop;
145
146#[cfg(not(no_global_oom_handling))]
147mod set_len_on_drop;
148
149#[cfg(not(no_global_oom_handling))]
150use self::in_place_drop::{InPlaceDrop, InPlaceDstDataSrcBufDrop};
151
152#[cfg(not(no_global_oom_handling))]
153mod in_place_drop;
154
155#[cfg(not(no_global_oom_handling))]
156use self::spec_from_iter_nested::SpecFromIterNested;
157
158#[cfg(not(no_global_oom_handling))]
159mod spec_from_iter_nested;
160
161#[cfg(not(no_global_oom_handling))]
162use self::spec_from_iter::SpecFromIter;
163
164#[cfg(not(no_global_oom_handling))]
165mod spec_from_iter;
166
167#[cfg(not(no_global_oom_handling))]
168use self::spec_extend::SpecExtend;
169
170#[cfg(not(no_global_oom_handling))]
171mod spec_extend;
172
173/// A contiguous growable array type, written as `Vec<T>`, short for 'vector'.
174///
175/// # Examples
176///
177/// ```
178/// let mut vec = Vec::new();
179/// vec.push(1);
180/// vec.push(2);
181///
182/// assert_eq!(vec.len(), 2);
183/// assert_eq!(vec[0], 1);
184///
185/// assert_eq!(vec.pop(), Some(2));
186/// assert_eq!(vec.len(), 1);
187///
188/// vec[0] = 7;
189/// assert_eq!(vec[0], 7);
190///
191/// vec.extend([1, 2, 3]);
192///
193/// for x in &vec {
194/// println!("{x}");
195/// }
196/// assert_eq!(vec, [7, 1, 2, 3]);
197/// ```
198///
199/// The [`vec!`] macro is provided for convenient initialization:
200///
201/// ```
202/// let mut vec1 = vec![1, 2, 3];
203/// vec1.push(4);
204/// let vec2 = Vec::from([1, 2, 3, 4]);
205/// assert_eq!(vec1, vec2);
206/// ```
207///
208/// It can also initialize each element of a `Vec<T>` with a given value.
209/// This may be more efficient than performing allocation and initialization
210/// in separate steps, especially when initializing a vector of zeros:
211///
212/// ```
213/// let vec = vec![0; 5];
214/// assert_eq!(vec, [0, 0, 0, 0, 0]);
215///
216/// // The following is equivalent, but potentially slower:
217/// let mut vec = Vec::with_capacity(5);
218/// vec.resize(5, 0);
219/// assert_eq!(vec, [0, 0, 0, 0, 0]);
220/// ```
221///
222/// For more information, see
223/// [Capacity and Reallocation](#capacity-and-reallocation).
224///
225/// Use a `Vec<T>` as an efficient stack:
226///
227/// ```
228/// let mut stack = Vec::new();
229///
230/// stack.push(1);
231/// stack.push(2);
232/// stack.push(3);
233///
234/// while let Some(top) = stack.pop() {
235/// // Prints 3, 2, 1
236/// println!("{top}");
237/// }
238/// ```
239///
240/// # Indexing
241///
242/// The `Vec` type allows access to values by index, because it implements the
243/// [`Index`] trait. An example will be more explicit:
244///
245/// ```
246/// let v = vec![0, 2, 4, 6];
247/// println!("{}", v[1]); // it will display '2'
248/// ```
249///
250/// However be careful: if you try to access an index which isn't in the `Vec`,
251/// your software will panic! You cannot do this:
252///
253/// ```should_panic
254/// let v = vec![0, 2, 4, 6];
255/// println!("{}", v[6]); // it will panic!
256/// ```
257///
258/// Use [`get`] and [`get_mut`] if you want to check whether the index is in
259/// the `Vec`.
260///
261/// # Slicing
262///
263/// A `Vec` can be mutable. On the other hand, slices are read-only objects.
264/// To get a [slice][prim@slice], use [`&`]. Example:
265///
266/// ```
267/// fn read_slice(slice: &[usize]) {
268/// // ...
269/// }
270///
271/// let v = vec![0, 1];
272/// read_slice(&v);
273///
274/// // ... and that's all!
275/// // you can also do it like this:
276/// let u: &[usize] = &v;
277/// // or like this:
278/// let u: &[_] = &v;
279/// ```
280///
281/// In Rust, it's more common to pass slices as arguments rather than vectors
282/// when you just want to provide read access. The same goes for [`String`] and
283/// [`&str`].
284///
285/// # Capacity and reallocation
286///
287/// The capacity of a vector is the amount of space allocated for any future
288/// elements that will be added onto the vector. This is not to be confused with
289/// the *length* of a vector, which specifies the number of actual elements
290/// within the vector. If a vector's length exceeds its capacity, its capacity
291/// will automatically be increased, but its elements will have to be
292/// reallocated.
293///
294/// For example, a vector with capacity 10 and length 0 would be an empty vector
295/// with space for 10 more elements. Pushing 10 or fewer elements onto the
296/// vector will not change its capacity or cause reallocation to occur. However,
297/// if the vector's length is increased to 11, it will have to reallocate, which
298/// can be slow. For this reason, it is recommended to use [`Vec::with_capacity`]
299/// whenever possible to specify how big the vector is expected to get.
300///
301/// # Guarantees
302///
303/// Due to its incredibly fundamental nature, `Vec` makes a lot of guarantees
304/// about its design. This ensures that it's as low-overhead as possible in
305/// the general case, and can be correctly manipulated in primitive ways
306/// by unsafe code. Note that these guarantees refer to an unqualified `Vec<T>`.
307/// If additional type parameters are added (e.g., to support custom allocators),
308/// overriding their defaults may change the behavior.
309///
310/// Most fundamentally, `Vec` is and always will be a (pointer, capacity, length)
311/// triplet. No more, no less. The order of these fields is completely
312/// unspecified, and you should use the appropriate methods to modify these.
313/// The pointer will never be null, so this type is null-pointer-optimized.
314///
315/// However, the pointer might not actually point to allocated memory. In particular,
316/// if you construct a `Vec` with capacity 0 via [`Vec::new`], [`vec![]`][`vec!`],
317/// [`Vec::with_capacity(0)`][`Vec::with_capacity`], or by calling [`shrink_to_fit`]
318/// on an empty Vec, it will not allocate memory. Similarly, if you store zero-sized
319/// types inside a `Vec`, it will not allocate space for them. *Note that in this case
320/// the `Vec` might not report a [`capacity`] of 0*. `Vec` will allocate if and only
321/// if <code>[size_of::\<T>]\() * [capacity]\() > 0</code>. In general, `Vec`'s allocation
322/// details are very subtle --- if you intend to allocate memory using a `Vec`
323/// and use it for something else (either to pass to unsafe code, or to build your
324/// own memory-backed collection), be sure to deallocate this memory by using
325/// `from_raw_parts` to recover the `Vec` and then dropping it.
326///
327/// If a `Vec` *has* allocated memory, then the memory it points to is on the heap
328/// (as defined by the allocator Rust is configured to use by default), and its
329/// pointer points to [`len`] initialized, contiguous elements in order (what
330/// you would see if you coerced it to a slice), followed by <code>[capacity] - [len]</code>
331/// logically uninitialized, contiguous elements.
332///
333/// A vector containing the elements `'a'` and `'b'` with capacity 4 can be
334/// visualized as below. The top part is the `Vec` struct, it contains a
335/// pointer to the head of the allocation in the heap, length and capacity.
336/// The bottom part is the allocation on the heap, a contiguous memory block.
337///
338/// ```text
339/// ptr len capacity
340/// +--------+--------+--------+
341/// | 0x0123 | 2 | 4 |
342/// +--------+--------+--------+
343/// |
344/// v
345/// Heap +--------+--------+--------+--------+
346/// | 'a' | 'b' | uninit | uninit |
347/// +--------+--------+--------+--------+
348/// ```
349///
350/// - **uninit** represents memory that is not initialized, see [`MaybeUninit`].
351/// - Note: the ABI is not stable and `Vec` makes no guarantees about its memory
352/// layout (including the order of fields).
353///
354/// `Vec` will never perform a "small optimization" where elements are actually
355/// stored on the stack for two reasons:
356///
357/// * It would make it more difficult for unsafe code to correctly manipulate
358/// a `Vec`. The contents of a `Vec` wouldn't have a stable address if it were
359/// only moved, and it would be more difficult to determine if a `Vec` had
360/// actually allocated memory.
361///
362/// * It would penalize the general case, incurring an additional branch
363/// on every access.
364///
365/// `Vec` will never automatically shrink itself, even if completely empty. This
366/// ensures no unnecessary allocations or deallocations occur. Emptying a `Vec`
367/// and then filling it back up to the same [`len`] should incur no calls to
368/// the allocator. If you wish to free up unused memory, use
369/// [`shrink_to_fit`] or [`shrink_to`].
370///
371/// [`push`] and [`insert`] will never (re)allocate if the reported capacity is
372/// sufficient. [`push`] and [`insert`] *will* (re)allocate if
373/// <code>[len] == [capacity]</code>. That is, the reported capacity is completely
374/// accurate, and can be relied on. It can even be used to manually free the memory
375/// allocated by a `Vec` if desired. Bulk insertion methods *may* reallocate, even
376/// when not necessary.
377///
378/// `Vec` does not guarantee any particular growth strategy when reallocating
379/// when full, nor when [`reserve`] is called. The current strategy is basic
380/// and it may prove desirable to use a non-constant growth factor. Whatever
381/// strategy is used will of course guarantee *O*(1) amortized [`push`].
382///
383/// It is guaranteed, in order to respect the intentions of the programmer, that
384/// all of `vec![e_1, e_2, ..., e_n]`, `vec![x; n]`, and [`Vec::with_capacity(n)`] produce a `Vec`
385/// that requests an allocation of the exact size needed for precisely `n` elements from the allocator,
386/// and no other size (such as, for example: a size rounded up to the nearest power of 2).
387/// The allocator will return an allocation that is at least as large as requested, but it may be larger.
388///
389/// It is guaranteed that the [`Vec::capacity`] method returns a value that is at least the requested capacity
390/// and not more than the allocated capacity.
391///
392/// The method [`Vec::shrink_to_fit`] will attempt to discard excess capacity an allocator has given to a `Vec`.
393/// If <code>[len] == [capacity]</code>, then a `Vec<T>` can be converted
394/// to and from a [`Box<[T]>`][owned slice] without reallocating or moving the elements.
395/// `Vec` exploits this fact as much as reasonable when implementing common conversions
396/// such as [`into_boxed_slice`].
397///
398/// `Vec` will not specifically overwrite any data that is removed from it,
399/// but also won't specifically preserve it. Its uninitialized memory is
400/// scratch space that it may use however it wants. It will generally just do
401/// whatever is most efficient or otherwise easy to implement. Do not rely on
402/// removed data to be erased for security purposes. Even if you drop a `Vec`, its
403/// buffer may simply be reused by another allocation. Even if you zero a `Vec`'s memory
404/// first, that might not actually happen because the optimizer does not consider
405/// this a side-effect that must be preserved. There is one case which we will
406/// not break, however: using `unsafe` code to write to the excess capacity,
407/// and then increasing the length to match, is always valid.
408///
409/// Currently, `Vec` does not guarantee the order in which elements are dropped.
410/// The order has changed in the past and may change again.
411///
412/// [`get`]: slice::get
413/// [`get_mut`]: slice::get_mut
414/// [`String`]: crate::string::String
415/// [`&str`]: type@str
416/// [`shrink_to_fit`]: Vec::shrink_to_fit
417/// [`shrink_to`]: Vec::shrink_to
418/// [capacity]: Vec::capacity
419/// [`capacity`]: Vec::capacity
420/// [`Vec::capacity`]: Vec::capacity
421/// [size_of::\<T>]: size_of
422/// [len]: Vec::len
423/// [`len`]: Vec::len
424/// [`push`]: Vec::push
425/// [`insert`]: Vec::insert
426/// [`reserve`]: Vec::reserve
427/// [`Vec::with_capacity(n)`]: Vec::with_capacity
428/// [`MaybeUninit`]: core::mem::MaybeUninit
429/// [owned slice]: Box
430/// [`into_boxed_slice`]: Vec::into_boxed_slice
431#[stable(feature = "rust1", since = "1.0.0")]
432#[rustc_diagnostic_item = "Vec"]
433#[rustc_insignificant_dtor]
434pub struct Vec<T, #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator = Global> {
435 buf: RawVec<T, A>,
436 len: usize,
437}
438
439////////////////////////////////////////////////////////////////////////////////
440// Inherent methods
441////////////////////////////////////////////////////////////////////////////////
442
443impl<T> Vec<T> {
444 /// Constructs a new, empty `Vec<T>`.
445 ///
446 /// The vector will not allocate until elements are pushed onto it.
447 ///
448 /// # Examples
449 ///
450 /// ```
451 /// # #![allow(unused_mut)]
452 /// let mut vec: Vec<i32> = Vec::new();
453 /// ```
454 #[inline]
455 #[rustc_const_stable(feature = "const_vec_new", since = "1.39.0")]
456 #[rustc_diagnostic_item = "vec_new"]
457 #[stable(feature = "rust1", since = "1.0.0")]
458 #[must_use]
459 pub const fn new() -> Self {
460 Vec { buf: RawVec::new(), len: 0 }
461 }
462
463 /// Constructs a new, empty `Vec<T>` with at least the specified capacity.
464 ///
465 /// The vector will be able to hold at least `capacity` elements without
466 /// reallocating. This method is allowed to allocate for more elements than
467 /// `capacity`. If `capacity` is zero, the vector will not allocate.
468 ///
469 /// It is important to note that although the returned vector has the
470 /// minimum *capacity* specified, the vector will have a zero *length*. For
471 /// an explanation of the difference between length and capacity, see
472 /// *[Capacity and reallocation]*.
473 ///
474 /// If it is important to know the exact allocated capacity of a `Vec`,
475 /// always use the [`capacity`] method after construction.
476 ///
477 /// For `Vec<T>` where `T` is a zero-sized type, there will be no allocation
478 /// and the capacity will always be `usize::MAX`.
479 ///
480 /// [Capacity and reallocation]: #capacity-and-reallocation
481 /// [`capacity`]: Vec::capacity
482 ///
483 /// # Panics
484 ///
485 /// Panics if the new capacity exceeds `isize::MAX` _bytes_.
486 ///
487 /// # Examples
488 ///
489 /// ```
490 /// let mut vec = Vec::with_capacity(10);
491 ///
492 /// // The vector contains no items, even though it has capacity for more
493 /// assert_eq!(vec.len(), 0);
494 /// assert!(vec.capacity() >= 10);
495 ///
496 /// // These are all done without reallocating...
497 /// for i in 0..10 {
498 /// vec.push(i);
499 /// }
500 /// assert_eq!(vec.len(), 10);
501 /// assert!(vec.capacity() >= 10);
502 ///
503 /// // ...but this may make the vector reallocate
504 /// vec.push(11);
505 /// assert_eq!(vec.len(), 11);
506 /// assert!(vec.capacity() >= 11);
507 ///
508 /// // A vector of a zero-sized type will always over-allocate, since no
509 /// // allocation is necessary
510 /// let vec_units = Vec::<()>::with_capacity(10);
511 /// assert_eq!(vec_units.capacity(), usize::MAX);
512 /// ```
513 #[cfg(not(no_global_oom_handling))]
514 #[inline]
515 #[stable(feature = "rust1", since = "1.0.0")]
516 #[must_use]
517 #[rustc_diagnostic_item = "vec_with_capacity"]
518 #[track_caller]
519 pub fn with_capacity(capacity: usize) -> Self {
520 Self::with_capacity_in(capacity, Global)
521 }
522
523 /// Constructs a new, empty `Vec<T>` with at least the specified capacity.
524 ///
525 /// The vector will be able to hold at least `capacity` elements without
526 /// reallocating. This method is allowed to allocate for more elements than
527 /// `capacity`. If `capacity` is zero, the vector will not allocate.
528 ///
529 /// # Errors
530 ///
531 /// Returns an error if the capacity exceeds `isize::MAX` _bytes_,
532 /// or if the allocator reports allocation failure.
533 #[inline]
534 #[unstable(feature = "try_with_capacity", issue = "91913")]
535 pub fn try_with_capacity(capacity: usize) -> Result<Self, TryReserveError> {
536 Self::try_with_capacity_in(capacity, Global)
537 }
538
539 /// Creates a `Vec<T>` directly from a pointer, a length, and a capacity.
540 ///
541 /// # Safety
542 ///
543 /// This is highly unsafe, due to the number of invariants that aren't
544 /// checked:
545 ///
546 /// * If `T` is not a zero-sized type and the capacity is nonzero, `ptr` must have
547 /// been allocated using the global allocator, such as via the [`alloc::alloc`]
548 /// function. If `T` is a zero-sized type or the capacity is zero, `ptr` need
549 /// only be non-null and aligned.
550 /// * `T` needs to have the same alignment as what `ptr` was allocated with,
551 /// if the pointer is required to be allocated.
552 /// (`T` having a less strict alignment is not sufficient, the alignment really
553 /// needs to be equal to satisfy the [`dealloc`] requirement that memory must be
554 /// allocated and deallocated with the same layout.)
555 /// * The size of `T` times the `capacity` (ie. the allocated size in bytes), if
556 /// nonzero, needs to be the same size as the pointer was allocated with.
557 /// (Because similar to alignment, [`dealloc`] must be called with the same
558 /// layout `size`.)
559 /// * `length` needs to be less than or equal to `capacity`.
560 /// * The first `length` values must be properly initialized values of type `T`.
561 /// * `capacity` needs to be the capacity that the pointer was allocated with,
562 /// if the pointer is required to be allocated.
563 /// * The allocated size in bytes must be no larger than `isize::MAX`.
564 /// See the safety documentation of [`pointer::offset`].
565 ///
566 /// These requirements are always upheld by any `ptr` that has been allocated
567 /// via `Vec<T>`. Other allocation sources are allowed if the invariants are
568 /// upheld.
569 ///
570 /// Violating these may cause problems like corrupting the allocator's
571 /// internal data structures. For example it is normally **not** safe
572 /// to build a `Vec<u8>` from a pointer to a C `char` array with length
573 /// `size_t`, doing so is only safe if the array was initially allocated by
574 /// a `Vec` or `String`.
575 /// It's also not safe to build one from a `Vec<u16>` and its length, because
576 /// the allocator cares about the alignment, and these two types have different
577 /// alignments. The buffer was allocated with alignment 2 (for `u16`), but after
578 /// turning it into a `Vec<u8>` it'll be deallocated with alignment 1. To avoid
579 /// these issues, it is often preferable to do casting/transmuting using
580 /// [`slice::from_raw_parts`] instead.
581 ///
582 /// The ownership of `ptr` is effectively transferred to the
583 /// `Vec<T>` which may then deallocate, reallocate or change the
584 /// contents of memory pointed to by the pointer at will. Ensure
585 /// that nothing else uses the pointer after calling this
586 /// function.
587 ///
588 /// [`String`]: crate::string::String
589 /// [`alloc::alloc`]: crate::alloc::alloc
590 /// [`dealloc`]: crate::alloc::GlobalAlloc::dealloc
591 ///
592 /// # Examples
593 ///
594 // FIXME Update this when vec_into_raw_parts is stabilized
595 /// ```
596 /// use std::ptr;
597 /// use std::mem;
598 ///
599 /// let v = vec![1, 2, 3];
600 ///
601 /// // Prevent running `v`'s destructor so we are in complete control
602 /// // of the allocation.
603 /// let mut v = mem::ManuallyDrop::new(v);
604 ///
605 /// // Pull out the various important pieces of information about `v`
606 /// let p = v.as_mut_ptr();
607 /// let len = v.len();
608 /// let cap = v.capacity();
609 ///
610 /// unsafe {
611 /// // Overwrite memory with 4, 5, 6
612 /// for i in 0..len {
613 /// ptr::write(p.add(i), 4 + i);
614 /// }
615 ///
616 /// // Put everything back together into a Vec
617 /// let rebuilt = Vec::from_raw_parts(p, len, cap);
618 /// assert_eq!(rebuilt, [4, 5, 6]);
619 /// }
620 /// ```
621 ///
622 /// Using memory that was allocated elsewhere:
623 ///
624 /// ```rust
625 /// use std::alloc::{alloc, Layout};
626 ///
627 /// fn main() {
628 /// let layout = Layout::array::<u32>(16).expect("overflow cannot happen");
629 ///
630 /// let vec = unsafe {
631 /// let mem = alloc(layout).cast::<u32>();
632 /// if mem.is_null() {
633 /// return;
634 /// }
635 ///
636 /// mem.write(1_000_000);
637 ///
638 /// Vec::from_raw_parts(mem, 1, 16)
639 /// };
640 ///
641 /// assert_eq!(vec, &[1_000_000]);
642 /// assert_eq!(vec.capacity(), 16);
643 /// }
644 /// ```
645 #[inline]
646 #[stable(feature = "rust1", since = "1.0.0")]
647 pub unsafe fn from_raw_parts(ptr: *mut T, length: usize, capacity: usize) -> Self {
648 unsafe { Self::from_raw_parts_in(ptr, length, capacity, Global) }
649 }
650
651 #[doc(alias = "from_non_null_parts")]
652 /// Creates a `Vec<T>` directly from a `NonNull` pointer, a length, and a capacity.
653 ///
654 /// # Safety
655 ///
656 /// This is highly unsafe, due to the number of invariants that aren't
657 /// checked:
658 ///
659 /// * `ptr` must have been allocated using the global allocator, such as via
660 /// the [`alloc::alloc`] function.
661 /// * `T` needs to have the same alignment as what `ptr` was allocated with.
662 /// (`T` having a less strict alignment is not sufficient, the alignment really
663 /// needs to be equal to satisfy the [`dealloc`] requirement that memory must be
664 /// allocated and deallocated with the same layout.)
665 /// * The size of `T` times the `capacity` (ie. the allocated size in bytes) needs
666 /// to be the same size as the pointer was allocated with. (Because similar to
667 /// alignment, [`dealloc`] must be called with the same layout `size`.)
668 /// * `length` needs to be less than or equal to `capacity`.
669 /// * The first `length` values must be properly initialized values of type `T`.
670 /// * `capacity` needs to be the capacity that the pointer was allocated with.
671 /// * The allocated size in bytes must be no larger than `isize::MAX`.
672 /// See the safety documentation of [`pointer::offset`].
673 ///
674 /// These requirements are always upheld by any `ptr` that has been allocated
675 /// via `Vec<T>`. Other allocation sources are allowed if the invariants are
676 /// upheld.
677 ///
678 /// Violating these may cause problems like corrupting the allocator's
679 /// internal data structures. For example it is normally **not** safe
680 /// to build a `Vec<u8>` from a pointer to a C `char` array with length
681 /// `size_t`, doing so is only safe if the array was initially allocated by
682 /// a `Vec` or `String`.
683 /// It's also not safe to build one from a `Vec<u16>` and its length, because
684 /// the allocator cares about the alignment, and these two types have different
685 /// alignments. The buffer was allocated with alignment 2 (for `u16`), but after
686 /// turning it into a `Vec<u8>` it'll be deallocated with alignment 1. To avoid
687 /// these issues, it is often preferable to do casting/transmuting using
688 /// [`NonNull::slice_from_raw_parts`] instead.
689 ///
690 /// The ownership of `ptr` is effectively transferred to the
691 /// `Vec<T>` which may then deallocate, reallocate or change the
692 /// contents of memory pointed to by the pointer at will. Ensure
693 /// that nothing else uses the pointer after calling this
694 /// function.
695 ///
696 /// [`String`]: crate::string::String
697 /// [`alloc::alloc`]: crate::alloc::alloc
698 /// [`dealloc`]: crate::alloc::GlobalAlloc::dealloc
699 ///
700 /// # Examples
701 ///
702 // FIXME Update this when vec_into_raw_parts is stabilized
703 /// ```
704 /// #![feature(box_vec_non_null)]
705 ///
706 /// use std::ptr::NonNull;
707 /// use std::mem;
708 ///
709 /// let v = vec![1, 2, 3];
710 ///
711 /// // Prevent running `v`'s destructor so we are in complete control
712 /// // of the allocation.
713 /// let mut v = mem::ManuallyDrop::new(v);
714 ///
715 /// // Pull out the various important pieces of information about `v`
716 /// let p = unsafe { NonNull::new_unchecked(v.as_mut_ptr()) };
717 /// let len = v.len();
718 /// let cap = v.capacity();
719 ///
720 /// unsafe {
721 /// // Overwrite memory with 4, 5, 6
722 /// for i in 0..len {
723 /// p.add(i).write(4 + i);
724 /// }
725 ///
726 /// // Put everything back together into a Vec
727 /// let rebuilt = Vec::from_parts(p, len, cap);
728 /// assert_eq!(rebuilt, [4, 5, 6]);
729 /// }
730 /// ```
731 ///
732 /// Using memory that was allocated elsewhere:
733 ///
734 /// ```rust
735 /// #![feature(box_vec_non_null)]
736 ///
737 /// use std::alloc::{alloc, Layout};
738 /// use std::ptr::NonNull;
739 ///
740 /// fn main() {
741 /// let layout = Layout::array::<u32>(16).expect("overflow cannot happen");
742 ///
743 /// let vec = unsafe {
744 /// let Some(mem) = NonNull::new(alloc(layout).cast::<u32>()) else {
745 /// return;
746 /// };
747 ///
748 /// mem.write(1_000_000);
749 ///
750 /// Vec::from_parts(mem, 1, 16)
751 /// };
752 ///
753 /// assert_eq!(vec, &[1_000_000]);
754 /// assert_eq!(vec.capacity(), 16);
755 /// }
756 /// ```
757 #[inline]
758 #[unstable(feature = "box_vec_non_null", reason = "new API", issue = "130364")]
759 pub unsafe fn from_parts(ptr: NonNull<T>, length: usize, capacity: usize) -> Self {
760 unsafe { Self::from_parts_in(ptr, length, capacity, Global) }
761 }
762
763 /// Decomposes a `Vec<T>` into its raw components: `(pointer, length, capacity)`.
764 ///
765 /// Returns the raw pointer to the underlying data, the length of
766 /// the vector (in elements), and the allocated capacity of the
767 /// data (in elements). These are the same arguments in the same
768 /// order as the arguments to [`from_raw_parts`].
769 ///
770 /// After calling this function, the caller is responsible for the
771 /// memory previously managed by the `Vec`. Most often, one does
772 /// this by converting the raw pointer, length, and capacity back
773 /// into a `Vec` with the [`from_raw_parts`] function; more generally,
774 /// if `T` is non-zero-sized and the capacity is nonzero, one may use
775 /// any method that calls [`dealloc`] with a layout of
776 /// `Layout::array::<T>(capacity)`; if `T` is zero-sized or the
777 /// capacity is zero, nothing needs to be done.
778 ///
779 /// [`from_raw_parts`]: Vec::from_raw_parts
780 /// [`dealloc`]: crate::alloc::GlobalAlloc::dealloc
781 ///
782 /// # Examples
783 ///
784 /// ```
785 /// #![feature(vec_into_raw_parts)]
786 /// let v: Vec<i32> = vec![-1, 0, 1];
787 ///
788 /// let (ptr, len, cap) = v.into_raw_parts();
789 ///
790 /// let rebuilt = unsafe {
791 /// // We can now make changes to the components, such as
792 /// // transmuting the raw pointer to a compatible type.
793 /// let ptr = ptr as *mut u32;
794 ///
795 /// Vec::from_raw_parts(ptr, len, cap)
796 /// };
797 /// assert_eq!(rebuilt, [4294967295, 0, 1]);
798 /// ```
799 #[must_use = "losing the pointer will leak memory"]
800 #[unstable(feature = "vec_into_raw_parts", reason = "new API", issue = "65816")]
801 pub fn into_raw_parts(self) -> (*mut T, usize, usize) {
802 let mut me = ManuallyDrop::new(self);
803 (me.as_mut_ptr(), me.len(), me.capacity())
804 }
805
806 #[doc(alias = "into_non_null_parts")]
807 /// Decomposes a `Vec<T>` into its raw components: `(NonNull pointer, length, capacity)`.
808 ///
809 /// Returns the `NonNull` pointer to the underlying data, the length of
810 /// the vector (in elements), and the allocated capacity of the
811 /// data (in elements). These are the same arguments in the same
812 /// order as the arguments to [`from_parts`].
813 ///
814 /// After calling this function, the caller is responsible for the
815 /// memory previously managed by the `Vec`. The only way to do
816 /// this is to convert the `NonNull` pointer, length, and capacity back
817 /// into a `Vec` with the [`from_parts`] function, allowing
818 /// the destructor to perform the cleanup.
819 ///
820 /// [`from_parts`]: Vec::from_parts
821 ///
822 /// # Examples
823 ///
824 /// ```
825 /// #![feature(vec_into_raw_parts, box_vec_non_null)]
826 ///
827 /// let v: Vec<i32> = vec![-1, 0, 1];
828 ///
829 /// let (ptr, len, cap) = v.into_parts();
830 ///
831 /// let rebuilt = unsafe {
832 /// // We can now make changes to the components, such as
833 /// // transmuting the raw pointer to a compatible type.
834 /// let ptr = ptr.cast::<u32>();
835 ///
836 /// Vec::from_parts(ptr, len, cap)
837 /// };
838 /// assert_eq!(rebuilt, [4294967295, 0, 1]);
839 /// ```
840 #[must_use = "losing the pointer will leak memory"]
841 #[unstable(feature = "box_vec_non_null", reason = "new API", issue = "130364")]
842 // #[unstable(feature = "vec_into_raw_parts", reason = "new API", issue = "65816")]
843 pub fn into_parts(self) -> (NonNull<T>, usize, usize) {
844 let (ptr, len, capacity) = self.into_raw_parts();
845 // SAFETY: A `Vec` always has a non-null pointer.
846 (unsafe { NonNull::new_unchecked(ptr) }, len, capacity)
847 }
848}
849
850impl<T, A: Allocator> Vec<T, A> {
851 /// Constructs a new, empty `Vec<T, A>`.
852 ///
853 /// The vector will not allocate until elements are pushed onto it.
854 ///
855 /// # Examples
856 ///
857 /// ```
858 /// #![feature(allocator_api)]
859 ///
860 /// use std::alloc::System;
861 ///
862 /// # #[allow(unused_mut)]
863 /// let mut vec: Vec<i32, _> = Vec::new_in(System);
864 /// ```
865 #[inline]
866 #[unstable(feature = "allocator_api", issue = "32838")]
867 pub const fn new_in(alloc: A) -> Self {
868 Vec { buf: RawVec::new_in(alloc), len: 0 }
869 }
870
871 /// Constructs a new, empty `Vec<T, A>` with at least the specified capacity
872 /// with the provided allocator.
873 ///
874 /// The vector will be able to hold at least `capacity` elements without
875 /// reallocating. This method is allowed to allocate for more elements than
876 /// `capacity`. If `capacity` is zero, the vector will not allocate.
877 ///
878 /// It is important to note that although the returned vector has the
879 /// minimum *capacity* specified, the vector will have a zero *length*. For
880 /// an explanation of the difference between length and capacity, see
881 /// *[Capacity and reallocation]*.
882 ///
883 /// If it is important to know the exact allocated capacity of a `Vec`,
884 /// always use the [`capacity`] method after construction.
885 ///
886 /// For `Vec<T, A>` where `T` is a zero-sized type, there will be no allocation
887 /// and the capacity will always be `usize::MAX`.
888 ///
889 /// [Capacity and reallocation]: #capacity-and-reallocation
890 /// [`capacity`]: Vec::capacity
891 ///
892 /// # Panics
893 ///
894 /// Panics if the new capacity exceeds `isize::MAX` _bytes_.
895 ///
896 /// # Examples
897 ///
898 /// ```
899 /// #![feature(allocator_api)]
900 ///
901 /// use std::alloc::System;
902 ///
903 /// let mut vec = Vec::with_capacity_in(10, System);
904 ///
905 /// // The vector contains no items, even though it has capacity for more
906 /// assert_eq!(vec.len(), 0);
907 /// assert!(vec.capacity() >= 10);
908 ///
909 /// // These are all done without reallocating...
910 /// for i in 0..10 {
911 /// vec.push(i);
912 /// }
913 /// assert_eq!(vec.len(), 10);
914 /// assert!(vec.capacity() >= 10);
915 ///
916 /// // ...but this may make the vector reallocate
917 /// vec.push(11);
918 /// assert_eq!(vec.len(), 11);
919 /// assert!(vec.capacity() >= 11);
920 ///
921 /// // A vector of a zero-sized type will always over-allocate, since no
922 /// // allocation is necessary
923 /// let vec_units = Vec::<(), System>::with_capacity_in(10, System);
924 /// assert_eq!(vec_units.capacity(), usize::MAX);
925 /// ```
926 #[cfg(not(no_global_oom_handling))]
927 #[inline]
928 #[unstable(feature = "allocator_api", issue = "32838")]
929 #[track_caller]
930 pub fn with_capacity_in(capacity: usize, alloc: A) -> Self {
931 Vec { buf: RawVec::with_capacity_in(capacity, alloc), len: 0 }
932 }
933
934 /// Constructs a new, empty `Vec<T, A>` with at least the specified capacity
935 /// with the provided allocator.
936 ///
937 /// The vector will be able to hold at least `capacity` elements without
938 /// reallocating. This method is allowed to allocate for more elements than
939 /// `capacity`. If `capacity` is zero, the vector will not allocate.
940 ///
941 /// # Errors
942 ///
943 /// Returns an error if the capacity exceeds `isize::MAX` _bytes_,
944 /// or if the allocator reports allocation failure.
945 #[inline]
946 #[unstable(feature = "allocator_api", issue = "32838")]
947 // #[unstable(feature = "try_with_capacity", issue = "91913")]
948 pub fn try_with_capacity_in(capacity: usize, alloc: A) -> Result<Self, TryReserveError> {
949 Ok(Vec { buf: RawVec::try_with_capacity_in(capacity, alloc)?, len: 0 })
950 }
951
952 /// Creates a `Vec<T, A>` directly from a pointer, a length, a capacity,
953 /// and an allocator.
954 ///
955 /// # Safety
956 ///
957 /// This is highly unsafe, due to the number of invariants that aren't
958 /// checked:
959 ///
960 /// * `ptr` must be [*currently allocated*] via the given allocator `alloc`.
961 /// * `T` needs to have the same alignment as what `ptr` was allocated with.
962 /// (`T` having a less strict alignment is not sufficient, the alignment really
963 /// needs to be equal to satisfy the [`dealloc`] requirement that memory must be
964 /// allocated and deallocated with the same layout.)
965 /// * The size of `T` times the `capacity` (ie. the allocated size in bytes) needs
966 /// to be the same size as the pointer was allocated with. (Because similar to
967 /// alignment, [`dealloc`] must be called with the same layout `size`.)
968 /// * `length` needs to be less than or equal to `capacity`.
969 /// * The first `length` values must be properly initialized values of type `T`.
970 /// * `capacity` needs to [*fit*] the layout size that the pointer was allocated with.
971 /// * The allocated size in bytes must be no larger than `isize::MAX`.
972 /// See the safety documentation of [`pointer::offset`].
973 ///
974 /// These requirements are always upheld by any `ptr` that has been allocated
975 /// via `Vec<T, A>`. Other allocation sources are allowed if the invariants are
976 /// upheld.
977 ///
978 /// Violating these may cause problems like corrupting the allocator's
979 /// internal data structures. For example it is **not** safe
980 /// to build a `Vec<u8>` from a pointer to a C `char` array with length `size_t`.
981 /// It's also not safe to build one from a `Vec<u16>` and its length, because
982 /// the allocator cares about the alignment, and these two types have different
983 /// alignments. The buffer was allocated with alignment 2 (for `u16`), but after
984 /// turning it into a `Vec<u8>` it'll be deallocated with alignment 1.
985 ///
986 /// The ownership of `ptr` is effectively transferred to the
987 /// `Vec<T>` which may then deallocate, reallocate or change the
988 /// contents of memory pointed to by the pointer at will. Ensure
989 /// that nothing else uses the pointer after calling this
990 /// function.
991 ///
992 /// [`String`]: crate::string::String
993 /// [`dealloc`]: crate::alloc::GlobalAlloc::dealloc
994 /// [*currently allocated*]: crate::alloc::Allocator#currently-allocated-memory
995 /// [*fit*]: crate::alloc::Allocator#memory-fitting
996 ///
997 /// # Examples
998 ///
999 // FIXME Update this when vec_into_raw_parts is stabilized
1000 /// ```
1001 /// #![feature(allocator_api)]
1002 ///
1003 /// use std::alloc::System;
1004 ///
1005 /// use std::ptr;
1006 /// use std::mem;
1007 ///
1008 /// let mut v = Vec::with_capacity_in(3, System);
1009 /// v.push(1);
1010 /// v.push(2);
1011 /// v.push(3);
1012 ///
1013 /// // Prevent running `v`'s destructor so we are in complete control
1014 /// // of the allocation.
1015 /// let mut v = mem::ManuallyDrop::new(v);
1016 ///
1017 /// // Pull out the various important pieces of information about `v`
1018 /// let p = v.as_mut_ptr();
1019 /// let len = v.len();
1020 /// let cap = v.capacity();
1021 /// let alloc = v.allocator();
1022 ///
1023 /// unsafe {
1024 /// // Overwrite memory with 4, 5, 6
1025 /// for i in 0..len {
1026 /// ptr::write(p.add(i), 4 + i);
1027 /// }
1028 ///
1029 /// // Put everything back together into a Vec
1030 /// let rebuilt = Vec::from_raw_parts_in(p, len, cap, alloc.clone());
1031 /// assert_eq!(rebuilt, [4, 5, 6]);
1032 /// }
1033 /// ```
1034 ///
1035 /// Using memory that was allocated elsewhere:
1036 ///
1037 /// ```rust
1038 /// #![feature(allocator_api)]
1039 ///
1040 /// use std::alloc::{AllocError, Allocator, Global, Layout};
1041 ///
1042 /// fn main() {
1043 /// let layout = Layout::array::<u32>(16).expect("overflow cannot happen");
1044 ///
1045 /// let vec = unsafe {
1046 /// let mem = match Global.allocate(layout) {
1047 /// Ok(mem) => mem.cast::<u32>().as_ptr(),
1048 /// Err(AllocError) => return,
1049 /// };
1050 ///
1051 /// mem.write(1_000_000);
1052 ///
1053 /// Vec::from_raw_parts_in(mem, 1, 16, Global)
1054 /// };
1055 ///
1056 /// assert_eq!(vec, &[1_000_000]);
1057 /// assert_eq!(vec.capacity(), 16);
1058 /// }
1059 /// ```
1060 #[inline]
1061 #[unstable(feature = "allocator_api", issue = "32838")]
1062 pub unsafe fn from_raw_parts_in(ptr: *mut T, length: usize, capacity: usize, alloc: A) -> Self {
1063 ub_checks::assert_unsafe_precondition!(
1064 check_library_ub,
1065 "Vec::from_raw_parts_in requires that length <= capacity",
1066 (length: usize = length, capacity: usize = capacity) => length <= capacity
1067 );
1068 unsafe { Vec { buf: RawVec::from_raw_parts_in(ptr, capacity, alloc), len: length } }
1069 }
1070
1071 #[doc(alias = "from_non_null_parts_in")]
1072 /// Creates a `Vec<T, A>` directly from a `NonNull` pointer, a length, a capacity,
1073 /// and an allocator.
1074 ///
1075 /// # Safety
1076 ///
1077 /// This is highly unsafe, due to the number of invariants that aren't
1078 /// checked:
1079 ///
1080 /// * `ptr` must be [*currently allocated*] via the given allocator `alloc`.
1081 /// * `T` needs to have the same alignment as what `ptr` was allocated with.
1082 /// (`T` having a less strict alignment is not sufficient, the alignment really
1083 /// needs to be equal to satisfy the [`dealloc`] requirement that memory must be
1084 /// allocated and deallocated with the same layout.)
1085 /// * The size of `T` times the `capacity` (ie. the allocated size in bytes) needs
1086 /// to be the same size as the pointer was allocated with. (Because similar to
1087 /// alignment, [`dealloc`] must be called with the same layout `size`.)
1088 /// * `length` needs to be less than or equal to `capacity`.
1089 /// * The first `length` values must be properly initialized values of type `T`.
1090 /// * `capacity` needs to [*fit*] the layout size that the pointer was allocated with.
1091 /// * The allocated size in bytes must be no larger than `isize::MAX`.
1092 /// See the safety documentation of [`pointer::offset`].
1093 ///
1094 /// These requirements are always upheld by any `ptr` that has been allocated
1095 /// via `Vec<T, A>`. Other allocation sources are allowed if the invariants are
1096 /// upheld.
1097 ///
1098 /// Violating these may cause problems like corrupting the allocator's
1099 /// internal data structures. For example it is **not** safe
1100 /// to build a `Vec<u8>` from a pointer to a C `char` array with length `size_t`.
1101 /// It's also not safe to build one from a `Vec<u16>` and its length, because
1102 /// the allocator cares about the alignment, and these two types have different
1103 /// alignments. The buffer was allocated with alignment 2 (for `u16`), but after
1104 /// turning it into a `Vec<u8>` it'll be deallocated with alignment 1.
1105 ///
1106 /// The ownership of `ptr` is effectively transferred to the
1107 /// `Vec<T>` which may then deallocate, reallocate or change the
1108 /// contents of memory pointed to by the pointer at will. Ensure
1109 /// that nothing else uses the pointer after calling this
1110 /// function.
1111 ///
1112 /// [`String`]: crate::string::String
1113 /// [`dealloc`]: crate::alloc::GlobalAlloc::dealloc
1114 /// [*currently allocated*]: crate::alloc::Allocator#currently-allocated-memory
1115 /// [*fit*]: crate::alloc::Allocator#memory-fitting
1116 ///
1117 /// # Examples
1118 ///
1119 // FIXME Update this when vec_into_raw_parts is stabilized
1120 /// ```
1121 /// #![feature(allocator_api, box_vec_non_null)]
1122 ///
1123 /// use std::alloc::System;
1124 ///
1125 /// use std::ptr::NonNull;
1126 /// use std::mem;
1127 ///
1128 /// let mut v = Vec::with_capacity_in(3, System);
1129 /// v.push(1);
1130 /// v.push(2);
1131 /// v.push(3);
1132 ///
1133 /// // Prevent running `v`'s destructor so we are in complete control
1134 /// // of the allocation.
1135 /// let mut v = mem::ManuallyDrop::new(v);
1136 ///
1137 /// // Pull out the various important pieces of information about `v`
1138 /// let p = unsafe { NonNull::new_unchecked(v.as_mut_ptr()) };
1139 /// let len = v.len();
1140 /// let cap = v.capacity();
1141 /// let alloc = v.allocator();
1142 ///
1143 /// unsafe {
1144 /// // Overwrite memory with 4, 5, 6
1145 /// for i in 0..len {
1146 /// p.add(i).write(4 + i);
1147 /// }
1148 ///
1149 /// // Put everything back together into a Vec
1150 /// let rebuilt = Vec::from_parts_in(p, len, cap, alloc.clone());
1151 /// assert_eq!(rebuilt, [4, 5, 6]);
1152 /// }
1153 /// ```
1154 ///
1155 /// Using memory that was allocated elsewhere:
1156 ///
1157 /// ```rust
1158 /// #![feature(allocator_api, box_vec_non_null)]
1159 ///
1160 /// use std::alloc::{AllocError, Allocator, Global, Layout};
1161 ///
1162 /// fn main() {
1163 /// let layout = Layout::array::<u32>(16).expect("overflow cannot happen");
1164 ///
1165 /// let vec = unsafe {
1166 /// let mem = match Global.allocate(layout) {
1167 /// Ok(mem) => mem.cast::<u32>(),
1168 /// Err(AllocError) => return,
1169 /// };
1170 ///
1171 /// mem.write(1_000_000);
1172 ///
1173 /// Vec::from_parts_in(mem, 1, 16, Global)
1174 /// };
1175 ///
1176 /// assert_eq!(vec, &[1_000_000]);
1177 /// assert_eq!(vec.capacity(), 16);
1178 /// }
1179 /// ```
1180 #[inline]
1181 #[unstable(feature = "allocator_api", reason = "new API", issue = "32838")]
1182 // #[unstable(feature = "box_vec_non_null", issue = "130364")]
1183 pub unsafe fn from_parts_in(ptr: NonNull<T>, length: usize, capacity: usize, alloc: A) -> Self {
1184 ub_checks::assert_unsafe_precondition!(
1185 check_library_ub,
1186 "Vec::from_parts_in requires that length <= capacity",
1187 (length: usize = length, capacity: usize = capacity) => length <= capacity
1188 );
1189 unsafe { Vec { buf: RawVec::from_nonnull_in(ptr, capacity, alloc), len: length } }
1190 }
1191
1192 /// Decomposes a `Vec<T>` into its raw components: `(pointer, length, capacity, allocator)`.
1193 ///
1194 /// Returns the raw pointer to the underlying data, the length of the vector (in elements),
1195 /// the allocated capacity of the data (in elements), and the allocator. These are the same
1196 /// arguments in the same order as the arguments to [`from_raw_parts_in`].
1197 ///
1198 /// After calling this function, the caller is responsible for the
1199 /// memory previously managed by the `Vec`. The only way to do
1200 /// this is to convert the raw pointer, length, and capacity back
1201 /// into a `Vec` with the [`from_raw_parts_in`] function, allowing
1202 /// the destructor to perform the cleanup.
1203 ///
1204 /// [`from_raw_parts_in`]: Vec::from_raw_parts_in
1205 ///
1206 /// # Examples
1207 ///
1208 /// ```
1209 /// #![feature(allocator_api, vec_into_raw_parts)]
1210 ///
1211 /// use std::alloc::System;
1212 ///
1213 /// let mut v: Vec<i32, System> = Vec::new_in(System);
1214 /// v.push(-1);
1215 /// v.push(0);
1216 /// v.push(1);
1217 ///
1218 /// let (ptr, len, cap, alloc) = v.into_raw_parts_with_alloc();
1219 ///
1220 /// let rebuilt = unsafe {
1221 /// // We can now make changes to the components, such as
1222 /// // transmuting the raw pointer to a compatible type.
1223 /// let ptr = ptr as *mut u32;
1224 ///
1225 /// Vec::from_raw_parts_in(ptr, len, cap, alloc)
1226 /// };
1227 /// assert_eq!(rebuilt, [4294967295, 0, 1]);
1228 /// ```
1229 #[must_use = "losing the pointer will leak memory"]
1230 #[unstable(feature = "allocator_api", issue = "32838")]
1231 // #[unstable(feature = "vec_into_raw_parts", reason = "new API", issue = "65816")]
1232 pub fn into_raw_parts_with_alloc(self) -> (*mut T, usize, usize, A) {
1233 let mut me = ManuallyDrop::new(self);
1234 let len = me.len();
1235 let capacity = me.capacity();
1236 let ptr = me.as_mut_ptr();
1237 let alloc = unsafe { ptr::read(me.allocator()) };
1238 (ptr, len, capacity, alloc)
1239 }
1240
1241 #[doc(alias = "into_non_null_parts_with_alloc")]
1242 /// Decomposes a `Vec<T>` into its raw components: `(NonNull pointer, length, capacity, allocator)`.
1243 ///
1244 /// Returns the `NonNull` pointer to the underlying data, the length of the vector (in elements),
1245 /// the allocated capacity of the data (in elements), and the allocator. These are the same
1246 /// arguments in the same order as the arguments to [`from_parts_in`].
1247 ///
1248 /// After calling this function, the caller is responsible for the
1249 /// memory previously managed by the `Vec`. The only way to do
1250 /// this is to convert the `NonNull` pointer, length, and capacity back
1251 /// into a `Vec` with the [`from_parts_in`] function, allowing
1252 /// the destructor to perform the cleanup.
1253 ///
1254 /// [`from_parts_in`]: Vec::from_parts_in
1255 ///
1256 /// # Examples
1257 ///
1258 /// ```
1259 /// #![feature(allocator_api, vec_into_raw_parts, box_vec_non_null)]
1260 ///
1261 /// use std::alloc::System;
1262 ///
1263 /// let mut v: Vec<i32, System> = Vec::new_in(System);
1264 /// v.push(-1);
1265 /// v.push(0);
1266 /// v.push(1);
1267 ///
1268 /// let (ptr, len, cap, alloc) = v.into_parts_with_alloc();
1269 ///
1270 /// let rebuilt = unsafe {
1271 /// // We can now make changes to the components, such as
1272 /// // transmuting the raw pointer to a compatible type.
1273 /// let ptr = ptr.cast::<u32>();
1274 ///
1275 /// Vec::from_parts_in(ptr, len, cap, alloc)
1276 /// };
1277 /// assert_eq!(rebuilt, [4294967295, 0, 1]);
1278 /// ```
1279 #[must_use = "losing the pointer will leak memory"]
1280 #[unstable(feature = "allocator_api", issue = "32838")]
1281 // #[unstable(feature = "box_vec_non_null", reason = "new API", issue = "130364")]
1282 // #[unstable(feature = "vec_into_raw_parts", reason = "new API", issue = "65816")]
1283 pub fn into_parts_with_alloc(self) -> (NonNull<T>, usize, usize, A) {
1284 let (ptr, len, capacity, alloc) = self.into_raw_parts_with_alloc();
1285 // SAFETY: A `Vec` always has a non-null pointer.
1286 (unsafe { NonNull::new_unchecked(ptr) }, len, capacity, alloc)
1287 }
1288
1289 /// Returns the total number of elements the vector can hold without
1290 /// reallocating.
1291 ///
1292 /// # Examples
1293 ///
1294 /// ```
1295 /// let mut vec: Vec<i32> = Vec::with_capacity(10);
1296 /// vec.push(42);
1297 /// assert!(vec.capacity() >= 10);
1298 /// ```
1299 ///
1300 /// A vector with zero-sized elements will always have a capacity of usize::MAX:
1301 ///
1302 /// ```
1303 /// #[derive(Clone)]
1304 /// struct ZeroSized;
1305 ///
1306 /// fn main() {
1307 /// assert_eq!(std::mem::size_of::<ZeroSized>(), 0);
1308 /// let v = vec![ZeroSized; 0];
1309 /// assert_eq!(v.capacity(), usize::MAX);
1310 /// }
1311 /// ```
1312 #[inline]
1313 #[stable(feature = "rust1", since = "1.0.0")]
1314 #[rustc_const_stable(feature = "const_vec_string_slice", since = "1.87.0")]
1315 pub const fn capacity(&self) -> usize {
1316 self.buf.capacity()
1317 }
1318
1319 /// Reserves capacity for at least `additional` more elements to be inserted
1320 /// in the given `Vec<T>`. The collection may reserve more space to
1321 /// speculatively avoid frequent reallocations. After calling `reserve`,
1322 /// capacity will be greater than or equal to `self.len() + additional`.
1323 /// Does nothing if capacity is already sufficient.
1324 ///
1325 /// # Panics
1326 ///
1327 /// Panics if the new capacity exceeds `isize::MAX` _bytes_.
1328 ///
1329 /// # Examples
1330 ///
1331 /// ```
1332 /// let mut vec = vec![1];
1333 /// vec.reserve(10);
1334 /// assert!(vec.capacity() >= 11);
1335 /// ```
1336 #[cfg(not(no_global_oom_handling))]
1337 #[stable(feature = "rust1", since = "1.0.0")]
1338 #[track_caller]
1339 #[rustc_diagnostic_item = "vec_reserve"]
1340 pub fn reserve(&mut self, additional: usize) {
1341 self.buf.reserve(self.len, additional);
1342 }
1343
1344 /// Reserves the minimum capacity for at least `additional` more elements to
1345 /// be inserted in the given `Vec<T>`. Unlike [`reserve`], this will not
1346 /// deliberately over-allocate to speculatively avoid frequent allocations.
1347 /// After calling `reserve_exact`, capacity will be greater than or equal to
1348 /// `self.len() + additional`. Does nothing if the capacity is already
1349 /// sufficient.
1350 ///
1351 /// Note that the allocator may give the collection more space than it
1352 /// requests. Therefore, capacity can not be relied upon to be precisely
1353 /// minimal. Prefer [`reserve`] if future insertions are expected.
1354 ///
1355 /// [`reserve`]: Vec::reserve
1356 ///
1357 /// # Panics
1358 ///
1359 /// Panics if the new capacity exceeds `isize::MAX` _bytes_.
1360 ///
1361 /// # Examples
1362 ///
1363 /// ```
1364 /// let mut vec = vec![1];
1365 /// vec.reserve_exact(10);
1366 /// assert!(vec.capacity() >= 11);
1367 /// ```
1368 #[cfg(not(no_global_oom_handling))]
1369 #[stable(feature = "rust1", since = "1.0.0")]
1370 #[track_caller]
1371 pub fn reserve_exact(&mut self, additional: usize) {
1372 self.buf.reserve_exact(self.len, additional);
1373 }
1374
1375 /// Tries to reserve capacity for at least `additional` more elements to be inserted
1376 /// in the given `Vec<T>`. The collection may reserve more space to speculatively avoid
1377 /// frequent reallocations. After calling `try_reserve`, capacity will be
1378 /// greater than or equal to `self.len() + additional` if it returns
1379 /// `Ok(())`. Does nothing if capacity is already sufficient. This method
1380 /// preserves the contents even if an error occurs.
1381 ///
1382 /// # Errors
1383 ///
1384 /// If the capacity overflows, or the allocator reports a failure, then an error
1385 /// is returned.
1386 ///
1387 /// # Examples
1388 ///
1389 /// ```
1390 /// use std::collections::TryReserveError;
1391 ///
1392 /// fn process_data(data: &[u32]) -> Result<Vec<u32>, TryReserveError> {
1393 /// let mut output = Vec::new();
1394 ///
1395 /// // Pre-reserve the memory, exiting if we can't
1396 /// output.try_reserve(data.len())?;
1397 ///
1398 /// // Now we know this can't OOM in the middle of our complex work
1399 /// output.extend(data.iter().map(|&val| {
1400 /// val * 2 + 5 // very complicated
1401 /// }));
1402 ///
1403 /// Ok(output)
1404 /// }
1405 /// # process_data(&[1, 2, 3]).expect("why is the test harness OOMing on 12 bytes?");
1406 /// ```
1407 #[stable(feature = "try_reserve", since = "1.57.0")]
1408 pub fn try_reserve(&mut self, additional: usize) -> Result<(), TryReserveError> {
1409 self.buf.try_reserve(self.len, additional)
1410 }
1411
1412 /// Tries to reserve the minimum capacity for at least `additional`
1413 /// elements to be inserted in the given `Vec<T>`. Unlike [`try_reserve`],
1414 /// this will not deliberately over-allocate to speculatively avoid frequent
1415 /// allocations. After calling `try_reserve_exact`, capacity will be greater
1416 /// than or equal to `self.len() + additional` if it returns `Ok(())`.
1417 /// Does nothing if the capacity is already sufficient.
1418 ///
1419 /// Note that the allocator may give the collection more space than it
1420 /// requests. Therefore, capacity can not be relied upon to be precisely
1421 /// minimal. Prefer [`try_reserve`] if future insertions are expected.
1422 ///
1423 /// [`try_reserve`]: Vec::try_reserve
1424 ///
1425 /// # Errors
1426 ///
1427 /// If the capacity overflows, or the allocator reports a failure, then an error
1428 /// is returned.
1429 ///
1430 /// # Examples
1431 ///
1432 /// ```
1433 /// use std::collections::TryReserveError;
1434 ///
1435 /// fn process_data(data: &[u32]) -> Result<Vec<u32>, TryReserveError> {
1436 /// let mut output = Vec::new();
1437 ///
1438 /// // Pre-reserve the memory, exiting if we can't
1439 /// output.try_reserve_exact(data.len())?;
1440 ///
1441 /// // Now we know this can't OOM in the middle of our complex work
1442 /// output.extend(data.iter().map(|&val| {
1443 /// val * 2 + 5 // very complicated
1444 /// }));
1445 ///
1446 /// Ok(output)
1447 /// }
1448 /// # process_data(&[1, 2, 3]).expect("why is the test harness OOMing on 12 bytes?");
1449 /// ```
1450 #[stable(feature = "try_reserve", since = "1.57.0")]
1451 pub fn try_reserve_exact(&mut self, additional: usize) -> Result<(), TryReserveError> {
1452 self.buf.try_reserve_exact(self.len, additional)
1453 }
1454
1455 /// Shrinks the capacity of the vector as much as possible.
1456 ///
1457 /// The behavior of this method depends on the allocator, which may either shrink the vector
1458 /// in-place or reallocate. The resulting vector might still have some excess capacity, just as
1459 /// is the case for [`with_capacity`]. See [`Allocator::shrink`] for more details.
1460 ///
1461 /// [`with_capacity`]: Vec::with_capacity
1462 ///
1463 /// # Examples
1464 ///
1465 /// ```
1466 /// let mut vec = Vec::with_capacity(10);
1467 /// vec.extend([1, 2, 3]);
1468 /// assert!(vec.capacity() >= 10);
1469 /// vec.shrink_to_fit();
1470 /// assert!(vec.capacity() >= 3);
1471 /// ```
1472 #[cfg(not(no_global_oom_handling))]
1473 #[stable(feature = "rust1", since = "1.0.0")]
1474 #[track_caller]
1475 #[inline]
1476 pub fn shrink_to_fit(&mut self) {
1477 // The capacity is never less than the length, and there's nothing to do when
1478 // they are equal, so we can avoid the panic case in `RawVec::shrink_to_fit`
1479 // by only calling it with a greater capacity.
1480 if self.capacity() > self.len {
1481 self.buf.shrink_to_fit(self.len);
1482 }
1483 }
1484
1485 /// Shrinks the capacity of the vector with a lower bound.
1486 ///
1487 /// The capacity will remain at least as large as both the length
1488 /// and the supplied value.
1489 ///
1490 /// If the current capacity is less than the lower limit, this is a no-op.
1491 ///
1492 /// # Examples
1493 ///
1494 /// ```
1495 /// let mut vec = Vec::with_capacity(10);
1496 /// vec.extend([1, 2, 3]);
1497 /// assert!(vec.capacity() >= 10);
1498 /// vec.shrink_to(4);
1499 /// assert!(vec.capacity() >= 4);
1500 /// vec.shrink_to(0);
1501 /// assert!(vec.capacity() >= 3);
1502 /// ```
1503 #[cfg(not(no_global_oom_handling))]
1504 #[stable(feature = "shrink_to", since = "1.56.0")]
1505 #[track_caller]
1506 pub fn shrink_to(&mut self, min_capacity: usize) {
1507 if self.capacity() > min_capacity {
1508 self.buf.shrink_to_fit(cmp::max(self.len, min_capacity));
1509 }
1510 }
1511
1512 /// Converts the vector into [`Box<[T]>`][owned slice].
1513 ///
1514 /// Before doing the conversion, this method discards excess capacity like [`shrink_to_fit`].
1515 ///
1516 /// [owned slice]: Box
1517 /// [`shrink_to_fit`]: Vec::shrink_to_fit
1518 ///
1519 /// # Examples
1520 ///
1521 /// ```
1522 /// let v = vec![1, 2, 3];
1523 ///
1524 /// let slice = v.into_boxed_slice();
1525 /// ```
1526 ///
1527 /// Any excess capacity is removed:
1528 ///
1529 /// ```
1530 /// let mut vec = Vec::with_capacity(10);
1531 /// vec.extend([1, 2, 3]);
1532 ///
1533 /// assert!(vec.capacity() >= 10);
1534 /// let slice = vec.into_boxed_slice();
1535 /// assert_eq!(slice.into_vec().capacity(), 3);
1536 /// ```
1537 #[cfg(not(no_global_oom_handling))]
1538 #[stable(feature = "rust1", since = "1.0.0")]
1539 #[track_caller]
1540 pub fn into_boxed_slice(mut self) -> Box<[T], A> {
1541 unsafe {
1542 self.shrink_to_fit();
1543 let me = ManuallyDrop::new(self);
1544 let buf = ptr::read(&me.buf);
1545 let len = me.len();
1546 buf.into_box(len).assume_init()
1547 }
1548 }
1549
1550 /// Shortens the vector, keeping the first `len` elements and dropping
1551 /// the rest.
1552 ///
1553 /// If `len` is greater or equal to the vector's current length, this has
1554 /// no effect.
1555 ///
1556 /// The [`drain`] method can emulate `truncate`, but causes the excess
1557 /// elements to be returned instead of dropped.
1558 ///
1559 /// Note that this method has no effect on the allocated capacity
1560 /// of the vector.
1561 ///
1562 /// # Examples
1563 ///
1564 /// Truncating a five element vector to two elements:
1565 ///
1566 /// ```
1567 /// let mut vec = vec![1, 2, 3, 4, 5];
1568 /// vec.truncate(2);
1569 /// assert_eq!(vec, [1, 2]);
1570 /// ```
1571 ///
1572 /// No truncation occurs when `len` is greater than the vector's current
1573 /// length:
1574 ///
1575 /// ```
1576 /// let mut vec = vec![1, 2, 3];
1577 /// vec.truncate(8);
1578 /// assert_eq!(vec, [1, 2, 3]);
1579 /// ```
1580 ///
1581 /// Truncating when `len == 0` is equivalent to calling the [`clear`]
1582 /// method.
1583 ///
1584 /// ```
1585 /// let mut vec = vec![1, 2, 3];
1586 /// vec.truncate(0);
1587 /// assert_eq!(vec, []);
1588 /// ```
1589 ///
1590 /// [`clear`]: Vec::clear
1591 /// [`drain`]: Vec::drain
1592 #[stable(feature = "rust1", since = "1.0.0")]
1593 pub fn truncate(&mut self, len: usize) {
1594 // This is safe because:
1595 //
1596 // * the slice passed to `drop_in_place` is valid; the `len > self.len`
1597 // case avoids creating an invalid slice, and
1598 // * the `len` of the vector is shrunk before calling `drop_in_place`,
1599 // such that no value will be dropped twice in case `drop_in_place`
1600 // were to panic once (if it panics twice, the program aborts).
1601 unsafe {
1602 // Note: It's intentional that this is `>` and not `>=`.
1603 // Changing it to `>=` has negative performance
1604 // implications in some cases. See #78884 for more.
1605 if len > self.len {
1606 return;
1607 }
1608 let remaining_len = self.len - len;
1609 let s = ptr::slice_from_raw_parts_mut(self.as_mut_ptr().add(len), remaining_len);
1610 self.len = len;
1611 ptr::drop_in_place(s);
1612 }
1613 }
1614
1615 /// Extracts a slice containing the entire vector.
1616 ///
1617 /// Equivalent to `&s[..]`.
1618 ///
1619 /// # Examples
1620 ///
1621 /// ```
1622 /// use std::io::{self, Write};
1623 /// let buffer = vec![1, 2, 3, 5, 8];
1624 /// io::sink().write(buffer.as_slice()).unwrap();
1625 /// ```
1626 #[inline]
1627 #[stable(feature = "vec_as_slice", since = "1.7.0")]
1628 #[rustc_diagnostic_item = "vec_as_slice"]
1629 #[rustc_const_stable(feature = "const_vec_string_slice", since = "1.87.0")]
1630 pub const fn as_slice(&self) -> &[T] {
1631 // SAFETY: `slice::from_raw_parts` requires pointee is a contiguous, aligned buffer of size
1632 // `len` containing properly-initialized `T`s. Data must not be mutated for the returned
1633 // lifetime. Further, `len * size_of::<T>` <= `isize::MAX`, and allocation does not
1634 // "wrap" through overflowing memory addresses.
1635 //
1636 // * Vec API guarantees that self.buf:
1637 // * contains only properly-initialized items within 0..len
1638 // * is aligned, contiguous, and valid for `len` reads
1639 // * obeys size and address-wrapping constraints
1640 //
1641 // * We only construct `&mut` references to `self.buf` through `&mut self` methods; borrow-
1642 // check ensures that it is not possible to mutably alias `self.buf` within the
1643 // returned lifetime.
1644 unsafe { slice::from_raw_parts(self.as_ptr(), self.len) }
1645 }
1646
1647 /// Extracts a mutable slice of the entire vector.
1648 ///
1649 /// Equivalent to `&mut s[..]`.
1650 ///
1651 /// # Examples
1652 ///
1653 /// ```
1654 /// use std::io::{self, Read};
1655 /// let mut buffer = vec![0; 3];
1656 /// io::repeat(0b101).read_exact(buffer.as_mut_slice()).unwrap();
1657 /// ```
1658 #[inline]
1659 #[stable(feature = "vec_as_slice", since = "1.7.0")]
1660 #[rustc_diagnostic_item = "vec_as_mut_slice"]
1661 #[rustc_const_stable(feature = "const_vec_string_slice", since = "1.87.0")]
1662 pub const fn as_mut_slice(&mut self) -> &mut [T] {
1663 // SAFETY: `slice::from_raw_parts_mut` requires pointee is a contiguous, aligned buffer of
1664 // size `len` containing properly-initialized `T`s. Data must not be accessed through any
1665 // other pointer for the returned lifetime. Further, `len * size_of::<T>` <=
1666 // `ISIZE::MAX` and allocation does not "wrap" through overflowing memory addresses.
1667 //
1668 // * Vec API guarantees that self.buf:
1669 // * contains only properly-initialized items within 0..len
1670 // * is aligned, contiguous, and valid for `len` reads
1671 // * obeys size and address-wrapping constraints
1672 //
1673 // * We only construct references to `self.buf` through `&self` and `&mut self` methods;
1674 // borrow-check ensures that it is not possible to construct a reference to `self.buf`
1675 // within the returned lifetime.
1676 unsafe { slice::from_raw_parts_mut(self.as_mut_ptr(), self.len) }
1677 }
1678
1679 /// Returns a raw pointer to the vector's buffer, or a dangling raw pointer
1680 /// valid for zero sized reads if the vector didn't allocate.
1681 ///
1682 /// The caller must ensure that the vector outlives the pointer this
1683 /// function returns, or else it will end up dangling.
1684 /// Modifying the vector may cause its buffer to be reallocated,
1685 /// which would also make any pointers to it invalid.
1686 ///
1687 /// The caller must also ensure that the memory the pointer (non-transitively) points to
1688 /// is never written to (except inside an `UnsafeCell`) using this pointer or any pointer
1689 /// derived from it. If you need to mutate the contents of the slice, use [`as_mut_ptr`].
1690 ///
1691 /// This method guarantees that for the purpose of the aliasing model, this method
1692 /// does not materialize a reference to the underlying slice, and thus the returned pointer
1693 /// will remain valid when mixed with other calls to [`as_ptr`], [`as_mut_ptr`],
1694 /// and [`as_non_null`].
1695 /// Note that calling other methods that materialize mutable references to the slice,
1696 /// or mutable references to specific elements you are planning on accessing through this pointer,
1697 /// as well as writing to those elements, may still invalidate this pointer.
1698 /// See the second example below for how this guarantee can be used.
1699 ///
1700 ///
1701 /// # Examples
1702 ///
1703 /// ```
1704 /// let x = vec![1, 2, 4];
1705 /// let x_ptr = x.as_ptr();
1706 ///
1707 /// unsafe {
1708 /// for i in 0..x.len() {
1709 /// assert_eq!(*x_ptr.add(i), 1 << i);
1710 /// }
1711 /// }
1712 /// ```
1713 ///
1714 /// Due to the aliasing guarantee, the following code is legal:
1715 ///
1716 /// ```rust
1717 /// unsafe {
1718 /// let mut v = vec![0, 1, 2];
1719 /// let ptr1 = v.as_ptr();
1720 /// let _ = ptr1.read();
1721 /// let ptr2 = v.as_mut_ptr().offset(2);
1722 /// ptr2.write(2);
1723 /// // Notably, the write to `ptr2` did *not* invalidate `ptr1`
1724 /// // because it mutated a different element:
1725 /// let _ = ptr1.read();
1726 /// }
1727 /// ```
1728 ///
1729 /// [`as_mut_ptr`]: Vec::as_mut_ptr
1730 /// [`as_ptr`]: Vec::as_ptr
1731 /// [`as_non_null`]: Vec::as_non_null
1732 #[stable(feature = "vec_as_ptr", since = "1.37.0")]
1733 #[rustc_const_stable(feature = "const_vec_string_slice", since = "1.87.0")]
1734 #[rustc_never_returns_null_ptr]
1735 #[rustc_as_ptr]
1736 #[inline]
1737 pub const fn as_ptr(&self) -> *const T {
1738 // We shadow the slice method of the same name to avoid going through
1739 // `deref`, which creates an intermediate reference.
1740 self.buf.ptr()
1741 }
1742
1743 /// Returns a raw mutable pointer to the vector's buffer, or a dangling
1744 /// raw pointer valid for zero sized reads if the vector didn't allocate.
1745 ///
1746 /// The caller must ensure that the vector outlives the pointer this
1747 /// function returns, or else it will end up dangling.
1748 /// Modifying the vector may cause its buffer to be reallocated,
1749 /// which would also make any pointers to it invalid.
1750 ///
1751 /// This method guarantees that for the purpose of the aliasing model, this method
1752 /// does not materialize a reference to the underlying slice, and thus the returned pointer
1753 /// will remain valid when mixed with other calls to [`as_ptr`], [`as_mut_ptr`],
1754 /// and [`as_non_null`].
1755 /// Note that calling other methods that materialize references to the slice,
1756 /// or references to specific elements you are planning on accessing through this pointer,
1757 /// may still invalidate this pointer.
1758 /// See the second example below for how this guarantee can be used.
1759 ///
1760 /// The method also guarantees that, as long as `T` is not zero-sized and the capacity is
1761 /// nonzero, the pointer may be passed into [`dealloc`] with a layout of
1762 /// `Layout::array::<T>(capacity)` in order to deallocate the backing memory. If this is done,
1763 /// be careful not to run the destructor of the `Vec`, as dropping it will result in
1764 /// double-frees. Wrapping the `Vec` in a [`ManuallyDrop`] is the typical way to achieve this.
1765 ///
1766 /// # Examples
1767 ///
1768 /// ```
1769 /// // Allocate vector big enough for 4 elements.
1770 /// let size = 4;
1771 /// let mut x: Vec<i32> = Vec::with_capacity(size);
1772 /// let x_ptr = x.as_mut_ptr();
1773 ///
1774 /// // Initialize elements via raw pointer writes, then set length.
1775 /// unsafe {
1776 /// for i in 0..size {
1777 /// *x_ptr.add(i) = i as i32;
1778 /// }
1779 /// x.set_len(size);
1780 /// }
1781 /// assert_eq!(&*x, &[0, 1, 2, 3]);
1782 /// ```
1783 ///
1784 /// Due to the aliasing guarantee, the following code is legal:
1785 ///
1786 /// ```rust
1787 /// unsafe {
1788 /// let mut v = vec![0];
1789 /// let ptr1 = v.as_mut_ptr();
1790 /// ptr1.write(1);
1791 /// let ptr2 = v.as_mut_ptr();
1792 /// ptr2.write(2);
1793 /// // Notably, the write to `ptr2` did *not* invalidate `ptr1`:
1794 /// ptr1.write(3);
1795 /// }
1796 /// ```
1797 ///
1798 /// Deallocating a vector using [`Box`] (which uses [`dealloc`] internally):
1799 ///
1800 /// ```
1801 /// use std::mem::{ManuallyDrop, MaybeUninit};
1802 ///
1803 /// let mut v = ManuallyDrop::new(vec![0, 1, 2]);
1804 /// let ptr = v.as_mut_ptr();
1805 /// let capacity = v.capacity();
1806 /// let slice_ptr: *mut [MaybeUninit<i32>] =
1807 /// std::ptr::slice_from_raw_parts_mut(ptr.cast(), capacity);
1808 /// drop(unsafe { Box::from_raw(slice_ptr) });
1809 /// ```
1810 ///
1811 /// [`as_mut_ptr`]: Vec::as_mut_ptr
1812 /// [`as_ptr`]: Vec::as_ptr
1813 /// [`as_non_null`]: Vec::as_non_null
1814 /// [`dealloc`]: crate::alloc::GlobalAlloc::dealloc
1815 /// [`ManuallyDrop`]: core::mem::ManuallyDrop
1816 #[stable(feature = "vec_as_ptr", since = "1.37.0")]
1817 #[rustc_const_stable(feature = "const_vec_string_slice", since = "1.87.0")]
1818 #[rustc_never_returns_null_ptr]
1819 #[rustc_as_ptr]
1820 #[inline]
1821 pub const fn as_mut_ptr(&mut self) -> *mut T {
1822 // We shadow the slice method of the same name to avoid going through
1823 // `deref_mut`, which creates an intermediate reference.
1824 self.buf.ptr()
1825 }
1826
1827 /// Returns a `NonNull` pointer to the vector's buffer, or a dangling
1828 /// `NonNull` pointer valid for zero sized reads if the vector didn't allocate.
1829 ///
1830 /// The caller must ensure that the vector outlives the pointer this
1831 /// function returns, or else it will end up dangling.
1832 /// Modifying the vector may cause its buffer to be reallocated,
1833 /// which would also make any pointers to it invalid.
1834 ///
1835 /// This method guarantees that for the purpose of the aliasing model, this method
1836 /// does not materialize a reference to the underlying slice, and thus the returned pointer
1837 /// will remain valid when mixed with other calls to [`as_ptr`], [`as_mut_ptr`],
1838 /// and [`as_non_null`].
1839 /// Note that calling other methods that materialize references to the slice,
1840 /// or references to specific elements you are planning on accessing through this pointer,
1841 /// may still invalidate this pointer.
1842 /// See the second example below for how this guarantee can be used.
1843 ///
1844 /// # Examples
1845 ///
1846 /// ```
1847 /// #![feature(box_vec_non_null)]
1848 ///
1849 /// // Allocate vector big enough for 4 elements.
1850 /// let size = 4;
1851 /// let mut x: Vec<i32> = Vec::with_capacity(size);
1852 /// let x_ptr = x.as_non_null();
1853 ///
1854 /// // Initialize elements via raw pointer writes, then set length.
1855 /// unsafe {
1856 /// for i in 0..size {
1857 /// x_ptr.add(i).write(i as i32);
1858 /// }
1859 /// x.set_len(size);
1860 /// }
1861 /// assert_eq!(&*x, &[0, 1, 2, 3]);
1862 /// ```
1863 ///
1864 /// Due to the aliasing guarantee, the following code is legal:
1865 ///
1866 /// ```rust
1867 /// #![feature(box_vec_non_null)]
1868 ///
1869 /// unsafe {
1870 /// let mut v = vec![0];
1871 /// let ptr1 = v.as_non_null();
1872 /// ptr1.write(1);
1873 /// let ptr2 = v.as_non_null();
1874 /// ptr2.write(2);
1875 /// // Notably, the write to `ptr2` did *not* invalidate `ptr1`:
1876 /// ptr1.write(3);
1877 /// }
1878 /// ```
1879 ///
1880 /// [`as_mut_ptr`]: Vec::as_mut_ptr
1881 /// [`as_ptr`]: Vec::as_ptr
1882 /// [`as_non_null`]: Vec::as_non_null
1883 #[unstable(feature = "box_vec_non_null", reason = "new API", issue = "130364")]
1884 #[rustc_const_unstable(feature = "box_vec_non_null", reason = "new API", issue = "130364")]
1885 #[inline]
1886 pub const fn as_non_null(&mut self) -> NonNull<T> {
1887 self.buf.non_null()
1888 }
1889
1890 /// Returns a reference to the underlying allocator.
1891 #[unstable(feature = "allocator_api", issue = "32838")]
1892 #[inline]
1893 pub fn allocator(&self) -> &A {
1894 self.buf.allocator()
1895 }
1896
1897 /// Forces the length of the vector to `new_len`.
1898 ///
1899 /// This is a low-level operation that maintains none of the normal
1900 /// invariants of the type. Normally changing the length of a vector
1901 /// is done using one of the safe operations instead, such as
1902 /// [`truncate`], [`resize`], [`extend`], or [`clear`].
1903 ///
1904 /// [`truncate`]: Vec::truncate
1905 /// [`resize`]: Vec::resize
1906 /// [`extend`]: Extend::extend
1907 /// [`clear`]: Vec::clear
1908 ///
1909 /// # Safety
1910 ///
1911 /// - `new_len` must be less than or equal to [`capacity()`].
1912 /// - The elements at `old_len..new_len` must be initialized.
1913 ///
1914 /// [`capacity()`]: Vec::capacity
1915 ///
1916 /// # Examples
1917 ///
1918 /// See [`spare_capacity_mut()`] for an example with safe
1919 /// initialization of capacity elements and use of this method.
1920 ///
1921 /// `set_len()` can be useful for situations in which the vector
1922 /// is serving as a buffer for other code, particularly over FFI:
1923 ///
1924 /// ```no_run
1925 /// # #![allow(dead_code)]
1926 /// # // This is just a minimal skeleton for the doc example;
1927 /// # // don't use this as a starting point for a real library.
1928 /// # pub struct StreamWrapper { strm: *mut std::ffi::c_void }
1929 /// # const Z_OK: i32 = 0;
1930 /// # unsafe extern "C" {
1931 /// # fn deflateGetDictionary(
1932 /// # strm: *mut std::ffi::c_void,
1933 /// # dictionary: *mut u8,
1934 /// # dictLength: *mut usize,
1935 /// # ) -> i32;
1936 /// # }
1937 /// # impl StreamWrapper {
1938 /// pub fn get_dictionary(&self) -> Option<Vec<u8>> {
1939 /// // Per the FFI method's docs, "32768 bytes is always enough".
1940 /// let mut dict = Vec::with_capacity(32_768);
1941 /// let mut dict_length = 0;
1942 /// // SAFETY: When `deflateGetDictionary` returns `Z_OK`, it holds that:
1943 /// // 1. `dict_length` elements were initialized.
1944 /// // 2. `dict_length` <= the capacity (32_768)
1945 /// // which makes `set_len` safe to call.
1946 /// unsafe {
1947 /// // Make the FFI call...
1948 /// let r = deflateGetDictionary(self.strm, dict.as_mut_ptr(), &mut dict_length);
1949 /// if r == Z_OK {
1950 /// // ...and update the length to what was initialized.
1951 /// dict.set_len(dict_length);
1952 /// Some(dict)
1953 /// } else {
1954 /// None
1955 /// }
1956 /// }
1957 /// }
1958 /// # }
1959 /// ```
1960 ///
1961 /// While the following example is sound, there is a memory leak since
1962 /// the inner vectors were not freed prior to the `set_len` call:
1963 ///
1964 /// ```
1965 /// let mut vec = vec![vec![1, 0, 0],
1966 /// vec![0, 1, 0],
1967 /// vec![0, 0, 1]];
1968 /// // SAFETY:
1969 /// // 1. `old_len..0` is empty so no elements need to be initialized.
1970 /// // 2. `0 <= capacity` always holds whatever `capacity` is.
1971 /// unsafe {
1972 /// vec.set_len(0);
1973 /// # // FIXME(https://github.com/rust-lang/miri/issues/3670):
1974 /// # // use -Zmiri-disable-leak-check instead of unleaking in tests meant to leak.
1975 /// # vec.set_len(3);
1976 /// }
1977 /// ```
1978 ///
1979 /// Normally, here, one would use [`clear`] instead to correctly drop
1980 /// the contents and thus not leak memory.
1981 ///
1982 /// [`spare_capacity_mut()`]: Vec::spare_capacity_mut
1983 #[inline]
1984 #[stable(feature = "rust1", since = "1.0.0")]
1985 pub unsafe fn set_len(&mut self, new_len: usize) {
1986 ub_checks::assert_unsafe_precondition!(
1987 check_library_ub,
1988 "Vec::set_len requires that new_len <= capacity()",
1989 (new_len: usize = new_len, capacity: usize = self.capacity()) => new_len <= capacity
1990 );
1991
1992 self.len = new_len;
1993 }
1994
1995 /// Removes an element from the vector and returns it.
1996 ///
1997 /// The removed element is replaced by the last element of the vector.
1998 ///
1999 /// This does not preserve ordering of the remaining elements, but is *O*(1).
2000 /// If you need to preserve the element order, use [`remove`] instead.
2001 ///
2002 /// [`remove`]: Vec::remove
2003 ///
2004 /// # Panics
2005 ///
2006 /// Panics if `index` is out of bounds.
2007 ///
2008 /// # Examples
2009 ///
2010 /// ```
2011 /// let mut v = vec!["foo", "bar", "baz", "qux"];
2012 ///
2013 /// assert_eq!(v.swap_remove(1), "bar");
2014 /// assert_eq!(v, ["foo", "qux", "baz"]);
2015 ///
2016 /// assert_eq!(v.swap_remove(0), "foo");
2017 /// assert_eq!(v, ["baz", "qux"]);
2018 /// ```
2019 #[inline]
2020 #[stable(feature = "rust1", since = "1.0.0")]
2021 pub fn swap_remove(&mut self, index: usize) -> T {
2022 #[cold]
2023 #[cfg_attr(not(feature = "panic_immediate_abort"), inline(never))]
2024 #[track_caller]
2025 #[optimize(size)]
2026 fn assert_failed(index: usize, len: usize) -> ! {
2027 panic!("swap_remove index (is {index}) should be < len (is {len})");
2028 }
2029
2030 let len = self.len();
2031 if index >= len {
2032 assert_failed(index, len);
2033 }
2034 unsafe {
2035 // We replace self[index] with the last element. Note that if the
2036 // bounds check above succeeds there must be a last element (which
2037 // can be self[index] itself).
2038 let value = ptr::read(self.as_ptr().add(index));
2039 let base_ptr = self.as_mut_ptr();
2040 ptr::copy(base_ptr.add(len - 1), base_ptr.add(index), 1);
2041 self.set_len(len - 1);
2042 value
2043 }
2044 }
2045
2046 /// Inserts an element at position `index` within the vector, shifting all
2047 /// elements after it to the right.
2048 ///
2049 /// # Panics
2050 ///
2051 /// Panics if `index > len`.
2052 ///
2053 /// # Examples
2054 ///
2055 /// ```
2056 /// let mut vec = vec!['a', 'b', 'c'];
2057 /// vec.insert(1, 'd');
2058 /// assert_eq!(vec, ['a', 'd', 'b', 'c']);
2059 /// vec.insert(4, 'e');
2060 /// assert_eq!(vec, ['a', 'd', 'b', 'c', 'e']);
2061 /// ```
2062 ///
2063 /// # Time complexity
2064 ///
2065 /// Takes *O*([`Vec::len`]) time. All items after the insertion index must be
2066 /// shifted to the right. In the worst case, all elements are shifted when
2067 /// the insertion index is 0.
2068 #[cfg(not(no_global_oom_handling))]
2069 #[stable(feature = "rust1", since = "1.0.0")]
2070 #[track_caller]
2071 pub fn insert(&mut self, index: usize, element: T) {
2072 let _ = self.insert_mut(index, element);
2073 }
2074
2075 /// Inserts an element at position `index` within the vector, shifting all
2076 /// elements after it to the right, and returning a reference to the new
2077 /// element.
2078 ///
2079 /// # Panics
2080 ///
2081 /// Panics if `index > len`.
2082 ///
2083 /// # Examples
2084 ///
2085 /// ```
2086 /// #![feature(push_mut)]
2087 /// let mut vec = vec![1, 3, 5, 9];
2088 /// let x = vec.insert_mut(3, 6);
2089 /// *x += 1;
2090 /// assert_eq!(vec, [1, 3, 5, 7, 9]);
2091 /// ```
2092 ///
2093 /// # Time complexity
2094 ///
2095 /// Takes *O*([`Vec::len`]) time. All items after the insertion index must be
2096 /// shifted to the right. In the worst case, all elements are shifted when
2097 /// the insertion index is 0.
2098 #[cfg(not(no_global_oom_handling))]
2099 #[inline]
2100 #[unstable(feature = "push_mut", issue = "135974")]
2101 #[track_caller]
2102 #[must_use = "if you don't need a reference to the value, use `Vec::insert` instead"]
2103 pub fn insert_mut(&mut self, index: usize, element: T) -> &mut T {
2104 #[cold]
2105 #[cfg_attr(not(feature = "panic_immediate_abort"), inline(never))]
2106 #[track_caller]
2107 #[optimize(size)]
2108 fn assert_failed(index: usize, len: usize) -> ! {
2109 panic!("insertion index (is {index}) should be <= len (is {len})");
2110 }
2111
2112 let len = self.len();
2113 if index > len {
2114 assert_failed(index, len);
2115 }
2116
2117 // space for the new element
2118 if len == self.buf.capacity() {
2119 self.buf.grow_one();
2120 }
2121
2122 unsafe {
2123 // infallible
2124 // The spot to put the new value
2125 let p = self.as_mut_ptr().add(index);
2126 {
2127 if index < len {
2128 // Shift everything over to make space. (Duplicating the
2129 // `index`th element into two consecutive places.)
2130 ptr::copy(p, p.add(1), len - index);
2131 }
2132 // Write it in, overwriting the first copy of the `index`th
2133 // element.
2134 ptr::write(p, element);
2135 }
2136 self.set_len(len + 1);
2137 &mut *p
2138 }
2139 }
2140
2141 /// Removes and returns the element at position `index` within the vector,
2142 /// shifting all elements after it to the left.
2143 ///
2144 /// Note: Because this shifts over the remaining elements, it has a
2145 /// worst-case performance of *O*(*n*). If you don't need the order of elements
2146 /// to be preserved, use [`swap_remove`] instead. If you'd like to remove
2147 /// elements from the beginning of the `Vec`, consider using
2148 /// [`VecDeque::pop_front`] instead.
2149 ///
2150 /// [`swap_remove`]: Vec::swap_remove
2151 /// [`VecDeque::pop_front`]: crate::collections::VecDeque::pop_front
2152 ///
2153 /// # Panics
2154 ///
2155 /// Panics if `index` is out of bounds.
2156 ///
2157 /// # Examples
2158 ///
2159 /// ```
2160 /// let mut v = vec!['a', 'b', 'c'];
2161 /// assert_eq!(v.remove(1), 'b');
2162 /// assert_eq!(v, ['a', 'c']);
2163 /// ```
2164 #[stable(feature = "rust1", since = "1.0.0")]
2165 #[track_caller]
2166 #[rustc_confusables("delete", "take")]
2167 pub fn remove(&mut self, index: usize) -> T {
2168 #[cold]
2169 #[cfg_attr(not(feature = "panic_immediate_abort"), inline(never))]
2170 #[track_caller]
2171 #[optimize(size)]
2172 fn assert_failed(index: usize, len: usize) -> ! {
2173 panic!("removal index (is {index}) should be < len (is {len})");
2174 }
2175
2176 let len = self.len();
2177 if index >= len {
2178 assert_failed(index, len);
2179 }
2180 unsafe {
2181 // infallible
2182 let ret;
2183 {
2184 // the place we are taking from.
2185 let ptr = self.as_mut_ptr().add(index);
2186 // copy it out, unsafely having a copy of the value on
2187 // the stack and in the vector at the same time.
2188 ret = ptr::read(ptr);
2189
2190 // Shift everything down to fill in that spot.
2191 ptr::copy(ptr.add(1), ptr, len - index - 1);
2192 }
2193 self.set_len(len - 1);
2194 ret
2195 }
2196 }
2197
2198 /// Retains only the elements specified by the predicate.
2199 ///
2200 /// In other words, remove all elements `e` for which `f(&e)` returns `false`.
2201 /// This method operates in place, visiting each element exactly once in the
2202 /// original order, and preserves the order of the retained elements.
2203 ///
2204 /// # Examples
2205 ///
2206 /// ```
2207 /// let mut vec = vec![1, 2, 3, 4];
2208 /// vec.retain(|&x| x % 2 == 0);
2209 /// assert_eq!(vec, [2, 4]);
2210 /// ```
2211 ///
2212 /// Because the elements are visited exactly once in the original order,
2213 /// external state may be used to decide which elements to keep.
2214 ///
2215 /// ```
2216 /// let mut vec = vec![1, 2, 3, 4, 5];
2217 /// let keep = [false, true, true, false, true];
2218 /// let mut iter = keep.iter();
2219 /// vec.retain(|_| *iter.next().unwrap());
2220 /// assert_eq!(vec, [2, 3, 5]);
2221 /// ```
2222 #[stable(feature = "rust1", since = "1.0.0")]
2223 pub fn retain<F>(&mut self, mut f: F)
2224 where
2225 F: FnMut(&T) -> bool,
2226 {
2227 self.retain_mut(|elem| f(elem));
2228 }
2229
2230 /// Retains only the elements specified by the predicate, passing a mutable reference to it.
2231 ///
2232 /// In other words, remove all elements `e` such that `f(&mut e)` returns `false`.
2233 /// This method operates in place, visiting each element exactly once in the
2234 /// original order, and preserves the order of the retained elements.
2235 ///
2236 /// # Examples
2237 ///
2238 /// ```
2239 /// let mut vec = vec![1, 2, 3, 4];
2240 /// vec.retain_mut(|x| if *x <= 3 {
2241 /// *x += 1;
2242 /// true
2243 /// } else {
2244 /// false
2245 /// });
2246 /// assert_eq!(vec, [2, 3, 4]);
2247 /// ```
2248 #[stable(feature = "vec_retain_mut", since = "1.61.0")]
2249 pub fn retain_mut<F>(&mut self, mut f: F)
2250 where
2251 F: FnMut(&mut T) -> bool,
2252 {
2253 let original_len = self.len();
2254
2255 if original_len == 0 {
2256 // Empty case: explicit return allows better optimization, vs letting compiler infer it
2257 return;
2258 }
2259
2260 // Avoid double drop if the drop guard is not executed,
2261 // since we may make some holes during the process.
2262 unsafe { self.set_len(0) };
2263
2264 // Vec: [Kept, Kept, Hole, Hole, Hole, Hole, Unchecked, Unchecked]
2265 // |<- processed len ->| ^- next to check
2266 // |<- deleted cnt ->|
2267 // |<- original_len ->|
2268 // Kept: Elements which predicate returns true on.
2269 // Hole: Moved or dropped element slot.
2270 // Unchecked: Unchecked valid elements.
2271 //
2272 // This drop guard will be invoked when predicate or `drop` of element panicked.
2273 // It shifts unchecked elements to cover holes and `set_len` to the correct length.
2274 // In cases when predicate and `drop` never panick, it will be optimized out.
2275 struct BackshiftOnDrop<'a, T, A: Allocator> {
2276 v: &'a mut Vec<T, A>,
2277 processed_len: usize,
2278 deleted_cnt: usize,
2279 original_len: usize,
2280 }
2281
2282 impl<T, A: Allocator> Drop for BackshiftOnDrop<'_, T, A> {
2283 fn drop(&mut self) {
2284 if self.deleted_cnt > 0 {
2285 // SAFETY: Trailing unchecked items must be valid since we never touch them.
2286 unsafe {
2287 ptr::copy(
2288 self.v.as_ptr().add(self.processed_len),
2289 self.v.as_mut_ptr().add(self.processed_len - self.deleted_cnt),
2290 self.original_len - self.processed_len,
2291 );
2292 }
2293 }
2294 // SAFETY: After filling holes, all items are in contiguous memory.
2295 unsafe {
2296 self.v.set_len(self.original_len - self.deleted_cnt);
2297 }
2298 }
2299 }
2300
2301 let mut g = BackshiftOnDrop { v: self, processed_len: 0, deleted_cnt: 0, original_len };
2302
2303 fn process_loop<F, T, A: Allocator, const DELETED: bool>(
2304 original_len: usize,
2305 f: &mut F,
2306 g: &mut BackshiftOnDrop<'_, T, A>,
2307 ) where
2308 F: FnMut(&mut T) -> bool,
2309 {
2310 while g.processed_len != original_len {
2311 // SAFETY: Unchecked element must be valid.
2312 let cur = unsafe { &mut *g.v.as_mut_ptr().add(g.processed_len) };
2313 if !f(cur) {
2314 // Advance early to avoid double drop if `drop_in_place` panicked.
2315 g.processed_len += 1;
2316 g.deleted_cnt += 1;
2317 // SAFETY: We never touch this element again after dropped.
2318 unsafe { ptr::drop_in_place(cur) };
2319 // We already advanced the counter.
2320 if DELETED {
2321 continue;
2322 } else {
2323 break;
2324 }
2325 }
2326 if DELETED {
2327 // SAFETY: `deleted_cnt` > 0, so the hole slot must not overlap with current element.
2328 // We use copy for move, and never touch this element again.
2329 unsafe {
2330 let hole_slot = g.v.as_mut_ptr().add(g.processed_len - g.deleted_cnt);
2331 ptr::copy_nonoverlapping(cur, hole_slot, 1);
2332 }
2333 }
2334 g.processed_len += 1;
2335 }
2336 }
2337
2338 // Stage 1: Nothing was deleted.
2339 process_loop::<F, T, A, false>(original_len, &mut f, &mut g);
2340
2341 // Stage 2: Some elements were deleted.
2342 process_loop::<F, T, A, true>(original_len, &mut f, &mut g);
2343
2344 // All item are processed. This can be optimized to `set_len` by LLVM.
2345 drop(g);
2346 }
2347
2348 /// Removes all but the first of consecutive elements in the vector that resolve to the same
2349 /// key.
2350 ///
2351 /// If the vector is sorted, this removes all duplicates.
2352 ///
2353 /// # Examples
2354 ///
2355 /// ```
2356 /// let mut vec = vec![10, 20, 21, 30, 20];
2357 ///
2358 /// vec.dedup_by_key(|i| *i / 10);
2359 ///
2360 /// assert_eq!(vec, [10, 20, 30, 20]);
2361 /// ```
2362 #[stable(feature = "dedup_by", since = "1.16.0")]
2363 #[inline]
2364 pub fn dedup_by_key<F, K>(&mut self, mut key: F)
2365 where
2366 F: FnMut(&mut T) -> K,
2367 K: PartialEq,
2368 {
2369 self.dedup_by(|a, b| key(a) == key(b))
2370 }
2371
2372 /// Removes all but the first of consecutive elements in the vector satisfying a given equality
2373 /// relation.
2374 ///
2375 /// The `same_bucket` function is passed references to two elements from the vector and
2376 /// must determine if the elements compare equal. The elements are passed in opposite order
2377 /// from their order in the slice, so if `same_bucket(a, b)` returns `true`, `a` is removed.
2378 ///
2379 /// If the vector is sorted, this removes all duplicates.
2380 ///
2381 /// # Examples
2382 ///
2383 /// ```
2384 /// let mut vec = vec!["foo", "bar", "Bar", "baz", "bar"];
2385 ///
2386 /// vec.dedup_by(|a, b| a.eq_ignore_ascii_case(b));
2387 ///
2388 /// assert_eq!(vec, ["foo", "bar", "baz", "bar"]);
2389 /// ```
2390 #[stable(feature = "dedup_by", since = "1.16.0")]
2391 pub fn dedup_by<F>(&mut self, mut same_bucket: F)
2392 where
2393 F: FnMut(&mut T, &mut T) -> bool,
2394 {
2395 let len = self.len();
2396 if len <= 1 {
2397 return;
2398 }
2399
2400 // Check if we ever want to remove anything.
2401 // This allows to use copy_non_overlapping in next cycle.
2402 // And avoids any memory writes if we don't need to remove anything.
2403 let mut first_duplicate_idx: usize = 1;
2404 let start = self.as_mut_ptr();
2405 while first_duplicate_idx != len {
2406 let found_duplicate = unsafe {
2407 // SAFETY: first_duplicate always in range [1..len)
2408 // Note that we start iteration from 1 so we never overflow.
2409 let prev = start.add(first_duplicate_idx.wrapping_sub(1));
2410 let current = start.add(first_duplicate_idx);
2411 // We explicitly say in docs that references are reversed.
2412 same_bucket(&mut *current, &mut *prev)
2413 };
2414 if found_duplicate {
2415 break;
2416 }
2417 first_duplicate_idx += 1;
2418 }
2419 // Don't need to remove anything.
2420 // We cannot get bigger than len.
2421 if first_duplicate_idx == len {
2422 return;
2423 }
2424
2425 /* INVARIANT: vec.len() > read > write > write-1 >= 0 */
2426 struct FillGapOnDrop<'a, T, A: core::alloc::Allocator> {
2427 /* Offset of the element we want to check if it is duplicate */
2428 read: usize,
2429
2430 /* Offset of the place where we want to place the non-duplicate
2431 * when we find it. */
2432 write: usize,
2433
2434 /* The Vec that would need correction if `same_bucket` panicked */
2435 vec: &'a mut Vec<T, A>,
2436 }
2437
2438 impl<'a, T, A: core::alloc::Allocator> Drop for FillGapOnDrop<'a, T, A> {
2439 fn drop(&mut self) {
2440 /* This code gets executed when `same_bucket` panics */
2441
2442 /* SAFETY: invariant guarantees that `read - write`
2443 * and `len - read` never overflow and that the copy is always
2444 * in-bounds. */
2445 unsafe {
2446 let ptr = self.vec.as_mut_ptr();
2447 let len = self.vec.len();
2448
2449 /* How many items were left when `same_bucket` panicked.
2450 * Basically vec[read..].len() */
2451 let items_left = len.wrapping_sub(self.read);
2452
2453 /* Pointer to first item in vec[write..write+items_left] slice */
2454 let dropped_ptr = ptr.add(self.write);
2455 /* Pointer to first item in vec[read..] slice */
2456 let valid_ptr = ptr.add(self.read);
2457
2458 /* Copy `vec[read..]` to `vec[write..write+items_left]`.
2459 * The slices can overlap, so `copy_nonoverlapping` cannot be used */
2460 ptr::copy(valid_ptr, dropped_ptr, items_left);
2461
2462 /* How many items have been already dropped
2463 * Basically vec[read..write].len() */
2464 let dropped = self.read.wrapping_sub(self.write);
2465
2466 self.vec.set_len(len - dropped);
2467 }
2468 }
2469 }
2470
2471 /* Drop items while going through Vec, it should be more efficient than
2472 * doing slice partition_dedup + truncate */
2473
2474 // Construct gap first and then drop item to avoid memory corruption if `T::drop` panics.
2475 let mut gap =
2476 FillGapOnDrop { read: first_duplicate_idx + 1, write: first_duplicate_idx, vec: self };
2477 unsafe {
2478 // SAFETY: we checked that first_duplicate_idx in bounds before.
2479 // If drop panics, `gap` would remove this item without drop.
2480 ptr::drop_in_place(start.add(first_duplicate_idx));
2481 }
2482
2483 /* SAFETY: Because of the invariant, read_ptr, prev_ptr and write_ptr
2484 * are always in-bounds and read_ptr never aliases prev_ptr */
2485 unsafe {
2486 while gap.read < len {
2487 let read_ptr = start.add(gap.read);
2488 let prev_ptr = start.add(gap.write.wrapping_sub(1));
2489
2490 // We explicitly say in docs that references are reversed.
2491 let found_duplicate = same_bucket(&mut *read_ptr, &mut *prev_ptr);
2492 if found_duplicate {
2493 // Increase `gap.read` now since the drop may panic.
2494 gap.read += 1;
2495 /* We have found duplicate, drop it in-place */
2496 ptr::drop_in_place(read_ptr);
2497 } else {
2498 let write_ptr = start.add(gap.write);
2499
2500 /* read_ptr cannot be equal to write_ptr because at this point
2501 * we guaranteed to skip at least one element (before loop starts).
2502 */
2503 ptr::copy_nonoverlapping(read_ptr, write_ptr, 1);
2504
2505 /* We have filled that place, so go further */
2506 gap.write += 1;
2507 gap.read += 1;
2508 }
2509 }
2510
2511 /* Technically we could let `gap` clean up with its Drop, but
2512 * when `same_bucket` is guaranteed to not panic, this bloats a little
2513 * the codegen, so we just do it manually */
2514 gap.vec.set_len(gap.write);
2515 mem::forget(gap);
2516 }
2517 }
2518
2519 /// Appends an element to the back of a collection.
2520 ///
2521 /// # Panics
2522 ///
2523 /// Panics if the new capacity exceeds `isize::MAX` _bytes_.
2524 ///
2525 /// # Examples
2526 ///
2527 /// ```
2528 /// let mut vec = vec![1, 2];
2529 /// vec.push(3);
2530 /// assert_eq!(vec, [1, 2, 3]);
2531 /// ```
2532 ///
2533 /// # Time complexity
2534 ///
2535 /// Takes amortized *O*(1) time. If the vector's length would exceed its
2536 /// capacity after the push, *O*(*capacity*) time is taken to copy the
2537 /// vector's elements to a larger allocation. This expensive operation is
2538 /// offset by the *capacity* *O*(1) insertions it allows.
2539 #[cfg(not(no_global_oom_handling))]
2540 #[inline]
2541 #[stable(feature = "rust1", since = "1.0.0")]
2542 #[rustc_confusables("push_back", "put", "append")]
2543 #[track_caller]
2544 pub fn push(&mut self, value: T) {
2545 let _ = self.push_mut(value);
2546 }
2547
2548 /// Appends an element if there is sufficient spare capacity, otherwise an error is returned
2549 /// with the element.
2550 ///
2551 /// Unlike [`push`] this method will not reallocate when there's insufficient capacity.
2552 /// The caller should use [`reserve`] or [`try_reserve`] to ensure that there is enough capacity.
2553 ///
2554 /// [`push`]: Vec::push
2555 /// [`reserve`]: Vec::reserve
2556 /// [`try_reserve`]: Vec::try_reserve
2557 ///
2558 /// # Examples
2559 ///
2560 /// A manual, panic-free alternative to [`FromIterator`]:
2561 ///
2562 /// ```
2563 /// #![feature(vec_push_within_capacity)]
2564 ///
2565 /// use std::collections::TryReserveError;
2566 /// fn from_iter_fallible<T>(iter: impl Iterator<Item=T>) -> Result<Vec<T>, TryReserveError> {
2567 /// let mut vec = Vec::new();
2568 /// for value in iter {
2569 /// if let Err(value) = vec.push_within_capacity(value) {
2570 /// vec.try_reserve(1)?;
2571 /// // this cannot fail, the previous line either returned or added at least 1 free slot
2572 /// let _ = vec.push_within_capacity(value);
2573 /// }
2574 /// }
2575 /// Ok(vec)
2576 /// }
2577 /// assert_eq!(from_iter_fallible(0..100), Ok(Vec::from_iter(0..100)));
2578 /// ```
2579 ///
2580 /// # Time complexity
2581 ///
2582 /// Takes *O*(1) time.
2583 #[inline]
2584 #[unstable(feature = "vec_push_within_capacity", issue = "100486")]
2585 pub fn push_within_capacity(&mut self, value: T) -> Result<(), T> {
2586 self.push_mut_within_capacity(value).map(|_| ())
2587 }
2588
2589 /// Appends an element to the back of a collection, returning a reference to it.
2590 ///
2591 /// # Panics
2592 ///
2593 /// Panics if the new capacity exceeds `isize::MAX` _bytes_.
2594 ///
2595 /// # Examples
2596 ///
2597 /// ```
2598 /// #![feature(push_mut)]
2599 ///
2600 ///
2601 /// let mut vec = vec![1, 2];
2602 /// let last = vec.push_mut(3);
2603 /// assert_eq!(*last, 3);
2604 /// assert_eq!(vec, [1, 2, 3]);
2605 ///
2606 /// let last = vec.push_mut(3);
2607 /// *last += 1;
2608 /// assert_eq!(vec, [1, 2, 3, 4]);
2609 /// ```
2610 ///
2611 /// # Time complexity
2612 ///
2613 /// Takes amortized *O*(1) time. If the vector's length would exceed its
2614 /// capacity after the push, *O*(*capacity*) time is taken to copy the
2615 /// vector's elements to a larger allocation. This expensive operation is
2616 /// offset by the *capacity* *O*(1) insertions it allows.
2617 #[cfg(not(no_global_oom_handling))]
2618 #[inline]
2619 #[unstable(feature = "push_mut", issue = "135974")]
2620 #[track_caller]
2621 #[must_use = "if you don't need a reference to the value, use `Vec::push` instead"]
2622 pub fn push_mut(&mut self, value: T) -> &mut T {
2623 // Inform codegen that the length does not change across grow_one().
2624 let len = self.len;
2625 // This will panic or abort if we would allocate > isize::MAX bytes
2626 // or if the length increment would overflow for zero-sized types.
2627 if len == self.buf.capacity() {
2628 self.buf.grow_one();
2629 }
2630 unsafe {
2631 let end = self.as_mut_ptr().add(len);
2632 ptr::write(end, value);
2633 self.len = len + 1;
2634 // SAFETY: We just wrote a value to the pointer that will live the lifetime of the reference.
2635 &mut *end
2636 }
2637 }
2638
2639 /// Appends an element and returns a reference to it if there is sufficient spare capacity,
2640 /// otherwise an error is returned with the element.
2641 ///
2642 /// Unlike [`push_mut`] this method will not reallocate when there's insufficient capacity.
2643 /// The caller should use [`reserve`] or [`try_reserve`] to ensure that there is enough capacity.
2644 ///
2645 /// [`push_mut`]: Vec::push_mut
2646 /// [`reserve`]: Vec::reserve
2647 /// [`try_reserve`]: Vec::try_reserve
2648 ///
2649 /// # Time complexity
2650 ///
2651 /// Takes *O*(1) time.
2652 #[unstable(feature = "push_mut", issue = "135974")]
2653 // #[unstable(feature = "vec_push_within_capacity", issue = "100486")]
2654 #[inline]
2655 #[must_use = "if you don't need a reference to the value, use `Vec::push_within_capacity` instead"]
2656 pub fn push_mut_within_capacity(&mut self, value: T) -> Result<&mut T, T> {
2657 if self.len == self.buf.capacity() {
2658 return Err(value);
2659 }
2660 unsafe {
2661 let end = self.as_mut_ptr().add(self.len);
2662 ptr::write(end, value);
2663 self.len += 1;
2664 // SAFETY: We just wrote a value to the pointer that will live the lifetime of the reference.
2665 Ok(&mut *end)
2666 }
2667 }
2668
2669 /// Removes the last element from a vector and returns it, or [`None`] if it
2670 /// is empty.
2671 ///
2672 /// If you'd like to pop the first element, consider using
2673 /// [`VecDeque::pop_front`] instead.
2674 ///
2675 /// [`VecDeque::pop_front`]: crate::collections::VecDeque::pop_front
2676 ///
2677 /// # Examples
2678 ///
2679 /// ```
2680 /// let mut vec = vec![1, 2, 3];
2681 /// assert_eq!(vec.pop(), Some(3));
2682 /// assert_eq!(vec, [1, 2]);
2683 /// ```
2684 ///
2685 /// # Time complexity
2686 ///
2687 /// Takes *O*(1) time.
2688 #[inline]
2689 #[stable(feature = "rust1", since = "1.0.0")]
2690 #[rustc_diagnostic_item = "vec_pop"]
2691 pub fn pop(&mut self) -> Option<T> {
2692 if self.len == 0 {
2693 None
2694 } else {
2695 unsafe {
2696 self.len -= 1;
2697 core::hint::assert_unchecked(self.len < self.capacity());
2698 Some(ptr::read(self.as_ptr().add(self.len())))
2699 }
2700 }
2701 }
2702
2703 /// Removes and returns the last element from a vector if the predicate
2704 /// returns `true`, or [`None`] if the predicate returns false or the vector
2705 /// is empty (the predicate will not be called in that case).
2706 ///
2707 /// # Examples
2708 ///
2709 /// ```
2710 /// let mut vec = vec![1, 2, 3, 4];
2711 /// let pred = |x: &mut i32| *x % 2 == 0;
2712 ///
2713 /// assert_eq!(vec.pop_if(pred), Some(4));
2714 /// assert_eq!(vec, [1, 2, 3]);
2715 /// assert_eq!(vec.pop_if(pred), None);
2716 /// ```
2717 #[stable(feature = "vec_pop_if", since = "1.86.0")]
2718 pub fn pop_if(&mut self, predicate: impl FnOnce(&mut T) -> bool) -> Option<T> {
2719 let last = self.last_mut()?;
2720 if predicate(last) { self.pop() } else { None }
2721 }
2722
2723 /// Returns a mutable reference to the last item in the vector, or
2724 /// `None` if it is empty.
2725 ///
2726 /// # Examples
2727 ///
2728 /// Basic usage:
2729 ///
2730 /// ```
2731 /// #![feature(vec_peek_mut)]
2732 /// let mut vec = Vec::new();
2733 /// assert!(vec.peek_mut().is_none());
2734 ///
2735 /// vec.push(1);
2736 /// vec.push(5);
2737 /// vec.push(2);
2738 /// assert_eq!(vec.last(), Some(&2));
2739 /// if let Some(mut val) = vec.peek_mut() {
2740 /// *val = 0;
2741 /// }
2742 /// assert_eq!(vec.last(), Some(&0));
2743 /// ```
2744 #[inline]
2745 #[unstable(feature = "vec_peek_mut", issue = "122742")]
2746 pub fn peek_mut(&mut self) -> Option<PeekMut<'_, T, A>> {
2747 PeekMut::new(self)
2748 }
2749
2750 /// Moves all the elements of `other` into `self`, leaving `other` empty.
2751 ///
2752 /// # Panics
2753 ///
2754 /// Panics if the new capacity exceeds `isize::MAX` _bytes_.
2755 ///
2756 /// # Examples
2757 ///
2758 /// ```
2759 /// let mut vec = vec![1, 2, 3];
2760 /// let mut vec2 = vec![4, 5, 6];
2761 /// vec.append(&mut vec2);
2762 /// assert_eq!(vec, [1, 2, 3, 4, 5, 6]);
2763 /// assert_eq!(vec2, []);
2764 /// ```
2765 #[cfg(not(no_global_oom_handling))]
2766 #[inline]
2767 #[stable(feature = "append", since = "1.4.0")]
2768 #[track_caller]
2769 pub fn append(&mut self, other: &mut Self) {
2770 unsafe {
2771 self.append_elements(other.as_slice() as _);
2772 other.set_len(0);
2773 }
2774 }
2775
2776 /// Appends elements to `self` from other buffer.
2777 #[cfg(not(no_global_oom_handling))]
2778 #[inline]
2779 #[track_caller]
2780 unsafe fn append_elements(&mut self, other: *const [T]) {
2781 let count = other.len();
2782 self.reserve(count);
2783 let len = self.len();
2784 unsafe { ptr::copy_nonoverlapping(other as *const T, self.as_mut_ptr().add(len), count) };
2785 self.len += count;
2786 }
2787
2788 /// Removes the subslice indicated by the given range from the vector,
2789 /// returning a double-ended iterator over the removed subslice.
2790 ///
2791 /// If the iterator is dropped before being fully consumed,
2792 /// it drops the remaining removed elements.
2793 ///
2794 /// The returned iterator keeps a mutable borrow on the vector to optimize
2795 /// its implementation.
2796 ///
2797 /// # Panics
2798 ///
2799 /// Panics if the range has `start_bound > end_bound`, or, if the range is
2800 /// bounded on either end and past the length of the vector.
2801 ///
2802 /// # Leaking
2803 ///
2804 /// If the returned iterator goes out of scope without being dropped (due to
2805 /// [`mem::forget`], for example), the vector may have lost and leaked
2806 /// elements arbitrarily, including elements outside the range.
2807 ///
2808 /// # Examples
2809 ///
2810 /// ```
2811 /// let mut v = vec![1, 2, 3];
2812 /// let u: Vec<_> = v.drain(1..).collect();
2813 /// assert_eq!(v, &[1]);
2814 /// assert_eq!(u, &[2, 3]);
2815 ///
2816 /// // A full range clears the vector, like `clear()` does
2817 /// v.drain(..);
2818 /// assert_eq!(v, &[]);
2819 /// ```
2820 #[stable(feature = "drain", since = "1.6.0")]
2821 pub fn drain<R>(&mut self, range: R) -> Drain<'_, T, A>
2822 where
2823 R: RangeBounds<usize>,
2824 {
2825 // Memory safety
2826 //
2827 // When the Drain is first created, it shortens the length of
2828 // the source vector to make sure no uninitialized or moved-from elements
2829 // are accessible at all if the Drain's destructor never gets to run.
2830 //
2831 // Drain will ptr::read out the values to remove.
2832 // When finished, remaining tail of the vec is copied back to cover
2833 // the hole, and the vector length is restored to the new length.
2834 //
2835 let len = self.len();
2836 let Range { start, end } = slice::range(range, ..len);
2837
2838 unsafe {
2839 // set self.vec length's to start, to be safe in case Drain is leaked
2840 self.set_len(start);
2841 let range_slice = slice::from_raw_parts(self.as_ptr().add(start), end - start);
2842 Drain {
2843 tail_start: end,
2844 tail_len: len - end,
2845 iter: range_slice.iter(),
2846 vec: NonNull::from(self),
2847 }
2848 }
2849 }
2850
2851 /// Clears the vector, removing all values.
2852 ///
2853 /// Note that this method has no effect on the allocated capacity
2854 /// of the vector.
2855 ///
2856 /// # Examples
2857 ///
2858 /// ```
2859 /// let mut v = vec![1, 2, 3];
2860 ///
2861 /// v.clear();
2862 ///
2863 /// assert!(v.is_empty());
2864 /// ```
2865 #[inline]
2866 #[stable(feature = "rust1", since = "1.0.0")]
2867 pub fn clear(&mut self) {
2868 let elems: *mut [T] = self.as_mut_slice();
2869
2870 // SAFETY:
2871 // - `elems` comes directly from `as_mut_slice` and is therefore valid.
2872 // - Setting `self.len` before calling `drop_in_place` means that,
2873 // if an element's `Drop` impl panics, the vector's `Drop` impl will
2874 // do nothing (leaking the rest of the elements) instead of dropping
2875 // some twice.
2876 unsafe {
2877 self.len = 0;
2878 ptr::drop_in_place(elems);
2879 }
2880 }
2881
2882 /// Returns the number of elements in the vector, also referred to
2883 /// as its 'length'.
2884 ///
2885 /// # Examples
2886 ///
2887 /// ```
2888 /// let a = vec![1, 2, 3];
2889 /// assert_eq!(a.len(), 3);
2890 /// ```
2891 #[inline]
2892 #[stable(feature = "rust1", since = "1.0.0")]
2893 #[rustc_const_stable(feature = "const_vec_string_slice", since = "1.87.0")]
2894 #[rustc_confusables("length", "size")]
2895 pub const fn len(&self) -> usize {
2896 let len = self.len;
2897
2898 // SAFETY: The maximum capacity of `Vec<T>` is `isize::MAX` bytes, so the maximum value can
2899 // be returned is `usize::checked_div(size_of::<T>()).unwrap_or(usize::MAX)`, which
2900 // matches the definition of `T::MAX_SLICE_LEN`.
2901 unsafe { intrinsics::assume(len <= T::MAX_SLICE_LEN) };
2902
2903 len
2904 }
2905
2906 /// Returns `true` if the vector contains no elements.
2907 ///
2908 /// # Examples
2909 ///
2910 /// ```
2911 /// let mut v = Vec::new();
2912 /// assert!(v.is_empty());
2913 ///
2914 /// v.push(1);
2915 /// assert!(!v.is_empty());
2916 /// ```
2917 #[stable(feature = "rust1", since = "1.0.0")]
2918 #[rustc_diagnostic_item = "vec_is_empty"]
2919 #[rustc_const_stable(feature = "const_vec_string_slice", since = "1.87.0")]
2920 pub const fn is_empty(&self) -> bool {
2921 self.len() == 0
2922 }
2923
2924 /// Splits the collection into two at the given index.
2925 ///
2926 /// Returns a newly allocated vector containing the elements in the range
2927 /// `[at, len)`. After the call, the original vector will be left containing
2928 /// the elements `[0, at)` with its previous capacity unchanged.
2929 ///
2930 /// - If you want to take ownership of the entire contents and capacity of
2931 /// the vector, see [`mem::take`] or [`mem::replace`].
2932 /// - If you don't need the returned vector at all, see [`Vec::truncate`].
2933 /// - If you want to take ownership of an arbitrary subslice, or you don't
2934 /// necessarily want to store the removed items in a vector, see [`Vec::drain`].
2935 ///
2936 /// # Panics
2937 ///
2938 /// Panics if `at > len`.
2939 ///
2940 /// # Examples
2941 ///
2942 /// ```
2943 /// let mut vec = vec!['a', 'b', 'c'];
2944 /// let vec2 = vec.split_off(1);
2945 /// assert_eq!(vec, ['a']);
2946 /// assert_eq!(vec2, ['b', 'c']);
2947 /// ```
2948 #[cfg(not(no_global_oom_handling))]
2949 #[inline]
2950 #[must_use = "use `.truncate()` if you don't need the other half"]
2951 #[stable(feature = "split_off", since = "1.4.0")]
2952 #[track_caller]
2953 pub fn split_off(&mut self, at: usize) -> Self
2954 where
2955 A: Clone,
2956 {
2957 #[cold]
2958 #[cfg_attr(not(feature = "panic_immediate_abort"), inline(never))]
2959 #[track_caller]
2960 #[optimize(size)]
2961 fn assert_failed(at: usize, len: usize) -> ! {
2962 panic!("`at` split index (is {at}) should be <= len (is {len})");
2963 }
2964
2965 if at > self.len() {
2966 assert_failed(at, self.len());
2967 }
2968
2969 let other_len = self.len - at;
2970 let mut other = Vec::with_capacity_in(other_len, self.allocator().clone());
2971
2972 // Unsafely `set_len` and copy items to `other`.
2973 unsafe {
2974 self.set_len(at);
2975 other.set_len(other_len);
2976
2977 ptr::copy_nonoverlapping(self.as_ptr().add(at), other.as_mut_ptr(), other.len());
2978 }
2979 other
2980 }
2981
2982 /// Resizes the `Vec` in-place so that `len` is equal to `new_len`.
2983 ///
2984 /// If `new_len` is greater than `len`, the `Vec` is extended by the
2985 /// difference, with each additional slot filled with the result of
2986 /// calling the closure `f`. The return values from `f` will end up
2987 /// in the `Vec` in the order they have been generated.
2988 ///
2989 /// If `new_len` is less than `len`, the `Vec` is simply truncated.
2990 ///
2991 /// This method uses a closure to create new values on every push. If
2992 /// you'd rather [`Clone`] a given value, use [`Vec::resize`]. If you
2993 /// want to use the [`Default`] trait to generate values, you can
2994 /// pass [`Default::default`] as the second argument.
2995 ///
2996 /// # Panics
2997 ///
2998 /// Panics if the new capacity exceeds `isize::MAX` _bytes_.
2999 ///
3000 /// # Examples
3001 ///
3002 /// ```
3003 /// let mut vec = vec![1, 2, 3];
3004 /// vec.resize_with(5, Default::default);
3005 /// assert_eq!(vec, [1, 2, 3, 0, 0]);
3006 ///
3007 /// let mut vec = vec![];
3008 /// let mut p = 1;
3009 /// vec.resize_with(4, || { p *= 2; p });
3010 /// assert_eq!(vec, [2, 4, 8, 16]);
3011 /// ```
3012 #[cfg(not(no_global_oom_handling))]
3013 #[stable(feature = "vec_resize_with", since = "1.33.0")]
3014 #[track_caller]
3015 pub fn resize_with<F>(&mut self, new_len: usize, f: F)
3016 where
3017 F: FnMut() -> T,
3018 {
3019 let len = self.len();
3020 if new_len > len {
3021 self.extend_trusted(iter::repeat_with(f).take(new_len - len));
3022 } else {
3023 self.truncate(new_len);
3024 }
3025 }
3026
3027 /// Consumes and leaks the `Vec`, returning a mutable reference to the contents,
3028 /// `&'a mut [T]`.
3029 ///
3030 /// Note that the type `T` must outlive the chosen lifetime `'a`. If the type
3031 /// has only static references, or none at all, then this may be chosen to be
3032 /// `'static`.
3033 ///
3034 /// As of Rust 1.57, this method does not reallocate or shrink the `Vec`,
3035 /// so the leaked allocation may include unused capacity that is not part
3036 /// of the returned slice.
3037 ///
3038 /// This function is mainly useful for data that lives for the remainder of
3039 /// the program's life. Dropping the returned reference will cause a memory
3040 /// leak.
3041 ///
3042 /// # Examples
3043 ///
3044 /// Simple usage:
3045 ///
3046 /// ```
3047 /// let x = vec![1, 2, 3];
3048 /// let static_ref: &'static mut [usize] = x.leak();
3049 /// static_ref[0] += 1;
3050 /// assert_eq!(static_ref, &[2, 2, 3]);
3051 /// # // FIXME(https://github.com/rust-lang/miri/issues/3670):
3052 /// # // use -Zmiri-disable-leak-check instead of unleaking in tests meant to leak.
3053 /// # drop(unsafe { Box::from_raw(static_ref) });
3054 /// ```
3055 #[stable(feature = "vec_leak", since = "1.47.0")]
3056 #[inline]
3057 pub fn leak<'a>(self) -> &'a mut [T]
3058 where
3059 A: 'a,
3060 {
3061 let mut me = ManuallyDrop::new(self);
3062 unsafe { slice::from_raw_parts_mut(me.as_mut_ptr(), me.len) }
3063 }
3064
3065 /// Returns the remaining spare capacity of the vector as a slice of
3066 /// `MaybeUninit<T>`.
3067 ///
3068 /// The returned slice can be used to fill the vector with data (e.g. by
3069 /// reading from a file) before marking the data as initialized using the
3070 /// [`set_len`] method.
3071 ///
3072 /// [`set_len`]: Vec::set_len
3073 ///
3074 /// # Examples
3075 ///
3076 /// ```
3077 /// // Allocate vector big enough for 10 elements.
3078 /// let mut v = Vec::with_capacity(10);
3079 ///
3080 /// // Fill in the first 3 elements.
3081 /// let uninit = v.spare_capacity_mut();
3082 /// uninit[0].write(0);
3083 /// uninit[1].write(1);
3084 /// uninit[2].write(2);
3085 ///
3086 /// // Mark the first 3 elements of the vector as being initialized.
3087 /// unsafe {
3088 /// v.set_len(3);
3089 /// }
3090 ///
3091 /// assert_eq!(&v, &[0, 1, 2]);
3092 /// ```
3093 #[stable(feature = "vec_spare_capacity", since = "1.60.0")]
3094 #[inline]
3095 pub fn spare_capacity_mut(&mut self) -> &mut [MaybeUninit<T>] {
3096 // Note:
3097 // This method is not implemented in terms of `split_at_spare_mut`,
3098 // to prevent invalidation of pointers to the buffer.
3099 unsafe {
3100 slice::from_raw_parts_mut(
3101 self.as_mut_ptr().add(self.len) as *mut MaybeUninit<T>,
3102 self.buf.capacity() - self.len,
3103 )
3104 }
3105 }
3106
3107 /// Returns vector content as a slice of `T`, along with the remaining spare
3108 /// capacity of the vector as a slice of `MaybeUninit<T>`.
3109 ///
3110 /// The returned spare capacity slice can be used to fill the vector with data
3111 /// (e.g. by reading from a file) before marking the data as initialized using
3112 /// the [`set_len`] method.
3113 ///
3114 /// [`set_len`]: Vec::set_len
3115 ///
3116 /// Note that this is a low-level API, which should be used with care for
3117 /// optimization purposes. If you need to append data to a `Vec`
3118 /// you can use [`push`], [`extend`], [`extend_from_slice`],
3119 /// [`extend_from_within`], [`insert`], [`append`], [`resize`] or
3120 /// [`resize_with`], depending on your exact needs.
3121 ///
3122 /// [`push`]: Vec::push
3123 /// [`extend`]: Vec::extend
3124 /// [`extend_from_slice`]: Vec::extend_from_slice
3125 /// [`extend_from_within`]: Vec::extend_from_within
3126 /// [`insert`]: Vec::insert
3127 /// [`append`]: Vec::append
3128 /// [`resize`]: Vec::resize
3129 /// [`resize_with`]: Vec::resize_with
3130 ///
3131 /// # Examples
3132 ///
3133 /// ```
3134 /// #![feature(vec_split_at_spare)]
3135 ///
3136 /// let mut v = vec![1, 1, 2];
3137 ///
3138 /// // Reserve additional space big enough for 10 elements.
3139 /// v.reserve(10);
3140 ///
3141 /// let (init, uninit) = v.split_at_spare_mut();
3142 /// let sum = init.iter().copied().sum::<u32>();
3143 ///
3144 /// // Fill in the next 4 elements.
3145 /// uninit[0].write(sum);
3146 /// uninit[1].write(sum * 2);
3147 /// uninit[2].write(sum * 3);
3148 /// uninit[3].write(sum * 4);
3149 ///
3150 /// // Mark the 4 elements of the vector as being initialized.
3151 /// unsafe {
3152 /// let len = v.len();
3153 /// v.set_len(len + 4);
3154 /// }
3155 ///
3156 /// assert_eq!(&v, &[1, 1, 2, 4, 8, 12, 16]);
3157 /// ```
3158 #[unstable(feature = "vec_split_at_spare", issue = "81944")]
3159 #[inline]
3160 pub fn split_at_spare_mut(&mut self) -> (&mut [T], &mut [MaybeUninit<T>]) {
3161 // SAFETY:
3162 // - len is ignored and so never changed
3163 let (init, spare, _) = unsafe { self.split_at_spare_mut_with_len() };
3164 (init, spare)
3165 }
3166
3167 /// Safety: changing returned .2 (&mut usize) is considered the same as calling `.set_len(_)`.
3168 ///
3169 /// This method provides unique access to all vec parts at once in `extend_from_within`.
3170 unsafe fn split_at_spare_mut_with_len(
3171 &mut self,
3172 ) -> (&mut [T], &mut [MaybeUninit<T>], &mut usize) {
3173 let ptr = self.as_mut_ptr();
3174 // SAFETY:
3175 // - `ptr` is guaranteed to be valid for `self.len` elements
3176 // - but the allocation extends out to `self.buf.capacity()` elements, possibly
3177 // uninitialized
3178 let spare_ptr = unsafe { ptr.add(self.len) };
3179 let spare_ptr = spare_ptr.cast_uninit();
3180 let spare_len = self.buf.capacity() - self.len;
3181
3182 // SAFETY:
3183 // - `ptr` is guaranteed to be valid for `self.len` elements
3184 // - `spare_ptr` is pointing one element past the buffer, so it doesn't overlap with `initialized`
3185 unsafe {
3186 let initialized = slice::from_raw_parts_mut(ptr, self.len);
3187 let spare = slice::from_raw_parts_mut(spare_ptr, spare_len);
3188
3189 (initialized, spare, &mut self.len)
3190 }
3191 }
3192
3193 /// Groups every `N` elements in the `Vec<T>` into chunks to produce a `Vec<[T; N]>`, dropping
3194 /// elements in the remainder. `N` must be greater than zero.
3195 ///
3196 /// If the capacity is not a multiple of the chunk size, the buffer will shrink down to the
3197 /// nearest multiple with a reallocation or deallocation.
3198 ///
3199 /// This function can be used to reverse [`Vec::into_flattened`].
3200 ///
3201 /// # Examples
3202 ///
3203 /// ```
3204 /// #![feature(vec_into_chunks)]
3205 ///
3206 /// let vec = vec![0, 1, 2, 3, 4, 5, 6, 7];
3207 /// assert_eq!(vec.into_chunks::<3>(), [[0, 1, 2], [3, 4, 5]]);
3208 ///
3209 /// let vec = vec![0, 1, 2, 3];
3210 /// let chunks: Vec<[u8; 10]> = vec.into_chunks();
3211 /// assert!(chunks.is_empty());
3212 ///
3213 /// let flat = vec![0; 8 * 8 * 8];
3214 /// let reshaped: Vec<[[[u8; 8]; 8]; 8]> = flat.into_chunks().into_chunks().into_chunks();
3215 /// assert_eq!(reshaped.len(), 1);
3216 /// ```
3217 #[cfg(not(no_global_oom_handling))]
3218 #[unstable(feature = "vec_into_chunks", issue = "142137")]
3219 pub fn into_chunks<const N: usize>(mut self) -> Vec<[T; N], A> {
3220 const {
3221 assert!(N != 0, "chunk size must be greater than zero");
3222 }
3223
3224 let (len, cap) = (self.len(), self.capacity());
3225
3226 let len_remainder = len % N;
3227 if len_remainder != 0 {
3228 self.truncate(len - len_remainder);
3229 }
3230
3231 let cap_remainder = cap % N;
3232 if !T::IS_ZST && cap_remainder != 0 {
3233 self.buf.shrink_to_fit(cap - cap_remainder);
3234 }
3235
3236 let (ptr, _, _, alloc) = self.into_raw_parts_with_alloc();
3237
3238 // SAFETY:
3239 // - `ptr` and `alloc` were just returned from `self.into_raw_parts_with_alloc()`
3240 // - `[T; N]` has the same alignment as `T`
3241 // - `size_of::<[T; N]>() * cap / N == size_of::<T>() * cap`
3242 // - `len / N <= cap / N` because `len <= cap`
3243 // - the allocated memory consists of `len / N` valid values of type `[T; N]`
3244 // - `cap / N` fits the size of the allocated memory after shrinking
3245 unsafe { Vec::from_raw_parts_in(ptr.cast(), len / N, cap / N, alloc) }
3246 }
3247}
3248
3249impl<T: Clone, A: Allocator> Vec<T, A> {
3250 /// Resizes the `Vec` in-place so that `len` is equal to `new_len`.
3251 ///
3252 /// If `new_len` is greater than `len`, the `Vec` is extended by the
3253 /// difference, with each additional slot filled with `value`.
3254 /// If `new_len` is less than `len`, the `Vec` is simply truncated.
3255 ///
3256 /// This method requires `T` to implement [`Clone`],
3257 /// in order to be able to clone the passed value.
3258 /// If you need more flexibility (or want to rely on [`Default`] instead of
3259 /// [`Clone`]), use [`Vec::resize_with`].
3260 /// If you only need to resize to a smaller size, use [`Vec::truncate`].
3261 ///
3262 /// # Panics
3263 ///
3264 /// Panics if the new capacity exceeds `isize::MAX` _bytes_.
3265 ///
3266 /// # Examples
3267 ///
3268 /// ```
3269 /// let mut vec = vec!["hello"];
3270 /// vec.resize(3, "world");
3271 /// assert_eq!(vec, ["hello", "world", "world"]);
3272 ///
3273 /// let mut vec = vec!['a', 'b', 'c', 'd'];
3274 /// vec.resize(2, '_');
3275 /// assert_eq!(vec, ['a', 'b']);
3276 /// ```
3277 #[cfg(not(no_global_oom_handling))]
3278 #[stable(feature = "vec_resize", since = "1.5.0")]
3279 #[track_caller]
3280 pub fn resize(&mut self, new_len: usize, value: T) {
3281 let len = self.len();
3282
3283 if new_len > len {
3284 self.extend_with(new_len - len, value)
3285 } else {
3286 self.truncate(new_len);
3287 }
3288 }
3289
3290 /// Clones and appends all elements in a slice to the `Vec`.
3291 ///
3292 /// Iterates over the slice `other`, clones each element, and then appends
3293 /// it to this `Vec`. The `other` slice is traversed in-order.
3294 ///
3295 /// Note that this function is the same as [`extend`],
3296 /// except that it also works with slice elements that are Clone but not Copy.
3297 /// If Rust gets specialization this function may be deprecated.
3298 ///
3299 /// # Examples
3300 ///
3301 /// ```
3302 /// let mut vec = vec![1];
3303 /// vec.extend_from_slice(&[2, 3, 4]);
3304 /// assert_eq!(vec, [1, 2, 3, 4]);
3305 /// ```
3306 ///
3307 /// [`extend`]: Vec::extend
3308 #[cfg(not(no_global_oom_handling))]
3309 #[stable(feature = "vec_extend_from_slice", since = "1.6.0")]
3310 #[track_caller]
3311 pub fn extend_from_slice(&mut self, other: &[T]) {
3312 self.spec_extend(other.iter())
3313 }
3314
3315 /// Given a range `src`, clones a slice of elements in that range and appends it to the end.
3316 ///
3317 /// `src` must be a range that can form a valid subslice of the `Vec`.
3318 ///
3319 /// # Panics
3320 ///
3321 /// Panics if starting index is greater than the end index
3322 /// or if the index is greater than the length of the vector.
3323 ///
3324 /// # Examples
3325 ///
3326 /// ```
3327 /// let mut characters = vec!['a', 'b', 'c', 'd', 'e'];
3328 /// characters.extend_from_within(2..);
3329 /// assert_eq!(characters, ['a', 'b', 'c', 'd', 'e', 'c', 'd', 'e']);
3330 ///
3331 /// let mut numbers = vec![0, 1, 2, 3, 4];
3332 /// numbers.extend_from_within(..2);
3333 /// assert_eq!(numbers, [0, 1, 2, 3, 4, 0, 1]);
3334 ///
3335 /// let mut strings = vec![String::from("hello"), String::from("world"), String::from("!")];
3336 /// strings.extend_from_within(1..=2);
3337 /// assert_eq!(strings, ["hello", "world", "!", "world", "!"]);
3338 /// ```
3339 #[cfg(not(no_global_oom_handling))]
3340 #[stable(feature = "vec_extend_from_within", since = "1.53.0")]
3341 #[track_caller]
3342 pub fn extend_from_within<R>(&mut self, src: R)
3343 where
3344 R: RangeBounds<usize>,
3345 {
3346 let range = slice::range(src, ..self.len());
3347 self.reserve(range.len());
3348
3349 // SAFETY:
3350 // - `slice::range` guarantees that the given range is valid for indexing self
3351 unsafe {
3352 self.spec_extend_from_within(range);
3353 }
3354 }
3355}
3356
3357impl<T, A: Allocator, const N: usize> Vec<[T; N], A> {
3358 /// Takes a `Vec<[T; N]>` and flattens it into a `Vec<T>`.
3359 ///
3360 /// # Panics
3361 ///
3362 /// Panics if the length of the resulting vector would overflow a `usize`.
3363 ///
3364 /// This is only possible when flattening a vector of arrays of zero-sized
3365 /// types, and thus tends to be irrelevant in practice. If
3366 /// `size_of::<T>() > 0`, this will never panic.
3367 ///
3368 /// # Examples
3369 ///
3370 /// ```
3371 /// let mut vec = vec![[1, 2, 3], [4, 5, 6], [7, 8, 9]];
3372 /// assert_eq!(vec.pop(), Some([7, 8, 9]));
3373 ///
3374 /// let mut flattened = vec.into_flattened();
3375 /// assert_eq!(flattened.pop(), Some(6));
3376 /// ```
3377 #[stable(feature = "slice_flatten", since = "1.80.0")]
3378 pub fn into_flattened(self) -> Vec<T, A> {
3379 let (ptr, len, cap, alloc) = self.into_raw_parts_with_alloc();
3380 let (new_len, new_cap) = if T::IS_ZST {
3381 (len.checked_mul(N).expect("vec len overflow"), usize::MAX)
3382 } else {
3383 // SAFETY:
3384 // - `cap * N` cannot overflow because the allocation is already in
3385 // the address space.
3386 // - Each `[T; N]` has `N` valid elements, so there are `len * N`
3387 // valid elements in the allocation.
3388 unsafe { (len.unchecked_mul(N), cap.unchecked_mul(N)) }
3389 };
3390 // SAFETY:
3391 // - `ptr` was allocated by `self`
3392 // - `ptr` is well-aligned because `[T; N]` has the same alignment as `T`.
3393 // - `new_cap` refers to the same sized allocation as `cap` because
3394 // `new_cap * size_of::<T>()` == `cap * size_of::<[T; N]>()`
3395 // - `len` <= `cap`, so `len * N` <= `cap * N`.
3396 unsafe { Vec::<T, A>::from_raw_parts_in(ptr.cast(), new_len, new_cap, alloc) }
3397 }
3398}
3399
3400impl<T: Clone, A: Allocator> Vec<T, A> {
3401 #[cfg(not(no_global_oom_handling))]
3402 #[track_caller]
3403 /// Extend the vector by `n` clones of value.
3404 fn extend_with(&mut self, n: usize, value: T) {
3405 self.reserve(n);
3406
3407 unsafe {
3408 let mut ptr = self.as_mut_ptr().add(self.len());
3409 // Use SetLenOnDrop to work around bug where compiler
3410 // might not realize the store through `ptr` through self.set_len()
3411 // don't alias.
3412 let mut local_len = SetLenOnDrop::new(&mut self.len);
3413
3414 // Write all elements except the last one
3415 for _ in 1..n {
3416 ptr::write(ptr, value.clone());
3417 ptr = ptr.add(1);
3418 // Increment the length in every step in case clone() panics
3419 local_len.increment_len(1);
3420 }
3421
3422 if n > 0 {
3423 // We can write the last element directly without cloning needlessly
3424 ptr::write(ptr, value);
3425 local_len.increment_len(1);
3426 }
3427
3428 // len set by scope guard
3429 }
3430 }
3431}
3432
3433impl<T: PartialEq, A: Allocator> Vec<T, A> {
3434 /// Removes consecutive repeated elements in the vector according to the
3435 /// [`PartialEq`] trait implementation.
3436 ///
3437 /// If the vector is sorted, this removes all duplicates.
3438 ///
3439 /// # Examples
3440 ///
3441 /// ```
3442 /// let mut vec = vec![1, 2, 2, 3, 2];
3443 ///
3444 /// vec.dedup();
3445 ///
3446 /// assert_eq!(vec, [1, 2, 3, 2]);
3447 /// ```
3448 #[stable(feature = "rust1", since = "1.0.0")]
3449 #[inline]
3450 pub fn dedup(&mut self) {
3451 self.dedup_by(|a, b| a == b)
3452 }
3453}
3454
3455////////////////////////////////////////////////////////////////////////////////
3456// Internal methods and functions
3457////////////////////////////////////////////////////////////////////////////////
3458
3459#[doc(hidden)]
3460#[cfg(not(no_global_oom_handling))]
3461#[stable(feature = "rust1", since = "1.0.0")]
3462#[rustc_diagnostic_item = "vec_from_elem"]
3463#[track_caller]
3464pub fn from_elem<T: Clone>(elem: T, n: usize) -> Vec<T> {
3465 <T as SpecFromElem>::from_elem(elem, n, Global)
3466}
3467
3468#[doc(hidden)]
3469#[cfg(not(no_global_oom_handling))]
3470#[unstable(feature = "allocator_api", issue = "32838")]
3471#[track_caller]
3472pub fn from_elem_in<T: Clone, A: Allocator>(elem: T, n: usize, alloc: A) -> Vec<T, A> {
3473 <T as SpecFromElem>::from_elem(elem, n, alloc)
3474}
3475
3476#[cfg(not(no_global_oom_handling))]
3477trait ExtendFromWithinSpec {
3478 /// # Safety
3479 ///
3480 /// - `src` needs to be valid index
3481 /// - `self.capacity() - self.len()` must be `>= src.len()`
3482 unsafe fn spec_extend_from_within(&mut self, src: Range<usize>);
3483}
3484
3485#[cfg(not(no_global_oom_handling))]
3486impl<T: Clone, A: Allocator> ExtendFromWithinSpec for Vec<T, A> {
3487 default unsafe fn spec_extend_from_within(&mut self, src: Range<usize>) {
3488 // SAFETY:
3489 // - len is increased only after initializing elements
3490 let (this, spare, len) = unsafe { self.split_at_spare_mut_with_len() };
3491
3492 // SAFETY:
3493 // - caller guarantees that src is a valid index
3494 let to_clone = unsafe { this.get_unchecked(src) };
3495
3496 iter::zip(to_clone, spare)
3497 .map(|(src, dst)| dst.write(src.clone()))
3498 // Note:
3499 // - Element was just initialized with `MaybeUninit::write`, so it's ok to increase len
3500 // - len is increased after each element to prevent leaks (see issue #82533)
3501 .for_each(|_| *len += 1);
3502 }
3503}
3504
3505#[cfg(not(no_global_oom_handling))]
3506impl<T: Copy, A: Allocator> ExtendFromWithinSpec for Vec<T, A> {
3507 unsafe fn spec_extend_from_within(&mut self, src: Range<usize>) {
3508 let count = src.len();
3509 {
3510 let (init, spare) = self.split_at_spare_mut();
3511
3512 // SAFETY:
3513 // - caller guarantees that `src` is a valid index
3514 let source = unsafe { init.get_unchecked(src) };
3515
3516 // SAFETY:
3517 // - Both pointers are created from unique slice references (`&mut [_]`)
3518 // so they are valid and do not overlap.
3519 // - Elements are :Copy so it's OK to copy them, without doing
3520 // anything with the original values
3521 // - `count` is equal to the len of `source`, so source is valid for
3522 // `count` reads
3523 // - `.reserve(count)` guarantees that `spare.len() >= count` so spare
3524 // is valid for `count` writes
3525 unsafe { ptr::copy_nonoverlapping(source.as_ptr(), spare.as_mut_ptr() as _, count) };
3526 }
3527
3528 // SAFETY:
3529 // - The elements were just initialized by `copy_nonoverlapping`
3530 self.len += count;
3531 }
3532}
3533
3534////////////////////////////////////////////////////////////////////////////////
3535// Common trait implementations for Vec
3536////////////////////////////////////////////////////////////////////////////////
3537
3538#[stable(feature = "rust1", since = "1.0.0")]
3539impl<T, A: Allocator> ops::Deref for Vec<T, A> {
3540 type Target = [T];
3541
3542 #[inline]
3543 fn deref(&self) -> &[T] {
3544 self.as_slice()
3545 }
3546}
3547
3548#[stable(feature = "rust1", since = "1.0.0")]
3549impl<T, A: Allocator> ops::DerefMut for Vec<T, A> {
3550 #[inline]
3551 fn deref_mut(&mut self) -> &mut [T] {
3552 self.as_mut_slice()
3553 }
3554}
3555
3556#[unstable(feature = "deref_pure_trait", issue = "87121")]
3557unsafe impl<T, A: Allocator> ops::DerefPure for Vec<T, A> {}
3558
3559#[cfg(not(no_global_oom_handling))]
3560#[stable(feature = "rust1", since = "1.0.0")]
3561impl<T: Clone, A: Allocator + Clone> Clone for Vec<T, A> {
3562 #[track_caller]
3563 fn clone(&self) -> Self {
3564 let alloc = self.allocator().clone();
3565 <[T]>::to_vec_in(&**self, alloc)
3566 }
3567
3568 /// Overwrites the contents of `self` with a clone of the contents of `source`.
3569 ///
3570 /// This method is preferred over simply assigning `source.clone()` to `self`,
3571 /// as it avoids reallocation if possible. Additionally, if the element type
3572 /// `T` overrides `clone_from()`, this will reuse the resources of `self`'s
3573 /// elements as well.
3574 ///
3575 /// # Examples
3576 ///
3577 /// ```
3578 /// let x = vec![5, 6, 7];
3579 /// let mut y = vec![8, 9, 10];
3580 /// let yp: *const i32 = y.as_ptr();
3581 ///
3582 /// y.clone_from(&x);
3583 ///
3584 /// // The value is the same
3585 /// assert_eq!(x, y);
3586 ///
3587 /// // And no reallocation occurred
3588 /// assert_eq!(yp, y.as_ptr());
3589 /// ```
3590 #[track_caller]
3591 fn clone_from(&mut self, source: &Self) {
3592 crate::slice::SpecCloneIntoVec::clone_into(source.as_slice(), self);
3593 }
3594}
3595
3596/// The hash of a vector is the same as that of the corresponding slice,
3597/// as required by the `core::borrow::Borrow` implementation.
3598///
3599/// ```
3600/// use std::hash::BuildHasher;
3601///
3602/// let b = std::hash::RandomState::new();
3603/// let v: Vec<u8> = vec![0xa8, 0x3c, 0x09];
3604/// let s: &[u8] = &[0xa8, 0x3c, 0x09];
3605/// assert_eq!(b.hash_one(v), b.hash_one(s));
3606/// ```
3607#[stable(feature = "rust1", since = "1.0.0")]
3608impl<T: Hash, A: Allocator> Hash for Vec<T, A> {
3609 #[inline]
3610 fn hash<H: Hasher>(&self, state: &mut H) {
3611 Hash::hash(&**self, state)
3612 }
3613}
3614
3615#[stable(feature = "rust1", since = "1.0.0")]
3616impl<T, I: SliceIndex<[T]>, A: Allocator> Index<I> for Vec<T, A> {
3617 type Output = I::Output;
3618
3619 #[inline]
3620 fn index(&self, index: I) -> &Self::Output {
3621 Index::index(&**self, index)
3622 }
3623}
3624
3625#[stable(feature = "rust1", since = "1.0.0")]
3626impl<T, I: SliceIndex<[T]>, A: Allocator> IndexMut<I> for Vec<T, A> {
3627 #[inline]
3628 fn index_mut(&mut self, index: I) -> &mut Self::Output {
3629 IndexMut::index_mut(&mut **self, index)
3630 }
3631}
3632
3633/// Collects an iterator into a Vec, commonly called via [`Iterator::collect()`]
3634///
3635/// # Allocation behavior
3636///
3637/// In general `Vec` does not guarantee any particular growth or allocation strategy.
3638/// That also applies to this trait impl.
3639///
3640/// **Note:** This section covers implementation details and is therefore exempt from
3641/// stability guarantees.
3642///
3643/// Vec may use any or none of the following strategies,
3644/// depending on the supplied iterator:
3645///
3646/// * preallocate based on [`Iterator::size_hint()`]
3647/// * and panic if the number of items is outside the provided lower/upper bounds
3648/// * use an amortized growth strategy similar to `pushing` one item at a time
3649/// * perform the iteration in-place on the original allocation backing the iterator
3650///
3651/// The last case warrants some attention. It is an optimization that in many cases reduces peak memory
3652/// consumption and improves cache locality. But when big, short-lived allocations are created,
3653/// only a small fraction of their items get collected, no further use is made of the spare capacity
3654/// and the resulting `Vec` is moved into a longer-lived structure, then this can lead to the large
3655/// allocations having their lifetimes unnecessarily extended which can result in increased memory
3656/// footprint.
3657///
3658/// In cases where this is an issue, the excess capacity can be discarded with [`Vec::shrink_to()`],
3659/// [`Vec::shrink_to_fit()`] or by collecting into [`Box<[T]>`][owned slice] instead, which additionally reduces
3660/// the size of the long-lived struct.
3661///
3662/// [owned slice]: Box
3663///
3664/// ```rust
3665/// # use std::sync::Mutex;
3666/// static LONG_LIVED: Mutex<Vec<Vec<u16>>> = Mutex::new(Vec::new());
3667///
3668/// for i in 0..10 {
3669/// let big_temporary: Vec<u16> = (0..1024).collect();
3670/// // discard most items
3671/// let mut result: Vec<_> = big_temporary.into_iter().filter(|i| i % 100 == 0).collect();
3672/// // without this a lot of unused capacity might be moved into the global
3673/// result.shrink_to_fit();
3674/// LONG_LIVED.lock().unwrap().push(result);
3675/// }
3676/// ```
3677#[cfg(not(no_global_oom_handling))]
3678#[stable(feature = "rust1", since = "1.0.0")]
3679impl<T> FromIterator<T> for Vec<T> {
3680 #[inline]
3681 #[track_caller]
3682 fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> Vec<T> {
3683 <Self as SpecFromIter<T, I::IntoIter>>::from_iter(iter.into_iter())
3684 }
3685}
3686
3687#[stable(feature = "rust1", since = "1.0.0")]
3688impl<T, A: Allocator> IntoIterator for Vec<T, A> {
3689 type Item = T;
3690 type IntoIter = IntoIter<T, A>;
3691
3692 /// Creates a consuming iterator, that is, one that moves each value out of
3693 /// the vector (from start to end). The vector cannot be used after calling
3694 /// this.
3695 ///
3696 /// # Examples
3697 ///
3698 /// ```
3699 /// let v = vec!["a".to_string(), "b".to_string()];
3700 /// let mut v_iter = v.into_iter();
3701 ///
3702 /// let first_element: Option<String> = v_iter.next();
3703 ///
3704 /// assert_eq!(first_element, Some("a".to_string()));
3705 /// assert_eq!(v_iter.next(), Some("b".to_string()));
3706 /// assert_eq!(v_iter.next(), None);
3707 /// ```
3708 #[inline]
3709 fn into_iter(self) -> Self::IntoIter {
3710 unsafe {
3711 let me = ManuallyDrop::new(self);
3712 let alloc = ManuallyDrop::new(ptr::read(me.allocator()));
3713 let buf = me.buf.non_null();
3714 let begin = buf.as_ptr();
3715 let end = if T::IS_ZST {
3716 begin.wrapping_byte_add(me.len())
3717 } else {
3718 begin.add(me.len()) as *const T
3719 };
3720 let cap = me.buf.capacity();
3721 IntoIter { buf, phantom: PhantomData, cap, alloc, ptr: buf, end }
3722 }
3723 }
3724}
3725
3726#[stable(feature = "rust1", since = "1.0.0")]
3727impl<'a, T, A: Allocator> IntoIterator for &'a Vec<T, A> {
3728 type Item = &'a T;
3729 type IntoIter = slice::Iter<'a, T>;
3730
3731 fn into_iter(self) -> Self::IntoIter {
3732 self.iter()
3733 }
3734}
3735
3736#[stable(feature = "rust1", since = "1.0.0")]
3737impl<'a, T, A: Allocator> IntoIterator for &'a mut Vec<T, A> {
3738 type Item = &'a mut T;
3739 type IntoIter = slice::IterMut<'a, T>;
3740
3741 fn into_iter(self) -> Self::IntoIter {
3742 self.iter_mut()
3743 }
3744}
3745
3746#[cfg(not(no_global_oom_handling))]
3747#[stable(feature = "rust1", since = "1.0.0")]
3748impl<T, A: Allocator> Extend<T> for Vec<T, A> {
3749 #[inline]
3750 #[track_caller]
3751 fn extend<I: IntoIterator<Item = T>>(&mut self, iter: I) {
3752 <Self as SpecExtend<T, I::IntoIter>>::spec_extend(self, iter.into_iter())
3753 }
3754
3755 #[inline]
3756 #[track_caller]
3757 fn extend_one(&mut self, item: T) {
3758 self.push(item);
3759 }
3760
3761 #[inline]
3762 #[track_caller]
3763 fn extend_reserve(&mut self, additional: usize) {
3764 self.reserve(additional);
3765 }
3766
3767 #[inline]
3768 unsafe fn extend_one_unchecked(&mut self, item: T) {
3769 // SAFETY: Our preconditions ensure the space has been reserved, and `extend_reserve` is implemented correctly.
3770 unsafe {
3771 let len = self.len();
3772 ptr::write(self.as_mut_ptr().add(len), item);
3773 self.set_len(len + 1);
3774 }
3775 }
3776}
3777
3778impl<T, A: Allocator> Vec<T, A> {
3779 // leaf method to which various SpecFrom/SpecExtend implementations delegate when
3780 // they have no further optimizations to apply
3781 #[cfg(not(no_global_oom_handling))]
3782 #[track_caller]
3783 fn extend_desugared<I: Iterator<Item = T>>(&mut self, mut iterator: I) {
3784 // This is the case for a general iterator.
3785 //
3786 // This function should be the moral equivalent of:
3787 //
3788 // for item in iterator {
3789 // self.push(item);
3790 // }
3791 while let Some(element) = iterator.next() {
3792 let len = self.len();
3793 if len == self.capacity() {
3794 let (lower, _) = iterator.size_hint();
3795 self.reserve(lower.saturating_add(1));
3796 }
3797 unsafe {
3798 ptr::write(self.as_mut_ptr().add(len), element);
3799 // Since next() executes user code which can panic we have to bump the length
3800 // after each step.
3801 // NB can't overflow since we would have had to alloc the address space
3802 self.set_len(len + 1);
3803 }
3804 }
3805 }
3806
3807 // specific extend for `TrustedLen` iterators, called both by the specializations
3808 // and internal places where resolving specialization makes compilation slower
3809 #[cfg(not(no_global_oom_handling))]
3810 #[track_caller]
3811 fn extend_trusted(&mut self, iterator: impl iter::TrustedLen<Item = T>) {
3812 let (low, high) = iterator.size_hint();
3813 if let Some(additional) = high {
3814 debug_assert_eq!(
3815 low,
3816 additional,
3817 "TrustedLen iterator's size hint is not exact: {:?}",
3818 (low, high)
3819 );
3820 self.reserve(additional);
3821 unsafe {
3822 let ptr = self.as_mut_ptr();
3823 let mut local_len = SetLenOnDrop::new(&mut self.len);
3824 iterator.for_each(move |element| {
3825 ptr::write(ptr.add(local_len.current_len()), element);
3826 // Since the loop executes user code which can panic we have to update
3827 // the length every step to correctly drop what we've written.
3828 // NB can't overflow since we would have had to alloc the address space
3829 local_len.increment_len(1);
3830 });
3831 }
3832 } else {
3833 // Per TrustedLen contract a `None` upper bound means that the iterator length
3834 // truly exceeds usize::MAX, which would eventually lead to a capacity overflow anyway.
3835 // Since the other branch already panics eagerly (via `reserve()`) we do the same here.
3836 // This avoids additional codegen for a fallback code path which would eventually
3837 // panic anyway.
3838 panic!("capacity overflow");
3839 }
3840 }
3841
3842 /// Creates a splicing iterator that replaces the specified range in the vector
3843 /// with the given `replace_with` iterator and yields the removed items.
3844 /// `replace_with` does not need to be the same length as `range`.
3845 ///
3846 /// `range` is removed even if the `Splice` iterator is not consumed before it is dropped.
3847 ///
3848 /// It is unspecified how many elements are removed from the vector
3849 /// if the `Splice` value is leaked.
3850 ///
3851 /// The input iterator `replace_with` is only consumed when the `Splice` value is dropped.
3852 ///
3853 /// This is optimal if:
3854 ///
3855 /// * The tail (elements in the vector after `range`) is empty,
3856 /// * or `replace_with` yields fewer or equal elements than `range`'s length
3857 /// * or the lower bound of its `size_hint()` is exact.
3858 ///
3859 /// Otherwise, a temporary vector is allocated and the tail is moved twice.
3860 ///
3861 /// # Panics
3862 ///
3863 /// Panics if the range has `start_bound > end_bound`, or, if the range is
3864 /// bounded on either end and past the length of the vector.
3865 ///
3866 /// # Examples
3867 ///
3868 /// ```
3869 /// let mut v = vec![1, 2, 3, 4];
3870 /// let new = [7, 8, 9];
3871 /// let u: Vec<_> = v.splice(1..3, new).collect();
3872 /// assert_eq!(v, [1, 7, 8, 9, 4]);
3873 /// assert_eq!(u, [2, 3]);
3874 /// ```
3875 ///
3876 /// Using `splice` to insert new items into a vector efficiently at a specific position
3877 /// indicated by an empty range:
3878 ///
3879 /// ```
3880 /// let mut v = vec![1, 5];
3881 /// let new = [2, 3, 4];
3882 /// v.splice(1..1, new);
3883 /// assert_eq!(v, [1, 2, 3, 4, 5]);
3884 /// ```
3885 #[cfg(not(no_global_oom_handling))]
3886 #[inline]
3887 #[stable(feature = "vec_splice", since = "1.21.0")]
3888 pub fn splice<R, I>(&mut self, range: R, replace_with: I) -> Splice<'_, I::IntoIter, A>
3889 where
3890 R: RangeBounds<usize>,
3891 I: IntoIterator<Item = T>,
3892 {
3893 Splice { drain: self.drain(range), replace_with: replace_with.into_iter() }
3894 }
3895
3896 /// Creates an iterator which uses a closure to determine if an element in the range should be removed.
3897 ///
3898 /// If the closure returns `true`, the element is removed from the vector
3899 /// and yielded. If the closure returns `false`, or panics, the element
3900 /// remains in the vector and will not be yielded.
3901 ///
3902 /// Only elements that fall in the provided range are considered for extraction, but any elements
3903 /// after the range will still have to be moved if any element has been extracted.
3904 ///
3905 /// If the returned `ExtractIf` is not exhausted, e.g. because it is dropped without iterating
3906 /// or the iteration short-circuits, then the remaining elements will be retained.
3907 /// Use [`retain_mut`] with a negated predicate if you do not need the returned iterator.
3908 ///
3909 /// [`retain_mut`]: Vec::retain_mut
3910 ///
3911 /// Using this method is equivalent to the following code:
3912 ///
3913 /// ```
3914 /// # let some_predicate = |x: &mut i32| { *x % 2 == 1 };
3915 /// # let mut vec = vec![0, 1, 2, 3, 4, 5, 6];
3916 /// # let mut vec2 = vec.clone();
3917 /// # let range = 1..5;
3918 /// let mut i = range.start;
3919 /// let end_items = vec.len() - range.end;
3920 /// # let mut extracted = vec![];
3921 ///
3922 /// while i < vec.len() - end_items {
3923 /// if some_predicate(&mut vec[i]) {
3924 /// let val = vec.remove(i);
3925 /// // your code here
3926 /// # extracted.push(val);
3927 /// } else {
3928 /// i += 1;
3929 /// }
3930 /// }
3931 ///
3932 /// # let extracted2: Vec<_> = vec2.extract_if(range, some_predicate).collect();
3933 /// # assert_eq!(vec, vec2);
3934 /// # assert_eq!(extracted, extracted2);
3935 /// ```
3936 ///
3937 /// But `extract_if` is easier to use. `extract_if` is also more efficient,
3938 /// because it can backshift the elements of the array in bulk.
3939 ///
3940 /// The iterator also lets you mutate the value of each element in the
3941 /// closure, regardless of whether you choose to keep or remove it.
3942 ///
3943 /// # Panics
3944 ///
3945 /// If `range` is out of bounds.
3946 ///
3947 /// # Examples
3948 ///
3949 /// Splitting a vector into even and odd values, reusing the original vector:
3950 ///
3951 /// ```
3952 /// let mut numbers = vec![1, 2, 3, 4, 5, 6, 8, 9, 11, 13, 14, 15];
3953 ///
3954 /// let evens = numbers.extract_if(.., |x| *x % 2 == 0).collect::<Vec<_>>();
3955 /// let odds = numbers;
3956 ///
3957 /// assert_eq!(evens, vec![2, 4, 6, 8, 14]);
3958 /// assert_eq!(odds, vec![1, 3, 5, 9, 11, 13, 15]);
3959 /// ```
3960 ///
3961 /// Using the range argument to only process a part of the vector:
3962 ///
3963 /// ```
3964 /// let mut items = vec![0, 0, 0, 0, 0, 0, 0, 1, 2, 1, 2, 1, 2];
3965 /// let ones = items.extract_if(7.., |x| *x == 1).collect::<Vec<_>>();
3966 /// assert_eq!(items, vec![0, 0, 0, 0, 0, 0, 0, 2, 2, 2]);
3967 /// assert_eq!(ones.len(), 3);
3968 /// ```
3969 #[stable(feature = "extract_if", since = "1.87.0")]
3970 pub fn extract_if<F, R>(&mut self, range: R, filter: F) -> ExtractIf<'_, T, F, A>
3971 where
3972 F: FnMut(&mut T) -> bool,
3973 R: RangeBounds<usize>,
3974 {
3975 ExtractIf::new(self, filter, range)
3976 }
3977}
3978
3979/// Extend implementation that copies elements out of references before pushing them onto the Vec.
3980///
3981/// This implementation is specialized for slice iterators, where it uses [`copy_from_slice`] to
3982/// append the entire slice at once.
3983///
3984/// [`copy_from_slice`]: slice::copy_from_slice
3985#[cfg(not(no_global_oom_handling))]
3986#[stable(feature = "extend_ref", since = "1.2.0")]
3987impl<'a, T: Copy + 'a, A: Allocator> Extend<&'a T> for Vec<T, A> {
3988 #[track_caller]
3989 fn extend<I: IntoIterator<Item = &'a T>>(&mut self, iter: I) {
3990 self.spec_extend(iter.into_iter())
3991 }
3992
3993 #[inline]
3994 #[track_caller]
3995 fn extend_one(&mut self, &item: &'a T) {
3996 self.push(item);
3997 }
3998
3999 #[inline]
4000 #[track_caller]
4001 fn extend_reserve(&mut self, additional: usize) {
4002 self.reserve(additional);
4003 }
4004
4005 #[inline]
4006 unsafe fn extend_one_unchecked(&mut self, &item: &'a T) {
4007 // SAFETY: Our preconditions ensure the space has been reserved, and `extend_reserve` is implemented correctly.
4008 unsafe {
4009 let len = self.len();
4010 ptr::write(self.as_mut_ptr().add(len), item);
4011 self.set_len(len + 1);
4012 }
4013 }
4014}
4015
4016/// Implements comparison of vectors, [lexicographically](Ord#lexicographical-comparison).
4017#[stable(feature = "rust1", since = "1.0.0")]
4018impl<T, A1, A2> PartialOrd<Vec<T, A2>> for Vec<T, A1>
4019where
4020 T: PartialOrd,
4021 A1: Allocator,
4022 A2: Allocator,
4023{
4024 #[inline]
4025 fn partial_cmp(&self, other: &Vec<T, A2>) -> Option<Ordering> {
4026 PartialOrd::partial_cmp(&**self, &**other)
4027 }
4028}
4029
4030#[stable(feature = "rust1", since = "1.0.0")]
4031impl<T: Eq, A: Allocator> Eq for Vec<T, A> {}
4032
4033/// Implements ordering of vectors, [lexicographically](Ord#lexicographical-comparison).
4034#[stable(feature = "rust1", since = "1.0.0")]
4035impl<T: Ord, A: Allocator> Ord for Vec<T, A> {
4036 #[inline]
4037 fn cmp(&self, other: &Self) -> Ordering {
4038 Ord::cmp(&**self, &**other)
4039 }
4040}
4041
4042#[stable(feature = "rust1", since = "1.0.0")]
4043unsafe impl<#[may_dangle] T, A: Allocator> Drop for Vec<T, A> {
4044 fn drop(&mut self) {
4045 unsafe {
4046 // use drop for [T]
4047 // use a raw slice to refer to the elements of the vector as weakest necessary type;
4048 // could avoid questions of validity in certain cases
4049 ptr::drop_in_place(ptr::slice_from_raw_parts_mut(self.as_mut_ptr(), self.len))
4050 }
4051 // RawVec handles deallocation
4052 }
4053}
4054
4055#[stable(feature = "rust1", since = "1.0.0")]
4056#[rustc_const_unstable(feature = "const_default", issue = "143894")]
4057impl<T> const Default for Vec<T> {
4058 /// Creates an empty `Vec<T>`.
4059 ///
4060 /// The vector will not allocate until elements are pushed onto it.
4061 fn default() -> Vec<T> {
4062 Vec::new()
4063 }
4064}
4065
4066#[stable(feature = "rust1", since = "1.0.0")]
4067impl<T: fmt::Debug, A: Allocator> fmt::Debug for Vec<T, A> {
4068 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
4069 fmt::Debug::fmt(&**self, f)
4070 }
4071}
4072
4073#[stable(feature = "rust1", since = "1.0.0")]
4074impl<T, A: Allocator> AsRef<Vec<T, A>> for Vec<T, A> {
4075 fn as_ref(&self) -> &Vec<T, A> {
4076 self
4077 }
4078}
4079
4080#[stable(feature = "vec_as_mut", since = "1.5.0")]
4081impl<T, A: Allocator> AsMut<Vec<T, A>> for Vec<T, A> {
4082 fn as_mut(&mut self) -> &mut Vec<T, A> {
4083 self
4084 }
4085}
4086
4087#[stable(feature = "rust1", since = "1.0.0")]
4088impl<T, A: Allocator> AsRef<[T]> for Vec<T, A> {
4089 fn as_ref(&self) -> &[T] {
4090 self
4091 }
4092}
4093
4094#[stable(feature = "vec_as_mut", since = "1.5.0")]
4095impl<T, A: Allocator> AsMut<[T]> for Vec<T, A> {
4096 fn as_mut(&mut self) -> &mut [T] {
4097 self
4098 }
4099}
4100
4101#[cfg(not(no_global_oom_handling))]
4102#[stable(feature = "rust1", since = "1.0.0")]
4103impl<T: Clone> From<&[T]> for Vec<T> {
4104 /// Allocates a `Vec<T>` and fills it by cloning `s`'s items.
4105 ///
4106 /// # Examples
4107 ///
4108 /// ```
4109 /// assert_eq!(Vec::from(&[1, 2, 3][..]), vec![1, 2, 3]);
4110 /// ```
4111 #[track_caller]
4112 fn from(s: &[T]) -> Vec<T> {
4113 s.to_vec()
4114 }
4115}
4116
4117#[cfg(not(no_global_oom_handling))]
4118#[stable(feature = "vec_from_mut", since = "1.19.0")]
4119impl<T: Clone> From<&mut [T]> for Vec<T> {
4120 /// Allocates a `Vec<T>` and fills it by cloning `s`'s items.
4121 ///
4122 /// # Examples
4123 ///
4124 /// ```
4125 /// assert_eq!(Vec::from(&mut [1, 2, 3][..]), vec![1, 2, 3]);
4126 /// ```
4127 #[track_caller]
4128 fn from(s: &mut [T]) -> Vec<T> {
4129 s.to_vec()
4130 }
4131}
4132
4133#[cfg(not(no_global_oom_handling))]
4134#[stable(feature = "vec_from_array_ref", since = "1.74.0")]
4135impl<T: Clone, const N: usize> From<&[T; N]> for Vec<T> {
4136 /// Allocates a `Vec<T>` and fills it by cloning `s`'s items.
4137 ///
4138 /// # Examples
4139 ///
4140 /// ```
4141 /// assert_eq!(Vec::from(&[1, 2, 3]), vec![1, 2, 3]);
4142 /// ```
4143 #[track_caller]
4144 fn from(s: &[T; N]) -> Vec<T> {
4145 Self::from(s.as_slice())
4146 }
4147}
4148
4149#[cfg(not(no_global_oom_handling))]
4150#[stable(feature = "vec_from_array_ref", since = "1.74.0")]
4151impl<T: Clone, const N: usize> From<&mut [T; N]> for Vec<T> {
4152 /// Allocates a `Vec<T>` and fills it by cloning `s`'s items.
4153 ///
4154 /// # Examples
4155 ///
4156 /// ```
4157 /// assert_eq!(Vec::from(&mut [1, 2, 3]), vec![1, 2, 3]);
4158 /// ```
4159 #[track_caller]
4160 fn from(s: &mut [T; N]) -> Vec<T> {
4161 Self::from(s.as_mut_slice())
4162 }
4163}
4164
4165#[cfg(not(no_global_oom_handling))]
4166#[stable(feature = "vec_from_array", since = "1.44.0")]
4167impl<T, const N: usize> From<[T; N]> for Vec<T> {
4168 /// Allocates a `Vec<T>` and moves `s`'s items into it.
4169 ///
4170 /// # Examples
4171 ///
4172 /// ```
4173 /// assert_eq!(Vec::from([1, 2, 3]), vec![1, 2, 3]);
4174 /// ```
4175 #[track_caller]
4176 fn from(s: [T; N]) -> Vec<T> {
4177 <[T]>::into_vec(Box::new(s))
4178 }
4179}
4180
4181#[stable(feature = "vec_from_cow_slice", since = "1.14.0")]
4182impl<'a, T> From<Cow<'a, [T]>> for Vec<T>
4183where
4184 [T]: ToOwned<Owned = Vec<T>>,
4185{
4186 /// Converts a clone-on-write slice into a vector.
4187 ///
4188 /// If `s` already owns a `Vec<T>`, it will be returned directly.
4189 /// If `s` is borrowing a slice, a new `Vec<T>` will be allocated and
4190 /// filled by cloning `s`'s items into it.
4191 ///
4192 /// # Examples
4193 ///
4194 /// ```
4195 /// # use std::borrow::Cow;
4196 /// let o: Cow<'_, [i32]> = Cow::Owned(vec![1, 2, 3]);
4197 /// let b: Cow<'_, [i32]> = Cow::Borrowed(&[1, 2, 3]);
4198 /// assert_eq!(Vec::from(o), Vec::from(b));
4199 /// ```
4200 #[track_caller]
4201 fn from(s: Cow<'a, [T]>) -> Vec<T> {
4202 s.into_owned()
4203 }
4204}
4205
4206// note: test pulls in std, which causes errors here
4207#[stable(feature = "vec_from_box", since = "1.18.0")]
4208impl<T, A: Allocator> From<Box<[T], A>> for Vec<T, A> {
4209 /// Converts a boxed slice into a vector by transferring ownership of
4210 /// the existing heap allocation.
4211 ///
4212 /// # Examples
4213 ///
4214 /// ```
4215 /// let b: Box<[i32]> = vec![1, 2, 3].into_boxed_slice();
4216 /// assert_eq!(Vec::from(b), vec![1, 2, 3]);
4217 /// ```
4218 fn from(s: Box<[T], A>) -> Self {
4219 s.into_vec()
4220 }
4221}
4222
4223// note: test pulls in std, which causes errors here
4224#[cfg(not(no_global_oom_handling))]
4225#[stable(feature = "box_from_vec", since = "1.20.0")]
4226impl<T, A: Allocator> From<Vec<T, A>> for Box<[T], A> {
4227 /// Converts a vector into a boxed slice.
4228 ///
4229 /// Before doing the conversion, this method discards excess capacity like [`Vec::shrink_to_fit`].
4230 ///
4231 /// [owned slice]: Box
4232 /// [`Vec::shrink_to_fit`]: Vec::shrink_to_fit
4233 ///
4234 /// # Examples
4235 ///
4236 /// ```
4237 /// assert_eq!(Box::from(vec![1, 2, 3]), vec![1, 2, 3].into_boxed_slice());
4238 /// ```
4239 ///
4240 /// Any excess capacity is removed:
4241 /// ```
4242 /// let mut vec = Vec::with_capacity(10);
4243 /// vec.extend([1, 2, 3]);
4244 ///
4245 /// assert_eq!(Box::from(vec), vec![1, 2, 3].into_boxed_slice());
4246 /// ```
4247 #[track_caller]
4248 fn from(v: Vec<T, A>) -> Self {
4249 v.into_boxed_slice()
4250 }
4251}
4252
4253#[cfg(not(no_global_oom_handling))]
4254#[stable(feature = "rust1", since = "1.0.0")]
4255impl From<&str> for Vec<u8> {
4256 /// Allocates a `Vec<u8>` and fills it with a UTF-8 string.
4257 ///
4258 /// # Examples
4259 ///
4260 /// ```
4261 /// assert_eq!(Vec::from("123"), vec![b'1', b'2', b'3']);
4262 /// ```
4263 #[track_caller]
4264 fn from(s: &str) -> Vec<u8> {
4265 From::from(s.as_bytes())
4266 }
4267}
4268
4269#[stable(feature = "array_try_from_vec", since = "1.48.0")]
4270impl<T, A: Allocator, const N: usize> TryFrom<Vec<T, A>> for [T; N] {
4271 type Error = Vec<T, A>;
4272
4273 /// Gets the entire contents of the `Vec<T>` as an array,
4274 /// if its size exactly matches that of the requested array.
4275 ///
4276 /// # Examples
4277 ///
4278 /// ```
4279 /// assert_eq!(vec![1, 2, 3].try_into(), Ok([1, 2, 3]));
4280 /// assert_eq!(<Vec<i32>>::new().try_into(), Ok([]));
4281 /// ```
4282 ///
4283 /// If the length doesn't match, the input comes back in `Err`:
4284 /// ```
4285 /// let r: Result<[i32; 4], _> = (0..10).collect::<Vec<_>>().try_into();
4286 /// assert_eq!(r, Err(vec![0, 1, 2, 3, 4, 5, 6, 7, 8, 9]));
4287 /// ```
4288 ///
4289 /// If you're fine with just getting a prefix of the `Vec<T>`,
4290 /// you can call [`.truncate(N)`](Vec::truncate) first.
4291 /// ```
4292 /// let mut v = String::from("hello world").into_bytes();
4293 /// v.sort();
4294 /// v.truncate(2);
4295 /// let [a, b]: [_; 2] = v.try_into().unwrap();
4296 /// assert_eq!(a, b' ');
4297 /// assert_eq!(b, b'd');
4298 /// ```
4299 fn try_from(mut vec: Vec<T, A>) -> Result<[T; N], Vec<T, A>> {
4300 if vec.len() != N {
4301 return Err(vec);
4302 }
4303
4304 // SAFETY: `.set_len(0)` is always sound.
4305 unsafe { vec.set_len(0) };
4306
4307 // SAFETY: A `Vec`'s pointer is always aligned properly, and
4308 // the alignment the array needs is the same as the items.
4309 // We checked earlier that we have sufficient items.
4310 // The items will not double-drop as the `set_len`
4311 // tells the `Vec` not to also drop them.
4312 let array = unsafe { ptr::read(vec.as_ptr() as *const [T; N]) };
4313 Ok(array)
4314 }
4315}