Testing, fixes, and documentation.

Author: electricessence

Open.Collections.sln

@@ -7,6 +7,8 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Open.Collections", "source\
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Open.Collections.Tests", "testing\Open.Collections.Tests\Open.Collections.Tests.csproj", "{44063AEE-8909-4A26-80BE-8623F5EBBA1F}"
 EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Open.Collections.Benchmarking", "benchmarking\Open.Collections.Benchmarking.csproj", "{A3EA31B7-6E9B-4780-808A-BBDF116521EA}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -21,6 +23,10 @@ Global
 		{44063AEE-8909-4A26-80BE-8623F5EBBA1F}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{44063AEE-8909-4A26-80BE-8623F5EBBA1F}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{44063AEE-8909-4A26-80BE-8623F5EBBA1F}.Release|Any CPU.Build.0 = Release|Any CPU
+		{A3EA31B7-6E9B-4780-808A-BBDF116521EA}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{A3EA31B7-6E9B-4780-808A-BBDF116521EA}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{A3EA31B7-6E9B-4780-808A-BBDF116521EA}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{A3EA31B7-6E9B-4780-808A-BBDF116521EA}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE

benchmarking/Benchmarks/SubsetBenchmarks.cs

@@ -0,0 +1,27 @@
+using BenchmarkDotNet.Attributes;
+using System.Collections.Generic;
+using System.Linq;
+
+namespace Open.Collections.Benchmarks
+{
+	public class SubsetBenchmarks
+	{
+		readonly IEnumerable<int> FullSet = Enumerable.Range(0, 10);
+
+		[Benchmark]
+		public int Subset()
+		{
+			var buffer = new int[7];
+			var sum = FullSet.MemoizeUnsafe().Subsets(7, buffer).SelectMany(e => e).Sum();
+			return sum;
+		}
+
+		[Benchmark]
+		public int SubsetProgressive()
+		{
+			var buffer = new int[7];
+			var sum = FullSet.MemoizeUnsafe().SubsetsProgressive(7, buffer).SelectMany(e => e).Sum();
+			return sum;
+		}
+	}
+}

benchmarking/Open.Collections.Benchmarking.csproj

@@ -15,6 +15,12 @@
     <LangVersion>latest</LangVersion>
   </PropertyGroup>
 
+  <ItemGroup>
+    <Compile Remove="BenchmarkDotNet.Artifacts\**" />
+    <EmbeddedResource Remove="BenchmarkDotNet.Artifacts\**" />
+    <None Remove="BenchmarkDotNet.Artifacts\**" />
+  </ItemGroup>
+
   <ItemGroup>
     <PackageReference Include="BenchmarkDotNet" Version="0.13.0" />
     <PackageReference Include="Open.Diagnostics" Version="1.4.1" />

benchmarking/Program.cs

@@ -1,27 +1,19 @@
-using Open.Collections;
+using BenchmarkDotNet.Running;
+using Open.Collections;
+using Open.Collections.Benchmarks;
 using Open.Collections.Synchronized;
 using Open.Diagnostics;
 using System;
 using System.Collections.Generic;
 using System.Diagnostics;
+using System.Linq;
 using System.Threading.Tasks;
 
 internal class Program
 {
 	static void Main()
 	{
-		Console.Clear();
-		var perms = new char[] { 'A', 'B', 'C' }.Permutations(new char[3]);
-		foreach (var p in perms)
-		{
-			Console.WriteLine(new string(p));
-		}
-
-		//var combs = new Open.Collections.Benchmarking.Combinations();
-		//OutputList(combs.AllPossible());
-		//OutputList(combs.Subsets());
-
-		//BenchmarkRunner.Run<Open.Collections.Benchmarking.Combinations>();
+		BenchmarkRunner.Run<SubsetBenchmarks>();
 
 		//TestEntry.Test1();
 		//TestEntry.Test2();

source/Extensions.Combinations.cs

@@ -9,7 +9,7 @@ namespace Open.Collections
 {
 	public static partial class Extensions
 	{
-		static IEnumerable<T[]> CombinationsCore<T>(IReadOnlyList<T> source, int length, bool distinctSet, T[]? buffer = null)
+		static IEnumerable<T[]> CombinationsCore<T>(IReadOnlyList<T> source, int length, bool distinctSet, T[] buffer)
 		{
 			Debug.Assert(length != 0);
 			var count = source.Count;
@@ -59,12 +59,11 @@ bool GetNext()
 
 				while (GetNext())
 				{
-					var result = buffer ?? new T[length];
 					for (var i = 0; i < length; i++)
 					{
-						result[i] = source[indexes[i]];
+						buffer![i] = source[indexes[i]];
 					}
-					yield return result;
+					yield return buffer!;
 				}
 			}
 			finally
@@ -73,17 +72,25 @@ bool GetNext()
 			}
 		}
 
-		/// <summary>
-		/// Enumerates all possible combinations of values.
-		/// Results can be different permutations of another set.
-		/// 
-		/// Example:
-		/// [0, 0], [0, 1], [1, 0], [1, 1] where [0, 1] and [1, 0] are a different permutatation of the same set.
-		/// </summary>
-		/// <param name="elements">The elements to draw from.</param>
-		/// <param name="length">The length of each result.</param>
-		/// <param name="buffer">An optional buffer that is filled with the values and returned as the yielded value instead of a new array</param>
-		public static IEnumerable<T[]> Combinations<T>(this IEnumerable<T> elements, int length, T[]? buffer = null)
+		static IEnumerable<T[]> CombinationsCore<T>(IReadOnlyList<T> source, int length, bool distinctSet)
+		{
+			var pool = ArrayPool<T>.Shared;
+			var buffer = pool.Rent(length);
+			try
+			{
+				foreach (var b in CombinationsCore(source, length,distinctSet, buffer))
+					yield return b;
+			}
+			finally
+			{
+				pool.Return(buffer, true);
+			}
+		}
+	
+
+		/// <inheritdoc cref="Combinations{T}(IEnumerable{T}, int)"/>
+		/// <param name="buffer">A buffer that is filled with the values and returned as the yielded value instead of a new array.</param>
+		public static IEnumerable<T[]> Combinations<T>(this IEnumerable<T> elements, int length, T[] buffer)
 		{
 			if (elements is null)
 				throw new ArgumentNullException(nameof(elements));
@@ -96,17 +103,10 @@ public static IEnumerable<T[]> Combinations<T>(this IEnumerable<T> elements, int
 			return source.Count == 0 ? Enumerable.Empty<T[]>() : CombinationsCore(source, length, false, buffer);
 		}
 
-		/// <summary>
-		/// Enumerates all possible distinct set combinations.
-		/// A set that has its items reordered is not distinct from the original.
-		/// 
-		/// Example:
-		/// [0, 0], [0, 1], [1, 1] where [1, 0] is not included as it is not a disticnt set from [0, 1].
-		/// </summary>
-		/// <param name="elements">The elements to draw from.</param>
-		/// <param name="length">The length of each result.</param>
+
+		/// <inheritdoc cref="CombinationsDistinct{T}(IEnumerable{T}, int)"/>
 		/// <param name="buffer">An optional buffer that is filled with the values and returned as the yielded value instead of a new array</param>
-		public static IEnumerable<T[]> CombinationsDistinct<T>(this IEnumerable<T> elements, int length, T[]? buffer = null)
+		public static IEnumerable<T[]> CombinationsDistinct<T>(this IEnumerable<T> elements, int length, T[] buffer)
 		{
 			if (elements is null)
 				throw new ArgumentNullException(nameof(elements));
@@ -133,69 +133,105 @@ public static IEnumerable<T[]> Combinations<T>(this IEnumerable<T> elements, int
 			var count = source.Count;
 			if (count == 0) return Enumerable.Empty<T[]>();
 
-			return uniqueOnly ? source.Subsets(length) : CombinationsCore(source, length, true);
+			if (uniqueOnly) return source.Subsets(length);
+			return uniqueOnly ? source.Subsets(length) : CombinationsCore(source, length, true).Select(e=>e.AsCopy(length));
 		}
 
-		/// <summary>
-		/// Enumerates all possible (order retained) combinations of the source elements up to the length.
-		/// </summary>
-		/// <param name="elements">The elements to draw from.</param>
-		/// <param name="length">The length of each result.</param>
-		public static IEnumerable<T[]> CombinationsBuffered<T>(this IEnumerable<T> elements, int length)
+		/// <inheritdoc cref="Combinations{T}(IEnumerable{T}, int)"/>
+		/// <remarks>Values are yielded as read only memory buffer that should not be retained as its array is returned to pool afterwards.</remarks>
+		/// <returns>An enumerable the yields as read only memory buffer that should not be retained as its array is returned to pool afterwards.</returns>
+		public static IEnumerable<ReadOnlyMemory<T>> CombinationsBuffered<T>(this IEnumerable<T> elements, int length)
 		{
 			if (elements is null)
 				throw new ArgumentNullException(nameof(elements));
 			if (length < 0)
 				throw new ArgumentOutOfRangeException(nameof(length), length, "Cannot be less than zero.");
 			Contract.EndContractBlock();
 
-			if (length == 0)
+			if (length == 0) yield break;
+
+			var pool = ArrayPool<T>.Shared;
+			var buffer = pool.Rent(length);
+			var readBuffer = new ReadOnlyMemory<T>(buffer, 0, length);
+			try
+			{
+				foreach (var _ in Combinations(elements, length, buffer))
+					yield return readBuffer;
+			}
+			finally
 			{
-				yield break;
+				pool.Return(buffer, true);
 			}
+		}
+
+
+		/// <inheritdoc cref="CombinationsDistinct{T}(IEnumerable{T}, int)"/>
+		/// <remarks>Values are yielded as read only memory buffer that should not be retained as its array is returned to pool afterwards.</remarks>
+		/// <returns>An enumerable the yields as read only memory buffer that should not be retained as its array is returned to pool afterwards.</returns>
+		public static IEnumerable<ReadOnlyMemory<T>> CombinationsDistinctBuffered<T>(this IEnumerable<T> elements, int length)
+		{
+			if (elements is null)
+				throw new ArgumentNullException(nameof(elements));
+			if (length < 0)
+				throw new ArgumentOutOfRangeException(nameof(length), length, "Cannot be less than zero.");
+			Contract.EndContractBlock();
+
+			if (length == 0) yield break;
 
 			var pool = ArrayPool<T>.Shared;
 			var buffer = pool.Rent(length);
+			var readBuffer = new ReadOnlyMemory<T>(buffer, 0, length);
 			try
 			{
-				foreach (var c in Combinations(elements, length, buffer))
-					yield return c;
+				foreach (var _ in CombinationsDistinct(elements, length, buffer))
+					yield return readBuffer;
 			}
 			finally
 			{
 				pool.Return(buffer, true);
 			}
 		}
 
+		/// <inheritdoc cref="Combinations{T}(IEnumerable{T})"/>
+		/// <param name="length">The length of each result.</param>
+		public static IEnumerable<T[]> Combinations<T>(this IEnumerable<T> elements, int length)
+		{
+			foreach (var c in CombinationsBuffered(elements, length))
+				yield return c.ToArray();
+		}
+
+		/// <inheritdoc cref="CombinationsDistinct{T}(IEnumerable{T})"/>
+		/// <param name="length">The length of each result.</param>
+		public static IEnumerable<T[]> CombinationsDistinct<T>(this IEnumerable<T> elements, int length)
+		{
+			foreach (var c in CombinationsDistinctBuffered(elements, length))
+				yield return c.ToArray();
+		}
+
 
 		/// <summary>
 		/// Enumerates all possible combinations of values.
 		/// Results can be different permutations of another set.
-		/// Examples:
-		/// [0, 0], [0, 1], [1, 0], [1, 1] where [0, 1] and [1, 0] are a different permutatation of the same set.
 		/// </summary>
-		/// <param name="elements">The elements to draw from.</param>\
+		/// <example>[0, 0], [0, 1], [1, 0], [1, 1] where [0, 1] and [1, 0] are a different permutatation of the same set.</example>
+		/// <param name="elements">The elements to draw from.</param>
 		public static IEnumerable<T[]> Combinations<T>(this IEnumerable<T> elements)
 		{
-			if (elements is null)
-				throw new ArgumentNullException(nameof(elements));
+			if (elements is null) throw new ArgumentNullException(nameof(elements));
 			Contract.EndContractBlock();
 			var source = elements as IReadOnlyList<T> ?? elements.ToArray();
 			return source.Count == 0 ? Enumerable.Empty<T[]>() : Combinations(source, source.Count);
 		}
 
 		/// <summary>
 		/// Enumerates all possible distinct set combinations.
-		/// A set that has its items reordered is not distinct from the original.
-		/// Examples:
-		/// [0, 0], [0, 1], [1, 1] where [1, 0] is not included as it is not a disticnt set from [0, 1].
-		///
+		/// In contrast a set that has its items reordered is not distinct from the original.
 		/// </summary>
+		/// <example>[0, 0], [0, 1], [1, 1] where [1, 0] is not included as it is not a disticnt set from [0, 1].</example>
 		/// <param name="elements">The elements to draw from.</param>
 		public static IEnumerable<T[]> CombinationsDistinct<T>(this IEnumerable<T> elements)
 		{
-			if (elements is null)
-				throw new ArgumentNullException(nameof(elements));
+			if (elements is null) throw new ArgumentNullException(nameof(elements));
 			Contract.EndContractBlock();
 			var source = elements as IReadOnlyList<T> ?? elements.ToArray();
 			return source.Count == 0 ? Enumerable.Empty<T[]>() : CombinationsDistinct(source, source.Count);