-- 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 <a>mapM</a> functions.
--   
--   Functions with names ending in ' collect their results into
--   <a>MonadPlus</a> containers. Note that any short-circuit effect that
--   those types' <a>MonadPlus</a> instances may provide in a lazy context
--   (such as the instance for <a>Maybe</a>) 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 <a>mapM</a>, 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 <a>forkMapM</a> but without bothering to keep the return values
forkMapM_ :: (a -> IO b) -> [a] -> IO [Maybe SomeException]

-- | like <a>forkMapM_</a> 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 <a>MonadPlus</a> 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 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 {...}
--   <a>untilM_</a> ...
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 <a>MonadPlus</a> value. Parameters are arranged for infix
--   usage. eg. do {...} <a>untilM_</a> ...
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 {...}
--   <a>untilM_</a> ...
untilM_ :: (Monad m) => m a -> m Bool -> m ()
infixr 0 `untilM_`

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

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

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

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

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

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

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

-- | The supplied <a>Maybe</a> expression will be repeatedly called until
--   it returns <a>Nothing</a>. 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 <a>MonadPlus</a> 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 <a>unfoldr</a>. This is a monad-friendly version of that.
unfoldrM :: (Monad m) => (a -> m (Maybe (b, a))) -> a -> m [b]

-- | See <a>unfoldr</a>. 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
--   (<a>&gt;=&gt;</a>) - 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 <a>and</a> for values of type Monad m =&gt; m Bool
andM :: (Monad m) => [m Bool] -> m Bool

-- | short-circuit <a>or</a> for values of type Monad m =&gt; m Bool
orM :: (Monad m) => [m Bool] -> m Bool

-- | short-circuit <a>any</a> 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 <a>all</a> 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 <a>any</a> with a "monadic predicate".
anyM :: (Monad m) => (a -> m Bool) -> [a] -> m Bool

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

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

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

-- | like <a>dropWhileM</a> 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)
