C# Reference ยท Operators and Expressions
C# collection expressions and the spread element
Reference for C# 12 collection expressions: the [a, b, c] syntax, the spread element .., target types, empty collections, collection builders and limits.
A collection expression is a list of elements in square brackets that creates an array, a List<T>, a span, an immutable collection or any other supported collection type. The type is chosen from the target: int[] a = [1, 2, 3]; makes an array, List<int> l = [1, 2, 3]; makes a list.
Inside the brackets, a spread element ..expr inserts every item of another sequence in place. This is how you concatenate, copy and filter sequences without Concat, AddRange or manual loops. Collection expressions were added in C# 12; they need a target type, so var x = [1, 2]; does not compile (C# 14 does not change this).
int[] first = [1, 2, 3]; int[] more = [0, ..first, 4]; // 0,1,2,3,4
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Syntax
Target t = [element1, element2, ..sequence, element3]; Target e = [];
| Part | Description |
|---|---|
[ ... ] |
Collection expression. Needs a target type from a declaration, parameter, return type or cast. |
element |
Any expression convertible to the element type. |
..sequence |
Spread: every item of sequence (anything enumerable) is inserted at that position, in order. |
Valid targets: arrays; Span<T> and ReadOnlySpan<T>; types with a collection initializer shape (an IEnumerable implementation and a suitable Add), such as List<T>, HashSet<T> and Queue<T>; interfaces IEnumerable<T>, IReadOnlyCollection<T>, IReadOnlyList<T>, ICollection<T> and IList<T>; and types with a [CollectionBuilder] method, such as the immutable collections.
Errors: no target type, or a target type that is not a supported collection (for example a Dictionary<,>, which has no Add(T) shape), is a compile error. The spread's elements must convert to the element type.
Usage notes
- Two syntaxes, two meanings of
... In[..a, ..b]the..is a spread; ina[1..3]it is the range operator. They never conflict because of their positions. - Allocation. The compiler picks an efficient plan: for an array target with known sizes it allocates once; for
ReadOnlySpan<T>of constants it can point at static data; forList<T>it presizes. This is usually faster thannew List<int>(a).AddRange(b)chains. - Interface targets.
IEnumerable<T>,IReadOnlyList<T>and similar produce a read-only compiler-generated object.ICollection<T>andIList<T>produce a mutableList<T>. Do not rely on the concrete type. - Spread evaluates once, in order, and the source sequence is not modified. Spreading a sequence into itself (
list = [..list, 1]) creates a new list. - No
var.var x = [1, 2, 3];fails; declare the type, or writeint[] x = [1, 2, 3];. - Dictionaries are not collection expression targets in C# 14. Use a dictionary initializer.
- Custom types can opt in with
[CollectionBuilder(typeof(MyBuilder), nameof(MyBuilder.Create))]and aCreate(ReadOnlySpan<T>)method. - Differs from the old syntax:
new[] { 1, 2 },new List<int> { 1, 2 }andArray.Empty<int>()still work;[]for an empty array may reuse a cached empty instance. - Target-typed in conditionals.
cond ? [1] : []works when a target type exists.