Add TryAdd and TryGetValue overloads with out int index to OrderedDictionary (#109324)

Add TryAdd and TryGetValue overloads with out var index

Author: PranavSenthilnathan

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

@@ -174,7 +174,9 @@ void System.Collections.IList.Remove(object? value) { }
         public void TrimExcess() { }
         public void TrimExcess(int capacity) { }
         public bool TryAdd(TKey key, TValue value) { throw null; }
+        public bool TryAdd(TKey key, TValue value, out int index) { throw null; }
         public bool TryGetValue(TKey key, [System.Diagnostics.CodeAnalysis.MaybeNullWhenAttribute(false)] out TValue value) { throw null; }
+        public bool TryGetValue(TKey key, [System.Diagnostics.CodeAnalysis.MaybeNullWhenAttribute(false)] out TValue value, out int index) { throw null; }
         public partial struct Enumerator : System.Collections.Generic.IEnumerator<System.Collections.Generic.KeyValuePair<TKey, TValue>>, System.Collections.IDictionaryEnumerator, System.Collections.IEnumerator, System.IDisposable
         {
             private object _dummy;

src/libraries/System.Collections/src/System/Collections/Generic/OrderedDictionary.cs

@@ -377,7 +377,7 @@ public TValue this[TKey key]
             {
                 ThrowIfNull(key);
 
-                bool modified = TryInsert(index: -1, key, value, InsertionBehavior.OverwriteExisting);
+                bool modified = TryInsert(index: -1, key, value, InsertionBehavior.OverwriteExisting, out _);
                 Debug.Assert(modified);
             }
         }
@@ -392,8 +392,9 @@ public TValue this[TKey key]
         /// - OverwriteExisting: If the key already exists, overwrites its value with the specified value, e.g. this[key] = value
         /// - ThrowOnExisting: If the key already exists, throws an exception, e.g. Add(key, value)
         /// </param>
+        /// <param name="keyIndex">The index of the added or existing key. This is always a valid index into the dictionary.</param>
         /// <returns>true if the collection was updated; otherwise, false.</returns>
-        private bool TryInsert(int index, TKey key, TValue value, InsertionBehavior behavior)
+        private bool TryInsert(int index, TKey key, TValue value, InsertionBehavior behavior, out int keyIndex)
         {
             // Search for the key in the dictionary.
             uint hashCode = 0, collisionCount = 0;
@@ -402,6 +403,9 @@ private bool TryInsert(int index, TKey key, TValue value, InsertionBehavior beha
             // Handle the case where the key already exists, based on the requested behavior.
             if (i >= 0)
             {
+                keyIndex = i;
+                Debug.Assert(0 <= keyIndex && keyIndex < _count);
+
                 Debug.Assert(_entries is not null);
 
                 switch (behavior)
@@ -467,6 +471,9 @@ private bool TryInsert(int index, TKey key, TValue value, InsertionBehavior beha
 
             RehashIfNecessary(collisionCount, entries);
 
+            keyIndex = index;
+            Debug.Assert(0 <= keyIndex && keyIndex < _count);
+
             return true;
         }
 
@@ -479,19 +486,27 @@ public void Add(TKey key, TValue value)
         {
             ThrowIfNull(key);
 
-            TryInsert(index: -1, key, value, InsertionBehavior.ThrowOnExisting);
+            TryInsert(index: -1, key, value, InsertionBehavior.ThrowOnExisting, out _);
         }
 
         /// <summary>Adds the specified key and value to the dictionary if the key doesn't already exist.</summary>
         /// <param name="key">The key of the element to add.</param>
         /// <param name="value">The value of the element to add. The value can be null for reference types.</param>
         /// <exception cref="ArgumentNullException">key is null.</exception>
         /// <returns>true if the key didn't exist and the key and value were added to the dictionary; otherwise, false.</returns>
-        public bool TryAdd(TKey key, TValue value)
+        public bool TryAdd(TKey key, TValue value) => TryAdd(key, value, out _);
+
+        /// <summary>Adds the specified key and value to the dictionary if the key doesn't already exist.</summary>
+        /// <param name="key">The key of the element to add.</param>
+        /// <param name="value">The value of the element to add. The value can be null for reference types.</param>
+        /// <param name="index">The index of the added or existing <paramref name="key"/>. This is always a valid index into the dictionary.</param>
+        /// <exception cref="ArgumentNullException">key is null.</exception>
+        /// <returns>true if the key didn't exist and the key and value were added to the dictionary; otherwise, false.</returns>
+        public bool TryAdd(TKey key, TValue value, out int index)
         {
             ThrowIfNull(key);
 
-            return TryInsert(index: -1, key, value, InsertionBehavior.IgnoreInsertion);
+            return TryInsert(index: -1, key, value, InsertionBehavior.IgnoreInsertion, out index);
         }
 
         /// <summary>Adds each element of the enumerable to the dictionary.</summary>
@@ -714,7 +729,7 @@ public void Insert(int index, TKey key, TValue value)
 
             ThrowIfNull(key);
 
-            TryInsert(index, key, value, InsertionBehavior.ThrowOnExisting);
+            TryInsert(index, key, value, InsertionBehavior.ThrowOnExisting, out _);
         }
 
         /// <summary>Removes the value with the specified key from the <see cref="OrderedDictionary{TKey, TValue}"/>.</summary>
@@ -896,12 +911,22 @@ public void TrimExcess(int capacity)
         /// otherwise, the default value for the type of the value parameter.
         /// </param>
         /// <returns>true if the <see cref="OrderedDictionary{TKey, TValue}"/> contains an element with the specified key; otherwise, false.</returns>
-        public bool TryGetValue(TKey key, [MaybeNullWhen(false)] out TValue value)
+        public bool TryGetValue(TKey key, [MaybeNullWhen(false)] out TValue value) => TryGetValue(key, out value, out _);
+
+        /// <summary>Gets the value associated with the specified key.</summary>
+        /// <param name="key">The key of the value to get.</param>
+        /// <param name="value">
+        /// When this method returns, contains the value associated with the specified key, if the key is found;
+        /// otherwise, the default value for the type of the value parameter.
+        /// </param>
+        /// <param name="index">The index of <paramref name="key"/> if found; otherwise, -1.</param>
+        /// <returns>true if the <see cref="OrderedDictionary{TKey, TValue}"/> contains an element with the specified key; otherwise, false.</returns>
+        public bool TryGetValue(TKey key, [MaybeNullWhen(false)] out TValue value, out int index)
         {
             ThrowIfNull(key);
 
             // Find the key.
-            int index = IndexOf(key);
+            index = IndexOf(key);
             if (index >= 0)
             {
                 // It exists. Return its value.

src/libraries/System.Collections/tests/Generic/OrderedDictionary/OrderedDictionary.Generic.Tests.cs

@@ -139,6 +139,7 @@ public void OrderedDictionary_Generic_Constructor_AllKeysEqualComparer()
         #endregion
 
         #region TryAdd
+
         [Fact]
         public void TryAdd_NullKeyThrows()
         {
@@ -148,29 +149,30 @@ public void TryAdd_NullKeyThrows()
             }
 
             var dictionary = new OrderedDictionary<TKey, TValue>();
+            int index;
+
             AssertExtensions.Throws<ArgumentNullException>("key", () => dictionary.TryAdd(default(TKey), CreateTValue(0)));
+            AssertExtensions.Throws<ArgumentNullException>("key", () => dictionary.TryAdd(default(TKey), CreateTValue(0), out index));
+
             Assert.True(dictionary.TryAdd(CreateTKey(0), default));
             Assert.Equal(1, dictionary.Count);
+
+            Assert.True(dictionary.TryAdd(CreateTKey(1), default, out index));
+            Assert.Equal(1, index);
+            Assert.Equal(2, dictionary.Count);
         }
 
-        [Fact]
-        public void TryAdd_AppendsItemToEndOfDictionary()
+        [Theory]
+        [MemberData(nameof(ValidCollectionSizes))]
+        public void TryAdd_AppendsItemToEndOfDictionary(int count)
         {
-            var dictionary = new OrderedDictionary<TKey, TValue>();
-            AddToCollection(dictionary, 10);
+            OrderedDictionary<TKey, TValue> dictionary = (OrderedDictionary<TKey, TValue>)GenericIDictionaryFactory(count);
             foreach (var entry in dictionary)
             {
                 Assert.False(dictionary.TryAdd(entry.Key, entry.Value));
             }
 
-            TKey newKey;
-            int i = 0;
-            do
-            {
-                newKey = CreateTKey(i);
-            }
-            while (dictionary.ContainsKey(newKey));
-
+            TKey newKey = GetNewKey(dictionary);
             Assert.True(dictionary.TryAdd(newKey, CreateTValue(42)));
             Assert.Equal(dictionary.Count - 1, dictionary.IndexOf(newKey));
         }
@@ -187,6 +189,90 @@ public void TryAdd_ItemAlreadyExists_DoesNotInvalidateEnumerator()
 
             Assert.True(valuesEnum.MoveNext());
         }
+
+        [Theory]
+        [MemberData(nameof(ValidCollectionSizes))]
+        public void TryAdd_Index_AppendsItemToEndOfDictionary(int count)
+        {
+            OrderedDictionary<TKey, TValue> dictionary = (OrderedDictionary<TKey, TValue>)GenericIDictionaryFactory(count);
+            int index;
+
+            for (int i = 0; i < dictionary.Count; i++)
+            {
+                (TKey key, TValue value) = dictionary.GetAt(i);
+                Assert.False(dictionary.TryAdd(key, value, out index));
+                Assert.Equal(i, index);
+            }
+
+            Assert.True(dictionary.TryAdd(GetNewKey(dictionary), CreateTValue(42), out index));
+            Assert.Equal(dictionary.Count - 1, index);
+        }
+
+        [Theory]
+        [MemberData(nameof(ValidPositiveCollectionSizes))]
+        public void TryAdd_NewItem_IndexCorrect(int count)
+        {
+            var dictionary = new OrderedDictionary<TKey, TValue>();
+
+            for (int i = 0; i < count; i++)
+            {
+                int index;
+                TKey newKey = GetNewKey(dictionary);
+
+                Assert.True(dictionary.TryAdd(newKey, CreateTValue(i), out index));
+                Assert.Equal(i, index);
+                Assert.False(dictionary.TryAdd(newKey, CreateTValue(i), out index));
+                Assert.Equal(i, index);
+            }
+        }
+
+        #endregion
+
+        #region TryGetValue
+
+        [Theory]
+        [MemberData(nameof(ValidCollectionSizes))]
+        public void TryGetValue_Index_NullKeyThrows(int count)
+        {
+            OrderedDictionary<TKey, TValue> dictionary = (OrderedDictionary<TKey, TValue>)GenericIDictionaryFactory(count);
+            TValue outValue;
+            int index;
+            if (DefaultValueAllowed)
+            {
+                TKey missingKey = default(TKey);
+                while (dictionary.ContainsKey(missingKey))
+                    dictionary.Remove(missingKey);
+                Assert.False(dictionary.TryGetValue(missingKey, out outValue, out index));
+            }
+            else
+            {
+                Assert.Throws<ArgumentNullException>(() => dictionary.TryGetValue(default(TKey), out outValue, out index));
+            }
+        }
+
+        [Theory]
+        [MemberData(nameof(ValidCollectionSizes))]
+        public void TryGetValue_ValidKeyNotContainedInDictionary(int count)
+        {
+            OrderedDictionary<TKey, TValue> dictionary = (OrderedDictionary<TKey, TValue>)GenericIDictionaryFactory(count);
+            TKey missingKey = GetNewKey(dictionary);
+            Assert.False(dictionary.TryGetValue(missingKey, out _, out int index));
+            Assert.Equal(-1, index);
+        }
+
+        [Theory]
+        [MemberData(nameof(ValidCollectionSizes))]
+        public void TryGetValue_ValidKeyContainedInDictionary(int count)
+        {
+            OrderedDictionary<TKey, TValue>dictionary = (OrderedDictionary<TKey, TValue>)GenericIDictionaryFactory(count);
+            TKey missingKey = GetNewKey(dictionary);
+            TValue value = CreateTValue(5123);
+            dictionary.TryAdd(missingKey, value);
+            Assert.True(dictionary.TryGetValue(missingKey, out TValue outValue, out int index));
+            Assert.Equal(value, outValue);
+            Assert.Equal(dictionary.Count - 1, index);
+        }
+
         #endregion
 
         #region ContainsValue

src/libraries/System.Text.Json/src/System/Text/Json/Nodes/JsonObject.cs

@@ -248,9 +248,17 @@ internal void SetItem(string propertyName, JsonNode? value)
 
             OrderedDictionary<string, JsonNode?> dict = Dictionary;
 
-            if (!dict.TryAdd(propertyName, value))
+            if (
+#if NET10_0_OR_GREATER
+                !dict.TryAdd(propertyName, value, out int index)
+#else
+                !dict.TryAdd(propertyName, value)
+#endif
+                )
             {
+#if !NET10_0_OR_GREATER
                 int index = dict.IndexOf(propertyName);
+#endif
                 Debug.Assert(index >= 0);
                 JsonNode? replacedValue = dict.GetAt(index).Value;