Vec::from_raw_parts docs incorrectly suggest the pointer is legal to be null

[mahkoh]

if ptr is null, then length and capacity should be 0

http://doc.rust-lang.org/nightly/collections/vec/struct.Vec.html#method.from_raw_parts

[thestinger]

The documentation is misleading. The pointer is not allowed to be null.

[mitsuhiko]

How do you make an empty slice if the pointer is not allowed to be null?

[thestinger]

@mitsuhiko: The underlying representation is an implementation detail and shouldn't be documented beyond the ability to convert the raw parts obtained from a vector back into a vector.

[thestinger]

The language and library documentation has a love affair with making far too many promises about the implementation. In the vector module, there are numerous errors when it comes to information about the vector's capacity too. It tends to guarantee that the capacity is exactly what was asked for rather than at least that much. It is allowed to set the capacity to a value provided by the allocator.

[mitsuhiko]

Does that mean you are required to special case the empty case and then use a different way to make an empty vector?

[thestinger]

No, it means you can't use this method outside of the standard library beyond converting from an existing vector.

[thestinger]

If what you're asking is how it does this internally, the answer is that empty vectors along with zero-size allocations in general are allowed to be entirely arbitrary pointers. They will never be dereferenced and the compiler / library code will never attempt to deallocate them.

[thestinger]

The documentation is not supposed to cover these implementation details. It would make sense to cover it in comments (which it is) or internal design documentation.

[mitsuhiko]

In that case I suppose the docs should say: can only be constructed from components of an already existing vector.