القاموس Dictionary في C#: Add وTryGetValue والمرور والفرز

يخزّن Dictionary<TKey, TValue> القيم تحت مفاتيح فريدة ويجد القيمة بمفتاحها في زمن ثابت تقريبًا، مهما كان عدد المدخلات. وهو مكافئ جدول التجزئة (hash map) في C#: دليل هاتف من الاسم إلى الرقم، أو ذاكرة مؤقتة من المعرّف إلى السجل، أو عدد لكل كلمة.

إنشاء قاموس وقراءة القيم

using System;
using System.Collections.Generic;

class Program
{
    static void Main()
    {
        var stock = new Dictionary<string, int>();
        stock["apples"] = 12;
        stock["pears"] = 0;

        var prices = new Dictionary<string, decimal>
        {
            ["coffee"] = 3.20m,
            ["tea"] = 2.50m,
        };

        var capitals = new Dictionary<string, string>
        {
            { "France", "Paris" },
            { "Peru", "Lima" },
        };

        Console.WriteLine(stock["apples"]);
        Console.WriteLine(prices["tea"]);
        Console.WriteLine(capitals.Count);
        Console.WriteLine(capitals.ContainsKey("Peru"));
        Console.WriteLine(capitals.ContainsValue("Rome"));
    }
}

المخرجات:

12
2.50
2
True
False

شكلا التهيئة يفعلان الشيء نفسه. يستخدم الشكل ["key"] = value (C# 6) المفهرس، فيستبدل المفتاح المكرّر؛ ويستدعي الشكل { key, value } الدالة Add، فيرمي المفتاح المكرّر استثناءً حين يُنفَّذ السطر.

ContainsKey بحث بالتجزئة وهي سريعة. أما ContainsValue فعليها المرور على كل مدخل، لأن القيم غير مفهرسة.

Add مقابل المفهرس مقابل TryAdd

هناك ثلاث طرق لإدخال مدخل، ولا تختلف إلا فيما يحدث حين يكون المفتاح موجودًا:

using System;
using System.Collections.Generic;

class Program
{
    static void Main()
    {
        var ages = new Dictionary<string, int>();

        ages.Add("Ana", 31);
        ages["Ben"] = 25;     // new key: inserted
        ages["Ben"] = 26;     // existing key: overwritten
        Console.WriteLine(ages["Ben"]);

        try
        {
            ages.Add("Ana", 40); // duplicate key
        }
        catch (ArgumentException e)
        {
            Console.WriteLine("Caught " + e.GetType().Name);
        }

        Console.WriteLine(ages.TryAdd("Chloe", 22)); // new: added
        Console.WriteLine(ages.TryAdd("Ana", 99));   // exists: not added
        Console.WriteLine(ages["Ana"]);
    }
}

المخرجات:

26
Caught ArgumentException
True
False
31

رمي Add لاستثناء عند التكرار ميزة: يكشف البيانات التي كان يجب أن تكون فريدة ولم تكن. استخدم المفهرس حين تقصد "أدرج أو حدّث"، وTryAdd (.NET Core 2.0 وما بعده) حين يجب أن تفوز القيمة الأولى.

لا يمكن أن تكون المفاتيح null. ترمي Add(null, ...) أو dict[null] استثناء ArgumentNullException. ويمكن أن تكون القيم null حين يسمح نوع القيمة بذلك.

KeyNotFoundException وTryGetValue

قراءة مفتاح غير موجود بالمفهرس ترمي KeyNotFoundException. هذا أشيع خطأ في القواميس، والإصلاح دائمًا تقريبًا TryGetValue.

using System;
using System.Collections.Generic;

class Program
{
    static void Main()
    {
        var emails = new Dictionary<int, string>
        {
            [101] = "ana@example.com",
            [102] = "ben@example.com",
        };

        try
        {
            Console.WriteLine(emails[999]);
        }
        catch (KeyNotFoundException e)
        {
            Console.WriteLine("Caught " + e.GetType().Name);
        }

        if (emails.TryGetValue(101, out string email))
        {
            Console.WriteLine("Found " + email);
        }

        if (!emails.TryGetValue(999, out string none))
        {
            Console.WriteLine("Missing, value is null: " + (none == null));
        }

        string fallback = emails.TryGetValue(103, out var e3) ? e3 : "no email";
        Console.WriteLine(fallback);
    }
}

المخرجات:

Caught KeyNotFoundException
Found ana@example.com
Missing, value is null: True
no email

تجري TryGetValue بحثًا واحدًا بالتجزئة وتبلّغ عن النجاح كقيمة bool. النمط if (dict.ContainsKey(k)) { var v = dict[k]; } يعمل لكنه يبحث عن المفتاح مرتين. وحين يكون المفتاح غائبًا يحصل متغيّر out على القيمة الافتراضية للنوع (null و0 وfalse).

في .NET Core 2.0 وما بعده توجد أيضًا GetValueOrDefault(key, fallback)، التي تعيد القيمة البديلة حين يكون المفتاح غائبًا: emails.GetValueOrDefault(103, "no email").

تحديث المدخلات وحذفها

using System;
using System.Collections.Generic;

class Program
{
    static void Main()
    {
        var cart = new Dictionary<string, int> { ["milk"] = 1, ["eggs"] = 6 };

        cart["milk"] += 1;                     // read, add, write back
        Console.WriteLine(cart["milk"]);

        Console.WriteLine(cart.Remove("eggs")); // true: removed
        Console.WriteLine(cart.Remove("rice")); // false: was not there
        Console.WriteLine(cart.Count);

        cart.Clear();
        Console.WriteLine(cart.Count);
    }
}

المخرجات:

2
True
False
1
0

ترمي cart["milk"] += 1 استثناء KeyNotFoundException إن لم يكن milk في القاموس بعد، لأنها تقرأ قبل أن تكتب. وتعيد Remove القيمة false بدل رمي استثناء لمفتاح غائب، فلا حاجة لفحص ContainsKey أولًا.

المرور: KeyValuePair وKeys وValues

ينتج foreach على قاموس عناصر KeyValuePair<TKey, TValue>، لكل منها Key وValue.

using System;
using System.Collections.Generic;

class Program
{
    static void Main()
    {
        var scores = new Dictionary<string, int>
        {
            ["Ana"] = 88,
            ["Ben"] = 72,
            ["Chloe"] = 95,
        };

        foreach (KeyValuePair<string, int> pair in scores)
        {
            Console.WriteLine(pair.Key + ": " + pair.Value);
        }

        foreach (string name in scores.Keys)
        {
            Console.Write(name + " ");
        }
        Console.WriteLine();

        int total = 0;
        foreach (int s in scores.Values) total += s;
        Console.WriteLine("Total " + total);

        // Change values: loop over a copy of the keys.
        foreach (string name in new List<string>(scores.Keys))
        {
            scores[name] += 5;
        }
        Console.WriteLine(scores["Ben"]);
    }
}

المخرجات:

Ana: 88
Ben: 72
Chloe: 95
Ana Ben Chloe 
Total 255
77

pair.Value للقراءة فقط، فتحديث القيم يعني الكتابة عبر المفهرس. تمرّ الحلقة الأخيرة على نسخة List<string> من المفاتيح، وهذا آمن دائمًا؛ أما المرور على scores.Keys مباشرة مع استبدال قيم موجودة فمسموح في .NET Core 3.0 وما بعده لكنه يرمي InvalidOperationException في .NET Framework.

إضافة مفتاح جديد داخل foreach على القاموس نفسه ترمي InvalidOperationException في كل إصدار. والحذف أثناء التعداد يرمي في .NET Framework ومسموح منذ .NET Core 3.0. والشيفرة التي يجب أن تعمل في كل مكان تجمع المفاتيح المراد حذفها أولًا، ثم تحذفها بعد الحلقة.

مع C# 7 و.NET Core 2.0 أو أحدث يمكن تفكيك KeyValuePair في ترويسة الحلقة:

foreach (var (name, score) in scores)
{
    Console.WriteLine($"{name}: {score}");
}

العدّ بقاموس

عدّ التكرارات هو الاستخدام النموذجي. اقرأ العدد الحالي بـ TryGetValue (المفتاح الغائب يعطي 0)، ثم اكتب النتيجة.

using System;
using System.Collections.Generic;

class Program
{
    static void Main()
    {
        string text = "the cat and the dog and the bird";
        var counts = new Dictionary<string, int>();

        foreach (string word in text.Split(' '))
        {
            counts.TryGetValue(word, out int n); // n is 0 when missing
            counts[word] = n + 1;
        }

        foreach (var pair in counts)
        {
            Console.WriteLine(pair.Key + " " + pair.Value);
        }
    }
}

المخرجات:

the 3
cat 1
and 2
dog 1
bird 1

الشكل نفسه يجمّع العناصر: Dictionary<string, List<Order>>، حيث تجلب القائمة بـ TryGetValue، وتنشئ واحدة وتخزّنها إن غابت، ثم تضيف إليها بـ Add. وللعدّ والتجميع لمرة واحدة يفعل LINQ ذلك في تعبير واحد: words.GroupBy(w => w).ToDictionary(g => g.Key, g => g.Count()). راجع LINQ.

مفاتيح غير حساسة لحالة الأحرف بأداة مقارنة

تُقارن مفاتيح النصوص بدقة افتراضيًا: "Apple" و"apple" مفتاحان. مرّر IEqualityComparer<string> إلى المُنشئ لتغيير ذلك.

using System;
using System.Collections.Generic;

class Program
{
    static void Main()
    {
        var exact = new Dictionary<string, int>();
        exact["Apple"] = 1;
        Console.WriteLine(exact.ContainsKey("apple"));

        var headers = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
        headers["Content-Type"] = "text/html";
        Console.WriteLine(headers["content-type"]);
        headers["CONTENT-TYPE"] = "application/json"; // same key: overwrites
        Console.WriteLine(headers.Count);
    }
}

المخرجات:

False
text/html
1

StringComparer.OrdinalIgnoreCase هي الخيار الصحيح للمعرّفات مثل ترويسات HTTP وامتدادات الملفات وأسماء المستخدمين. استدعاء .ToLower() على كل مفتاح قبل تخزينه يعمل أيضًا، لكن يسهل نسيانه في مكان ما.

في مفاتيح من صنفك يستدعي القاموس GetHashCode وEquals للمفتاح. الصنف الذي لا يتجاوزهما يقارن بالمرجع، فيكون كائنان منفصلان بالحقول نفسها مفتاحين مختلفين. راجع HashSet لطريقة كتابة هذا الزوج.

الترتيب والفرز وSortedDictionary

لا يعد Dictionary بأي ترتيب تعداد. عمليًا يُعدَّد القاموس الذي لم تُضف إليه إلا مدخلات بترتيب الإدراج، لكن بعد Remove قد تعيد Add لاحقة استخدام الخانة المحرّرة وتظهر مبكرًا. يجب ألا تعتمد الشيفرة على ذلك أبدًا.

حين تحتاج إلى ترتيب، رتّب في موضع الاستخدام أو استخدم مجموعة مرتّبة:

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

class Program
{
    static void Main()
    {
        var sales = new Dictionary<string, int>
        {
            ["Lima"] = 340,
            ["Oslo"] = 520,
            ["Cairo"] = 210,
        };

        foreach (var pair in sales.OrderBy(p => p.Key))
            Console.WriteLine(pair.Key + " " + pair.Value);

        Console.WriteLine("By value, highest first:");
        foreach (var pair in sales.OrderByDescending(p => p.Value))
            Console.WriteLine(pair.Key + " " + pair.Value);

        var sorted = new SortedDictionary<string, int>(sales);
        sorted["Berlin"] = 90;
        Console.WriteLine(string.Join(", ", sorted.Keys));
    }
}

المخرجات:

Cairo 210
Lima 340
Oslo 520
By value, highest first:
Oslo 520
Lima 340
Cairo 210
Berlin, Cairo, Lima, Oslo

يبقي SortedDictionary<TKey, TValue> مفاتيحه مرتّبة دائمًا (هو شجرة متوازنة)، فيكون البحث والإدراج O(log n) بدل O(1). استخدمه حين تعدّد بترتيب المفاتيح كثيرًا؛ ورتّب قاموسًا عاديًا بـ LINQ حين لا تحتاج إلى الترتيب إلا مرة. وSortedList<TKey, TValue> خيار ثالث يستخدم ذاكرة أقل لكن الإدراج فيه بطيء حين يكبر.

مرجع سريع

أخطاء شائعة

• قراءة مفتاح غائب بـ d[k]. يرمي KeyNotFoundException؛ استخدم TryGetValue.
• استدعاء Add لمفتاح قد يكون موجودًا. يرمي ArgumentException؛ استخدم المفهرس أو TryAdd.
• إضافة مفاتيح داخل foreach على القاموس. يرمي InvalidOperationException؛ اجمع التغييرات وطبّقها بعدها.
• الاعتماد على ترتيب التعداد. رتّب، أو استخدم SortedDictionary.
• تغيير حقول كائن المفتاح بعد إدراجه. يتغيّر رمز التجزئة ولا يعود العثور على المدخل ممكنًا.
• ContainsKey ثم المفهرس. بحثان؛ وTryGetValue تجري بحثًا واحدًا.