Proposal: CollectionInitializerAttribute

[HaloFour]

• Proposed
• Prototype: Not Started
• Implementation: Not Started
• Specification: Not Started

Summary

Allow developers to provide hints to the C# compiler as to how best to emit method calls for collection initializer syntax.

Motivation

Collection initializers currently follow a convention to discover how to add elements to the target. That convention is that the target type implements System.Collections.IEnumerable and offers an instance Add method accepting a single argument. This works pretty well for the most part but it has the two following problems:

1. It's inefficient in that the compiler will emit multiple calls to Add for each item rather than a method like AddRange which would allow the type to add the items in bulk.
2. For some types like ImmutableArray<T> the convention doesn't work as Add doesn't mutate the current instance but instead returns a new instance.

Furthermore, improving the current initializer behavior to, say, support AddRange over Add could introduce breaking changes to people's code.

Detailed design

Instead of making the compiler automatically "smarter" in selecting better methods to perform the initializer, a new attribute (or attributes) could be provided to give the compiler hints as to what code to emit. That would allow the change to be more intentional and a lot less likely to be "breaking".

I propose the addition of the attribute System.Runtime.CompilerServices.CollectionInitializerAttribute which the C# compiler would recognize by the full type name, as it does with System.Runtime.CompilerServices.ExtensionAttribute. Further, I propose the following behaviors when a method is decorated with this attribute:

1. When the method accepts an array or a collection all of the elements in the initializer will be passed to that method in a single method call:

   public class MyList {
       [CollectionInitializer]
       public void AddRange(int[] numbers) {
           Console.WriteLine($"Added {numbers.Length} numbers!");
       }
   }
   
   ///
   var list = new MyList { 1, 2, 3 };
   // equivalent to
   var list = new MyList();
   list.AddRange(new int[] { 1, 2, 3 });

2. When the method returns the same type as the target method then the return value of the method will be the resulting expression of the collection initializer:

   public class MyImmutableList {
       [CollectionInitializer]
       public MyImmutableList Add(int value) {
           Console.Write($"{value} ");
       }
   }
   
   ///
   var list = new MyImmutableList { 1, 2, 3 };
   // equivalent to
   var list = new MyImmutableList()
       .Add(1)
       .Add(2)
       .Add(3);

3. The two above behaviors can be combined:

   public class MyEfficientImmutableList {
       [CollectionInitializer]
       public MyEfficientImmutableList AddRange(IEnumerable<int> values) { }
   }
   
   ///
   var list = new MyEfficientImmutableList { 1, 2, 3 };
   // equivalent to
   var list = new MyEfficientImmutableList()
       .AddRange(new int[] { 1, 2, 3 });

Drawbacks

Alternatives

Unresolved questions

Design meetings

[HaloFour]

Threw this proposal together based on this comment about how the C# compiler already gets collection initializers wrong with the types in System.Collections.Immutable.

[alrz]

var list = new MyList { 1, 2, 3 };
// equivalent to
var list = new MyList();
list.AddRange(new int[] { 1, 2, 3 });

What is the advantage of this compared to a params parameter?

[HaloFour]

@alrz

What is the advantage of this compared to a params parameter?

The ability to use collection initializer syntax. The method could be params though.

[svick]

It's inefficient in that the compiler will emit multiple calls to Add for each item rather than a method like AddRange which would allow the type to add the items in bulk.

How is a method that always allocates a garbage array going to help with efficiency?

What I would prefer would be some way for the collection initializer to tell the collection how many items are there going to be. For example, var list = new List<int> { 1, 2, 3 }; would compile to var list = new List<int>(3); list.Add(1); list.Add(2); list.Add(3);.

(I'm not completely sure this is good enough, because it could decrease performance in cases like var list = new List<int> { 1, 2, 3 }; list.Add(4);. But I think it's still better than allocating an array unnecessarily.)

For some types like ImmutableArray<T> the convention doesn't work as Add doesn't mutate the current instance but instead returns a new instance.

How does this proposal help with that? What attributes could be applied to ImmutableArray<T> and what would they do?

When the method accepts an array or a collection […]

How does the compiler know how to create the collection? Or did you mean "a collection interface" and the compiler will always create an array?

[HaloFour]

@svick

How is a method that always allocates a garbage array going to help with efficiency?

Heh, that's definitely true. Perhaps multiple overloads could be decorated and the compiler would pick the most appropriate one via normal overload resolution?

public class MyList {
    [CollectionInitializer]
    public void Add(int x) { }
    [CollectionInitializer]
    public void Add(int x, int y) { }
    [CollectionInitializer]
    public void Add(int x, int y, int z) { }
    [CollectionInitializer]
    public void Add(params int[] x);
}

///
var list = new MyList { 1, 2, 3 };
// equivalent to
var list = new MyList();
list.Add(1, 2, 3);

How does this proposal help with that? What attributes could be applied to ImmutableArray<T> and what would they do?

That should be ImmutableList<T>, my mistake. The second part of this proposal would be to allow said methods to return new instances rather than mutating.

How does the compiler know how to create the collection?

I left that kind of vague intentionally. Easiest route would be via an array, like params today, but I'd be happy to explore other options.

I'm also aware of the "weirdness" around having one attribute mean multiple things. I'd also be game for multiple attributes or properties of that attribute that would provide the hints to the compiler, e.g.

[CollectionInitializer(Range = true)]
public void Add(params int[] x) { ... }

[CollectionInitializer(Builder = true)]
public MyList(int x) { ...; return new MyList(...); }

After your comment about the compiler doing the wrong thing in certain cases and not being able to change that due to backward compatibility I thought about what might be possible to "fix" these scenarios and to make the initializers smarter based on hints provided by the developer.

[MgSam]

@svick In what instances would collection initializers be used in the kind of performance critical code where it makes any meaningful difference whether the collection is specified with a default size or allocated an array for params?

Seems like premature optimization to me.

I think this proposal is useful for the 99% of cases where collection initializers are executed only once (not in an inner loop of something).

[svick]

@MgSam That's a good question.

I think if you can easily make a change to the generated code that sometimes improves performance at least by a small amount (and never decreases it), then that's a change that should be taken. Though it's not clear to me whether my suggestion fits any of these criteria.

On the other hand, what is the point of adding support to AddRange, if performance is not important? The only reason to support it seems to be performance.

[MgSam]

I agree about AddRange. I doubt there's much benefit there.

However, I like this proposal because it takes a narrowly applicable feature and makes it more broadly usable. The fact that collection initializers currently only work for Add methods has always been unfortunate.

[uecasm]

Having just created a custom collection class which does some additional work after Add (statistics) and thus does have the property where AddRange will be cheaper than repeated Add (at least where N is large enough to offset any negative effects of creating an array; I haven't profiled it), something like this would be nice.

Another possibility might be some sort of deferred update interface (eg. BeginUpdate/EndUpdate like in many Windows Forms classes) which gets automatically used by collection initializers if implemented by the collection class. That seems like more work to implement correctly in the collection classes than just making it use AddRange, though perhaps avoids any performance penalty from creating arrays (unless the class internally needs to put deferred items in a separate list... which might not be uncommon).

[StefanBertels]

IMHO the most important thing is to avoid wrong code for use cases like immutable data types as suggested in #3211.

new MyImmutableList {1,2,3} needs to produce code equivalent to new MyImmutableList<int>().Add(1).Add(2).Add(3) or produce compiler errors.

Everything else like performance is IMHO nice to have, cf. extensive discussion IEnumerable ./. params.

[sab39]

InterpolatedStringHandlerAttribute might be a good pattern to use here, since it gives the implementor a lot of flexibility to decide which strategy is the most optimal for the specific type in question.