Krotki w C# (tuple): nazwane krotki, zwracanie wielu wartości, dekonstrukcja

Krotka (tuple) łączy małą, stałą liczbę wartości w jedną wartość bez deklarowania dla niej klasy. ("Ana", 31) to krotka ze string i int. Krotki to idiomatyczny sposób na zwrócenie dwóch lub trzech rzeczy z metody i na przechowywanie krótko żyjących par wewnątrz metody.

Tworzenie krotki

Typ też zapisuje się w nawiasach: (string, int) to typ krotki, której pierwszy element to string, a drugi 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);
    }
}

Wynik:

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

Bez nazw elementy to Item1, Item2, Item3 i tak dalej. Te krotki to struktury System.ValueTuple, więc przypisanie jednej do innej zmiennej kopiuje wartości, a zmiana kopii nie wpływa na oryginał.

Nazwane elementy

Item1 nic nie mówi o tym, czym jest wartość. Nadaj elementom nazwy, w typie albo w literale:

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

Wynik:

Ana, 31
Desk lamp costs 24.99
Ana
Ana

Nazwy to udogodnienie czasu kompilacji. W czasie działania obie powyższe krotki to zwykłe wartości ValueTuple<string, int>, dlatego przypisanie person do krotki o innych nazwach się kompiluje: muszą się zgadzać tylko typy elementów i ich kolejność.

C# 7.1 i nowsze wnioskują też nazwy ze zmiennych w literale, więc var t = (name, age); daje ci t.name i t.age bez pisania ich dwa razy. W C# 7.0 te elementy to tylko Item1 i Item2.

Zwracanie wielu wartości z metody

To główny powód, dla którego krotki dodano do języka. Wcześniej do wyboru były parametry out, jednorazowa klasa albo System.Tuple z anonimowym 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"));
    }
}

Wynik:

Lowest 60, highest 95
Average 78.75

Nazwy elementów w typie zwracanym stają się nazwami, które widzi wywołujący. Porównaj tę samą metodę z parametrami 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);

Parametry out pozostają konwencją dla kształtu TryParse, w którym bool mówi, czy się udało, a wartość wraca obok niego. Przy zadaniu "oblicz kilka rzeczy i je zwróć" krotka czyta się lepiej. Zobacz ref i out.

Dekonstrukcja

Dekonstrukcja rozpakowuje krotkę na osobne zmienne w jednej instrukcji:

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

Wynik:

Lima 24.5
Lima
24.5
2 1

Nazwy zmiennych w var (city, temp) wybierasz sam; nie muszą pasować do nazw elementów krotki, bo dekonstrukcja działa według pozycji. Zamiana (a, b) = (b, a) najpierw buduje krotkę ze starych wartości, a potem przypisuje, więc żadna wartość nie ginie.

Twoje własne klasy mogą obsługiwać dekonstrukcję, jeśli zadeklarujesz w nich metodę Deconstruct z parametrami out. Od C# 7 z .NET Core 2.0 lub nowszym ma ją też KeyValuePair, więc pętla po słowniku może rozpakować każdy wpis w nagłówku:

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

Ta sama forma foreach (var (a, b) in listOfTuples) działa dla listy krotek. Równie dobrze działa pobranie całej krotki jako jednej zmiennej pętli i odczytywanie jej nazwanych elementów, jak w następnej sekcji.

Krotki w listach, LINQ i słownikach

Lista nazwanych krotek to lekki sposób na przechowywanie wierszy danych wewnątrz metody:

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

Wynik:

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

ValueTuple implementuje Equals i GetHashCode element po elemencie, więc (2, 7) zbudowane w dwóch różnych miejscach znajduje ten sam wpis w słowniku. Dzięki temu krotka to najprostszy klucz złożony: bez klasy, bez ręcznie pisanej funkcji skrótu, bez łączenia stringów w stylu row + ":" + col.

Równość krotek

Equals porównuje element po elemencie i działa od momentu wprowadzenia krotek:

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

Wynik:

True
False

C# 7.3 dodał dla krotek == i !=, które kompilują się do tego samego porównania element po elemencie i też ignorują nazwy:

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

System.Tuple a ValueTuple

.NET 4 wprowadził System.Tuple, klasę tworzoną przez Tuple.Create. Nadal jest we frameworku i nadal pojawia się w starszym kodzie i API, dlatego wyszukiwania "C# tuple" często na nią trafiają.

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

Wynik:

Ben 25
(Ben, 25)

ToValueTuple() i ToTuple() konwertują między nimi. W nowym kodzie wybieraj krotki wartościowe: niczego nie alokują na stercie i mogą mieć nazwy.

Kiedy zamiast tego użyć klasy lub rekordu

Krotki sprawdzają się najlepiej, gdy grupowanie jest lokalne i oczywiste: metoda zwraca dwie liczby, zapytanie LINQ przekazuje parę do następnego kroku, słownik potrzebuje dwuczęściowego klucza. Przejdź na nazwany typ, gdy:

• Ten sam kształt pojawia się w kilku publicznych sygnaturach metod. (string, string, int) w pięciu miejscach to klasa, której jeszcze nie napisano.
• Wartości potrzebują zachowania, walidacji albo więcej niż trzech lub czterech elementów.
• Dane przekraczają granicę, taką jak serializacja. Nazwy nie istnieją w czasie działania, więc Newtonsoft.Json zapisuje Item1 i Item2, a System.Text.Json zapisuje {}, bo elementy krotki to pola, które domyślnie pomija.

Rekordy z C# 9 dają większość wygody krotki z prawdziwą nazwą. record Score(string Name, int Points); ma wbudowaną równość wartości, czytelny ToString i dekonstrukcję. Zobacz rekordy.

Częste błędy

• Oczekiwanie, że nazwy przetrwają w czasie działania. Refleksja i serializatory widzą Item1, Item2 (albo w ogóle nic).
• Zmienianie kopii. Krotki to struktury: var t2 = t1; t2.Item1 = 5; zostawia t1 bez zmian.
• Krotki z wieloma elementami. Powyżej trzech lub czterech nazwany typ czyta się lepiej.
• Pomylenie kolejności dekonstrukcji. Działa według pozycji: przy krotce (Name, Age) var (age, name) = person; umieszcza imię w age, a ponieważ var wnioskuje typy, nic cię nie ostrzeże.