diff --git a/src/System/Random/Internal.hs b/src/System/Random/Internal.hs index d86fa440..cca4a5f6 100644 --- a/src/System/Random/Internal.hs +++ b/src/System/Random/Internal.hs @@ -139,8 +139,8 @@ import Data.ByteString (ByteString) -- over the network, etc. -- -- Constructor is not exported, becasue it is important for implementation to enforce the --- invariant of the unrelying byte array being of exact same length as the generator has --- specified in `System.Random.Seed.SeedSize`. Used `System.Random.Seed.mkSize` and +-- invariant of the underlying byte array being of the exact same length as the generator has +-- specified in `System.Random.Seed.SeedSize`. Use `System.Random.Seed.mkSize` and -- `System.Random.Seed.unSize` to get access to the raw bytes in a safe manner. -- -- @since 1.3.0 @@ -300,8 +300,6 @@ class RandomGen g => SplitGen g where -- @since 1.3.0 splitGen :: g -> (g, g) - - -- | 'StatefulGen' is an interface to monadic pseudo-random number generators. -- -- @since 1.2.0 diff --git a/src/System/Random/Seed.hs b/src/System/Random/Seed.hs index 97d97354..89a1aa9b 100644 --- a/src/System/Random/Seed.hs +++ b/src/System/Random/Seed.hs @@ -52,17 +52,39 @@ import qualified System.Random.SplitMix32 as SM32 --- | Interface for coverting a pure pseudo-random number generator to and from non-empty --- sequence of bytes/words. Seeds are stored in Little-Endian order regardless of the platform --- it is being used on, which provides inter-platform compatibility, while providing --- optimal performance for most common platforms. +-- | 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 +-- 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 dealing with binary sequence. Whenever a user provides --- functionality for converting to and from a list with `Word64` +-- 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 `unseedGen64` and `seedGen64` respectively. In +-- that case cross-platform support will be handled automaticaly. +-- +-- >>> import Data.Word +-- >>> import Data.List.NonEmpty (NonEmpty ((:|))) +-- >>> newtype OneByteGen = OneByteGen Word8 deriving Show +-- >>> :{ +-- instance SeedGen OneByteGen where +-- type SeedSize OneByteGen = 1 +-- seedGen64 (x :| _) = OneByteGen (fromIntegral x) +-- unseedGen64 (OneByteGen x) = fromIntegral x :| [] +-- :} +-- >>> unseedGen (OneByteGen 0x80) +-- Seed [0x80] +-- >>> unseedGen64 (OneByteGen 0x80) +-- 128 :| [] +-- >>> seedGen (unseedGen (OneByteGen 0x80)) +-- OneByteGen 128 +-- +-- 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 `unseedGen` and `seedGen`. -- -- @since 1.3.0 class (KnownNat (SeedSize g), 1 <= SeedSize g, Typeable g) => SeedGen g where @@ -167,11 +189,11 @@ mkSeed :: forall g m. (SeedGen g, F.MonadFail m) => ByteArray -> m (Seed g) mkSeed ba = do unless (sizeOfByteArray ba == seedSize @g) $ do F.fail $ "Unexpected number of bytes: " - <> show (sizeOfByteArray ba) - <> ". Exactly " - <> show (seedSize @g) - <> " bytes is required by the " - <> show (genTypeName @g) + ++ show (sizeOfByteArray ba) + ++ ". Exactly " + ++ show (seedSize @g) + ++ " bytes is required by the " + ++ show (genTypeName @g) pure $ Seed ba