Skip to content

Commit

Permalink
Merge pull request #151 from haskell/lehins/remove-mwc-example
Browse files Browse the repository at this point in the history
Remove dependency on mwc-random in doctests
  • Loading branch information
lehins authored Oct 29, 2023
2 parents 7ada644 + dcb5bc2 commit 8ae00a0
Show file tree
Hide file tree
Showing 2 changed files with 20 additions and 45 deletions.
1 change: 0 additions & 1 deletion random.cabal
Original file line number Diff line number Diff line change
Expand Up @@ -131,7 +131,6 @@ test-suite doctests
doctest >=0.15 && <0.23
if impl(ghc >= 8.2) && impl(ghc < 8.10)
build-depends:
mwc-random >=0.13 && <0.16,
primitive >=0.6 && <0.8,
random,
stm,
Expand Down
64 changes: 20 additions & 44 deletions src/System/Random/Stateful.hs
Original file line number Diff line number Diff line change
Expand Up @@ -94,7 +94,7 @@ module System.Random.Stateful
-- * Appendix

-- ** How to implement 'StatefulGen'
-- $implementmonadrandom
-- $implemenstatefulegen

-- ** Floating point number caveats #fpcaveats#
-- $floating
Expand Down Expand Up @@ -142,32 +142,28 @@ import System.Random.Internal
-- 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 as follows:
-- 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@](https://hackage.haskell.org/package/mwc-random) as follows:
--
-- >>> :{
-- let rollsM :: StatefulGen g m => Int -> g -> m [Word]
-- rollsM n = replicateM n . uniformRM (1, 6)
-- in do
-- 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 an 'IO' or 'ST' context by
-- applying a monadic adapter like 'AtomicGenM', 'IOGenM' or 'STGenM'
-- (see [monadic-adapters](#monadicadapters)) to the pure pseudo-random number
-- generator.
-- > 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]
--
-- >>> :{
-- let rollsM :: StatefulGen g m => Int -> g -> m [Word]
-- rollsM n = replicateM n . uniformRM (1, 6)
-- pureGen = mkStdGen 42
-- in
-- newIOGenM pureGen >>= rollsM 10 :: IO [Word]
-- :}
-- 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](#monadicadapters)) 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]

-------------------------------------------------------------------------------
Expand All @@ -183,8 +179,8 @@ import System.Random.Internal
--
-- ['StatefulGen': monadic pseudo-random number generators] These generators
-- mutate their own state as they produce pseudo-random values. They
-- generally live in 'ST' or 'IO' or some transformer that implements
-- @PrimMonad@.
-- generally live in 'StateT', 'ST', 'IO' or 'STM' or some other transformer
-- on top of those monads.
--

-------------------------------------------------------------------------------
Expand Down Expand Up @@ -743,7 +739,7 @@ applyTGen f (TGenM tvar) = do
-- and [CPython 3.8](https://github.com/python/cpython/blob/3.8/Lib/random.py#L417)
-- use the same procedure to generate floating point values in a range.
--
-- $implementmonadrandom
-- $implemenstatefulegen
--
-- Typically, a monadic pseudo-random number generator has facilities to save
-- and restore its internal state in addition to generating pseudo-random numbers.
Expand All @@ -756,7 +752,7 @@ applyTGen f (TGenM tvar) = do
-- > uniformWord16 = MWC.uniform
-- > uniformWord32 = MWC.uniform
-- > uniformWord64 = MWC.uniform
-- > uniformShortByteString n g = unsafeSTToPrim (genShortByteStringST n (MWC.uniform g))
-- > uniformShortByteString n g = stToPrim (genShortByteStringST n (MWC.uniform g))
--
-- > instance PrimMonad m => FrozenGen MWC.Seed m where
-- > type MutableGen MWC.Seed m = MWC.Gen (PrimState m)
Expand Down Expand Up @@ -791,12 +787,6 @@ applyTGen f (TGenM tvar) = do
-- >>> print $ runST $ myCustomRandomList (STGen (mkStdGen 217))
-- [-50,-2,4,-8,-58,-40,24,-32,-110,24]
--
-- or a @Seed@ from @mwc-random@:
--
-- >>> import Data.Vector.Primitive as P
-- >>> print $ runST $ myCustomRandomList (MWC.toSeed (P.fromList [1,2,3]))
-- [24,40,10,40,-8,48,-78,70,-12]
--
-- 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
Expand All @@ -812,8 +802,6 @@ applyTGen f (TGenM tvar) = do
-- <https://doi.org/10.1145/2660193.2660195>

-- $setup
-- >>> import Control.Monad.Primitive
-- >>> import qualified System.Random.MWC as MWC
-- >>> writeIORef theStdGen $ mkStdGen 2021
--
-- >>> :set -XFlexibleContexts
Expand All @@ -822,16 +810,4 @@ applyTGen f (TGenM tvar) = do
-- >>> :set -XTypeFamilies
-- >>> :set -XUndecidableInstances
--
-- >>> :{
-- instance (s ~ PrimState m, PrimMonad m) => StatefulGen (MWC.Gen s) m where
-- uniformWord8 = MWC.uniform
-- uniformWord16 = MWC.uniform
-- uniformWord32 = MWC.uniform
-- uniformWord64 = MWC.uniform
-- uniformShortByteString n g = unsafeSTToPrim (genShortByteStringST n (MWC.uniform g))
-- instance PrimMonad m => FrozenGen MWC.Seed m where
-- type MutableGen MWC.Seed m = MWC.Gen (PrimState m)
-- thawGen = MWC.restore
-- freezeGen = MWC.save
-- :}
--

0 comments on commit 8ae00a0

Please sign in to comment.