Add doc comments about safest way to initialize a vector of zeros

[mandeep]

This adds more information about the vec! macro as discussed in #54628. I think this is a good starting point, but I think additional detail is needed so that we can explain why vec! is safer than the alternatives.

[rust-highfive]

r? @shepmaster

(rust_highfive has picked a reviewer for you, use r? to override)

[shepmaster]

I don't know if this is something we wish to guarantee, especially the bits about "previously zeroed memory is requested from the operating system".

r? @alexcrichton

[mandeep]

Yeah it's not likely to be the case on all systems, but I would like to somehow convey how this macro operates under the hood.

[alexcrichton]

Thanks for the PR! I don't think we need to have the term "safest" in the description as this isn't any safer than other mechanisms, and I agree with @shepmaster that we shouldn't try to make any guarantees about where memory comes from.

I think it may be best if we instead say that this strategy is an optimized way to initialize with zeros but not go too much into the details about what the optimization is.

[mandeep]

Is there anything we can add that will let users know that they should use the macro instead of the other options when initializing with zeros?

[the8472]

How about this?

It can also initialize each element of a Vec with a given value. This may be more efficient than performing allocation and initialization in separate steps, especially when initializing with zero-values.

let vec = vec![0; 5];
assert_eq!(vec, [0, 0, 0, 0, 0]);

// equivalent, but potentially slower:
let mut vec1 = Vec::with_capacity(5);
vec1.resize(5, 0);

More weasely and also adds it to the code examples in case someone doesn't read the prose.

[alexcrichton]

@the8472 that sounds great to me! @mandeep I think it's a bit strong to say that users should use this macro one way or another. We'll basically always keep the optimization of calling calloc where possible, but it's not always the case that speed needs to be at an optimum.

[alexcrichton]

@bors: r+ rollup

[bors]

📌 Commit 1e584bf has been approved by alexcrichton