From 9e42d14927924036884734bd094747dd76b8b5f3 Mon Sep 17 00:00:00 2001 From: Ivan Tham Date: Thu, 3 Dec 2020 10:56:13 +0800 Subject: [PATCH] Add Vec visualization to understand capacity Visualize vector while differentiating between stack and heap. Inspired by cheats.rs, as this is probably the first place beginner go, they could understand stack and heap, length and capacity with this. Not sure if adding this means we should add to other places too. Superseeds #76066 --- library/alloc/src/vec/mod.rs | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/library/alloc/src/vec/mod.rs b/library/alloc/src/vec/mod.rs index ccc4f03a1e505..88cdf588e3566 100644 --- a/library/alloc/src/vec/mod.rs +++ b/library/alloc/src/vec/mod.rs @@ -253,6 +253,26 @@ 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 @@ -345,6 +365,7 @@ mod spec_extend; /// [`push`]: Vec::push /// [`insert`]: Vec::insert /// [`reserve`]: Vec::reserve +/// [`MaybeUninit`]: core::mem::MaybeUninit /// [owned slice]: Box /// [slice]: ../../std/primitive.slice.html /// [`&`]: ../../std/primitive.reference.html