Why doesn't Dictionary have AddRange?

Question

Title is basic enough, why can't I:

Dictionary<string, string> dic = new Dictionary<string, string>();
dic.AddRange(MethodThatReturnAnotherDic());

Answer 1

A comment to the original question sums this up pretty well:

because no one ever designed, specified, implemented, tested, documented and shipped that feature. - @Gabe Moothart

As to why? Well, likely because the behavior of merging dictionaries can't be reasoned about in a manner that fits with the Framework guidelines.

AddRange doesn't exist because a range doesn't have any meaning to an associative container, as the range of data allows for duplicate entries. E.g if you had an IEnumerable<KeyValuePair<K,T>> that collection does not guard against duplicate entries.

The behavior of adding a collection of key-value pairs, or even merging two dictionaries is straight-forward. The behavior of how to deal with multiple duplicate entries, however, is not.

What should be the behavior of the method when it deals with a duplicate?

There are at least three solutions I can think of:

1. throw an exception for the first entry that is a duplicate
2. throw an exception that contains all the duplicate entries
3. Ignore duplicates

When an exception is thrown, what should be the state of the original dictionary?

Add is almost always implemented as an atomic operation: it succeeds and updates the state of the collection, or it fails, and the state of the collection is left unchanged. As AddRange can fail due to duplicate errors, the way to keep its behavior consistent with Add would be to also make it atomic by throwing an exception on any duplicate, and leave the state of the original dictionary as unchanged.

As an API consumer, it would be tedious to have to iteratively remove duplicate elements, which implies that the AddRange should throw a single exception that contains all the duplicate values.

The choice then boils down to:

1. Throw an exception with all duplicates, leaving the original dictionary alone.
2. Ignore duplicates and proceed.

There are arguments for supporting both use cases. To do that, do you add a IgnoreDuplicates flag to the signature?

The IgnoreDuplicates flag (when set to true) would also provide a significant speed up, as the underlying implementation would bypass the code for duplicate checking.

So now, you have a flag that allows the AddRange to support both cases, but has an undocumented side effect (which is something that the Framework designers worked really hard to avoid).

Summary

As there is no clear, consistent and expected behavior when it comes to dealing with duplicates, it's easier to not deal with them all together, and not provide the method to begin with.

If you find yourself continually having to merge dictionaries, you can of course write your own extension method to merge dictionaries, which will behave in a manner that works for your application(s).

Answer 2

I've got some solution:

Dictionary<string, string> mainDic = new Dictionary<string, string>() { 
    { "Key1", "Value1" },
    { "Key2", "Value2.1" },
};
Dictionary<string, string> additionalDic= new Dictionary<string, string>() { 
    { "Key2", "Value2.2" },
    { "Key3", "Value3" },
};
mainDic.AddRangeOverride(additionalDic); // Overrides all existing keys
// or
mainDic.AddRangeNewOnly(additionalDic); // Adds new keys only
// or
mainDic.AddRange(additionalDic); // Throws an error if keys already exist
// or
if (!mainDic.ContainsKeys(additionalDic.Keys)) // Checks if keys don't exist
{
    mainDic.AddRange(additionalDic);
}

...

namespace MyProject.Helper
{
  public static class CollectionHelper
  {
    public static void AddRangeOverride<TKey, TValue>(this IDictionary<TKey, TValue> dic, IDictionary<TKey, TValue> dicToAdd)
    {
        dicToAdd.ForEach(x => dic[x.Key] = x.Value);
    }

    public static void AddRangeNewOnly<TKey, TValue>(this IDictionary<TKey, TValue> dic, IDictionary<TKey, TValue> dicToAdd)
    {
        dicToAdd.ForEach(x => { if (!dic.ContainsKey(x.Key)) dic.Add(x.Key, x.Value); });
    }

    public static void AddRange<TKey, TValue>(this IDictionary<TKey, TValue> dic, IDictionary<TKey, TValue> dicToAdd)
    {
        dicToAdd.ForEach(x => dic.Add(x.Key, x.Value));
    }

    public static bool ContainsKeys<TKey, TValue>(this IDictionary<TKey, TValue> dic, IEnumerable<TKey> keys)
    {
        bool result = false;
        keys.ForEachOrBreak((x) => { result = dic.ContainsKey(x); return result; });
        return result;
    }

    public static void ForEach<T>(this IEnumerable<T> source, Action<T> action)
    {
        foreach (var item in source)
            action(item);
    }

    public static void ForEachOrBreak<T>(this IEnumerable<T> source, Func<T, bool> func)
    {
        foreach (var item in source)
        {
            bool result = func(item);
            if (result) break;
        }
    }
  }
}

Have fun.

Answer 3

In case someone comes across this question like myself - it's possible to achieve "AddRange" by using IEnumerable extension methods:

var combined =
    dict1.Union(dict2)
        .GroupBy(kvp => kvp.Key)
        .Select(grp => grp.First())
        .ToDictionary(kvp => kvp.Key, kvp => kvp.Value);

The main trick when combining dictionaries is dealing with the duplicate keys. In the code above it's the part .Select(grp => grp.First()). In this case it simply takes the first element from the group of duplicates but you can implement more sophisticated logic there if needed.

Answer 4

My guess is lack of proper output to the user as to what happened. As you can't have repeating keys in a dictionaries, how would you handle merging two dictionary where some keys intersect? Sure you could say: "I don't care" but that's breaking the convention of returning false / throwing an exception for repeating keys.

Answer 5

You could do this

Dictionary<string, string> dic = new Dictionary<string, string>();
// dictionary other items already added.
MethodThatReturnAnotherDic(dic);

public void MethodThatReturnAnotherDic(Dictionary<string, string> dic)
{
    dic.Add(.., ..);
}

or use a List for addrange and/or using the pattern above.

List<KeyValuePair<string, string>>

Answer 6

Feel free to use extension method like this:

public static Dictionary<T, U> AddRange<T, U>(this Dictionary<T, U> destination, Dictionary<T, U> source)
{
  if (destination == null) destination = new Dictionary<T, U>();
  foreach (var e in source)
    destination.Add(e.Key, e.Value);
  return destination;
}

Answer 7

Just use Concat():

dic.Concat(MethodThatReturnAnotherDic());

Answer 8

Why doesn't Dictionary have AddRange?

List.AddRange is specifically a "fast contiguous block copy" method of the kind seen across different languages for collections like lists, vectors or arrays, which have their data contiguously laid out in memory, i.e. with each element following the last, at regular offsets. Range hints at its internals, that is, only one range (of elements, of memory).

Dictionarys internally look very different to Lists. This is due to the way in which a hashtable (i.e. Dictionary) stores its entries: They're not contiguous in memory as we see in an array or a List, instead a Dicts elements are fragmented across multiple hash buckets which contain several entries, many empty, so you cannot just block-copy the whole range into e.g. a List or you'll get a bunch of empty entries which Dictionary usually hides from you through its interface.

Due to this fragmentation, we are left no choice but to manually iterate through the Dictionary's entries in order to extract only valid keys and values into a contiguous array, List or another Dict. See Microsoft's reference implementation, where CopyTo is thus implemented using for.

List.AddRange uses Array.Copy. This is similar to Buffer.BlockCopy whose equivalent in C is memcpy. It exists for performant copies of large blocks of contiguous data, all of which you want. This Adding is easily done at the end of a listB from listA, but the merging of two Dictionarys entries is not so trivial. And your proposal would need to handle that.

The method you conceptually propose would be useful, and is indeed possible to add. But to call it AddRange would be a misnomer. I would call it AddEntries, perhaps. And any implementation would have some interesting questions to solve, some of which others here have commented on.

Answer 9

If you're dealing w/ a new Dictionary (and you don't have existing rows to lose), you can always use ToDictionary() from another list of objects.

So, in your case, you would do something like this:

Dictionary<string, string> dic = new Dictionary<string, string>();
dic = SomeList.ToDictionary(x => x.Attribute1, x => x.Attribute2);

Answer 10

If you know you aren't going to have duplicate keys, you can do:

dic = dic.Union(MethodThatReturnAnotherDic()).ToDictionary(kvp => kvp.Key, kvp => kvp.Value);

It will throw an exception if there is a duplicate key/value pair.

I don't know why this isn't in the framework; should be. There's no uncertainty; just throw an exception. In the case of this code, it does throw an exception.

Answer 11

Here is an alternative solution using c# 7 ValueTuples (tuple literals)

public static class DictionaryExtensions
{
    public static Dictionary<TKey, TValue> AddRange<TKey, TValue>(this Dictionary<TKey, TValue> source,  IEnumerable<ValueTuple<TKey, TValue>> kvps)
    {
        foreach (var kvp in kvps)
            source.Add(kvp.Item1, kvp.Item2);

        return source;
    }

    public static void AddTo<TKey, TValue>(this IEnumerable<ValueTuple<TKey, TValue>> source, Dictionary<TKey, TValue> target)
    {
        target.AddRange(source);
    }
}

Used like

segments
    .Zip(values, (s, v) => (s.AsSpan().StartsWith("{") ? s.Trim('{', '}') : null, v))
    .Where(zip => zip.Item1 != null)
    .AddTo(queryParams);

Answer 12

As others have mentioned, the reason why Dictionary<TKey,TVal>.AddRange is not implemented is because there are various ways you might want to handle cases where you have duplicates. This is also the case for Collection or interfaces such as IDictionary<TKey,TVal>, ICollection<T>, etc.

Only List<T> implements it, and you will note that the IList<T> interface does not, for the same reasons: the expected behaviour when adding a range of values to a collection can vary broadly, depending on context.

The context of your question suggests you are not worried about duplicates, in which case you have a simple oneliner alternative, using Linq:

MethodThatReturnAnotherDic().ToList.ForEach(kvp => dic.Add(kvp.Key, kvp.Value));

Answer 13

This is an extension function written by one of my colleagues and it saved my life today. HYG!

    /// <summary>
    /// Add key value pairs range to dictionary
    /// </summary>
    /// <param name="dictionary">current dictionary</param>
    /// <param name="range">new range to add</param>
    /// <typeparam name="TKey">dictionary key type</typeparam>
    /// <typeparam name="TValue">dictionary value type</typeparam>
    /// <returns>list of duplicate records that weren't added</returns>

public static IEnumerable<KeyValuePair<TKey, TValue>> AddRange<TKey, TValue>(this IDictionary<TKey, TValue> dictionary, IDictionary<TKey, TValue> range)
       {
        var duplicateRecords = new List<KeyValuePair<TKey, TValue>>();
        
        foreach (var item in range)
        {
            if (dictionary.ContainsKey(item.Key))
                duplicateRecords.Add(item);
            else
                dictionary.Add(item);
        }
        return duplicateRecords;
    }