-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Producers for handling randomness.
--   
--   Producers for handling randomness.
@package pipes-random
@version 1.0.0.4


-- | Producers for handling randomness.
--   
--   <h2>Random Numbers</h2>
--   
--   Use functions like <a>uniform</a> and <a>normal</a> to generate
--   endless streams of random numbers of the standard <a>Num</a> types.
--   For instance, you could perform some IO action based on a threshold:
--   
--   <pre>
--   {-# LANGUAGE TypeApplications #-}  -- GHC8 only. Provides the @ syntax.
--   
--   import qualified Pipes.Prelude as P
--   
--   perhaps :: Effect IO ()
--   perhaps = uniform @Float &gt;-&gt; P.filter (&gt; 0.1) &gt;-&gt; lift releaseTheHounds
--   </pre>
--   
--   <h2>Random Elements from Containers</h2>
--   
--   We expose the functions <a>finite</a> and <a>endless</a> for randomly
--   Producing elements from a collection.
--   
--   <a>finite</a> will only Produce until each of its elements have been
--   yielded once. Making a shuffle function then is easy:
--   
--   <pre>
--   import           Data.Vector (Vector)
--   import qualified Pipes.Prelude as P
--   
--   shuffle :: Vector a -&gt; IO [a]
--   shuffle = P.toListM . finite
--   </pre>
--   
--   <a>endless</a> on the other hand will endlessly Produce elements in
--   any order. Repeats will likely appear long before each element has
--   been yielded once. You can limit the number of results with
--   <a>take</a>:
--   
--   <pre>
--   import           Data.Vector (Vector)
--   import qualified Pipes.Prelude as P
--   
--   twenty :: Vector a -&gt; Producer a IO ()
--   twenty v = endless v &gt;-&gt; P.take 20
--   </pre>
--   
--   For the time being, only <a>Vector</a>s (all kinds) are supported.
module Pipes.Random

-- | A pseudo-random number generator, produced using system randomness.
--   
--   <a>lift</a> this to transform it into a <a>Producer</a>.
pool :: IO GenIO

-- | Endlessly produce anything that's <a>Variate</a> from a uniform
--   distribution.
--   
--   <ul>
--   <li>For integral types, the entire bit range is used.</li>
--   <li>For floating types, the range is (0,1], where 0 is specifically
--   excluded.</li>
--   </ul>
uniform :: Variate v => Producer v IO ()

-- | Endlessly produce anything that's <a>Variate</a> from a uniform
--   distribution, within some given range of values.
--   
--   <ul>
--   <li>For integral types, inclusive range is used.</li>
--   <li>For floating types, (a,b] is used.</li>
--   </ul>
uniformR :: Variate v => (v, v) -> Producer v IO ()

-- | Given a mean and a standard deviation, endlessly produce values from a
--   normal (Gaussian) distribution.
normal :: Double -> Double -> Producer Double IO ()

-- | Given some <a>Vector</a>, produce its elements in a random order, once
--   each.
--   
--   <pre>
--   &gt;&gt;&gt; P.toListM $ finite (V.fromList @Data.Vector.Vector ['a'..'z'])
--   "rkzpnwjfeqotvdlsaxiuhcbymg"
--   </pre>
finite :: Vector v a => v a -> Producer a IO ()

-- | Given some <a>Vector</a>, endlessly produce elements from it.
--   
--   <pre>
--   &gt;&gt;&gt; P.toListM $ endless (V.fromList @Data.Vector.Vector ['a'..'z']) &gt;-&gt; P.take 20
--   "nvecotyjhestgrrlganj"
--   </pre>
endless :: Vector v a => v a -> Producer a IO ()
