diff --git a/FastRng/Double/IRandom.cs b/FastRng/Double/IRandom.cs index ec4220c..dd6f2d9 100644 --- a/FastRng/Double/IRandom.cs +++ b/FastRng/Double/IRandom.cs @@ -5,8 +5,20 @@ using FastRng.Double.Distributions; namespace FastRng.Double { + /// + /// Interface for random number generators. + /// public interface IRandom : IDisposable { + /// + /// Returns a uniform distributed pseudo-random number from the interval (0,1]. + /// This means, the result 0 is impossible, whereas 1 is possible. + /// + /// + /// This method is thread-safe. You can consume numbers from the same generator + /// by using multiple threads at the same time. + /// + /// An optional cancellation token. public ValueTask GetUniform(CancellationToken cancel = default); } } \ No newline at end of file diff --git a/FastRng/Double/MathTools.cs b/FastRng/Double/MathTools.cs index 3de59d6..e833a7f 100644 --- a/FastRng/Double/MathTools.cs +++ b/FastRng/Double/MathTools.cs @@ -2,11 +2,18 @@ using System; namespace FastRng.Double { + /// + /// Provides some mathematical function, which are not available within in the .NET framework. + /// public static class MathTools { private static readonly double SQRT_2 = Math.Sqrt(2.0); private static readonly double SQRT_PI = Math.Sqrt(Math.PI); + /// + /// The mathematical gamma function. + /// + /// The value for which you want calculate gamma. public static double Gamma(double z) { // Source: http://rosettacode.org/wiki/Gamma_function#Go @@ -36,8 +43,17 @@ namespace FastRng.Double return MathTools.SQRT_2 * MathTools.SQRT_PI * Math.Pow(t, z - 0.5) * Math.Exp(-t) * x; } + /// + /// The mathematical factorial function for floating-point numbers. + /// + /// The value, for which you want to know the factorial. public static double Factorial(double x) => MathTools.Gamma(x + 1.0); + /// + /// The mathematical factorial function for integer numbers. + /// + /// The value, for which you want to know the factorial. + /// Throws, when x is greater than 20. Due to limitations of 64bit ulong type. public static ulong Factorial(uint x) { if (x > 20) @@ -50,6 +66,12 @@ namespace FastRng.Double return accumulator; } + /// + /// The mathematical factorial function for integer numbers. + /// + /// The value, for which you want to know the factorial. + /// Throws, when x is greater than 20. Due to limitations + /// of 64bit ulong type. Throws also, when x is less than 0. public static ulong Factorial(int x) { if(x < 0) diff --git a/FastRng/Double/MultiThreadedRng.cs b/FastRng/Double/MultiThreadedRng.cs index 5c586a0..6b35aca 100644 --- a/FastRng/Double/MultiThreadedRng.cs +++ b/FastRng/Double/MultiThreadedRng.cs @@ -68,6 +68,15 @@ namespace FastRng.Double #region Constructors + /// + /// Creates a multi-threaded random number generator. + /// + /// + /// This constructor uses the user's current local time + /// to derive necessary parameters for the generator. + /// Thus, the results are depending on the time, where + /// the generator was created. + /// public MultiThreadedRng() { // @@ -81,6 +90,19 @@ namespace FastRng.Double this.StartProducerThreads(); } + /// + /// Creates a multi-threaded random number generator. + /// + /// + /// A multi-threaded random number generator created by this constructor is + /// deterministic. It's behaviour is not depending on the time of its creation.

+ /// + /// Please note: Although the number generator and all distributions are deterministic, + /// the behavior of the consuming application might be non-deterministic. This is possible if + /// the application with multiple threads consumes the numbers. The scheduling of the threads + /// is up to the operating system and might not be predictable. + /// + /// A seed value to generate a deterministic generator. public MultiThreadedRng(uint seedU) { this.mW = seedU; @@ -88,6 +110,20 @@ namespace FastRng.Double this.StartProducerThreads(); } + /// + /// Creates a multi-threaded random number generator. + /// + /// + /// A multi-threaded random number generator created by this constructor is + /// deterministic. It's behaviour is not depending on the time of its creation.

+ /// + /// Please note: Although the number generator and all distributions are deterministic, + /// the behavior of the consuming application might be non-deterministic. This is possible if + /// the application with multiple threads consumes the numbers. The scheduling of the threads + /// is up to the operating system and might not be predictable. + /// + /// The first seed value. + /// The second seed value. public MultiThreadedRng(uint seedU, uint seedV) { this.mW = seedU; @@ -209,6 +245,15 @@ namespace FastRng.Double #region Implementing interface + /// + /// Returns a uniform distributed pseudo-random number from the interval (0,1]. + /// This means, the result 0 is impossible, whereas 1 is possible. + /// + /// + /// This method is thread-safe. You can consume numbers from the same generator + /// by using multiple threads at the same time. + /// + /// An optional cancellation token. public async ValueTask GetUniform(CancellationToken cancel = default) { while (!cancel.IsCancellationRequested) @@ -301,6 +346,11 @@ namespace FastRng.Double private void StopProducer() => this.producerTokenSource.Cancel(); + /// + /// Disposes this generator. It is important to dispose a generator, + /// when it is no longer needed. Otherwise, the background threads + /// are still running. + /// public void Dispose() => this.StopProducer(); #endregion diff --git a/FastRng/Double/ShapeFitter.cs b/FastRng/Double/ShapeFitter.cs index 032ddee..508b4ef 100644 --- a/FastRng/Double/ShapeFitter.cs +++ b/FastRng/Double/ShapeFitter.cs @@ -17,6 +17,12 @@ namespace FastRng.Double private readonly double sampleSize; private readonly IDistribution uniform; + /// + /// Creates a shape fitter instance. + /// + /// The function which describes the desired shape. + /// The random number generator instance to use. + /// The number of sampling steps to sample the given function. public ShapeFitter(Func shapeFunction, IRandom rng, ushort sampleSize = 50) { this.rng = rng; @@ -39,6 +45,11 @@ namespace FastRng.Double this.max = maxValue; } + /// + /// Returns a random number regarding the given shape. + /// + /// An optional cancellation token. + /// The next value regarding the given shape. public async ValueTask NextNumber(CancellationToken token = default) { while (!token.IsCancellationRequested) diff --git a/FastRng/Float/IRandom.cs b/FastRng/Float/IRandom.cs index 268d037..893f170 100644 --- a/FastRng/Float/IRandom.cs +++ b/FastRng/Float/IRandom.cs @@ -5,8 +5,20 @@ using FastRng.Float.Distributions; namespace FastRng.Float { + /// + /// Interface for random number generators. + /// public interface IRandom : IDisposable { + /// + /// Returns a uniform distributed pseudo-random number from the interval (0,1]. + /// This means, the result 0 is impossible, whereas 1 is possible. + /// + /// + /// This method is thread-safe. You can consume numbers from the same generator + /// by using multiple threads at the same time. + /// + /// An optional cancellation token. public ValueTask GetUniform(CancellationToken cancel = default); } } \ No newline at end of file diff --git a/FastRng/Float/MathTools.cs b/FastRng/Float/MathTools.cs index 63115a4..eb3e5ae 100644 --- a/FastRng/Float/MathTools.cs +++ b/FastRng/Float/MathTools.cs @@ -2,11 +2,18 @@ using System; namespace FastRng.Float { + /// + /// Provides some mathematical function, which are not available within in the .NET framework. + /// public static class MathTools { private static readonly float SQRT_2 = MathF.Sqrt(2.0f); private static readonly float SQRT_PI = MathF.Sqrt(MathF.PI); + /// + /// The mathematical gamma function. + /// + /// The value for which you want calculate gamma. public static float Gamma(float z) { // Source: http://rosettacode.org/wiki/Gamma_function#Go @@ -36,8 +43,17 @@ namespace FastRng.Float return MathTools.SQRT_2 * MathTools.SQRT_PI * MathF.Pow(t, z - 0.5f) * MathF.Exp(-t) * x; } + /// + /// The mathematical factorial function for floating-point numbers. + /// + /// The value, for which you want to know the factorial. public static float Factorial(float x) => MathTools.Gamma(x + 1.0f); + /// + /// The mathematical factorial function for integer numbers. + /// + /// The value, for which you want to know the factorial. + /// Throws, when x is greater than 20. Due to limitations of 64bit ulong type. public static ulong Factorial(uint x) { if (x > 20) @@ -50,6 +66,12 @@ namespace FastRng.Float return accumulator; } + /// + /// The mathematical factorial function for integer numbers. + /// + /// The value, for which you want to know the factorial. + /// Throws, when x is greater than 20. Due to limitations + /// of 64bit ulong type. Throws also, when x is less than 0. public static ulong Factorial(int x) { if(x < 0) diff --git a/FastRng/Float/MultiThreadedRng.cs b/FastRng/Float/MultiThreadedRng.cs index 1c15b40..b6e9b1e 100644 --- a/FastRng/Float/MultiThreadedRng.cs +++ b/FastRng/Float/MultiThreadedRng.cs @@ -68,6 +68,15 @@ namespace FastRng.Float #region Constructors + /// + /// Creates a multi-threaded random number generator. + /// + /// + /// This constructor uses the user's current local time + /// to derive necessary parameters for the generator. + /// Thus, the results are depending on the time, where + /// the generator was created. + /// public MultiThreadedRng() { // @@ -81,6 +90,19 @@ namespace FastRng.Float this.StartProducerThreads(); } + /// + /// Creates a multi-threaded random number generator. + /// + /// + /// A multi-threaded random number generator created by this constructor is + /// deterministic. It's behaviour is not depending on the time of its creation.

+ /// + /// Please note: Although the number generator and all distributions are deterministic, + /// the behavior of the consuming application might be non-deterministic. This is possible if + /// the application with multiple threads consumes the numbers. The scheduling of the threads + /// is up to the operating system and might not be predictable. + /// + /// A seed value to generate a deterministic generator. public MultiThreadedRng(uint seedU) { this.mW = seedU; @@ -88,6 +110,20 @@ namespace FastRng.Float this.StartProducerThreads(); } + /// + /// Creates a multi-threaded random number generator. + /// + /// + /// A multi-threaded random number generator created by this constructor is + /// deterministic. It's behaviour is not depending on the time of its creation.

+ /// + /// Please note: Although the number generator and all distributions are deterministic, + /// the behavior of the consuming application might be non-deterministic. This is possible if + /// the application with multiple threads consumes the numbers. The scheduling of the threads + /// is up to the operating system and might not be predictable. + /// + /// The first seed value. + /// The second seed value. public MultiThreadedRng(uint seedU, uint seedV) { this.mW = seedU; @@ -209,6 +245,15 @@ namespace FastRng.Float #region Implementing interface + /// + /// Returns a uniform distributed pseudo-random number from the interval (0,1]. + /// This means, the result 0 is impossible, whereas 1 is possible. + /// + /// + /// This method is thread-safe. You can consume numbers from the same generator + /// by using multiple threads at the same time. + /// + /// An optional cancellation token. public async ValueTask GetUniform(CancellationToken cancel = default) { while (!cancel.IsCancellationRequested) @@ -301,6 +346,11 @@ namespace FastRng.Float private void StopProducer() => this.producerTokenSource.Cancel(); + /// + /// Disposes this generator. It is important to dispose a generator, + /// when it is no longer needed. Otherwise, the background threads + /// are still running. + /// public void Dispose() => this.StopProducer(); #endregion diff --git a/FastRng/Float/ShapeFitter.cs b/FastRng/Float/ShapeFitter.cs index 3ddab89..d17cedd 100644 --- a/FastRng/Float/ShapeFitter.cs +++ b/FastRng/Float/ShapeFitter.cs @@ -16,6 +16,12 @@ namespace FastRng.Float private readonly float sampleSize; private readonly IDistribution uniform; + /// + /// Creates a shape fitter instance. + /// + /// The function which describes the desired shape. + /// The random number generator instance to use. + /// The number of sampling steps to sample the given function. public ShapeFitter(Func shapeFunction, IRandom rng, ushort sampleSize = 50) { this.rng = rng; @@ -38,6 +44,11 @@ namespace FastRng.Float this.max = maxValue; } + /// + /// Returns a random number regarding the given shape. + /// + /// An optional cancellation token. + /// The next value regarding the given shape. public async ValueTask NextNumber(CancellationToken token = default) { while (!token.IsCancellationRequested)