{-# OPTIONS_HADDOCK prune #-}
{-# LANGUAGE BangPatterns #-}

-- |
-- Module: Crypto.PRNG.Pure
-- Copyright: (c) 2026 Jared Tobin
-- License: MIT
-- Maintainer: Jared Tobin <jared@ppad.tech>
--
-- A fast, non-cryptographic pseudorandom number generator,
-- [xoshiro256++](https://prng.di.unimi.it/), as an immutable value.
--
-- This is the generator of "Crypto.PRNG", with the same output for the
-- same seed, but threaded through code explicitly: each function
-- returns its result along with the next generator. Generators are
-- values, so using one twice yields the same output twice; derive
-- non-overlapping streams via 'jump' or 'long_jump'.
--
-- When these functions are inlined into a strict loop, GHC keeps the
-- generator's state in registers and allocates nothing, which is
-- several times faster than the mutable generator. Bind results with
-- @case@ or bang patterns rather than lazy @let@s. Called where GHC
-- can't inline or specialise them, e.g. via a lazy fold or an
-- unspecialised class method, each draw allocates, and the mutable
-- "Crypto.PRNG" may be faster.
--
-- Its output is predictable from a small sample; use "Crypto.CSPRNG"
-- for anything that must be unpredictable.

module Crypto.PRNG.Pure (
    -- * Generator
    Gen
  , Draw(..)
  , new
  , new_system
  , from_state

    -- * Output
  , word64
  , word64_range
  , int_range
  , double

    -- * Streams
  , jump
  , long_jump
  ) where

import qualified Crypto.Range as Range
import qualified Crypto.Xoshiro as X
import Data.Bits ((.>>.))
import Data.Word (Word64)

-- utils ----------------------------------------------------------------------

fi :: (Integral a, Num b) => a -> b
fi :: forall a b. (Integral a, Num b) => a -> b
fi = a -> b
forall a b. (Integral a, Num b) => a -> b
fromIntegral
{-# INLINE fi #-}

-- generator ------------------------------------------------------------------

-- | A xoshiro256++ generator.
newtype Gen = Gen X.S

-- | A generated value, along with the next generator.
data Draw a = Draw !a {-# UNPACK #-} !Gen

-- | Create a generator from a 64-bit seed, expanded to the full
--   256-bit state via splitmix64, per the xoshiro authors'
--   recommendation.
--
--   >>> let Draw w _ = word64 (new 42)
--   >>> w
--   15021278609987233951
new :: Word64 -> Gen
new :: Word64 -> Gen
new = S -> Gen
Gen (S -> Gen) -> (Word64 -> S) -> Word64 -> Gen
forall b c a. (b -> c) -> (a -> b) -> a -> c
. Word64 -> S
X.seed
{-# INLINE new #-}

-- | Create a generator from the given 256-bit state, returning
--   'Nothing' if it is all zero.
--
--   >>> let Just gen = from_state 1 2 3 4
--   >>> let Draw w _ = word64 gen
--   >>> w
--   41943041
from_state :: Word64 -> Word64 -> Word64 -> Word64 -> Maybe Gen
from_state :: Word64 -> Word64 -> Word64 -> Word64 -> Maybe Gen
from_state Word64
s0 Word64
s1 Word64
s2 Word64
s3 = (S -> Gen) -> Maybe S -> Maybe Gen
forall a b. (a -> b) -> Maybe a -> Maybe b
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap S -> Gen
Gen (Word64 -> Word64 -> Word64 -> Word64 -> Maybe S
X.from_words Word64
s0 Word64
s1 Word64
s2 Word64
s3)
{-# INLINE from_state #-}

-- | Create a generator with a 256-bit state drawn from the operating
--   system's entropy source, returning 'Nothing' if that fails.
--
--   >>> Just gen <- new_system
new_system :: IO (Maybe Gen)
new_system :: IO (Maybe Gen)
new_system = (Maybe S -> Maybe Gen) -> IO (Maybe S) -> IO (Maybe Gen)
forall a b. (a -> b) -> IO a -> IO b
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap ((S -> Gen) -> Maybe S -> Maybe Gen
forall a b. (a -> b) -> Maybe a -> Maybe b
forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap S -> Gen
Gen) IO (Maybe S)
X.system

-- output ---------------------------------------------------------------------

-- | Generate a uniformly-distributed 'Word64'.
--
--   >>> let Just gen = from_state 1 2 3 4
--   >>> let Draw a g1 = word64 gen
--   >>> let Draw b _  = word64 g1
--   >>> (a, b)
--   (41943041,58720359)
word64 :: Gen -> Draw Word64
word64 :: Gen -> Draw Word64
word64 (Gen S
s) = Word64 -> Gen -> Draw Word64
forall a. a -> Gen -> Draw a
Draw (S -> Word64
X.output S
s) (S -> Gen
Gen (S -> S
X.next S
s))
{-# INLINE word64 #-}

-- | Generate a uniformly-distributed 'Word64' in the given inclusive
--   range, whose bounds may be given in either order.
--
--   The result is unbiased; see 'int_range'.
--
--   >>> let Draw w _ = word64_range 1 6 (new 42)
--   >>> w
--   5
word64_range :: Word64 -> Word64 -> Gen -> Draw Word64
word64_range :: Word64 -> Word64 -> Gen -> Draw Word64
word64_range Word64
a Word64
b (Gen S
s) =
  let !lo :: Word64
lo = Word64 -> Word64 -> Word64
forall a. Ord a => a -> a -> a
min Word64
a Word64
b
      !hi :: Word64
hi = Word64 -> Word64 -> Word64
forall a. Ord a => a -> a -> a
max Word64
a Word64
b
      !(Word64
r, S
ns) = (S -> (Word64, S)) -> Word64 -> S -> (Word64, S)
forall g. (g -> (Word64, g)) -> Word64 -> g -> (Word64, g)
Range.upto_pure S -> (Word64, S)
step (Word64
hi Word64 -> Word64 -> Word64
forall a. Num a => a -> a -> a
- Word64
lo) S
s
  in  Word64 -> Gen -> Draw Word64
forall a. a -> Gen -> Draw a
Draw (Word64
lo Word64 -> Word64 -> Word64
forall a. Num a => a -> a -> a
+ Word64
r) (S -> Gen
Gen S
ns)
{-# INLINE word64_range #-}

-- | Generate a uniformly-distributed 'Int' in the given inclusive
--   range, whose bounds may be given in either order.
--
--   The result is unbiased, via Lemire's method: an occasional draw is
--   rejected and replaced, so the number of words consumed varies.
--
--   >>> let Draw x _ = int_range (-10) 10 (new 42)
--   >>> x
--   7
int_range :: Int -> Int -> Gen -> Draw Int
int_range :: Int -> Int -> Gen -> Draw Int
int_range Int
a Int
b (Gen S
s) =
  let !lo :: Int
lo = Int -> Int -> Int
forall a. Ord a => a -> a -> a
min Int
a Int
b
      !hi :: Int
hi = Int -> Int -> Int
forall a. Ord a => a -> a -> a
max Int
a Int
b
      !(Word64
r, S
ns) = (S -> (Word64, S)) -> Word64 -> S -> (Word64, S)
forall g. (g -> (Word64, g)) -> Word64 -> g -> (Word64, g)
Range.upto_pure S -> (Word64, S)
step (Int -> Word64
forall a b. (Integral a, Num b) => a -> b
fi Int
hi Word64 -> Word64 -> Word64
forall a. Num a => a -> a -> a
- Int -> Word64
forall a b. (Integral a, Num b) => a -> b
fi Int
lo) S
s
  in  Int -> Gen -> Draw Int
forall a. a -> Gen -> Draw a
Draw (Int
lo Int -> Int -> Int
forall a. Num a => a -> a -> a
+ Word64 -> Int
forall a b. (Integral a, Num b) => a -> b
fi Word64
r) (S -> Gen
Gen S
ns)
{-# INLINE int_range #-}

-- | Generate a uniformly-distributed 'Double' in [0, 1), from the
--   upper 53 bits of a 'Word64'.
--
--   >>> let Just gen = from_state 1 2 3 4
--   >>> let Draw d _ = double gen
--   >>> d
--   2.2737367544323206e-12
double :: Gen -> Draw Double
double :: Gen -> Draw Double
double Gen
gen = case Gen -> Draw Word64
word64 Gen
gen of
  -- 2 ^ -53
  Draw Word64
w Gen
ng -> Double -> Gen -> Draw Double
forall a. a -> Gen -> Draw a
Draw (Word64 -> Double
forall a b. (Integral a, Num b) => a -> b
fi (Word64
w Word64 -> Int -> Word64
forall a. Bits a => a -> Int -> a
.>>. Int
11) Double -> Double -> Double
forall a. Num a => a -> a -> a
* Double
1.1102230246251565e-16) Gen
ng
{-# INLINE double #-}

-- one step of the generator, for 'Range.upto_pure'
step :: X.S -> (Word64, X.S)
step :: S -> (Word64, S)
step S
s = (S -> Word64
X.output S
s, S -> S
X.next S
s)
{-# INLINE step #-}

-- streams --------------------------------------------------------------------

-- | Advance a generator by 2 ^ 128 outputs.
--
--   Repeated jumps yield up to 2 ^ 128 non-overlapping streams of
--   2 ^ 128 outputs each, e.g. one per thread.
--
--   >>> let gens = take 4 (iterate jump (new 42))
jump :: Gen -> Gen
jump :: Gen -> Gen
jump (Gen S
s) = S -> Gen
Gen (S -> S
X.jump S
s)

-- | Advance a generator by 2 ^ 192 outputs.
--
--   Repeated long jumps yield up to 2 ^ 64 starting points, from each
--   of which 'jump' yields 2 ^ 64 non-overlapping streams.
--
--   >>> let starts = take 4 (iterate long_jump (new 42))
long_jump :: Gen -> Gen
long_jump :: Gen -> Gen
long_jump (Gen S
s) = S -> Gen
Gen (S -> S
X.long_jump S
s)