[Proposal]: Collection Expressions Next (C#13 and beyond)

[CyrusNajmabadi]

Collection Expressions Next

• [x] Proposed
• [ ] Prototype: Not Started
• [ ] Implementation: Not Started
• [ ] Specification: Not Started

Summary

This issue is intended to be the umbrella tracking item for all collection expression designs and work following the core design (https://github.com/dotnet/csharplang/issues/5354) that shipped in C#12.

As this is likely to be a large item with many constituent parts, it will link out to respective discussions and designs as they occur.

Roughly, here are the items we would like to consider, as well as early notes on the topic: https://github.com/dotnet/csharplang/blob/main/meetings/working-groups/collection-literals/CL-2024-01-23.md

1. Dictionary expressions. https://github.com/dotnet/csharplang/issues/7822
2. Natural type
3. Immediately enumerated collections. e.g. ["a", .. b ? ["c"] : []] and foreach (bool? b in [true, false, null]). https://github.com/dotnet/csharplang/pull/7864
4. Extension methods on collections
5. Missing collection-creatable types (e.g. Memory<T>, ArraySegment<T> etc.)
6. Supporting non-generic core collections (IEnumerable, etc.)
7. Relaxing restrictions. https://github.com/dotnet/csharplang/issues/7744

Design meetings

https://github.com/dotnet/csharplang/blob/main/meetings/2024/LDM-2024-01-08.md - Iteration types of collections https://github.com/dotnet/csharplang/blob/main/meetings/working-groups/collection-literals/CL-2024-01-23.md - WG meetup https://github.com/dotnet/csharplang/blob/main/meetings/2024/LDM-2024-01-10.md - Conversions vs construction https://github.com/dotnet/csharplang/blob/main/meetings/2024/LDM-2024-02-05.md#collection-expressions-inline-collections https://github.com/dotnet/csharplang/blob/main/meetings/2024/LDM-2024-09-06.md#collection-expressions-next-c13-and-beyond

[KennethHoff]

I'd like to see some way of calling the constructor of a type and/or setting some property during initialization. The first thing that came to mind is the comparer of a dictionary, but I'm sure there are other use-cases.

Either way, collection expressions are amazing, and support for natural types and inline expressions would make them that little bit better!

[CyrusNajmabadi]

@KennethHoff that's in the list, as part of hte dictionary-expression exploration work. Thanks :)

[BlinD-HuNTeR]

I'm not sure if the following proposal is too crazy, so I will describe it here quickly, as it's related to this topic:

Imagine that I have a int[] ints = [1, 2, 3], and I would like to have a string[] with the representations of those ints. One way to do that would be string[] strings = [ints[0].ToString(), ints[1].ToString(), ints[2].ToString()], but that only works because I know the length.

Ideally I would like to spread the array of ints into the array of strings while also calling ToString on each element.

If int had an user-defined implicit conversion operator to string, then I could write string[] strings = [.. ints], and it would be valid C# code, invoking the op_Implicit method on each int.

But since there is no such conversion, I would like to write something like string[] strings = [ (..ints).ToString()], and it would do exactly that. Hence, the proposal:

Spread operator as a first-class citizen.

So basically the spread operator .. becomes a regular unary-operator of the C# language, which at first may only be used inside collection expressions, but possibly could have its use expanded to everywhere.

The spread unary operator may be applied to any other expression, resulting in a spread_expression. When that happens, an implicit foreach loop is inserted for expression following the usual rules. It is, therefore, a compile-error if the operator is applied to something that isn't enumerable.

The spread_expression then behaves, for the purposes of member-lookup and overload-resolution, as an expression whose type is the element-type of the original enumerable. Because of that, one may invoke any members the element type might have, as well use the spread_expression on a method that takes element-type as argument. These invocations will then be inserted inside the invisible foreach loop, and spread_expression will be substituted for the loop variable.

The result of a member invocation performed on, or taking the spread_expression as an argument, is also itself a spread_expression, whose element-type is the return type of the invoked member, if not void. Method invocations can be chained on a spread_expression , and they will all be moved to the inside of the foreach loop.

Finally, one will want to capture the result of all these method invocations on each element of the original collection. Therefore, any spread_expression can be used regularly as a spread_element in a collection expression, with the existing rules.

Problems:

• There is a known ambiguity between spread operator and range operator. Originally this was addressed by forcing range operator to be inside parentheses, but with this proposal, it will also be necessary to put the spread inside parentheses when invoking members of the element-type. This is not an impeditive per se, because range operator may only be applied to int or System.Index, which are not (usually) enumerable, but the complexity of parsing would increase.

[HaloFour]

@BlinD-HuNTeR

C# already has a query comprehension syntax, LINQ.

[BlinD-HuNTeR]

C# already has a query comprehension syntax, LINQ.

True, but, that's not really an argument. If you would argue against all proposals saying "it can already be done in some way", then none would ever be accepted. Lists could already be created with LINQ or with initializers, yet collection expressions were introduced. And they have the added benefits of duck typing/nice syntax/good performance.

LINQ, on the other hand, is interface-based and makes use of delegates and anonymous objects. If one could perform some simple transformations through the use of spread operator, everything would be inserted directly in the caller method, with no delegates or closures. There isn't any optimization better than that, LINQ would almost be obsolete.

[HaloFour]

@BlinD-HuNTeR

See: https://github.com/dotnet/csharplang/discussions/7634

[CyrusNajmabadi]

@BlinD-HuNTeR

Imagine that I have a int[] ints = [1, 2, 3], and I would like to have a string[] with the representations of those ints.

That's where supporting extension methods would help. As you could write:

[1, 2, 3].Select(i => i.ToString()).ToArray()

[KennethHoff]

[1, 2, 3].Select(i => i.ToString()).ToArray()

I assume you could also do this?

[ ..[1, 2, 3].Select(i => i.ToString()) ]

[CyrusNajmabadi]

@KennethHoff yes.

[jnm2]

@KennethHoff Yes, or [.. from i in [1, 2, 3] select i.ToString()]

[En3Tho]

I suggest widening support for collection builders to accept other buildable collections.

For example I can choose to wrap a HashSet or a List or an Array or whatever. It feels so weird to accept a Span for such types.

[CyrusNajmabadi]

@En3Tho Can you give an example?

[En3Tho]

@CyrusNajmabadi

public class ArrayWrapperBuilder
{
    // This works
    public static ArrayWrapper<T> Create<T>(ReadOnlySpan<T> values)
    {
        return new(values.ToArray());
    }

    // I want this to work instead. Array is already a creatable collection, so just let compiler create it and use directly here
    // Imagine if it was a List<T> or HashSet<T> wrapper. Even more allocations while compiler is perfectly able to create this kind of collection directly.
    public static ArrayWrapper<T> Create<T>(T[] values)
    {
        return new(values);
    }
}

[CollectionBuilder(typeof(ArrayWrapperBuilder), nameof(ArrayWrapperBuilder.Create))]
public readonly struct ArrayWrapper<T>(T[] array) : IEnumerable<T>
{
    public T[] Array => array;
    public IEnumerator<T> GetEnumerator()
    {
        throw new NotImplementedException();
    }

    IEnumerator IEnumerable.GetEnumerator()
    {
        return GetEnumerator();
    }
}

public static class ArrayWrapperCreator
{
    public static ArrayWrapper<T> GetWrapper<T>() => [default, default, default];
}

[koszeggy]

I'm glad the lack of foreach support is covered in the plans.

Something like

foreach (int i in [1, 2, 3])

was literally the first thing I tried with collection literals and I was surprised why it was failing to compile with CS9176 saying there was no target type. It basically provides exactly the same amount of information as

foreach (var i in (IEnumerable<int>)[1, 2, 3])

which happily compiles today (though I would rather use some old-school array initialization instead of the bulky cast).

I think this could be added even independently from natural types.

[eiriktsarpalis]

One addition that we would like to see is support for multi-dimensional collection literals. These are important when working with tensor libraries, e.g. here's how simple tensors are defined using the pytorch library:

data = [[1, 2],[3, 4]]
x_data = torch.tensor(data)

The above form isn't feasible using today's C# collection literals, so supporting it without some kind of language support seems unlikely.

One possibility is that we could reuse nested collection literal syntax to construct multi-dimensional collections. TL;DR it should be possible to extend the collection builder pattern to recognize factory methods such as

public static T[,] Create<T>(ReadOnlySpan<T> values, int nDim, int mDim);

and then be able to define 2-D arrays like so

T[,] values = [[1, 0], [0, 1]];

In principle, it should be possible for the compiler to infer the rank and dimensions and detect shape mismatches (e.g. something like [[1], [2, 3]]).

What's more interesting though is that by reusing nested collection syntax there is no inherent limit on the supported number of dimensions, and the number of dimensions doesn't need to be fixed for a given type. We could for instance support builder methods of shape

public static Tensor<T> Create<T>(ReadOnlySpan<T> values, params ReadOnlySpan<int> dimensions);

Which should let you specify the following 2x2x2 tensor:

Tensor<int> tensor = [[[0, 0], [0, 0]], [[1, 0], [0, 1]]];

[CyrusNajmabadi]

Thanks @eiriktsarpalis . The working group is discussing this. I'll add you to that.

[NetMage]

Having read the (hundreds) of comments on the original Collection Expression proposal, and noting the large number of natural type immutable versus mutable comments, what about if the type was immutable if the Collection Expression consisted only of immutable literals?

var ss = [ "a", "b", "c" ]; // creates ImmutableArray<string> (or ideally a native immutable array type (`const T)[]`)

ss[1] = "z"; // compiler error

but

var tt = [ ..ss ];

tt[1] = "z"; // fine

[jnm2]

@NetMage Why would [.. expr] create a mutable collection while [expr] creates an immutable one?

[SENya1990]

Greetings to everyone.

Sorry in advance if the topic I am asking about was already discussed somewhere. In that case I would be very grateful if you share the link to such discussion with me. I usually do not participate in the proposal discussions, this is a first one for me. So, please excuse me if I don't follow some workflow for proposal discussions.

I decided to reach out after I worked a bit with collection expressions in C# 12, investigated the generated code for them, and found two cases that I personally found confusing. Here is the first one:

Infinite generators.

Suppose that you have some kind of a collection generator that can generate an infinite IEnumerable<T> collection. Here is an example:

private static IEnumerable<int> OddNumbers()
{
	int current = 1;

	while (true)
	{
		yield return current;
		current+=2;
	}
}

This can be used with LINQ: OddNumbers().Take(3). Now I have to prepend the collection with -1:

var oddNumbers = OddNumbers();
IEnumerable<int> oddNumberWithMinus1 = [-1, .. oddNumbers];
// we will never get here

Unexpectedly, this program hangs. The investigation of the generated code shows that the compiler generates the code that internally fully materializes the collection in memory:

IEnumerable<int> ints1 = Program.OddNumbers();
List<int> items = new List<int>();
items.Add(-1);

foreach (int num in ints1)
     items.Add(num);
     
IEnumerable<int> ints2 = (IEnumerable<int>) new \u003C\u003Ez__ReadOnlyList<int>(items);

Because of this the program hangs - it's impossible to materialize an infinite collection. So my problems are:

1. It is unexpected to see that infinite collections are not supported. Maybe it's my fault but I totally missed that the collection initializer feature works only on finite collections and requires their materialization. I saw terms "collection" and "sequence" used in the discussion and in the articles describing the feature (like this one from MSDN: https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/operators/collection-expressions).

However, the term collection was used for IEnumerable<T> and nothing mentions that they have to be finite. If I missed it then I'm sorry about this rant, please share the link with me.

I think, it will be difficult if even possible to write an analyzer to warn about such cases, but at least the documentation should be very clear about them.

2. It is unexpected to see an intermediate collection materialization of IEnumerable<T> completely hidden from the developer. Moreover, the usage of collection expression breaks the lazy evaluation implicitly. Is it expected that square braces act as some sort of collection materializer like ToList() and ToArray() in LINQ?

Could this scenario receive some extra support in C# 13? Because the extra allocation here could be removed with standard LINQ methods like Prepend:

var oddNumbers = OddNumbers();
IEnumerable<int> x = oddNumbers.Prepend(-1);
Console.WriteLine(string.Join(" ", x.Take(3)));             // prints -1 1 3

Sorry if such proposal was already considered and thanks in advance.

[HaloFour]

@SENya1990

Collection expressions aren't a comprehension language or intended as an alternative to LINQ, they always fully materialize spreads. I do agree that the documentation should probably call this out more clearly.

[CyrusNajmabadi]

Is it expected that square braces act as some sort of collection materializer like ToList() and ToArray() in LINQ?

Yes. It's a core part of the design. Linq is already there for comprehensions. Collection expressions exist intentionally to produce fully materialized collections.

[CyrusNajmabadi]

Could this scenario receive some extra support in C# 13? Because the extra allocation here could be removed with standard LINQ methods like Prepend:

Thanks for the feedback, but this was an intentional decision. We do not want these collections to be lazy (and then have expensive enumeration semantics, or have them redo computation each time you enumerate). We have query comprehensions for that already. These collections are intended to be fully materialized, so you know that the final collection you get is cheap, efficient and finite.

[SENya1990]

The second scenario I have encountered is somewhat artificial and definitely does not follow best design practices. Still, I believe it useful to bring it because in this scenario C# compiler breaks the code subtly because of its usage of duck typing.

Misuse of the "Count" property with duck typing

The scenario involves the collection expression like this:

public static IEnumerable<int> PrependOne(<Some integer collection type> s) => [1, ..s];

The generated code for the method looks like this:

      int num1 = 1;
      <collection type> myCollection = s;
      int index1 = 0;
      int[] items = new int[1 + myCollection.Count];
      items[index1] = num1;
      int index2 = index1 + 1;
      
      foreach (int num2 in myCollection)
      {
        items[index2] = num2;
        ++index2;
      }
      
      return (IEnumerable<int>) new <>z__ReadOnlyArray<int>(items);

The C# compiler is very clever, it attempts to generate the most optimized code relying on the Count property if such property is present in the collection type and deducing the required size of the created temporary array used to materialize the collection.

However, while C# compiler cheats while using this size calculation. Everything is OK when the collection explicitly states that it can provide Count for its elements by implementing one of the common interfaces for the collections with a known number of elements such as IReadOnlyCollection<T>. But, when collection does not implement such interface, C# compiler uses duck typing to access the Count property, if the collection has such property accessible in the scope of the collection expression.

Now consider this example. Suppose I have the following custom collection:

public class MyCollection : IEnumerable<int>, IEnumerable<string>
{
	private readonly int[] _ints;
	private readonly string[] _strings;

	internal int Count => _strings.Length;

	public MyCollection(int[] ints, string[] strings) => (_ints, _strings) = (ints, strings);

	public IEnumerator<int> GetEnumerator() => ((IEnumerable<int>)_ints).GetEnumerator();

	IEnumerator IEnumerable.GetEnumerator() => _ints.GetEnumerator();

	IEnumerator<string> IEnumerable<string>.GetEnumerator() => ((IEnumerable<string>)_strings).GetEnumerator();
}

The example is artificial and it's clearly not the best design. But similar code appears sometimes, or can live in an old legacy code base.

Now, suppose I'm using this custom collection in a collection expression:

public static IEnumerable<int> PrependOne(MyCollection s) => [1, ..s];

//...
var myCollection = new MyCollection([1, 2, 3, 4], ["string"]);
IEnumerable<int> modified = PrependOne(myCollection);

And unexpectedly I received IndexOutOfRangeException. Why? I never have accessed any indexes. This custom collection does not even have them! This error happens because C# compiler assumes that there is a contract somewhere where it does not exists.

This looks confusing to me, no written code has any access by index. It requires for developer to know what code is generated by the compiler behind the nice syntax sugar.

I can't say that I really like this compiler trick even if it is legal and probably brings some performance benefits and less allocations in case of value types. The compiler assumes a contract in a place where it does not exists (the whole idea of duck typing). I know that C# already did this before, for example with foreach. But in this place in my opinion it is easier to misinterpret the intention behind the Count property. And C# feels much less statically typed at this moment (and I'm not talking about the dynamic feature).

[SENya1990]

@HaloFour , @CyrusNajmabadi thank you for your response!

You both very clearly confirmed that the feature was designed to materialize collections and works only on finite collections. Could you please specify a place in the Microsoft documentation, or at least an easy to find blog post (although not ideal because they are frequently lost after several years), where it contains as clear explanation as the one you provided to me?

[CyrusNajmabadi]

The example is artificial and it's clearly not the best design.

We made explicit choices with collection expressions to assume that people write well-behaved and sensible types. We want the optimizations to hit the broadest set of cases. It is understood that a non-well-behaved type may then have problems. But we're optimizing the lang design for the literal 99.999% case, at the cost of these strange outliers. Our recommendation if you do have types like these is to write analyzers to block them off with collection-exprs.

[SENya1990]

@CyrusNajmabadi that is understandable. I do understand at least part of the reasons why the duck typing was used. However, shouldn't this be described very thoroughly in the official documentation?

For example, you just introduced a new way to classify types - well-behaved. Is there a formal definition for a well behaved type? I may consider the collection from my example to be well-behaved, why not? It does not break any contracts it explicitly states, only some implicit contracts that were later imposed by the new version of compiler.

[CyrusNajmabadi]

However, shouldn't this be described very thoroughly in the official documentation?

Sure. Feel free to file doc bugs. :)

For example, you just introduced a new way to classify types - well-behaved. Is there a formal definition for a well behaved type?

Yes. If you are a collection type (defined in our spec), and you supply a .Count, then enumerating you should produce the same number of elements. Similarly, if you have an indexer, and you index into the type from 0 to Count-1 then those should produce the same values in the same order as if you just did the enumerator.

[CyrusNajmabadi]

I may consider the collection from my example to be well-behaved, why not?

Because the Count and GetEnumerator refer to totally different sequences. Again, this is vastly out of the normal case for collection use in reality. :)

We are being pragmatic here. The 99.999% case is well behaved collections. Sacrificing the value we get on the normal case for the ecosystem for strange types like this would be cutting off our nose to spite our face.

[SENya1990]

Yes. It's a core part of the design. Linq is already there for comprehensions. Collection expressions exist intentionally to produce fully materialized collections.

And there is nothing in the documentation that clarifies this and prevents the feature from being misused. Moreover, collection expressions definitely overlap with IEnumerable collections. Before I learned about the collection materialization I would definitely use collection expressions instead of LINQ Append, Prepend, Concat because of the new short and more elegant syntax.

Sure. Feel free to file doc bugs. :)

I definitely will. I have read more thoroughly the documentation and feature specs and I'm sorry to say this but I feel that the current documentation is in an awful state. A lot of things like collection materialization or duck typing are implicit or not mentioned at all. Many are described in "feature specs" which contain too much details about implementation and at the same time explicitly state that the actual implementation may be different which undermines their value.

[CyrusNajmabadi]

And there is nothing in the documentation that clarifies this and prevents the feature from being misused.

Feel free to contribute doc fixes or file issues. This is all open source :-)

This is the repo for the design and specification of the feature. Docs are not done here. Feedback on that should go to the docs team. Thanks!