RandomNumberGeneratorExtensions.cs

using System.Collections;
using System.Numerics;
using System.Security.Cryptography;

namespace BytecodeApi.Extensions;

/// <summary>
/// Provides a set of <see langword="static" /> methods for interaction with <see cref="RandomNumberGenerator" /> objects.
/// </summary>
public static class RandomNumberGeneratorExtensions
{
	private static readonly RandomNumberGenerator _Shared = RandomNumberGenerator.Create();

	extension(RandomNumberGenerator)
	{
		/// <summary>
		/// Provides a thread-safe <see cref="RandomNumberGenerator" /> instance that may be used concurrently from any thread.
		/// </summary>
		public static RandomNumberGenerator Shared => _Shared;
	}

	extension(RandomNumberGenerator randomNumberGenerator)
	{
		/// <summary>
		/// Creates a <see cref="byte" />[] with a specified length and fills all elements with a cryptographically strong random sequence of bytes.
		/// </summary>
		/// <param name="count">The size of the returned <see cref="byte" />[].</param>
		/// <returns>
		/// A new <see cref="byte" />[] with a specified length, filled with a cryptographically strong random sequence of bytes.
		/// </returns>
		public byte[] GetBytes(int count)
		{
			Check.ArgumentNull(randomNumberGenerator);
			Check.ArgumentOutOfRangeEx.GreaterEqual0(count);

			byte[] data = new byte[count];
			randomNumberGenerator.GetBytes(data);
			return data;
		}
		/// <summary>
		/// Creates a <see cref="byte" />[] with a specified length and fills all elements with a cryptographically strong random sequence of nonzero bytes.
		/// </summary>
		/// <param name="count">The size of the returned <see cref="byte" />[].</param>
		/// <returns>
		/// A new <see cref="byte" />[] with a specified length, filled with a cryptographically strong random sequence of nonzero bytes.
		/// </returns>
		public byte[] GetNonZeroBytes(int count)
		{
			Check.ArgumentNull(randomNumberGenerator);
			Check.ArgumentOutOfRangeEx.GreaterEqual0(count);

			byte[] data = new byte[count];
			randomNumberGenerator.GetNonZeroBytes(data);
			return data;
		}
		/// <summary>
		/// Generates a cryptographically strong random <see cref="bool" /> value that is either <see langword="false" /> or <see langword="true" />.
		/// </summary>
		/// <returns>
		/// A cryptographically strong random <see cref="bool" /> value that is either <see langword="false" /> or <see langword="true" />.
		/// </returns>
		public bool GetBoolean()
		{
			Check.ArgumentNull(randomNumberGenerator);

			return (randomNumberGenerator.GetByte() & 1) == 1;
		}
		/// <summary>
		/// Generates a cryptographically strong random <see cref="byte" /> value that is greater than or equal to 0, and less than or equal to <see cref="byte.MaxValue" />.
		/// </summary>
		/// <returns>
		/// A cryptographically strong random <see cref="byte" /> value that is greater than or equal to 0, and less than or equal to <see cref="byte.MaxValue" />.
		/// </returns>
		public byte GetByte()
		{
			Check.ArgumentNull(randomNumberGenerator);

			return randomNumberGenerator.GetBytes(1)[0];
		}
		/// <summary>
		/// Generates a cryptographically strong random nonzero <see cref="byte" /> value that is less than or equal to <see cref="byte.MaxValue" />.
		/// </summary>
		/// <returns>
		/// A cryptographically strong random nonzero <see cref="byte" /> value that is less than or equal to <see cref="byte.MaxValue" />.
		/// </returns>
		public byte GetNonZeroByte()
		{
			Check.ArgumentNull(randomNumberGenerator);

			return randomNumberGenerator.GetNonZeroBytes(1)[0];
		}
		/// <summary>
		/// Generates a cryptographically strong random <see cref="sbyte" /> value that is greater than or equal to <see cref="sbyte.MinValue" />, and less than or equal to <see cref="sbyte.MaxValue" />.
		/// </summary>
		/// <returns>
		/// A cryptographically strong random <see cref="sbyte" /> value that is greater than or equal to <see cref="sbyte.MinValue" />, and less than or equal to <see cref="sbyte.MaxValue" />.
		/// </returns>
		public sbyte GetSByte()
		{
			Check.ArgumentNull(randomNumberGenerator);

			return (sbyte)(randomNumberGenerator.GetByte() - 128);
		}
		/// <summary>
		/// Generates a cryptographically strong random <see cref="char" /> value that is greater than or equal to '\0', and less than or equal to <see cref="char.MaxValue" />.
		/// </summary>
		/// <returns>
		/// A cryptographically strong random <see cref="char" /> value that is greater than or equal to '\0', and less than or equal to <see cref="char.MaxValue" />.
		/// </returns>
		public char GetChar()
		{
			Check.ArgumentNull(randomNumberGenerator);

			return BitConverter.ToChar(randomNumberGenerator.GetBytes(2), 0);
		}
		/// <summary>
		/// Generates a cryptographically strong random <see cref="int" /> value that is greater than or equal to <see cref="int.MinValue" />, and less than or equal to <see cref="int.MaxValue" />.
		/// </summary>
		/// <returns>
		/// A cryptographically strong random <see cref="int" /> value that is greater than or equal to <see cref="int.MinValue" />, and less than or equal to <see cref="int.MaxValue" />.
		/// </returns>
		public int GetInt32()
		{
			Check.ArgumentNull(randomNumberGenerator);

			return BitConverter.ToInt32(randomNumberGenerator.GetBytes(4), 0);
		}
		/// <summary>
		/// Generates a cryptographically strong random <see cref="int" /> value that is less than the specified maximum.
		/// </summary>
		/// <param name="maxValue">The exclusive upper bound of the random number to be generated. <paramref name="maxValue" /> must be greater than or equal to 0.</param>
		/// <returns>
		/// A cryptographically strong random <see cref="int" /> value that is less than the specified maximum.
		/// </returns>
		public int GetInt32(int maxValue)
		{
			Check.ArgumentNull(randomNumberGenerator);
			Check.ArgumentOutOfRangeEx.GreaterEqual0(maxValue);

			byte[] bytes = randomNumberGenerator.GetBytes(4);
			BitOperations.SetBit(bytes, 31, false);

			return (int)((long)BitConverter.ToInt32(bytes, 0) * maxValue / int.MaxValue);
		}
		/// <summary>
		/// Generates a cryptographically strong random <see cref="int" /> value that is less than the specified maximum.
		/// </summary>
		/// <param name="minValue">The inclusive lower bound of the random number returned.</param>
		/// <param name="maxValue">The exclusive upper bound of the random number to be generated. <paramref name="maxValue" /> must be greater than or equal to 0.</param>
		/// <returns>
		/// A cryptographically strong random <see cref="int" /> value that is less than the specified maximum.
		/// </returns>
		public int GetInt32(int minValue, int maxValue)
		{
			Check.ArgumentNull(randomNumberGenerator);
			Check.ArgumentOutOfRangeEx.GreaterEqual0(maxValue);
			Check.ArgumentOutOfRangeEx.GreaterEqualValue(maxValue, minValue);

			return minValue + randomNumberGenerator.GetInt32(maxValue - minValue);
		}
		/// <summary>
		/// Generates a cryptographically strong random <see cref="uint" /> value that is greater than or equal to 0, and less than or equal to <see cref="uint.MaxValue" />.
		/// </summary>
		/// <returns>
		/// A cryptographically strong random <see cref="uint" /> value that is greater than or equal to 0, and less than or equal to <see cref="uint.MaxValue" />.
		/// </returns>
		public uint GetUInt32()
		{
			Check.ArgumentNull(randomNumberGenerator);

			return BitConverter.ToUInt32(randomNumberGenerator.GetBytes(4), 0);
		}
		/// <summary>
		/// Generates a cryptographically strong random <see cref="long" /> value that is greater than or equal to <see cref="long.MinValue" />, and less than or equal to <see cref="long.MaxValue" />.
		/// </summary>
		/// <returns>
		/// A cryptographically strong random <see cref="long" /> value that is greater than or equal to <see cref="long.MinValue" />, and less than or equal to <see cref="long.MaxValue" />.
		/// </returns>
		public long GetInt64()
		{
			Check.ArgumentNull(randomNumberGenerator);

			return BitConverter.ToInt64(randomNumberGenerator.GetBytes(8), 0);
		}
		/// <summary>
		/// Generates a cryptographically strong random <see cref="ulong" /> value that is greater than or equal to 0UL, and less than or equal to <see cref="ulong.MaxValue" />.
		/// </summary>
		/// <returns>
		/// A cryptographically strong random <see cref="ulong" /> value that is greater than or equal to 0UL, and less than or equal to <see cref="ulong.MaxValue" />.
		/// </returns>
		public ulong GetUInt64()
		{
			Check.ArgumentNull(randomNumberGenerator);

			return BitConverter.ToUInt64(randomNumberGenerator.GetBytes(8), 0);
		}
		/// <summary>
		/// Generates a cryptographically strong random <see cref="short" /> value that is greater than or equal to <see cref="short.MinValue" />, and less than or equal to <see cref="short.MaxValue" />.
		/// </summary>
		/// <returns>
		/// A cryptographically strong random <see cref="short" /> value that is greater than or equal to <see cref="short.MinValue" />, and less than or equal to <see cref="short.MaxValue" />.
		/// </returns>
		public short GetInt16()
		{
			Check.ArgumentNull(randomNumberGenerator);

			return BitConverter.ToInt16(randomNumberGenerator.GetBytes(2), 0);
		}
		/// <summary>
		/// Generates a cryptographically strong random <see cref="ushort" /> value that is greater than or equal to 0, and less than or equal to <see cref="ushort.MaxValue" />.
		/// </summary>
		/// <returns>
		/// A cryptographically strong random <see cref="ushort" /> value that is greater than or equal to 0, and less than or equal to <see cref="ushort.MaxValue" />.
		/// </returns>
		public ushort GetUInt16()
		{
			Check.ArgumentNull(randomNumberGenerator);

			return BitConverter.ToUInt16(randomNumberGenerator.GetBytes(2), 0);
		}
		/// <summary>
		/// Creates a <see cref="BitArray" /> with a specified length and fills all elements with a cryptographically strong random sequence of <see cref="bool" /> values.
		/// </summary>
		/// <param name="count">The size of the returned <see cref="BitArray" />.</param>
		/// <returns>
		/// A new <see cref="BitArray" /> with a specified length, filled with a cryptographically strong random sequence of <see cref="bool" /> values.
		/// </returns>
		public BitArray GetBits(int count)
		{
			Check.ArgumentNull(randomNumberGenerator);
			Check.ArgumentOutOfRangeEx.GreaterEqual0(count);

			BitArray bits = new(count);
			byte[] buffer = new byte[16];
			int bufferPosition = int.MaxValue;

			for (int i = 0; i < count; i++)
			{
				if (bufferPosition >= buffer.Length << 3)
				{
					randomNumberGenerator.GetBytes(buffer);
					bufferPosition = 0;
				}

				bits[i] = (buffer[bufferPosition >> 3] & 1 << (bufferPosition & 7)) > 0;
				bufferPosition++;
			}

			return bits;
		}
		/// <summary>
		/// Returns a random <see cref="object" /> of the specified type from <paramref name="list" />, selected based on a cryptographically strong random index.
		/// </summary>
		/// <typeparam name="T">The element type of <paramref name="list" />.</typeparam>
		/// <param name="list">A <see cref="IList{T}" /> of the specified type.</param>
		/// <returns>
		/// A random <see cref="object" /> of the specified type from <paramref name="list" />.
		/// </returns>
		public T GetObject<T>(IList<T> list)
		{
			Check.ArgumentNull(randomNumberGenerator);
			Check.ArgumentNull(list);
			Check.ArgumentEx.ArrayElementsRequired(list);

			return list[randomNumberGenerator.GetInt32(list.Count)];
		}
		/// <summary>
		/// Returns a random value of the specified <see langword="enum" /> type.
		/// </summary>
		/// <typeparam name="T">The type of the <see cref="Enum" /> to be returned.</typeparam>
		/// <returns>
		/// A random value of the specified <see langword="enum" /> type.
		/// </returns>
		public T GetEnumValue<T>() where T : struct, Enum
		{
			Check.ArgumentNull(randomNumberGenerator);

			T[] values = Enum.GetValues<T>();
			if (values.None()) throw Throw.Argument(nameof(T), "Enum does not have values.");

			return randomNumberGenerator.GetObject(values);
		}
	}
}