79 /// capacity of the vector (the number of elements that currently fit into the vector), its length
80 /// (the number of elements that are currently stored in the vector) and the `Allocator` type used
86 /// [`Vec`]'s backing buffer gets, if required, automatically increased (re-allocated) when elements
94 /// - `self.len` always represents the exact number of elements stored in the vector.
96 /// - `self.layout` represents the absolute number of elements that can be stored within the vector
109     /// elements we can still store without reallocating.
154 // SAFETY: `Vec` is `Send` if `T` is `Send` because `Vec` owns its elements.
162 // SAFETY: `Vec` is `Sync` if `T` is `Sync` because `Vec` owns its elements.
179     /// Returns the number of elements that can be stored within the vector without allocating
189     /// Returns the number of elements stored within the vector.
200     /// - All elements within the interval [`self.len`,`self.len + additional`) must be initialized.
206         // elements stored within `self`.  in inc_len()
212     /// Returns a mutable slice to the elements forgotten by the vector. It is the caller's
213     /// responsibility to drop these elements if necessary.
220         // INVARIANT: We relinquish ownership of the elements within the range `[self.len - count,  in dec_len()
221         // self.len)`, hence the updated value of `set.len` represents the exact number of elements  in dec_len()
225         // elements of type `T`.  in dec_len()
265     /// Returns `true` if the vector contains no elements, `false` otherwise.
289         // - `len` is zero, since no elements can be or have been stored,  in new()
480         // SAFETY: `p.add(1).add(self.len - i - 1)` is `i+1+len-i-1 == len` elements after the  in remove()
546     /// - The first `length` elements must be initialized values of type `T`.
573     /// This will not run the destructor of the contained elements and for non-ZSTs the allocation
575     /// elements and free the allocation, if any.
604     /// Ensures that the capacity exceeds the length by at least `additional` elements.
684             // SAFETY: the contract of `dec_len` guarantees that the elements in `ptr` are  in truncate()
685             // valid elements whose ownership has been transferred to the caller.  in truncate()
707         // INVARIANT: The first `len` elements of the spare capacity are valid values, and as we  in drain_all()
710             elements: elems.iter_mut(),  in drain_all()
714     /// Removes all elements that don't match the provided closure.
758         // - the loop and the line above initialized the next `n` elements.  in extend_with()
764     /// Pushes clones of the elements of slice into the [`Vec`] instance.
863         // - all elements within `b` are initialized values of `T`,
891         // initialized elements of type `T`.  in deref()
903         // initialized elements of type `T`.  in deref_mut()
1071 /// An [`Iterator`] implementation for [`Vec`] that moves elements out of a vector.
1139     /// buffer. However, this backing buffer may be shrunk to the actual count of elements.
1183         // SAFETY: If the iterator has been advanced, the advanced elements have been copied to  in collect()
1326     elements: slice::IterMut<'vec, T>,  field
1333         let elem: *mut T = self.elements.next()?;  in next()
1339         self.elements.size_hint()  in size_hint()
1346             let iter = core::mem::take(&mut self.elements);  in drop()