Ausführbare C#-Docs: Dictionary

Q: Was ist der Unterschied zwischen Dictionary.Add und dem Indexer in C#?

dict.Add(key, value) fügt einen neuen Eintrag ein und wirft ArgumentException, wenn der Schlüssel schon existiert. dict[key] = value fügt den Eintrag ein, wenn der Schlüssel neu ist, überschreibt den Wert, wenn er existiert, und wirft bei einem Duplikat nie. TryAdd(key, value) fügt nur ein, wenn der Schlüssel neu ist, und gibt sonst false zurück.

Q: Wie funktioniert TryGetValue in C#?

dict.TryGetValue(key, out var value) gibt true zurück und setzt value, wenn der Schlüssel existiert, und gibt false zurück und setzt value auf den Standardwert seines Typs, wenn nicht. Es macht ein Nachschlagen, wo ContainsKey gefolgt von dict[key] zwei macht, und wirft nie KeyNotFoundException.

Q: Wie durchlaufe ich in C# ein Dictionary?

foreach (KeyValuePair pair in dict) liefert jeden Eintrag mit pair.Key und pair.Value. Um nur Schlüssel oder nur Werte zu durchlaufen, nimm dict.Keys oder dict.Values. Füge in dieser Schleife keine Schlüssel zum Dictionary hinzu: Das wirft InvalidOperationException.

Q: Wie mache ich Dictionary-Schlüssel unabhängig von Groß- und Kleinschreibung?

Übergib dem Konstruktor einen Comparer: new Dictionary (StringComparer.OrdinalIgnoreCase). Dann sind "Apple" und "apple" für Nachschlagen, Add und ContainsKey derselbe Schlüssel. Der Comparer wird beim Erzeugen des Dictionarys festgelegt.

Q: Was ist ein KeyValuePair in C#?

KeyValuePair ist das Struct, das dir ein Dictionary beim Durchlaufen für jeden Eintrag gibt. Es hat schreibgeschützte Properties Key und Value, du kannst einen Eintrag darüber also nicht ändern; schreibe stattdessen dict[pair.Key] = newValue (nach der Schleife oder über eine Kopie der Schlüssel).

Dictionary<TKey, TValue> speichert Werte unter eindeutigen Schlüsseln und findet einen Wert über seinen Schlüssel in ungefähr konstanter Zeit, egal wie viele Einträge es gibt. Es ist das C#-Gegenstück zu einer Hash Map: ein Telefonbuch von Name zu Nummer, ein Cache von ID zu Datensatz, ein Zähler pro Wort.

Ein Dictionary erzeugen und Werte lesen

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

Ausgabe:

12
2.50
2
True
False

Beide Initialisiererformen tun dasselbe. Die Form ["key"] = value (C# 6) verwendet den Indexer, ein wiederholter Schlüssel überschreibt also; die Form { key, value } ruft Add auf, ein wiederholter Schlüssel wirft also, wenn die Zeile läuft.

ContainsKey ist ein Hash-Nachschlagen und schnell. ContainsValue muss jeden Eintrag durchsuchen, weil Werte nicht indiziert sind.

Add gegenüber Indexer gegenüber TryAdd

Es gibt drei Wege, einen Eintrag einzufügen, und sie unterscheiden sich nur darin, was passiert, wenn der Schlüssel schon existiert:

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

Ausgabe:

26
Caught ArgumentException
True
False
31

Dass Add bei einem Duplikat wirft, ist ein Feature: Es bringt Daten ans Licht, die eindeutig sein sollten, es aber nicht waren. Nimm den Indexer, wenn du „einfügen oder aktualisieren“ meinst, und TryAdd (ab .NET Core 2.0), wenn der erste Wert gewinnen soll.

Schlüssel können nicht null sein. Add(null, ...) oder dict[null] wirft ArgumentNullException. Werte können null sein, wenn der Werttyp es erlaubt.

KeyNotFoundException und TryGetValue

Einen nicht vorhandenen Schlüssel mit dem Indexer zu lesen wirft KeyNotFoundException. Das ist der häufigste Dictionary-Fehler, und die Lösung ist fast immer 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);
    }
}

Ausgabe:

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

TryGetValue macht ein einziges Hash-Nachschlagen und meldet den Erfolg als bool. Das Muster if (dict.ContainsKey(k)) { var v = dict[k]; } funktioniert, schlägt den Schlüssel aber zweimal nach. Fehlt der Schlüssel, bekommt die out-Variable den Standardwert des Typs (null, 0, false).

Ab .NET Core 2.0 gibt es außerdem GetValueOrDefault(key, fallback), das den Ersatzwert zurückgibt, wenn der Schlüssel fehlt: emails.GetValueOrDefault(103, "no email").

Einträge aktualisieren und entfernen

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

Ausgabe:

2
True
False
1
0

cart["milk"] += 1 wirft KeyNotFoundException, wenn milk noch nicht im Dictionary ist, weil es liest, bevor es schreibt. Remove gibt bei einem fehlenden Schlüssel false zurück, statt zu werfen, eine vorherige Prüfung mit ContainsKey ist also nicht nötig.

Durchlaufen: KeyValuePair, Keys und Values

Ein foreach über ein Dictionary liefert KeyValuePair<TKey, TValue>-Elemente, jedes mit einem Key und einem 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"]);
    }
}

Ausgabe:

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

pair.Value ist schreibgeschützt, Werte werden also über den Indexer aktualisiert. Die letzte Schleife durchläuft eine List<string>-Kopie der Schlüssel, was immer sicher ist; scores.Keys direkt zu durchlaufen und dabei bestehende Werte zu überschreiben ist ab .NET Core 3.0 erlaubt, wirft aber unter .NET Framework InvalidOperationException.

Einen neuen Schlüssel in einem foreach über dasselbe Dictionary hinzuzufügen wirft in jeder Version InvalidOperationException. Entfernen während des Durchlaufens wirft unter .NET Framework und ist ab .NET Core 3.0 erlaubt. Code, der überall laufen muss, sammelt die zu entfernenden Schlüssel zuerst und entfernt sie nach der Schleife.

Mit C# 7 und .NET Core 2.0 oder neuer lässt sich KeyValuePair im Schleifenkopf dekonstruieren:

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

Mit einem Dictionary zählen

Vorkommen zu zählen ist der Lehrbuchfall. Lies den aktuellen Zählerstand mit TryGetValue (ein fehlender Schlüssel ergibt 0) und schreibe dann zurück.

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

Ausgabe:

the 3
cat 1
and 2
dog 1
bird 1

Dieselbe Form gruppiert Elemente: Dictionary<string, List<Order>>, bei dem du die Liste mit TryGetValue holst, eine erzeugst und speicherst, wenn sie fehlt, und dann mit Add hinzufügst. Für einmaliges Zählen und Gruppieren erledigt LINQ das in einem Ausdruck: words.GroupBy(w => w).ToDictionary(g => g.Key, g => g.Count()). Siehe LINQ.

Schlüssel ohne Groß- und Kleinschreibung mit einem Comparer

String-Schlüssel werden standardmäßig exakt verglichen: "Apple" und "apple" sind zwei Schlüssel. Übergib dem Konstruktor einen IEqualityComparer<string>, um das zu ändern.

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

Ausgabe:

False
text/html
1

StringComparer.OrdinalIgnoreCase ist die richtige Wahl für Bezeichner wie HTTP-Header, Dateiendungen und Benutzernamen. Vor dem Speichern .ToLower() auf jeden Schlüssel anzuwenden funktioniert auch, wird aber leicht an einer Stelle vergessen.

Bei Schlüsseln deiner eigenen Klasse ruft das Dictionary GetHashCode und Equals des Schlüssels auf. Eine Klasse, die sie nicht überschreibt, vergleicht per Referenz, zwei separate Objekte mit denselben Feldern sind also verschiedene Schlüssel. Wie du dieses Paar schreibst, steht unter HashSet.

Reihenfolge, Sortieren und SortedDictionary

Ein Dictionary gibt kein Versprechen über die Reihenfolge beim Durchlaufen. In der Praxis durchläuft ein Dictionary, dem nur Einträge hinzugefügt wurden, in Einfügereihenfolge, aber nach einem Remove kann ein späteres Add den freien Platz wiederverwenden und früher erscheinen. Code sollte sich nie darauf verlassen.

Wenn du eine Reihenfolge brauchst, sortiere an der Stelle, wo du sie brauchst, oder nimm eine sortierte Collection:

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

Ausgabe:

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

SortedDictionary<TKey, TValue> hält seine Schlüssel jederzeit sortiert (es ist ein balancierter Baum), Nachschlagen und Einfügen kosten also O(log n) statt O(1). Nimm es, wenn du oft in Schlüsselreihenfolge durchläufst; sortiere ein normales Dictionary mit LINQ, wenn du die Reihenfolge nur einmal brauchst. SortedList<TKey, TValue> ist eine dritte Option, die weniger Speicher braucht, aber bei großer Größe langsam beim Einfügen ist.

Kurzübersicht

Aufgabe	Code
Erzeugen	`new Dictionary<string, int>()`
Einfügen oder überschreiben	`d[k] = v`
Einfügen, bei Duplikat werfen	`d.Add(k, v)`
Nur einfügen, wenn neu	`d.TryAdd(k, v)`
Lesen, werfen wenn fehlend	`d[k]`
Sicher lesen	`d.TryGetValue(k, out var v)`
Schlüssel existiert	`d.ContainsKey(k)`
Entfernen	`d.Remove(k)` (gibt `bool` zurück)
Größe	`d.Count`
Schlüssel, Werte	`d.Keys`, `d.Values`
Nach Schlüssel sortiert	`d.OrderBy(p => p.Key)` oder `SortedDictionary`
Schreibweise ignorieren	`new Dictionary<string, T>(StringComparer.OrdinalIgnoreCase)`

Häufige Fehler

Einen fehlenden Schlüssel mit d[k] lesen. Wirft KeyNotFoundException; nimm TryGetValue.
Add für einen Schlüssel aufrufen, der existieren könnte. Wirft ArgumentException; nimm den Indexer oder TryAdd.
In foreach über das Dictionary Schlüssel hinzufügen. Wirft InvalidOperationException; sammle Änderungen und wende sie danach an.
Sich auf die Reihenfolge beim Durchlaufen verlassen. Sortiere oder nimm SortedDictionary.
Felder eines Schlüsselobjekts nach dem Einfügen ändern. Sein Hashcode ändert sich, und der Eintrag lässt sich nicht mehr finden.
ContainsKey und dann Indexer. Zwei Nachschlagevorgänge; TryGetValue macht einen.

Häufig gestellte Fragen

Was ist der Unterschied zwischen Dictionary.Add und dem Indexer in C#?

dict.Add(key, value) fügt einen neuen Eintrag ein und wirft ArgumentException, wenn der Schlüssel schon existiert. dict[key] = value fügt den Eintrag ein, wenn der Schlüssel neu ist, überschreibt den Wert, wenn er existiert, und wirft bei einem Duplikat nie. TryAdd(key, value) fügt nur ein, wenn der Schlüssel neu ist, und gibt sonst false zurück.

Wie funktioniert TryGetValue in C#?

dict.TryGetValue(key, out var value) gibt true zurück und setzt value, wenn der Schlüssel existiert, und gibt false zurück und setzt value auf den Standardwert seines Typs, wenn nicht. Es macht ein Nachschlagen, wo ContainsKey gefolgt von dict[key] zwei macht, und wirft nie KeyNotFoundException.

Wie durchlaufe ich in C# ein Dictionary?

foreach (KeyValuePair<string, int> pair in dict) liefert jeden Eintrag mit pair.Key und pair.Value. Um nur Schlüssel oder nur Werte zu durchlaufen, nimm dict.Keys oder dict.Values. Füge in dieser Schleife keine Schlüssel zum Dictionary hinzu: Das wirft InvalidOperationException.

Ist ein C#-Dictionary geordnet?

Es wird keine Reihenfolge garantiert. Ein Dictionary, dem nur Einträge hinzugefügt wurden, durchläuft meist in Einfügereihenfolge, aber nach einem Remove können neue Einträge den freien Platz füllen, und die Reihenfolge ändert sich. Sortiere, wenn du eine Reihenfolge brauchst: dict.OrderBy(p => p.Key), oder nimm SortedDictionary<TKey, TValue>, das immer nach Schlüssel durchläuft.

Wie mache ich Dictionary-Schlüssel unabhängig von Groß- und Kleinschreibung?

Übergib dem Konstruktor einen Comparer: new Dictionary<string, int>(StringComparer.OrdinalIgnoreCase). Dann sind "Apple" und "apple" für Nachschlagen, Add und ContainsKey derselbe Schlüssel. Der Comparer wird beim Erzeugen des Dictionarys festgelegt.

Was ist ein KeyValuePair in C#?

KeyValuePair<TKey, TValue> ist das Struct, das dir ein Dictionary beim Durchlaufen für jeden Eintrag gibt. Es hat schreibgeschützte Properties Key und Value, du kannst einen Eintrag darüber also nicht ändern; schreibe stattdessen dict[pair.Key] = newValue (nach der Schleife oder über eine Kopie der Schlüssel).

Verwandte Konzepte