RandN 0.1.0

RandN is an alternative library for random number generation.

There is a newer version of this package available.
See the version list below for details.
Install-Package RandN -Version 0.1.0
dotnet add package RandN --version 0.1.0
<PackageReference Include="RandN" Version="0.1.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add RandN --version 0.1.0
The NuGet Team does not provide support for this client. Please contact its maintainers for support.
#r "nuget: RandN, 0.1.0"
For F# scripts that support #r syntax, copy this into the source code to reference the package.

RandN

RandN on NuGet

RandN is a .NET library for random number generation. It aims to rectify deficiencies in
System.Random
with adaptability and
extensibility in mind. RandN is heavily inspired by the design of the Rust crate
rand, and aims to maintain some level of
compatibility with it.

What's wrong with System.Random?

In short, the algorithm it uses is slow and
biased. The API is very rigid and inflexible, and as
a result is unsuited for many purposes.

RandN provides a clear and obvious API that is difficult to use incorrectly, unlike the API of
System.Random. This is accomplished by clearly separating two concepts; generating randomness
with an IRng, and turning that data into something useful with an IDistribution.

Docs

The full documentation is available here.

Usage

Install the RandN package from Nuget for most use cases.
If you just want to implement an random number generator (ex. you're publishing a package with a new
RNG), instead depend on RandN.Core.

Examples

Creating an RNG

using RandN;

// Creates a cryptographically secure RNG
var cryptoRng = StandardRng.Create();

// Creates a non-cryptographically secure RNG that's fast and uses less memory
var rng = SmallRng.Create();

A reproducible RNG can also be created by using an algorithm directly:

using RandN.Rngs;

// Use ThreadLocalRng to seed the RNG - this uses a cryptographically secure
// algorithm, so tight loops won't result in similar seeds
var seeder = ThreadLocalRng.Instance;

// Create the seed (Seeds can also be created manually)
var factory = ChaCha.GetChaCha8Factory();
var seed = factory.CreateSeed(seeder);

// Create the RNG from the seed
var rng = factory.Create(seed);

Getting random numbers

Once you have an RNG, you can either use it directly,

var num = rng.NextUInt32();
var bigNum = rng.NextUInt64();
var buffer = new Byte[1000];
rng.Fill(buffer);

or you can use it to sample a distribution:

var distribution = Uniform.NewInclusive(42, 54); // [42 - 54]
var answer = distribution.Sample(rng);

var weightedCoin = Bernoulli.FromRatio(8, 10); // 80% chance of true
var probablyHeads = weightedCoin.Sample(rng);

Shuffling a list is also easy:

var list = new List<Int32>() { 1, 2, 3, 4, 5, 6 };
rng.ShuffleInPlace(list);

Any type implementing IRng can be wrapped with RandomShim, which can be used as a drop-in
replacement for Random.

using RandN.Compat;
Random random = RandomShim.Create(rng);
random.Next(2);

Compatibility

  • RandN is written with the assumption that C# 8 Nullable Reference types are enabled and therefore
    does not null check arguments. Null checks may be added through Fody in the future.

RandN

RandN on NuGet

RandN is a .NET library for random number generation. It aims to rectify deficiencies in
System.Random
with adaptability and
extensibility in mind. RandN is heavily inspired by the design of the Rust crate
rand, and aims to maintain some level of
compatibility with it.

What's wrong with System.Random?

In short, the algorithm it uses is slow and
biased. The API is very rigid and inflexible, and as
a result is unsuited for many purposes.

RandN provides a clear and obvious API that is difficult to use incorrectly, unlike the API of
System.Random. This is accomplished by clearly separating two concepts; generating randomness
with an IRng, and turning that data into something useful with an IDistribution.

Docs

The full documentation is available here.

Usage

Install the RandN package from Nuget for most use cases.
If you just want to implement an random number generator (ex. you're publishing a package with a new
RNG), instead depend on RandN.Core.

Examples

Creating an RNG

using RandN;

// Creates a cryptographically secure RNG
var cryptoRng = StandardRng.Create();

// Creates a non-cryptographically secure RNG that's fast and uses less memory
var rng = SmallRng.Create();

A reproducible RNG can also be created by using an algorithm directly:

using RandN.Rngs;

// Use ThreadLocalRng to seed the RNG - this uses a cryptographically secure
// algorithm, so tight loops won't result in similar seeds
var seeder = ThreadLocalRng.Instance;

// Create the seed (Seeds can also be created manually)
var factory = ChaCha.GetChaCha8Factory();
var seed = factory.CreateSeed(seeder);

// Create the RNG from the seed
var rng = factory.Create(seed);

Getting random numbers

Once you have an RNG, you can either use it directly,

var num = rng.NextUInt32();
var bigNum = rng.NextUInt64();
var buffer = new Byte[1000];
rng.Fill(buffer);

or you can use it to sample a distribution:

var distribution = Uniform.NewInclusive(42, 54); // [42 - 54]
var answer = distribution.Sample(rng);

var weightedCoin = Bernoulli.FromRatio(8, 10); // 80% chance of true
var probablyHeads = weightedCoin.Sample(rng);

Shuffling a list is also easy:

var list = new List<Int32>() { 1, 2, 3, 4, 5, 6 };
rng.ShuffleInPlace(list);

Any type implementing IRng can be wrapped with RandomShim, which can be used as a drop-in
replacement for Random.

using RandN.Compat;
Random random = RandomShim.Create(rng);
random.Next(2);

Compatibility

  • RandN is written with the assumption that C# 8 Nullable Reference types are enabled and therefore
    does not null check arguments. Null checks may be added through Fody in the future.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version History

Version Downloads Last updated
0.2.0 1,687 12/21/2020
0.1.0 3,819 6/20/2020
0.1.0-beta 165 6/15/2020