Clarification on ranges

[AartBluestoke]

can we please have a section in https://github.com/dotnet/csharplang/blob/master/proposals/csharp-8.0/ranges.md which points out the contrast between the two different meanings of the index from end operator, depending on if it is an isolated unary_expression, or part of a range_expression .

the System.Index section begins

We introduce a new Index expression that means "from the end".
var lastItem = array[^1]; // array[new Index(1, fromEnd: true)]

this ^1 compiles to array3[new Index(1, true).GetOffset(array3.Length)];

the '^1' here means "from the length", a 0 indexed statement. The examples in this section should have a case demonstrating that ^0 is an error here.

This especially confusing when the documentation says

We call the .. operator the range operator. The built-in range operator can roughly be understood to correspond to the invocation of a built-in operator of this form:

System.Range operator ..(Index start = 0, Index end = ^0);

except that ^0 here is translated to the second parameter of the slice, and is a 1 indexed statement

The details are there, but at separate parts of the document.

the Runtime Behavior summary says

• ^0 does not throw, but it translates to the length of the collection/enumerable it is supplied to.
• Range.All is semantically equivalent to 0..^0, and can be deconstructed to these indices.
  except that :

1. Range.All doesn't translate to array[0..Array.Length], it translates to something equivalent array[0...Array.Length-1]
2. array[^0] is guaranteed to throw.

var array = new int[] { 1, 2, 3, 4, 5 };
var toTheEnd = array[..^0]; // "0 from end", or "all of them" :  { 1, 2, 3, 4, 5 }
var wrongLast = array[^0]; // index out of range "i want array[array.Length]"
var wrongSlice= array[..5];   // translation implied by statement ^0 above, also index out of range "i want array[array.Length]"

var slice = array[4..^0];      // {5}
var slice_ug = array[4..5];      // {5}
var theValue = array[^1]; // 5

According to the spec,
what does [0..^0] mean?

The first argument of Slice will be obtained by converting the range typed expression in the following way:

When expr is of the form expr1..expr2 (where expr2 can be omitted) and expr1 has type int, then it will be emitted as expr1.
...
This value(0) will be re-used ... as start. 
The second argument of Slice will be obtained by...
When expr is of the form expr1..^expr2, then it will be emitted as (receiver.Length - expr2) - start.

so this means Array.Slice(0,(reciever.Length-0)-0); or "the entire array" as expected

what does [0..Array.Length] mean?

...
The second argument of Slice will be obtained by...
When expr is of the form expr1..expr2 and expr2 has type int, then it will be emitted as expr2 - start.

so this means Array.Slice(0,(reciever.Length-0)); or "the entire array" as expected...

---

tldr:
Basically the first element of a range is 0 indexed, the second is 1 indexed, and ^1 is viable in both. The documentation should clarify this with examples like
var theValue = array[^0]; // an error
var theValue = array[^1]; // the last element
var theValue = array[0..1]; // just the first element
var theValue = array[0..array.Length]; // all the elements
var theValue = array[0..^0]; // all the elements
var theValue = array[0..^1]; // all but the last element