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


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


-- | Additional monadic random functions, based on <a>MonadRandom</a>.
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.
--   
--   Complexity: O(n * log n)
shuffle :: (MonadRandom m) => [a] -> m [a]

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

-- | Take a random sample from a list.
--   
--   Complexity: O(n + m * log n)
sample :: (MonadRandom m) => Int -> [a] -> m [a]

-- | Take a random sample from a sequence.
--   
--   Complexity: O(m * log n)
sampleSeq :: (MonadRandom m) => Int -> Seq a -> m [a]

-- | Randomly choose and extract an element from a list.
--   
--   Complexity: O(n)
choiceExtract :: (MonadRandom m) => [a] -> m (Maybe ([a], a))

-- | Randomly choose and extract an element from a sequence.
--   
--   Complexity: O(log n)
choiceExtractSeq :: (MonadRandom m) => Seq a -> m (Maybe (Seq a, a))

-- | Select a random element from a list.
--   
--   Complexity: O(n).
choice :: (MonadRandom m) => [a] -> m a

-- | Select a random element from a sequence.
--   
--   Complexity: O(log n).
choiceSeq :: (MonadRandom m) => Seq a -> m a

-- | Select a random element from an array.
--   
--   Complexity: O(1).
choiceArray :: (MonadRandom m, IArray arr a, Ix i, Random i) => arr i a -> m a

-- | Select <i>m</i> random elements from a list.
--   
--   Complexity: O(m)
choices :: (MonadRandom m) => Int -> [a] -> m [a]

-- | Select <i>m</i> random elements from an array.
--   
--   Complexity: O(m)
choicesArray :: (MonadRandom m, IArray arr a, Ix i, Random i) => Int -> arr i a -> m [a]