Explain how Vec::with_capacity is faithful #135933

hkBst · 2025-01-23T14:19:22Z

This is a revival of #99790 building on the prose of @workingjubilee and edits of @jmaargh. Closes #99385.

rustbot · 2025-01-23T14:19:31Z

rustbot has assigned @ibraheemdev.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

Kixunil

Awesome! Not only is this very clear and understandable, it's also a good design that can make use of advanced allocator capabilities.

Linking #101316 for convenience.

ibraheemdev · 2025-01-31T03:26:52Z

library/alloc/src/vec/mod.rs

+/// and no other size (such as, for example: a size rounded up to the nearest power of 2).
+/// The allocator will return an allocation that is at least as large as requested, but it may be larger.
+///
+/// It is guaranteed that the [Vec::capacity] method returns a value that is at least the requested capacity


Suggested change

/// It is guaranteed that the [Vec::capacity] method returns a value that is at least the requested capacity

/// It is guaranteed that the [`Vec::capacity`] method returns a value that is at least the requested capacity

I incorporated this.

ibraheemdev · 2025-01-31T03:27:04Z

library/alloc/src/vec/mod.rs

+/// It is guaranteed that the [Vec::capacity] method returns a value that is at least the requested capacity
+/// and not more than the allocated capacity.
+///
+/// The method [Vec::shrink_to_fit] can discard excess capacity an allocator has given to a `Vec`.


Suggested change

/// The method [Vec::shrink_to_fit] can discard excess capacity an allocator has given to a `Vec`.

/// The method [`Vec::shrink_to_fit`] can discard excess capacity an allocator has given to a `Vec`.

Also incorporated this.

ibraheemdev · 2025-01-31T03:29:23Z

r? @workingjubilee because there were some open questions on the original PR.

rustbot · 2025-01-31T03:29:25Z

Could not assign reviewer from: workingjubilee.
User(s) workingjubilee are either the PR author, already assigned, or on vacation. Please use r? to specify someone else to assign.

ibraheemdev · 2025-01-31T06:43:42Z

Seems they are on vacation. r? libs-api because from what I understand this adds additional guarantees to the public API.

dtolnay · 2025-01-31T08:03:49Z

@rust-lang/libs-api:
@rfcbot fcp merge

This PR adds the guarantee that vec! and Vec::with_capacity request an allocation of the exact size needed for that number of elements (as long as size_of::<T>() * n > 0 as carved out in a previous paragraph).

Whether the actual allocation can hold a larger number of elements is up to the allocator. So this still only guarantees that vec.capacity() >= n, not ==.

Before this PR, we guaranteed vec.capacity() >= n but did not guarantee that n would be the requested size of the allocation. Hypothetically the Vec implementation could have rounded up the capacity, and that will no longer be allowed. Only the allocator gets to round up.

rfcbot · 2025-01-31T08:03:51Z

Team member @dtolnay has proposed to merge this. The next step is review by the rest of the tagged team members:

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

rfcbot · 2025-02-11T15:34:59Z

🔔 This is now entering its final comment period, as per the review above. 🔔

library/alloc/src/vec/mod.rs

workingjubilee

This is what I was aiming at, yes. Thank you for incorporating this and @jmaargh's edits.

RalfJung · 2025-02-21T07:04:41Z

library/alloc/src/vec/mod.rs

-/// and from a [`Box<[T]>`][owned slice] without reallocating or moving the elements.
+/// It is guaranteed, in order to respect the intentions of the programmer, that
+/// all of `vec![e_1, e_2, ..., e_n]`, `vec![x; n]` and [`Vec::with_capacity(n)`] produce a `Vec`,
+/// that requests an allocation of the exact size needed for precisely `n` elements from the allocator,


Suggested change

/// that requests an allocation of the exact size needed for precisely `n` elements from the allocator,

/// that requests an allocation of the exact size needed for precisely `n` elements from the allocator

AFAIK there shouldn't be a comma here?

If we replace this comma and the rest of the sentence with just a dot, then the sentence already says everything it should. Then if we want to re-add this clarifying clause, it seems logical to replace the dot with a comma and then the clause. Thus I think the comma is correct here, but I could be wrong.

I'm not sure I can justify the comma that comes before the part you quoted though...

Ah sorry I meant to remove the one after Vec, indeed. That's the one that is definitely wrong.

Co-authored-by: Jubilee <[email protected]> and jmaargh

rfcbot · 2025-02-21T15:39:38Z

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

This will be merged soon.

workingjubilee · 2025-02-24T16:18:38Z

@bors r+

bors · 2025-02-24T16:18:43Z

📌 Commit da7210b has been approved by workingjubilee

It is now in the queue for this repository.

workingjubilee · 2025-02-24T16:44:21Z

@bors rollup

rustbot assigned ibraheemdev Jan 23, 2025

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-libs Relevant to the library team, which will review and decide on the PR/issue. labels Jan 23, 2025

Dylan-DPC mentioned this pull request Jan 24, 2025

Explain how Vec::with_capacity is faithful #99790

Closed

Kixunil approved these changes Jan 24, 2025

View reviewed changes

ibraheemdev reviewed Jan 31, 2025

View reviewed changes

rustbot added the T-libs-api Relevant to the library API team, which will review and decide on the PR/issue. label Jan 31, 2025

rustbot assigned dtolnay and unassigned ibraheemdev Jan 31, 2025

dtolnay removed the T-libs Relevant to the library team, which will review and decide on the PR/issue. label Jan 31, 2025

rfcbot added proposed-final-comment-period Proposed to merge/close by relevant subteam, see T-<team> label. Will enter FCP once signed off. disposition-merge This issue / PR is in PFCP or FCP with a disposition to merge it. labels Jan 31, 2025

hkBst force-pushed the patch-19 branch from 6d37179 to 97105ff Compare January 31, 2025 12:30

Sky9x approved these changes Feb 2, 2025

View reviewed changes

rfcbot added final-comment-period In the final comment period and will be merged soon unless new substantive objections are raised. and removed proposed-final-comment-period Proposed to merge/close by relevant subteam, see T-<team> label. Will enter FCP once signed off. labels Feb 11, 2025

workingjubilee reviewed Feb 14, 2025

View reviewed changes

library/alloc/src/vec/mod.rs Outdated Show resolved Hide resolved

workingjubilee approved these changes Feb 14, 2025

View reviewed changes

hkBst force-pushed the patch-19 branch from 8e74d64 to a10e3d9 Compare February 15, 2025 06:48

RalfJung reviewed Feb 21, 2025

View reviewed changes

Explain how Vec::with_capacity is faithful

da7210b

Co-authored-by: Jubilee <[email protected]> and jmaargh

hkBst force-pushed the patch-19 branch from a10e3d9 to da7210b Compare February 21, 2025 11:46

rustbot mentioned this pull request Feb 21, 2025

Tracking issue for release notes of #135933: Explain how Vec::with_capacity is faithful #137378

Closed

3 tasks

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Feb 24, 2025

workingjubilee mentioned this pull request Feb 24, 2025

update doc for Vec::into_boxed_slice #137546

Open

tgross35 mentioned this pull request Feb 24, 2025

Rollup of 8 pull requests #137571

Merged

bors merged commit dc2b86f into rust-lang:master Feb 25, 2025
6 checks passed

rustbot added this to the 1.87.0 milestone Feb 25, 2025

BoxyUwU mentioned this pull request Apr 21, 2025

Draft release notes for 1.87 #140133

Closed

apiraino removed the to-announce Announce this issue on triage meeting label Apr 30, 2025

	/// It is guaranteed that the [Vec::capacity] method returns a value that is at least the requested capacity
	/// It is guaranteed that the [`Vec::capacity`] method returns a value that is at least the requested capacity

	/// The method [Vec::shrink_to_fit] can discard excess capacity an allocator has given to a `Vec`.
	/// The method [`Vec::shrink_to_fit`] can discard excess capacity an allocator has given to a `Vec`.

	/// that requests an allocation of the exact size needed for precisely `n` elements from the allocator,
	/// that requests an allocation of the exact size needed for precisely `n` elements from the allocator

Explain how Vec::with_capacity is faithful #135933

Explain how Vec::with_capacity is faithful #135933

Uh oh!

Conversation

hkBst commented Jan 23, 2025

Uh oh!

rustbot commented Jan 23, 2025

Uh oh!

Kixunil left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ibraheemdev commented Jan 31, 2025

Uh oh!

rustbot commented Jan 31, 2025

Uh oh!

ibraheemdev commented Jan 31, 2025

Uh oh!

dtolnay commented Jan 31, 2025

Uh oh!

rfcbot commented Jan 31, 2025 • edited by Amanieu Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rfcbot commented Feb 11, 2025

Uh oh!

Uh oh!

workingjubilee left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rfcbot commented Feb 21, 2025

Uh oh!

workingjubilee commented Feb 24, 2025

Uh oh!

bors commented Feb 24, 2025

Uh oh!

workingjubilee commented Feb 24, 2025

Uh oh!

Uh oh!

Uh oh!

rfcbot commented Jan 31, 2025 •

edited by Amanieu

Loading