search

rust-lang / rust

Empowering everyone to build reliable and efficient software.
https://www.rust-lang.org
Other
99.05k stars 12.8k forks source link

The documentation of `Vec` contradicts itself regarding `with_capacity` #101316

Open Kixunil opened 2 years ago

Kixunil commented 2 years ago

Location

https://doc.rust-lang.org/std/vec/struct.Vec.html

Summary

In section Guarantees the documentation says:

vec![x; n], vec![a, b, c, d], and Vec::with_capacity(n), will all produce a Vec with exactly the requested capacity.

However in Vec::with_capacity(n) it says:

This method is allowed to allocate for more elements than capacity.

And

If it is imporant to know the exact allocated capacity of a Vec, always use the capacity method after construction.

These clearly contradict each-other. I guess it's better for performance to not guarantee capacity but maybe it'd break someones code to change it since it was already "documented". :(

ehuss commented 2 years ago

I believe this is being worked on in #99790. Can you take a look at that PR and comment over there if it still seems unclear?

Kixunil commented 2 years ago

Heh, was trying to find an issue but didn't think of looking at PRs. Will keep open until that merges.