C#: Which List Constructor is Invoked When Using a Collection Expression?

A collection expression will use the constructor with a capacity parameter if the collection literal has a known length and the target type supports collection initialisers.

From the known length translation section of the feature specification,

• If T supports collection initializers, then:

  • if the type T contains an accessible constructor with a single parameter int capacity, then the literal is translated as:

    CSHARPCopied
    T __result = new T(capacity: __len);
    __result.Add(__e1);
     foreach (var __t in __s1)
        __result.Add(__t);
    
    // further additions of the remaining elements
    

Note: the name of the parameter is required to be capacity.

Here the spec is assuming that __e1 is an expression element (i.e. without the .. prefix) of the collection expression, and __s1 is a spread element (with the .. prefix) of the collection expression.

The definition of "known length" is at the top of that section,

A collection expression has a known length if the compile-time type of each spread element in the collection expression is countable.

And "countable" is defined in the spec for indices and ranges.

A type is Countable if it has a property named Length or Count with an accessible getter and a return type of int.

---

So something simple like,

CSHARPCopied
List<int> list = [1,2,3,4];

will use the capacity constructor.

But if you use any non-countable type in the collection expression, it will not use the capacity constructor. e.g.

CSHARPCopied
IEnumerable<int> someRandomEnumerable = new int[3];
List<int> list = [..someRandomEnumerable ,4];

which version of List constructor will the collection expression compile to?

This depends on which compiler and runtime, and the exact syntax used. If you have a recent compiler (I believe from C# 12 / .NET 8 onwards, but I haven't checked), then the compiler goes far out of it's way to be efficient here. Let's take the example (from @canton7's comment above):

CSHARPCopied
List<int> list = [1, 2, 3, 4, 5];

Assuming this is used against a recent runtime, this goes to great lengths to be efficient; not only using new List<int>(5), but also using nefarious CollectionsMarshal techniques to push the underlying values as efficiently as possible - bypassing the usual list.Add(...) boilerplate, since it understands what is going to happen:

CSHARPCopied
int num = 5;
List<int> list = new List<int>(num);
CollectionsMarshal.SetCount(list, num);
Span<int> span = CollectionsMarshal.AsSpan(list);
int num2 = 0;
span[num2] = 1;
num2++;
span[num2] = 2;
num2++;
span[num2] = 3;
num2++;
span[num2] = 4;
num2++;
span[num2] = 5;
num2++;
List<int> list2 = list;

If the necessary CollectionsMarshal methods aren't available, it will still use the correct initial size.

If we use the older syntax:

CSHARPCopied
var list = new List<int> { 1, 2, 3, 4, 5 };

then this uses the default new List<int>() constructor without the size, and just uses .Add():

CSHARPCopied
List<int> list = new List<int>();
list.Add(1);
list.Add(2);
list.Add(3);
list.Add(4);
list.Add(5);
List<int> list2 = list;

This may be due to how the language specification defines this to behave, or may just be to avoid unexpected surprises. You can improve that by manually specifying the size:

CSHARPCopied
var list = new List<int>(5) { 1, 2, 3, 4, 5 };

but then you need to ensure that you're correct!

So: prefer [...] syntax over {...} syntax, and yes: you should be fine.