Add support for Index & Range

[Nigel-Ecma]

Alternative to #605

• Add support for Index & Ranges
• Details of types and "implicit support" in new chapter, temporarily at end to reduce lots of changes due to renumbering
• Attempts to avoid all implementation specific details from source material
• Covers dynamic binding, associativity, etc.
• Updates grammar test reference files (adding a new layer to the expression stack changes the tree but not the parse). These files can be ignored for review (they are machine generated).
• Adds a new grammar test with Index & Range samples

[RexJaeschke]

Editorial Nits

I can take care of the following once we merge this PR:

1. Change all code block starts from CSharp to csharp.
2. Change all "indicies" to "indices".
3. Change all "[C|c]hapter" to "[C|c]lause" Done by PR Replace chapter/section with clause/subclause, and clause with subclause, as appropriate #1373.
4. Make consistent with the existing spec the use of "that" vs. "which" and associated punctuation.
5. Add test harnesses to all examples.
6. Change all "must" in normative text to "shall".
7. Make sure that all the (currently) hard-coded references in the new clause 24, "Extended Indexing and Slicing," are made relative.

[RexJaeschke]

In email Nigel sent to active TG2 members on 2025-07-12, Subject: [TG2] Re: PR#1369 Add support for Index & Range, he wrote

The types added in §C.3 have documentation comments. Good, bad or ugly?

I've generalized that question by linking (the currently Parked) Issue 1135 to here, and asked for priority on that Issue next call.

[Nigel-Ecma]

Thanks for quick the review, I'll work my way down.

Editorial Nits

I can take care of the following once we merge this PR:

1. Change all code block starts from CSharp to csharp.

Will be in next commit.

2. Change all "indicies" to "indices".

This one beat my spell-checker, will be in the commit.

3. Change all "[C|c]hapter" to "[C|c]lause"

Not sure about this one.

While “chapter” does not occur in the text often (I think it is used a few times in 3 out of 7 versions) when it does it is referring to a whole §N (no .M), i.e. a whole chapter ;-) Further it is used in the page headings in most versions including the last one, v7. I like that it unambiguously refers to the whole chapter. We typically use “subclause” (which GitHub has now replaced twice with “subclass” and I've fixed it, I may not spot this every time!) for a §N(.M)+, but not always, sometimes I think to refer to a chapter, and sometimes to refer to a language construct – some examples:

• subclause, §15.7.3 “This clause applies to both properties…”
• chapter, §12.1 “This clause defines the syntax…”
• language construct, §21.4 “Once a matching catch clause is found…”
• most things, §6.2.4 “The syntactic grammar of C# is presented in the clauses, subclauses, and annexes that follow this subclause.”
• does clause/subclause include nested subclauses, sometimes we elaborate:
  • §23.1 “The remainder of this clause, including all of its subclauses, is conditionally normative.”
  • §12.8.9.1 “The remainder of this subclause and the following sibling subclauses are conditionally normative.”

I can see an argument for “chapter”, a review of how (sub)clause is used (yikes!), and acknowledge the usages I added are currently the only ones in v8.

4. Make consistent with the existing spec the use of "that" vs. "which" and associated punctuation.
5. Add test harnesses to all examples.

These two are definitely more @RexJaeschke’s area than mine, I happily leave them to him, thanks :-)

[RexJaeschke]

Re chapter/clause usage. Until we adopted the wrapper spec for ISO to avoid complying completely with their style, we followed ISO rules in this regard. And we might as well keep doing that to be consistent.

• An ISO spec had clauses rather than chapters.
• An ISO spec had subclauses rather than sections.
• An ISO spec does not have subsubclauses; subclause is used for all subordinate levels.

[Nigel-Ecma]

Re chapter/clause usage. Until we adopted the wrapper spec for ISO to avoid complying completely with their style, we followed ISO rules in this regard. And we might as well keep doing that to be consistent.

• An ISO spec had clauses rather than chapters.
• An ISO spec had subclauses rather than sections.
• An ISO spec does not have subsubclauses; subclause is used for all subordinate levels.

Isn't it also a requirement that all text is in subclauses (the reason for all the §N.1 General subclauses)?

So a clause has no text in it and something like “see clause §N“ can be taken to mean the whole clause and all the subclauses, i.e. what “chapter” has been used for occasionally over the versions and now in this PR.

Does this mean something like “see clause §N.M” should use subclause, or does the “.M” allow clause to be used?

Anyway, if this is definitive we need an issue to remove “Chapter” from the page headers in the final Standard (where it is in most ECMA releases).

I suspect that clause might be misused to mean subclause, and that it is not maybe clear that clause means the whole chapter, so so cleanup might be in order. There are 107 uses (in draft-v8 at the point this PR branched), I think most refer to language clauses so are fine so the job isn’t too daunting…

[RexJaeschke]

@Nigel-Ecma:

Isn't it also a requirement that all text is in subclauses (the reason for all the §N.1 General subclauses)?

Yes, Any clause or subclause containing a subclause cannot have its own text. Specifically, "hanging paragraphs are not allowed."

So a clause has no text in it and something like “see clause §N“ can be taken to mean the whole clause and all the subclauses, i.e. what “chapter” has been used for occasionally over the versions and now in this PR.

Exactly! This is the reason ISO has this requirement. A reference of §N always means all of N and its subordinates, and a reference of §N.M always means all of N.M and its subordinates.

Does this mean something like “see clause §N.M” should use subclause, or does the “.M” allow clause to be used?

N.M is a subclause, not a clause. ISO only uses the word "Clause" in a reference when the whole clause is intended. They do not use "subclause" for N.M, but rather, say nothing, so "see §N.M" is used instead. That said, ISO does not allow the use § in references, but I've always has it in documentation I've written, and I introduced it in V1.

Anyway, if this is definitive we need an issue to remove “Chapter” from the page headers in the final Standard (where it is in most ECMA releases).

Good observation. When we are ready to push out a new edition, Jon gives me the final generated Word version and I do light formatting on it before submitting it to Ecma. I just added to my list of "things to do in that process" to change the clause headers from "Chapter" to "Clause." Or we could simply omit that word altogether. In any event, we don't say "Annex" for each Annex header.

I suspect that clause might be misused to mean subclause, and that it is not maybe clear that clause means the whole chapter, so so cleanup might be in order. There are 107 uses (in draft-v8 at the point this PR branched), I think most refer to language clauses so are fine so the job isn’t too daunting…

Once we've discussed this I can clean this up.

[Nigel-Ecma]

@RexJaeschke wrote:

[snip] That said, ISO does not allow the use § in references, but I've always has it in documentation I've written, and I introduced it in V1.

Well of course they don’t, it is the section sign and they are clearly anti-section ;-), we like §, M§GA (ducking) ;-) Are there enough ;-)’s?

With the plan to remove all the occurrences of chapter and aim for consistency on the use of (sub)clause, the need for things like “this subclause and its subclauses”, et al., the four that are down to me will be gone in the next commit.

[jskeet]

Lots of tiny nits/typos, but I'm generally liking the approach here a lot.

[Nigel-Ecma]

If a comment thread was left open and not marked as resolved before the second commit it is still valid – ignore GitHib’s “Outdated” tag.

The failure of the renumbering check is fixed, any reference to §24.1.1 is now correctly §24.1 in the master and there is no need to report the issue.

[BillWagner]

Good work overall. A few comments and suggestions.

[BillWagner]

While I'd prefer a single word, I'd prefer something like "reverse index" or something.

[Nigel-Ecma]

It is called both the hat operator and the index from end operator in the various source materials, with the LDM at least recording a preference for the former at some point. I thought the latter was too much of a mouthful. Let’s see what the consensus is, remembering to consider list of definitions in §24.1 (from-start, from-end & past-end index) – hat (and other names/terms) are not fixed.

[Nigel-Ecma]

I will leave this one unresolved as I don’t recall we discussed it. The question is should the term be:

• hat (from source material and plenty of hits using DDG so it might qualify as lingua franca if we care ;-))
• from-end index (mainly for the index rather than the operator – from source material and also hits using DDG);
• reverse index (@BillWagner above); or
• something else?

[BillWagner]

After arrays.md might make the most sense. Sadly, it makes me wonder if interfaces should precede arrays, instead of the other way around.

[jskeet]

Some comments (don't merge just yet), but I'd really like to get the first pass at this merged either during or shortly after the meeting, and additional issues filed if necessary.

[jskeet]

Should we note that two Index values can resolve to the same concrete int index value when applied to the same countable collection, but still be unequal due to one being from-start and the other being from-end? Maybe it's obvious enough. (Or maybe we just state that equality is based on both the Value and IsFromEnd properties being equal.)

[Nigel-Ecma]

@jskeet – Hmm, its comparing abstract indices so it should be obvious… but if you’d like to craft a Note I see no harm. Or I could spell it out as you suggest. Another one for the meeting.

[KalleOlaviNiemitalo]

Toying with lifted operators:

using System;
class C
{
    // means ^default(int), not ^default(int?)
    static Index? I => ^default;

    // means I..default(Index), not I..default(Index?)
    static Range? R => I..default;

    // error CS8310: Operator '*' cannot be applied to operand 'default'
    static int? K => ((int?)4) * default;
}

Does something in the specification explain why default is allowed as an operand in lifted .. but not in lifted *? Or is this a compiler bug?

[Nigel-Ecma]

@KalleOlaviNiemitalo – Can you add an issue for this to be looked into? Or would you prefer we do it?

[gafter]

I believe the first two are target-typed, and the third is not.

[Nigel-Ecma]

Given @gafter’s comment this might come down to ^ & .. not being overloadable, while * is which requires both operands have types to resolve overloading. If that is correct I wouldn’t say it exactly jumps off the page…

[gafter]

I believe the first two are target-typed, and the third is not.

[jskeet]

We will try to resolve remaining issues offline.

[Nigel-Ecma]

Post-meeting changes made.
Most conversations marked as resolved, a few left open – authors please check and (un)resolve if neccesary.
Removing "Draft" status and re-requesting reviews.

[MadsTorgersen]

This is a very impressive PR! I read through everything in the standard folder, and as far as I can see, the whole thing checks out.