Potential documentation gap in impl Index<Range<usize>> for [T]

[pezcore]

Location

Index::index

Summary

In Rust, if you attempt to index a slice or array with a "backwards" Range<usize> , the program panics:

let arr = [0,1,2,3,4,5,6];
let slice = &arr[4..1]; // panic: slice index starts at 4 but ends at 1 

This behavior is unsurprising, but not obvious: a reasonable alternative behavior would be to just return the empty slice &[]. This is what python does.

The documentation for Index::index states that the indexing operation "May panic if the index is out of bounds", but doesn't define what it means to be "out of bounds". I'd argue that in this example, the Range 4..1 is actually not out-of-bounds for an array of size 7 because both 4 and 1 are less than 7 and therefore, by the letter of the documentation, the panic behavior here is wrong and returning the empty slice &[] is a more reasonable behavior to expect than panicking.

I feel like the documentation should make explicitly clear that this panics if either of the following are true:

1. range.end > slice.len()
2. range.end < range.start

Also the documentation should make clear that this does panic, not just that it might, because surely this panic is not UB.

[clubby789]

Implementors of the trait might or might not panic on third party types, so 'may' is technically correct. The documentation for the implementations themselves could say 'will'

[pezcore]

"may panic" is correct on the Index<Idx> level, but on the Index<Range<usize>> level of specificity , the documentation should say that it does panic and define the exact set of conditions that panic.

[JaniM]

@rustbot claim

This is a weird one. It is very difficult to find this specific implementation from the docs (having to jump through SliceIndex). We can add documentation for each SliceIndex impl, but I feel like thwre'd be value in rethinking the discoverability of this.