C# Reference ยท Types and Literals
C# tuples and ValueTuple
Reference for C# tuples: (int, string) syntax, element names, deconstruction, equality, discards, ValueTuple versus Tuple and tuple limits.
A tuple groups several values into one lightweight value without declaring a class. The syntax (int Id, string Name) creates a System.ValueTuple<int, string>, a mutable struct whose fields are called Item1, Item2 and so on; the names you write are compile-time conveniences for those fields. Tuples are most useful as return values when a method has to give back two or three related things.
Tuples support deconstruction (var (id, name) = pair;), structural equality with ==, and discards. They are not a replacement for a real type when the data has meaning beyond one call: use a record for that.
(int Min, int Max) range = (1, 10); var (low, high) = range;
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
(int, string) t1 = (1, "a"); // unnamed (int Id, string Name) t2 = (1, "a"); // named var t3 = (Id: 1, Name: "a"); // named by the expression var (id, name) = t3; // deconstruction (int x, int y) = GetPoint(); // declare while deconstructing ValueTuple<int, string> t4 = new(1, "a"); // the long form
| Feature | Description |
|---|---|
Item1 ... Item7, Rest |
The real field names. Eight or more elements nest in Rest, which the compiler hides. |
| Element names | Exist only at compile time (stored in an attribute on members and return types). Not visible through reflection on variables. |
==, != |
Element-wise comparison with each element's own ==. |
Equals, GetHashCode, CompareTo |
Structural, using the default comparer of each element. |
ToString() |
"(1, a)". |
Conversions. Tuples of the same arity convert implicitly when each element converts, regardless of names, because the names are not part of the runtime type.
Errors / undefined behavior. There is none specific to tuples; default((int, string)) is (0, null). A tuple literal needs at least two elements.
Usage notes
ValueTupleversusTuple.System.Tuple<...>is the old immutable class withItem1/Item2.ValueTupleis a struct, has the C# syntax and allocates nothing; prefer it.- Mutable structs. Fields can be assigned, but a tuple stored in a collection or a
readonlyfield gives you a copy, so changes to it are lost. - Hash keys. Tuples make good composite keys in dictionaries and sets, and their hash code mixes all elements. Do not mutate them while they are keys.
- Public APIs. Names vanish across assemblies that do not read the metadata attribute and tuples have no behavior or validation. For public contracts, a
recordor small struct is clearer and versionable. - Deconstruction works with your types too: add a
Deconstruct(out ..., out ...)method andvar (a, b) = obj;works. Positional records get one automatically. - Async.
Task<(int, string)>works; remember thatoutparameters cannot be used in async methods, which is a common reason to return a tuple. - Performance. Large tuples are copied by value, so more than three or four elements is a sign you want a named type.
Related
struct,record,out,ref,in,object- Lessons: Tuples, Records, Pattern matching basics