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


-- | Additional functions for random values.
--   
--   Additional functions for random values, based on random-fu. Inspired
--   by random-shuffle.
@package random-extras
@version 0.10


-- | Additional monadic random functions, based on random-fu.
module Control.Monad.Random.Extras

-- | Shuffle a list randomly. The method is based on Oleg Kiselyov's
--   <i>perfect shuffle</i>
--   <a>http://okmij.org/ftp/Haskell/perfect-shuffle.txt</a>, but much
--   simpler because it uses existing data structures. The efficiency of
--   both methods should be comparable.
--   
--   <i>Complexity:</i> O(n * log n), where <i>n</i> is the length of the
--   input list.
shuffle :: [a] -> RVar [a]

-- | Shuffle a sequence randomly. This is being used by <a>shuffle</a>, so
--   it logically uses the same method.
--   
--   <i>Complexity:</i> O(n * log n), where <i>n</i> is the length of the
--   input sequence.
shuffleSeq :: Seq a -> RVar [a]

-- | Take a random sample from a list.
--   
--   <i>Complexity:</i> O(n + m * log n), where <i>n</i> is the length of
--   the input list and <i>m</i> is the sample size.
sample :: Int -> [a] -> RVar [a]

-- | Take a random sample from a sequence.
--   
--   <i>Complexity:</i> O(m * log n), where <i>n</i> is the length of the
--   input sequence and <i>m</i> is the sample size.
sampleSeq :: Int -> Seq a -> RVar [a]

-- | Randomly choose and extract an element from a list.
--   
--   <i>Complexity:</i> O(n), where <i>n</i> is the length of the input
--   list.
choiceExtract :: [a] -> Maybe (RVar ([a], a))

-- | Randomly choose and extract an element from a sequence.
--   
--   <i>Complexity:</i> O(log n), where <i>n</i> is the length of the input
--   sequence.
choiceExtractSeq :: Seq a -> Maybe (RVar (Seq a, a))

-- | Select a random element from a list.
--   
--   <i>Partial function:</i> This function is only defined on non-empty
--   lists.
--   
--   <i>Complexity:</i> O(n), where <i>n</i> is the length of the input
--   list.
choice :: [a] -> RVar a

-- | Safely select a random element from a list.
--   
--   <i>Complexity:</i> O(n), where <i>n</i> is the length of the input
--   list.
safeChoice :: [a] -> Maybe (RVar a)

-- | Select a random element from a list, traversing the list only once.
--   
--   <i>Partial function:</i> This function is only defined on non-empty
--   lists with a length below (<a>maxBound</a> + 1 :: Int).
--   
--   <i>Complexity:</i> O(n), where <i>n</i> is the length of the input
--   list.
iterativeChoice :: [a] -> RVar a

-- | Select a random element from a sequence.
--   
--   <i>Partial function:</i> This function is only defined on non-empty
--   sequences.
--   
--   <i>Complexity:</i> O(log n), where <i>n</i> is the length of the input
--   sequence.
choiceSeq :: Seq a -> RVar a

-- | Safely select a random element from a sequence.
--   
--   <i>Complexity:</i> O(log n), where <i>n</i> is the length of the input
--   sequence.
safeChoiceSeq :: Seq a -> Maybe (RVar a)

-- | Select a random element from an array.
--   
--   <i>Complexity:</i> O(1).
choiceArray :: (IArray arr a, Ix i, Distribution Uniform i) => arr i a -> RVar a

-- | A stream of random elements from a list.
--   
--   <i>Partial function:</i> This function is only defined on non-empty
--   lists.
--   
--   <i>Complexity:</i> O(n) base and O(1) per element.
choices :: Int -> [a] -> RVar [a]

-- | Safely get a stream of random elements from a list.
--   
--   <i>Complexity:</i> O(n) base and O(1) per element, where <i>n</i> is
--   the length of the input list.
safeChoices :: Int -> [a] -> Maybe (RVar [a])

-- | A stream of random elements from an array.
--   
--   <i>Complexity:</i> O(1) per element.
choicesArray :: (IArray arr a, Ix i, Distribution Uniform i) => Int -> arr i a -> RVar [a]