Skip to content
Tutorials Center
My learning

Topics

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).

C#
int[] first = [1, 2, 3];
int[] more = [0, ..first, 4];   // 0,1,2,3,4

Try it

C# Creating and combining collections

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.

C# Target types and spans

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

C#
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; in a[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; for List<T> it presizes. This is usually faster than new List<int>(a).AddRange(b) chains.
  • Interface targets. IEnumerable<T>, IReadOnlyList<T> and similar produce a read-only compiler-generated object. ICollection<T> and IList<T> produce a mutable List<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 write int[] 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 a Create(ReadOnlySpan<T>) method.
  • Differs from the old syntax: new[] { 1, 2 }, new List<int> { 1, 2 } and Array.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.