Tedd.RandomUtils 1.0.2

FastRandom, ConcurrentRandom (thread safe lockless random), CryptoRandom (rng crypto grade random), plus methods for primitive datatypes SByte, Byte, Int16, UInt16, Int32, UInt32, Int64, UInt64, short, int, long. This packet replaces Tedd.MoreRandom and Tedd.RandomExtensions.

Install-Package Tedd.RandomUtils -Version 1.0.2
dotnet add package Tedd.RandomUtils --version 1.0.2
<PackageReference Include="Tedd.RandomUtils" Version="1.0.2" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Tedd.RandomUtils --version 1.0.2
The NuGet Team does not provide support for this client. Please contact its maintainers for support.

NuGet

Available as NuGet package: https://www.nuget.org/packages/Tedd.RandomUtils

Content

All extension methods that are available for System.Random are also implemented for both ConcurrentRandom and CryptoRandom.

System.Random Extension methods

Extension methods for System.Random that adds support for more datatypes.<br />
NextBoolean, NextSByte(), NextByte(), NextInt16(), NextUInt16(), NextIn32(), NextUInt32(), NextInt64(), NextUInt64(), NextFloat() and NextString().

ConcurrentRandom

ConcurrentRandom provides a lock free thread safe static way to access System.Random. This is implemented by creating a new System.Random object per thread (ThreadLocal), seeded by a root random object protected by a spinlock.

CryptoRandom

CryptoRandom uses the operating systems underlying CSP (Cryptographic Service Provider) for better random data. See further down for explanation.

Examples

Random by type

var rnd = new Random();

bool   val1  = rnd.NextBoolean();
sbyte  val2  = rnd.NextSByte();
byte   val3  = rnd.NextByte();
short  val4  = rnd.NextInt16();
ushort val5  = rnd.NextUInt16();
int    val6  = rnd.NextInt32();
uint   val7  = rnd.NextUInt32();
long   val8  = rnd.NextInt64();
ulong  val9  = rnd.NextUInt64();
float  val10 = rnd.NextFloat();
string val11 = rnd.NextString("abcdefg", 8);

Thread safe random

Thread safe random without locking.

bool   val1  = ConcurrentRandom.NextBoolean();
sbyte  val2  = ConcurrentRandom.NextSByte();
byte   val3  = ConcurrentRandom.NextByte();
short  val4  = ConcurrentRandom.NextInt16();
ushort val5  = ConcurrentRandom.NextUInt16();
int    val6  = ConcurrentRandom.NextInt32();
uint   val7  = ConcurrentRandom.NextUInt32();
long   val8  = ConcurrentRandom.NextInt64();
ulong  val9  = ConcurrentRandom.NextUInt64();
float  val10 = ConcurrentRandom.NextFloat();
string val11 = ConcurrentRandom.NextString("abcdefg", 8);
ConcurrentRandom.NextBytes(byteArray);

Crypto strength random

using rnd = new CryptoRandom();

bool   val1  = rnd.NextBoolean();
sbyte  val2  = rnd.NextSByte();
byte   val3  = rnd.NextByte();
short  val4  = rnd.NextInt16();
ushort val5  = rnd.NextUInt16();
int    val6  = rnd.NextInt32();
uint   val7  = rnd.NextUInt32();
long   val8  = rnd.NextInt64();
ulong  val9  = rnd.NextUInt64();
float  val10 = rnd.NextFloat();
string val11 = rnd.NextString("abcdefg", 8);
rnd.NextBytes(byteArray);

CryptoRandom

Drop-in replacement for System.Random that gets more random data from Cryptographic Service Provider.

Example

Works exactly like System.Random, except you may want to dispose of it when you are done.
(If you don't dispose of it, the destructor will do it for you upon garbage collect.)

var rnd = new CryptoRandom();
var dice = rnd.Next(1, 7); // A random number between 1 and 6 inclusive
rnd.Dispose();

Or with using:

using (var rnd = new CryptoRandom()) {
	var percent = rnd.NextDouble() * 100;
	Console.WriteLine($"You are {percent}% done, please wait...");
}

Note that it is recommended to create a shared Random object, and in case of multiple threads use synchronized access to generate random data.

public static class Main {
	public static CryptoRandom Rnd = new CryptoRandomRandom();

	public static void Start() {
		int dice;
		lock (Rnd)
			dice = Rnd.Next(1, 7); // A random number between 1 and 6 inclusive
	}
}

Thread safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Background

System.Random is based on a pseudorandom algorithm. This means that given a seed (default: number of milliseconds since computer was started) math is used to generate seemingly random numbers. If given the same seed, a sequence of random numbers will look the same every time. For most cases this is fine, but in some cases you need more random data. One such case is cryptography, where a pseudorandom generator such as System.Random would generate a predictable sequence of numbers.

RNGCryptoServiceProvider through RandomNumberGenerator provides "cryptography grade random" numbers. These numbers are a bit more random as they are provided by the operating system, which has methods of collecting random data.

RandomNumberGenerator gives you a bunch of random bytes. It's up to you to convert to a number and size for whatever purpose. System.Random however has a simple interface, for example rnd.Next(10).

This is where MoreRandom comes in. CryptoRandom mimics System.Random and is a drop-in replacement. You get the power of RandomNumberGenerator with the ease of System.Random.

Remarks

Vanilla System.Random vs this library

Standard System.Random.Next() returns a positive integer, while all this library return full range of values for given datatype.
Standard System.Random.Next(from, to) has "exclusive to" value, meaning it only returns 31 random bits in the 32-bit integer. This library returns random for all 32 and 64 bits on NextInt32(), NextUInt32, NextInt64() and NextUInt64() respectively.

Unit testing

xUnit in .Net Core with near 100% code coverage. Boundary checks as well as average check (for statistical distribution) on large number of samples.

NuGet

Available as NuGet package: https://www.nuget.org/packages/Tedd.RandomUtils

Content

All extension methods that are available for System.Random are also implemented for both ConcurrentRandom and CryptoRandom.

System.Random Extension methods

Extension methods for System.Random that adds support for more datatypes.<br />
NextBoolean, NextSByte(), NextByte(), NextInt16(), NextUInt16(), NextIn32(), NextUInt32(), NextInt64(), NextUInt64(), NextFloat() and NextString().

ConcurrentRandom

ConcurrentRandom provides a lock free thread safe static way to access System.Random. This is implemented by creating a new System.Random object per thread (ThreadLocal), seeded by a root random object protected by a spinlock.

CryptoRandom

CryptoRandom uses the operating systems underlying CSP (Cryptographic Service Provider) for better random data. See further down for explanation.

Examples

Random by type

var rnd = new Random();

bool   val1  = rnd.NextBoolean();
sbyte  val2  = rnd.NextSByte();
byte   val3  = rnd.NextByte();
short  val4  = rnd.NextInt16();
ushort val5  = rnd.NextUInt16();
int    val6  = rnd.NextInt32();
uint   val7  = rnd.NextUInt32();
long   val8  = rnd.NextInt64();
ulong  val9  = rnd.NextUInt64();
float  val10 = rnd.NextFloat();
string val11 = rnd.NextString("abcdefg", 8);

Thread safe random

Thread safe random without locking.

bool   val1  = ConcurrentRandom.NextBoolean();
sbyte  val2  = ConcurrentRandom.NextSByte();
byte   val3  = ConcurrentRandom.NextByte();
short  val4  = ConcurrentRandom.NextInt16();
ushort val5  = ConcurrentRandom.NextUInt16();
int    val6  = ConcurrentRandom.NextInt32();
uint   val7  = ConcurrentRandom.NextUInt32();
long   val8  = ConcurrentRandom.NextInt64();
ulong  val9  = ConcurrentRandom.NextUInt64();
float  val10 = ConcurrentRandom.NextFloat();
string val11 = ConcurrentRandom.NextString("abcdefg", 8);
ConcurrentRandom.NextBytes(byteArray);

Crypto strength random

using rnd = new CryptoRandom();

bool   val1  = rnd.NextBoolean();
sbyte  val2  = rnd.NextSByte();
byte   val3  = rnd.NextByte();
short  val4  = rnd.NextInt16();
ushort val5  = rnd.NextUInt16();
int    val6  = rnd.NextInt32();
uint   val7  = rnd.NextUInt32();
long   val8  = rnd.NextInt64();
ulong  val9  = rnd.NextUInt64();
float  val10 = rnd.NextFloat();
string val11 = rnd.NextString("abcdefg", 8);
rnd.NextBytes(byteArray);

CryptoRandom

Drop-in replacement for System.Random that gets more random data from Cryptographic Service Provider.

Example

Works exactly like System.Random, except you may want to dispose of it when you are done.
(If you don't dispose of it, the destructor will do it for you upon garbage collect.)

var rnd = new CryptoRandom();
var dice = rnd.Next(1, 7); // A random number between 1 and 6 inclusive
rnd.Dispose();

Or with using:

using (var rnd = new CryptoRandom()) {
	var percent = rnd.NextDouble() * 100;
	Console.WriteLine($"You are {percent}% done, please wait...");
}

Note that it is recommended to create a shared Random object, and in case of multiple threads use synchronized access to generate random data.

public static class Main {
	public static CryptoRandom Rnd = new CryptoRandomRandom();

	public static void Start() {
		int dice;
		lock (Rnd)
			dice = Rnd.Next(1, 7); // A random number between 1 and 6 inclusive
	}
}

Thread safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Background

System.Random is based on a pseudorandom algorithm. This means that given a seed (default: number of milliseconds since computer was started) math is used to generate seemingly random numbers. If given the same seed, a sequence of random numbers will look the same every time. For most cases this is fine, but in some cases you need more random data. One such case is cryptography, where a pseudorandom generator such as System.Random would generate a predictable sequence of numbers.

RNGCryptoServiceProvider through RandomNumberGenerator provides "cryptography grade random" numbers. These numbers are a bit more random as they are provided by the operating system, which has methods of collecting random data.

RandomNumberGenerator gives you a bunch of random bytes. It's up to you to convert to a number and size for whatever purpose. System.Random however has a simple interface, for example rnd.Next(10).

This is where MoreRandom comes in. CryptoRandom mimics System.Random and is a drop-in replacement. You get the power of RandomNumberGenerator with the ease of System.Random.

Remarks

Vanilla System.Random vs this library

Standard System.Random.Next() returns a positive integer, while all this library return full range of values for given datatype.
Standard System.Random.Next(from, to) has "exclusive to" value, meaning it only returns 31 random bits in the 32-bit integer. This library returns random for all 32 and 64 bits on NextInt32(), NextUInt32, NextInt64() and NextUInt64() respectively.

Unit testing

xUnit in .Net Core with near 100% code coverage. Boundary checks as well as average check (for statistical distribution) on large number of samples.

Release Notes

Added FastRandom based on Lehmer which is 70% faster than System.Random.
Increased speed of ConcurrentRandom by 25% by avoiding ThreadLocal.

  • .NETCoreApp 2.0

    • No dependencies.
  • .NETCoreApp 2.1

    • No dependencies.
  • .NETCoreApp 3.0

    • No dependencies.
  • .NETCoreApp 3.1

    • No dependencies.
  • .NETFramework 4.6.1

  • .NETStandard 2.1

    • No dependencies.

This package is not used by any popular GitHub repositories.

Version History

Version Downloads Last updated
1.0.2 28 2/1/2020
1.0.1 51 12/21/2019
1.0.0 61 12/19/2019