bjoernager/rust
bjoernager/rust
1
Fork 0
Code Activity

Add more details explaning the Vec visualization

Browse source 
Suggested by oli-obk
This commit is contained in:
Ivan Tham 2020-12-05 10:21:54 +08:00
parent 9e42d14927
commit 9f338e18af
1 changed files with 22 additions and 20 deletions
Download patch file Download diff file Expand all files Collapse all files

42
library/alloc/src/vec/mod.rs
View file

@ -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:
///