Add ImmutableDictionary.CreateRangeWithOverwrite (#115570)

Author: stephentoub

src/libraries/System.Collections.Immutable/ref/System.Collections.Immutable.cs

@@ -436,7 +436,9 @@ public static partial class ImmutableDictionary
         public static System.Collections.Immutable.ImmutableDictionary<TKey, TValue>.Builder CreateBuilder<TKey, TValue>(System.Collections.Generic.IEqualityComparer<TKey>? keyComparer) where TKey : notnull { throw null; }
         public static System.Collections.Immutable.ImmutableDictionary<TKey, TValue>.Builder CreateBuilder<TKey, TValue>(System.Collections.Generic.IEqualityComparer<TKey>? keyComparer, System.Collections.Generic.IEqualityComparer<TValue>? valueComparer) where TKey : notnull { throw null; }
         public static System.Collections.Immutable.ImmutableDictionary<TKey, TValue> CreateRange<TKey, TValue>(System.Collections.Generic.IEnumerable<System.Collections.Generic.KeyValuePair<TKey, TValue>> items) where TKey : notnull { throw null; }
+        public static System.Collections.Immutable.ImmutableDictionary<TKey, TValue> CreateRangeWithOverwrite<TKey, TValue>(params System.ReadOnlySpan<System.Collections.Generic.KeyValuePair<TKey, TValue>> items) where TKey : notnull { throw null; }
         public static System.Collections.Immutable.ImmutableDictionary<TKey, TValue> CreateRange<TKey, TValue>(System.Collections.Generic.IEqualityComparer<TKey>? keyComparer, System.Collections.Generic.IEnumerable<System.Collections.Generic.KeyValuePair<TKey, TValue>> items) where TKey : notnull { throw null; }
+        public static System.Collections.Immutable.ImmutableDictionary<TKey, TValue> CreateRangeWithOverwrite<TKey, TValue>(System.Collections.Generic.IEqualityComparer<TKey>? keyComparer, params System.ReadOnlySpan<System.Collections.Generic.KeyValuePair<TKey, TValue>> items) where TKey : notnull { throw null; }
         public static System.Collections.Immutable.ImmutableDictionary<TKey, TValue> CreateRange<TKey, TValue>(System.Collections.Generic.IEqualityComparer<TKey>? keyComparer, System.Collections.Generic.IEqualityComparer<TValue>? valueComparer, System.Collections.Generic.IEnumerable<System.Collections.Generic.KeyValuePair<TKey, TValue>> items) where TKey : notnull { throw null; }
         public static System.Collections.Immutable.ImmutableDictionary<TKey, TValue> Create<TKey, TValue>() where TKey : notnull { throw null; }
         public static System.Collections.Immutable.ImmutableDictionary<TKey, TValue> Create<TKey, TValue>(System.Collections.Generic.IEqualityComparer<TKey>? keyComparer) where TKey : notnull { throw null; }
@@ -453,6 +455,7 @@ public static partial class ImmutableDictionary
         public static System.Collections.Immutable.ImmutableDictionary<TKey, TValue> ToImmutableDictionary<TSource, TKey, TValue>(this System.Collections.Generic.IEnumerable<TSource> source, System.Func<TSource, TKey> keySelector, System.Func<TSource, TValue> elementSelector, System.Collections.Generic.IEqualityComparer<TKey>? keyComparer) where TKey : notnull { throw null; }
         public static System.Collections.Immutable.ImmutableDictionary<TKey, TValue> ToImmutableDictionary<TSource, TKey, TValue>(this System.Collections.Generic.IEnumerable<TSource> source, System.Func<TSource, TKey> keySelector, System.Func<TSource, TValue> elementSelector, System.Collections.Generic.IEqualityComparer<TKey>? keyComparer, System.Collections.Generic.IEqualityComparer<TValue>? valueComparer) where TKey : notnull { throw null; }
     }
+    [System.Runtime.CompilerServices.CollectionBuilderAttribute(typeof(System.Collections.Immutable.ImmutableDictionary), "CreateRangeWithOverwrite")]
     public sealed partial class ImmutableDictionary<TKey, TValue> : System.Collections.Generic.ICollection<System.Collections.Generic.KeyValuePair<TKey, TValue>>, System.Collections.Generic.IDictionary<TKey, TValue>, System.Collections.Generic.IEnumerable<System.Collections.Generic.KeyValuePair<TKey, TValue>>, System.Collections.Generic.IReadOnlyCollection<System.Collections.Generic.KeyValuePair<TKey, TValue>>, System.Collections.Generic.IReadOnlyDictionary<TKey, TValue>, System.Collections.ICollection, System.Collections.IDictionary, System.Collections.IEnumerable, System.Collections.Immutable.IImmutableDictionary<TKey, TValue> where TKey : notnull
     {
         internal ImmutableDictionary() { }

src/libraries/System.Collections.Immutable/src/System/Collections/Immutable/ImmutableDictionary.cs

@@ -64,6 +64,25 @@ public static ImmutableDictionary<TKey, TValue> CreateRange<TKey, TValue>(IEnume
             return ImmutableDictionary<TKey, TValue>.Empty.AddRange(items);
         }
 
+        /// <summary>
+        /// Creates a new immutable dictionary that contains the specified items.
+        /// </summary>
+        /// <typeparam name="TKey">The type of keys in the dictionary.</typeparam>
+        /// <typeparam name="TValue">The type of values in the dictionary.</typeparam>
+        /// <param name="items">The items used to populate the dictionary before it's immutable.</param>
+        /// <returns>A new immutable dictionary that contains the specified items.</returns>
+        /// <remarks>
+        /// In contrast to <see cref="CreateRange{TKey, TValue}(IEnumerable{KeyValuePair{TKey, TValue}})"/>,
+        /// if there are duplicate keys in the <paramref name="items"/> collection, the last one will be used,
+        /// rather than an exception being thrown.
+        /// </remarks>
+        public static ImmutableDictionary<TKey, TValue> CreateRangeWithOverwrite<TKey, TValue>(
+            params ReadOnlySpan<KeyValuePair<TKey, TValue>> items)
+            where TKey : notnull
+        {
+            return ImmutableDictionary<TKey, TValue>.Empty.AddRange(items, ImmutableDictionary<TKey, TValue>.KeyCollisionBehavior.SetValue);
+        }
+
         /// <summary>
         /// Creates a new immutable collection prefilled with the specified items.
         /// </summary>
@@ -77,6 +96,27 @@ public static ImmutableDictionary<TKey, TValue> CreateRange<TKey, TValue>(IEqual
             return ImmutableDictionary<TKey, TValue>.Empty.WithComparers(keyComparer).AddRange(items);
         }
 
+        /// <summary>
+        /// Creates a new immutable dictionary that contains the specified items and uses the specified key comparer.
+        /// </summary>
+        /// <typeparam name="TKey">The type of keys in the dictionary.</typeparam>
+        /// <typeparam name="TValue">The type of values in the dictionary.</typeparam>
+        /// <param name="keyComparer">The comparer implementation to use to compare keys for equality.</param>
+        /// <param name="items">The items to add to the dictionary before it's immutable.</param>
+        /// <returns>A new immutable dictionary that contains the specified items and uses the specified comparer.</returns>
+        /// <remarks>
+        /// In contrast to <see cref="CreateRange{TKey, TValue}(IEqualityComparer{TKey}?, IEnumerable{KeyValuePair{TKey, TValue}})"/>,
+        /// if there are duplicate keys in the <paramref name="items"/> collection, the last one will be used,
+        /// rather than an exception being thrown.
+        /// </remarks>
+        public static ImmutableDictionary<TKey, TValue> CreateRangeWithOverwrite<TKey, TValue>(
+            IEqualityComparer<TKey>? keyComparer,
+            params ReadOnlySpan<KeyValuePair<TKey, TValue>> items)
+            where TKey : notnull
+        {
+            return ImmutableDictionary<TKey, TValue>.Empty.WithComparers(keyComparer).AddRange(items, ImmutableDictionary<TKey, TValue>.KeyCollisionBehavior.SetValue);
+        }
+
         /// <summary>
         /// Creates a new immutable collection prefilled with the specified items.
         /// </summary>

src/libraries/System.Collections.Immutable/src/System/Collections/Immutable/ImmutableDictionary_2.cs

@@ -5,6 +5,7 @@
 using System.Diagnostics;
 using System.Diagnostics.CodeAnalysis;
 using System.Linq;
+using System.Runtime.CompilerServices;
 
 namespace System.Collections.Immutable
 {
@@ -15,6 +16,7 @@ namespace System.Collections.Immutable
     /// <typeparam name="TValue">The type of the value.</typeparam>
     [DebuggerDisplay("Count = {Count}")]
     [DebuggerTypeProxy(typeof(ImmutableDictionaryDebuggerProxy<,>))]
+    [CollectionBuilder(typeof(ImmutableDictionary), nameof(ImmutableDictionary.CreateRangeWithOverwrite))]
     public sealed partial class ImmutableDictionary<TKey, TValue> : IImmutableDictionary<TKey, TValue>, IImmutableDictionaryInternal<TKey, TValue>, IDictionary<TKey, TValue>, IDictionary where TKey : notnull
     {
         /// <summary>
@@ -313,6 +315,11 @@ public ImmutableDictionary<TKey, TValue> AddRange(IEnumerable<KeyValuePair<TKey,
             return this.AddRange(pairs, false);
         }
 
+        internal ImmutableDictionary<TKey, TValue> AddRange(ReadOnlySpan<KeyValuePair<TKey, TValue>> pairs, KeyCollisionBehavior collisionBehavior = KeyCollisionBehavior.ThrowIfValueDifferent)
+        {
+            return AddRange(pairs, this.Origin, collisionBehavior).Finalize(this);
+        }
+
         /// <summary>
         /// See the <see cref="IImmutableDictionary{TKey, TValue}"/> interface.
         /// </summary>
@@ -970,6 +977,30 @@ private static MutationResult AddRange(IEnumerable<KeyValuePair<TKey, TValue>> i
             return new MutationResult(newRoot, countAdjustment);
         }
 
+        /// <summary>
+        /// Performs the operation on a given data structure.
+        /// </summary>
+        private static MutationResult AddRange(ReadOnlySpan<KeyValuePair<TKey, TValue>> items, MutationInput origin, KeyCollisionBehavior collisionBehavior = KeyCollisionBehavior.ThrowIfValueDifferent)
+        {
+            int countAdjustment = 0;
+            SortedInt32KeyNode<ImmutableDictionary<TKey, TValue>.HashBucket> newRoot = origin.Root;
+            foreach (KeyValuePair<TKey, TValue> pair in items)
+            {
+                Requires.NotNullAllowStructs(pair.Key, nameof(pair.Key));
+                int hashCode = origin.KeyComparer.GetHashCode(pair.Key);
+                HashBucket bucket = newRoot.GetValueOrDefault(hashCode);
+                OperationResult result;
+                ImmutableDictionary<TKey, TValue>.HashBucket newBucket = bucket.Add(pair.Key, pair.Value, origin.KeyOnlyComparer, origin.ValueComparer, collisionBehavior, out result);
+                newRoot = UpdateRoot(newRoot, hashCode, newBucket, origin.HashBucketComparer);
+                if (result == OperationResult.SizeChanged)
+                {
+                    countAdjustment++;
+                }
+            }
+
+            return new MutationResult(newRoot, countAdjustment);
+        }
+
         /// <summary>
         /// Performs the operation on a given data structure.
         /// </summary>

src/libraries/System.Collections.Immutable/tests/ImmutableDictionaryTest.cs

@@ -121,6 +121,14 @@ public void ContainsValue_NoSuchValue_ReturnsFalse()
         public void Create()
         {
             IEnumerable<KeyValuePair<string, string>> pairs = new Dictionary<string, string> { { "a", "b" } };
+            ReadOnlySpan<KeyValuePair<string, string>> pairsWithDuplicates =
+            [
+                new KeyValuePair<string, string>("a", "b"),
+                new KeyValuePair<string, string>("a", "c"),
+                new KeyValuePair<string, string>("b", "d"),
+                new KeyValuePair<string, string>("B", "e"),
+                new KeyValuePair<string, string>("a", "f"),
+            ];
             StringComparer keyComparer = StringComparer.OrdinalIgnoreCase;
             StringComparer valueComparer = StringComparer.CurrentCulture;
 
@@ -153,6 +161,31 @@ public void Create()
             Assert.Equal(1, dictionary.Count);
             Assert.Same(keyComparer, dictionary.KeyComparer);
             Assert.Same(valueComparer, dictionary.ValueComparer);
+
+            dictionary = ImmutableDictionary.CreateRangeWithOverwrite<string, string>();
+            Assert.Equal(0, dictionary.Count);
+            Assert.Same(EqualityComparer<string>.Default, dictionary.KeyComparer);
+            Assert.Same(EqualityComparer<string>.Default, dictionary.ValueComparer);
+
+            dictionary = ImmutableDictionary.CreateRangeWithOverwrite<string, string>(keyComparer);
+            Assert.Equal(0, dictionary.Count);
+            Assert.Same(keyComparer, dictionary.KeyComparer);
+            Assert.Same(EqualityComparer<string>.Default, dictionary.ValueComparer);
+
+            dictionary = ImmutableDictionary.CreateRangeWithOverwrite(pairsWithDuplicates);
+            Assert.Equal(3, dictionary.Count);
+            Assert.Same(EqualityComparer<string>.Default, dictionary.KeyComparer);
+            Assert.Same(EqualityComparer<string>.Default, dictionary.ValueComparer);
+            Assert.Equal("f", dictionary["a"]);
+            Assert.Equal("d", dictionary["b"]);
+            Assert.Equal("e", dictionary["B"]);
+
+            dictionary = ImmutableDictionary.CreateRangeWithOverwrite(keyComparer, pairsWithDuplicates);
+            Assert.Equal(2, dictionary.Count);
+            Assert.Same(keyComparer, dictionary.KeyComparer);
+            Assert.Same(EqualityComparer<string>.Default, dictionary.ValueComparer);
+            Assert.Equal("f", dictionary["a"]);
+            Assert.Equal("e", dictionary["b"]);
         }
 
         [Fact]