Buffer provides an entirely safe interface for managing memory within other
collections. It provides allocate, reallocate, and deallocate functionality
and obeys RAII principles (deallocate on drop).

This can be used to simplify the implementation of any data structure which
does allocation not through another structure like Vec.

From the docs:

A safe wrapper around a heap allocated buffer of Ts, tracking capacity only.

Buffer makes no promises about the actual contents of this memory, that's up
to the user of the structure and can be manipulated using the standard pointer
utilities, accessible through the impl of `Deref<Target=*mut T>` for `Buffer<T>`.

As a result of this hands-off approach, `Buffer`s destructor does not attempt
to drop any of the contained elements; the destructor simply frees the contained
memory.

You can think of `Buffer<T>` as an approximation for `Box<[T]>` where the elements
are not guaranteed to be valid/initialized. It is meant to be used as a building
block for other collections, so they do not have to concern themselves with the
minutiae of allocating, reallocating, and deallocating memory.

These checks aren't needed since the old size was checked when
it was originally allocated.

Also provide forward-compatibility for the move to `NonZero<Unique<T>>`
in the future and tweak some docs.

…location.

By only swapping out the buffer and not also changing the capacity
to 0 during reallocation, a capacity overflow could cause the drop
impl of Buffer to run when the buffer was empty() and the capacity
was non-zero, causing an incorrect call to deallocate.

We now also swap the capacity to 0, so that when reallocate is called
(the site of a possible panic) the buffer is in a consistent empty
state.

Also, in order to avoid leaking memory on oom (ya kind of useless,
but still) reallocate now deallocates the old ptr if reallocation
fails.