C# Reference ยท Collections
C# collections overview
Overview of the C# collection types: arrays, List<T>, Dictionary, HashSet, Queue, Stack and sorted collections, with a guide to choosing the right one.
A collection holds a group of related values. .NET ships a small family of them in System.Collections.Generic, and each one is optimized for a different access pattern: by position, by key, by uniqueness, or by arrival order. Picking the right one usually matters more than any micro-optimization later.
In new code you use the generic collections (List<T>, Dictionary<TKey,TValue>, and so on). The old non-generic ones in System.Collections (ArrayList, Hashtable) store object, box value types and give no compile-time type checking. Avoid them.
List<string> names = ["Ann", "Bob"]; Dictionary<string, int> ages = new() { ["Ann"] = 31 }; HashSet<int> seen = [];
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.
The collection families
| Need | Use | Lookup | Add |
|---|---|---|---|
| Fixed size, fastest indexing | T[] |
O(1) by index | not possible |
| Growable ordered list | List<T> |
O(1) by index, O(n) search | O(1) amortized at the end |
| Find a value by key | Dictionary<TKey,TValue> |
O(1) average | O(1) average |
| Unique values, fast membership | HashSet<T> |
O(1) average | O(1) average |
| Sorted unique values | SortedSet<T> |
O(log n) | O(log n) |
| Sorted key/value pairs | SortedDictionary<TKey,TValue>, SortedList<TKey,TValue> |
O(log n) | O(log n) (SortedList: O(n) for a middle insert) |
| First in, first out | Queue<T> |
peek the front | O(1) |
| Last in, first out | Stack<T> |
peek the top | O(1) |
| Smallest priority first | PriorityQueue<TElement,TPriority> |
peek the min | O(log n) |
| Fast insert/remove at a known node | LinkedList<T> |
O(n) search | O(1) at a node |
Other groups worth knowing:
- Immutable and frozen collections (
ImmutableArray<T>,FrozenDictionary) never change after creation, which makes them safe to share. - Concurrent collections (
ConcurrentDictionary,ConcurrentQueue<T>) are safe to use from several threads. - Read-only views (
IReadOnlyList<T>,ReadOnlyCollection<T>) expose a collection without letting callers change it.
Usage notes
- Default to
List<T>andDictionary<TKey,TValue>. They cover most needs. Reach for the others when the access pattern clearly matches. - Program to interfaces at boundaries. Accept
IEnumerable<T>orIReadOnlyList<T>in parameters and return the narrowest interface that is useful. Inside a method, use the concrete type. - Dictionary and HashSet enumeration order is not guaranteed. Do not rely on insertion order, and sort before printing if you need stable output.
- Keys need good equality. A custom key type needs consistent
EqualsandGetHashCode(or anIEqualityComparer<T>). Mutating a key after inserting it breaks lookups. - Do not modify while enumerating. Adding or removing during
foreachthrowsInvalidOperationExceptionfor the standard collections. - Collection expressions (
[1, 2, 3]) create arrays, lists, sets and spans with one syntax, and the spread element..combines them. - Set capacity with the constructor when you know the final size, to avoid repeated resizing.