comment and cleanup

Author: LoneWandererProductions

ExtendedSystemObjects/Helper/SharedRessources.cs

@@ -38,6 +38,11 @@ internal static class SharedResources
         /// </summary>
         internal const string ErrorValueExists = "Value already exists: ";
 
+        /// <summary>
+        /// The error duplicate key (const). "Duplicate key detected: {key}".
+        /// </summary>
+        internal const string ErrorDuplicateKey = "Duplicate key detected: {key}";
+
         /// <summary>
         ///     Separator(const). Value: " , ".
         /// </summary>

ExtendedSystemObjects/ImmutableLookupMap.cs

@@ -76,16 +76,17 @@ public ImmutableLookupMap(IDictionary<TKey, TValue> data)
 
                     if (_keys[hash].Equals(key))
                     {
-                        throw new InvalidOperationException($"Duplicate key detected: {key}");
+                        throw new InvalidOperationException(string.Format(SharedResources.ErrorDuplicateKey, key));
                     }
                 }
             }
         }
 
         /// <inheritdoc />
         /// <summary>
-        ///     Returns an enumerator for iterating over the key-value pairs in the map.
+        /// Returns an enumerator that iterates through the key-value pairs in the map.
         /// </summary>
+        /// <returns>An enumerator for the map.</returns>
         public IEnumerator<KeyValuePair<TKey, TValue>> GetEnumerator()
         {
             for (var i = 0; i < _keys.Length; i++)
@@ -110,11 +111,11 @@ IEnumerator IEnumerable.GetEnumerator()
         }
 
         /// <summary>
-        ///     Retrieves the value associated with the specified key.
+        /// Gets the value associated with the specified key.
         /// </summary>
-        /// <param name="key">The key.</param>
-        /// <returns>Requested Value from Key</returns>
-        /// <exception cref="KeyNotFoundException">The key {key} was not found in the lookup map.</exception>
+        /// <param name="key">The key to lookup.</param>
+        /// <returns>The value associated with the key.</returns>
+        /// <exception cref="KeyNotFoundException">Thrown if the key is not found in the map.</exception>
         public TValue Get(TKey key)
         {
             var hash = GetHash(key, _keys.Length);
@@ -138,11 +139,11 @@ public TValue Get(TKey key)
         }
 
         /// <summary>
-        ///     Attempts to retrieve the value associated with the specified key.
+        /// Attempts to retrieve the value associated with the specified key.
         /// </summary>
-        /// <param name="key">The key.</param>
-        /// <param name="value">The value.</param>
-        /// <returns>The value amd bool check if it exists.</returns>
+        /// <param name="key">The key to lookup.</param>
+        /// <param name="value">When this method returns, contains the value associated with the key, if found; otherwise, the default value.</param>
+        /// <returns><c>true</c> if the key was found; otherwise, <c>false</c>.</returns>
         public bool TryGetValue(TKey key, out TValue value)
         {
             var hash = GetHash(key, _keys.Length);

ExtendedSystemObjects/ImmutableLookupMapUnmanaged.cs

@@ -2,8 +2,9 @@
  * COPYRIGHT:   See COPYING in the top level directory
  * PROJECT:     ExtendedSystemObjects
  * FILE:        ExtendedSystemObjects/ImmutableLookupMap.cs
- * PURPOSE:     A high-performance, immutable lookup map that uses an array-based internal structure for fast key-value lookups. Tis one is for unmanaged only. It uses my UnmanagedArray.
- * PROGRAMER:   Peter Geinitz (Wayfarer)
+ * PURPOSE:     A high-performance, immutable lookup map that uses an array-based internal structure for fast key-value lookups.
+ *              This version is limited to unmanaged types and uses UnmanagedArray<T>.
+ * PROGRAMMER:  Peter Geinitz (Wayfarer)
  */
 
 // ReSharper disable UnusedMember.Global
@@ -19,19 +20,45 @@ namespace ExtendedSystemObjects
 {
     /// <summary>
     /// A high-performance, immutable lookup map using unmanaged arrays.
+    /// Suitable for value types only. Keys must be unique.
     /// </summary>
     public sealed unsafe class ImmutableLookupMapUnmanaged<TKey, TValue> : IDisposable, IEnumerable<KeyValuePair<TKey, TValue>>
         where TKey : unmanaged, IEquatable<TKey>
         where TValue : unmanaged
     {
+        /// <summary>
+        /// The keys
+        /// </summary>
         private readonly UnmanagedArray<TKey> _keys;
+
+        /// <summary>
+        /// The values
+        /// </summary>
         private readonly UnmanagedArray<TValue> _values;
+
+        /// <summary>
+        /// Indicates whether a key is present at the given hash slot.
+        /// </summary>
         private readonly UnmanagedArray<byte> _keyPresence;
 
+        /// <summary>
+        /// The capacity
+        /// </summary>
         private readonly int _capacity;
 
+        /// <summary>
+        /// Gets the number of entries in the map.
+        /// </summary>
         public int Count { get; }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ImmutableLookupMapUnmanaged{TKey, TValue}"/> class
+        /// with the specified key-value data.
+        /// </summary>
+        /// <param name="data">A dictionary containing the initial key-value pairs.</param>
+        /// <exception cref="ArgumentNullException">Thrown when <paramref name="data"/> is null.</exception>
+        /// <exception cref="InvalidOperationException">Thrown when a duplicate key is found.</exception>
+
         public ImmutableLookupMapUnmanaged(IDictionary<TKey, TValue> data)
         {
             if (data == null)
@@ -48,7 +75,7 @@ public ImmutableLookupMapUnmanaged(IDictionary<TKey, TValue> data)
             {
                 for (var i = 0; i < _capacity; i++)
                 {
-                    var hash = (GetHash(key, _capacity) + i * i) % _capacity;
+                    var hash = (GetHash(key, _capacity) + (i * i)) % _capacity;
 
                     if (_keyPresence[hash] == 0)
                     {
@@ -59,11 +86,17 @@ public ImmutableLookupMapUnmanaged(IDictionary<TKey, TValue> data)
                     }
 
                     if (_keys[hash].Equals(key))
-                        throw new InvalidOperationException($"Duplicate key detected: {key}");
+                        throw new InvalidOperationException(string.Format(SharedResources.ErrorDuplicateKey, key));
                 }
             }
         }
 
+        /// <summary>
+        /// Gets the value associated with the specified key.
+        /// </summary>
+        /// <param name="key">The key to lookup.</param>
+        /// <returns>The value associated with the key.</returns>
+        /// <exception cref="KeyNotFoundException">Thrown if the key is not found in the map.</exception>
         public TValue Get(TKey key)
         {
             var hash = GetHash(key, _capacity);
@@ -79,9 +112,15 @@ public TValue Get(TKey key)
                     break;
             }
 
-            throw new KeyNotFoundException($"Key '{key}' not found in lookup.");
+            throw new KeyNotFoundException(SharedResources.ErrorValueNotFound);
         }
 
+        /// <summary>
+        /// Attempts to retrieve the value associated with the specified key.
+        /// </summary>
+        /// <param name="key">The key to lookup.</param>
+        /// <param name="value">When this method returns, contains the value associated with the key, if found; otherwise, the default value.</param>
+        /// <returns><c>true</c> if the key was found; otherwise, <c>false</c>.</returns>
         public bool TryGetValue(TKey key, out TValue value)
         {
             var hash = GetHash(key, _capacity);
@@ -104,6 +143,10 @@ public bool TryGetValue(TKey key, out TValue value)
             return false;
         }
 
+        /// <inheritdoc />
+        /// <summary>
+        ///     Returns an enumerator for iterating over the key-value pairs in the map.
+        /// </summary>
         public IEnumerator<KeyValuePair<TKey, TValue>> GetEnumerator()
         {
             for (var i = 0; i < _capacity; i++)
@@ -113,28 +156,55 @@ public IEnumerator<KeyValuePair<TKey, TValue>> GetEnumerator()
             }
         }
 
+        /// <inheritdoc />
+        /// <summary>
+        ///     Returns an enumerator that iterates through a collection.
+        /// </summary>
+        /// <returns>
+        ///     An <see cref="T:System.Collections.IEnumerator" /> object that can be used to iterate through the collection.
+        /// </returns>
         IEnumerator IEnumerable.GetEnumerator() => GetEnumerator();
 
+        /// <summary>
+        /// Releases the unmanaged memory used by the lookup map.
+        /// </summary>
         public void Dispose()
         {
             _keys.Dispose();
             _values.Dispose();
             _keyPresence.Dispose();
         }
 
+        /// <summary>
+        /// Computes the hash code of a key and reduces it to fit the map's capacity.
+        /// </summary>
+        /// <param name="key">The key.</param>
+        /// <param name="capacity">The internal array size.</param>
+        /// <returns>A non-negative integer hash.</returns>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         private static int GetHash(TKey key, int capacity)
         {
             return Math.Abs(key.GetHashCode() % capacity);
         }
 
+        /// <summary>
+        /// Finds the next prime number greater than or equal to the specified number.
+        /// </summary>
+        /// <param name="number">The minimum value.</param>
+        /// <returns>The next prime number ≥ <paramref name="number"/>.</returns>
         private static int FindNextPrime(int number)
         {
             while (!IsPrime(number))
                 number++;
             return number;
         }
 
+        /// <summary>
+        /// Determines whether a number is prime.
+        /// Uses precomputed small primes for optimization.
+        /// </summary>
+        /// <param name="number">The number to check.</param>
+        /// <returns><c>true</c> if prime; otherwise, <c>false</c>.</returns>
         private static bool IsPrime(int number)
         {
             if (number < 2) return false;