From 9f338e18afd865e776d8f8cd7c763572a9a03ddf Mon Sep 17 00:00:00 2001 From: Ivan Tham Date: Sat, 5 Dec 2020 10:21:54 +0800 Subject: [PATCH] Add more details explaning the Vec visualization Suggested by oli-obk --- library/alloc/src/vec/mod.rs | 42 +++++++++++++++++++----------------- 1 file changed, 22 insertions(+), 20 deletions(-) diff --git a/library/alloc/src/vec/mod.rs b/library/alloc/src/vec/mod.rs index 88cdf588e3566..e09c3e5d23b03 100644 --- a/library/alloc/src/vec/mod.rs +++ b/library/alloc/src/vec/mod.rs @@ -253,26 +253,6 @@ mod spec_extend; /// can be slow. For this reason, it is recommended to use [`Vec::with_capacity`] /// whenever possible to specify how big the vector is expected to get. /// -/// A vector containing the elements `'a'` and `'b'` with capacity 4 can be -/// visualized as: -/// -/// ```text -/// Stack ptr len capacity -/// /Heap +--------+--------+--------+ -/// | 0x0123 | 2 | 4 | -/// +--------+--------+--------+ -/// | -/// v -/// Heap +--------+--------+--------+--------+ -/// | 'a' | 'b' | uninit | uninit | -/// +--------+--------+--------+--------+ -/// ``` -/// -/// - **uninit** represents memory that is not initialized, see [`MaybeUninit`]. -/// - Note: the ABI is not stable and `Vec` makes no guarantees about its memory -/// layout (including the order of fields). See [the section about -/// guarantees](#guarantees). -/// /// # Guarantees /// /// Due to its incredibly fundamental nature, `Vec` makes a lot of guarantees @@ -305,6 +285,28 @@ mod spec_extend; /// you would see if you coerced it to a slice), followed by [`capacity`]` - /// `[`len`] logically uninitialized, contiguous elements. /// +/// A vector containing the elements `'a'` and `'b'` with capacity 4 can be +/// visualized as below. The top part is the `Vec` struct, it contains a +/// pointer to the head of the allocation in the heap, length and capacity. +/// The bottom part is the allocation on the heap, a contiguous memory block. +/// +/// ```text +/// ptr len capacity +/// +--------+--------+--------+ +/// | 0x0123 | 2 | 4 | +/// +--------+--------+--------+ +/// | +/// v +/// Heap +--------+--------+--------+--------+ +/// | 'a' | 'b' | uninit | uninit | +/// +--------+--------+--------+--------+ +/// ``` +/// +/// - **uninit** represents memory that is not initialized, see [`MaybeUninit`]. +/// - Note: the ABI is not stable and `Vec` makes no guarantees about its memory +/// layout (including the order of fields). See [the section about +/// guarantees](#guarantees). +/// /// `Vec` will never perform a "small optimization" where elements are actually /// stored on the stack for two reasons: ///