Added read only collection extensions.

Author: Oren (electricessence)

Open.RandomizationExtensions.csproj

@@ -14,7 +14,7 @@ Part of the "Open" set of libraries.</Description>
     <RepositoryUrl>https://github.com/electricessence/Open.RandomizationExtensions</RepositoryUrl>
     <RepositoryType>Git</RepositoryType>
     <PackageTags>random select</PackageTags>
-    <Version>1.0.1</Version>
+    <Version>1.1.0</Version>
   </PropertyGroup>
 
   <ItemGroup>

Random.cs

@@ -177,17 +177,9 @@ public static int RandomSelectIndex<T>(this in ReadOnlySpan<T> source, IEnumerab
 		public static int RandomSelectIndex<T>(this in Span<T> source, IEnumerable<T> exclusion = null)
 			=> RandomSelectIndex((ReadOnlySpan<T>)source, exclusion);
 
-		/// <summary>
-		/// Randomly selects an index from the source.
-		/// Will not return indexes that are contained in the optional exclusion set.
-		/// </summary>
-		/// <typeparam name="T">The generic type of the source.</typeparam>
-		/// <param name="source">The source collection.</param>
-		/// <param name="exclusion">The optional values to exclude from selection.</param>
-		/// <returns>The index selected.</returns>
-		public static int RandomSelectIndex<T>(this ICollection<T> source, IEnumerable<T> exclusion = null)
+		static int RandomSelectIndex<T>(int count, IEnumerable<T> source, IEnumerable<T> exclusion)
 		{
-			if (source.Count == 0)
+			if (count == 0)
 				return -1;
 
 			HashSet<T> setCreated = null;
@@ -197,9 +189,9 @@ public static int RandomSelectIndex<T>(this ICollection<T> source, IEnumerable<T
 				: exclusion as ISet<T> ?? (setCreated = new HashSet<T>(exclusion));
 
 				if (exclusionSet == null || exclusionSet.Count == 0)
-					return R.Value.Next(source.Count);
+					return R.Value.Next(count);
 
-				using (var indexesTemp = ArrayPool<int>.Shared.RentDisposable(source.Count))
+				using (var indexesTemp = ArrayPool<int>.Shared.RentDisposable(count))
 				{
 					var indexes = indexesTemp.Array;
 					var i = -1;
@@ -219,6 +211,28 @@ public static int RandomSelectIndex<T>(this ICollection<T> source, IEnumerable<T
 			}
 		}
 
+		/// <summary>
+		/// Randomly selects an index from the source.
+		/// Will not return indexes that are contained in the optional exclusion set.
+		/// </summary>
+		/// <typeparam name="T">The generic type of the source.</typeparam>
+		/// <param name="source">The source collection.</param>
+		/// <param name="exclusion">The optional values to exclude from selection.</param>
+		/// <returns>The index selected.</returns>
+		public static int RandomSelectIndex<T>(this IReadOnlyCollection<T> source, IEnumerable<T> exclusion = null)
+			=> RandomSelectIndex(source.Count, source, exclusion);
+
+		/// <summary>
+		/// Randomly selects an index from the source.
+		/// Will not return indexes that are contained in the optional exclusion set.
+		/// </summary>
+		/// <typeparam name="T">The generic type of the source.</typeparam>
+		/// <param name="source">The source collection.</param>
+		/// <param name="exclusion">The optional values to exclude from selection.</param>
+		/// <returns>The index selected.</returns>
+		public static int RandomSelectIndex<T>(this ICollection<T> source, IEnumerable<T> exclusion = null)
+			=> RandomSelectIndex(source.Count, source, exclusion);
+
 		/// <summary>
 		/// Randomly selects an index from the source.
 		/// Will not return indexes that are contained in the optional exclusion set.
@@ -272,34 +286,25 @@ public static int RandomSelectIndexExcept<T>(this in ReadOnlySpan<T> source, T e
 		public static int RandomSelectIndexExcept<T>(this in Span<T> source, T exclusion, params T[] others)
 			=> RandomSelectIndexExcept((ReadOnlySpan<T>)source, exclusion, others);
 
-		/// <summary>
-		/// Randomly selects an index from the source.
-		/// Will not return indexes that are contained in the optional exclusion set.
-		/// </summary>
-		/// <typeparam name="T">The generic type of the source.</typeparam>
-		/// <param name="source">The source collection.</param>
-		/// <param name="exclusion">A value to exclude from selection.</param>
-		/// <param name="others">The additional set of optional values to exclude from selection.</param>
-		/// <returns>The index selected.</returns>
-		public static int RandomSelectIndexExcept<T>(this ICollection<T> source, T exclusion, params T[] others)
+		static int RandomSelectIndexExcept<T>(int count, IEnumerable<T> source, T exclusion, T[] others)
 		{
-			if (source.Count == 0)
+			if (count == 0)
 				return -1;
 
 			if (others.Length != 0)
 			{
 				var setCreated = new HashSet<T>(others) { exclusion };
 				try
 				{
-					return RandomSelectIndex(source, setCreated);
+					return RandomSelectIndex(count, source, setCreated);
 				}
 				finally
 				{
 					setCreated.Clear();
 				}
 			}
 
-			using (var indexesTemp = ArrayPool<int>.Shared.RentDisposable(source.Count))
+			using (var indexesTemp = ArrayPool<int>.Shared.RentDisposable(count))
 			{
 				var indexes = indexesTemp.Array;
 				var i = -1;
@@ -314,6 +319,30 @@ public static int RandomSelectIndexExcept<T>(this ICollection<T> source, T exclu
 			}
 		}
 
+		/// <summary>
+		/// Randomly selects an index from the source.
+		/// Will not return indexes that are contained in the optional exclusion set.
+		/// </summary>
+		/// <typeparam name="T">The generic type of the source.</typeparam>
+		/// <param name="source">The source collection.</param>
+		/// <param name="exclusion">A value to exclude from selection.</param>
+		/// <param name="others">The additional set of optional values to exclude from selection.</param>
+		/// <returns>The index selected.</returns>
+		public static int RandomSelectIndexExcept<T>(this IReadOnlyCollection<T> source, T exclusion, params T[] others)
+			=> RandomSelectIndexExcept(source.Count, source, exclusion, others);
+
+		/// <summary>
+		/// Randomly selects an index from the source.
+		/// Will not return indexes that are contained in the optional exclusion set.
+		/// </summary>
+		/// <typeparam name="T">The generic type of the source.</typeparam>
+		/// <param name="source">The source collection.</param>
+		/// <param name="exclusion">A value to exclude from selection.</param>
+		/// <param name="others">The additional set of optional values to exclude from selection.</param>
+		/// <returns>The index selected.</returns>
+		public static int RandomSelectIndexExcept<T>(this ICollection<T> source, T exclusion, params T[] others)
+			=> RandomSelectIndexExcept(source.Count, source, exclusion, others);
+
 		/// <summary>
 		/// Attempts to select an index at random from the source and returns the value from it..
 		/// Will not select indexes that are contained in the optional exclusion set.
@@ -354,6 +383,30 @@ public static bool TryRandomSelectOne<T>(
 			IEnumerable<T> exclusion = null)
 			=> TryRandomSelectOne((ReadOnlySpan<T>)source, out value, exclusion);
 
+		/// <summary>
+		/// Selects an index at random from the source and returns the value from it.
+		/// Will not select indexes that are contained in the optional exclusion set.
+		/// </summary>
+		/// <typeparam name="T">The generic type of the source.</typeparam>
+		/// <param name="source">The source span.</param>
+		/// <param name="exclusion">The optional values to exclude from selection.</param>
+		/// <returns>The value selected.</returns>
+		public static T RandomSelectOne<T>(
+			this IReadOnlyCollection<T> source,
+			IEnumerable<T> exclusion = null)
+		{
+			if (source.Count == 0)
+				throw new InvalidOperationException("Source collection is empty.");
+
+			var index = RandomSelectIndex(source, exclusion);
+			if (index == -1)
+				throw new InvalidOperationException("Exclusion set invalidates the source.  No possible value can be selected.");
+
+			return source is IReadOnlyList<T> list
+				? list[index]
+				: source.ElementAt(index);
+		}
+
 		/// <summary>
 		/// Selects an index at random from the source and returns the value from it.
 		/// Will not select indexes that are contained in the optional exclusion set.
@@ -378,6 +431,34 @@ public static T RandomSelectOne<T>(
 				: source.ElementAt(index);
 		}
 
+		/// <summary>
+		/// Attempts to select an index at random from the source and returns the value from it..
+		/// Will not select indexes that are contained in the optional exclusion set.
+		/// </summary>
+		/// <typeparam name="T">The generic type of the source.</typeparam>
+		/// <param name="source">The source collection.</param>
+		/// <param name="value">The value selected.</param>
+		/// <param name="exclusion">The optional values to exclude from selection.</param>
+		/// <returns>True if a valid value was selected.</returns>
+		public static bool TryRandomSelectOne<T>(
+			this IReadOnlyCollection<T> source,
+			out T value,
+			IEnumerable<T> exclusion = null)
+		{
+			var index = RandomSelectIndex(source, exclusion);
+			if (index == -1)
+			{
+				value = default;
+				return false;
+			}
+
+			value = source is IReadOnlyList<T> list
+				? list[index]
+				: source.ElementAt(index);
+
+			return true;
+		}
+
 		/// <summary>
 		/// Attempts to select an index at random from the source and returns the value from it..
 		/// Will not select indexes that are contained in the optional exclusion set.
@@ -458,7 +539,35 @@ public static bool TryRandomSelectOneExcept<T>(
 		/// <param name="excluding">The value to exclude from selection.</param>
 		/// <param name="others">The additional set of optional values to exclude from selection.</param>
 		/// <returns>True if a valid value was selected.</returns>
+		public static bool TryRandomSelectOneExcept<T>(
+			this IReadOnlyCollection<T> source,
+			out T value,
+			T excluding, params T[] others)
+		{
+			var index = RandomSelectIndexExcept(source, excluding, others);
+			if (index == -1)
+			{
+				value = default;
+				return false;
+			}
+
+			value = source is IReadOnlyList<T> list
+				? list[index]
+				: source.ElementAt(index);
 
+			return true;
+		}
+
+		/// <summary>
+		/// Attempts to select an index at random from the source and returns the value from it..
+		/// Will not select indexes that are contained in the optional exclusion set.
+		/// </summary>
+		/// <typeparam name="T">The generic type of the source.</typeparam>
+		/// <param name="source">The source collection.</param>
+		/// <param name="value">The value selected.</param>
+		/// <param name="excluding">The value to exclude from selection.</param>
+		/// <param name="others">The additional set of optional values to exclude from selection.</param>
+		/// <returns>True if a valid value was selected.</returns>
 		public static bool TryRandomSelectOneExcept<T>(
 			this ICollection<T> source,
 			out T value,
@@ -514,6 +623,28 @@ public static T RandomSelectOneExcept<T>(
 			T excluding, params T[] others)
 			=> RandomSelectOneExcept((ReadOnlySpan<T>)source, excluding, others);
 
+		/// <summary>
+		/// Selects an index at random from the source and returns the value from it.
+		/// Will not select indexes that are contained in the optional exclusion set.
+		/// </summary>
+		/// <typeparam name="T">The generic type of the source.</typeparam>
+		/// <param name="source">The source collection.</param>
+		/// <param name="excluding">The value to exclude from selection.</param>
+		/// <param name="others">The additional set of optional values to exclude from selection.</param>
+		/// <returns>The value selected.</returns>
+		public static T RandomSelectOneExcept<T>(
+			this IReadOnlyCollection<T> source,
+			T excluding, params T[] others)
+		{
+			if (source.Count == 0)
+				throw new InvalidOperationException("Source collection is empty.");
+
+			if (source.TryRandomSelectOneExcept(out T value, excluding, others))
+				return value;
+
+			throw new InvalidOperationException("Exclusion set invalidates the source.  No possible value can be selected.");
+		}
+
 		/// <summary>
 		/// Selects an index at random from the source and returns the value from it.
 		/// Will not select indexes that are contained in the optional exclusion set.