C# Reference ยท Collections
Collections of tuples
Patterns for collections of C# tuples: lists of named tuples, tuples as dictionary or HashSet keys, sorting, deconstruction in foreach and when a record fits better.
A ValueTuple such as (string Name, int Age) is a lightweight way to group a few values without declaring a class. Collections of tuples are handy for small result sets, multi-part dictionary keys, grid coordinates and quick sorting by several fields. Tuples implement value equality and a good GetHashCode, so they work as keys in a Dictionary or HashSet out of the box.
Tuple element names are a compile-time feature. At run time the elements are always Item1, Item2, and so on, so names do not take part in equality and are lost if you cast to object.
var people = new List<(string Name, int Age)> { ("Ann", 31), ("Bob", 25) }; var visited = new HashSet<(int X, int Y)> { (0, 0), (1, 0) };
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
List<(string Name, int Age)> list = new(); // tuple type with names Dictionary<(int X, int Y), char> map = new(); // tuple as key var (name, age) = list[0]; // deconstruction
Tuple types are System.ValueTuple<T1, T2, ...>: structs with public mutable fields Item1, Item2, and so on. The older System.Tuple<...> is a class and is rarely the right choice.
Equality and ordering: ValueTuple implements IEquatable, IComparable and IStructuralEquatable. Comparison goes element by element with the default comparer of each element type.
Usage notes
- A tuple key is mutable inside a list but a dictionary copies it on insertion, so changing your variable later does not affect the key.
- Tuples contain public fields:
list[0].Age = 5fails withCS1612: Cannot modify the return value of 'List<(string Name, int Age)>.this[int]' because it is not a variable, because the indexer returns a copy. Replace the whole tuple (list[0] = (list[0].Name, 5)) or use aforeachwith an index loop. - Names are only compile-time. Converting to
object, reflection, serialization andToString()ignore them (ToString()prints(Ann, 31)). - Large tuples (more than 7 or 8 elements) get nested internally and are hard to read; switch to a
recordorstructwhen a group of values is used in many places or has behavior. - A tuple of reference types and
float/doubleelements uses their default equality, soNaNandnullfollow the usual rules of those types. - For a custom equality rule (for example case-insensitive strings), pass an
IEqualityComparer<(string, int)>to the dictionary or set. - Tuples are structs, so a list of tuples stores the values inline, with no per-item allocation.