RandN 0.5.0
dotnet add package RandN --version 0.5.0
NuGet\Install-Package RandN -Version 0.5.0
<PackageReference Include="RandN" Version="0.5.0" />
<PackageVersion Include="RandN" Version="0.5.0" />
<PackageReference Include="RandN" />
paket add RandN --version 0.5.0
#r "nuget: RandN, 0.5.0"
#addin nuget:?package=RandN&version=0.5.0
#tool nuget:?package=RandN&version=0.5.0
RandN
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 rng = StandardRng.Create();
// Creates a non-cryptographically secure RNG that's fast and uses less memory
var insecureRng = 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:
Uniform.Int32 distribution = Uniform.NewInclusive(42, 54); // [42 - 54]
int answer = distribution.Sample(rng);
Bernoulli weightedCoin = Bernoulli.FromRatio(8, 10); // 80% chance of true
bool 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); // returns 0 or 1
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net5.0 was computed. net5.0-windows was computed. net6.0 is compatible. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. |
| .NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
| .NET Standard | netstandard2.0 is compatible. netstandard2.1 is compatible. |
| .NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
| MonoAndroid | monoandroid was computed. |
| MonoMac | monomac was computed. |
| MonoTouch | monotouch was computed. |
| Tizen | tizen40 was computed. tizen60 was computed. |
| Xamarin.iOS | xamarinios was computed. |
| Xamarin.Mac | xamarinmac was computed. |
| Xamarin.TVOS | xamarintvos was computed. |
| Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.0
- RandN.ChaCha (>= 0.5.0 && < 0.6.0)
- RandN.Core (>= 0.5.0 && < 0.6.0)
- RandN.Pcg32 (>= 0.5.0 && < 0.6.0)
- System.Runtime.InteropServices (>= 4.3.0)
-
.NETStandard 2.1
- RandN.ChaCha (>= 0.5.0 && < 0.6.0)
- RandN.Core (>= 0.5.0 && < 0.6.0)
- RandN.Pcg32 (>= 0.5.0 && < 0.6.0)
-
net6.0
- RandN.ChaCha (>= 0.5.0 && < 0.6.0)
- RandN.Core (>= 0.5.0 && < 0.6.0)
- RandN.Pcg32 (>= 0.5.0 && < 0.6.0)
-
net8.0
- RandN.ChaCha (>= 0.5.0 && < 0.6.0)
- RandN.Core (>= 0.5.0 && < 0.6.0)
- RandN.Pcg32 (>= 0.5.0 && < 0.6.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
Version 0.5.0
Added .NET 8 target
(Breaking Change) Dropped .NET Core 3.1 and .NET 7 targets
Added a Uniform distribution for BigInteger
Added Uniform distributions for UInt128 and Int128 - these are only available on .NET 8 and later targets.
Greatly improve performance of ShuffleInPlace on Lists and arrays
(Breaking Change) Removed Big-Endian support
Reorganized RNG algorithms into separate packages:
Moved the PCG 32 RNG into the new `RandN.Pcg32` package and made it a dependency of `RandN`.
Moved the ChaCha RNG into the new `RandN.ChaCha` package and made it a dependency of `RandN`.
(Breaking Change) Moved XorShift and Mersenne Twister into the optional `RandN.ExtraRngs` package