Кортежи в C#: именованные кортежи, возврат нескольких значений, деконструкция

Кортеж объединяет небольшое фиксированное число значений в одно значение без объявления класса. ("Ana", 31) это кортеж из string и int. Кортежи это идиоматичный способ вернуть из метода две или три вещи и хранить недолговечные пары внутри метода.

Создание кортежа

Тип тоже записывается в скобках: (string, int) это тип кортежа, первый элемент которого string, а второй 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);
    }
}

Вывод:

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

Без имён элементы называются Item1, Item2, Item3 и так далее. Эти кортежи являются структурами System.ValueTuple, поэтому присваивание одного другой переменной копирует значения, и изменение копии не затрагивает оригинал.

Именованные элементы

Item1 ничего не говорит о том, что это за значение. Дайте элементам имена либо в типе, либо в литерале:

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);
    }
}

Вывод:

Ana, 31
Desk lamp costs 24.99
Ana
Ana

Имена это удобство времени компиляции. Во время выполнения оба кортежа выше это обычные значения ValueTuple<string, int>, поэтому присваивание person кортежу с другими именами компилируется: совпадать должны только типы элементов и их порядок.

C# 7.1 и новее также выводят имена из переменных в литерале, поэтому var t = (name, age); даёт t.name и t.age без повторного написания. В C# 7.0 эти элементы доступны только как Item1 и Item2.

Возврат нескольких значений из метода

Это главная причина, по которой кортежи добавили в язык. До них вариантами были параметры out, разовый класс или System.Tuple с его безымянным 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"));
    }
}

Вывод:

Lowest 60, highest 95
Average 78.75

Имена элементов в возвращаемом типе становятся именами, которые видит вызывающий код. Сравните с тем же методом на параметрах out:

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 остаются соглашением для формы TryParse, где bool сообщает, получилось ли, а значение возвращается рядом с ним. Для «вычислить несколько вещей и вернуть их» кортеж читается лучше. См. ref и out.

Деконструкция

Деконструкция распаковывает кортеж в отдельные переменные одним оператором:

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);
    }
}

Вывод:

Lima 24.5
Lima
24.5
2 1

Имена переменных в var (city, temp) выбираете вы; они не обязаны совпадать с именами элементов кортежа, потому что деконструкция идёт по позиции. Обмен (a, b) = (b, a) сначала строит кортеж из старых значений, а затем присваивает, поэтому ни одно значение не теряется.

Ваши собственные классы могут поддерживать деконструкцию, объявив метод Deconstruct с параметрами out. Начиная с C# 7 и .NET Core 2.0 или новее такой метод есть и у KeyValuePair, поэтому цикл по словарю может распаковывать каждый элемент прямо в заголовке:

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}");
}

Та же форма foreach (var (a, b) in listOfTuples) работает и для списка кортежей. Брать весь кортеж одной переменной цикла и читать его именованные элементы, как в следующем разделе, тоже вполне нормально.

Кортежи в списках, LINQ и словарях

Список именованных кортежей это лёгкий способ хранить строки данных внутри метода:

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)));
    }
}

Вывод:

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

ValueTuple реализует Equals и GetHashCode поэлементно, поэтому (2, 7), созданный в двух разных местах, находит один и тот же элемент словаря. Это делает кортеж самым простым составным ключом: ни класса, ни написанной вручную хеш-функции, ни склеивания строк вроде row + ":" + col.

Равенство кортежей

Equals сравнивает поэлементно и работает с момента появления кортежей:

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)));
    }
}

Вывод:

True
False

C# 7.3 добавил для кортежей == и !=, которые компилируются в такое же поэлементное сравнение и тоже не учитывают имена:

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

System.Tuple и ValueTuple

В .NET 4 появился System.Tuple, класс, создаваемый через Tuple.Create. Он по-прежнему есть во фреймворке и по-прежнему встречается в старом коде и API, поэтому поиск «C# tuple» часто приводит к нему.

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);
    }
}

Вывод:

Ben 25
(Ben, 25)

ToValueTuple() и ToTuple() преобразуют одно в другое. В новом коде предпочитайте кортежи-значения: они ничего не выделяют в куче и могут нести имена.

Когда вместо кортежа нужен класс или запись

Кортежи лучше всего подходят, когда группировка локальная и очевидная: метод возвращает два числа, запрос LINQ передаёт пару на следующий шаг, словарю нужен ключ из двух частей. Переходите на именованный тип, когда:

• Одна и та же форма встречается в нескольких сигнатурах открытых методов. (string, string, int) в пяти местах это класс, который ещё не написан.
• Значениям нужны поведение, проверка или больше трёх-четырёх элементов.
• Данные пересекают границу, например сериализацию. Имён во время выполнения нет, поэтому Newtonsoft.Json пишет Item1 и Item2, а System.Text.Json пишет {}, потому что элементы кортежа это поля, которые он по умолчанию пропускает.

Записи C# 9 дают большую часть удобства кортежа, но с настоящим именем. У record Score(string Name, int Points); есть встроенные равенство по значению, читаемый ToString и деконструкция. См. записи.

Частые ошибки

• Ожидание, что имена сохранятся во время выполнения. Рефлексия и сериализаторы видят Item1, Item2 (или вообще ничего).
• Изменение копии. Кортежи это структуры: var t2 = t1; t2.Item1 = 5; не меняет t1.
• Кортежи с большим числом элементов. После трёх-четырёх именованный тип читается лучше.
• Путаница в порядке деконструкции. Она позиционная: с кортежем (Name, Age) запись var (age, name) = person; кладёт имя в age, и поскольку var выводит типы, ничего вас не предупредит.