Skip to content

Commit

Permalink
Add more details explaning the Vec visualization
Browse files Browse the repository at this point in the history
Suggested by oli-obk
  • Loading branch information
pickfire committed Jan 20, 2021
1 parent 9e42d14 commit 9f338e1
Showing 1 changed file with 22 additions and 20 deletions.
42 changes: 22 additions & 20 deletions library/alloc/src/vec/mod.rs
Expand Up @@ -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
Expand Down Expand Up @@ -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:
///
Expand Down

0 comments on commit 9f338e1

Please sign in to comment.