random-1.3.0: Pseudo-random number generation

Copyright | (c) The University of Glasgow 2001
License | BSD-style (see the file LICENSE in the 'random' repository)
Maintainer | libraries@haskell.org
Stability | stable
Safe Haskell | Trustworthy
Language | Haskell2010

System.Random.Stateful

Contents

- Pure Random Generator
- Monadic Random Generator
- Usage
- Mutable pseudo-random number generator interfaces
  - Deprecated
- Monadic adapters for pure pseudo-random number generators
  - Pure adapter in `MonadState`
  - Mutable thread-safe adapter in `IO`
  - Mutable adapter in `IO`
  - Mutable adapter in `ST`
  - Mutable thread-safe adapter in `STM`
- Pseudo-random values of various types
  - Lists
  - Generators for sequences of pseudo-random bytes
- Helper functions for createing instances
  - Sequences of bytes
  - Floating point numbers
  - Enum types
  - Word
- Appendix
  - How to implement `StatefulGen`
  - Floating point number caveats
- References

Description

This library deals with the common task of pseudo-random number generation.

Synopsis

- class RandomGen g where
  - next :: g -> (Int, g)
  - genWord8 :: g -> (Word8, g)
  - genWord16 :: g -> (Word16, g)
  - genWord32 :: g -> (Word32, g)
  - genWord64 :: g -> (Word64, g)
  - genWord32R :: Word32 -> g -> (Word32, g)
  - genWord64R :: Word64 -> g -> (Word64, g)
  - genShortByteString :: Int -> g -> (ShortByteString, g)
  - unsafeUniformFillMutableByteArray :: MutableByteArray s -> Int -> Int -> g -> ST s g
  - genRange :: g -> (Int, Int)
  - split :: g -> (g, g)
- class RandomGen g => SplitGen g where
  - splitGen :: g -> (g, g)
- uniform :: (Uniform a, RandomGen g) => g -> (a, g)
- uniformR :: (UniformRange a, RandomGen g) => (a, a) -> g -> (a, g)
- class Random a where
  - randomR :: RandomGen g => (a, a) -> g -> (a, g)
  - random :: RandomGen g => g -> (a, g)
  - randomRs :: RandomGen g => (a, a) -> g -> [a]
  - randoms :: RandomGen g => g -> [a]
- class Uniform a
- class UniformRange a
- class Finite a
- data Seed g
- uniforms :: (Uniform a, RandomGen g) => g -> [a]
- uniformRs :: (UniformRange a, RandomGen g) => (a, a) -> g -> [a]
- uniformList :: (Uniform a, RandomGen g) => Int -> g -> ([a], g)
- uniformListR :: (UniformRange a, RandomGen g) => Int -> (a, a) -> g -> ([a], g)
- uniformShuffleList :: RandomGen g => [a] -> g -> ([a], g)
- uniformByteArray :: RandomGen g => Bool -> Int -> g -> (ByteArray, g)
- uniformByteString :: RandomGen g => Int -> g -> (ByteString, g)
- uniformFillMutableByteArray :: RandomGen g => MutableByteArray s -> Int -> Int -> g -> ST s g
- genByteString :: RandomGen g => Int -> g -> (ByteString, g)
- data StdGen
- mkStdGen :: Int -> StdGen
- mkStdGen64 :: Word64 -> StdGen
- initStdGen :: MonadIO m => m StdGen
- getStdRandom :: MonadIO m => (StdGen -> (a, StdGen)) -> m a
- getStdGen :: MonadIO m => m StdGen
- setStdGen :: MonadIO m => StdGen -> m ()
- newStdGen :: MonadIO m => m StdGen
- randomIO :: (Random a, MonadIO m) => m a
- randomRIO :: (Random a, MonadIO m) => (a, a) -> m a
- class (KnownNat (SeedSize g), 1 <= SeedSize g, Typeable g) => SeedGen g where
  - type SeedSize g :: Nat
  - fromSeed :: Seed g -> g
  - toSeed :: g -> Seed g
  - fromSeed64 :: NonEmpty Word64 -> g
  - toSeed64 :: g -> NonEmpty Word64
- seedSize :: SeedGen g => Int
- seedSizeProxy :: forall proxy g. SeedGen g => proxy g -> Int
- mkSeed :: (SeedGen g, MonadFail m) => ByteArray -> m (Seed g)
- unSeed :: Seed g -> ByteArray
- mkSeedFromByteString :: (SeedGen g, MonadFail m) => ByteString -> m (Seed g)
- unSeedToByteString :: Seed g -> ByteString
- withSeed :: SeedGen g => Seed g -> (g -> (a, g)) -> (a, Seed g)
- withSeedM :: (SeedGen g, Functor f) => Seed g -> (g -> f (a, g)) -> f (a, Seed g)
- withSeedFile :: (SeedGen g, MonadIO m) => FilePath -> (Seed g -> m (a, Seed g)) -> m a
- seedGenTypeName :: SeedGen g => String
- nonEmptyToSeed :: SeedGen g => NonEmpty Word64 -> Seed g
- nonEmptyFromSeed :: SeedGen g => Seed g -> NonEmpty Word64
- type family SeedSize g :: Nat
- class Monad m => StatefulGen g (m :: Type -> Type) where
  - uniformWord32R :: Word32 -> g -> m Word32
  - uniformWord64R :: Word64 -> g -> m Word64
  - uniformWord8 :: g -> m Word8
  - uniformWord16 :: g -> m Word16
  - uniformWord32 :: g -> m Word32
  - uniformWord64 :: g -> m Word64
  - uniformShortByteString :: Int -> g -> m ShortByteString
- class StatefulGen (MutableGen f m) m => FrozenGen f (m :: Type -> Type) where
  - type MutableGen f (m :: Type -> Type) = (g :: Type) | g -> f
  - freezeGen :: MutableGen f m -> m f
  - modifyGen :: MutableGen f m -> (f -> (a, f)) -> m a
  - overwriteGen :: MutableGen f m -> f -> m ()
- class FrozenGen f m => ThawedGen f (m :: Type -> Type) where
  - thawGen :: f -> m (MutableGen f m)
- withMutableGen :: ThawedGen f m => f -> (MutableGen f m -> m a) -> m (a, f)
- withMutableGen_ :: ThawedGen f m => f -> (MutableGen f m -> m a) -> m a
- withSeedMutableGen :: (SeedGen g, ThawedGen g m) => Seed g -> (MutableGen g m -> m a) -> m (a, Seed g)
- withSeedMutableGen_ :: (SeedGen g, ThawedGen g m) => Seed g -> (MutableGen g m -> m a) -> m a
- randomM :: (Random a, RandomGen g, FrozenGen g m) => MutableGen g m -> m a
- randomRM :: (Random a, RandomGen g, FrozenGen g m) => (a, a) -> MutableGen g m -> m a
- splitGenM :: (SplitGen f, FrozenGen f m) => MutableGen f m -> m f
- splitMutableGenM :: (SplitGen f, ThawedGen f m) => MutableGen f m -> m (MutableGen f m)
- class (RandomGen r, StatefulGen g m) => RandomGenM g r (m :: Type -> Type) | g -> r where
  - applyRandomGenM :: (r -> (a, r)) -> g -> m a
- newtype StateGen g = StateGen {
  - unStateGen :: g
  }
- data StateGenM g = StateGenM
- runStateGen :: RandomGen g => g -> (StateGenM g -> State g a) -> (a, g)
- runStateGen_ :: RandomGen g => g -> (StateGenM g -> State g a) -> a
- runStateGenT :: RandomGen g => g -> (StateGenM g -> StateT g m a) -> m (a, g)
- runStateGenT_ :: (RandomGen g, Functor f) => g -> (StateGenM g -> StateT g f a) -> f a
- runStateGenST :: RandomGen g => g -> (forall s. StateGenM g -> StateT g (ST s) a) -> (a, g)
- runStateGenST_ :: RandomGen g => g -> (forall s. StateGenM g -> StateT g (ST s) a) -> a
- newtype AtomicGen g = AtomicGen {
  - unAtomicGen :: g
  }
- newtype AtomicGenM g = AtomicGenM {
  - unAtomicGenM :: IORef g
  }
- newAtomicGenM :: MonadIO m => g -> m (AtomicGenM g)
- applyAtomicGen :: MonadIO m => (g -> (a, g)) -> AtomicGenM g -> m a
- globalStdGen :: AtomicGenM StdGen
- newtype IOGen g = IOGen {
  - unIOGen :: g
  }
- newtype IOGenM g = IOGenM {
  - unIOGenM :: IORef g
  }
- newIOGenM :: MonadIO m => g -> m (IOGenM g)
- applyIOGen :: MonadIO m => (g -> (a, g)) -> IOGenM g -> m a
- newtype STGen g = STGen {
  - unSTGen :: g
  }
- newtype STGenM g s = STGenM {
  - unSTGenM :: STRef s g
  }
- newSTGenM :: g -> ST s (STGenM g s)
- applySTGen :: (g -> (a, g)) -> STGenM g s -> ST s a
- runSTGen :: RandomGen g => g -> (forall s. STGenM g s -> ST s a) -> (a, g)
- runSTGen_ :: RandomGen g => g -> (forall s. STGenM g s -> ST s a) -> a
- newtype TGen g = TGen {
  - unTGen :: g
  }
- newtype TGenM g = TGenM {
  - unTGenM :: TVar g
  }
- newTGenM :: g -> STM (TGenM g)
- newTGenMIO :: MonadIO m => g -> m (TGenM g)
- applyTGen :: (g -> (a, g)) -> TGenM g -> STM a
- class Uniform a where
  - uniformM :: StatefulGen g m => g -> m a
- uniformViaFiniteM :: (StatefulGen g m, Generic a, GFinite (Rep a)) => g -> m a
- class UniformRange a where
  - uniformRM :: StatefulGen g m => (a, a) -> g -> m a
  - isInRange :: (a, a) -> a -> Bool
- isInRangeOrd :: Ord a => (a, a) -> a -> Bool
- isInRangeEnum :: Enum a => (a, a) -> a -> Bool
- uniformListM :: (StatefulGen g m, Uniform a) => Int -> g -> m [a]
- uniformListRM :: (StatefulGen g m, UniformRange a) => Int -> (a, a) -> g -> m [a]
- uniformShuffleListM :: StatefulGen g m => [a] -> g -> m [a]
- uniformByteArrayM :: StatefulGen g m => Bool -> Int -> g -> m ByteArray
- uniformByteStringM :: StatefulGen g m => Int -> g -> m ByteString
- uniformShortByteStringM :: StatefulGen g m => Int -> g -> m ShortByteString
- fillByteArrayST :: Bool -> Int -> ST s Word64 -> ST s ByteArray
- genShortByteStringIO :: Int -> IO Word64 -> IO ShortByteString
- genShortByteStringST :: Int -> ST s Word64 -> ST s ShortByteString
- defaultUnsafeUniformFillMutableByteArray :: RandomGen g => MutableByteArray s -> Int -> Int -> g -> ST s g
- uniformDouble01M :: StatefulGen g m => g -> m Double
- uniformDoublePositive01M :: StatefulGen g m => g -> m Double
- uniformFloat01M :: StatefulGen g m => g -> m Float
- uniformFloatPositive01M :: StatefulGen g m => g -> m Float
- uniformEnumM :: (Enum a, Bounded a, StatefulGen g m) => g -> m a
- uniformEnumRM :: (Enum a, StatefulGen g m) => (a, a) -> g -> m a
- uniformWordR :: StatefulGen g m => Word -> g -> m Word
- scaleFloating :: (RealFloat a, Integral w, Bounded w, FiniteBits w) => a -> a -> w -> a

# Pure Random Generator

class RandomGen g where #

`RandomGen` is an interface to pure pseudo-random number generators.

`StdGen` is the standard `RandomGen` instance provided by this library.

Since: 1.0.0

Minimal complete definition

(genWord32 | genWord64 | next, genRange)

Methods

next :: g -> (Int, g) #

Deprecated: No longer used

Returns an `Int` that is uniformly distributed over the range returned by `genRange` (including both end points), and a new generator. Using `next` is inefficient as all operations go via `Integer`. See here for more details. It is thus deprecated.

Since: 1.0.0

genWord8 :: g -> (Word8, g) #

Returns a `Word8` that is uniformly distributed over the entire `Word8` range.

Since: 1.2.0

genWord16 :: g -> (Word16, g) #

Returns a `Word16` that is uniformly distributed over the entire `Word16` range.

Since: 1.2.0

genWord32 :: g -> (Word32, g) #

Returns a `Word32` that is uniformly distributed over the entire `Word32` range.

Since: 1.2.0

genWord64 :: g -> (Word64, g) #

Returns a `Word64` that is uniformly distributed over the entire `Word64` range.

Since: 1.2.0

genWord32R :: Word32 -> g -> (Word32, g) #

`genWord32R upperBound g` returns a `Word32` that is uniformly distributed over the range `[0, upperBound]`.

Since: 1.2.0

genWord64R :: Word64 -> g -> (Word64, g) #

`genWord64R upperBound g` returns a `Word64` that is uniformly distributed over the range `[0, upperBound]`.

Since: 1.2.0

genShortByteString :: Int -> g -> (ShortByteString, g) #

Deprecated: In favor of `uniformShortByteString`

Same as ``uniformByteArray` `False``, but for `ShortByteString`.

`genShortByteString n g` returns a `ShortByteString` of length `n` filled with pseudo-random bytes.

Note - This function will be removed from the type class in the next major release as it is no longer needed because of `unsafeUniformFillMutableByteArray`.

Since: 1.2.0

unsafeUniformFillMutableByteArray #

Arguments

:: MutableByteArray s | Mutable array to fill with random bytes
-> Int | Offset into a mutable array from the beginning in number of bytes. Offset must be non-negative, but this will not be checked
-> Int | Number of randomly generated bytes to write into the array. Number of bytes must be non-negative and less then the total size of the array, minus the offset. This also will be checked.
-> g |
-> ST s g |

Fill in the supplied `MutableByteArray` with uniformly generated random bytes. This function is unsafe because it is not required to do any bounds checking. For a safe variant use `uniformFillMutableByteArrayM` instead.

Default type class implementation uses `defaultUnsafeUniformFillMutableByteArray`.

Since: 1.3.0

genRange :: g -> (Int, Int) #

Deprecated: No longer used

Yields the range of values returned by `next`.

It is required that:

- If `(a, b) = `genRange` g`, then `a < b`.
- `genRange` must not examine its argument so the value it returns is determined only by the instance of `RandomGen`.

The default definition spans the full range of `Int`.

Since: 1.0.0

split :: g -> (g, g) #

Deprecated: In favor of `splitGen`

Returns two distinct pseudo-random number generators.

Implementations should take care to ensure that the resulting generators are not correlated. Some pseudo-random number generators are not splittable. In that case, the `split` implementation should fail with a descriptive `error` message.

Since: 1.0.0

default split :: SplitGen g => g -> (g, g) #

#### Instances

Instances details

RandomGen StdGen # |
Instance details Defined in System.Random.Internal Methods next :: StdGen -> (Int, StdGen) # genWord8 :: StdGen -> (Word8, StdGen) # genWord16 :: StdGen -> (Word16, StdGen) # genWord32 :: StdGen -> (Word32, StdGen) # genWord64 :: StdGen -> (Word64, StdGen) # genWord32R :: Word32 -> StdGen -> (Word32, StdGen) # genWord64R :: Word64 -> StdGen -> (Word64, StdGen) # genShortByteString :: Int -> StdGen -> (ShortByteString, StdGen) # unsafeUniformFillMutableByteArray :: MutableByteArray s -> Int -> Int -> StdGen -> ST s StdGen # genRange :: StdGen -> (Int, Int) # split :: StdGen -> (StdGen, StdGen) #
RandomGen SMGen # |
Instance details Defined in System.Random.Internal Methods next :: SMGen -> (Int, SMGen) # genWord8 :: SMGen -> (Word8, SMGen) # genWord16 :: SMGen -> (Word16, SMGen) # genWord32 :: SMGen -> (Word32, SMGen) # genWord64 :: SMGen -> (Word64, SMGen) # genWord32R :: Word32 -> SMGen -> (Word32, SMGen) # genWord64R :: Word64 -> SMGen -> (Word64, SMGen) # genShortByteString :: Int -> SMGen -> (ShortByteString, SMGen) # unsafeUniformFillMutableByteArray :: MutableByteArray s -> Int -> Int -> SMGen -> ST s SMGen # genRange :: SMGen -> (Int, Int) # split :: SMGen -> (SMGen, SMGen) #
RandomGen SMGen # |
Instance details Defined in System.Random.Internal Methods next :: SMGen -> (Int, SMGen) # genWord8 :: SMGen -> (Word8, SMGen) # genWord16 :: SMGen -> (Word16, SMGen) # genWord32 :: SMGen -> (Word32, SMGen) # genWord64 :: SMGen -> (Word64, SMGen) # genWord32R :: Word32 -> SMGen -> (Word32, SMGen) # genWord64R :: Word64 -> SMGen -> (Word64, SMGen) # genShortByteString :: Int -> SMGen -> (ShortByteString, SMGen) # unsafeUniformFillMutableByteArray :: MutableByteArray s -> Int -> Int -> SMGen -> ST s SMGen # genRange :: SMGen -> (Int, Int) # split :: SMGen -> (SMGen, SMGen) #
RandomGen g => RandomGen (StateGen g) # |
Instance details Defined in System.Random.Internal Methods next :: StateGen g -> (Int, StateGen g) # genWord8 :: StateGen g -> (Word8, StateGen g) # genWord16 :: StateGen g -> (Word16, StateGen g) # genWord32 :: StateGen g -> (Word32, StateGen g) # genWord64 :: StateGen g -> (Word64, StateGen g) # genWord32R :: Word32 -> StateGen g -> (Word32, StateGen g) # genWord64R :: Word64 -> StateGen g -> (Word64, StateGen g) # genShortByteString :: Int -> StateGen g -> (ShortByteString, StateGen g) # unsafeUniformFillMutableByteArray :: MutableByteArray s -> Int -> Int -> StateGen g -> ST s (StateGen g) # genRange :: StateGen g -> (Int, Int) # split :: StateGen g -> (StateGen g, StateGen g) #
RandomGen g => RandomGen (AtomicGen g) # |
Instance details Defined in System.Random.Stateful Methods next :: AtomicGen g -> (Int, AtomicGen g) # genWord8 :: AtomicGen g -> (Word8, AtomicGen g) # genWord16 :: AtomicGen g -> (Word16, AtomicGen g) # genWord32 :: AtomicGen g -> (Word32, AtomicGen g) # genWord64 :: AtomicGen g -> (Word64, AtomicGen g) # genWord32R :: Word32 -> AtomicGen g -> (Word32, AtomicGen g) # genWord64R :: Word64 -> AtomicGen g -> (Word64, AtomicGen g) # genShortByteString :: Int -> AtomicGen g -> (ShortByteString, AtomicGen g) # unsafeUniformFillMutableByteArray :: MutableByteArray s -> Int -> Int -> AtomicGen g -> ST s (AtomicGen g) # genRange :: AtomicGen g -> (Int, Int) # split :: AtomicGen g -> (AtomicGen g, AtomicGen g) #
RandomGen g => RandomGen (IOGen g) # |
Instance details Defined in System.Random.Stateful Methods next :: IOGen g -> (Int, IOGen g) # genWord8 :: IOGen g -> (Word8, IOGen g) # genWord16 :: IOGen g -> (Word16, IOGen g) # genWord32 :: IOGen g -> (Word32, IOGen g) # genWord64 :: IOGen g -> (Word64, IOGen g) # genWord32R :: Word32 -> IOGen g -> (Word32, IOGen g) # genWord64R :: Word64 -> IOGen g -> (Word64, IOGen g) # genShortByteString :: Int -> IOGen g -> (ShortByteString, IOGen g) # unsafeUniformFillMutableByteArray :: MutableByteArray s -> Int -> Int -> IOGen g -> ST s (IOGen g) # genRange :: IOGen g -> (Int, Int) # split :: IOGen g -> (IOGen g, IOGen g) #
RandomGen g => RandomGen (STGen g) # |
Instance details Defined in System.Random.Stateful Methods next :: STGen g -> (Int, STGen g) # genWord8 :: STGen g -> (Word8, STGen g) # genWord16 :: STGen g -> (Word16, STGen g) # genWord32 :: STGen g -> (Word32, STGen g) # genWord64 :: STGen g -> (Word64, STGen g) # genWord32R :: Word32 -> STGen g -> (Word32, STGen g) # genWord64R :: Word64 -> STGen g -> (Word64, STGen g) # genShortByteString :: Int -> STGen g -> (ShortByteString, STGen g) # unsafeUniformFillMutableByteArray :: MutableByteArray s -> Int -> Int -> STGen g -> ST s (STGen g) # genRange :: STGen g -> (Int, Int) # split :: STGen g -> (STGen g, STGen g) #
RandomGen g => RandomGen (TGen g) # |
Instance details Defined in System.Random.Stateful Methods next :: TGen g -> (Int, TGen g) # genWord8 :: TGen g -> (Word8, TGen g) # genWord16 :: TGen g -> (Word16, TGen g) # genWord32 :: TGen g -> (Word32, TGen g) # genWord64 :: TGen g -> (Word64, TGen g) # genWord32R :: Word32 -> TGen g -> (Word32, TGen g) # genWord64R :: Word64 -> TGen g -> (Word64, TGen g) # genShortByteString :: Int -> TGen g -> (ShortByteString, TGen g) # unsafeUniformFillMutableByteArray :: MutableByteArray s -> Int -> Int -> TGen g -> ST s (TGen g) # genRange :: TGen g -> (Int, Int) # split :: TGen g -> (TGen g, TGen g) #

class RandomGen g => SplitGen g where #

Pseudo-random generators that can be split into two separate and independent psuedo-random generators should provide an instance for this type class.

Historically this functionality was included in the `RandomGen` type class in the `split` function, however, few pseudo-random generators possess this property of splittability. This lead the old `split` function being usually implemented in terms of `error`.

Since: 1.3.0

Methods

splitGen :: g -> (g, g) #

Returns two distinct pseudo-random number generators.

Implementations should take care to ensure that the resulting generators are not correlated.

Since: 1.3.0

#### Instances

Instances details

SplitGen StdGen # |
Instance details Defined in System.Random.Internal Methods splitGen :: StdGen -> (StdGen, StdGen) #
SplitGen SMGen # |
Instance details Defined in System.Random.Internal Methods splitGen :: SMGen -> (SMGen, SMGen) #
SplitGen SMGen # |
Instance details Defined in System.Random.Internal Methods splitGen :: SMGen -> (SMGen, SMGen) #
SplitGen g => SplitGen (AtomicGen g) # |
Instance details Defined in System.Random.Stateful Methods splitGen :: AtomicGen g -> (AtomicGen g, AtomicGen g) #
SplitGen g => SplitGen (IOGen g) # |
Instance details Defined in System.Random.Stateful Methods splitGen :: IOGen g -> (IOGen g, IOGen g) #
SplitGen g => SplitGen (STGen g) # |
Instance details Defined in System.Random.Stateful Methods splitGen :: STGen g -> (STGen g, STGen g) #
SplitGen g => SplitGen (TGen g) # |
Instance details Defined in System.Random.Stateful Methods splitGen :: TGen g -> (TGen g, TGen g) #

uniform :: (Uniform a, RandomGen g) => g -> (a, g) #

Generates a value uniformly distributed over all possible values of that type.

This is a pure version of `uniformM`.

#### Examples

Expand

    >>> import System.Random
    >>> let pureGen = mkStdGen 137
    >>> uniform pureGen :: (Bool, StdGen)
    (True,StdGen {unStdGen = SMGen 11285859549637045894 7641485672361121627})

You can use type applications to disambiguate the type of the generated numbers:

    >>> :seti -XTypeApplications
    >>> uniform @Bool pureGen
    (True,StdGen {unStdGen = SMGen 11285859549637045894 7641485672361121627})

Since: 1.2.0

uniformR :: (UniformRange a, RandomGen g) => (a, a) -> g -> (a, g) #

Generates a value uniformly distributed over the provided range, which is interpreted as inclusive in the lower and upper bound.

- `uniformR (1 :: Int, 4 :: Int)` generates values uniformly from the set \(\{1,2,3,4\}\)
- `uniformR (1 :: Float, 4 :: Float)` generates values uniformly from the set \(\{x\;|\;1 \le x \le 4\}\)

The following law should hold to make the function always defined:

    uniformR (a, b) = uniformR (b, a)

This is a pure version of `uniformRM`.

#### Examples

Expand

    >>> import System.Random
    >>> let pureGen = mkStdGen 137
    >>> uniformR (1 :: Int, 4 :: Int) pureGen
    (4,StdGen {unStdGen = SMGen 11285859549637045894 7641485672361121627})

You can use type applications to disambiguate the type of the generated numbers:

    >>> :seti -XTypeApplications
    >>> uniformR @Int (1, 4) pureGen
    (4,StdGen {unStdGen = SMGen 11285859549637045894 7641485672361121627})

Since: 1.2.0

class Random a where #

The class of types for which random values can be generated. Most instances of `Random` will produce values that are uniformly distributed on the full range, but for those types without a well-defined "full range" some sensible default subrange will be selected.

`Random` exists primarily for backwards compatibility with version 1.1 of this library. In new code, use the better specified `Uniform` and `UniformRange` instead.

Since: 1.0.0

Minimal complete definition

Nothing

Methods

randomR :: RandomGen g => (a, a) -> g -> (a, g) #

Takes a range (lo,hi) and a pseudo-random number generator g, and returns a pseudo-random value uniformly distributed over the closed interval [lo,hi], together with a new generator. It is unspecified what happens if lo>hi, but usually the values will simply get swapped.

    >>> let gen = mkStdGen 26
    >>> fst $ randomR ('a', 'z') gen
    'z'
    >>> fst $ randomR ('a', 'z') gen
    'z'

For continuous types there is no requirement that the values lo and hi are ever produced, but they may be, depending on the implementation and the interval.

There is no requirement to follow the `Ord` instance and the concept of range can be defined on per type basis. For example product types will treat their values independently:

    >>> fst $ randomR (('a', 5.0), ('z', 10.0)) $ mkStdGen 26
    ('z',5.22694980853051)

In case when a lawful range is desired `uniformR` should be used instead.

Since: 1.0.0

default randomR :: (RandomGen g, UniformRange a) => (a, a) -> g -> (a, g) #

random :: RandomGen g => g -> (a, g) #

The same as `randomR`, but using a default range determined by the type:

- For bounded types (instances of `Bounded`, such as `Char`), the range is normally the whole type.
- For floating point types, the range is normally the closed interval `[0,1]`.
- For `Integer`, the range is (arbitrarily) the range of `Int`.

Since: 1.0.0

default random :: (RandomGen g, Uniform a) => g -> (a, g) #

randomRs :: RandomGen g => (a, a) -> g -> [a] #

Plural variant of `randomR`, producing an infinite list of pseudo-random values instead of returning a new generator.

Since: 1.0.0

randoms :: RandomGen g => g -> [a] #

Plural variant of `random`, producing an infinite list of pseudo-random values instead of returning a new generator.

Since: 1.0.0

#### Instances

Instances details

Random CBool # |
Instance details Defined in System.Random Methods randomR :: RandomGen g => (CBool, CBool) -> g -> (CBool, g) # random :: RandomGen g => g -> (CBool, g) # randomRs :: RandomGen g => (CBool, CBool) -> g -> [CBool] # randoms :: RandomGen g => g -> [CBool] #
Random CChar # |
Instance details Defined in System.Random Methods randomR :: RandomGen g => (CChar, CChar) -> g -> (CChar, g) # random :: RandomGen g => g -> (CChar, g) # randomRs :: RandomGen g => (CChar, CChar) -> g -> [CChar] # randoms :: RandomGen g => g -> [CChar] #
Random CDouble # | Note - `random` produces values in the closed range `[0,1]`.
Instance details Defined in System.Random Methods randomR :: RandomGen g => (CDouble, CDouble) -> g -> (CDouble, g) # random :: RandomGen g => g -> (CDouble, g) # randomRs :: RandomGen g => (CDouble, CDouble) -> g -> [CDouble] # randoms :: RandomGen g => g -> [CDouble] #
Random CFloat # | Note - `random` produces values in the closed range `[0,1]`.
Instance details Defined in System.Random Methods randomR :: RandomGen g => (CFloat, CFloat) -> g -> (CFloat, g) # random :: RandomGen g => g -> (CFloat, g) # randomRs :: RandomGen g => (CFloat, CFloat) -> g -> [CFloat] # randoms :: RandomGen g => g -> [CFloat] #
Random CInt # |
Instance details Defined in System.Random Methods randomR :: RandomGen g => (CInt, CInt) -> g -> (CInt, g) # random :: RandomGen g => g -> (CInt, g) # randomRs :: RandomGen g => (CInt, CInt) -> g -> [CInt] # randoms :: RandomGen g => g -> [CInt] #
Random CIntMax # |
Instance details Defined in System.Random Methods randomR :: RandomGen g => (CIntMax, CIntMax) -> g -> (CIntMax, g) # random :: RandomGen g => g -> (CIntMax, g) # randomRs :: RandomGen g => (CIntMax, CIntMax) -> g -> [CIntMax] # randoms :: RandomGen g => g -> [CIntMax] #
Random CIntPtr # |
Instance details Defined in System.Random Methods randomR :: RandomGen g => (CIntPtr, CIntPtr) -> g -> (CIntPtr, g) # random :: RandomGen g => g -> (CIntPtr, g) # randomRs :: RandomGen g => (CIntPtr, CIntPtr) -> g -> [CIntPtr] # randoms :: RandomGen g => g -> [CIntPtr] #
Random CLLong # |
Instance details Defined in System.Random Methods randomR :: RandomGen g => (CLLong, CLLong) -> g -> (CLLong, g) # random :: RandomGen g => g -> (CLLong, g) # randomRs :: RandomGen g => (CLLong, CLLong) -> g -> [CLLong] # randoms :: RandomGen g => g -> [CLLong] #
Random CLong # |
Instance details Defined in System.Random Methods randomR :: RandomGen g => (CLong, CLong) -> g -> (CLong, g) # random :: RandomGen g => g -> (CLong, g) # randomRs :: RandomGen g => (CLong, CLong) -> g -> [CLong] # randoms :: RandomGen g => g -> [CLong] #
Random CPtrdiff # |
Instance details Defined in System.Random Methods randomR :: RandomGen g => (CPtrdiff, CPtrdiff) -> g -> (CPtrdiff, g) # random :: RandomGen g => g -> (CPtrdiff, g) # randomRs :: RandomGen g => (CPtrdiff, CPtrdiff) -> g -> [CPtrdiff] # randoms :: RandomGen g => g -> [CPtrdiff] #
Random CSChar # |
Instance details Defined in System.Random Methods randomR :: RandomGen g => (CSChar, CSChar) -> g -> (CSChar, g) # random :: RandomGen g => g -> (CSChar, g) # randomRs :: RandomGen g => (CSChar, CSChar) -> g -> [CSChar] # randoms :: RandomGen g => g -> [CSChar] #
Random CShort # |
Instance details Defined in System.Random Methods randomR :: RandomGen g => (CShort, CShort) -> g -> (CShort, g) # random :: RandomGen g => g -> (CShort, g) # randomRs :: RandomGen g => (CShort, CShort) -> g -> [CShort] # randoms :: RandomGen g => g -> [CShort] #
Random CSigAtomic # |
Instance details Defined in System.Random Methods randomR :: RandomGen g => (CSigAtomic, CSigAtomic) -> g -> (CSigAtomic, g) # random :: RandomGen g => g -> (CSigAtomic, g) # randomRs :: RandomGen g => (CSigAtomic, CSigAtomic) -> g -> [CSigAtomic] # randoms :: RandomGen g => g -> [CSigAtomic] #
Random CSize # |
Instance details Defined in System.Random Methods randomR :: RandomGen g => (CSize, CSize) -> g -> (CSize, g) # random :: RandomGen g => g -> (CSize, g) # randomRs :: RandomGen g => (CSize, CSize) -> g -> [CSize] # randoms :: RandomGen g => g -> [CSize] #
Random CUChar # |
Instance details Defined in System.Random Methods randomR :: RandomGen g => (CUChar, CUChar) -> g -> (CUChar, g) # random :: RandomGen g => g -> (CUChar, g) # randomRs :: RandomGen g => (CUChar, CUChar) -> g -> [CUChar] # randoms :: RandomGen g => g -> [CUChar] #
Random CUInt # |
Instance details Defined in System.Random Methods randomR :: RandomGen g => (CUInt, CUInt) -> g -> (CUInt, g) # random :: RandomGen g => g -> (CUInt, g) # randomRs :: RandomGen g => (CUInt, CUInt) -> g -> [CUInt] # randoms :: RandomGen g => g -> [CUInt] #
Random CUIntMax # |
Instance details Defined in System.Random Methods randomR :: RandomGen g => (CUIntMax, CUIntMax) -> g -> (CUIntMax, g) # random :: RandomGen g => g -> (CUIntMax, g) # randomRs :: RandomGen g => (CUIntMax, CUIntMax) -> g -> [CUIntMax] # randoms :: RandomGen g => g -> [CUIntMax] #
Random CUIntPtr # |
Instance details Defined in System.Random Methods randomR :: RandomGen g => (CUIntPtr, CUIntPtr) -> g -> (CUIntPtr, g) # random :: RandomGen g => g -> (CUIntPtr, g) # randomRs :: RandomGen g => (CUIntPtr, CUIntPtr) -> g -> [CUIntPtr] # randoms :: RandomGen g => g -> [CUIntPtr] #
Random CULLong # |
Instance details Defined in System.Random Methods randomR :: RandomGen g => (CULLong, CULLong) -> g -> (CULLong, g) # random :: RandomGen g => g -> (CULLong, g) # randomRs :: RandomGen g => (CULLong, CULLong) -> g -> [CULLong] # randoms :: RandomGen g => g -> [CULLong] #
Random CULong # |
Instance details Defined in System.Random Methods randomR :: RandomGen g => (CULong, CULong) -> g -> (CULong, g) # random :: RandomGen g => g -> (CULong, g) # randomRs :: RandomGen g => (CULong, CULong) -> g -> [CULong] # randoms :: RandomGen g => g -> [CULong] #
Random CUShort # |
Instance details Defined in System.Random Methods randomR :: RandomGen g => (CUShort, CUShort) -> g -> (CUShort, g) # random :: RandomGen g => g -> (CUShort, g) # randomRs :: RandomGen g => (CUShort, CUShort) -> g -> [CUShort] # randoms :: RandomGen g => g -> [CUShort] #
Random CWchar # |
Instance details Defined in System.Random Methods randomR :: RandomGen g => (CWchar, CWchar) -> g -> (CWchar, g) # random :: RandomGen g => g -> (CWchar, g) # randomRs :: RandomGen g => (CWchar, CWchar) -> g -> [CWchar] # randoms :: RandomGen g => g -> [CWchar] #
Random Int16 # |
Instance details Defined in System.Random Methods randomR :: RandomGen g => (Int16, Int16) -> g -> (Int16, g) # random :: RandomGen g => g -> (Int16, g) # randomRs :: RandomGen g => (Int16, Int16) -> g -> [Int16] # randoms :: RandomGen g => g -> [Int16] #
Random Int32 # |
Instance details Defined in System.Random Methods randomR :: RandomGen g => (Int32, Int32) -> g -> (Int32, g) # random :: RandomGen g => g -> (Int32, g) # randomRs :: RandomGen g => (Int32, Int32) -> g -> [Int32] # randoms :: RandomGen g => g -> [Int32] #
Random Int64 # |
Instance details Defined in System.Random Methods randomR :: RandomGen g => (Int64, Int64) -> g -> (Int64, g) # random :: RandomGen g => g -> (Int64, g) # randomRs :: RandomGen g => (Int64, Int64) -> g -> [Int64] # randoms :: RandomGen g => g -> [Int64] #
Random Int8 # |
Instance details Defined in System.Random Methods randomR :: RandomGen g => (Int8, Int8) -> g -> (Int8, g) # random :: RandomGen g => g -> (Int8, g) # randomRs :: RandomGen g => (Int8, Int8) -> g -> [Int8] # randoms :: RandomGen g => g -> [Int8] #
Random Word16 # |
Instance details Defined in System.Random Methods randomR :: RandomGen g => (Word16, Word16) -> g -> (Word16, g) # random :: RandomGen g => g -> (Word16, g) # randomRs :: RandomGen g => (Word16, Word16) -> g -> [Word16] # randoms :: RandomGen g => g -> [Word16] #
Random Word32 # |
Instance details Defined in System.Random Methods randomR :: RandomGen g => (Word32, Word32) -> g -> (Word32, g) # random :: RandomGen g => g -> (Word32, g) # randomRs :: RandomGen g => (Word32, Word32) -> g -> [Word32] # randoms :: RandomGen g => g -> [Word32] #
Random Word64 # |
Instance details Defined in System.Random Methods randomR :: RandomGen g => (Word64, Word64) -> g -> (Word64, g) # random :: RandomGen g => g -> (Word64, g) # randomRs :: RandomGen g => (Word64, Word64) -> g -> [Word64] # randoms :: RandomGen g => g -> [Word64] #
Random Word8 # |
Instance details Defined in System.Random Methods randomR :: RandomGen g => (Word8, Word8) -> g -> (Word8, g) # random :: RandomGen g => g -> (Word8, g) # randomRs :: RandomGen g => (Word8, Word8) -> g -> [Word8] # randoms :: RandomGen g => g -> [Word8] #
Random Integer # | Note - `random` generates values in the `Int` range
Instance details Defined in System.Random Methods randomR :: RandomGen g => (Integer, Integer) -> g -> (Integer, g) # random :: RandomGen g => g -> (Integer, g) # randomRs :: RandomGen g => (Integer, Integer) -> g -> [Integer] # randoms :: RandomGen g => g -> [Integer] #
Random Bool # |
Instance details Defined in System.Random Methods randomR :: RandomGen g => (Bool, Bool) -> g -> (Bool, g) # random :: RandomGen g => g -> (Bool, g) # randomRs :: RandomGen g => (Bool, Bool) -> g -> [Bool] # randoms :: RandomGen g => g -> [Bool] #
Random Char # |
Instance details Defined in System.Random Methods randomR :: RandomGen g => (Char, Char) -> g -> (Char, g) # random :: RandomGen g => g -> (Char, g) # randomRs :: RandomGen g => (Char, Char) -> g -> [Char] # randoms :: RandomGen g => g -> [Char] #
Random Double # | Note - `random` produces values in the closed range `[0,1]`.
Instance details Defined in System.Random Methods randomR :: RandomGen g => (Double, Double) -> g -> (Double, g) # random :: RandomGen g => g -> (Double, g) # randomRs :: RandomGen g => (Double, Double) -> g -> [Double] # randoms :: RandomGen g => g -> [Double] #
Random Float # | Note - `random` produces values in the closed range `[0,1]`.
Instance details Defined in System.Random Methods randomR :: RandomGen g => (Float, Float) -> g -> (Float, g) # random :: RandomGen g => g -> (Float, g) # randomRs :: RandomGen g => (Float, Float) -> g -> [Float] # randoms :: RandomGen g => g -> [Float] #
Random Int # |
Instance details Defined in System.Random Methods randomR :: RandomGen g => (Int, Int) -> g -> (Int, g) # random :: RandomGen g => g -> (Int, g) # randomRs :: RandomGen g => (Int, Int) -> g -> [Int] # randoms :: RandomGen g => g -> [Int] #
Random Word # |
Instance details Defined in System.Random Methods randomR :: RandomGen g => (Word, Word) -> g -> (Word, g) # random :: RandomGen g => g -> (Word, g) # randomRs :: RandomGen g => (Word, Word) -> g -> [Word] # randoms :: RandomGen g => g -> [Word] #
(Random a, Random b) => Random (a, b) # | Note - `randomR` treats `a` and `b` types independently
Instance details Defined in System.Random Methods randomR :: RandomGen g => ((a, b), (a, b)) -> g -> ((a, b), g) # random :: RandomGen g => g -> ((a, b), g) # randomRs :: RandomGen g => ((a, b), (a, b)) -> g -> [(a, b)] # randoms :: RandomGen g => g -> [(a, b)] #
(Random a, Random b, Random c) => Random (a, b, c) # | Note - `randomR` treats `a`, `b` and `c` types independently
Instance details Defined in System.Random Methods randomR :: RandomGen g => ((a, b, c), (a, b, c)) -> g -> ((a, b, c), g) # random :: RandomGen g => g -> ((a, b, c), g) # randomRs :: RandomGen g => ((a, b, c), (a, b, c)) -> g -> [(a, b, c)] # randoms :: RandomGen g => g -> [(a, b, c)] #
(Random a, Random b, Random c, Random d) => Random (a, b, c, d) # | Note - `randomR` treats `a`, `b`, `c` and `d` types independently
Instance details Defined in System.Random Methods randomR :: RandomGen g => ((a, b, c, d), (a, b, c, d)) -> g -> ((a, b, c, d), g) # random :: RandomGen g => g -> ((a, b, c, d), g) # randomRs :: RandomGen g => ((a, b, c, d), (a, b, c, d)) -> g -> [(a, b, c, d)] # randoms :: RandomGen g => g -> [(a, b, c, d)] #
(Random a, Random b, Random c, Random d, Random e) => Random (a, b, c, d, e) # | Note - `randomR` treats `a`, `b`, `c`, `d` and `e` types independently
Instance details Defined in System.Random Methods randomR :: RandomGen g => ((a, b, c, d, e), (a, b, c, d, e)) -> g -> ((a, b, c, d, e), g) # random :: RandomGen g => g -> ((a, b, c, d, e), g) # randomRs :: RandomGen g => ((a, b, c, d, e), (a, b, c, d, e)) -> g -> [(a, b, c, d, e)] # randoms :: RandomGen g => g -> [(a, b, c, d, e)] #
(Random a, Random b, Random c, Random d, Random e, Random f) => Random (a, b, c, d, e, f) # | Note - `randomR` treats `a`, `b`, `c`, `d`, `e` and `f` types independently
Instance details Defined in System.Random Methods randomR :: RandomGen g => ((a, b, c, d, e, f), (a, b, c, d, e, f)) -> g -> ((a, b, c, d, e, f), g) # random :: RandomGen g => g -> ((a, b, c, d, e, f), g) # randomRs :: RandomGen g => ((a, b, c, d, e, f), (a, b, c, d, e, f)) -> g -> [(a, b, c, d, e, f)] # randoms :: RandomGen g => g -> [(a, b, c, d, e, f)] #
(Random a, Random b, Random c, Random d, Random e, Random f, Random g) => Random (a, b, c, d, e, f, g) # | Note - `randomR` treats `a`, `b`, `c`, `d`, `e`, `f` and `g` types independently
Instance details Defined in System.Random Methods randomR :: RandomGen g0 => ((a, b, c, d, e, f, g), (a, b, c, d, e, f, g)) -> g0 -> ((a, b, c, d, e, f, g), g0) # random :: RandomGen g0 => g0 -> ((a, b, c, d, e, f, g), g0) # randomRs :: RandomGen g0 => ((a, b, c, d, e, f, g), (a, b, c, d, e, f, g)) -> g0 -> [(a, b, c, d, e, f, g)] # randoms :: RandomGen g0 => g0 -> [(a, b, c, d, e, f, g)] #

class Uniform a #

The class of types for which a uniformly distributed value can be drawn from all possible values of the type.

Since: 1.2.0

#### Instances

Instances details

Uniform CBool # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CBool #
Uniform CChar # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CChar #
Uniform CInt # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CInt #
Uniform CIntMax # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CIntMax #
Uniform CIntPtr # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CIntPtr #
Uniform CLLong # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CLLong #
Uniform CLong # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CLong #
Uniform CPtrdiff # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CPtrdiff #
Uniform CSChar # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CSChar #
Uniform CShort # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CShort #
Uniform CSigAtomic # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CSigAtomic #
Uniform CSize # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CSize #
Uniform CUChar # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CUChar #
Uniform CUInt # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CUInt #
Uniform CUIntMax # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CUIntMax #
Uniform CUIntPtr # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CUIntPtr #
Uniform CULLong # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CULLong #
Uniform CULong # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CULong #
Uniform CUShort # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CUShort #
Uniform CWchar # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CWchar #
Uniform Int16 # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m Int16 #
Uniform Int32 # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m Int32 #
Uniform Int64 # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m Int64 #
Uniform Int8 # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m Int8 #
Uniform Word16 # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m Word16 #
Uniform Word32 # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m Word32 #
Uniform Word64 # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m Word64 #
Uniform Word8 # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m Word8 #
Uniform () # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m () #
Uniform Bool # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m Bool #
Uniform Char # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m Char #
Uniform Int # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m Int #
Uniform Word # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m Word #
SeedGen g => Uniform (Seed g) # |
Instance details Defined in System.Random.Seed Methods uniformM :: StatefulGen g0 m => g0 -> m (Seed g) #
(Finite a, Uniform a) => Uniform (Maybe a) # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m (Maybe a) #
(Finite a, Uniform a, Finite b, Uniform b) => Uniform (Either a b) # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m (Either a b) #
(Uniform a, Uniform b) => Uniform (a, b) # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m (a, b) #
(Uniform a, Uniform b, Uniform c) => Uniform (a, b, c) # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m (a, b, c) #
(Uniform a, Uniform b, Uniform c, Uniform d) => Uniform (a, b, c, d) # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m (a, b, c, d) #
(Uniform a, Uniform b, Uniform c, Uniform d, Uniform e) => Uniform (a, b, c, d, e) # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m (a, b, c, d, e) #
(Uniform a, Uniform b, Uniform c, Uniform d, Uniform e, Uniform f) => Uniform (a, b, c, d, e, f) # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m (a, b, c, d, e, f) #
(Uniform a, Uniform b, Uniform c, Uniform d, Uniform e, Uniform f, Uniform g) => Uniform (a, b, c, d, e, f, g) # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g0 m => g0 -> m (a, b, c, d, e, f, g) #

class UniformRange a #

The class of types for which a uniformly distributed value can be drawn from a range.

Since: 1.2.0

#### Instances

Instances details

UniformRange CBool # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CBool, CBool) -> g -> m CBool # isInRange :: (CBool, CBool) -> CBool -> Bool #
UniformRange CChar # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CChar, CChar) -> g -> m CChar # isInRange :: (CChar, CChar) -> CChar -> Bool #
UniformRange CDouble # | See Floating point number caveats.
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CDouble, CDouble) -> g -> m CDouble # isInRange :: (CDouble, CDouble) -> CDouble -> Bool #
UniformRange CFloat # | See Floating point number caveats.
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CFloat, CFloat) -> g -> m CFloat # isInRange :: (CFloat, CFloat) -> CFloat -> Bool #
UniformRange CInt # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CInt, CInt) -> g -> m CInt # isInRange :: (CInt, CInt) -> CInt -> Bool #
UniformRange CIntMax # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CIntMax, CIntMax) -> g -> m CIntMax # isInRange :: (CIntMax, CIntMax) -> CIntMax -> Bool #
UniformRange CIntPtr # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CIntPtr, CIntPtr) -> g -> m CIntPtr # isInRange :: (CIntPtr, CIntPtr) -> CIntPtr -> Bool #
UniformRange CLLong # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CLLong, CLLong) -> g -> m CLLong # isInRange :: (CLLong, CLLong) -> CLLong -> Bool #
UniformRange CLong # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CLong, CLong) -> g -> m CLong # isInRange :: (CLong, CLong) -> CLong -> Bool #
UniformRange CPtrdiff # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CPtrdiff, CPtrdiff) -> g -> m CPtrdiff # isInRange :: (CPtrdiff, CPtrdiff) -> CPtrdiff -> Bool #
UniformRange CSChar # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CSChar, CSChar) -> g -> m CSChar # isInRange :: (CSChar, CSChar) -> CSChar -> Bool #
UniformRange CShort # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CShort, CShort) -> g -> m CShort # isInRange :: (CShort, CShort) -> CShort -> Bool #
UniformRange CSigAtomic # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CSigAtomic, CSigAtomic) -> g -> m CSigAtomic # isInRange :: (CSigAtomic, CSigAtomic) -> CSigAtomic -> Bool #
UniformRange CSize # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CSize, CSize) -> g -> m CSize # isInRange :: (CSize, CSize) -> CSize -> Bool #
UniformRange CUChar # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CUChar, CUChar) -> g -> m CUChar # isInRange :: (CUChar, CUChar) -> CUChar -> Bool #
UniformRange CUInt # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CUInt, CUInt) -> g -> m CUInt # isInRange :: (CUInt, CUInt) -> CUInt -> Bool #
UniformRange CUIntMax # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CUIntMax, CUIntMax) -> g -> m CUIntMax # isInRange :: (CUIntMax, CUIntMax) -> CUIntMax -> Bool #
UniformRange CUIntPtr # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CUIntPtr, CUIntPtr) -> g -> m CUIntPtr # isInRange :: (CUIntPtr, CUIntPtr) -> CUIntPtr -> Bool #
UniformRange CULLong # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CULLong, CULLong) -> g -> m CULLong # isInRange :: (CULLong, CULLong) -> CULLong -> Bool #
UniformRange CULong # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CULong, CULong) -> g -> m CULong # isInRange :: (CULong, CULong) -> CULong -> Bool #
UniformRange CUShort # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CUShort, CUShort) -> g -> m CUShort # isInRange :: (CUShort, CUShort) -> CUShort -> Bool #
UniformRange CWchar # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CWchar, CWchar) -> g -> m CWchar # isInRange :: (CWchar, CWchar) -> CWchar -> Bool #
UniformRange Int16 # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Int16, Int16) -> g -> m Int16 # isInRange :: (Int16, Int16) -> Int16 -> Bool #
UniformRange Int32 # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Int32, Int32) -> g -> m Int32 # isInRange :: (Int32, Int32) -> Int32 -> Bool #
UniformRange Int64 # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Int64, Int64) -> g -> m Int64 # isInRange :: (Int64, Int64) -> Int64 -> Bool #
UniformRange Int8 # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Int8, Int8) -> g -> m Int8 # isInRange :: (Int8, Int8) -> Int8 -> Bool #
UniformRange Word16 # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Word16, Word16) -> g -> m Word16 # isInRange :: (Word16, Word16) -> Word16 -> Bool #
UniformRange Word32 # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Word32, Word32) -> g -> m Word32 # isInRange :: (Word32, Word32) -> Word32 -> Bool #
UniformRange Word64 # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Word64, Word64) -> g -> m Word64 # isInRange :: (Word64, Word64) -> Word64 -> Bool #
UniformRange Word8 # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Word8, Word8) -> g -> m Word8 # isInRange :: (Word8, Word8) -> Word8 -> Bool #
UniformRange Integer # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Integer, Integer) -> g -> m Integer # isInRange :: (Integer, Integer) -> Integer -> Bool #
UniformRange Natural # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Natural, Natural) -> g -> m Natural # isInRange :: (Natural, Natural) -> Natural -> Bool #
UniformRange () # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => ((), ()) -> g -> m () # isInRange :: ((), ()) -> () -> Bool #
UniformRange Bool # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Bool, Bool) -> g -> m Bool # isInRange :: (Bool, Bool) -> Bool -> Bool #
UniformRange Char # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Char, Char) -> g -> m Char # isInRange :: (Char, Char) -> Char -> Bool #
UniformRange Double # | See Floating point number caveats.
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Double, Double) -> g -> m Double # isInRange :: (Double, Double) -> Double -> Bool #
UniformRange Float # | See Floating point number caveats.
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Float, Float) -> g -> m Float # isInRange :: (Float, Float) -> Float -> Bool #
UniformRange Int # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Int, Int) -> g -> m Int # isInRange :: (Int, Int) -> Int -> Bool #
UniformRange Word # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Word, Word) -> g -> m Word # isInRange :: (Word, Word) -> Word -> Bool #
(UniformRange a, UniformRange b) => UniformRange (a, b) # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => ((a, b), (a, b)) -> g -> m (a, b) # isInRange :: ((a, b), (a, b)) -> (a, b) -> Bool #
(UniformRange a, UniformRange b, UniformRange c) => UniformRange (a, b, c) # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => ((a, b, c), (a, b, c)) -> g -> m (a, b, c) # isInRange :: ((a, b, c), (a, b, c)) -> (a, b, c) -> Bool #
(UniformRange a, UniformRange b, UniformRange c, UniformRange d) => UniformRange (a, b, c, d) # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => ((a, b, c, d), (a, b, c, d)) -> g -> m (a, b, c, d) # isInRange :: ((a, b, c, d), (a, b, c, d)) -> (a, b, c, d) -> Bool #
(UniformRange a, UniformRange b, UniformRange c, UniformRange d, UniformRange e) => UniformRange (a, b, c, d, e) # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => ((a, b, c, d, e), (a, b, c, d, e)) -> g -> m (a, b, c, d, e) # isInRange :: ((a, b, c, d, e), (a, b, c, d, e)) -> (a, b, c, d, e) -> Bool #
(UniformRange a, UniformRange b, UniformRange c, UniformRange d, UniformRange e, UniformRange f) => UniformRange (a, b, c, d, e, f) # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => ((a, b, c, d, e, f), (a, b, c, d, e, f)) -> g -> m (a, b, c, d, e, f) # isInRange :: ((a, b, c, d, e, f), (a, b, c, d, e, f)) -> (a, b, c, d, e, f) -> Bool #
(UniformRange a, UniformRange b, UniformRange c, UniformRange d, UniformRange e, UniformRange f, UniformRange g) => UniformRange (a, b, c, d, e, f, g) # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g0 m => ((a, b, c, d, e, f, g), (a, b, c, d, e, f, g)) -> g0 -> m (a, b, c, d, e, f, g) # isInRange :: ((a, b, c, d, e, f, g), (a, b, c, d, e, f, g)) -> (a, b, c, d, e, f, g) -> Bool #

class Finite a #

A type class for data with a finite number of inhabitants. This type class is used in the default implementation of `Uniform`.

Users are not supposed to write instances of `Finite` manually. There is a default implementation in terms of `Generic` instead.

    >>> :seti -XDeriveGeneric -XDeriveAnyClass
    >>> import GHC.Generics (Generic)
    >>> data MyBool = MyTrue | MyFalse deriving (Generic, Finite)
    >>> data Action = Code MyBool | Eat (Maybe Bool) | Sleep deriving (Generic, Finite)

#### Instances

Instances details

Finite Void # |
Instance details Defined in System.Random.GFinite Methods cardinality :: Proxy# Void -> Cardinality toFinite :: Integer -> Void fromFinite :: Void -> Integer
Finite Int16 # |
Instance details Defined in System.Random.GFinite Methods cardinality :: Proxy# Int16 -> Cardinality toFinite :: Integer -> Int16 fromFinite :: Int16 -> Integer
Finite Int32 # |
Instance details Defined in System.Random.GFinite Methods cardinality :: Proxy# Int32 -> Cardinality toFinite :: Integer -> Int32 fromFinite :: Int32 -> Integer
Finite Int64 # |
Instance details Defined in System.Random.GFinite Methods cardinality :: Proxy# Int64 -> Cardinality toFinite :: Integer -> Int64 fromFinite :: Int64 -> Integer
Finite Int8 # |
Instance details Defined in System.Random.GFinite Methods cardinality :: Proxy# Int8 -> Cardinality toFinite :: Integer -> Int8 fromFinite :: Int8 -> Integer
Finite Word16 # |
Instance details Defined in System.Random.GFinite Methods cardinality :: Proxy# Word16 -> Cardinality toFinite :: Integer -> Word16 fromFinite :: Word16 -> Integer
Finite Word32 # |
Instance details Defined in System.Random.GFinite Methods cardinality :: Proxy# Word32 -> Cardinality toFinite :: Integer -> Word32 fromFinite :: Word32 -> Integer
Finite Word64 # |
Instance details Defined in System.Random.GFinite Methods cardinality :: Proxy# Word64 -> Cardinality toFinite :: Integer -> Word64 fromFinite :: Word64 -> Integer
Finite Word8 # |
Instance details Defined in System.Random.GFinite Methods cardinality :: Proxy# Word8 -> Cardinality toFinite :: Integer -> Word8 fromFinite :: Word8 -> Integer
Finite Ordering # |
Instance details Defined in System.Random.GFinite Methods cardinality :: Proxy# Ordering -> Cardinality toFinite :: Integer -> Ordering fromFinite :: Ordering -> Integer
Finite () # |
Instance details Defined in System.Random.GFinite Methods cardinality :: Proxy# () -> Cardinality toFinite :: Integer -> () fromFinite :: () -> Integer
Finite Bool # |
Instance details Defined in System.Random.GFinite Methods cardinality :: Proxy# Bool -> Cardinality toFinite :: Integer -> Bool fromFinite :: Bool -> Integer
Finite Char # |
Instance details Defined in System.Random.GFinite Methods cardinality :: Proxy# Char -> Cardinality toFinite :: Integer -> Char fromFinite :: Char -> Integer
Finite Int # |
Instance details Defined in System.Random.GFinite Methods cardinality :: Proxy# Int -> Cardinality toFinite :: Integer -> Int fromFinite :: Int -> Integer
Finite Word # |
Instance details Defined in System.Random.GFinite Methods cardinality :: Proxy# Word -> Cardinality toFinite :: Integer -> Word fromFinite :: Word -> Integer
Finite a => Finite (Maybe a) # |
Instance details Defined in System.Random.GFinite Methods cardinality :: Proxy# (Maybe a) -> Cardinality toFinite :: Integer -> Maybe a fromFinite :: Maybe a -> Integer
(Finite a, Finite b) => Finite (Either a b) # |
Instance details Defined in System.Random.GFinite Methods cardinality :: Proxy# (Either a b) -> Cardinality toFinite :: Integer -> Either a b fromFinite :: Either a b -> Integer
(Finite a, Finite b) => Finite (a, b) # |
Instance details Defined in System.Random.GFinite Methods cardinality :: Proxy# (a, b) -> Cardinality toFinite :: Integer -> (a, b) fromFinite :: (a, b) -> Integer
(Finite a, Finite b, Finite c) => Finite (a, b, c) # |
Instance details Defined in System.Random.GFinite Methods cardinality :: Proxy# (a, b, c) -> Cardinality toFinite :: Integer -> (a, b, c) fromFinite :: (a, b, c) -> Integer
(Finite a, Finite b, Finite c, Finite d) => Finite (a, b, c, d) # |
Instance details Defined in System.Random.GFinite Methods cardinality :: Proxy# (a, b, c, d) -> Cardinality toFinite :: Integer -> (a, b, c, d) fromFinite :: (a, b, c, d) -> Integer
(Finite a, Finite b, Finite c, Finite d, Finite e) => Finite (a, b, c, d, e) # |
Instance details Defined in System.Random.GFinite Methods cardinality :: Proxy# (a, b, c, d, e) -> Cardinality toFinite :: Integer -> (a, b, c, d, e) fromFinite :: (a, b, c, d, e) -> Integer
(Finite a, Finite b, Finite c, Finite d, Finite e, Finite f) => Finite (a, b, c, d, e, f) # |
Instance details Defined in System.Random.GFinite Methods cardinality :: Proxy# (a, b, c, d, e, f) -> Cardinality toFinite :: Integer -> (a, b, c, d, e, f) fromFinite :: (a, b, c, d, e, f) -> Integer
(Finite a, Finite b, Finite c, Finite d, Finite e, Finite f, Finite g) => Finite (a, b, c, d, e, f, g) # |
Instance details Defined in System.Random.GFinite Methods cardinality :: Proxy# (a, b, c, d, e, f, g) -> Cardinality toFinite :: Integer -> (a, b, c, d, e, f, g) fromFinite :: (a, b, c, d, e, f, g) -> Integer

data Seed g #

This is a binary form of pseudo-random number generator's state. It is designed to be safe and easy to use for input/output operations like restoring from file, transmitting over the network, etc.

Constructor is not exported, becasue it is important for implementation to enforce the invariant of the underlying byte array being of the exact same length as the generator has specified in `SeedSize`. Use `mkSize` and `unSize` to get access to the raw bytes in a safe manner.

Since: 1.3.0

#### Instances

Instances details

Show (Seed g) # |
Instance details Defined in System.Random.Internal Methods showsPrec :: Int -> Seed g -> ShowS # show :: Seed g -> String # showList :: [Seed g] -> ShowS #
Eq (Seed g) # |
Instance details Defined in System.Random.Internal Methods (==) :: Seed g -> Seed g -> Bool # (/=) :: Seed g -> Seed g -> Bool #
Ord (Seed g) # |
Instance details Defined in System.Random.Internal Methods compare :: Seed g -> Seed g -> Ordering # (<) :: Seed g -> Seed g -> Bool # (<=) :: Seed g -> Seed g -> Bool # (>) :: Seed g -> Seed g -> Bool # (>=) :: Seed g -> Seed g -> Bool # max :: Seed g -> Seed g -> Seed g # min :: Seed g -> Seed g -> Seed g #
SeedGen g => Uniform (Seed g) # |
Instance details Defined in System.Random.Seed Methods uniformM :: StatefulGen g0 m => g0 -> m (Seed g) #

uniforms :: (Uniform a, RandomGen g) => g -> [a] #

Produce an infinite list of pseudo-random values. Integrates nicely with list fusion. Naturally, there is no way to recover the final generator, therefore either use `split` before calling `uniforms` or use `uniformList` instead.

Similar to `randoms`, except it relies on `Uniform` type class instead of `Random`

#### Examples

Expand

    >>> let gen = mkStdGen 2023
    >>> import Data.Word (Word16)
    >>> take 5 $ uniforms gen :: [Word16]
    [56342,15850,25292,14347,13919]

Since: 1.3.0

uniformRs :: (UniformRange a, RandomGen g) => (a, a) -> g -> [a] #

Produce an infinite list of pseudo-random values in a specified range. Same as `uniforms`, integrates nicely with list fusion. There is no way to recover the final generator, therefore either use `split` before calling `uniformRs` or use `uniformListR` instead.

Similar to `randomRs`, except it relies on `UniformRange` type class instead of `Random`.

#### Examples

Expand

    >>> let gen = mkStdGen 2023
    >>> take 5 $ uniformRs (10, 100) gen :: [Int]
    [32,86,21,57,39]

Since: 1.3.0

uniformList :: (Uniform a, RandomGen g) => Int -> g -> ([a], g) #

Produce a list of the supplied length with elements generated uniformly.

See `uniformListM` for a stateful counterpart.

#### Examples

Expand

    >>> let gen = mkStdGen 2023
    >>> import Data.Word (Word16)
    >>> uniformList 5 gen :: ([Word16], StdGen)
    ([56342,15850,25292,14347,13919],StdGen {unStdGen = SMGen 6446154349414395371 1920468677557965761})

Since: 1.3.0

uniformListR :: (UniformRange a, RandomGen g) => Int -> (a, a) -> g -> ([a], g) #

Produce a list of the supplied length with elements generated uniformly.

See `uniformListM` for a stateful counterpart.

#### Examples

Expand

    >>> let gen = mkStdGen 2023
    >>> uniformListR 10 (20, 30) gen :: ([Int], StdGen)
    ([26,30,27,24,30,25,27,21,27,27],StdGen {unStdGen = SMGen 12965503083958398648 1920468677557965761})

Since: 1.3.0

uniformShuffleList :: RandomGen g => [a] -> g -> ([a], g) #

Shuffle elements of a list in a uniformly random order.

#### Examples

Expand

    >>> uniformShuffleList "ELVIS" $ mkStdGen 252
    ("LIVES",StdGen {unStdGen = SMGen 17676540583805057877 5302934877338729551})

Since: 1.3.0

uniformByteArray #

Arguments

:: RandomGen g |
=> Bool | Should byte array be allocted in pinned or unpinned memory.
-> Int | Number of bytes to generate
-> g | Pure pseudo-random numer generator
-> (ByteArray, g) |

Efficiently generates a sequence of pseudo-random bytes in a platform independent manner.

Since: 1.3.0

uniformByteString :: RandomGen g => Int -> g -> (ByteString, g) #

Generates a `ByteString` of the specified size using a pure pseudo-random number generator. See `uniformByteStringM` for the monadic version.

#### Examples

Expand

    >>> import System.Random
    >>> import Data.ByteString (unpack)
    >>> let pureGen = mkStdGen 137
    >>> unpack . fst $ uniformByteString 10 pureGen
    [51,123,251,37,49,167,90,109,1,4]

Since: 1.3.0

uniformFillMutableByteArray #

Arguments

:: RandomGen g |
=> MutableByteArray s | Mutable array to fill with random bytes
-> Int | Offset into a mutable array from the beginning in number of bytes. Offset will be clamped into the range between 0 and the total size of the mutable array
-> Int | Number of randomly generated bytes to write into the array. This number will be clamped between 0 and the total size of the array without the offset.
-> g |
-> ST s g |

Fill in a slice of a mutable byte array with randomly generated bytes. This function does not fail, instead it clamps the offset and number of bytes to generate into a valid range.

Since: 1.3.0

genByteString :: RandomGen g => Int -> g -> (ByteString, g) #

Deprecated: In favor of `uniformByteString`

Generates a `ByteString` of the specified size using a pure pseudo-random number generator. See `uniformByteStringM` for the monadic version.

#### Examples

Expand

    >>> import System.Random
    >>> import Data.ByteString
    >>> let pureGen = mkStdGen 137
    >>> :seti -Wno-deprecations
    >>> unpack . fst . genByteString 10 $ pureGen
    [51,123,251,37,49,167,90,109,1,4]

Since: 1.2.0

data StdGen #

The standard pseudo-random number generator.

#### Instances

Instances details

NFData StdGen # |
Instance details Defined in System.Random.Internal Methods rnf :: StdGen -> () #
Show StdGen # |
Instance details Defined in System.Random.Internal Methods showsPrec :: Int -> StdGen -> ShowS # show :: StdGen -> String # showList :: [StdGen] -> ShowS #
Eq StdGen # |
Instance details Defined in System.Random.Internal Methods (==) :: StdGen -> StdGen -> Bool # (/=) :: StdGen -> StdGen -> Bool #
RandomGen StdGen # |
Instance details Defined in System.Random.Internal Methods next :: StdGen -> (Int, StdGen) # genWord8 :: StdGen -> (Word8, StdGen) # genWord16 :: StdGen -> (Word16, StdGen) # genWord32 :: StdGen -> (Word32, StdGen) # genWord64 :: StdGen -> (Word64, StdGen) # genWord32R :: Word32 -> StdGen -> (Word32, StdGen) # genWord64R :: Word64 -> StdGen -> (Word64, StdGen) # genShortByteString :: Int -> StdGen -> (ShortByteString, StdGen) # unsafeUniformFillMutableByteArray :: MutableByteArray s -> Int -> Int -> StdGen -> ST s StdGen # genRange :: StdGen -> (Int, Int) # split :: StdGen -> (StdGen, StdGen) #
SplitGen StdGen # |
Instance details Defined in System.Random.Internal Methods splitGen :: StdGen -> (StdGen, StdGen) #
SeedGen StdGen # |
Instance details Defined in System.Random.Seed Associated Types
type SeedSize StdGen |
Instance details Defined in System.Random.Seed type SeedSize StdGen = SeedSize SMGen
Methods fromSeed :: Seed StdGen -> StdGen # toSeed :: StdGen -> Seed StdGen # fromSeed64 :: NonEmpty Word64 -> StdGen # toSeed64 :: StdGen -> NonEmpty Word64 #
type SeedSize StdGen # |
Instance details Defined in System.Random.Seed type SeedSize StdGen = SeedSize SMGen

mkStdGen :: Int -> StdGen #

Constructs a `StdGen` deterministically from an `Int` seed. See `mkStdGen64` for a `Word64` variant that is architecture agnostic.

mkStdGen64 :: Word64 -> StdGen #

Constructs a `StdGen` deterministically from a `Word64` seed.

The difference between `mkStdGen` is that `mkStdGen64` will work the same on 64-bit and 32-bit architectures, while the former can only use 32-bit of information for initializing the psuedo-random number generator on 32-bit operating systems

Since: 1.3.0

initStdGen :: MonadIO m => m StdGen #

Initialize `StdGen` using system entropy (i.e. `/dev/urandom`) when it is available, while falling back on using system time as the seed.

Since: 1.2.1

getStdRandom :: MonadIO m => (StdGen -> (a, StdGen)) -> m a #

Uses the supplied function to get a value from the current global random generator, and updates the global generator with the new generator returned by the function. For example, `rollDice` produces a pseudo-random integer between 1 and 6:

    >>> rollDice = getStdRandom (randomR (1, 6))
    >>> replicateM 10 (rollDice :: IO Int)
    [1,1,1,4,5,6,1,2,2,5]

This is an outdated function and it is recommended to switch to its equivalent `applyAtomicGen` instead, possibly with the `globalStdGen` if relying on the global state is acceptable.

    >>> import System.Random.Stateful
    >>> rollDice = applyAtomicGen (uniformR (1, 6)) globalStdGen
    >>> replicateM 10 (rollDice :: IO Int)
    [2,1,1,5,4,3,6,6,3,2]

Since: 1.0.0

getStdGen :: MonadIO m => m StdGen #

Gets the global pseudo-random number generator. Extracts the contents of `globalStdGen`

Since: 1.0.0

setStdGen :: MonadIO m => StdGen -> m () #

Sets the global pseudo-random number generator. Overwrites the contents of `globalStdGen`

Since: 1.0.0

newStdGen :: MonadIO m => m StdGen #

Applies `split` to the current global pseudo-random generator `globalStdGen`, updates it with one of the results, and returns the other.

Since: 1.0.0

randomIO :: (Random a, MonadIO m) => m a #

A variant of `randomM` that uses the global pseudo-random number generator `globalStdGen`.

    >>> import Data.Int
    >>> randomIO :: IO Int32
    114794456

This function is equivalent to ``getStdRandom` `random`` and is included in this interface for historical reasons and backwards compatibility. It is recommended to use `uniformM` instead, possibly with the `globalStdGen` if relying on the global state is acceptable.

    >>> import System.Random.Stateful
    >>> uniformM globalStdGen :: IO Int32
    -1768545016

Since: 1.0.0

randomRIO :: (Random a, MonadIO m) => (a, a) -> m a #

A variant of `randomRM` that uses the global pseudo-random number generator `globalStdGen`

    >>> randomRIO (2020, 2100) :: IO Int
    2028

Similar to `randomIO`, this function is equivalent to ``getStdRandom` `randomR`` and is included in this interface for historical reasons and backwards compatibility. It is recommended to use `uniformRM` instead, possibly with the `globalStdGen` if relying on the global state is acceptable.

    >>> import System.Random.Stateful
    >>> uniformRM (2020, 2100) globalStdGen :: IO Int
    2044

Since: 1.0.0

class (KnownNat (SeedSize g), 1 <= SeedSize g, Typeable g) => SeedGen g where #

Interface for converting a pure pseudo-random number generator to and from non-empty sequence of bytes. Seeds are stored in Little-Endian order regardless of the platform it is being used on, which provides cross-platform compatibility, while providing optimal performance for the most common platform type.

Conversion to and from a `Seed` serves as a building block for implementing serialization for any pure or frozen pseudo-random number generator.

It is not trivial to implement platform independence. For this reason this type class has two alternative ways of creating an instance for this class. The easiest way for constructing a platform indepent seed is by converting the inner state of a generator to and from a list of 64 bit words using `toSeed64` and `fromSeed64` respectively. In that case cross-platform support will be handled automaticaly.

    >>> :set -XDataKinds -XTypeFamilies
    >>> import Data.Word (Word8, Word32)
    >>> import Data.Bits ((.|.), shiftR, shiftL)
    >>> import Data.List.NonEmpty (NonEmpty ((:|)))
    >>> data FiveByteGen = FiveByteGen Word8 Word32 deriving Show
    >>> :{
    instance SeedGen FiveByteGen where
      type SeedSize FiveByteGen = 5
      fromSeed64 (w64 :| _) =
        FiveByteGen (fromIntegral (w64 `shiftR` 32)) (fromIntegral w64)
      toSeed64 (FiveByteGen x1 x4) =
        let w64 = (fromIntegral x1 `shiftL` 32) .|. fromIntegral x4
         in (w64 :| [])
    :}

    >>> FiveByteGen 0x80 0x01020304
    FiveByteGen 128 16909060
    >>> fromSeed (toSeed (FiveByteGen 0x80 0x01020304))
    FiveByteGen 128 16909060
    >>> toSeed (FiveByteGen 0x80 0x01020304)
    Seed [0x04, 0x03, 0x02, 0x01, 0x80]
    >>> toSeed64 (FiveByteGen 0x80 0x01020304)
    549772722948 :| []

However, when performance is of utmost importance or default handling of cross platform independence is not sufficient, then an adventurous developer can try implementing conversion into bytes directly with `toSeed` and `fromSeed`.

Properties that must hold:

    > fromSeed (toSeed gen) == gen

    > fromSeed64 (toSeed64 gen) == gen

Note, that there is no requirement for every `Seed` to roundtrip, eg. this proprty does not even hold for `StdGen`:

    >>> let seed = nonEmptyToSeed (0xab :| [0xff00]) :: Seed StdGen
    >>> seed == toSeed (fromSeed seed)
    False

Since: 1.3.0

Minimal complete definition

fromSeed, toSeed | fromSeed64, toSeed64

Associated Types

type SeedSize g :: Nat #

Number of bytes that is required for storing the full state of a pseudo-random number generator. It should be big enough to satisfy the roundtrip property:

    > fromSeed (toSeed gen) == gen

Methods

fromSeed :: Seed g -> g #

Convert from a binary representation to a pseudo-random number generator

Since: 1.3.0

toSeed :: g -> Seed g #

Convert to a binary representation of a pseudo-random number generator

Since: 1.3.0

fromSeed64 :: NonEmpty Word64 -> g #

Construct pseudo-random number generator from a list of words. Whenever list does not have enough bytes to satisfy the `SeedSize` requirement, it will be padded with zeros. On the other hand when it has more than necessary, extra bytes will be dropped.

For example if `SeedSize` is set to 2, then only the lower 16 bits of the first element in the list will be used.

Since: 1.3.0

toSeed64 :: g -> NonEmpty Word64 #

Convert pseudo-random number generator to a list of words

In case when `SeedSize` is not a multiple of 8, then the upper bits of the last word in the list will be set to zero.

Since: 1.3.0

#### Instances

Instances details

SeedGen StdGen # |
Instance details Defined in System.Random.Seed Associated Types
type SeedSize StdGen |
Instance details Defined in System.Random.Seed type SeedSize StdGen = SeedSize SMGen
Methods fromSeed :: Seed StdGen -> StdGen # toSeed :: StdGen -> Seed StdGen # fromSeed64 :: NonEmpty Word64 -> StdGen # toSeed64 :: StdGen -> NonEmpty Word64 #
SeedGen SMGen # |
Instance details Defined in System.Random.Seed Associated Types
type SeedSize SMGen |
Instance details Defined in System.Random.Seed type SeedSize SMGen = 16
Methods fromSeed :: Seed SMGen -> SMGen # toSeed :: SMGen -> Seed SMGen # fromSeed64 :: NonEmpty Word64 -> SMGen # toSeed64 :: SMGen -> NonEmpty Word64 #
SeedGen SMGen # |
Instance details Defined in System.Random.Seed Associated Types
type SeedSize SMGen |
Instance details Defined in System.Random.Seed type SeedSize SMGen = 8
Methods fromSeed :: Seed SMGen -> SMGen # toSeed :: SMGen -> Seed SMGen # fromSeed64 :: NonEmpty Word64 -> SMGen # toSeed64 :: SMGen -> NonEmpty Word64 #
SeedGen g => SeedGen (StateGen g) # |
Instance details Defined in System.Random.Seed Associated Types
type SeedSize (StateGen g) |
Instance details Defined in System.Random.Seed type SeedSize (StateGen g) = SeedSize g
Methods fromSeed :: Seed (StateGen g) -> StateGen g # toSeed :: StateGen g -> Seed (StateGen g) # fromSeed64 :: NonEmpty Word64 -> StateGen g # toSeed64 :: StateGen g -> NonEmpty Word64 #
SeedGen g => SeedGen (AtomicGen g) # |
Instance details Defined in System.Random.Stateful Associated Types
type SeedSize (AtomicGen g) |
Instance details Defined in System.Random.Stateful type SeedSize (AtomicGen g) = SeedSize g
Methods fromSeed :: Seed (AtomicGen g) -> AtomicGen g # toSeed :: AtomicGen g -> Seed (AtomicGen g) # fromSeed64 :: NonEmpty Word64 -> AtomicGen g # toSeed64 :: AtomicGen g -> NonEmpty Word64 #
SeedGen g => SeedGen (IOGen g) # |
Instance details Defined in System.Random.Stateful Associated Types
type SeedSize (IOGen g) |
Instance details Defined in System.Random.Stateful type SeedSize (IOGen g) = SeedSize g
Methods fromSeed :: Seed (IOGen g) -> IOGen g # toSeed :: IOGen g -> Seed (IOGen g) # fromSeed64 :: NonEmpty Word64 -> IOGen g # toSeed64 :: IOGen g -> NonEmpty Word64 #
SeedGen g => SeedGen (STGen g) # |
Instance details Defined in System.Random.Stateful Associated Types
type SeedSize (STGen g) |
Instance details Defined in System.Random.Stateful type SeedSize (STGen g) = SeedSize g
Methods fromSeed :: Seed (STGen g) -> STGen g # toSeed :: STGen g -> Seed (STGen g) # fromSeed64 :: NonEmpty Word64 -> STGen g # toSeed64 :: STGen g -> NonEmpty Word64 #
SeedGen g => SeedGen (TGen g) # |
Instance details Defined in System.Random.Stateful Associated Types
type SeedSize (TGen g) |
Instance details Defined in System.Random.Stateful type SeedSize (TGen g) = SeedSize g
Methods fromSeed :: Seed (TGen g) -> TGen g # toSeed :: TGen g -> Seed (TGen g) # fromSeed64 :: NonEmpty Word64 -> TGen g # toSeed64 :: TGen g -> NonEmpty Word64 #

seedSize :: SeedGen g => Int #

Get the expected size of the `Seed` in number bytes

Since: 1.3.0

seedSizeProxy :: forall proxy g. SeedGen g => proxy g -> Int #

Just like `seedSize`, except it accepts a proxy as an argument.

Since: 1.3.0

mkSeed :: (SeedGen g, MonadFail m) => ByteArray -> m (Seed g) #

Construct a `Seed` from a `ByteArray` of expected length. Whenever `ByteArray` does not match the `SeedSize` specified by the pseudo-random generator, this function will `fail`.

Since: 1.3.0

unSeed :: Seed g -> ByteArray #

Unwrap the `Seed` and get the underlying `ByteArray`

Since: 1.3.0

mkSeedFromByteString :: (SeedGen g, MonadFail m) => ByteString -> m (Seed g) #

Just like `mkSeed`, but uses `ByteString` as argument. Results in a memcopy of the seed.

Since: 1.3.0

unSeedToByteString :: Seed g -> ByteString #

Just like `unSeed`, but produced a `ByteString`. Results in a memcopy of the seed.

Since: 1.3.0

withSeed :: SeedGen g => Seed g -> (g -> (a, g)) -> (a, Seed g) #

Helper function that allows for operating directly on the `Seed`, while supplying a function that uses the pseudo-random number generator that is constructed from that `Seed`.

#### Example

Expand

    >>> :set -XTypeApplications
    >>> import System.Random
    >>> withSeed (nonEmptyToSeed (pure 2024) :: Seed StdGen) (uniform @Int)
    (1039666877624726199,Seed [0xe9, 0x07, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00])

Since: 1.3.0

withSeedM :: (SeedGen g, Functor f) => Seed g -> (g -> f (a, g)) -> f (a, Seed g) #

Same as `withSeed`, except it is useful with monadic computation and frozen generators.

See `withSeedMutableGen` for a helper that also handles seeds for mutable pseduo-random number generators.

Since: 1.3.0

withSeedFile :: (SeedGen g, MonadIO m) => FilePath -> (Seed g -> m (a, Seed g)) -> m a #

Read the seed from a file and use it for constructing a pseudo-random number generator. After supplied action has been applied to the constructed generator, the resulting generator will be converted back to a seed and written to the same file.

Since: 1.3.0

seedGenTypeName :: SeedGen g => String #

This is a function that shows the name of the generator type, which is useful for error reporting.

Since: 1.3.0

nonEmptyToSeed :: SeedGen g => NonEmpty Word64 -> Seed g #

Construct a seed from a list of 64-bit words. At most `SeedSize` many bytes will be used.

Since: 1.3.0

nonEmptyFromSeed :: SeedGen g => Seed g -> NonEmpty Word64 #

Convert a `Seed` to a list of 64bit words.

Since: 1.3.0

type family SeedSize g :: Nat #

Number of bytes that is required for storing the full state of a pseudo-random number generator. It should be big enough to satisfy the roundtrip property:

    > fromSeed (toSeed gen) == gen

#### Instances

Instances details

type SeedSize StdGen # |
Instance details Defined in System.Random.Seed type SeedSize StdGen = SeedSize SMGen
type SeedSize SMGen # |
Instance details Defined in System.Random.Seed type SeedSize SMGen = 16
type SeedSize SMGen # |
Instance details Defined in System.Random.Seed type SeedSize SMGen = 8
type SeedSize (StateGen g) # |
Instance details Defined in System.Random.Seed type SeedSize (StateGen g) = SeedSize g
type SeedSize (AtomicGen g) # |
Instance details Defined in System.Random.Stateful type SeedSize (AtomicGen g) = SeedSize g
type SeedSize (IOGen g) # |
Instance details Defined in System.Random.Stateful type SeedSize (IOGen g) = SeedSize g
type SeedSize (STGen g) # |
Instance details Defined in System.Random.Stateful type SeedSize (STGen g) = SeedSize g
type SeedSize (TGen g) # |
Instance details Defined in System.Random.Stateful type SeedSize (TGen g) = SeedSize g

# Monadic Random Generator

This module provides type classes and instances for the following concepts:

Monadic pseudo-random number generators
  `StatefulGen` is an interface to monadic pseudo-random number generators.
Monadic adapters
  `StateGenM`, `AtomicGenM`, `IOGenM`, `STGenM` and `TGenM` turn a `RandomGen` instance into a `StatefulGen` instance.
Drawing from a range
  `UniformRange` is used to generate a value of a type uniformly within a range.

  This library provides instances of `UniformRange` for many common numeric types.

Drawing from the entire domain of a type
  `Uniform` is used to generate a value of a type uniformly over all possible values of that type.

  This library provides instances of `Uniform` for many common bounded numeric types.

# Usage

In monadic code, use the relevant `Uniform` and `UniformRange` instances to generate pseudo-random values via `uniformM` and `uniformRM`, respectively.

As an example, `rollsM` generates `n` pseudo-random values of `Word` in the range `[1, 6]` in a `StatefulGen` context; given a monadic pseudo-random number generator, you can run this probabilistic computation using `mwc-random` as follows:

    >>> import Control.Monad (replicateM)
    >>> :{
    let rollsM :: StatefulGen g m => Int -> g -> m [Word]
        rollsM n = replicateM n . uniformRM (1, 6)
    :}

    import qualified System.Random.MWC as MWC
    >>> monadicGen <- MWC.create
    >>> rollsM 10 monadicGen :: IO [Word]
    [3,4,3,1,4,6,1,6,1,4]

Given a pure pseudo-random number generator, you can run the monadic pseudo-random number computation `rollsM` in `StateT`, `IO`, `ST` or `STM` context by applying a monadic adapter like `StateGenM`, `AtomicGenM`, `IOGenM`, `STGenM` or `TGenM` (see monadic-adapters) to the pure pseudo-random number generator.

    >>> let pureGen = mkStdGen 42
    >>> newIOGenM pureGen >>= rollsM 10 :: IO [Word]
    [1,1,3,2,4,5,3,4,6,2]

# Mutable pseudo-random number generator interfaces

Pseudo-random number generators come in two flavours: pure and monadic.

`RandomGen`: pure pseudo-random number generators
  See System.Random module.
`StatefulGen`: monadic pseudo-random number generators
  These generators mutate their own state as they produce pseudo-random values. They generally live in `StateT`, `ST`, `IO` or `STM` or some other transformer on top of those monads.

class Monad m => StatefulGen g (m :: Type -> Type) where #

`StatefulGen` is an interface to monadic pseudo-random number generators.

Since: 1.2.0

Minimal complete definition

uniformWord32 | uniformWord64

Methods

uniformWord32R :: Word32 -> g -> m Word32 #

`uniformWord32R upperBound g` generates a `Word32` that is uniformly distributed over the range `[0, upperBound]`.

Since: 1.2.0

uniformWord64R :: Word64 -> g -> m Word64 #

`uniformWord64R upperBound g` generates a `Word64` that is uniformly distributed over the range `[0, upperBound]`.

Since: 1.2.0

uniformWord8 :: g -> m Word8 #

Generates a `Word8` that is uniformly distributed over the entire `Word8` range.

The default implementation extracts a `Word8` from `uniformWord32`.

Since: 1.2.0

uniformWord16 :: g -> m Word16 #

Generates a `Word16` that is uniformly distributed over the entire `Word16` range.

The default implementation extracts a `Word16` from `uniformWord32`.

Since: 1.2.0

uniformWord32 :: g -> m Word32 #

Generates a `Word32` that is uniformly distributed over the entire `Word32` range.

The default implementation extracts a `Word32` from `uniformWord64`.

Since: 1.2.0

uniformWord64 :: g -> m Word64 #

Generates a `Word64` that is uniformly distributed over the entire `Word64` range.

The default implementation combines two `Word32` from `uniformWord32` into one `Word64`.

Since: 1.2.0

uniformShortByteString :: Int -> g -> m ShortByteString #

Deprecated: In favor of `uniformShortByteStringM`

`uniformShortByteString n g` generates a `ShortByteString` of length `n` filled with pseudo-random bytes.

Since: 1.2.0

#### Instances

Instances details

(RandomGen g, MonadState g m) => StatefulGen (StateGenM g) m # |
Instance details Defined in System.Random.Internal Methods uniformWord32R :: Word32 -> StateGenM g -> m Word32 # uniformWord64R :: Word64 -> StateGenM g -> m Word64 # uniformWord8 :: StateGenM g -> m Word8 # uniformWord16 :: StateGenM g -> m Word16 # uniformWord32 :: StateGenM g -> m Word32 # uniformWord64 :: StateGenM g -> m Word64 # uniformByteArrayM :: Bool -> Int -> StateGenM g -> m ByteArray # uniformShortByteString :: Int -> StateGenM g -> m ShortByteString #
(RandomGen g, MonadIO m) => StatefulGen (AtomicGenM g) m # |
Instance details Defined in System.Random.Stateful Methods uniformWord32R :: Word32 -> AtomicGenM g -> m Word32 # uniformWord64R :: Word64 -> AtomicGenM g -> m Word64 # uniformWord8 :: AtomicGenM g -> m Word8 # uniformWord16 :: AtomicGenM g -> m Word16 # uniformWord32 :: AtomicGenM g -> m Word32 # uniformWord64 :: AtomicGenM g -> m Word64 # uniformByteArrayM :: Bool -> Int -> AtomicGenM g -> m ByteArray # uniformShortByteString :: Int -> AtomicGenM g -> m ShortByteString #
(RandomGen g, MonadIO m) => StatefulGen (IOGenM g) m # |
Instance details Defined in System.Random.Stateful Methods uniformWord32R :: Word32 -> IOGenM g -> m Word32 # uniformWord64R :: Word64 -> IOGenM g -> m Word64 # uniformWord8 :: IOGenM g -> m Word8 # uniformWord16 :: IOGenM g -> m Word16 # uniformWord32 :: IOGenM g -> m Word32 # uniformWord64 :: IOGenM g -> m Word64 # uniformByteArrayM :: Bool -> Int -> IOGenM g -> m ByteArray # uniformShortByteString :: Int -> IOGenM g -> m ShortByteString #
RandomGen g => StatefulGen (TGenM g) STM # | Since: 1.2.1
Instance details Defined in System.Random.Stateful Methods uniformWord32R :: Word32 -> TGenM g -> STM Word32 # uniformWord64R :: Word64 -> TGenM g -> STM Word64 # uniformWord8 :: TGenM g -> STM Word8 # uniformWord16 :: TGenM g -> STM Word16 # uniformWord32 :: TGenM g -> STM Word32 # uniformWord64 :: TGenM g -> STM Word64 # uniformByteArrayM :: Bool -> Int -> TGenM g -> STM ByteArray # uniformShortByteString :: Int -> TGenM g -> STM ShortByteString #
RandomGen g => StatefulGen (STGenM g s) (ST s) # |
Instance details Defined in System.Random.Stateful Methods uniformWord32R :: Word32 -> STGenM g s -> ST s Word32 # uniformWord64R :: Word64 -> STGenM g s -> ST s Word64 # uniformWord8 :: STGenM g s -> ST s Word8 # uniformWord16 :: STGenM g s -> ST s Word16 # uniformWord32 :: STGenM g s -> ST s Word32 # uniformWord64 :: STGenM g s -> ST s Word64 # uniformByteArrayM :: Bool -> Int -> STGenM g s -> ST s ByteArray # uniformShortByteString :: Int -> STGenM g s -> ST s ShortByteString #

class StatefulGen (MutableGen f m) m => FrozenGen f (m :: Type -> Type) where #

This class is designed for mutable pseudo-random number generators that have a frozen imutable counterpart that can be manipulated in pure code.

It also works great with frozen generators that are based on pure generators that have a `RandomGen` instance.

Here are a few laws, which are important for this type class:

- Roundtrip and complete destruction on overwrite:

    overwriteGen mg fg >> freezeGen mg = pure fg

- Modification of a mutable generator:

    overwriteGen mg fg = modifyGen mg (const ((), fg)

- Freezing of a mutable generator:

    freezeGen mg = modifyGen mg (fg -> (fg, fg))

Since: 1.2.0

Minimal complete definition

(modifyGen | freezeGen, overwriteGen)

Associated Types

type MutableGen f (m :: Type -> Type) = (g :: Type) | g -> f #

Represents the state of the pseudo-random number generator for use with `thawGen` and `freezeGen`.

Since: 1.2.0

Methods

freezeGen :: MutableGen f m -> m f #

Saves the state of the pseudo-random number generator as a frozen seed.

Since: 1.2.0

modifyGen :: MutableGen f m -> (f -> (a, f)) -> m a #

Apply a pure function to the frozen pseudo-random number generator.

Since: 1.3.0

overwriteGen :: MutableGen f m -> f -> m () #

Overwrite contents of the mutable pseudo-random number generator with the supplied frozen one

Since: 1.3.0

#### Instances

Instances details

(RandomGen g, MonadState g m) => FrozenGen (StateGen g) m # |
Instance details Defined in System.Random.Internal Associated Types
type MutableGen (StateGen g) m |
Instance details Defined in System.Random.Internal type MutableGen (StateGen g) m = StateGenM g
Methods freezeGen :: MutableGen (StateGen g) m -> m (StateGen g) # modifyGen :: MutableGen (StateGen g) m -> (StateGen g -> (a, StateGen g)) -> m a # overwriteGen :: MutableGen (StateGen g) m -> StateGen g -> m () #
(RandomGen g, MonadIO m) => FrozenGen (AtomicGen g) m # |
Instance details Defined in System.Random.Stateful Associated Types
type MutableGen (AtomicGen g) m |
Instance details Defined in System.Random.Stateful type MutableGen (AtomicGen g) m = AtomicGenM g
Methods freezeGen :: MutableGen (AtomicGen g) m -> m (AtomicGen g) # modifyGen :: MutableGen (AtomicGen g) m -> (AtomicGen g -> (a, AtomicGen g)) -> m a # overwriteGen :: MutableGen (AtomicGen g) m -> AtomicGen g -> m () #
(RandomGen g, MonadIO m) => FrozenGen (IOGen g) m # |
Instance details Defined in System.Random.Stateful Associated Types
type MutableGen (IOGen g) m |
Instance details Defined in System.Random.Stateful type MutableGen (IOGen g) m = IOGenM g
Methods freezeGen :: MutableGen (IOGen g) m -> m (IOGen g) # modifyGen :: MutableGen (IOGen g) m -> (IOGen g -> (a, IOGen g)) -> m a # overwriteGen :: MutableGen (IOGen g) m -> IOGen g -> m () #
RandomGen g => FrozenGen (TGen g) STM # | Since: 1.2.1
Instance details Defined in System.Random.Stateful Associated Types
type MutableGen (TGen g) STM |
Instance details Defined in System.Random.Stateful type MutableGen (TGen g) STM = TGenM g
Methods freezeGen :: MutableGen (TGen g) STM -> STM (TGen g) # modifyGen :: MutableGen (TGen g) STM -> (TGen g -> (a, TGen g)) -> STM a # overwriteGen :: MutableGen (TGen g) STM -> TGen g -> STM () #
RandomGen g => FrozenGen (STGen g) (ST s) # |
Instance details Defined in System.Random.Stateful Associated Types
type MutableGen (STGen g) (ST s) |
Instance details Defined in System.Random.Stateful type MutableGen (STGen g) (ST s) = STGenM g s
Methods freezeGen :: MutableGen (STGen g) (ST s) -> ST s (STGen g) # modifyGen :: MutableGen (STGen g) (ST s) -> (STGen g -> (a, STGen g)) -> ST s a # overwriteGen :: MutableGen (STGen g) (ST s) -> STGen g -> ST s () #

class FrozenGen f m => ThawedGen f (m :: Type -> Type) where #

Functionality for thawing frozen generators is not part of the `FrozenGen` class, becase not all mutable generators support functionality of creating new mutable generators, which is what thawing is in its essence. For this reason `StateGen` does not have an instance for this type class, but it has one for `FrozenGen`.

Here is an important law that relates this type class to `FrozenGen`

- Roundtrip and independence of mutable generators:

    traverse thawGen fgs >>= traverse freezeGen = pure fgs

Since: 1.3.0

Methods

thawGen :: f -> m (MutableGen f m) #

Create a new mutable pseudo-random number generator from its frozen state.

Since: 1.2.0

#### Instances

Instances details

(RandomGen g, MonadIO m) => ThawedGen (AtomicGen g) m # |
Instance details Defined in System.Random.Stateful Methods thawGen :: AtomicGen g -> m (MutableGen (AtomicGen g) m) #
(RandomGen g, MonadIO m) => ThawedGen (IOGen g) m # |
Instance details Defined in System.Random.Stateful Methods thawGen :: IOGen g -> m (MutableGen (IOGen g) m) #
RandomGen g => ThawedGen (TGen g) STM # |
Instance details Defined in System.Random.Stateful Methods thawGen :: TGen g -> STM (MutableGen (TGen g) STM) #
RandomGen g => ThawedGen (STGen g) (ST s) # |
Instance details Defined in System.Random.Stateful Methods thawGen :: STGen g -> ST s (MutableGen (STGen g) (ST s)) #

withMutableGen :: ThawedGen f m => f -> (MutableGen f m -> m a) -> m (a, f) #

Runs a mutable pseudo-random number generator from its `FrozenGen` state.

#### Examples

Expand

    >>> import Data.Int (Int8)
    >>> withMutableGen (IOGen (mkStdGen 217)) (uniformListM 5) :: IO ([Int8], IOGen StdGen)
    ([-74,37,-50,-2,3],IOGen {unIOGen = StdGen {unStdGen = SMGen 4273268533320920145 15251669095119325999}})

Since: 1.2.0

withMutableGen_ :: ThawedGen f m => f -> (MutableGen f m -> m a) -> m a #

Same as `withMutableGen`, but only returns the generated value.

#### Examples

Expand

    >>> import System.Random.Stateful
    >>> let pureGen = mkStdGen 137
    >>> withMutableGen_ (IOGen pureGen) (uniformRM (1 :: Int, 6 :: Int))
    4

Since: 1.2.0

withSeedMutableGen :: (SeedGen g, ThawedGen g m) => Seed g -> (MutableGen g m -> m a) -> m (a, Seed g) #

Just like `withMutableGen`, except uses a `Seed` instead of a frozen generator.

#### Examples

Expand

Here is good example of how `withSeedMutableGen` can be used with `withSeedFile`, which uses a locally stored seed.

First we define a `reportSeed` function that will print the contents of a seed file as a list of bytes:

    >>> import Data.ByteString as BS (readFile, writeFile, unpack)
    >>> :seti -XOverloadedStrings
    >>> let reportSeed fp = print . ("Seed: " <>) . show . BS.unpack =<< BS.readFile fp

Given a file path, write an `StdGen` seed into the file:

    >>> :seti -XFlexibleContexts -XScopedTypeVariables
    >>> let writeInitSeed fp = BS.writeFile fp (unSeedToByteString (toSeed (mkStdGen 2025)))

Apply a `StatefulGen` monadic action that uses ``IOGen` `StdGen``, restored from the seed in the given path:

    >>> let withMutableSeedFile fp action = withSeedFile fp (\(seed :: Seed (IOGen StdGen)) -> withSeedMutableGen seed action)

Given a path and an action initialize the seed file and apply the action using that seed:

    >>> let withInitSeedFile fp action = writeInitSeed fp *> reportSeed fp *> withMutableSeedFile fp action <* reportSeed fp

For the sake of example we will use a temporary directory for storing the seed. Here we report the contents of the seed file before and after we shuffle a list:

    >>> import UnliftIO.Temporary (withSystemTempDirectory)
    >>> withSystemTempDirectory "random" (\fp -> withInitSeedFile (fp ++ "/seed.bin") (uniformShuffleListM [1..10]))
    "Seed: [183,178,143,77,132,163,109,14,157,105,82,99,148,82,109,173]"
    "Seed: [60,105,117,203,187,138,69,39,157,105,82,99,148,82,109,173]"
    [7,5,4,3,1,8,10,6,9,2]

Since: 1.3.0

withSeedMutableGen_ :: (SeedGen g, ThawedGen g m) => Seed g -> (MutableGen g m -> m a) -> m a #

Just like `withSeedMutableGen`, except it doesn't return the final generator, only the resulting value. This is slightly more efficient, since it doesn't incur overhead from freezeing the mutable generator

Since: 1.3.0

randomM :: (Random a, RandomGen g, FrozenGen g m) => MutableGen g m -> m a #

Generates a pseudo-random value using monadic interface and `Random` instance.

#### Examples

Expand

    >>> import System.Random.Stateful
    >>> let pureGen = mkStdGen 139
    >>> g <- newIOGenM pureGen
    >>> randomM g :: IO Double
    0.33775117339631733

You can use type applications to disambiguate the type of the generated numbers:

    >>> :seti -XTypeApplications
    >>> randomM @Double g
    0.9156875994165681

Since: 1.2.0

randomRM :: (Random a, RandomGen g, FrozenGen g m) => (a, a) -> MutableGen g m -> m a #

Generates a pseudo-random value using monadic interface and `Random` instance.

#### Examples

Expand

    >>> import System.Random.Stateful
    >>> let pureGen = mkStdGen 137
    >>> g <- newIOGenM pureGen
    >>> randomRM (1, 100) g :: IO Int
    52

You can use type applications to disambiguate the type of the generated numbers:

    >>> :seti -XTypeApplications
    >>> randomRM @Int (1, 100) g
    2

Since: 1.2.0

splitGenM :: (SplitGen f, FrozenGen f m) => MutableGen f m -> m f #

Splits a pseudo-random number generator into two. Overwrites the mutable pseudo-random number generator with one of the immutable pseudo-random number generators produced by a `split` function and returns the other.

Since: 1.3.0

splitMutableGenM :: (SplitGen f, ThawedGen f m) => MutableGen f m -> m (MutableGen f m) #

Splits a pseudo-random number generator into two. Overwrites the mutable wrapper with one of the resulting generators and returns the other as a new mutable generator.

Since: 1.3.0

## Deprecated

class (RandomGen r, StatefulGen g m) => RandomGenM g r (m :: Type -> Type) | g -> r where #

Deprecated: In favor of `FrozenGen`

Interface to operations on `RandomGen` wrappers like `IOGenM` and `StateGenM`.

Since: 1.2.0

Methods

applyRandomGenM :: (r -> (a, r)) -> g -> m a #

Deprecated: In favor of `modifyGen`

#### Instances

Instances details

(RandomGen r, MonadState r m) => RandomGenM (StateGenM r) r m # |
Instance details Defined in System.Random.Stateful Methods applyRandomGenM :: (r -> (a, r)) -> StateGenM r -> m a #
(RandomGen r, MonadIO m) => RandomGenM (AtomicGenM r) r m # |
Instance details Defined in System.Random.Stateful Methods applyRandomGenM :: (r -> (a, r)) -> AtomicGenM r -> m a #
(RandomGen r, MonadIO m) => RandomGenM (IOGenM r) r m # |
Instance details Defined in System.Random.Stateful Methods applyRandomGenM :: (r -> (a, r)) -> IOGenM r -> m a #
RandomGen r => RandomGenM (TGenM r) r STM # |
Instance details Defined in System.Random.Stateful Methods applyRandomGenM :: (r -> (a, r)) -> TGenM r -> STM a #
RandomGen r => RandomGenM (STGenM r s) r (ST s) # |
Instance details Defined in System.Random.Stateful Methods applyRandomGenM :: (r -> (a, r)) -> STGenM r s -> ST s a #

# Monadic adapters for pure pseudo-random number generators

Pure pseudo-random number generators can be used in monadic code via the adapters `StateGenM`, `AtomicGenM`, `IOGenM`, `STGenM` and `TGenM`

- `StateGenM` can be used in any state monad. With strict `StateT` there is no performance overhead compared to using the `RandomGen` instance directly. `StateGenM` is not safe to use in the presence of exceptions and concurrency.
- `AtomicGenM` is safe in the presence of exceptions and concurrency since it performs all actions atomically.
- `IOGenM` is a wrapper around an `IORef` that holds a pure generator. `IOGenM` is safe in the presence of exceptions, but not concurrency.
- `STGenM` is a wrapper around an `STRef` that holds a pure generator. `STGenM` is safe in the presence of exceptions, but not concurrency.
- `TGenM` is a wrapper around a `TVar` that holds a pure generator. `TGenM` can be used in a software transactional memory monad `STM`. It is not as performant as `AtomicGenM`, but it can provide stronger guarantees in a concurrent setting.

## Pure adapter in `MonadState`

newtype StateGen g #

Wrapper for pure state gen, which acts as an immutable seed for the corresponding stateful generator `StateGenM`

Since: 1.2.0

Constructors

StateGen |
Fields unStateGen :: g

#### Instances

Instances details

NFData g => NFData (StateGen g) # |
Instance details Defined in System.Random.Internal Methods rnf :: StateGen g -> () #
Storable g => Storable (StateGen g) # |
Instance details Defined in System.Random.Internal Methods sizeOf :: StateGen g -> Int # alignment :: StateGen g -> Int # peekElemOff :: Ptr (StateGen g) -> Int -> IO (StateGen g) # pokeElemOff :: Ptr (StateGen g) -> Int -> StateGen g -> IO () # peekByteOff :: Ptr b -> Int -> IO (StateGen g) # pokeByteOff :: Ptr b -> Int -> StateGen g -> IO () # peek :: Ptr (StateGen g) -> IO (StateGen g) # poke :: Ptr (StateGen g) -> StateGen g -> IO () #
Show g => Show (StateGen g) # |
Instance details Defined in System.Random.Internal Methods showsPrec :: Int -> StateGen g -> ShowS # show :: StateGen g -> String # showList :: [StateGen g] -> ShowS #
Eq g => Eq (StateGen g) # |
Instance details Defined in System.Random.Internal Methods (==) :: StateGen g -> StateGen g -> Bool # (/=) :: StateGen g -> StateGen g -> Bool #
Ord g => Ord (StateGen g) # |
Instance details Defined in System.Random.Internal Methods compare :: StateGen g -> StateGen g -> Ordering # (<) :: StateGen g -> StateGen g -> Bool # (<=) :: StateGen g -> StateGen g -> Bool # (>) :: StateGen g -> StateGen g -> Bool # (>=) :: StateGen g -> StateGen g -> Bool # max :: StateGen g -> StateGen g -> StateGen g # min :: StateGen g -> StateGen g -> StateGen g #
RandomGen g => RandomGen (StateGen g) # |
Instance details Defined in System.Random.Internal Methods next :: StateGen g -> (Int, StateGen g) # genWord8 :: StateGen g -> (Word8, StateGen g) # genWord16 :: StateGen g -> (Word16, StateGen g) # genWord32 :: StateGen g -> (Word32, StateGen g) # genWord64 :: StateGen g -> (Word64, StateGen g) # genWord32R :: Word32 -> StateGen g -> (Word32, StateGen g) # genWord64R :: Word64 -> StateGen g -> (Word64, StateGen g) # genShortByteString :: Int -> StateGen g -> (ShortByteString, StateGen g) # unsafeUniformFillMutableByteArray :: MutableByteArray s -> Int -> Int -> StateGen g -> ST s (StateGen g) # genRange :: StateGen g -> (Int, Int) # split :: StateGen g -> (StateGen g, StateGen g) #
SeedGen g => SeedGen (StateGen g) # |
Instance details Defined in System.Random.Seed Associated Types
type SeedSize (StateGen g) |
Instance details Defined in System.Random.Seed type SeedSize (StateGen g) = SeedSize g
Methods fromSeed :: Seed (StateGen g) -> StateGen g # toSeed :: StateGen g -> Seed (StateGen g) # fromSeed64 :: NonEmpty Word64 -> StateGen g # toSeed64 :: StateGen g -> NonEmpty Word64 #
(RandomGen g, MonadState g m) => FrozenGen (StateGen g) m # |
Instance details Defined in System.Random.Internal Associated Types
type MutableGen (StateGen g) m |
Instance details Defined in System.Random.Internal type MutableGen (StateGen g) m = StateGenM g
Methods freezeGen :: MutableGen (StateGen g) m -> m (StateGen g) # modifyGen :: MutableGen (StateGen g) m -> (StateGen g -> (a, StateGen g)) -> m a # overwriteGen :: MutableGen (StateGen g) m -> StateGen g -> m () #
type SeedSize (StateGen g) # |
Instance details Defined in System.Random.Seed type SeedSize (StateGen g) = SeedSize g
type MutableGen (StateGen g) m # |
Instance details Defined in System.Random.Internal type MutableGen (StateGen g) m = StateGenM g

data StateGenM g #

Opaque data type that carries the type of a pure pseudo-random number generator.

Since: 1.2.0

Constructors

StateGenM |

#### Instances

Instances details

(RandomGen g, MonadState g m) => StatefulGen (StateGenM g) m # |
Instance details Defined in System.Random.Internal Methods uniformWord32R :: Word32 -> StateGenM g -> m Word32 # uniformWord64R :: Word64 -> StateGenM g -> m Word64 # uniformWord8 :: StateGenM g -> m Word8 # uniformWord16 :: StateGenM g -> m Word16 # uniformWord32 :: StateGenM g -> m Word32 # uniformWord64 :: StateGenM g -> m Word64 # uniformByteArrayM :: Bool -> Int -> StateGenM g -> m ByteArray # uniformShortByteString :: Int -> StateGenM g -> m ShortByteString #
(RandomGen r, MonadState r m) => RandomGenM (StateGenM r) r m # |
Instance details Defined in System.Random.Stateful Methods applyRandomGenM :: (r -> (a, r)) -> StateGenM r -> m a #

runStateGen :: RandomGen g => g -> (StateGenM g -> State g a) -> (a, g) #

Runs a monadic generating action in the `State` monad using a pure pseudo-random number generator.

#### Examples

Expand

    >>> import System.Random.Stateful
    >>> let pureGen = mkStdGen 137
    >>> runStateGen pureGen randomM :: (Int, StdGen)
    (7879794327570578227,StdGen {unStdGen = SMGen 11285859549637045894 7641485672361121627})

Since: 1.2.0

runStateGen_ :: RandomGen g => g -> (StateGenM g -> State g a) -> a #

Runs a monadic generating action in the `State` monad using a pure pseudo-random number generator. Returns only the resulting pseudo-random value.

#### Examples

Expand

    >>> import System.Random.Stateful
    >>> let pureGen = mkStdGen 137
    >>> runStateGen_ pureGen randomM :: Int
    7879794327570578227

Since: 1.2.0

runStateGenT :: RandomGen g => g -> (StateGenM g -> StateT g m a) -> m (a, g) #

Runs a monadic generating action in the `StateT` monad using a pure pseudo-random number generator.

#### Examples

Expand

    >>> import System.Random.Stateful
    >>> let pureGen = mkStdGen 137
    >>> runStateGenT pureGen randomM :: IO (Int, StdGen)
    (7879794327570578227,StdGen {unStdGen = SMGen 11285859549637045894 7641485672361121627})

Since: 1.2.0

runStateGenT_ :: (RandomGen g, Functor f) => g -> (StateGenM g -> StateT g f a) -> f a #

Runs a monadic generating action in the `StateT` monad using a pure pseudo-random number generator. Returns only the resulting pseudo-random value.

#### Examples

Expand

    >>> import System.Random.Stateful
    >>> let pureGen = mkStdGen 137
    >>> runStateGenT_ pureGen randomM :: IO Int
    7879794327570578227

Since: 1.2.1

runStateGenST :: RandomGen g => g -> (forall s. StateGenM g -> StateT g (ST s) a) -> (a, g) #

Runs a monadic generating action in the `ST` monad using a pure pseudo-random number generator.

Since: 1.2.0

runStateGenST_ :: RandomGen g => g -> (forall s. StateGenM g -> StateT g (ST s) a) -> a #

Runs a monadic generating action in the `ST` monad using a pure pseudo-random number generator. Same as `runStateGenST`, but discards the resulting generator.

Since: 1.2.1

## Mutable thread-safe adapter in `IO`

newtype AtomicGen g #

Frozen version of mutable `AtomicGenM` generator

Since: 1.2.0

Constructors

AtomicGen |
Fields unAtomicGen :: g

#### Instances

Instances details

NFData g => NFData (AtomicGen g) # |
Instance details Defined in System.Random.Stateful Methods rnf :: AtomicGen g -> () #
Storable g => Storable (AtomicGen g) # |
Instance details Defined in System.Random.Stateful Methods sizeOf :: AtomicGen g -> Int # alignment :: AtomicGen g -> Int # peekElemOff :: Ptr (AtomicGen g) -> Int -> IO (AtomicGen g) # pokeElemOff :: Ptr (AtomicGen g) -> Int -> AtomicGen g -> IO () # peekByteOff :: Ptr b -> Int -> IO (AtomicGen g) # pokeByteOff :: Ptr b -> Int -> AtomicGen g -> IO () # peek :: Ptr (AtomicGen g) -> IO (AtomicGen g) # poke :: Ptr (AtomicGen g) -> AtomicGen g -> IO () #
Show g => Show (AtomicGen g) # |
Instance details Defined in System.Random.Stateful Methods showsPrec :: Int -> AtomicGen g -> ShowS # show :: AtomicGen g -> String # showList :: [AtomicGen g] -> ShowS #
Eq g => Eq (AtomicGen g) # |
Instance details Defined in System.Random.Stateful Methods (==) :: AtomicGen g -> AtomicGen g -> Bool # (/=) :: AtomicGen g -> AtomicGen g -> Bool #
Ord g => Ord (AtomicGen g) # |
Instance details Defined in System.Random.Stateful Methods compare :: AtomicGen g -> AtomicGen g -> Ordering # (<) :: AtomicGen g -> AtomicGen g -> Bool # (<=) :: AtomicGen g -> AtomicGen g -> Bool # (>) :: AtomicGen g -> AtomicGen g -> Bool # (>=) :: AtomicGen g -> AtomicGen g -> Bool # max :: AtomicGen g -> AtomicGen g -> AtomicGen g # min :: AtomicGen g -> AtomicGen g -> AtomicGen g #
RandomGen g => RandomGen (AtomicGen g) # |
Instance details Defined in System.Random.Stateful Methods next :: AtomicGen g -> (Int, AtomicGen g) # genWord8 :: AtomicGen g -> (Word8, AtomicGen g) # genWord16 :: AtomicGen g -> (Word16, AtomicGen g) # genWord32 :: AtomicGen g -> (Word32, AtomicGen g) # genWord64 :: AtomicGen g -> (Word64, AtomicGen g) # genWord32R :: Word32 -> AtomicGen g -> (Word32, AtomicGen g) # genWord64R :: Word64 -> AtomicGen g -> (Word64, AtomicGen g) # genShortByteString :: Int -> AtomicGen g -> (ShortByteString, AtomicGen g) # unsafeUniformFillMutableByteArray :: MutableByteArray s -> Int -> Int -> AtomicGen g -> ST s (AtomicGen g) # genRange :: AtomicGen g -> (Int, Int) # split :: AtomicGen g -> (AtomicGen g, AtomicGen g) #
SplitGen g => SplitGen (AtomicGen g) # |
Instance details Defined in System.Random.Stateful Methods splitGen :: AtomicGen g -> (AtomicGen g, AtomicGen g) #
SeedGen g => SeedGen (AtomicGen g) # |
Instance details Defined in System.Random.Stateful Associated Types
type SeedSize (AtomicGen g) |
Instance details Defined in System.Random.Stateful type SeedSize (AtomicGen g) = SeedSize g
Methods fromSeed :: Seed (AtomicGen g) -> AtomicGen g # toSeed :: AtomicGen g -> Seed (AtomicGen g) # fromSeed64 :: NonEmpty Word64 -> AtomicGen g # toSeed64 :: AtomicGen g -> NonEmpty Word64 #
(RandomGen g, MonadIO m) => FrozenGen (AtomicGen g) m # |
Instance details Defined in System.Random.Stateful Associated Types
type MutableGen (AtomicGen g) m |
Instance details Defined in System.Random.Stateful type MutableGen (AtomicGen g) m = AtomicGenM g
Methods freezeGen :: MutableGen (AtomicGen g) m -> m (AtomicGen g) # modifyGen :: MutableGen (AtomicGen g) m -> (AtomicGen g -> (a, AtomicGen g)) -> m a # overwriteGen :: MutableGen (AtomicGen g) m -> AtomicGen g -> m () #
(RandomGen g, MonadIO m) => ThawedGen (AtomicGen g) m # |
Instance details Defined in System.Random.Stateful Methods thawGen :: AtomicGen g -> m (MutableGen (AtomicGen g) m) #
type SeedSize (AtomicGen g) # |
Instance details Defined in System.Random.Stateful type SeedSize (AtomicGen g) = SeedSize g
type MutableGen (AtomicGen g) m # |
Instance details Defined in System.Random.Stateful type MutableGen (AtomicGen g) m = AtomicGenM g

newtype AtomicGenM g #

Wraps an `IORef` that holds a pure pseudo-random number generator. All operations are performed atomically.

- `AtomicGenM` is safe in the presence of exceptions and concurrency.
- `AtomicGenM` is the slowest of the monadic adapters due to the overhead of its atomic operations.

Since: 1.2.0

Constructors

AtomicGenM |
Fields unAtomicGenM :: IORef g

#### Instances

Instances details

(RandomGen g, MonadIO m) => StatefulGen (AtomicGenM g) m # |
Instance details Defined in System.Random.Stateful Methods uniformWord32R :: Word32 -> AtomicGenM g -> m Word32 # uniformWord64R :: Word64 -> AtomicGenM g -> m Word64 # uniformWord8 :: AtomicGenM g -> m Word8 # uniformWord16 :: AtomicGenM g -> m Word16 # uniformWord32 :: AtomicGenM g -> m Word32 # uniformWord64 :: AtomicGenM g -> m Word64 # uniformByteArrayM :: Bool -> Int -> AtomicGenM g -> m ByteArray # uniformShortByteString :: Int -> AtomicGenM g -> m ShortByteString #
(RandomGen r, MonadIO m) => RandomGenM (AtomicGenM r) r m # |
Instance details Defined in System.Random.Stateful Methods applyRandomGenM :: (r -> (a, r)) -> AtomicGenM r -> m a #

newAtomicGenM :: MonadIO m => g -> m (AtomicGenM g) #

Creates a new `AtomicGenM`.

Since: 1.2.0

applyAtomicGen :: MonadIO m => (g -> (a, g)) -> AtomicGenM g -> m a #

Atomically applies a pure operation to the wrapped pseudo-random number generator.

#### Examples

Expand

    >>> import System.Random.Stateful
    >>> let pureGen = mkStdGen 137
    >>> g <- newAtomicGenM pureGen
    >>> applyAtomicGen random g :: IO Int
    7879794327570578227

Since: 1.2.0

globalStdGen :: AtomicGenM StdGen #

Global mutable standard pseudo-random number generator. This is the same generator that was historically used by `randomIO` and `randomRIO` functions.

    >>> import Control.Monad (replicateM)
    >>> replicateM 10 (uniformRM ('a', 'z') globalStdGen)
    "tdzxhyfvgr"

Since: 1.2.1

## Mutable adapter in `IO`

newtype IOGen g #

Frozen version of mutable `IOGenM` generator

Since: 1.2.0

Constructors

IOGen |
Fields unIOGen :: g

#### Instances

Instances details

NFData g => NFData (IOGen g) # |
Instance details Defined in System.Random.Stateful Methods rnf :: IOGen g -> () #
Storable g => Storable (IOGen g) # |
Instance details Defined in System.Random.Stateful Methods sizeOf :: IOGen g -> Int # alignment :: IOGen g -> Int # peekElemOff :: Ptr (IOGen g) -> Int -> IO (IOGen g) # pokeElemOff :: Ptr (IOGen g) -> Int -> IOGen g -> IO () # peekByteOff :: Ptr b -> Int -> IO (IOGen g) # pokeByteOff :: Ptr b -> Int -> IOGen g -> IO () # peek :: Ptr (IOGen g) -> IO (IOGen g) # poke :: Ptr (IOGen g) -> IOGen g -> IO () #
Show g => Show (IOGen g) # |
Instance details Defined in System.Random.Stateful Methods showsPrec :: Int -> IOGen g -> ShowS # show :: IOGen g -> String # showList :: [IOGen g] -> ShowS #
Eq g => Eq (IOGen g) # |
Instance details Defined in System.Random.Stateful Methods (==) :: IOGen g -> IOGen g -> Bool # (/=) :: IOGen g -> IOGen g -> Bool #
Ord g => Ord (IOGen g) # |
Instance details Defined in System.Random.Stateful Methods compare :: IOGen g -> IOGen g -> Ordering # (<) :: IOGen g -> IOGen g -> Bool # (<=) :: IOGen g -> IOGen g -> Bool # (>) :: IOGen g -> IOGen g -> Bool # (>=) :: IOGen g -> IOGen g -> Bool # max :: IOGen g -> IOGen g -> IOGen g # min :: IOGen g -> IOGen g -> IOGen g #
RandomGen g => RandomGen (IOGen g) # |
Instance details Defined in System.Random.Stateful Methods next :: IOGen g -> (Int, IOGen g) # genWord8 :: IOGen g -> (Word8, IOGen g) # genWord16 :: IOGen g -> (Word16, IOGen g) # genWord32 :: IOGen g -> (Word32, IOGen g) # genWord64 :: IOGen g -> (Word64, IOGen g) # genWord32R :: Word32 -> IOGen g -> (Word32, IOGen g) # genWord64R :: Word64 -> IOGen g -> (Word64, IOGen g) # genShortByteString :: Int -> IOGen g -> (ShortByteString, IOGen g) # unsafeUniformFillMutableByteArray :: MutableByteArray s -> Int -> Int -> IOGen g -> ST s (IOGen g) # genRange :: IOGen g -> (Int, Int) # split :: IOGen g -> (IOGen g, IOGen g) #
SplitGen g => SplitGen (IOGen g) # |
Instance details Defined in System.Random.Stateful Methods splitGen :: IOGen g -> (IOGen g, IOGen g) #
SeedGen g => SeedGen (IOGen g) # |
Instance details Defined in System.Random.Stateful Associated Types
type SeedSize (IOGen g) |
Instance details Defined in System.Random.Stateful type SeedSize (IOGen g) = SeedSize g
Methods fromSeed :: Seed (IOGen g) -> IOGen g # toSeed :: IOGen g -> Seed (IOGen g) # fromSeed64 :: NonEmpty Word64 -> IOGen g # toSeed64 :: IOGen g -> NonEmpty Word64 #
(RandomGen g, MonadIO m) => FrozenGen (IOGen g) m # |
Instance details Defined in System.Random.Stateful Associated Types
type MutableGen (IOGen g) m |
Instance details Defined in System.Random.Stateful type MutableGen (IOGen g) m = IOGenM g
Methods freezeGen :: MutableGen (IOGen g) m -> m (IOGen g) # modifyGen :: MutableGen (IOGen g) m -> (IOGen g -> (a, IOGen g)) -> m a # overwriteGen :: MutableGen (IOGen g) m -> IOGen g -> m () #
(RandomGen g, MonadIO m) => ThawedGen (IOGen g) m # |
Instance details Defined in System.Random.Stateful Methods thawGen :: IOGen g -> m (MutableGen (IOGen g) m) #
type SeedSize (IOGen g) # |
Instance details Defined in System.Random.Stateful type SeedSize (IOGen g) = SeedSize g
type MutableGen (IOGen g) m # |
Instance details Defined in System.Random.Stateful type MutableGen (IOGen g) m = IOGenM g

newtype IOGenM g #

Wraps an `IORef` that holds a pure pseudo-random number generator.

- `IOGenM` is safe in the presence of exceptions, but not concurrency.
- `IOGenM` is slower than `StateGenM` due to the extra pointer indirection.
- `IOGenM` is faster than `AtomicGenM` since the `IORef` operations used by `IOGenM` are not atomic.

An example use case is writing pseudo-random bytes into a file:

    >>> import UnliftIO.Temporary (withSystemTempFile)
    >>> import Data.ByteString (hPutStr)
    >>> let ioGen g = withSystemTempFile "foo.bin" $ \_ h -> uniformRM (0, 100) g >>= flip uniformByteStringM g >>= hPutStr h

and then run it:

    >>> newIOGenM (mkStdGen 1729) >>= ioGen

Since: 1.2.0

Constructors

IOGenM |
Fields unIOGenM :: IORef g

#### Instances

Instances details

(RandomGen g, MonadIO m) => StatefulGen (IOGenM g) m # |
Instance details Defined in System.Random.Stateful Methods uniformWord32R :: Word32 -> IOGenM g -> m Word32 # uniformWord64R :: Word64 -> IOGenM g -> m Word64 # uniformWord8 :: IOGenM g -> m Word8 # uniformWord16 :: IOGenM g -> m Word16 # uniformWord32 :: IOGenM g -> m Word32 # uniformWord64 :: IOGenM g -> m Word64 # uniformByteArrayM :: Bool -> Int -> IOGenM g -> m ByteArray # uniformShortByteString :: Int -> IOGenM g -> m ShortByteString #
(RandomGen r, MonadIO m) => RandomGenM (IOGenM r) r m # |
Instance details Defined in System.Random.Stateful Methods applyRandomGenM :: (r -> (a, r)) -> IOGenM r -> m a #

newIOGenM :: MonadIO m => g -> m (IOGenM g) #

Creates a new `IOGenM`.

Since: 1.2.0

applyIOGen :: MonadIO m => (g -> (a, g)) -> IOGenM g -> m a #

Applies a pure operation to the wrapped pseudo-random number generator.

#### Examples

Expand

    >>> import System.Random.Stateful
    >>> let pureGen = mkStdGen 137
    >>> g <- newIOGenM pureGen
    >>> applyIOGen random g :: IO Int
    7879794327570578227

Since: 1.2.0

## Mutable adapter in `ST`

newtype STGen g #

Frozen version of mutable `STGenM` generator

Since: 1.2.0

Constructors

STGen |
Fields unSTGen :: g

#### Instances

Instances details

NFData g => NFData (STGen g) # |
Instance details Defined in System.Random.Stateful Methods rnf :: STGen g -> () #
Storable g => Storable (STGen g) # |
Instance details Defined in System.Random.Stateful Methods sizeOf :: STGen g -> Int # alignment :: STGen g -> Int # peekElemOff :: Ptr (STGen g) -> Int -> IO (STGen g) # pokeElemOff :: Ptr (STGen g) -> Int -> STGen g -> IO () # peekByteOff :: Ptr b -> Int -> IO (STGen g) # pokeByteOff :: Ptr b -> Int -> STGen g -> IO () # peek :: Ptr (STGen g) -> IO (STGen g) # poke :: Ptr (STGen g) -> STGen g -> IO () #
Show g => Show (STGen g) # |
Instance details Defined in System.Random.Stateful Methods showsPrec :: Int -> STGen g -> ShowS # show :: STGen g -> String # showList :: [STGen g] -> ShowS #
Eq g => Eq (STGen g) # |
Instance details Defined in System.Random.Stateful Methods (==) :: STGen g -> STGen g -> Bool # (/=) :: STGen g -> STGen g -> Bool #
Ord g => Ord (STGen g) # |
Instance details Defined in System.Random.Stateful Methods compare :: STGen g -> STGen g -> Ordering # (<) :: STGen g -> STGen g -> Bool # (<=) :: STGen g -> STGen g -> Bool # (>) :: STGen g -> STGen g -> Bool # (>=) :: STGen g -> STGen g -> Bool # max :: STGen g -> STGen g -> STGen g # min :: STGen g -> STGen g -> STGen g #
RandomGen g => RandomGen (STGen g) # |
Instance details Defined in System.Random.Stateful Methods next :: STGen g -> (Int, STGen g) # genWord8 :: STGen g -> (Word8, STGen g) # genWord16 :: STGen g -> (Word16, STGen g) # genWord32 :: STGen g -> (Word32, STGen g) # genWord64 :: STGen g -> (Word64, STGen g) # genWord32R :: Word32 -> STGen g -> (Word32, STGen g) # genWord64R :: Word64 -> STGen g -> (Word64, STGen g) # genShortByteString :: Int -> STGen g -> (ShortByteString, STGen g) # unsafeUniformFillMutableByteArray :: MutableByteArray s -> Int -> Int -> STGen g -> ST s (STGen g) # genRange :: STGen g -> (Int, Int) # split :: STGen g -> (STGen g, STGen g) #
SplitGen g => SplitGen (STGen g) # |
Instance details Defined in System.Random.Stateful Methods splitGen :: STGen g -> (STGen g, STGen g) #
SeedGen g => SeedGen (STGen g) # |
Instance details Defined in System.Random.Stateful Associated Types
type SeedSize (STGen g) |
Instance details Defined in System.Random.Stateful type SeedSize (STGen g) = SeedSize g
Methods fromSeed :: Seed (STGen g) -> STGen g # toSeed :: STGen g -> Seed (STGen g) # fromSeed64 :: NonEmpty Word64 -> STGen g # toSeed64 :: STGen g -> NonEmpty Word64 #
RandomGen g => FrozenGen (STGen g) (ST s) # |
Instance details Defined in System.Random.Stateful Associated Types
type MutableGen (STGen g) (ST s) |
Instance details Defined in System.Random.Stateful type MutableGen (STGen g) (ST s) = STGenM g s
Methods freezeGen :: MutableGen (STGen g) (ST s) -> ST s (STGen g) # modifyGen :: MutableGen (STGen g) (ST s) -> (STGen g -> (a, STGen g)) -> ST s a # overwriteGen :: MutableGen (STGen g) (ST s) -> STGen g -> ST s () #
RandomGen g => ThawedGen (STGen g) (ST s) # |
Instance details Defined in System.Random.Stateful Methods thawGen :: STGen g -> ST s (MutableGen (STGen g) (ST s)) #
type SeedSize (STGen g) # |
Instance details Defined in System.Random.Stateful type SeedSize (STGen g) = SeedSize g
type MutableGen (STGen g) (ST s) # |
Instance details Defined in System.Random.Stateful type MutableGen (STGen g) (ST s) = STGenM g s

newtype STGenM g s #

Wraps an `STRef` that holds a pure pseudo-random number generator.

- `STGenM` is safe in the presence of exceptions, but not concurrency.
- `STGenM` is slower than `StateGenM` due to the extra pointer indirection.

Since: 1.2.0

Constructors

STGenM |
Fields unSTGenM :: STRef s g

#### Instances

Instances details

RandomGen r => RandomGenM (STGenM r s) r (ST s) # |
Instance details Defined in System.Random.Stateful Methods applyRandomGenM :: (r -> (a, r)) -> STGenM r s -> ST s a #
RandomGen g => StatefulGen (STGenM g s) (ST s) # |
Instance details Defined in System.Random.Stateful Methods uniformWord32R :: Word32 -> STGenM g s -> ST s Word32 # uniformWord64R :: Word64 -> STGenM g s -> ST s Word64 # uniformWord8 :: STGenM g s -> ST s Word8 # uniformWord16 :: STGenM g s -> ST s Word16 # uniformWord32 :: STGenM g s -> ST s Word32 # uniformWord64 :: STGenM g s -> ST s Word64 # uniformByteArrayM :: Bool -> Int -> STGenM g s -> ST s ByteArray # uniformShortByteString :: Int -> STGenM g s -> ST s ShortByteString #

newSTGenM :: g -> ST s (STGenM g s) #

Creates a new `STGenM`.

Since: 1.2.0

applySTGen :: (g -> (a, g)) -> STGenM g s -> ST s a #

Applies a pure operation to the wrapped pseudo-random number generator.

#### Examples

Expand

    >>> import System.Random.Stateful
    >>> let pureGen = mkStdGen 137
    >>> (runSTGen pureGen (\g -> applySTGen random g)) :: (Int, StdGen)
    (7879794327570578227,StdGen {unStdGen = SMGen 11285859549637045894 7641485672361121627})

Since: 1.2.0

runSTGen :: RandomGen g => g -> (forall s. STGenM g s -> ST s a) -> (a, g) #

Runs a monadic generating action in the `ST` monad using a pure pseudo-random number generator.

#### Examples

Expand

    >>> import System.Random.Stateful
    >>> let pureGen = mkStdGen 137
    >>> (runSTGen pureGen (\g -> applySTGen random g)) :: (Int, StdGen)
    (7879794327570578227,StdGen {unStdGen = SMGen 11285859549637045894 7641485672361121627})

Since: 1.2.0

runSTGen_ :: RandomGen g => g -> (forall s. STGenM g s -> ST s a) -> a #

Runs a monadic generating action in the `ST` monad using a pure pseudo-random number generator. Returns only the resulting pseudo-random value.

#### Examples

Expand

    >>> import System.Random.Stateful
    >>> let pureGen = mkStdGen 137
    >>> (runSTGen_ pureGen (\g -> applySTGen random g)) :: Int
    7879794327570578227

Since: 1.2.0

## Mutable thread-safe adapter in `STM`

newtype TGen g #

Frozen version of mutable `TGenM` generator

Since: 1.2.1

Constructors

TGen |
Fields unTGen :: g

#### Instances

Instances details

NFData g => NFData (TGen g) # |
Instance details Defined in System.Random.Stateful Methods rnf :: TGen g -> () #
Storable g => Storable (TGen g) # |
Instance details Defined in System.Random.Stateful Methods sizeOf :: TGen g -> Int # alignment :: TGen g -> Int # peekElemOff :: Ptr (TGen g) -> Int -> IO (TGen g) # pokeElemOff :: Ptr (TGen g) -> Int -> TGen g -> IO () # peekByteOff :: Ptr b -> Int -> IO (TGen g) # pokeByteOff :: Ptr b -> Int -> TGen g -> IO () # peek :: Ptr (TGen g) -> IO (TGen g) # poke :: Ptr (TGen g) -> TGen g -> IO () #
Show g => Show (TGen g) # |
Instance details Defined in System.Random.Stateful Methods showsPrec :: Int -> TGen g -> ShowS # show :: TGen g -> String # showList :: [TGen g] -> ShowS #
Eq g => Eq (TGen g) # |
Instance details Defined in System.Random.Stateful Methods (==) :: TGen g -> TGen g -> Bool # (/=) :: TGen g -> TGen g -> Bool #
Ord g => Ord (TGen g) # |
Instance details Defined in System.Random.Stateful Methods compare :: TGen g -> TGen g -> Ordering # (<) :: TGen g -> TGen g -> Bool # (<=) :: TGen g -> TGen g -> Bool # (>) :: TGen g -> TGen g -> Bool # (>=) :: TGen g -> TGen g -> Bool # max :: TGen g -> TGen g -> TGen g # min :: TGen g -> TGen g -> TGen g #
RandomGen g => RandomGen (TGen g) # |
Instance details Defined in System.Random.Stateful Methods next :: TGen g -> (Int, TGen g) # genWord8 :: TGen g -> (Word8, TGen g) # genWord16 :: TGen g -> (Word16, TGen g) # genWord32 :: TGen g -> (Word32, TGen g) # genWord64 :: TGen g -> (Word64, TGen g) # genWord32R :: Word32 -> TGen g -> (Word32, TGen g) # genWord64R :: Word64 -> TGen g -> (Word64, TGen g) # genShortByteString :: Int -> TGen g -> (ShortByteString, TGen g) # unsafeUniformFillMutableByteArray :: MutableByteArray s -> Int -> Int -> TGen g -> ST s (TGen g) # genRange :: TGen g -> (Int, Int) # split :: TGen g -> (TGen g, TGen g) #
SplitGen g => SplitGen (TGen g) # |
Instance details Defined in System.Random.Stateful Methods splitGen :: TGen g -> (TGen g, TGen g) #
SeedGen g => SeedGen (TGen g) # |
Instance details Defined in System.Random.Stateful Associated Types
type SeedSize (TGen g) |
Instance details Defined in System.Random.Stateful type SeedSize (TGen g) = SeedSize g
Methods fromSeed :: Seed (TGen g) -> TGen g # toSeed :: TGen g -> Seed (TGen g) # fromSeed64 :: NonEmpty Word64 -> TGen g # toSeed64 :: TGen g -> NonEmpty Word64 #
RandomGen g => FrozenGen (TGen g) STM # | Since: 1.2.1
Instance details Defined in System.Random.Stateful Associated Types
type MutableGen (TGen g) STM |
Instance details Defined in System.Random.Stateful type MutableGen (TGen g) STM = TGenM g
Methods freezeGen :: MutableGen (TGen g) STM -> STM (TGen g) # modifyGen :: MutableGen (TGen g) STM -> (TGen g -> (a, TGen g)) -> STM a # overwriteGen :: MutableGen (TGen g) STM -> TGen g -> STM () #
RandomGen g => ThawedGen (TGen g) STM # |
Instance details Defined in System.Random.Stateful Methods thawGen :: TGen g -> STM (MutableGen (TGen g) STM) #
type SeedSize (TGen g) # |
Instance details Defined in System.Random.Stateful type SeedSize (TGen g) = SeedSize g
type MutableGen (TGen g) STM # |
Instance details Defined in System.Random.Stateful type MutableGen (TGen g) STM = TGenM g

newtype TGenM g #

Wraps a `TVar` that holds a pure pseudo-random number generator.

Since: 1.2.1

Constructors

TGenM |
Fields unTGenM :: TVar g

#### Instances

Instances details

RandomGen g => StatefulGen (TGenM g) STM # | Since: 1.2.1
Instance details Defined in System.Random.Stateful Methods uniformWord32R :: Word32 -> TGenM g -> STM Word32 # uniformWord64R :: Word64 -> TGenM g -> STM Word64 # uniformWord8 :: TGenM g -> STM Word8 # uniformWord16 :: TGenM g -> STM Word16 # uniformWord32 :: TGenM g -> STM Word32 # uniformWord64 :: TGenM g -> STM Word64 # uniformByteArrayM :: Bool -> Int -> TGenM g -> STM ByteArray # uniformShortByteString :: Int -> TGenM g -> STM ShortByteString #
RandomGen r => RandomGenM (TGenM r) r STM # |
Instance details Defined in System.Random.Stateful Methods applyRandomGenM :: (r -> (a, r)) -> TGenM r -> STM a #

newTGenM :: g -> STM (TGenM g) #

Creates a new `TGenM` in `STM`.

Since: 1.2.1

newTGenMIO :: MonadIO m => g -> m (TGenM g) #

Creates a new `TGenM` in `IO`.

Since: 1.2.1

applyTGen :: (g -> (a, g)) -> TGenM g -> STM a #

Applies a pure operation to the wrapped pseudo-random number generator.

#### Examples

Expand

    >>> import Control.Concurrent.STM
    >>> import System.Random.Stateful
    >>> import Data.Int (Int32)
    >>> let pureGen = mkStdGen 137
    >>> stmGen <- newTGenMIO pureGen
    >>> atomically $ applyTGen uniform stmGen :: IO Int32
    637238067

Since: 1.2.1

# Pseudo-random values of various types

This library provides two type classes to generate pseudo-random values:

- `UniformRange` is used to generate a value of a type uniformly within a range.
- `Uniform` is used to generate a value of a type uniformly over all possible values of that type.

Types may have instances for both or just one of `UniformRange` and `Uniform`. A few examples illustrate this:

- `Int`, `Word16` and `Bool` are instances of both `UniformRange` and `Uniform`.
- `Integer`, `Float` and `Double` each have an instance for `UniformRange` but no `Uniform` instance.
- A hypothetical type `Radian` representing angles by taking values in the range `[0, 2π)` has a trivial `Uniform` instance, but no `UniformRange` instance: the problem is that two given `Radian` values always span two ranges, one clockwise and one anti-clockwise.
- It is trivial to construct a `Uniform (a, b)` instance given `Uniform a` and `Uniform b` (and this library provides this tuple instance).
- On the other hand, there is no correct way to construct a `UniformRange (a, b)` instance based on just `UniformRange a` and `UniformRange b`.

class Uniform a where #

The class of types for which a uniformly distributed value can be drawn from all possible values of the type.

Since: 1.2.0

Minimal complete definition

Nothing

Methods

uniformM :: StatefulGen g m => g -> m a #

Generates a value uniformly distributed over all possible values of that type.

There is a default implementation via `Generic`:

    >>> :seti -XDeriveGeneric -XDeriveAnyClass
    >>> import GHC.Generics (Generic)
    >>> import System.Random.Stateful
    >>> data MyBool = MyTrue | MyFalse deriving (Show, Generic, Finite, Uniform)
    >>> data Action = Code MyBool | Eat (Maybe Bool) | Sleep deriving (Show, Generic, Finite, Uniform)
    >>> gen <- newIOGenM (mkStdGen 42)
    >>> uniformListM 10 gen :: IO [Action]
    [Code MyTrue,Code MyTrue,Eat Nothing,Code MyFalse,Eat (Just False),Eat (Just True),Eat Nothing,Eat (Just False),Sleep,Code MyFalse]

Since: 1.2.0

default uniformM :: (StatefulGen g m, Generic a, GUniform (Rep a)) => g -> m a #

#### Instances

Instances details

Uniform CBool # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CBool #
Uniform CChar # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CChar #
Uniform CInt # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CInt #
Uniform CIntMax # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CIntMax #
Uniform CIntPtr # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CIntPtr #
Uniform CLLong # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CLLong #
Uniform CLong # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CLong #
Uniform CPtrdiff # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CPtrdiff #
Uniform CSChar # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CSChar #
Uniform CShort # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CShort #
Uniform CSigAtomic # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CSigAtomic #
Uniform CSize # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CSize #
Uniform CUChar # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CUChar #
Uniform CUInt # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CUInt #
Uniform CUIntMax # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CUIntMax #
Uniform CUIntPtr # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CUIntPtr #
Uniform CULLong # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CULLong #
Uniform CULong # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CULong #
Uniform CUShort # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CUShort #
Uniform CWchar # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m CWchar #
Uniform Int16 # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m Int16 #
Uniform Int32 # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m Int32 #
Uniform Int64 # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m Int64 #
Uniform Int8 # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m Int8 #
Uniform Word16 # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m Word16 #
Uniform Word32 # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m Word32 #
Uniform Word64 # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m Word64 #
Uniform Word8 # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m Word8 #
Uniform () # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m () #
Uniform Bool # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m Bool #
Uniform Char # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m Char #
Uniform Int # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m Int #
Uniform Word # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m Word #
SeedGen g => Uniform (Seed g) # |
Instance details Defined in System.Random.Seed Methods uniformM :: StatefulGen g0 m => g0 -> m (Seed g) #
(Finite a, Uniform a) => Uniform (Maybe a) # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m (Maybe a) #
(Finite a, Uniform a, Finite b, Uniform b) => Uniform (Either a b) # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m (Either a b) #
(Uniform a, Uniform b) => Uniform (a, b) # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m (a, b) #
(Uniform a, Uniform b, Uniform c) => Uniform (a, b, c) # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m (a, b, c) #
(Uniform a, Uniform b, Uniform c, Uniform d) => Uniform (a, b, c, d) # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m (a, b, c, d) #
(Uniform a, Uniform b, Uniform c, Uniform d, Uniform e) => Uniform (a, b, c, d, e) # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m (a, b, c, d, e) #
(Uniform a, Uniform b, Uniform c, Uniform d, Uniform e, Uniform f) => Uniform (a, b, c, d, e, f) # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g m => g -> m (a, b, c, d, e, f) #
(Uniform a, Uniform b, Uniform c, Uniform d, Uniform e, Uniform f, Uniform g) => Uniform (a, b, c, d, e, f, g) # |
Instance details Defined in System.Random.Internal Methods uniformM :: StatefulGen g0 m => g0 -> m (a, b, c, d, e, f, g) #

uniformViaFiniteM :: (StatefulGen g m, Generic a, GFinite (Rep a)) => g -> m a #

A definition of `Uniform` for `Finite` types. If your data has several fields of sub-`Word` cardinality, this instance may be more efficient than one, derived via `Generic` and `GUniform`.

    >>> :seti -XDeriveGeneric -XDeriveAnyClass
    >>> import GHC.Generics (Generic)
    >>> import System.Random.Stateful
    >>> data Triple = Triple Word8 Word8 Word8 deriving (Show, Generic, Finite)
    >>> instance Uniform Triple where uniformM = uniformViaFiniteM
    >>> gen <- newIOGenM (mkStdGen 42)
    >>> uniformListM 5 gen :: IO [Triple]
    [Triple 60 226 48,Triple 234 194 151,Triple 112 96 95,Triple 51 251 15,Triple 6 0 208]

class UniformRange a where #

The class of types for which a uniformly distributed value can be drawn from a range.

Since: 1.2.0

Minimal complete definition

Nothing

Methods

uniformRM :: StatefulGen g m => (a, a) -> g -> m a #

Generates a value uniformly distributed over the provided range, which is interpreted as inclusive in the lower and upper bound.

- `uniformRM (1 :: Int, 4 :: Int)` generates values uniformly from the set \(\{1,2,3,4\}\)
- `uniformRM (1 :: Float, 4 :: Float)` generates values uniformly from the set \(\{x\;|\;1 \le x \le 4\}\)

The following law should hold to make the function always defined:

    uniformRM (a, b) = uniformRM (b, a)

The range is understood as defined by means of `isInRange`, so

    isInRange (a, b) <$> uniformRM (a, b) gen == pure True

but beware of floating point number caveats.

There is a default implementation via `Generic`:

    >>> :seti -XDeriveGeneric -XDeriveAnyClass
    >>> import GHC.Generics (Generic)
    >>> import Data.Word (Word8)
    >>> import Control.Monad (replicateM)
    >>> import System.Random.Stateful
    >>> gen <- newIOGenM (mkStdGen 42)
    >>> data Tuple = Tuple Bool Word8 deriving (Show, Generic, UniformRange)
    >>> replicateM 10 (uniformRM (Tuple False 100, Tuple True 150) gen)
    [Tuple False 102,Tuple True 118,Tuple False 115,Tuple True 113,Tuple True 126,Tuple False 127,Tuple True 130,Tuple False 113,Tuple False 150,Tuple False 125]

Since: 1.2.0

default uniformRM :: (StatefulGen g m, Generic a, GUniformRange (Rep a)) => (a, a) -> g -> m a #

isInRange :: (a, a) -> a -> Bool #

A notion of (inclusive) ranges prescribed to `a`.

Ranges are symmetric:

    isInRange (lo, hi) x == isInRange (hi, lo) x

Ranges include their endpoints:

    isInRange (lo, hi) lo == True

When endpoints coincide, there is nothing else:

    isInRange (x, x) y == x == y

Endpoints are endpoints:

    isInRange (lo, hi) x ==>
    isInRange (lo, x) hi == x == hi

Ranges are transitive relations:

    isInRange (lo, hi) lo' && isInRange (lo, hi) hi' && isInRange (lo', hi') x
    ==> isInRange (lo, hi) x

There is a default implementation of `isInRange` via `Generic`. Other helper function that can be used for implementing this function are `isInRangeOrd` and `isInRangeEnum`

Since: 1.3.0

default isInRange :: (Generic a, GUniformRange (Rep a)) => (a, a) -> a -> Bool #

#### Instances

Instances details

UniformRange CBool # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CBool, CBool) -> g -> m CBool # isInRange :: (CBool, CBool) -> CBool -> Bool #
UniformRange CChar # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CChar, CChar) -> g -> m CChar # isInRange :: (CChar, CChar) -> CChar -> Bool #
UniformRange CDouble # | See Floating point number caveats.
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CDouble, CDouble) -> g -> m CDouble # isInRange :: (CDouble, CDouble) -> CDouble -> Bool #
UniformRange CFloat # | See Floating point number caveats.
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CFloat, CFloat) -> g -> m CFloat # isInRange :: (CFloat, CFloat) -> CFloat -> Bool #
UniformRange CInt # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CInt, CInt) -> g -> m CInt # isInRange :: (CInt, CInt) -> CInt -> Bool #
UniformRange CIntMax # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CIntMax, CIntMax) -> g -> m CIntMax # isInRange :: (CIntMax, CIntMax) -> CIntMax -> Bool #
UniformRange CIntPtr # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CIntPtr, CIntPtr) -> g -> m CIntPtr # isInRange :: (CIntPtr, CIntPtr) -> CIntPtr -> Bool #
UniformRange CLLong # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CLLong, CLLong) -> g -> m CLLong # isInRange :: (CLLong, CLLong) -> CLLong -> Bool #
UniformRange CLong # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CLong, CLong) -> g -> m CLong # isInRange :: (CLong, CLong) -> CLong -> Bool #
UniformRange CPtrdiff # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CPtrdiff, CPtrdiff) -> g -> m CPtrdiff # isInRange :: (CPtrdiff, CPtrdiff) -> CPtrdiff -> Bool #
UniformRange CSChar # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CSChar, CSChar) -> g -> m CSChar # isInRange :: (CSChar, CSChar) -> CSChar -> Bool #
UniformRange CShort # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CShort, CShort) -> g -> m CShort # isInRange :: (CShort, CShort) -> CShort -> Bool #
UniformRange CSigAtomic # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CSigAtomic, CSigAtomic) -> g -> m CSigAtomic # isInRange :: (CSigAtomic, CSigAtomic) -> CSigAtomic -> Bool #
UniformRange CSize # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CSize, CSize) -> g -> m CSize # isInRange :: (CSize, CSize) -> CSize -> Bool #
UniformRange CUChar # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CUChar, CUChar) -> g -> m CUChar # isInRange :: (CUChar, CUChar) -> CUChar -> Bool #
UniformRange CUInt # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CUInt, CUInt) -> g -> m CUInt # isInRange :: (CUInt, CUInt) -> CUInt -> Bool #
UniformRange CUIntMax # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CUIntMax, CUIntMax) -> g -> m CUIntMax # isInRange :: (CUIntMax, CUIntMax) -> CUIntMax -> Bool #
UniformRange CUIntPtr # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CUIntPtr, CUIntPtr) -> g -> m CUIntPtr # isInRange :: (CUIntPtr, CUIntPtr) -> CUIntPtr -> Bool #
UniformRange CULLong # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CULLong, CULLong) -> g -> m CULLong # isInRange :: (CULLong, CULLong) -> CULLong -> Bool #
UniformRange CULong # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CULong, CULong) -> g -> m CULong # isInRange :: (CULong, CULong) -> CULong -> Bool #
UniformRange CUShort # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CUShort, CUShort) -> g -> m CUShort # isInRange :: (CUShort, CUShort) -> CUShort -> Bool #
UniformRange CWchar # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (CWchar, CWchar) -> g -> m CWchar # isInRange :: (CWchar, CWchar) -> CWchar -> Bool #
UniformRange Int16 # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Int16, Int16) -> g -> m Int16 # isInRange :: (Int16, Int16) -> Int16 -> Bool #
UniformRange Int32 # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Int32, Int32) -> g -> m Int32 # isInRange :: (Int32, Int32) -> Int32 -> Bool #
UniformRange Int64 # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Int64, Int64) -> g -> m Int64 # isInRange :: (Int64, Int64) -> Int64 -> Bool #
UniformRange Int8 # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Int8, Int8) -> g -> m Int8 # isInRange :: (Int8, Int8) -> Int8 -> Bool #
UniformRange Word16 # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Word16, Word16) -> g -> m Word16 # isInRange :: (Word16, Word16) -> Word16 -> Bool #
UniformRange Word32 # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Word32, Word32) -> g -> m Word32 # isInRange :: (Word32, Word32) -> Word32 -> Bool #
UniformRange Word64 # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Word64, Word64) -> g -> m Word64 # isInRange :: (Word64, Word64) -> Word64 -> Bool #
UniformRange Word8 # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Word8, Word8) -> g -> m Word8 # isInRange :: (Word8, Word8) -> Word8 -> Bool #
UniformRange Integer # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Integer, Integer) -> g -> m Integer # isInRange :: (Integer, Integer) -> Integer -> Bool #
UniformRange Natural # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Natural, Natural) -> g -> m Natural # isInRange :: (Natural, Natural) -> Natural -> Bool #
UniformRange () # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => ((), ()) -> g -> m () # isInRange :: ((), ()) -> () -> Bool #
UniformRange Bool # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Bool, Bool) -> g -> m Bool # isInRange :: (Bool, Bool) -> Bool -> Bool #
UniformRange Char # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Char, Char) -> g -> m Char # isInRange :: (Char, Char) -> Char -> Bool #
UniformRange Double # | See Floating point number caveats.
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Double, Double) -> g -> m Double # isInRange :: (Double, Double) -> Double -> Bool #
UniformRange Float # | See Floating point number caveats.
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Float, Float) -> g -> m Float # isInRange :: (Float, Float) -> Float -> Bool #
UniformRange Int # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Int, Int) -> g -> m Int # isInRange :: (Int, Int) -> Int -> Bool #
UniformRange Word # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => (Word, Word) -> g -> m Word # isInRange :: (Word, Word) -> Word -> Bool #
(UniformRange a, UniformRange b) => UniformRange (a, b) # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => ((a, b), (a, b)) -> g -> m (a, b) # isInRange :: ((a, b), (a, b)) -> (a, b) -> Bool #
(UniformRange a, UniformRange b, UniformRange c) => UniformRange (a, b, c) # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => ((a, b, c), (a, b, c)) -> g -> m (a, b, c) # isInRange :: ((a, b, c), (a, b, c)) -> (a, b, c) -> Bool #
(UniformRange a, UniformRange b, UniformRange c, UniformRange d) => UniformRange (a, b, c, d) # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => ((a, b, c, d), (a, b, c, d)) -> g -> m (a, b, c, d) # isInRange :: ((a, b, c, d), (a, b, c, d)) -> (a, b, c, d) -> Bool #
(UniformRange a, UniformRange b, UniformRange c, UniformRange d, UniformRange e) => UniformRange (a, b, c, d, e) # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => ((a, b, c, d, e), (a, b, c, d, e)) -> g -> m (a, b, c, d, e) # isInRange :: ((a, b, c, d, e), (a, b, c, d, e)) -> (a, b, c, d, e) -> Bool #
(UniformRange a, UniformRange b, UniformRange c, UniformRange d, UniformRange e, UniformRange f) => UniformRange (a, b, c, d, e, f) # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g m => ((a, b, c, d, e, f), (a, b, c, d, e, f)) -> g -> m (a, b, c, d, e, f) # isInRange :: ((a, b, c, d, e, f), (a, b, c, d, e, f)) -> (a, b, c, d, e, f) -> Bool #
(UniformRange a, UniformRange b, UniformRange c, UniformRange d, UniformRange e, UniformRange f, UniformRange g) => UniformRange (a, b, c, d, e, f, g) # |
Instance details Defined in System.Random.Internal Methods uniformRM :: StatefulGen g0 m => ((a, b, c, d, e, f, g), (a, b, c, d, e, f, g)) -> g0 -> m (a, b, c, d, e, f, g) # isInRange :: ((a, b, c, d, e, f, g), (a, b, c, d, e, f, g)) -> (a, b, c, d, e, f, g) -> Bool #

isInRangeOrd :: Ord a => (a, a) -> a -> Bool #

Utilize `Ord` instance to decide if a value is within the range. Designed to be used for implementing `isInRange`

Since: 1.3.0

isInRangeEnum :: Enum a => (a, a) -> a -> Bool #

Utilize `Enum` instance to decide if a value is within the range. Designed to be used for implementing `isInRange`

Since: 1.3.0

## Lists

uniformListM :: (StatefulGen g m, Uniform a) => Int -> g -> m [a] #

Generates a list of pseudo-random values.

#### Examples

Expand

    >>> import System.Random.Stateful
    >>> let pureGen = mkStdGen 137
    >>> g <- newIOGenM pureGen
    >>> uniformListM 10 g :: IO [Bool]
    [True,True,True,True,False,True,True,False,False,False]

Since: 1.2.0

uniformListRM :: (StatefulGen g m, UniformRange a) => Int -> (a, a) -> g -> m [a] #

Generates a list of pseudo-random values in a specified range.

#### Examples

Expand

    >>> import System.Random.Stateful
    >>> let pureGen = mkStdGen 137
    >>> g <- newIOGenM pureGen
    >>> uniformListRM 10 (20, 30) g :: IO [Int]
    [23,21,28,25,28,28,26,25,29,27]

Since: 1.3.0

uniformShuffleListM :: StatefulGen g m => [a] -> g -> m [a] #

Shuffle elements of a list in a uniformly random order.

#### Examples

Expand

    >>> import System.Random.Stateful
    >>> runStateGen_ (mkStdGen 127) $ uniformShuffleListM "ELVIS"
    "LIVES"

Since: 1.3.0

## Generators for sequences of pseudo-random bytes

uniformByteArrayM #

Arguments

:: StatefulGen g m |
=> Bool | Should `ByteArray` be allocated as pinned memory or not
-> Int | Size of the newly created `ByteArray` in number of bytes.
-> g | Generator to use for filling in the newly created `ByteArray`
-> m ByteArray |

`uniformByteArrayM n g` generates a `ByteArray` of length `n` filled with pseudo-random bytes.

Since: 1.3.0

uniformByteStringM :: StatefulGen g m => Int -> g -> m ByteString #

Generates a pseudo-random `ByteString` of the specified size.

Since: 1.2.0

uniformShortByteStringM :: StatefulGen g m => Int -> g -> m ShortByteString #

`uniformShortByteString n g` generates a `ShortByteString` of length `n` filled with pseudo-random bytes.

Since: 1.3.0

# Helper functions for createing instances

## Sequences of bytes

fillByteArrayST :: Bool -> Int -> ST s Word64 -> ST s ByteArray #

Using an `ST` action that generates 8 bytes at a time fill in a new `ByteArray` in architecture agnostic manner.

Since: 1.3.0

genShortByteStringIO #

Arguments

:: Int | Number of bytes to generate
-> IO Word64 | IO action that can generate 8 random bytes at a time
-> IO ShortByteString |

Deprecated: In favor of `fillByteArrayST`

Efficiently fills in a new `ShortByteString` in a platform independent manner.

Since: 1.2.0

genShortByteStringST :: Int -> ST s Word64 -> ST s ShortByteString #

Deprecated: In favor of `fillByteArrayST`, since `uniformShortByteString`, which it was used for, was also deprecated

Same as `genShortByteStringIO`, but runs in `ST`.

Since: 1.2.0

defaultUnsafeUniformFillMutableByteArray #

Arguments

:: RandomGen g |
=> MutableByteArray s |
-> Int | Starting offset
-> Int | Number of random bytes to write into the array
-> g | ST action that can generate 8 random bytes at a time
-> ST s g |

Efficiently generates a sequence of pseudo-random bytes in a platform independent manner.

Since: 1.2.0

## Floating point numbers

uniformDouble01M :: StatefulGen g m => g -> m Double #

Generates uniformly distributed `Double` in the range \([0, 1]\). Numbers are generated by generating uniform `Word64` and dividing it by \(2^{64}\). It's used to implement `UniformRange` instance for `Double`.

Since: 1.2.0

uniformDoublePositive01M :: StatefulGen g m => g -> m Double #

Generates uniformly distributed `Double` in the range \((0, 1]\). Number is generated as \(2^{-64}/2+\operatorname{uniformDouble01M}\). Constant is 1/2 of smallest nonzero value which could be generated by `uniformDouble01M`.

Since: 1.2.0

uniformFloat01M :: StatefulGen g m => g -> m Float #

Generates uniformly distributed `Float` in the range \([0, 1]\). Numbers are generated by generating uniform `Word32` and dividing it by \(2^{32}\). It's used to implement `UniformRange` instance for `Float`.

Since: 1.2.0

uniformFloatPositive01M :: StatefulGen g m => g -> m Float #

Generates uniformly distributed `Float` in the range \((0, 1]\). Number is generated as \(2^{-32}/2+\operatorname{uniformFloat01M}\). Constant is 1/2 of smallest nonzero value which could be generated by `uniformFloat01M`.

Since: 1.2.0

## Enum types

uniformEnumM :: (Enum a, Bounded a, StatefulGen g m) => g -> m a #

Generates uniformly distributed `Enum`. One can use it to define a `Uniform` instance:

    data Colors = Red | Green | Blue deriving (Enum, Bounded)
    instance Uniform Colors where uniformM = uniformEnumM

Since: 1.3.0

uniformEnumRM :: (Enum a, StatefulGen g m) => (a, a) -> g -> m a #

Generates uniformly distributed `Enum` in the given range. One can use it to define a `UniformRange` instance:

    data Colors = Red | Green | Blue deriving (Enum)
    instance UniformRange Colors where
      uniformRM = uniformEnumRM
      inInRange (lo, hi) x = isInRange (fromEnum lo, fromEnum hi) (fromEnum x)

Since: 1.3.0

## Word

uniformWordR #

Arguments

:: StatefulGen g m |
=> Word | Maximum value to generate
-> g | Stateful generator
-> m Word |

Architecture specific `Word` generation in the specified lower range

Since: 1.3.0

# Appendix

## How to implement `StatefulGen`

Typically, a monadic pseudo-random number generator has facilities to save and restore its internal state in addition to generating pseudo-random numbers.

Here is an example instance for the monadic pseudo-random number generator from the `mwc-random` package:

    import qualified System.Random.MWC as MWC
    import qualified Data.Vector.Generic as G

    instance (s ~ PrimState m, PrimMonad m) => StatefulGen (MWC.Gen s) m where
      uniformWord8 = MWC.uniform
      uniformWord16 = MWC.uniform
      uniformWord32 = MWC.uniform
      uniformWord64 = MWC.uniform
      uniformByteArrayM isPinned n g = stToPrim (fillByteArrayST isPinned n (MWC.uniform g))

    instance PrimMonad m => FrozenGen MWC.Seed m where
      type MutableGen MWC.Seed m = MWC.Gen (PrimState m)
      freezeGen = MWC.save
      overwriteGen (Gen mv) (Seed v) = G.copy mv v

    instance PrimMonad m => ThawedGen MWC.Seed m where
      thawGen = MWC.restore

### `FrozenGen`

`FrozenGen` gives us ability to use most of stateful pseudo-random number generator in its immutable form, if one exists that is. The biggest benefit that can be drawn from a polymorphic access to a stateful pseudo-random number generator in a frozen form is the ability to serialize, deserialize and possibly even use the stateful generator in a pure setting without knowing the actual type of a generator ahead of time. For example we can write a function that accepts a frozen state of some pseudo-random number generator and produces a short list with random even integers.

    >>> import Data.Int (Int8)
    >>> import Control.Monad (replicateM)
    >>> :{
    myCustomRandomList :: ThawedGen f m => f -> m [Int8]
    myCustomRandomList f =
      withMutableGen_ f $ \gen -> do
        len <- uniformRM (5, 10) gen
        replicateM len $ do
          x <- uniformM gen
          pure $ if even x then x else x + 1
    :}

and later we can apply it to a frozen version of a stateful generator, such as `STGen`:

    >>> print $ runST $ myCustomRandomList (STGen (mkStdGen 217))
    [-50,-2,4,-8,-58,-40,24,-32,-110,24]

Alternatively, instead of discarding the final state of the generator, as it happens above, we could have used `withMutableGen`, which together with the result would give us back its frozen form. This would allow us to store the end state of our generator somewhere for the later reuse.

## Floating point number caveats

scaleFloating #

Arguments

:: (RealFloat a, Integral w, Bounded w, FiniteBits w) |
=> a | Low
-> a | High
-> w | Uniformly distributed unsigned integral value that will be used for converting to a floating point value and subsequent scaling to the specified range
-> a |

This is the function that is used to scale a floating point value from random word range to the custom `[low, high]` range.

Since: 1.3.0

Due to rounding errors, floating point operations are neither associative nor distributive the way the corresponding operations on real numbers are. Additionally, floating point numbers admit special values `NaN` as well as negative and positive infinity.

The `UniformRange` instances for `Float` and `Double` use the following procedure to generate a random value in a range for `uniformRM (l, h) g`:

- If `l == h`, return: `l`.
- If ``isInfinite` l == True` or ``isInfinite` h == True`, return: `l + h`

- Otherwise:

  1. Generate an unsigned integral of matching width `w` uniformly.

  2. Check whether `h - l` overflows to infinity and, if it does, then convert `w` to a floating point number in `[0.0, 1.0]` range through division of `w` by the highest possible value:

         x = fromIntegral w / fromIntegral maxBound

     Then we scale and clamp it before returning it:

         max (min (x * l + (1 - x) * h) (max l h)) (min l h)

     Clamping is necessary, because otherwise it would be possible to run into a degenerate case when a scaled value is outside the specified range due to rounding errors.

  3. Whenever `h - l` does not overflow, we use this common formula for scaling: `l + (h - l) * x`. However, instead of using `[0.0, 1.0]` range we use the top most bit of `w` to decide whether we will treat the generated floating point value as `[0.0, 0.5]` range or `[0.5, 1.0]` range and use the left over bits to produce a floating point value in the half unit range:

         x = fromIntegral (clearBit w 31) / fromIntegral maxBound

     Further scaling depends on the top most bit:

         if testBit w 31
            then l + (h - l) * x
            else h + (l - h) * x

     Because of this clever technique the result does not need clamping, since scaled values are guaranteed to stay within the specified range. Another reason why this tecnique is used for the common case instead of the one described in `2.` is because it avoids usage of `1 - x`, which consequently reduces loss of randomness due to rounding.

What happens when `NaN` or `Infinity` are given to `uniformRM`? We first define them as constants:

    >>> nan = read "NaN" :: Float
    >>> inf = read "Infinity" :: Float
    >>> g <- newIOGenM (mkStdGen 2024)

- If at least one of \(l\) or \(h\) is `NaN`, the result is `NaN`.

      >>> uniformRM (nan, 1) g
      NaN
      >>> uniformRM (-1, nan) g
      NaN

- If \(l\) and \(h\) are both `Infinity` with opposing signs, then the result is `NaN`.

      >>> uniformRM (-inf, inf) g
      NaN
      >>> uniformRM (inf, -inf) g
      NaN

- Otherwise, if \(l\) is `Infinity` or `-Infinity`, the result is \(l\).

      >>> uniformRM (inf, 1) g
      Infinity
      >>> uniformRM (-inf, 1) g
      -Infinity

- Otherwise, if \(h\) is `Infinity` or `-Infinity`, the result is \(h\).

      >>> uniformRM (1, inf) g
      Infinity
      >>> uniformRM (1, -inf) g
      -Infinity

Note that the GCC 10.1.0 C++ standard library, the Java 10 standard library and CPython 3.8 use a similar procedure to generate floating point values in a range.

# References

1. Guy L. Steele, Jr., Doug Lea, and Christine H. Flood. 2014. Fast splittable pseudorandom number generators. In Proceedings of the 2014 ACM International Conference on Object Oriented Programming Systems Languages & Applications (OOPSLA '14). ACM, New York, NY, USA, 453-472. DOI: https://doi.org/10.1145/2660193.2660195