VecDeque::with_capacity contradicts std::collections module documentation

[gluyas]

From std::collections module-level doc (emphasis added):

Any with_capacity constructor will instruct the collection to allocate enough space for the specified number of elements. Ideally this will be for exactly that many elements, but some implementation details may prevent this. Vec and VecDeque can be relied on to allocate exactly the requested amount, though.

However, the implementation actually requires that the capacity is a power of 2, taking advantage of bitmask modulo tricks. It also needs to keep a single empty slot in the buffer.

playground example

There are some use cases that would want this feature: rotate would be an O(1) operation when len == cap, which could be useful in sliding-window type applications. But it doesn't seem like something general deque usage would really care about. So probably shouldn't reimplement the whole data structure and just change the doc to not mention VecDeque here.