-- 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.4
-- | Additional monadic random functions, based on MonadRandom.
module Control.Monad.Random.Extras
-- | Shuffle a list randomly. The method is based on Oleg Kiselyov's
-- perfect shuffle
-- http://okmij.org/ftp/Haskell/perfect-shuffle.txt, but much
-- simpler because it uses existing data structures. The efficiency of
-- both methods should be comparable.
--
-- Complexity: O(n * log n), where n is the length of the
-- input list.
shuffle :: (MonadRandom m) => [a] -> m [a]
-- | Shuffle a sequence randomly. This is being used by shuffle, so
-- it logically uses the same method.
--
-- Complexity: O(n * log n), where n is the length of the
-- input sequence.
shuffleSeq :: (MonadRandom m) => Seq a -> m [a]
-- | Take a random sample from a list.
--
-- Complexity: O(n + m * log n), where n is the length of
-- the input list and m is the sample size.
sample :: (MonadRandom m) => Int -> [a] -> m [a]
-- | Take a random sample from a sequence.
--
-- Complexity: O(m * log n), where n is the length of the
-- input sequence and m is the sample size.
sampleSeq :: (MonadRandom m) => Int -> Seq a -> m [a]
-- | Randomly choose and extract an element from a list.
--
-- Complexity: O(n), where n is the length of the input
-- list.
choiceExtract :: (MonadRandom m) => [a] -> m (Maybe ([a], a))
-- | Randomly choose and extract an element from a sequence.
--
-- Complexity: O(log n), where n is the length of the input
-- sequence.
choiceExtractSeq :: (MonadRandom m) => Seq a -> m (Maybe (Seq a, a))
-- | Select a random element from a list.
--
-- Partial function: This function is only defined on non-empty
-- lists.
--
-- Complexity: O(n), where n is the length of the input
-- list.
choice :: (MonadRandom m) => [a] -> m a
-- | Safely select a random element from a list.
--
-- Complexity: O(n), where n is the length of the input
-- list.
safeChoice :: (MonadRandom m) => [a] -> Maybe (m a)
-- | Select a random element from a list, traversing the list only once.
--
-- Partial function: This function is only defined on non-empty
-- lists with a length below (maxBound + 1 :: Int).
--
-- Complexity: O(n), where n is the length of the input
-- list.
iterativeChoice :: (MonadRandom m) => [a] -> m a
-- | Select a random element from a sequence.
--
-- Partial function: This function is only defined on non-empty
-- sequences.
--
-- Complexity: O(log n), where n is the length of the input
-- sequence.
choiceSeq :: (MonadRandom m) => Seq a -> m a
-- | Safely select a random element from a sequence.
--
-- Complexity: O(log n), where n is the length of the input
-- sequence.
safeChoiceSeq :: (MonadRandom m) => Seq a -> Maybe (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
-- | A stream of random elements from a list.
--
-- Partial function: This function is only defined on non-empty
-- lists.
--
-- Complexity: O(n) base and O(1) per element.
choices :: (MonadRandom m) => [a] -> m [a]
-- | Safely get a stream of random elements from a list.
--
-- Complexity: O(n) base and O(1) per element, where n is
-- the length of the input list.
safeChoices :: (MonadRandom m) => [a] -> Maybe (m [a])
-- | A stream of random elements from an array.
--
-- Complexity: O(1) per element.
choicesArray :: (MonadRandom m, IArray arr a, Ix i, Random i) => arr i a -> m [a]