ShuffleHelpers Class

Definition

Namespace

Bodu.Collections.Generic

Assembly

Bodu.Core.dll

Package

Bodu.Core 1.0.1

Source

ShuffleHelpers.Shuffle.cs

Provides in-place and yield-based Fisher-Yates randomization over arrays, spans, memory regions, and arbitrary IEnumerable<T> sources.

public static class ShuffleHelpers

Inheritance

object

ShuffleHelpers

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Examples

// Deterministic shuffle of an array - useful for tests and reproducible demos.
var deck = Enumerable.Range(1, 52).ToArray();
IRandomGenerator rng = new XorShiftRandom(seed: 42);
ShuffleHelpers.Shuffle(deck, rng);

// Sample five cards without replacement using the yield-based overload.
foreach (int card in ShuffleHelpers.ShuffleAndYield(deck, rng, count: 5))
    Console.WriteLine(card);

Remarks

The helpers implement the canonical Fisher-Yates (Knuth) shuffle: each position from the end of the live region down to index 1 swaps with a uniformly chosen earlier position. The resulting permutation is uniform when the supplied IRandomGenerator produces uniform draws over [0, exclusiveMax).

Two surface shapes are exposed. Shuffle mutates the supplied buffer in place and runs in O(n) time with no extra allocation. ShuffleAndYield produces a deferred sequence of the shuffled elements; the count overloads short-circuit after the first count draws and are equivalent to a partial Fisher-Yates - useful for sampling-without-replacement when only a prefix of the shuffle is needed.

Randomness quality is delegated entirely to the caller-supplied IRandomGenerator. For deterministic shuffles in tests pass a seeded generator (such as XorShiftRandom with a fixed seed); for production shuffling pass any non-cryptographic generator. None of these helpers are suitable for use in cryptographic permutations, key shuffling, or any context where an attacker can observe outputs and recover state.

Methods

ShuffleAndYield<T>(IEnumerable<T>, IRandomGenerator)

Lazily yields a fully shuffled sequence from the given source.

public static IEnumerable<T> ShuffleAndYield<T>(IEnumerable<T> source, IRandomGenerator rng)

Parameters

source IEnumerable<T>

The source sequence to shuffle.

rng IRandomGenerator

The random number generator.

Returns

IEnumerable<T>

A lazily-evaluated, fully shuffled sequence.

Type Parameters

T

The element type.

Remarks

The source is enumerated exactly once, when the result is first iterated - safe for one-shot sequences and sequences with side effects.

Exceptions

ArgumentNullException

Thrown when source or rng is null.

ShuffleAndYield<T>(IEnumerable<T>, IRandomGenerator, int)

Lazily yields a randomized subset of an IEnumerable<T> using a partial Fisher-Yates shuffle.

public static IEnumerable<T> ShuffleAndYield<T>(IEnumerable<T> source, IRandomGenerator rng, int count)

Parameters

source IEnumerable<T>

The source sequence to shuffle.

rng IRandomGenerator

The random number generator used to select shuffled items.

count int

The number of elements to yield from the shuffled source.

Returns

IEnumerable<T>

A lazily-evaluated sequence of randomly selected items from the source.

Type Parameters

T

The type of elements in the source sequence.

Remarks

Enumeration of source and shuffling are deferred until the result is first iterated. The entire source is buffered in memory before shuffling begins. The original sequence is not modified.

Exceptions

ArgumentNullException

Thrown when source or rng is null.

ArgumentOutOfRangeException

Thrown immediately if count is negative.

ArgumentOutOfRangeException

May be thrown upon first enumeration if count exceeds the total number of elements in source.

ShuffleAndYield<T>(Memory<T>, IRandomGenerator)

Yields a fully shuffled copy of the memory block.

public static IEnumerable<T> ShuffleAndYield<T>(Memory<T> memory, IRandomGenerator rng)

Parameters

memory Memory<T>

The memory block to shuffle.

rng IRandomGenerator

The random number generator.

Returns

IEnumerable<T>

A shuffled sequence from the memory block.

Type Parameters

T

The element type.

ShuffleAndYield<T>(Memory<T>, IRandomGenerator, int)

Yields a randomized subset of a Memory<T> block using a copied buffer and array shuffle.

public static IEnumerable<T> ShuffleAndYield<T>(Memory<T> memory, IRandomGenerator rng, int count)

Parameters

memory Memory<T>

The memory block to shuffle.

rng IRandomGenerator

The random number generator to use.

count int

The number of elements to yield.

Returns

IEnumerable<T>

A sequence of shuffled items from the memory block.

Type Parameters

T

The type of elements in memory.

Remarks

This method eagerly copies memory into a new array, which is then shuffled.

ShuffleAndYield<T>(ReadOnlySpan<T>, IRandomGenerator)

Yields a fully shuffled copy of the span.

public static IEnumerable<T> ShuffleAndYield<T>(ReadOnlySpan<T> span, IRandomGenerator rng)

Parameters

span ReadOnlySpan<T>

The span to shuffle.

rng IRandomGenerator

The random number generator.

Returns

IEnumerable<T>

A shuffled sequence from the span.

Type Parameters

T

The element type.

ShuffleAndYield<T>(ReadOnlySpan<T>, IRandomGenerator, int)

Yields a randomized subset of a ReadOnlySpan<T> using a copied buffer and array shuffle.

public static IEnumerable<T> ShuffleAndYield<T>(ReadOnlySpan<T> span, IRandomGenerator rng, int count)

Parameters

span ReadOnlySpan<T>

The span to shuffle.

rng IRandomGenerator

The random number generator to use.

count int

The number of elements to yield.

Returns

IEnumerable<T>

A sequence of shuffled items from the span.

Type Parameters

T

The type of elements in the span.

Remarks

This method eagerly copies span into a new array, which is then shuffled.

ShuffleAndYield<T>(T[], IRandomGenerator)

Yields a fully shuffled copy of the array.

public static IEnumerable<T> ShuffleAndYield<T>(T[] array, IRandomGenerator rng)

Parameters

array T[]

The array to shuffle.

rng IRandomGenerator

The random number generator.

Returns

IEnumerable<T>

A shuffled sequence based on the array.

Type Parameters

T

The element type.

Exceptions

ArgumentNullException

Thrown when array is null.

ShuffleAndYield<T>(T[], IRandomGenerator, int)

Yields a randomized subset of the specified array by copying and shuffling it using a partial Fisher-Yates algorithm.

public static IEnumerable<T> ShuffleAndYield<T>(T[] array, IRandomGenerator rng, int count)

Parameters

array T[]

The source array to shuffle. The original array is not modified.

rng IRandomGenerator

The random number generator used for shuffling.

count int

The number of elements to yield.

Returns

IEnumerable<T>

A sequence of randomly selected elements from the array.

Type Parameters

T

The type of elements in the array.

Remarks

The input array is copied before shuffling to ensure immutability of the original. Use this method when working with arrays and requiring source preservation. Argument validation runs eagerly at the call site; copying and shuffling are deferred until the result is first iterated.

Exceptions

ArgumentNullException

Thrown when array or rng is null.

ArgumentOutOfRangeException

Thrown if count is negative or exceeds the array length.

Shuffle<T>(Memory<T>, IRandomGenerator)

Performs an in-place Fisher-Yates shuffle over a memory region.

public static void Shuffle<T>(Memory<T> memory, IRandomGenerator rng)

Parameters

memory Memory<T>

The memory region to shuffle.

rng IRandomGenerator

The random number generator used to shuffle elements.

Type Parameters

T

The type of the elements in the memory block.

Remarks

This method shuffles the contents of the memory region in-place by accessing its underlying span. The original memory region is modified.

Exceptions

ArgumentNullException

Thrown if rng is null.

Shuffle<T>(Span<T>, IRandomGenerator)

Performs an in-place Fisher-Yates shuffle over a span of elements.

public static void Shuffle<T>(Span<T> span, IRandomGenerator rng)

Parameters

span Span<T>

The span of elements to shuffle.

rng IRandomGenerator

The random number generator used to shuffle elements.

Type Parameters

T

The type of the elements in the span.

Remarks

This method modifies the span in-place using the Fisher-Yates algorithm. It is optimized for shuffling stack-allocated or pooled data, and does not allocate memory.

Exceptions

ArgumentNullException

Thrown if rng is null.

Shuffle<T>(T[], IRandomGenerator)

Performs an in-place Fisher-Yates shuffle over the provided array.

public static void Shuffle<T>(T[] array, IRandomGenerator rng)

Parameters

array T[]

The array of elements to shuffle.

rng IRandomGenerator

The random number generator used to shuffle elements.

Type Parameters

T

The type of the elements in the array.

Remarks

This method modifies the original array using the Fisher-Yates algorithm. Each element has an equal probability of ending up in any position.

Exceptions

ArgumentNullException

Thrown if array or rng is null.

Applies to

Product	Versions
.NET	8, 10