Fix inconsistent safety requirement in VecDeque::nonoverlapping_ranges

[yilin0518]

The safety documentation of nonoverlapping_ranges says that its head argument must be in bounds:

    /// Get source, destination and count (like the arguments to [`ptr::copy_nonoverlapping`])
    /// for copying `count` values from index `src` to index `dst`.
    /// One of the ranges can wrap around the physical buffer, for this reason 2 triples are returned.
    ///
    /// Use of the word "ranges" specifically refers to `src..src + count` and `dst..dst + count`.
    ///
    /// # Safety
    ///
    /// - Ranges must not overlap: `src.abs_diff(dst) >= count`.
    /// - Ranges must be in bounds of the logical buffer: `src + count <= self.capacity()` and `dst + count <= self.capacity()`.
    /// - `head` must be in bounds: `head < self.capacity()`.
    #[cfg(not(no_global_oom_handling))]
    unsafe fn nonoverlapping_ranges(
        &mut self,
        src: usize,
        dst: usize,
        count: usize,
        head: usize,
    ) -> [(*const T, *mut T, usize); 2] {

However, this is slightly stricter than the VecDeque internal invariant for head. The struct-level invariant allows head == 0 when the buffer capacity is zero:

pub struct VecDeque<
    T,
    #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator = Global,
> {
    // `self[0]`, if it exists, is `buf[head]`.
    // `head < buf.capacity()`, unless `buf.capacity() == 0` when `head == 0`.
    head: WrappedIndex,
    // the number of initialized elements, starting from the one at `head` and potentially wrapping around.
    // if `len == 0`, the exact value of `head` is unimportant.
    // if `T` is zero-Sized, then `self.len <= usize::MAX`, otherwise `self.len <= isize::MAX as usize`.
    len: usize,
    buf: RawVec<T, A>,
}

This zero-capacity case is reachable through the public API. I create the corresponding case in Rustplayground. This case can run without UB, also Miri runs successfully.

So it seems that the safety documentation of VecDeque::nonoverlapping_ranges is incorrect, or this API should add additional processing to approach this condition. This PR provides the minimal fix: updates the safety documentation for nonoverlapping_ranges to match the existing VecDeque invariant.

If needed, I can add a debug_assert! to check whether the input satisfies the requirement.

No behavior is changed.

[rustbot]

r? @jhpratt

rustbot has assigned @jhpratt.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

Why was this reviewer chosen?

The reviewer was selected based on:

• Owners of files modified in this PR: libs
• libs expanded to 12 candidates
• Random selection from Darksonn, JohnTitor, Mark-Simulacrum, clarfonthey, jhpratt

[jhpratt]

Given that this is an internal API, this shouldn't need team approval.

@bors r+ rollup

[rust-bors]

📌 Commit 58f80da has been approved by jhpratt

It is now in the queue for this repository.

🌲 The tree is currently closed for pull requests below priority 2. This pull request will be tested once the tree is reopened.