Tuple ב-C#: tuples עם שמות, החזרת כמה ערכים ופירוק (deconstruction)

tuple מקבץ מספר קטן וקבוע של ערכים לערך אחד בלי להצהיר בשבילו על מחלקה. ("Ana", 31) הוא tuple של string ו-int. tuples הם הדרך המקובלת להחזיר שניים או שלושה דברים ממתודה ולהחזיק זוגות קצרי חיים בתוך מתודה.

יצירת tuple

גם הטיפוס נכתב עם סוגריים: (string, int) הוא טיפוס tuple שהאיבר הראשון שלו הוא 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 וכן הלאה. ה-tuples האלה הם structs מסוג 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

השמות הם נוחות של זמן קומפילציה. בזמן ריצה שני ה-tuples שלמעלה הם ערכי ValueTuple<string, int> רגילים, ולכן השמה של person ל-tuple עם שמות אחרים מתקמפלת: רק הטיפוסים של האיברים והסדר שלהם חייבים להתאים.

C# 7.1 ומעלה גם מסיקות שמות מהמשתנים שבליטרל, כך ש-var t = (name, age); נותן t.name ו-t.age בלי לכתוב אותם פעמיים. ב-C# 7.0 האיברים האלה הם רק Item1 ו-Item2.

החזרת כמה ערכים ממתודה

זו הסיבה העיקרית ש-tuples נוספו לשפה. לפניהם האפשרויות היו פרמטרי 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 אומר אם זה עבד והערך חוזר לצדו. עבור "חשבו כמה דברים והחזירו אותם", tuple קריא יותר. ראו ref ו-out.

פירוק (deconstruction)

פירוק פורס tuple למשתנים נפרדים בפקודה אחת:

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) הם שלכם; הם לא צריכים להתאים לשמות האיברים של ה-tuple, כי הפירוק נעשה לפי מיקום. ההחלפה (a, b) = (b, a) בונה קודם tuple מהערכים הישנים ורק אז משימה, כך ששום ערך לא הולך לאיבוד.

המחלקות שלכם יכולות לתמוך בפירוק אם מצהירים בהן על מתודת 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), עובדת עבור רשימה של tuples. לקחת את כל ה-tuple כמשתנה לולאה אחד ולקרוא את האיברים עם השמות שלו, כמו שהקטע הבא עושה, עובד באותה מידה.

tuples ברשימות, ב-LINQ ובמילונים

רשימה של tuples עם שמות היא דרך קלה להחזיק שורות של נתונים בתוך מתודה:

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) שנבנה בשני מקומות שונים מוצא את אותה רשומה במילון. זה הופך את ה-tuple למפתח המורכב הפשוט ביותר: בלי מחלקה, בלי פונקציית hash שנכתבה ידנית, ובלי שרשור מחרוזות כמו row + ":" + col.

שוויון של tuples

Equals משווה איבר אחר איבר ועובדת מאז ש-tuples הוצגו:

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 הוסיפה == ו-!= ל-tuples, שמתקמפלים לאותה השוואה איבר אחר איבר ומתעלמים גם הם מהשמות:

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

System.Tuple מול ValueTuple

.NET 4 הציגה את System.Tuple, מחלקה שנוצרת עם Tuple.Create. היא עדיין קיימת ב-framework ועדיין מופיעה בקוד וב-APIs ישנים, ולכן חיפושים של "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() ממירות בין השניים. העדיפו value tuples בקוד חדש: הם לא מקצים כלום ב-heap והם יכולים לשאת שמות.

מתי להשתמש במחלקה או ב-record במקום

tuples הכי טובים כשהקיבוץ מקומי וברור: מתודה מחזירה שני מספרים, שאילתת LINQ מעבירה זוג לשלב הבא, מילון צריך מפתח משני חלקים. עברו לטיפוס עם שם כש:

• אותה צורה מופיעה בכמה חתימות של מתודות ציבוריות. (string, string, int) בחמישה מקומות הוא מחלקה שעוד לא נכתבה.
• הערכים צריכים התנהגות, ולידציה, או יותר משלושה או ארבעה איברים.
• הנתונים חוצים גבול כמו סריאליזציה. השמות לא קיימים בזמן ריצה, כך ש-Newtonsoft.Json כותבת Item1 ו-Item2, ו-System.Text.Json כותבת {} כי איברי tuple הם שדות, שהיא מדלגת עליהם כברירת מחדל.

records של C# 9 נותנים את רוב הנוחות של tuple עם שם אמיתי. ל-record Score(string Name, int Points); יש שוויון ערכים, ToString קריא ופירוק מובנים. ראו records.

טעויות נפוצות

• ציפייה שהשמות ישרדו בזמן ריצה. reflection ו-serializers רואים Item1, Item2 (או בכלל כלום).
• שינוי של עותק. tuples הם structs: var t2 = t1; t2.Item1 = 5; משאיר את t1 ללא שינוי.
• tuples עם הרבה איברים. מעבר לשלושה או ארבעה, טיפוס עם שם קריא יותר.
• בלבול בסדר הפירוק. הוא לפי מיקום: עם tuple מסוג (Name, Age), var (age, name) = person; שם את השם ב-age, ומכיוון ש-var מסיק את הטיפוסים, שום דבר לא מזהיר אתכם.