Skip to content
Tutorials Center
My learning

Topics

C# Reference ยท Collections

C# collection expressions

Reference for C# 12 collection expressions: create arrays, lists, spans and immutable collections with [..], use the spread element and write custom builders.

A collection expression is a bracketed list of elements, such as [1, 2, 3], that the compiler turns into whatever collection type the context asks for. It was added in C# 12. The same syntax creates arrays, List<T>, Span<T>, ImmutableArray<T> and more, and .. inside the brackets spreads another sequence into the new collection.

A collection expression has no type of its own. It needs a target type: a variable declaration with an explicit type, a method argument, a return type or a cast. var x = [1, 2]; does not compile. (C# 15 previews a natural type for them; this runner uses C# 14.)

C#
int[] array = [1, 2, 3];
List<string> list = ["a", "b"];
int[] joined = [..array, 4, 5];

Try it

C# Targets and spread

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# Spread with conditions and nesting

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, ..spreadSequence, element3];
Element Description
expr One element, converted to the collection's element type.
..expr A spread element: every item of expr is added in order. expr must be enumerable.

Supported targets: arrays; Span<T> and ReadOnlySpan<T>; types with a constructor/Add (collection initializer pattern) such as List<T> and HashSet<T>; the interfaces IEnumerable<T>, IReadOnlyCollection<T>, IReadOnlyList<T>, ICollection<T> and IList<T>; and any type marked with [CollectionBuilder], such as ImmutableArray<T>.

Errors: CS9176 appears when there is no target type (for example with var). A target that is not a supported collection type produces a conversion error.

Usage notes

  • In a conditional inside a spread there is no target type, so cast one branch ((string[])["admin"]); otherwise you get CS0173.
  • The compiler picks an efficient strategy: it sizes the result up front when it can, and Span<T> targets can live on the stack for small fixed sizes. [] for IEnumerable<T> may return a shared empty instance.
  • For interface targets the concrete type is unspecified. Do not cast the result to List<T> and do not mutate a value you received as IEnumerable<T> or IReadOnlyList<T>.
  • Spread evaluates its sequence once. Elements are evaluated left to right, each time the expression runs, so [Next(), Next()] calls Next twice.
  • To support your own types, give the type an Add method and a parameterless constructor, or add [CollectionBuilder(typeof(MyBuilder), nameof(MyBuilder.Create))] pointing at a static method that takes a ReadOnlySpan<T>.
  • params parameters can use collection types too (params ReadOnlySpan<int>), and a collection expression passes the argument in one go.
  • Collection expressions can also be used in patterns: see list patterns. In a pattern, [1, 2, ..] matches and does not build.
  • Spread in an expression is not the same as the .. range operator (see range and index); it only appears inside brackets in a spread position.