{"id":283,"date":"2014-06-20T14:30:00","date_gmt":"2014-06-20T14:30:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/dotnet\/2014\/06\/20\/would-you-like-a-multidictionary\/"},"modified":"2021-09-30T16:48:53","modified_gmt":"2021-09-30T23:48:53","slug":"would-you-like-a-multidictionary","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/dotnet\/would-you-like-a-multidictionary\/","title":{"rendered":"Would you like a MultiDictionary?"},"content":{"rendered":"

We’ve recently shipped new collection types on NuGet with our Immutable Collections package. NuGet allows us to ship prerelease and experimental versions of libraries to gather feedback from the community. In this post, our software developer intern Ian Hays<\/strong> will talk about his intern project: an experimental NuGet package containing advanced collection types. — Immo<\/em><\/p>\n

Dictionary provides a mapping between a key and a single value, and is one of the most used collection types in the .NET Framework. Programs often need a mapping between one key and multiple values. While the functionality can be composed using existing collection types, it can be error prone due to corner cases.<\/p>\n

Today we’re releasing an experimental NuGet package<\/a> with a new related type, MultiDictionary<\/code>. The MultiDictionary<\/code> is a simple, intuitive collection that essentially functions like a Dictionary<TKey, ICollection<TValue>><\/code> but abstracts the ICollection<TValue><\/code>. A more precise definition is that it is a Dictionary<TKey, TValue><\/code> that allows multiple TValues<\/code> to be added for any TKey<\/code> (i.e. keys don’t have to be unique).<\/p>\n

What’s wrong with Dictionary?<\/h2>\n

The .NET Framework already includes an efficient dictionary implementation that can be used with an ICollection<\/code> as the value type parameter, so why bother making MultiDictionary<\/code> at all? The short answer is simplicity. The long answer is also simplicity.<\/p>\n

What’s your favorite data structure? Mine is the dictionary; I love the near constant time operations, the huge number of use cases, the cleanliness! Although the dictionary has a wide variety of uses, there are times when I want to add multiple values per key and Dictionary just doesn’t quite cut it. In those situations the solution is simple: just build a Dictionary<TKey, List<TValue>><\/code>!<\/p>\n

The issue with the dictionary of list is nearly every call to the Dictionary<\/code> has to be wrapped in logic to check the current state of the dictionary before adding\/removing\/indexing etc. I’m never satisfied with the idea of surrounding my dictionary calls with a series of if<\/code> statements, so I end up coding an entirely new data structure to wrap my dictionary of lists. I’ve had to do this more times than I’m proud of, which is why I’m pleased to code up that data structure just one last time<\/em>.<\/p>\n

Introducing MultiDictionary<\/h2>\n

I could go into detail on the API and characteristics of MultiDictionary<\/code>, but I’ll save that for later; let’s first look at some examples of typical usage for MultiDictionary<\/code>.<\/p>\n

MultiDictionary<string, int> myDictionary = new MultiDictionary<string, int>();
myDictionary.Add(\"key\", 1);
myDictionary.Add(\"key\", 2);
myDictionary.Add(\"key\", 3);
\/\/myDictionary[\"key\"] now contains the values 1, 2, and 3<\/code><\/pre>\n
When we index into our myDictionary<\/code>, we get an ICollection<int><\/code> that contains the elements 1, 2, and 3. If the key wasn’t in the MultiDictionary<\/code>, then an empty ICollection<\/code> associated with that key will be returned.<\/p>\n
All ICollection<\/code> instances returned by indexing into the MultiDictionary<\/code> function as indirections to the collections inside of our MultiDictionary<\/code>, which means that as the MultiDictionary<\/code> changes so does the ICollection<\/code> and vice versa. Consider the following example that illustrates this:<\/p>\n
MultiDictionary<string, int> myDictionary = new MultiDictionary<string, int>();
myDictionary.Add(\"key\", 1);
ICollection<int> myCollection = myDictionary[\"key\"];
myCollection.Add(2);
\/\/myCollection now contains the values 1, and 2<\/code><\/pre>\n
The MultiDictionary<\/code> also has methods for adding or removing one key-value pair at a time as well as adding or removing multiple values per key.<\/p>\n
MultiDictionary<string, int> myDictionary = new MultiDictionary<string, int>();
myDictionary.AddRange(\"key1\", new int[] { 1, 2, 3 });
myDictionary.AddRange(\"key2\", new int[] { 1, 2, 3 });
myDictionary.Remove(\"key1\");
myDictionary.RemoveItem(\"key2\", 2);
\/\/myDictionary now contains key2 with values 1 and 3<\/code><\/pre>\n
There are a few more interesting and useful methods inside of the MultiDictionary<\/code>, but I’ll let you explore those on your own!<\/p>\n
Why should I use MultiDictionary?<\/h2>\n
Let’s look at some benefits of the MultiDictionary<\/code>:<\/p>\n