-- 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.1


-- | 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, MonadPlus f) => Seq a -> m (f 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 (a, Seq 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