A Proposal to Define Some Container-Related Terms

[RexJaeschke]

To add your input to the discussion of a topic in this issue, do NOT create a new comment; instead, locate the existing topic thread and add your contribution to its end using the “edit” option.

Introduction

The word “collection” is used in the draft-v8 C# spec 90-odd times; however, the spec does not contain a definition for this word as a term.

Although we’ve gotten along without such a definition, collection-related features will be added in V8 and future versions, and one or more definitions might be desirable. Specifically:

• V8: The Indexer-and-Range feature spec defines the term “indexable sequence” (my own invention, which I propose be renamed as “indexable collection”).
• V12: Adds support for collection expressions, and inline arrays (which are collections).
• V13: Replaces “parameter array” with “parameter collection.”

And Bill is aware of other, potential future uses.

I propose that we define the term “collection” and some flavors thereof, and that we use them consistently starting with draft-v8.

Topics

• Where to define any collection-related terms?:
• Proposed term “collection”:
• Proposed term “collection type”:
• Proposed term “initializable collection type”:
• Proposed term “indexable collection”:
• Proposed term “countable type”:
• Future term “collection expression”:
• Future term “parameter collection”:
• Alternatives to “collection” as a generic English word:

[RexJaeschke]

Where to define any collection-related terms?

Unless stated otherwise below, I propose we define the new terms in a new, top-level section in the Types chapter, called “Collection types”?

[RexJaeschke]

Proposed term “collection”

A collection is an ordered set of zero or more collection elements that can be used in a polymorphic way. Often, the elements are of the same data type such as int or string. Sometimes the items derive from a common type; even deriving from the most general type, object.

[RexJaeschke]

Proposed term “collection type”

An instance of a collection type can be used to represent a collection of elements of that type. Such a type shall be enumerable (§x.x.x) and it shall be at least one of the following:

• An array type
• System.String
• System.Span<T>
• System.ReadOnlySpan<T>
• A type that implements any of the following interfaces:
  • System.Collections.IEnumerable
  • System.Collections.Generic.ICollection<T>
  • System.Collections.Generic.IEnumerable<T>
  • System.Collections.Generic.IList<T>
  • System.Collections.Generic.IReadOnlyCollection<T>
  • System.Collections.Generic.IReadOnlyList<T>
• V12: A type with a collection-creation method (§x.x.x)

A collection need not have a type that can be declared explicitly (not even using var), so long as an expression designating an instance of that type is used in the context of a target type, and an implicit conversion to that target type is defined. V12: True at least for collection expressions.

[RexJaeschke]

Proposed term “initializable collection type”

[New/changed text is inside >>...<<.]

Revise §12.8.17.4, “Collection initializers”
…
The collection object to which a collection initializer is applied shall >>have an initializable collection type; that is, a collection type that implements System.Collections.IEnumerable or a compile-time error occurs. Furthermore,<< for each specified element in order from left to right, normal member lookup is applied to find a member named Add. If the result of the member lookup is not a method group, a compile-time error occurs. Otherwise, overload resolution is applied with the expression list of the element initializer as the argument list, and the collection initializer invokes the resulting method. Thus, the collection object shall contain an applicable instance or extension method with the name Add for each element initializer.

[RexJaeschke]

Proposed term “indexable collection”

An indexable collection is a collection in which any given element can be accessed via an index, and a contiguous subset of elements—referred to as a slice—can be denoted via a range.

Note: An index is represented by a value of type int, uint, long, ulong, or System.Index, or a type that can be implicitly converted to int, uint, long, or ulong. A range is represented by a value of type System.Range. end note

To support indexing, a collection shall have an accessible indexer with the appropriate signature. If the indexer’s first argument has type System.Index or System.Range, the collection shall have a countable type.

[RexJaeschke]

Proposed term “countable type”

A type is countable if it has an instance property named Length or Count with an accessible get accessor and a return type of int.

Q. All the standard container types used in/referenced by the C# spec are countable, but can we say/require that all container types must be countable? Does this definition belong here (it doesn’t mention containers), or should it go in 8.1, “Types|General”?

[RexJaeschke]

Future term “collection expression”

This will be handled by the corresponding V12 feature draft PR.

[RexJaeschke]

Future term “parameter collection”

This will be handled by the corresponding V13 feature draft PR.

[RexJaeschke]

Alternatives to “collection” as a generic English word

Assuming we want/need one or more terms involving the word “collection” to mean specific things, perhaps with respect to C#’s type system, how then do we refer to the generic English word “collection?”

Consider the following spec text, from §6.4.1, “Tokens|General”:

Note: This is an ANTLR parser rule, it does not define a lexical token but rather the collection of token kinds. end note

Q. How about for generic uses of “collection” we use “set” instead (or possibly “group” if “set” implies a set-like collection [which is not a type in the CLI])?

On the 2025-01-22 TG2 call, there was some opposition to "set;" "group" was less likely to be misleading/confusing.