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

-- | Monadic loops
--   
--   Some useful control operators for looping.
--   
--   New in 0.4: STM loop operators have been split into a new package
--   instead of being conditionally-built.
--   
--   New in 0.3.2.0: various functions for traversing lists and computing
--   minima/maxima using arbitrary procedures to compare or score the
--   elements.
@package monad-loops
@version 0.4.3

-- | A collection of loop operators for use in monads (mostly in stateful
--   ones).
--   
--   There is a general naming pattern for many of these: Functions with
--   names ending in _ discard the results of the loop body as in the
--   standard Prelude mapM functions.
--   
--   Functions with names ending in ' collect their results into
--   MonadPlus containers. Note that any short-circuit effect that
--   those types' MonadPlus instances may provide in a lazy context
--   (such as the instance for Maybe) will _not_ cause execution to
--   short-circuit in these loops.
--   
--   Functions with names ending in neither of those will generally return
--   just plain old lists.
module Control.Monad.Loops

-- | Like mapM, but run all the actions in parallel threads,
--   collecting up the results and returning them all. Does not return
--   until all actions finish.
forkMapM :: (a -> IO b) -> [a] -> IO [Either SomeException b]

-- | like forkMapM but without bothering to keep the return values
forkMapM_ :: (a -> IO b) -> [a] -> IO [Maybe SomeException]

-- | like forkMapM_ but not even bothering to track success or
--   failure of the child threads. Still waits for them all though.
forkMapM__ :: (a -> IO b) -> [a] -> IO ()

-- | Execute an action repeatedly as long as the given boolean expression
--   returns True. The condition is evaluated before the loop body.
--   Collects the results into a list.
whileM :: Monad m => m Bool -> m a -> m [a]

-- | Execute an action repeatedly as long as the given boolean expression
--   returns True. The condition is evaluated before the loop body.
--   Collects the results into an arbitrary MonadPlus value.
whileM' :: (Monad m, MonadPlus f) => m Bool -> m a -> m (f a)

-- | Execute an action repeatedly as long as the given boolean expression
--   returns True. The condition is evaluated before the loop body.
--   Discards results.
whileM_ :: Monad m => m Bool -> m a -> m ()

-- | Execute an action repeatedly until its result fails to satisfy a
--   predicate, and return that result (discarding all others).
iterateWhile :: Monad m => (a -> Bool) -> m a -> m a

-- | Execute an action repeatedly until its result satisfies a predicate,
--   and return that result (discarding all others).
iterateUntil :: Monad m => (a -> Bool) -> m a -> m a

-- | Execute an action forever, feeding the result of each execution as the
--   input to the next.
iterateM_ :: Monad m => (a -> m a) -> a -> m b

-- | Execute an action repeatedly until the condition expression returns
--   True. The condition is evaluated after the loop body. Collects results
--   into a list. Parameters are arranged for infix usage. eg. do {...}
--   untilM_ ...
untilM :: Monad m => m a -> m Bool -> m [a]
infixr 0 `untilM`

-- | Execute an action repeatedly until the condition expression returns
--   True. The condition is evaluated after the loop body. Collects results
--   into a MonadPlus value. Parameters are arranged for infix
--   usage. eg. do {...} untilM_ ...
untilM' :: (Monad m, MonadPlus f) => m a -> m Bool -> m (f a)
infixr 0 `untilM'`

-- | Execute an action repeatedly until the condition expression returns
--   True. The condition is evaluated after the loop body. Discards
--   results. Parameters are arranged for infix usage. eg. do {...}
--   untilM_ ...
untilM_ :: Monad m => m a -> m Bool -> m ()
infixr 0 `untilM_`

-- | Analogue of (until) Yields the result of applying f
--   until p holds.
iterateUntilM :: Monad m => (a -> Bool) -> (a -> m a) -> a -> m a
infixr 0 `iterateUntilM`

-- | As long as the supplied Maybe expression returns "Just _", the
--   loop body will be called and passed the value contained in the
--   Just. Results are collected into a list.
whileJust :: Monad m => m (Maybe a) -> (a -> m b) -> m [b]

-- | As long as the supplied Maybe expression returns "Just _", the
--   loop body will be called and passed the value contained in the
--   Just. Results are collected into an arbitrary MonadPlus
--   container.
whileJust' :: (Monad m, MonadPlus f) => m (Maybe a) -> (a -> m b) -> m (f b)

-- | As long as the supplied Maybe expression returns "Just _", the
--   loop body will be called and passed the value contained in the
--   Just. Results are discarded.
whileJust_ :: Monad m => m (Maybe a) -> (a -> m b) -> m ()

-- | Run the supplied Maybe computation repeatedly until it returns
--   a value. Returns that value.
untilJust :: Monad m => m (Maybe a) -> m a

-- | The supplied Maybe expression will be repeatedly called until
--   it returns Nothing. All values returned are collected into a
--   list.
unfoldM :: Monad m => m (Maybe a) -> m [a]

-- | The supplied Maybe expression will be repeatedly called until
--   it returns Nothing. All values returned are collected into an
--   arbitrary MonadPlus thing.
unfoldM' :: (Monad m, MonadPlus f) => m (Maybe a) -> m (f a)

-- | The supplied Maybe expression will be repeatedly called until
--   it returns Nothing. All values returned are discarded.
unfoldM_ :: Monad m => m (Maybe a) -> m ()

-- | Repeatedly evaluates the second argument until the value satisfies the
--   given predicate, and returns a list of all values that satisfied the
--   predicate. Discards the final one (which failed the predicate).
unfoldWhileM :: Monad m => (a -> Bool) -> m a -> m [a]

-- | Repeatedly evaluates the second argument until the value satisfies the
--   given predicate, and returns a MonadPlus collection of all
--   values that satisfied the predicate. Discards the final one (which
--   failed the predicate).
unfoldWhileM' :: (Monad m, MonadPlus f) => (a -> Bool) -> m a -> m (f a)

-- | See unfoldr. This is a monad-friendly version of that.
unfoldrM :: Monad m => (a -> m (Maybe (b, a))) -> a -> m [b]

-- | See unfoldr. This is a monad-friendly version of that, with a
--   twist. Rather than returning a list, it returns any MonadPlus type of
--   your choice.
unfoldrM' :: (Monad m, MonadPlus f) => (a -> m (Maybe (b, a))) -> a -> m (f b)

-- | Compose a list of monadic actions into one action. Composes using
--   (>=>) - that is, the output of each action is fed to the
--   input of the one after it in the list.
concatM :: Monad m => [a -> m a] -> a -> m a

-- | short-circuit and for values of type Monad m => m Bool
andM :: Monad m => [m Bool] -> m Bool

-- | short-circuit or for values of type Monad m => m Bool
orM :: Monad m => [m Bool] -> m Bool

-- | short-circuit any with a list of "monadic predicates". Tests
--   the value presented against each predicate in turn until one passes,
--   then returns True without any further processing. If none passes,
--   returns False.
anyPM :: Monad m => [a -> m Bool] -> a -> m Bool

-- | short-circuit all with a list of "monadic predicates". Tests
--   the value presented against each predicate in turn until one fails,
--   then returns False. if none fail, returns True.
allPM :: Monad m => [a -> m Bool] -> a -> m Bool

-- | short-circuit any with a "monadic predicate".
anyM :: Monad m => (a -> m Bool) -> [a] -> m Bool

-- | short-circuit all with a "monadic predicate".
allM :: Monad m => (a -> m Bool) -> [a] -> m Bool

-- | Monadic takeWhile.
takeWhileM :: Monad m => (a -> m Bool) -> [a] -> m [a]

-- | Monadic dropWhile.
dropWhileM :: Monad m => (a -> m Bool) -> [a] -> m [a]

-- | like dropWhileM but trims both ends of the list.
trimM :: Monad m => (a -> m Bool) -> [a] -> m [a]

-- | return the first value from a list, if any, satisfying the given
--   predicate.
firstM :: Monad m => (a -> m Bool) -> [a] -> m (Maybe a)
minimaOnByM :: Monad m => (a -> m b) -> (b -> b -> m Ordering) -> [a] -> m [a]
maximaOnByM :: Monad m => (a -> m b) -> (b -> b -> m Ordering) -> [a] -> m [a]
minimaByM :: Monad m => (a -> a -> m Ordering) -> [a] -> m [a]
maximaByM :: Monad m => (a -> a -> m Ordering) -> [a] -> m [a]
minimaOnM :: (Monad m, Ord b) => (a -> m b) -> [a] -> m [a]
maximaOnM :: (Monad m, Ord b) => (a -> m b) -> [a] -> m [a]
minimumOnByM :: Monad m => (a -> m b) -> (b -> b -> m Ordering) -> [a] -> m (Maybe a)
maximumOnByM :: Monad m => (a -> m b) -> (b -> b -> m Ordering) -> [a] -> m (Maybe a)
minimumByM :: Monad m => (a -> a -> m Ordering) -> [a] -> m (Maybe a)
maximumByM :: Monad m => (a -> a -> m Ordering) -> [a] -> m (Maybe a)
minimumOnM :: (Monad m, Ord b) => (a -> m b) -> [a] -> m (Maybe a)
maximumOnM :: (Monad m, Ord b) => (a -> m b) -> [a] -> m (Maybe a)
