Исполняемые доки C#: Dictionary

Q: Чем Dictionary.Add отличается от индексатора в C#?

dict.Add(key, value) вставляет новый элемент и выбрасывает ArgumentException, если ключ уже существует. dict[key] = value вставляет элемент, если ключ новый, и перезаписывает значение, если он существует, и никогда не выбрасывает исключение из-за дубликата. TryAdd(key, value) вставляет, только когда ключ новый, и иначе возвращает false.

Q: Как работает TryGetValue в C#?

dict.TryGetValue(key, out var value) возвращает true и задаёт value, когда ключ существует, и возвращает false, задавая value значением по умолчанию для его типа, когда ключа нет. Он делает один поиск, тогда как ContainsKey с последующим dict[key] делают два, и никогда не выбрасывает KeyNotFoundException.

Q: Как перебрать Dictionary в C#?

foreach (KeyValuePair pair in dict) даёт каждый элемент с pair.Key и pair.Value. Чтобы перебрать только ключи или только значения, используйте dict.Keys или dict.Values. Не добавляйте ключи в словарь внутри такого цикла: это выбрасывает InvalidOperationException.

Q: Как сделать ключи Dictionary нечувствительными к регистру?

Передайте компаратор в конструктор: new Dictionary (StringComparer.OrdinalIgnoreCase). Тогда "Apple" и "apple" будут одним ключом для поиска, Add и ContainsKey. Компаратор фиксируется при создании словаря.

Q: Что такое KeyValuePair в C#?

KeyValuePair это структура, которую словарь выдаёт для каждого элемента при переборе. У неё свойства Key и Value только для чтения, поэтому изменить элемент через неё нельзя; пишите dict[pair.Key] = newValue (после цикла или перебирая копию ключей).

Dictionary<TKey, TValue> хранит значения под уникальными ключами и находит значение по ключу примерно за постоянное время, сколько бы ни было элементов. Это аналог хеш-таблицы в 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>, который занимает меньше памяти, но медленно вставляет, когда становится большим.

Краткая справка

Задача	Код
Создать	`new Dictionary<string, int>()`
Вставить или перезаписать	`d[k] = v`
Вставить, исключение при дубликате	`d.Add(k, v)`
Вставить, только если ключ новый	`d.TryAdd(k, v)`
Прочитать, исключение при отсутствии	`d[k]`
Безопасно прочитать	`d.TryGetValue(k, out var v)`
Ключ существует	`d.ContainsKey(k)`
Удалить	`d.Remove(k)` (возвращает `bool`)
Размер	`d.Count`
Ключи, значения	`d.Keys`, `d.Values`
Отсортировать по ключу	`d.OrderBy(p => p.Key)` или `SortedDictionary`
Без учёта регистра	`new Dictionary<string, T>(StringComparer.OrdinalIgnoreCase)`

Частые ошибки

Чтение отсутствующего ключа через d[k]. Выбрасывает KeyNotFoundException; используйте TryGetValue.
Вызов Add для ключа, который может существовать. Выбрасывает ArgumentException; используйте индексатор или TryAdd.
Добавление ключей внутри foreach по словарю. Выбрасывает InvalidOperationException; собирайте изменения и применяйте их после цикла.
Опора на порядок перебора. Сортируйте или используйте SortedDictionary.
Изменение полей объекта-ключа после вставки. Его хеш-код меняется, и элемент больше нельзя найти.
ContainsKey, а затем индексатор. Два поиска; TryGetValue делает один.

Часто задаваемые вопросы

Чем Dictionary.Add отличается от индексатора в C#?

dict.Add(key, value) вставляет новый элемент и выбрасывает ArgumentException, если ключ уже существует. dict[key] = value вставляет элемент, если ключ новый, и перезаписывает значение, если он существует, и никогда не выбрасывает исключение из-за дубликата. TryAdd(key, value) вставляет, только когда ключ новый, и иначе возвращает false.

Как работает TryGetValue в C#?

dict.TryGetValue(key, out var value) возвращает true и задаёт value, когда ключ существует, и возвращает false, задавая value значением по умолчанию для его типа, когда ключа нет. Он делает один поиск, тогда как ContainsKey с последующим dict[key] делают два, и никогда не выбрасывает KeyNotFoundException.

Как перебрать Dictionary в C#?

foreach (KeyValuePair<string, int> pair in dict) даёт каждый элемент с pair.Key и pair.Value. Чтобы перебрать только ключи или только значения, используйте dict.Keys или dict.Values. Не добавляйте ключи в словарь внутри такого цикла: это выбрасывает InvalidOperationException.

Упорядочен ли Dictionary в C#?

Никакой порядок не гарантируется. Словарь, в который только добавляли элементы, обычно перебирается в порядке вставки, но после Remove новые элементы могут занять освободившуюся ячейку, и порядок меняется. Когда нужен порядок, сортируйте: dict.OrderBy(p => p.Key) или используйте SortedDictionary<TKey, TValue>, который всегда перебирается по ключу.

Как сделать ключи Dictionary нечувствительными к регистру?

Передайте компаратор в конструктор: new Dictionary<string, int>(StringComparer.OrdinalIgnoreCase). Тогда "Apple" и "apple" будут одним ключом для поиска, Add и ContainsKey. Компаратор фиксируется при создании словаря.

Что такое KeyValuePair в C#?

KeyValuePair<TKey, TValue> это структура, которую словарь выдаёт для каждого элемента при переборе. У неё свойства Key и Value только для чтения, поэтому изменить элемент через неё нельзя; пишите dict[pair.Key] = newValue (после цикла или перебирая копию ключей).

Связанные концепции