diff --git a/src/Random.cs b/src/Random.cs
index 385bfb2..6f8b258 100644
--- a/src/Random.cs
+++ b/src/Random.cs
@@ -3,8 +3,10 @@ using System.Runtime.CompilerServices;
namespace MoonTools.ECS
{
- // WELLRNG512
- // https://stackoverflow.com/a/1227137
+ ///
+ /// This class implements the well equidistributed long-period linear pseudorandom number generator.
+ /// Code taken from Chris Lomont: http://lomont.org/papers/2008/Lomont_PRNG_2008.pdf
+ ///
public class Random
{
public const int STATE_BYTE_COUNT = 68; // 16 state ints + 1 index int
@@ -13,11 +15,17 @@ namespace MoonTools.ECS
uint Index = 0;
uint Seed;
+ ///
+ /// Initializes the RNG with an arbitrary seed.
+ ///
public Random()
{
Init((uint) Environment.TickCount);
}
+ ///
+ /// Initializes the RNG with a given seed.
+ ///
public void Init(uint seed)
{
Seed = seed;
@@ -30,11 +38,17 @@ namespace MoonTools.ECS
Index = 0;
}
+ ///
+ /// Returns the seed that was used to initialize the RNG.
+ ///
public uint GetSeed()
{
return Seed;
}
+ ///
+ /// Returns the entire state of the RNG as a string.
+ ///
public string PrintState()
{
var s = "";
@@ -46,7 +60,11 @@ namespace MoonTools.ECS
return s;
}
- // expects a span of STATE_BYTE_COUNT bytes
+ ///
+ /// Saves the entire state of the RNG to a Span.
+ ///
+ /// Must be a span of at least STATE_BYTE_COUNT bytes.
+ /// Thrown if the byte span is too short.
public unsafe void SaveState(Span bytes)
{
#if DEBUG
@@ -69,7 +87,11 @@ namespace MoonTools.ECS
}
}
- // expects a span of STATE_BYTE_COUNT bytes
+ ///
+ /// Loads the entire state of the RNG from a Span.
+ ///
+ /// Must be a span of at least STATE_BYTE_COUNT bytes.
+ /// Thrown if the byte span is too short.
public unsafe void LoadState(Span bytes)
{
#if DEBUG
@@ -109,17 +131,25 @@ namespace MoonTools.ECS
return State[Index];
}
- // .NET Random API always returns a non-negative signed int. Fun!
+ ///
+ /// Returns a non-negative signed integer.
+ ///
public int Next()
{
return (int) (NextInternal() >>> 1); // unsigned bitshift right to get rid of signed bit
}
- public int Next(int n)
+ ///
+ /// Returns a non-negative signed integer less than max.
+ ///
+ public int Next(int max)
{
- return (int) (((double) Next()) * n / int.MaxValue);
+ return (int) (((double) Next()) * max / int.MaxValue);
}
+ ///
+ /// Returns a signed integer greater than or equal to min and less than max.
+ ///
public int Next(int min, int max)
{
var diff = max - min;
@@ -127,6 +157,9 @@ namespace MoonTools.ECS
return min + next;
}
+ ///
+ /// Returns a non-negative signed 64 bit integer.
+ ///
public long NextInt64()
{
long next = NextInternal();
@@ -136,12 +169,18 @@ namespace MoonTools.ECS
return next;
}
- public long NextInt64(long n)
+ ///
+ /// Returns a non-negative signed 64 bit integer less than max.
+ ///
+ public long NextInt64(long max)
{
var next = NextInt64();
- return (long) (((double) next) * n / long.MaxValue);
+ return (long) (((double) next) * max / long.MaxValue);
}
+ ///
+ /// Returns a non-negative signed 64 bit integer greater than or equal to min and less than max.
+ ///
public long NextInt64(long min, long max)
{
var diff = max - min;
@@ -149,12 +188,18 @@ namespace MoonTools.ECS
return min + next;
}
- public float NextFloat()
+ ///
+ /// Returns a single-precision floating point value between 0 and 1.
+ ///
+ public float NextSingle()
{
var n = NextInternal();
return ((float) n) / uint.MaxValue;
}
+ ///
+ /// Returns a double-precision floating point value between 0 and 1.
+ ///
public double NextDouble()
{
var n = NextInternal();