@@ -148,6 +148,81 @@ use super::range::RangeArgument;
148148/// if the vector's length is increased to 11, it will have to reallocate, which
149149/// can be slow. For this reason, it is recommended to use `Vec::with_capacity`
150150/// whenever possible to specify how big the vector is expected to get.
151+ ///
152+ /// # Guarantees
153+ ///
154+ /// Due to its incredibly fundamental nature, Vec makes a lot of guarantees
155+ /// about its design. This ensures that it's as low-overhead as possible in
156+ /// the general case, and can be correctly manipulated in primitive ways
157+ /// by unsafe code. Note that these guarantees refer to an unqualified `Vec<T>`.
158+ /// If additional type parameters are added (e.g. to support custom allocators),
159+ /// overriding their defaults may change the behavior.
160+ ///
161+ /// Most fundamentally, Vec is and always will be a (pointer, capacity, length)
162+ /// triplet. No more, no less. The order of these fields is completely
163+ /// unspecified, and you should use the appropriate methods to modify these.
164+ /// The pointer will never be null, so this type is null-pointer-optimized.
165+ ///
166+ /// However, the pointer may not actually point to allocated memory. In particular,
167+ /// if you construct a Vec with capacity 0 via `Vec::new()`, `vec![]`,
168+ /// `Vec::with_capacity(0)`, or by calling `shrink_to_fit()` on an empty Vec, it
169+ /// will not allocate memory. Similarly, if you store zero-sized types inside
170+ /// a Vec, it will not allocate space for them. *Note that in this case the
171+ /// Vec may not report a `capacity()` of 0*. Vec will allocate if and only
172+ /// if `mem::size_of::<T>() * capacity() > 0`. In general, Vec's allocation
173+ /// details are subtle enough that it is strongly recommended that you only
174+ /// free memory allocated by a Vec by creating a new Vec and dropping it.
175+ ///
176+ /// If a Vec *has* allocated memory, then the memory it points to is on the heap
177+ /// (as defined by the allocator Rust is configured to use by default), and its
178+ /// pointer points to `len()` initialized elements in order (what you would see
179+ /// if you coerced it to a slice), followed by `capacity() - len()` logically
180+ /// uninitialized elements.
181+ ///
182+ /// Vec will never perform a "small optimization" where elements are actually
183+ /// stored on the stack for two reasons:
184+ ///
185+ /// * It would make it more difficult for unsafe code to correctly manipulate
186+ /// a Vec. The contents of a Vec wouldn't have a stable address if it were
187+ /// only moved, and it would be more difficult to determine if a Vec had
188+ /// actually allocated memory.
189+ ///
190+ /// * It would penalize the general case, incurring an additional branch
191+ /// on every access.
192+ ///
193+ /// Vec will never automatically shrink itself, even if completely empty. This
194+ /// ensures no unnecessary allocations or deallocations occur. Emptying a Vec
195+ /// and then filling it back up to the same `len()` should incur no calls to
196+ /// the allocator. If you wish to free up unused memory, use `shrink_to_fit`.
197+ ///
198+ /// `push` and `insert` will never (re)allocate if the reported capacity is
199+ /// sufficient. `push` and `insert` *will* (re)allocate if `len() == capacity()`.
200+ /// That is, the reported capacity is completely accurate, and can be relied on.
201+ /// It can even be used to manually free the memory allocated by a Vec if
202+ /// desired. Bulk insertion methods *may* reallocate, even when not necessary.
203+ ///
204+ /// Vec does not guarantee any particular growth strategy when reallocating
205+ /// when full, nor when `reserve` is called. The current strategy is basic
206+ /// and it may prove desirable to use a non-constant growth factor. Whatever
207+ /// strategy is used will of course guarantee `O(1)` amortized `push`.
208+ ///
209+ /// `vec![x; n]`, `vec![a, b, c, d]`, and `Vec::with_capacity(n)`, will all
210+ /// produce a Vec with exactly the requested capacity. If `len() == capacity()`,
211+ /// (as is the case for the `vec!` macro), then a `Vec<T>` can be converted
212+ /// to and from a `Box<[T]>` without reallocating or moving the elements.
213+ ///
214+ /// Vec will not specifically overwrite any data that is removed from it,
215+ /// but also won't specifically preserve it. Its uninitialized memory is
216+ /// scratch space that it may use however it wants. It will generally just do
217+ /// whatever is most efficient or otherwise easy to implement. Do not rely on
218+ /// removed data to be erased for security purposes. Even if you drop a Vec, its
219+ /// buffer may simply be reused by another Vec. Even if you zero a Vec's memory
220+ /// first, that may not actually happen because the optimizer does not consider
221+ /// this a side-effect that must be preserved.
222+ ///
223+ /// Vec does not currently guarantee the order in which elements are dropped
224+ /// (the order has changed in the past, and may change again).
225+ ///
151226#[ unsafe_no_drop_flag]
152227#[ stable( feature = "rust1" , since = "1.0.0" ) ]
153228pub struct Vec < T > {
0 commit comments