Improve doc of some methods that take ranges

[tkr-sh]

Some methods that were taking some range in parameter were a bit inconsistent / unclear in the panic documentation.

Here is the recap:

• Replaced "start/end point" by "start/end bound" to be coherent with RangeBounds naming (it's also easier to understand I think)
• Previously, it was written "[...] or if the end point is greater than the length of [...]", but this is not entirely true! Actually, you can have a start bound that is greater than the length, with an end bound that is unbounded and it will also panic. Therefore I think that "[...] one of the range bound is bounded and greater than the length of [...]" is better!
• String methods weren't mentionning that the method panics if start_bound > end_bound but it actually does! It uses slice::range which panics when start > end. (https://doc.rust-lang.org/stable/src/alloc/string.rs.html#1932-1934, https://doc.rust-lang.org/stable/src/core/slice/index.rs.html#835-837).
  You can also test it with:

struct MyRange;
impl std::ops::RangeBounds<usize> for MyRange {
    fn start_bound(&self) -> std::ops::Bound<&usize> {
        std::ops::Bound::Included(&3usize)
    }
    fn end_bound(&self) -> std::ops::Bound<&usize> {
        std::ops::Bound::Included(&1usize)
    }
}

fn main() {
    let mut s = String::from("I love Rust!");
    s.drain(MyRange); // panics!
}

[rustbot]

r? @ibraheemdev

rustbot has assigned @ibraheemdev.
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

[tkr-sh]

@rustbot label +A-docs

[tkr-sh]

r? @hkBst

[rustbot]

Failed to set assignee to hkBst: invalid assignee

Note: Only org members with at least the repository "read" role, users with write permissions, or people who have commented on the PR may be assigned.

[hkBst]

I'm happy with this.

[tgross35]

", or, a range bound is bounded and greater than ..." doesn't read quite right to me. Suggestion: ", or if the range has an end bound that is greater than the length of the dequeu".

[tkr-sh]

@tgross35 the problem with that is that it's not as precise as the previous one for 2 reasons:

• If the end bound is unbounded, do we consider that greater than the length ? Unbounded kind of means "infinite" so you could understand from your suggestion that if it's unbounded it will panic which is false
• The method can also panic if it's the start bound that is greater than the length of the deque

[tgross35]

• If the end bound is unbounded, do we consider that greater than the length

Users are more likely to think of things with regard to the range types, which may have "no end bound", not an "unbounded end bound" which this current PR's wording matches. I assume this comes from RangeBounds::end_bound always returning a Bound { Included, Excluded, Unbounded }; this type is better thought of as a flattened form of Option<enum { Included, Excluded }>, however, it is possible for an impl RangeBounds type to have "no end bound" (the docs for Unbounded say "Indicates that there is no bound in this direction.", after all).

The method can also panic if it's the start bound that is greater than the length of the deque

", or if the range has an end a start or end bound that is greater than the length of the dequeu" then? I'm open to other suggestions, but the "range bound is bounded" bit should change. (Also s/, or,/, or if)

[tkr-sh]

I can kind of agree with the first point, tho I'm not sure how you can put it into words so it's easier to understand.

And for the second point, well then:

, or if the range has a start or end bound that is greater than

v

, or if the range has a bound that is greater than

v

, or if a range bound is greater than

which is almost the same thing as the current documentation without the "is bounded" part (tho I agree on the sed part)