Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Vec visualization to understand capacity #76066

Closed
wants to merge 11 commits into from
Closed

Add Vec visualization to understand capacity #76066

Changes from 1 commit
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
9c1415e
Add Vec visualization to understand capacity
pickfire Aug 29, 2020
ea337c6
Center align ptr and len box vec doc
pickfire Aug 29, 2020
f2bd46b
Link uninitialized memory to MaybeUninit
pickfire Aug 30, 2020
53af7b8
Vec visualization separate description
pickfire Aug 30, 2020
a919516
Link Vec visualization to core::mem::MaybeUninit
pickfire Aug 31, 2020
55ad7f2
Vec visualization mention unstable ABI
pickfire Sep 1, 2020
44e9b7f
Use explicit details to relate to the diagram
pickfire Oct 15, 2020
6900744
Make vec note for visualization more explicit
pickfire Oct 15, 2020
79918c1
Use alphabetical example in vec visualization
pickfire Oct 27, 2020
62ba5b1
Fix vec doc merge conflict
pickfire Dec 1, 2020
702662e
Merge branch 'master' into patch-15
pickfire Dec 1, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions library/alloc/src/vec.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -194,6 +194,19 @@ use crate::raw_vec::RawVec;
/// 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.
///
/// In summary, a vector containing 1, 2 with capacity 4 can be visualized as:
pickfire marked this conversation as resolved.
Show resolved Hide resolved
/// ```text
/// Stack +--------+--------+--------+
/// | ptr |capacity| len |
pickfire marked this conversation as resolved.
Show resolved Hide resolved
/// | 0x0123 | 4 | 2 |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

into_raw_parts and from_raw_parts use (ptr, length, capacity), not (ptr, capacity, length). It might be good to use the same order here.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is intentionally different, see #76066 (comment).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jyn514 That comment suggests to use a different layout than the real layout. The 'real' layout is (RawVec, len), which is effectively a (ptr, cap, len). Changing it to (ptr, len, cap) as I suggest does make it different from the actual layout, just like the8472 asked for.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Weird, I didn't notice this, I thought I used len followed by capacity.

/// +--------+--------+--------+
/// |
/// v
/// Heap +--------+--------+--------+--------+
/// | 1 | 2 | | |
/// +--------+--------+--------+--------+
pickfire marked this conversation as resolved.
Show resolved Hide resolved
/// ```
///
/// # Guarantees
///
/// Due to its incredibly fundamental nature, `Vec` makes a lot of guarantees
Expand Down