Update project to v4.0.0 with various enhancements

Removed unused directives and files.
Added and improved XML documentation across multiple files.
Enhanced and added new methods in Extensions.cs.
Modified Shuffle method to accept optional Random parameter.
Simplified SequenceEqual method.
Updated project and package versions in Open.Collections.csproj.
Refactored ReadWriteSynchronizedCollectionWrapper.
Added missing assertion in BasicCollectionTests.cs.

Author: electricessence

benchmarking/Benchmarks/SubsetBufferedBench.cs

@@ -1,6 +1,5 @@
 using BenchmarkDotNet.Attributes;
 using System;
-using System.Collections.Generic;
 using System.Linq;
 
 namespace Open.Collections.Benchmarks;

source/ArrayPoolSegment.cs

@@ -10,8 +10,16 @@ namespace Open.Collections;
 /// <typeparam name="T">The type of the elements in the array.</typeparam>
 public readonly struct ArrayPoolSegment<T> : IDisposable
 {
+	/// <summary>
+	/// The segment of the array.
+	/// </summary>
 	public readonly ArraySegment<T> Segment;
+
+	/// <summary>
+	/// The <see cref="ArrayPool{T}"/> used to rent the array.
+	/// </summary>
 	public readonly ArrayPool<T>? Pool;
+
 	private readonly bool _clear;
 
 	/// <summary>

source/Extensions.Permutations.cs

@@ -1,12 +1,10 @@
-using Open.Disposable;
-using System;
+using System;
 using System.Buffers;
 using System.Collections.Generic;
 using System.Diagnostics.Contracts;
 using System.Linq;
 using System.Numerics;
 using System.Runtime.CompilerServices;
-using System.Xml.Linq;
 
 namespace Open.Collections;
 

source/Extensions.cs

@@ -313,19 +313,35 @@ public static void ForEach<T>(this ISynchronizedCollection<T> target, Cancellati
 		});
 	}
 
-	public static IEnumerable<T> Shuffle<T>(this IEnumerable<T> target)
+	/// <summary>
+	/// Randomizes the order of the source.
+	/// </summary>
+	public static IEnumerable<T> Shuffle<T>(
+		this IEnumerable<T> target, Random? rnd = null)
 	{
 		if (target is null)
 			throw new ArgumentNullException(nameof(target));
 		Contract.EndContractBlock();
 
-		var r = new Random();
+		var r = rnd ?? new Random();
 		return target.OrderBy(_ => r.Next());
 	}
 
-	// Ensures an optimized means of acquiring Any();
-	public static bool HasAny<T>(this IEnumerable<T> source) => source.HasAtLeast(1);
+	/// <summary>
+	/// Tests the count of the source to see if there's any items.
+	/// </summary>
+	/// <exception cref="ArgumentNullException">If the <paramref name="source"/> is null.</exception>
+	/// <remarks>
+	/// First checks the type to see if a count can be aquired directly.  If not, it will iterate through the source to count the items.
+	/// </remarks>
+	public static bool HasAny<T>(this IEnumerable<T> source)
+		=> source.HasAtLeast(1);
 
+	/// <summary>
+	/// Tests the count of the source to see if there's at least the <paramref name="minimum"/> number of items.
+	/// </summary>
+	/// <exception cref="ArgumentOutOfRangeException">If the <paramref name="minimum"/> is less than 1.</exception>
+	/// <inheritdoc cref="HasAny{T}(IEnumerable{T})"/>
 	public static bool HasAtLeast<T>(this IEnumerable<T> source, int minimum)
 	{
 		if (source is null)
@@ -338,8 +354,12 @@ public static bool HasAtLeast<T>(this IEnumerable<T> source, int minimum)
 		{
 			case T[] array:
 				return array.Length >= minimum;
+			case IReadOnlyCollection<T> collection:
+				return collection.Count >= minimum;
 			case ICollection collection:
 				return collection.Count >= minimum;
+			case ICollection<T> collection:
+				return collection.Count >= minimum;
 		}
 
 		using IEnumerator<T>? e = source.GetEnumerator();
@@ -351,6 +371,9 @@ public static bool HasAtLeast<T>(this IEnumerable<T> source, int minimum)
 		return false;
 	}
 
+	/// <summary>
+	/// Synchronizes enumerting by locking on the enumerator.
+	/// </summary>
 	public static bool ConcurrentTryMoveNext<T>(this IEnumerator<T> source, out T item)
 	{
 		// Always lock on next to prevent concurrency issues.
@@ -362,10 +385,14 @@ public static bool ConcurrentTryMoveNext<T>(this IEnumerator<T> source, out T it
 				return true;
 			}
 		}
+
 		item = default!;
 		return false;
 	}
 
+	/// <summary>
+	/// Syncronizes enumerting by locking on the enumerator and invokes the provided handlers depending on if .MoveNext() was true.
+	/// </summary>
 	public static bool ConcurrentMoveNext<T>(this IEnumerator<T> source, Action<T> trueHandler, Action? falseHandler = null)
 	{
 		// Always lock on next to prevent concurrency issues.
@@ -477,86 +504,19 @@ public static string ToConcatenatedString<T>(this IEnumerable<T> source, Func<T,
 		return b.ToString();
 	}
 
-	/// <summary>
-	/// Shortcut to String.Join() using "," as a default value.
-	/// </summary>
-	public static string Join(this string[] array, char separator)
-	{
-		if (array is null)
-			throw new ArgumentNullException(nameof(array));
-		Contract.EndContractBlock();
-
-		return string.Join(separator + string.Empty, array);
-	}
-
-	public static string Join(this string[] array, string separator = ",")
-	{
-		if (array is null)
-			throw new ArgumentNullException(nameof(array));
-		if (separator is null)
-			throw new ArgumentNullException(nameof(separator));
-		Contract.EndContractBlock();
-
-		return string.Join(separator, array);
-	}
-
-	/// <summary>
-	/// Concatenates a set of values into a single string using a character as a separator.
-	/// </summary>
-	public static string JoinToString<T>(this IEnumerable<T> source, char separator)
-	{
-		if (source is null) throw new ArgumentNullException(nameof(source));
-		Contract.EndContractBlock();
-
-		var sb = new StringBuilder();
-		using (IEnumerator<T>? enumerator = source.GetEnumerator())
-		{
-			if (enumerator.MoveNext())
-				sb.Append(enumerator.Current);
-			while (enumerator.MoveNext())
-				sb.Append(separator).Append(enumerator.Current);
-		}
-
-		return sb.ToString();
-	}
-
-	/// <summary>
-	/// Concatenates set of values into a single string using another string as a separator.
-	/// </summary>
-	public static string JoinToString<T>(this IEnumerable<T> source, string separator)
-	{
-		if (source is null) throw new ArgumentNullException(nameof(source));
-		if (separator is null) throw new ArgumentNullException(nameof(separator));
-		Contract.EndContractBlock();
-
-		var sb = new StringBuilder();
-		using (IEnumerator<T>? enumerator = source.GetEnumerator())
-		{
-			if (enumerator.MoveNext())
-				sb.Append(enumerator.Current);
-			while (enumerator.MoveNext())
-				sb.Append(separator).Append(enumerator.Current);
-		}
-
-		return sb.ToString();
-	}
-
 	/*public static T ValidateNotNull<T>(this T target)
 	{
 
 		Contract.Assume(target is not null);
 		return target;
 	}*/
 
-	public static Dictionary<TKey, TValue> ToDictionary<TKey, TValue>(this ParallelQuery<KeyValuePair<TKey, TValue>> source)
-		where TKey : notnull
-	{
-		if (source is null) throw new ArgumentNullException(nameof(source));
-		Contract.EndContractBlock();
-
-		return source.ToDictionary(kvp => kvp.Key, kvp => kvp.Value);
-	}
-
+#if NET9_0_OR_GREATER
+#else
+	/// <summary>
+	/// Returns a dictionary from the source key-value pairs.
+	/// </summary>
+	/// <exception cref="ArgumentNullException">If the <paramref name="source"/> is null.</exception>
 	public static Dictionary<TKey, TValue> ToDictionary<TKey, TValue>(this IEnumerable<KeyValuePair<TKey, TValue>> source)
 		where TKey : notnull
 	{
@@ -565,7 +525,12 @@ public static Dictionary<TKey, TValue> ToDictionary<TKey, TValue>(this IEnumerab
 
 		return source.ToDictionary(kvp => kvp.Key, kvp => kvp.Value);
 	}
+#endif
 
+	/// <summary>
+	/// Converts an enumerable to a sorted dictionary.
+	/// </summary>
+	/// <exception cref="ArgumentNullException">If the <paramref name="source"/> is null.</exception>
 	public static SortedDictionary<TKey, TValue> ToSortedDictionary<TKey, TValue>(this IEnumerable<KeyValuePair<TKey, TValue>> source)
 		where TKey : notnull
 	{
@@ -579,6 +544,10 @@ public static SortedDictionary<TKey, TValue> ToSortedDictionary<TKey, TValue>(th
 		return result;
 	}
 
+	/// <summary>
+	/// Converts an enumerable to a sorted dictionary.
+	/// </summary>
+	/// <exception cref="ArgumentNullException">If the <paramref name="source"/>, <paramref name="keySelector"/>, or <typeparamref name="TValue"/> are null.</exception>
 	public static SortedDictionary<TKey, TValue> ToSortedDictionary<TSource, TKey, TValue>(this IEnumerable<TSource> source,
 		Func<TSource, TKey> keySelector, Func<TSource, TValue> valueSelector)
 		where TKey : notnull
@@ -595,6 +564,10 @@ public static SortedDictionary<TKey, TValue> ToSortedDictionary<TSource, TKey, T
 		return result;
 	}
 
+	/// <summary>
+	/// Converts a grouping to a sorted dictionary.
+	/// </summary>
+	/// <exception cref="ArgumentNullException">If the <paramref name="source"/> is null.</exception>
 	public static SortedDictionary<TKey, IEnumerable<TValue>> ToSortedDictionary<TKey, TValue>(this IEnumerable<IGrouping<TKey, TValue>> source)
 		where TKey : notnull
 	{
@@ -664,18 +637,8 @@ public static bool IsEquivalentTo<T>(this IEnumerable<T> source, IEnumerable<T>
 		if (source is null || target is null)
 			return false;
 
-		if (source is IReadOnlyCollection<T> sC && target is IReadOnlyCollection<T> tC && sC.Count != tC.Count)
-			return false;
-
-		using IEnumerator<T>? enumSource = source.GetEnumerator();
-		using IEnumerator<T>? enumTarget = target.GetEnumerator();
-		while (enumSource.MoveNext() && enumTarget.MoveNext())
-		{
-			if (!enumSource.Current.Equals(enumTarget.Current))
-				return false;
-		}
-
-		return true;
+		// Both are not null, okay go.
+		return source.SequenceEqual(target);
 	}
 
 	/// <summary>
@@ -843,6 +806,9 @@ private class OrderByInfo
 	}
 	#endregion
 
+	/// <summary>
+	/// A nullable struct version of FirstOrDefault.
+	/// </summary>
 	public static T? NullableFirstOrDefault<T>(this IEnumerable<T> source)
 		where T : struct
 	{
@@ -854,6 +820,9 @@ private class OrderByInfo
 		return null;
 	}
 
+	/// <summary>
+	/// Rotates through each enumerable and returns the next value until none are left.
+	/// </summary>
 	public static IEnumerable<T> Weave<T>(this IEnumerable<IEnumerable<T>> source)
 	{
 		LinkedList<IEnumerator<T>>? queue = null;
@@ -1067,6 +1036,9 @@ public static IEnumerator<T> Preflight<T>(
 			yield return source.Current;
 	}
 
+	/// <summary>
+	/// Executes an action when the begins <paramref name="source"/> enumeration.
+	/// </summary>
 	public static IEnumerable<T> BeforeGetEnumerator<T>(
 		this IEnumerable<T> source,
 		Action before)

source/Open.Collections.csproj

@@ -18,7 +18,7 @@
 		<PackageProjectUrl>https://github.com/Open-NET-Libraries/Open.Collections/</PackageProjectUrl>
 		<RepositoryUrl>https://github.com/Open-NET-Libraries/Open.Collections/</RepositoryUrl>
 		<RepositoryType>git</RepositoryType>
-		<Version>3.2.0</Version>
+		<Version>4.0.0</Version>
 		<PackageReleaseNotes></PackageReleaseNotes>
 		<PackageLicenseExpression>MIT</PackageLicenseExpression>
 		<PublishRepositoryUrl>true</PublishRepositoryUrl>
@@ -42,16 +42,14 @@
 		  <Pack>True</Pack>
 		  <PackagePath>\</PackagePath>
 		</None>
-		<None Include="Extensions.ConcurrentBag.cs" />
-		<None Include="NonGeneric\Extensions.Synchronized.cs" />
 		<None Include="logo.png">
 			<Pack>True</Pack>
 			<PackagePath></PackagePath>
 		</None>		
 	</ItemGroup>
 
 	<ItemGroup>
-		<PackageReference Include="Open.Text" Version="8.1.0" />
+		<PackageReference Include="Open.Text" Version="8.2.1" />
 		<PackageReference Include="Open.Threading" Version="3.0.3" />
 		<PackageReference Include="System.Collections.Immutable" Version="9.0.0" />
 	</ItemGroup>

source/SortDirection.cs

@@ -1,7 +1,9 @@
 namespace Open.Collections;
 
+#pragma warning disable CS1591 // Missing XML comment for publicly visible type or member
 public enum SortDirection : sbyte
 {
 	Ascending = +1,
 	Descending = -1
 }
+#pragma warning restore CS1591 // Missing XML comment for publicly visible type or member

source/Subsets.cs

@@ -7,6 +7,9 @@
 
 namespace Open.Collections;
 
+/// <summary>
+/// Provides methods for generating subsets of a set.
+/// </summary>
 public static class Subsets
 {
 	internal static IEnumerable<int[]> IndexesInternal(int sourceLength, int subsetLength, int[] buffer)

source/Synchronized/ReadWriteSynchronizedCollectionWrapper.cs

@@ -8,17 +8,19 @@
 
 namespace Open.Collections.Synchronized;
 
-public class ReadWriteSynchronizedCollectionWrapper<T, TCollection>
-	: CollectionWrapper<T, TCollection>, ISynchronizedCollectionWrapper<T, TCollection>
+/// <summary>
+/// A disposable read-write synchronized wrapper for a collection.
+/// </summary>
+public class ReadWriteSynchronizedCollectionWrapper<T, TCollection>(
+	TCollection source, bool owner = false)
+	: CollectionWrapper<T, TCollection>(source, owner), ISynchronizedCollectionWrapper<T, TCollection>
 	where TCollection : class, ICollection<T>
 {
+	/// <summary>
+	/// The <see cref="ReaderWriterLockSlim"/> used for synchronization.
+	/// </summary>
 	protected ReaderWriterLockSlim RWLock = new(LockRecursionPolicy.SupportsRecursion); // Support recursion for read -> write locks.
 
-	protected ReadWriteSynchronizedCollectionWrapper(TCollection source, bool owner = false)
-		: base(source, owner)
-	{
-	}
-
 	#region Implementation of ICollection<T>
 
 	/// <inheritdoc />
@@ -118,10 +120,12 @@ public override Span<T> CopyTo(Span<T> span)
 	#endregion
 
 	#region Dispose
-	protected override void OnBeforeDispose() =>
+	/// <inheritdoc />
+	protected override void OnBeforeDispose()
 		// Give everything else a chance to finish up.
-		RWLock.TryWrite(1000, () => { });
+		=> RWLock.TryWrite(1000, () => { });
 
+	/// <inheritdoc />
 	protected override void OnDispose()
 	{
 		RWLock.Dispose();

testing/Open.Collections.Tests/BasicCollectionTests.cs

@@ -131,6 +131,7 @@ public void Contains()
 			Collection.Add(3);
 			search = 2;
 		}
+
 		Collection.Contains(search).Should().BeTrue();
 
 		if (Collection is not ISynchronizedCollectionWrapper<int, ICollection<int>> c) return;

testing/Open.Collections.Tests/PermutorTests.cs

@@ -1,7 +1,6 @@
 using System;
 using System.Collections.Generic;
 using System.Linq;
-using System.Numerics;
 using FluentAssertions;
 using Xunit;