الصفوف Tuple في C#: الصفوف المسمّاة وإعادة عدة قيم والتفكيك

يجمع الصف (tuple) عددًا صغيرًا ثابتًا من القيم في قيمة واحدة دون التصريح بصنف لها. ("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.

التفكيك

يفكّ التفكيك (deconstruction) الصف إلى متغيّرات منفصلة في عبارة واحدة:

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() بين الاثنين. فضّل value tuples في الشيفرة الجديدة: لا تحجز شيئًا في الكومة ويمكنها حمل الأسماء.

متى تستخدم صنفًا أو سجلًا بدلًا منها

الصفوف أفضل حين يكون التجميع محليًا وبديهيًا: دالة تعيد رقمين، أو استعلام 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 تستنتج الأنواع فلا شيء يحذّرك.