C# Tuple: Named Tuples, Return Multiple Values, Deconstruction

A tuple bundles a small, fixed number of values into one value without declaring a class for it. ("Ana", 31) is a tuple of a string and an int. Tuples are the idiomatic way to return two or three things from a method and to hold short-lived pairs inside a method.

Creating a tuple

The type is written with parentheses too: (string, int) is a tuple type whose first element is a string and second an int.

using System;

class Program
{
    static void Main()
    {
        var pair = ("Ana", 31);                     // type: (string, int)
        Console.WriteLine(pair.Item1 + " is " + pair.Item2);

        var point = (3, 4);                         // (int, int)
        Console.WriteLine(point);                   // ToString shows the values

        var order = ("A-1001", 3, 59.90m);          // any number of elements
        Console.WriteLine(order.Item3 * order.Item2);

        pair.Item2 = 32;                            // elements are mutable fields
        Console.WriteLine(pair);
    }
}

Output:

Ana is 31
(3, 4)
179.70
(Ana, 32)

Without names, the elements are Item1, Item2, Item3 and so on. These tuples are System.ValueTuple structs, so assigning one to another variable copies the values, and changing the copy leaves the original alone.

Named elements

Item1 says nothing about what the value is. Give the elements names, either in the type or in the literal:

using System;

class Program
{
    static void Main()
    {
        (string Name, int Age) person = ("Ana", 31);    // names in the type
        Console.WriteLine(person.Name + ", " + person.Age);

        var product = (Title: "Desk lamp", Price: 24.99m); // names in the literal
        Console.WriteLine(product.Title + " costs " + product.Price);

        Console.WriteLine(person.Item1);                 // still available

        (string First, int Years) renamed = person;      // names do not have to match
        Console.WriteLine(renamed.First);
    }
}

Output:

Ana, 31
Desk lamp costs 24.99
Ana
Ana

Names are a compile-time convenience. At run time both tuples above are plain ValueTuple<string, int> values, which is why assigning person to a tuple with different names compiles: only the element types and their order must match.

C# 7.1 and later also infer names from the variables in the literal, so var t = (name, age); gives you t.name and t.age without writing them twice. In C# 7.0 those elements are only Item1 and Item2.

Returning multiple values from a method

This is the main reason tuples were added to the language. Before them the options were out parameters, a one-off class, or System.Tuple with its anonymous Item1.

using System;

class Program
{
    static (int Min, int Max, double Average) Stats(int[] scores)
    {
        int min = scores[0], max = scores[0], sum = 0;
        foreach (int s in scores)
        {
            if (s < min) min = s;
            if (s > max) max = s;
            sum += s;
        }
        return (min, max, (double)sum / scores.Length);
    }

    static void Main()
    {
        int[] scores = { 72, 95, 60, 88 };

        var stats = Stats(scores);
        Console.WriteLine("Lowest " + stats.Min + ", highest " + stats.Max);
        Console.WriteLine("Average " + stats.Average.ToString("F2"));
    }
}

Output:

Lowest 60, highest 95
Average 78.75

The element names in the return type become the names the caller sees. Compare the same method with out parameters:

static void Stats(int[] scores, out int min, out int max, out double average) { ... }

Stats(scores, out int min, out int max, out double avg);

out parameters remain the convention for the TryParse shape, where a bool says whether it worked and the value comes back alongside it. For "compute several things and return them", a tuple reads better. See ref and out.

Deconstruction

Deconstruction unpacks a tuple into separate variables in one statement:

using System;

class Program
{
    static (string City, double TempC) Warmest()
    {
        return ("Lima", 24.5);
    }

    static void Main()
    {
        var (city, temp) = Warmest();                 // new variables, types inferred
        Console.WriteLine(city + " " + temp.ToString("F1"));

        (string c, double t) = Warmest();             // explicit types
        Console.WriteLine(c);

        var (_, onlyTemp) = Warmest();                // discard what you do not need
        Console.WriteLine(onlyTemp.ToString("F1"));

        int a = 1, b = 2;
        (a, b) = (b, a);                              // swap without a temp variable
        Console.WriteLine(a + " " + b);
    }
}

Output:

Lima 24.5
Lima
24.5
2 1

The variable names in var (city, temp) are yours; they do not have to match the tuple's element names, because deconstruction goes by position. The swap (a, b) = (b, a) builds a tuple from the old values first and then assigns, so neither value is lost.

Your own classes can support deconstruction by declaring a Deconstruct method with out parameters. From C# 7 with .NET Core 2.0 or later, KeyValuePair has one too, so a dictionary loop can unpack each entry in its header:

class Point
{
    public int X { get; }
    public int Y { get; }
    public Point(int x, int y) { X = x; Y = y; }
    public void Deconstruct(out int x, out int y) { x = X; y = Y; }
}

var (x, y) = new Point(3, 4);

foreach (var (name, score) in scoresByName)   // Dictionary<string, int>
{
    Console.WriteLine($"{name}: {score}");
}

The same foreach (var (a, b) in listOfTuples) form works for a list of tuples. Taking the whole tuple as one loop variable and reading its named elements, as the next section does, works just as well.

Tuples in lists, LINQ and dictionaries

A list of named tuples is a light way to hold rows of data inside a method:

using System;
using System.Collections.Generic;
using System.Linq;

class Program
{
    static void Main()
    {
        var results = new List<(string Name, int Score)>
        {
            ("Ana", 88),
            ("Ben", 72),
            ("Chloe", 95),
        };

        foreach (var r in results.OrderByDescending(r => r.Score))
        {
            Console.WriteLine(r.Name + " " + r.Score);
        }

        var passed = results
            .Where(r => r.Score >= 80)
            .Select(r => (r.Name, Grade: r.Score >= 90 ? "A" : "B"))
            .ToList();
        Console.WriteLine(string.Join(", ", passed));

        // Tuples compare by value, so they work as composite dictionary keys.
        var seats = new Dictionary<(int Row, int Col), string>
        {
            [(1, 4)] = "Ana",
            [(2, 7)] = "Ben",
        };
        Console.WriteLine(seats[(2, 7)]);
        Console.WriteLine(seats.ContainsKey((3, 1)));
    }
}

Output:

Chloe 95
Ana 88
Ben 72
(Ana, B), (Chloe, A)
Ben
False

ValueTuple implements Equals and GetHashCode element by element, so (2, 7) built in two different places finds the same dictionary entry. That makes a tuple the simplest composite key: no class, no hand-written hash function, no string concatenation like row + ":" + col.

Tuple equality

Equals compares element by element and has worked since tuples were introduced:

using System;

class Program
{
    static void Main()
    {
        var a = (Name: "Ana", Age: 31);
        var b = (Title: "Ana", Years: 31);   // different names, same values

        Console.WriteLine(a.Equals(b));
        Console.WriteLine(a.Equals(("Ana", 32)));
    }
}

Output:

True
False

C# 7.3 added == and != for tuples, which compile to the same element by element comparison and also ignore names:

if ((order.Status, order.Paid) == ("shipped", true)) { ... }
Console.WriteLine((1, "x") == (1, "x"));   // True

System.Tuple vs ValueTuple

.NET 4 introduced System.Tuple, a class created with Tuple.Create. It is still in the framework and still shows up in older code and APIs, which is why searches for "C# tuple" often land on it.

using System;

class Program
{
    static void Main()
    {
        Tuple<string, int> old = Tuple.Create("Ben", 25);
        Console.WriteLine(old.Item1 + " " + old.Item2);
        // old.Item2 = 26;  // compile error: Item2 is read-only

        var converted = old.ToValueTuple();   // (string, int)
        Console.WriteLine(converted);
    }
}

Output:

Ben 25
(Ben, 25)

ToValueTuple() and ToTuple() convert between the two. Prefer value tuples in new code: they allocate nothing on the heap and they can carry names.

When to use a class or record instead

Tuples are best when the grouping is local and obvious: a method returns two numbers, a LINQ query carries a pair to the next step, a dictionary needs a two-part key. Switch to a named type when:

• The same shape appears in several public method signatures. (string, string, int) in five places is a class that has not been written yet.
• The values need behavior, validation, or more than three or four elements.
• The data crosses a boundary such as serialization. The names do not exist at run time, so Newtonsoft.Json writes Item1 and Item2, and System.Text.Json writes {} because tuple elements are fields, which it skips by default.

C# 9 records give you most of a tuple's convenience with a real name. record Score(string Name, int Points); has value equality, a readable ToString and deconstruction built in. See records.

Common mistakes

• Expecting names to survive at run time. Reflection and serializers see Item1, Item2 (or nothing at all).
• Mutating a copy. Tuples are structs: var t2 = t1; t2.Item1 = 5; leaves t1 unchanged.
• Tuples with many elements. Past three or four, a named type reads better.
• Mixing up deconstruction order. It is positional: with a (Name, Age) tuple, var (age, name) = person; puts the name in age, and because var infers the types, nothing warns you.