Skip to content
Tutorials Center
My learning

Topics

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.

C#
(int Min, int Max) range = (1, 10);
var (low, high) = range;

Try it

C# Names, returns and deconstruction

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# Equality, dictionary keys and pattern matching

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#
(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

  • ValueTuple versus Tuple. System.Tuple<...> is the old immutable class with Item1/Item2. ValueTuple is 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 readonly field 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 record or small struct is clearer and versionable.
  • Deconstruction works with your types too: add a Deconstruct(out ..., out ...) method and var (a, b) = obj; works. Positional records get one automatically.
  • Async. Task<(int, string)> works; remember that out parameters 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.