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.)
int[] array = [1, 2, 3]; List<string> list = ["a", "b"]; int[] joined = [..array, 4, 5];
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, ..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 getCS0173. - 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.[]forIEnumerable<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 asIEnumerable<T>orIReadOnlyList<T>. - Spread evaluates its sequence once. Elements are evaluated left to right, each time the expression runs, so
[Next(), Next()]callsNexttwice. - To support your own types, give the type an
Addmethod and a parameterless constructor, or add[CollectionBuilder(typeof(MyBuilder), nameof(MyBuilder.Create))]pointing at a static method that takes aReadOnlySpan<T>. paramsparameters 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.
Related
- Spread operator
- List
- Immutable collections
- params keyword
- Collection expressions in the tutorial