Add QuickInteger distribution

Author: CaptainCrowbar

docs/random.md

@@ -151,6 +151,30 @@ inclusive; the bounds will be swapped if they are in the wrong order.
 _TODO: The current implementation exhibits undefined behaviour if the output
 range is larger than that of the input PRNG._
 
+### Quick uniform integer distribution
+
+```c++
+template <Integral T>
+class QuickRandom {
+    using result_type = T;
+    constexpr QuickRandom() noexcept;
+    constexpr explicit QuickRandom(T range) noexcept;
+    constexpr explicit QuickRandom(T min, T max) noexcept;
+    template <std::uniform_random_bit_generator RNG>
+        constexpr T operator()(RNG& rng) const;
+    constexpr T min() const noexcept;
+    constexpr T max() const noexcept;
+};
+```
+
+This has the same interface as `UniformInteger,` but generates its result with
+a simple modulo operation, and will never call the underlying RNG more than
+once. This is faster than `UniformInteger` but has a small bias, on the order
+of `output-range/RNG-range,` if the output range is not a power of 2.
+
+_TODO: This has the same issue as `UniformInteger` if the output range is
+large._
+
 ### Uniform floating point distribution
 
 ```c++

src/CMakeLists.txt

@@ -6,7 +6,7 @@ cmake_minimum_required(VERSION 3.30)
 # version.hpp.
 
 project(rs-core
-    VERSION 0.1.86
+    VERSION 0.1.87
     LANGUAGES CXX
 )
 
@@ -60,7 +60,10 @@ add_executable(${unittest}
     test/mp-integer-signed-conversion-test.cpp
     test/mp-integer-unsigned-arithmetic-test.cpp
     test/mp-integer-unsigned-conversion-test.cpp
-    test/random-test.cpp
+    test/random-algorithm-test.cpp
+    test/random-engine-test.cpp
+    test/random-float-test.cpp
+    test/random-integer-test.cpp
     test/rational-int-test.cpp
     test/rational-mp-integer-basics-test.cpp
     test/rational-mp-integer-maths-addition-subtraction-test.cpp

src/rs-core/random.hpp

@@ -176,7 +176,7 @@ namespace RS {
     private:
 
         T min_{0};
-        std::uint64_t range_{0};
+        std::uint64_t range_{0}; // 0 if range is full uint64_t
         std::uint64_t threshold_{0}; // Highest multiple of range that fits in a uint64_t
 
         constexpr void update() noexcept;
@@ -222,6 +222,11 @@ namespace RS {
 
         template <Integral T>
         constexpr T UniformInteger<T>::max() const noexcept {
+            if constexpr (std::same_as<T, std::uint64_t>) {
+                if (range_ == 0) {
+                    return std::numeric_limits<std::uint64_t>::max();
+                }
+            }
             auto half_range = range_ / 2;
             auto t1 = static_cast<T>(half_range);
             auto t2 = static_cast<T>(range_ - half_range - 1);
@@ -237,6 +242,74 @@ namespace RS {
             }
         }
 
+    // Quick integer distribution
+
+    template <Integral T>
+    class QuickRandom {
+
+    public:
+
+        using result_type = T;
+
+        constexpr QuickRandom() noexcept;
+        constexpr explicit QuickRandom(T range) noexcept; // UB if range<=0
+        constexpr explicit QuickRandom(T min, T max) noexcept;
+
+        template <std::uniform_random_bit_generator RNG>
+            constexpr T operator()(RNG& rng) const;
+
+        constexpr T min() const noexcept { return min_; }
+        constexpr T max() const noexcept;
+
+    private:
+
+        T min_{0};
+        std::uint64_t range_{0}; // 0 if range is full uint64_t
+
+    };
+
+        template <Integral T>
+        constexpr QuickRandom<T>::QuickRandom() noexcept:
+        min_(0),
+        range_(static_cast<std::uint64_t>(std::numeric_limits<T>::max()) + 1) {}
+
+        template <Integral T>
+        constexpr QuickRandom<T>::QuickRandom(T range) noexcept:
+        min_(0),
+        range_(static_cast<std::uint64_t>(range)) {}
+
+        template <Integral T>
+        constexpr QuickRandom<T>::QuickRandom(T min, T max) noexcept {
+            if (min > max) {
+                std::swap(min, max);
+            }
+            min_ = min;
+            range_ = static_cast<std::uint64_t>(max - min) + 1;
+        }
+
+        template <Integral T>
+        template <std::uniform_random_bit_generator RNG>
+        constexpr T QuickRandom<T>::operator()(RNG& rng) const {
+            auto x = rng();
+            if (range_ != 0) {
+                x %= range_;
+            }
+            return min_ + static_cast<T>(x);
+        }
+
+        template <Integral T>
+        constexpr T QuickRandom<T>::max() const noexcept {
+            if constexpr (std::same_as<T, std::uint64_t>) {
+                if (range_ == 0) {
+                    return std::numeric_limits<std::uint64_t>::max();
+                }
+            }
+            auto half_range = range_ / 2;
+            auto t1 = static_cast<T>(half_range);
+            auto t2 = static_cast<T>(range_ - half_range - 1);
+            return min_ + t1 + t2;
+        }
+
     // Bernoulli distribution
 
     class BernoulliDistribution {

src/rs-core/version.hpp

@@ -8,11 +8,11 @@
 namespace RS {
 
     inline std::array<int, 3> version() noexcept {
-        return {{ 0, 1, 86 }};
+        return {{ 0, 1, 87 }};
     }
 
     inline std::string version_string() {
-        return "0.1.86";
+        return "0.1.87";
     }
 
 }