MonadRandom-0.6.2: Random-number generation monad.

Copyright | (c) Brent Yorgey 2016
License | BSD3 (see LICENSE)
Maintainer | byorgey@gmail.com
Stability | experimental
Portability | non-portable (multi-param classes, functional dependencies, undecidable instances)
Safe Haskell | Trustworthy
Language | Haskell2010

Control.Monad.Trans.Random.Lazy

Contents

- The Rand monad transformer
- The RandT monad transformer
- Lifting other operations
- StatefulGen interface
- Examples
  - Random monads

Description

Lazy random monads, passing a random number generator through a computation. See below for examples.

For a strict version with the same interface, see Control.Monad.Trans.Random.Strict.

Synopsis

- type Rand g = RandT g Identity
- liftRand :: (g -> (a, g)) -> Rand g a
- runRand :: Rand g a -> g -> (a, g)
- evalRand :: Rand g a -> g -> a
- execRand :: Rand g a -> g -> g
- mapRand :: ((a, g) -> (b, g)) -> Rand g a -> Rand g b
- withRand :: (g -> g) -> Rand g a -> Rand g a
- evalRandIO :: Rand StdGen a -> IO a
- data RandT g (m :: Type -> Type) a
- liftRandT :: (g -> m (a, g)) -> RandT g m a
- runRandT :: RandT g m a -> g -> m (a, g)
- evalRandT :: Monad m => RandT g m a -> g -> m a
- execRandT :: Monad m => RandT g m a -> g -> m g
- mapRandT :: (m (a, g) -> n (b, g)) -> RandT g m a -> RandT g n b
- withRandT :: forall g (m :: Type -> Type) a. (g -> g) -> RandT g m a -> RandT g m a
- liftCallCC :: CallCC m (a, g) (b, g) -> CallCC (RandT g m) a b
- liftCallCC' :: CallCC m (a, g) (b, g) -> CallCC (RandT g m) a b
- liftCatch :: Catch e m (a, g) -> Catch e (RandT g m) a
- liftListen :: Monad m => Listen w m (a, g) -> Listen w (RandT g m) a
- liftPass :: Monad m => Pass w m (a, g) -> Pass w (RandT g m) a
- evalRandTIO :: MonadIO m => RandT StdGen m a -> m a
- data RandGen g = RandGen
- withRandGen :: g -> (RandGen g -> RandT g m a) -> m (a, g)
- withRandGen_ :: Monad m => g -> (RandGen g -> RandT g m a) -> m a

# The Rand monad transformer

type Rand g = RandT g Identity Source #

A random monad parameterized by the type `g` of the generator to carry.

The `return` function leaves the generator unchanged, while `>>=` uses the final generator of the first computation as the initial generator of the second.

liftRand Source #

Arguments

:: (g -> (a, g)) | pure random transformer
-> Rand g a | equivalent generator-passing computation

Construct a random monad computation from a function. (The inverse of `runRand`.)

runRand Source #

Arguments

:: Rand g a | generator-passing computation to execute
-> g | initial generator
-> (a, g) | return value and final generator

Unwrap a random monad computation as a function. (The inverse of `liftRand`.)

evalRand Source #

Arguments

:: Rand g a | generator-passing computation to execute
-> g | initial generator
-> a | return value of the random computation

Evaluate a random computation with the given initial generator and return the final value, discarding the final generator.

-     evalRand m s = fst (runRand m s)

execRand Source #

Arguments

:: Rand g a | generator-passing computation to execute
-> g | initial generator
-> g | final generator

Evaluate a random computation with the given initial generator and return the final generator, discarding the final value.

-     execRand m s = snd (runRand m s)

mapRand :: ((a, g) -> (b, g)) -> Rand g a -> Rand g b Source #

Map both the return value and final generator of a computation using the given function.

-     runRand (mapRand f m) = f . runRand m

withRand :: (g -> g) -> Rand g a -> Rand g a Source #

``withRand` f m` executes action `m` on a generator modified by applying `f`.

-     withRand f m = modify f >> m

evalRandIO :: Rand StdGen a -> IO a Source #

Evaluate a random computation in the `IO` monad, splitting the global standard generator to get a new one for the computation.

# The RandT monad transformer

data RandT g (m :: Type -> Type) a Source #

A random transformer monad parameterized by:

- `g` - The generator.
- `m` - The inner monad.

The `return` function leaves the generator unchanged, while `>>=` uses the final generator of the first computation as the initial generator of the second.

#### Instances

Instances details

(MonadReader r m, MonadWriter w m, MonadState s m) => MonadRWS r w s (RandT g m) Source # |
Instance details Defined in Control.Monad.Trans.Random.Lazy
(RandomGen g, Monad m) => MonadSplit g (RandT g m) Source # |
Instance details Defined in Control.Monad.Trans.Random.Lazy Methods getSplit :: RandT g m g Source #
MonadError e m => MonadError e (RandT g m) Source # |
Instance details Defined in Control.Monad.Trans.Random.Lazy Methods throwError :: e -> RandT g m a Source # catchError :: RandT g m a -> (e -> RandT g m a) -> RandT g m a Source #
MonadReader r m => MonadReader r (RandT g m) Source # |
Instance details Defined in Control.Monad.Trans.Random.Lazy Methods ask :: RandT g m r Source # local :: (r -> r) -> RandT g m a -> RandT g m a Source # reader :: (r -> a) -> RandT g m a Source #
MonadState s m => MonadState s (RandT g m) Source # |
Instance details Defined in Control.Monad.Trans.Random.Lazy Methods get :: RandT g m s Source # put :: s -> RandT g m () Source # state :: (s -> (a, s)) -> RandT g m a Source #
MonadWriter w m => MonadWriter w (RandT g m) Source # |
Instance details Defined in Control.Monad.Trans.Random.Lazy Methods writer :: (a, w) -> RandT g m a Source # tell :: w -> RandT g m () Source # listen :: RandT g m a -> RandT g m (a, w) Source # pass :: RandT g m (a, w -> w) -> RandT g m a Source #
MonadTrans (RandT g) Source # |
Instance details Defined in Control.Monad.Trans.Random.Lazy Methods lift :: Monad m => m a -> RandT g m a Source #
(Monad m, RandomGen g) => RandomGenM (RandGen g) g (RandT g m) Source # | Since: 0.5.3
Instance details Defined in Control.Monad.Trans.Random.Lazy Methods applyRandomGenM :: (g -> (a, g)) -> RandGen g -> RandT g m a Source #
(Monad m, RandomGen g) => StatefulGen (RandGen g) (RandT g m) Source # | Since: 0.5.3

Instance details

Defined in Control.Monad.Trans.Random.Lazy

Methods

uniformWord32R :: Word32 -> RandGen g -> RandT g m Word32 Source #

uniformWord64R :: Word64 -> RandGen g -> RandT g m Word64 Source #

uniformWord8 :: RandGen g -> RandT g m Word8 Source #

uniformWord16 :: RandGen g -> RandT g m Word16 Source #

uniformWord32 :: RandGen g -> RandT g m Word32 Source #

uniformWord64 :: RandGen g -> RandT g m Word64 Source #

uniformShortByteString :: Int -> RandGen g -> RandT g m ShortByteString Source #

(Monad m, RandomGen g) => MonadInterleave (RandT g m) Source # |
Instance details Defined in Control.Monad.Trans.Random.Lazy Methods interleave :: RandT g m a -> RandT g m a Source #
(RandomGen g, Monad m) => MonadRandom (RandT g m) Source # |
Instance details Defined in Control.Monad.Trans.Random.Lazy Methods getRandomR :: Random a => (a, a) -> RandT g m a Source # getRandom :: Random a => RandT g m a Source # getRandomRs :: Random a => (a, a) -> RandT g m [a] Source # getRandoms :: Random a => RandT g m [a] Source #
MonadIO m => MonadIO (RandT g m) Source # |
Instance details Defined in Control.Monad.Trans.Random.Lazy Methods liftIO :: IO a -> RandT g m a Source #
MonadPlus m => Alternative (RandT g m) Source # |
Instance details Defined in Control.Monad.Trans.Random.Lazy Methods empty :: RandT g m a Source # (<|>) :: RandT g m a -> RandT g m a -> RandT g m a Source # some :: RandT g m a -> RandT g m [a] Source # many :: RandT g m a -> RandT g m [a] Source #
Monad m => Applicative (RandT g m) Source # |
Instance details Defined in Control.Monad.Trans.Random.Lazy Methods pure :: a -> RandT g m a Source # (<*>) :: RandT g m (a -> b) -> RandT g m a -> RandT g m b Source # liftA2 :: (a -> b -> c) -> RandT g m a -> RandT g m b -> RandT g m c Source # (*>) :: RandT g m a -> RandT g m b -> RandT g m b Source # (<*) :: RandT g m a -> RandT g m b -> RandT g m a Source #
Functor m => Functor (RandT g m) Source # |
Instance details Defined in Control.Monad.Trans.Random.Lazy Methods fmap :: (a -> b) -> RandT g m a -> RandT g m b Source # (<$) :: a -> RandT g m b -> RandT g m a Source #
Monad m => Monad (RandT g m) Source # |
Instance details Defined in Control.Monad.Trans.Random.Lazy Methods (>>=) :: RandT g m a -> (a -> RandT g m b) -> RandT g m b Source # (>>) :: RandT g m a -> RandT g m b -> RandT g m b Source # return :: a -> RandT g m a Source #
MonadPlus m => MonadPlus (RandT g m) Source # |
Instance details Defined in Control.Monad.Trans.Random.Lazy Methods mzero :: RandT g m a Source # mplus :: RandT g m a -> RandT g m a -> RandT g m a Source #
MonadFail m => MonadFail (RandT g m) Source # |
Instance details Defined in Control.Monad.Trans.Random.Lazy Methods fail :: String -> RandT g m a Source #
MonadFix m => MonadFix (RandT g m) Source # |
Instance details Defined in Control.Monad.Trans.Random.Lazy Methods mfix :: (a -> RandT g m a) -> RandT g m a Source #
MonadCont m => MonadCont (RandT g m) Source # |
Instance details Defined in Control.Monad.Trans.Random.Lazy Methods callCC :: ((a -> RandT g m b) -> RandT g m a) -> RandT g m a Source #
PrimMonad m => PrimMonad (RandT s m) Source # |

Instance details

Defined in Control.Monad.Trans.Random.Lazy

Associated Types

type PrimState (RandT s m) |
Instance details Defined in Control.Monad.Trans.Random.Lazy type PrimState (RandT s m) = PrimState m

Methods

primitive :: (State# (PrimState (RandT s m)) -> (# State# (PrimState (RandT s m)), a #)) -> RandT s m a Source #

type PrimState (RandT s m) Source # |
Instance details Defined in Control.Monad.Trans.Random.Lazy type PrimState (RandT s m) = PrimState m

liftRandT Source #

Arguments

:: (g -> m (a, g)) | impure random transformer
-> RandT g m a | equivalent generator-passing computation

Construct a random monad computation from an impure function. (The inverse of `runRandT`.)

runRandT Source #

Arguments

:: RandT g m a | generator-passing computation to execute
-> g | initial generator
-> m (a, g) | return value and final generator

Unwrap a random monad computation as an impure function. (The inverse of `liftRandT`.)

evalRandT :: Monad m => RandT g m a -> g -> m a Source #

Evaluate a random computation with the given initial generator and return the final value, discarding the final generator.

-     evalRandT m g = liftM fst (runRandT m g)

execRandT :: Monad m => RandT g m a -> g -> m g Source #

Evaluate a random computation with the given initial generator and return the final generator, discarding the final value.

-     execRandT m g = liftM snd (runRandT m g)

mapRandT :: (m (a, g) -> n (b, g)) -> RandT g m a -> RandT g n b Source #

Map both the return value and final generator of a computation using the given function.

-     runRandT (mapRandT f m) = f . runRandT m

withRandT :: forall g (m :: Type -> Type) a. (g -> g) -> RandT g m a -> RandT g m a Source #

``withRandT` f m` executes action `m` on a generator modified by applying `f`.

-     withRandT f m = modify f >> m

# Lifting other operations

liftCallCC :: CallCC m (a, g) (b, g) -> CallCC (RandT g m) a b Source #

Uniform lifting of a `callCC` operation to the new monad. This version rolls back to the original state on entering the continuation.

liftCallCC' :: CallCC m (a, g) (b, g) -> CallCC (RandT g m) a b Source #

In-situ lifting of a `callCC` operation to the new monad. This version uses the current state on entering the continuation. It does not satisfy the uniformity property (see Control.Monad.Signatures).

liftCatch :: Catch e m (a, g) -> Catch e (RandT g m) a Source #

Lift a `catchE` operation to the new monad.

liftListen :: Monad m => Listen w m (a, g) -> Listen w (RandT g m) a Source #

Lift a `listen` operation to the new monad.

liftPass :: Monad m => Pass w m (a, g) -> Pass w (RandT g m) a Source #

Lift a `pass` operation to the new monad.

evalRandTIO :: MonadIO m => RandT StdGen m a -> m a Source #

Evaluate a random computation that is embedded in the `IO` monad, splitting the global standard generator to get a new one for the computation.

# StatefulGen interface

data RandGen g Source #

A proxy that carries information about the type of generator to use with `RandT` monad and its `StatefulGen` instance.

Since: 0.5.3

Constructors

RandGen |

#### Instances

Instances details

(Monad m, RandomGen g) => RandomGenM (RandGen g) g (RandT g m) Source # | Since: 0.5.3
Instance details Defined in Control.Monad.Trans.Random.Lazy Methods applyRandomGenM :: (g -> (a, g)) -> RandGen g -> RandT g m a Source #
(Monad m, RandomGen g) => RandomGenM (RandGen g) g (RandT g m) Source # | Since: 0.5.3
Instance details Defined in Control.Monad.Trans.Random.Strict Methods applyRandomGenM :: (g -> (a, g)) -> RandGen g -> RandT g m a Source #
(Monad m, RandomGen g) => StatefulGen (RandGen g) (RandT g m) Source # | Since: 0.5.3

Instance details

Defined in Control.Monad.Trans.Random.Lazy

Methods

uniformWord32R :: Word32 -> RandGen g -> RandT g m Word32 Source #

uniformWord64R :: Word64 -> RandGen g -> RandT g m Word64 Source #

uniformWord8 :: RandGen g -> RandT g m Word8 Source #

uniformWord16 :: RandGen g -> RandT g m Word16 Source #

uniformWord32 :: RandGen g -> RandT g m Word32 Source #

uniformWord64 :: RandGen g -> RandT g m Word64 Source #

uniformShortByteString :: Int -> RandGen g -> RandT g m ShortByteString Source #

(Monad m, RandomGen g) => StatefulGen (RandGen g) (RandT g m) Source # | Since: 0.5.3

Instance details

Defined in Control.Monad.Trans.Random.Strict

Methods

uniformWord32R :: Word32 -> RandGen g -> RandT g m Word32 Source #

uniformWord64R :: Word64 -> RandGen g -> RandT g m Word64 Source #

uniformWord8 :: RandGen g -> RandT g m Word8 Source #

uniformWord16 :: RandGen g -> RandT g m Word16 Source #

uniformWord32 :: RandGen g -> RandT g m Word32 Source #

uniformWord64 :: RandGen g -> RandT g m Word64 Source #

uniformShortByteString :: Int -> RandGen g -> RandT g m ShortByteString Source #

withRandGen Source #

Arguments

:: g | initial generator
-> (RandGen g -> RandT g m a) |
-> m (a, g) | return value and final generator

A `RandT` runner that allows using it with `StatefulGen` restricted actions. Returns the outcome of random computation and the new pseudo-random-number generator

    >>> withRandGen (mkStdGen 2021) uniformM :: IO (Int, StdGen)
    (6070831465987696718,StdGen {unStdGen = SMGen 4687568268719557181 4805600293067301895})

Since: 0.5.3

withRandGen_ Source #

Arguments

:: Monad m |
=> g | initial generator
-> (RandGen g -> RandT g m a) |
-> m a | return value and final generator

Same as `withRandGen`, but discards the resulting generator.

    >>> withRandGen_ (mkStdGen 2021) uniformM :: IO Int
    6070831465987696718

Since: 0.5.3

# Examples

## Random monads

The `die` function simulates the roll of a die, picking a number between 1 and 6, inclusive, and returning it in the `Rand` monad transformer. Notice that this code will work with any random number generator `g`.

    die :: (RandomGen g) => Rand g Int
    die = getRandomR (1, 6)

The `dice` function uses `replicate` and `sequence` to simulate the roll of `n` dice.

    dice :: (RandomGen g) => Int -> Rand g [Int]
    dice n = sequence (replicate n die)

To extract a value from the `Rand` monad transformer, we can use `evalRandIO`.

    main = do
      values <- evalRandIO (dice 2)
      putStrLn (show values)