Documentation for "substring" and Similar API

[RohitSaily]

The String API documentation for substring states

The substring of this string from start, inclusive, to end, exclusive.

It is reasonable to interpret this as start is a valid index because it is inclusive and no relation to end or length is specified at this point. Then the end of the documentation states

Both start and end must be non-negative and no greater than length;

Which implies start==length is valid. This can be confusing due to the earlier statement. Furthermore, it is not intuitive that start==end==length is a valid case but a similar/symmetrical case start==-1 and end==0 is not valid. Both are empty ranges adjacent to the range of valid indices. In my personal experience, I did not understand this nuance until I was testing code.

---

I think the documentation could benefit from clarifying this. Perhaps starting with the statement 0 ≤ start ≤ end ≤ length must hold. would clearly and quickly communicate the valid possible inputs. This change could also be applied to similar API e.g. List.sublist.

[lrhn]

Its tricky to be precise without being overly verbose.

The requirements are indeed 0 ≤ start ≤ end ≤ length.
That does allow start and end to be the same number, which is deliberate since it is allowed as a way to create an empty substring.

The "inclusive" and "exclusive" are about which indices are included in the result.

The precise way to express that would "The result is a code string containing the code units
of this string with position p such that start ≤ p < end.".
That won't fit in the first summary line, so the "from start, inclusive, to end, exclusive" is a shorter, and a little less precise, way to say the same thing.

(The start == -1 and end == 0 is not an empty range, it has length 1. The symmetric range corresponding to start == end == length is start == end == 0, both of which are allowed.)

[RohitSaily]

How about

The substring where 0 ≤ `start` ≤ `end` ≤ `length`. `start` is inclusive and `end` is exclusive.

Stating valid values first can help prevent confusion because the inclusive/exclusive part is read after the valid values are in mind. This is a reasonable length for a summarizing line, unless there is some character limit constraint it violates.

(The start == -1 and end == 0 is not an empty range, it has length 1. The symmetric range corresponding to start == end == length is start == end == 0, both of which are allowed.)

Yes, you are correct. I was still confused in relation to the inclusivity. I meant to say start==end==-1 which, as you explained, is not the symmetric case.