Enhance collections and improve performance

Added `using System;` and `using System.Runtime.CompilerServices;` to support new features and optimizations. Introduced conditional compilation for .NET 9.0+ in `CollectionWrapper.cs` and `IAddMultiple.cs` to use `ReadOnlySpan<T>`. Added new methods and overloads to `CollectionWrapper<T, TCollection>` for adding multiple items and ranges, including `ReadOnlySpan<T>` support. Added XML documentation comments to improve maintainability. Renamed `TryTakeWhileCpre` to `TryTakeWhileCore` in `Extensions.ConcurrentBag.cs` for consistency and added methods for trimming and clearing `ConcurrentBag<T>`. Added helper methods and classes like `KeyValuePair.Create` and `ReadOnlyCollectionAdapter<T>`. Enhanced `ListWrapper<T, TList>` and `TrackedCollectionWrapper<T, TCollection>` with additional constructors, methods, and properties. Marked some methods as `[Obsolete]` to guide developers towards more efficient alternatives. Improved exception handling and null checks for robustness.

Author: electricessence

source/CollectionWrapper.cs

@@ -1,4 +1,5 @@
-using System.Collections.Generic;
+using System;
+using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
 using System.Runtime.CompilerServices;
 
@@ -49,8 +50,13 @@ public virtual void Add(T item)
 		AddInternal(in item);
 	}
 
+#if NET9_0_OR_GREATER
+	/// <inheritdoc cref="IAddMultiple{T}.AddThese(T, T, ReadOnlySpan{T})"/>
+	public virtual void AddThese(T item1, T item2, params ReadOnlySpan<T> items)
+#else
 	/// <inheritdoc cref="IAddMultiple{T}.AddThese(T, T, T[])"/>
 	public virtual void AddThese(T item1, T item2, params T[] items)
+#endif
 	{
 		AssertIsAlive();
 		AddInternal(in item1);
@@ -67,6 +73,19 @@ public virtual void AddThese(T item1, T item2, params T[] items)
 	/// <param name="items">The items to add.</param>
 	[MethodImpl(MethodImplOptions.AggressiveInlining)]
 	public virtual void AddRange(IEnumerable<T> items)
+	{
+		AssertIsAlive();
+		if (items is null) return;
+		foreach (var i in items)
+			AddInternal(in i);
+	}
+
+	/// <inheritdoc cref="AddRange(IEnumerable{T})"/>
+#if NET9_0_OR_GREATER
+	[OverloadResolutionPriority(1)]
+#endif
+	[MethodImpl(MethodImplOptions.AggressiveInlining)]
+	public virtual void AddRange(ReadOnlySpan<T> items)
 	{
 		AssertIsAlive();
 		foreach (var i in items)
@@ -86,5 +105,5 @@ public virtual bool Remove(T item)
 	/// <inheritdoc />
 	public override bool IsReadOnly
 		=> InternalSource.IsReadOnly;
-	#endregion
+#endregion
 }

source/DictionaryToHashSetWrapper.cs

@@ -5,11 +5,17 @@
 
 namespace Open.Collections;
 
+/// <summary>
+/// A wrapper for a <see cref="IDictionary{TKey, TValue}"/> to implement <see cref="ISet{T}"/>.
+/// </summary>
 [method: ExcludeFromCodeCoverage]
 public class DictionaryToHashSetWrapper<T>(
 	IDictionary<T, bool> source)
 	: ISet<T>
 {
+	/// <summary>
+	/// The internal source dictionary.
+	/// </summary>
 	protected readonly IDictionary<T, bool> InternalSource = source;
 
 	/// <inheritdoc />

source/DictionaryWrapper.cs

@@ -34,18 +34,21 @@ protected override TValue GetValueInternal(TKey key)
 	protected override void SetValueInternal(TKey key, TValue value)
 		=> InternalSource[key] = value;
 
+	/// <inheritdoc />
 	[MethodImpl(MethodImplOptions.AggressiveInlining)]
 	protected override ICollection<TKey> GetKeys()
 		=> new ReadOnlyCollectionAdapter<TKey>(
 			ThrowIfDisposed(InternalSource.Keys),
 			() => InternalSource.Count);
 
+	/// <inheritdoc />
 	[MethodImpl(MethodImplOptions.AggressiveInlining)]
 	protected override ICollection<TValue> GetValues()
 		=> new ReadOnlyCollectionAdapter<TValue>(
 			ThrowIfDisposed(InternalSource.Values),
 			() => InternalSource.Count);
 
+	/// <inheritdoc />
 	[MethodImpl(MethodImplOptions.AggressiveInlining)]
 	protected override void AddInternal(TKey key, TValue value)
 		=> InternalSource.Add(key, value);

source/Extensions.Combinations.cs

@@ -150,6 +150,9 @@ public static IEnumerable<ArraySegment<T>> CombinationsDistinct<T>(this IEnumera
 		return source.Count == 0 ? Enumerable.Empty<ArraySegment<T>>() : CombinationsCore(source, true, buffer);
 	}
 
+	/// <summary>
+	/// Enumerates all possible combinations of values.
+	/// </summary>
 	[Obsolete("Deprecated in favor of using .Subsets(length) or .Combinations(length) depending on intent.")]
 	public static IEnumerable<T[]> Combinations<T>(this IEnumerable<T> elements, int length, bool uniqueOnly)
 	{

source/Extensions.ConcurrentBag.cs

@@ -9,14 +9,17 @@ namespace Open.Collections;
 
 public static partial class Extensions
 {
+	/// <summary>
+	/// Attempts to take items from the <see cref="ConcurrentBag{T}"/> while the <paramref name="predicate"/> is true.
+	/// </summary>
 	public static IEnumerable<T> TryTakeWhile<T>(this ConcurrentBag<T> target, Func<ConcurrentBag<T>, bool> predicate)
 	{
 		if (target is null) throw new ArgumentNullException(nameof(target));
 		Contract.EndContractBlock();
 
-		return TryTakeWhileCpre(target, predicate);
+		return TryTakeWhileCore(target, predicate);
 
-		static IEnumerable<T> TryTakeWhileCpre(ConcurrentBag<T> target, Func<ConcurrentBag<T>, bool> predicate)
+		static IEnumerable<T> TryTakeWhileCore(ConcurrentBag<T> target, Func<ConcurrentBag<T>, bool> predicate)
 		{
 			while (!target.IsEmpty && predicate(target) && target.TryTake(out T? value))
 			{
@@ -25,6 +28,7 @@ static IEnumerable<T> TryTakeWhileCpre(ConcurrentBag<T> target, Func<ConcurrentB
 		}
 	}
 
+	/// <inheritdoc cref="TryTakeWhile{T}(ConcurrentBag{T}, Func{bool})"/>
 	public static IEnumerable<T> TryTakeWhile<T>(this ConcurrentBag<T> target, Func<bool> predicate)
 	{
 		if (target is null) throw new ArgumentNullException(nameof(target));
@@ -33,13 +37,19 @@ public static IEnumerable<T> TryTakeWhile<T>(this ConcurrentBag<T> target, Func<
 		return TryTakeWhile(target, _ => predicate());
 	}
 
+	/// <summary>
+	/// Trims the <see cref="ConcurrentBag{T}"/> to the specified <paramref name="maxSize"/>.
+	/// </summary>
 	public static void Trim<T>(this ConcurrentBag<T> target, int maxSize)
 	{
 		foreach (T? _ in TryTakeWhile(target, t => t.Count > maxSize))
 		{
 		}
 	}
 
+	/// <summary>
+	/// Trims the <see cref="ConcurrentBag{T}"/> to the specified <paramref name="maxSize"/> and calls the <paramref name="handler"/> for each trimmed item.
+	/// </summary>
 	public static Task TrimAsync<T>(this ConcurrentBag<T> target, int maxSize, Action<T> handler)
 	{
 		if (target is null) throw new ArgumentNullException(nameof(target));
@@ -52,5 +62,9 @@ public static Task TrimAsync<T>(this ConcurrentBag<T> target, int maxSize, Actio
 		);
 	}
 
-	public static Task ClearAsync<T>(this ConcurrentBag<T> target, Action<T> handler) => TrimAsync(target, 0, handler);
+	/// <summary>
+	/// Clears the <see cref="ConcurrentBag{T}"/> and calls the <paramref name="handler"/> for each item.
+	/// </summary>
+	public static Task ClearAsync<T>(this ConcurrentBag<T> target, Action<T> handler)
+		=> TrimAsync(target, 0, handler);
 }

source/Extensions.Generic.cs

@@ -1,6 +1,7 @@
 using System;
 using System.Collections.Generic;
 using System.Diagnostics.Contracts;
+using System.Runtime.CompilerServices;
 
 namespace Open.Collections;
 
@@ -57,6 +58,9 @@ public static void AddRange<T>(
 	}
 
 	/// <inheritdoc cref="AddRange{T}(ICollection{T}, IEnumerable{T})"/>
+#if NET9_0_OR_GREATER
+	[OverloadResolutionPriority(1)]
+#endif
 	public static void AddRange<T>(
 		this ICollection<T> target,
 		ReadOnlySpan<T> values)

source/IAddMultiple.cs

@@ -1,19 +1,33 @@
-using System.Collections.Generic;
+using System;
+using System.Collections.Generic;
+using System.Runtime.CompilerServices;
 
 namespace Open.Collections;
+
+/// <summary>
+/// Represents a collection that can add multiple items.
+/// </summary>
 public interface IAddMultiple<T>
 {
+	/// <summary>
+	/// Adds all the items in <paramref name="items"/> to this collection.
+	/// </summary>
+	/// <param name="items">The items to add.</param>
+	void AddRange(IEnumerable<T> items);
+
 	// Note: "AddThese" is the name because Add can have multiple signatures.
 
 	/// <summary>Adds more than one item.</summary>
 	/// <param name="item1">First item to add.</param>
 	/// <param name="item2">Additional item to add.</param>
 	/// <param name="items">Extended param items to add.</param>
-	void AddThese(T item1, T item2, params T[] items);
+#if NET9_0_OR_GREATER
+	void AddThese(T item1, T item2, params System.ReadOnlySpan<T> items);
 
-	/// <summary>
-	/// Adds all the items in <paramref name="items"/> to this collection.
-	/// </summary>
-	/// <param name="items">The items to add.</param>
-	void AddRange(IEnumerable<T> items);
+	/// <inheritdoc cref="AddRange(IEnumerable{T})"/>/>
+	[OverloadResolutionPriority(1)]
+	void AddRange(ReadOnlySpan<T> items);
+#else
+	void AddThese(T item1, T item2, params T[] items);
+#endif
 }

source/KeyValuePair.cs

@@ -4,8 +4,14 @@
 
 namespace Open.Collections;
 
+/// <summary>
+/// A static helper class for creating <see cref="KeyValuePair{TKey, TValue}"/> instances.
+/// </summary>
 public static class KeyValuePair
 {
+	/// <summary>
+	/// Creates a new <see cref="KeyValuePair{TKey, TValue}"/>.
+	/// </summary>
 	[ExcludeFromCodeCoverage]
 	[MethodImpl(MethodImplOptions.AggressiveInlining)]
 	public static KeyValuePair<TKey, TValue> Create<TKey, TValue>(TKey key, TValue value) => new(key, value);

source/ListWrapper.cs

@@ -4,6 +4,9 @@
 
 namespace Open.Collections;
 
+/// <summary>
+/// A wrapper for <see cref="IList{T}"/> that allows for easy extension.
+/// </summary>
 public class ListWrapper<T, TList>(
 	TList source, bool owner = false)
 	: CollectionWrapper<T, TList>(source, owner), IList<T>
@@ -33,15 +36,22 @@ public virtual void RemoveAt(int index)
 		=> InternalSource.RemoveAt(index);
 }
 
+/// <summary>
+/// A wrapper for <see cref="IList{T}"/> that allows for easy extension.
+/// </summary>
 [ExcludeFromCodeCoverage]
 public class ListWrapper<T>
 	: ListWrapper<T, IList<T>>
 {
+	/// <summary>
+	/// Initializes a new instance of the <see cref="ListWrapper{T}"/> class.
+	/// </summary>
 	public ListWrapper(IList<T> source, bool owner = false)
 		: base(source, owner)
 	{
 	}
 
+	/// <inheritdoc cref="ListWrapper{T}.ListWrapper(IList{T}, bool)"/>
 	public ListWrapper(int capacity = 0)
 		: base(new List<T>(capacity))
 	{

source/ReadOnlyCollectionAdapter.cs

@@ -7,6 +7,9 @@
 
 namespace Open.Collections;
 
+/// <summary>
+/// A read-only collection adapter that can be used to wrap an existing collection.
+/// </summary>
 [method: ExcludeFromCodeCoverage]
 public sealed class ReadOnlyCollectionAdapter<T>(
 	IEnumerable<T> source, Func<int> getCount)
@@ -18,10 +21,14 @@ public sealed class ReadOnlyCollectionAdapter<T>(
 			? item => c.Contains(item)
 			: item => source.Contains(item);
 
+	/// <summary>
+	/// Initializes a new instance of the <see cref="ReadOnlyCollectionAdapter{T}"/> class.
+	/// </summary>
 	[ExcludeFromCodeCoverage]
 	public ReadOnlyCollectionAdapter(IReadOnlyCollection<T> source)
 		: this(source, () => source.Count) { }
 
+	/// <inheritdoc cref="ReadOnlyCollectionAdapter{T}.ReadOnlyCollectionAdapter(ICollection{T})"/>
 	[ExcludeFromCodeCoverage]
 	public ReadOnlyCollectionAdapter(ICollection<T> source)
 		: this(source, () => source.Count) { }