Explain how Vec::with_capacity is faithful

[hkBst]

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

r? @ibraheemdev

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

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.

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.

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.

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

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.

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

@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.

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

• @Amanieu
• @BurntSushi
• @dtolnay
• @joshtriplett
• @m-ou-se

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.

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

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

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.

Fixed.

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.

@bors r+

📌 Commit da7210b has been approved by workingjubilee

It is now in the queue for this repository.

@bors rollup