203 /// [Capacity and Reallocation](#capacity-and-reallocation).
265 /// # Capacity and reallocation
267 /// The capacity of a vector is the amount of space allocated for any future
270 /// within the vector. If a vector's length exceeds its capacity, its capacity
274 /// For example, a vector with capacity 10 and length 0 would be an empty vector
276 /// vector will not change its capacity or cause reallocation to occur. However,
290 /// Most fundamentally, `Vec` is and always will be a (pointer, capacity, length)
296 /// if you construct a `Vec` with capacity 0 via [`Vec::new`], [`vec![]`][`vec!`],
300 /// the `Vec` might not report a [`capacity`] of 0*. `Vec` will allocate if and only
301 /// if <code>[mem::size_of::\<T>]\() * [capacity]\() > 0</code>. In general, `Vec`'s allocation
310 /// you would see if you coerced it to a slice), followed by <code>[capacity] - [len]</code>
313 /// A vector containing the elements `'a'` and `'b'` with capacity 4 can be
315 /// pointer to the head of the allocation in the heap, length and capacity.
319 ///             ptr      len  capacity
351 /// [`push`] and [`insert`] will never (re)allocate if the reported capacity is
353 /// <code>[len] == [capacity]</code>. That is, the reported capacity is completely
365 /// with exactly the requested capacity. If <code>[len] == [capacity]</code>,
377 /// not break, however: using `unsafe` code to write to the excess capacity,
389 /// [capacity]: Vec::capacity
390 /// [`capacity`]: Vec::capacity
430     /// Constructs a new, empty `Vec<T>` with the specified capacity.
432     /// The vector will be able to hold exactly `capacity` elements without
433     /// reallocating. If `capacity` is 0, the vector will not allocate.
436     /// *capacity* specified, the vector will have a zero *length*. For an
437     /// explanation of the difference between length and capacity, see
438     /// *[Capacity and reallocation]*.
440     /// [Capacity and reallocation]: #capacity-and-reallocation
444     /// Panics if the new capacity exceeds `isize::MAX` bytes.
451     /// // The vector contains no items, even though it has capacity for more
453     /// assert_eq!(vec.capacity(), 10);
460     /// assert_eq!(vec.capacity(), 10);
465     /// assert!(vec.capacity() >= 11);
471     pub fn with_capacity(capacity: usize) -> Self {  in with_capacity()
472         Self::with_capacity_in(capacity, Global)  in with_capacity()
488     /// * The size of `T` times the `capacity` (ie. the allocated size in bytes) needs
491     /// * `length` needs to be less than or equal to `capacity`.
530     /// let cap = v.capacity();
545     pub unsafe fn from_raw_parts(ptr: *mut T, length: usize, capacity: usize) -> Self {  in from_raw_parts()
546         unsafe { Self::from_raw_parts_in(ptr, length, capacity, Global) }  in from_raw_parts()
571     /// Constructs a new, empty `Vec<T, A>` with the specified capacity with the provided
574     /// The vector will be able to hold exactly `capacity` elements without
575     /// reallocating. If `capacity` is 0, the vector will not allocate.
578     /// *capacity* specified, the vector will have a zero *length*. For an
579     /// explanation of the difference between length and capacity, see
580     /// *[Capacity and reallocation]*.
582     /// [Capacity and reallocation]: #capacity-and-reallocation
586     /// Panics if the new capacity exceeds `isize::MAX` bytes.
597     /// // The vector contains no items, even though it has capacity for more
599     /// assert_eq!(vec.capacity(), 10);
606     /// assert_eq!(vec.capacity(), 10);
611     /// assert!(vec.capacity() >= 11);
616     pub fn with_capacity_in(capacity: usize, alloc: A) -> Self {  in with_capacity_in()
617         Vec { buf: RawVec::with_capacity_in(capacity, alloc), len: 0 }  in with_capacity_in()
633     /// * `length` needs to be less than or equal to `capacity`.
634     /// * `capacity` needs to be the capacity that the pointer was allocated with.
676     /// let cap = v.capacity();
692     pub unsafe fn from_raw_parts_in(ptr: *mut T, length: usize, capacity: usize, alloc: A) -> Self {  in from_raw_parts_in()
693         unsafe { Vec { buf: RawVec::from_raw_parts_in(ptr, capacity, alloc), len: length } }  in from_raw_parts_in()
699     /// the vector (in elements), and the allocated capacity of the
705     /// this is to convert the raw pointer, length, and capacity back
731         (me.as_mut_ptr(), me.len(), me.capacity())  in into_raw_parts()
737     /// the allocated capacity of the data (in elements), and the allocator. These are the same
742     /// this is to convert the raw pointer, length, and capacity back
776         let capacity = me.capacity();  in into_raw_parts_with_alloc()  localVariable
779         (ptr, len, capacity, alloc)  in into_raw_parts_with_alloc()
789     /// assert_eq!(vec.capacity(), 10);
793     pub fn capacity(&self) -> usize {  in capacity()  method
794         self.buf.capacity()  in capacity()
797     /// Reserves capacity for at least `additional` more elements to be inserted
799     /// frequent reallocations. After calling `reserve`, capacity will be
801     /// capacity is already sufficient.
805     /// Panics if the new capacity exceeds `isize::MAX` bytes.
812     /// assert!(vec.capacity() >= 11);
820     /// Reserves the minimum capacity for exactly `additional` more elements to
822     /// capacity will be greater than or equal to `self.len() + additional`.
823     /// Does nothing if the capacity is already sufficient.
826     /// requests. Therefore, capacity can not be relied upon to be precisely
833     /// Panics if the new capacity exceeds `isize::MAX` bytes.
840     /// assert!(vec.capacity() >= 11);
848     /// Tries to reserve capacity for at least `additional` more elements to be inserted
850     /// frequent reallocations. After calling `try_reserve`, capacity will be
852     /// capacity is already sufficient.
856     /// If the capacity overflows, or the allocator reports a failure, then an error
884     /// Tries to reserve the minimum capacity for exactly `additional`
886     /// `try_reserve_exact`, capacity will be greater than or equal to
888     /// Does nothing if the capacity is already sufficient.
891     /// requests. Therefore, capacity can not be relied upon to be precisely
898     /// If the capacity overflows, or the allocator reports a failure, then an error
926     /// Shrinks the capacity of the vector as much as possible.
936     /// assert_eq!(vec.capacity(), 10);
938     /// assert!(vec.capacity() >= 3);
943         // The capacity is never less than the length, and there's nothing to do when  in shrink_to_fit()
945         // by only calling it with a greater capacity.  in shrink_to_fit()
946         if self.capacity() > self.len {  in shrink_to_fit()
951     /// Shrinks the capacity of the vector with a lower bound.
953     /// The capacity will remain at least as large as both the length
956     /// If the current capacity is less than the lower limit, this is a no-op.
963     /// assert_eq!(vec.capacity(), 10);
965     /// assert!(vec.capacity() >= 4);
967     /// assert!(vec.capacity() >= 3);
972         if self.capacity() > min_capacity {  in shrink_to()
979     /// Note that this will drop any excess capacity.
991     /// Any excess capacity is removed:
997     /// assert_eq!(vec.capacity(), 10);
999     /// assert_eq!(slice.into_vec().capacity(), 3);
1022     /// Note that this method has no effect on the allocated capacity
1206     /// - `new_len` must be less than or equal to [`capacity()`].
1209     /// [`capacity()`]: Vec::capacity
1236     ///     // 2. `dict_length` <= the capacity (32_768)
1262     /// // 2. `0 <= capacity` always holds whatever `capacity` is.
1273         debug_assert!(new_len <= self.capacity());  in set_len()
1358         if len == self.buf.capacity() {  in insert()
1719     /// Panics if the new capacity exceeds `isize::MAX` bytes.
1734         if self.len == self.buf.capacity() {  in push()
1756         if self.len == self.buf.capacity() {  in try_push()
1896     /// Note that this method has no effect on the allocated capacity
1960     /// the elements `[0, at)` with its previous capacity unchanged.
1996                 Vec::with_capacity_in(self.capacity(), self.allocator().clone()),  in split_off()
2059     /// so the leaked allocation may include unused capacity that is not part
2087     /// Returns the remaining spare capacity of the vector as a slice of
2124                 self.buf.capacity() - self.len,  in spare_capacity_mut()
2130     /// capacity of the vector as a slice of `MaybeUninit<T>`.
2132     /// The returned spare capacity slice can be used to fill the vector with data
2198         // - but the allocation extends out to `self.buf.capacity()` elements, possibly  in split_at_spare_mut_with_len()
2202         let spare_len = self.buf.capacity() - self.len;  in split_at_spare_mut_with_len()
2462     /// - `self.capacity() - self.len()` must be `>= src.len()`
2670             let cap = me.buf.capacity();  in into_iter()
2736             if len == self.capacity() {  in extend_desugared()
3066     /// If `v` has excess capacity, its items will be moved into a
3067     /// newly-allocated buffer with exactly the right capacity.