C# Reference ยท Collections
IDictionary and IReadOnlyDictionary
Reference for C# IDictionary<TKey,TValue> and IReadOnlyDictionary<TKey,TValue>: members, which classes implement them, TryGetValue and choosing a parameter type.
IDictionary<TKey,TValue> is the interface for "look up a value by key" collections. Dictionary, SortedDictionary, SortedList and ConcurrentDictionary all implement it (as does ExpandoObject). It extends ICollection<KeyValuePair<TKey,TValue>>, so you can also enumerate it as key-value pairs.
IReadOnlyDictionary<TKey,TValue> (.NET 4.5) is the read-only counterpart: lookups, Keys, Values, ContainsKey and TryGetValue, but no way to add or remove. Use it for parameters and return values that must not be modified through that reference.
IDictionary<string, int> ages = new Dictionary<string, int>(); ages["Ana"] = 31; ages.TryGetValue("Ana", out int age);
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.
Syntax
public interface IDictionary<TKey, TValue> : ICollection<KeyValuePair<TKey, TValue>> { TValue this[TKey key] { get; set; } ICollection<TKey> Keys { get; } ICollection<TValue> Values { get; } void Add(TKey key, TValue value); bool ContainsKey(TKey key); bool Remove(TKey key); bool TryGetValue(TKey key, out TValue value); } public interface IReadOnlyDictionary<TKey, TValue> : IReadOnlyCollection<KeyValuePair<TKey, TValue>> { TValue this[TKey key] { get; } IEnumerable<TKey> Keys { get; } IEnumerable<TValue> Values { get; } bool ContainsKey(TKey key); bool TryGetValue(TKey key, out TValue value); }
| Name | Description |
|---|---|
key |
The lookup key. null is not allowed for Dictionary. |
Keys, Values |
The keys and values, in the dictionary's own enumeration order. |
TryGetValue |
Looks up without throwing. When the key is missing, value is default. |
Returns: Remove(key) is true if something was removed. ContainsKey and TryGetValue return bool.
Errors: the indexer getter throws KeyNotFoundException; Add throws ArgumentException for a duplicate key; a null key throws ArgumentNullException. A dictionary created read-only throws NotSupportedException on writes.
Usage notes
- Indexer set versus
Add.d[k] = vadds or overwrites;d.Add(k, v)throws if the key exists. OnConcurrentDictionary, use the dedicated atomic methods instead. TryGetValuedoes one lookup.if (d.ContainsKey(k)) use(d[k])does two. PreferTryGetValue.- Interface versus class
Keys.IDictionary.Keysis anICollection<TKey>(withCount,Contains);IReadOnlyDictionary.Keysis only anIEnumerable<TKey>. ADictionaryhasKeysof its ownKeyCollectiontype, a live view with no copying. - Two interfaces, one class.
Dictionary<K,V>implements both, butIDictionary<K,V>does not inheritIReadOnlyDictionary<K,V>. A method that takesIReadOnlyDictionarytherefore cannot receive anIDictionaryvariable without a cast or copy, and some collections (likeImmutableDictionary) implement only the read-only one. - Order depends on the class.
Dictionaryhas no promised order;SortedDictionaryis sorted by key. Do not rely on insertion order. - Missing-key helpers.
GetValueOrDefault,TryAddandCollectionExtensionsmethods work on the interfaces (TryAddforIDictionary,GetValueOrDefaultfor both). See Dictionary operations. - Not thread-safe except
ConcurrentDictionary.