Clarify the std::vec::Vec::with_capacity docs

[ftxqxd]

There is some confusion (cc #15851) about what Vec::with_capacity actually does—someone who doesn’t understand the difference between capacity and length (an understandable conflation) could easily presume that it creates a new vector with the specified length (filled up with some kind of default or undefined value).

[lilyball]

The referenced issue does not appear to be conflating length and capacity. If it were, it wouldn't use the insert method. It appears to me that instead, the author expected to be able to construct a sparse vector. Although I don't know what they believed would happen if the same index were inserted twice.

In other words, I think this is a unnecessary attempt at clarifying the docs. It doesn't actually address the real confusion. Also, a single instance of confusion does not necessarily mean docs need changing anyway; even the clearest of documentation can still result in the occasional confused reader.

[daschl]

@kballard I was under the impression that with_capacity indeed returns me a a vector of the given size. I think clarifying capacity and size at a place like this makes sense and helps people that are new to the language.

[ftxqxd]

@kballard In a related discussion on IRC just after the referenced issue was filed, another person agreed that with_capacity is confusing, and that a reasonable solution would be to update the docs. This is what prompted me to make this PR.

[pczarn]

The name is self-explanatory. I think this could be clarified in a tutorial. You could mention that from_elem allows the user to specify the length.

[ftxqxd]

@pczarn The name is self-explanatory (in a sense), but that’s part of the problem—it might explain itself incorrectly. Anyone who doesn’t yet know of the difference between capacity and length could easily presume that with_capacity means ‘create a vector with the given length’.

The sort of scenario I’m trying to remedy is when somebody is looking for a way to create a vector with a given length, and looks for a name along the lines of with_length or something. The closest name to that is with_capacity, so it’d be reasonable for someone to try that. It doesn’t help that there’s no function with length in the name either.

I’m not trying to say that the above situation happens for every person looking for a function. If someone was looking for a function to create a vector from a given element, for example, they’d be quite pleased to find the right function for the job, from_elem. But for those people who expect to be able to find a function to generate a vector with a given length, with some kind of default value, it does help to steer them away from the wrong function and give them a point in the right direction.

[pnkfelix]

The notion of a "capacity" is referenced not just from the with_capacity construction method, but also from several other methods such as reserve (and also, the capacity observer method itself).

While it may be a good idea to include a reminder to the reader of the doc for fn with_capacity that capacity is not length, that one method is not the right place for lengthy discussion of what capacity denotes. Instead, if we are going to have such discussion in the doc for Vec, I would put it in the overview, above pub struct Vec<T> { ... } (and then link to that discussion from with_capacity and whatever other methods might benefit from the reminder of the distinction).

[ftxqxd]

@pnkfelix Good point. I’ve moved the capacity definition to the std::vec::Vec docs and expanded on it there. (Please correct me if I’ve made any mistakes.)