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


-- | Custom prelude used in Serokell
--   
--   See README.md file for more details.
@package universum
@version 1.1.1


-- | Convenient utils to work with <a>Applicative</a>. There were more
--   functions in this module (see <a>protolude version</a>) but only
--   convenient ans most used are left.
module Universum.Applicative

-- | Shorter alias for <tt>pure ()</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; pass :: Maybe ()
--   Just ()
--   </pre>
pass :: Applicative f => f ()


-- | Reexports from <tt>GHC.*</tt> modules of <a>base</a> package.
module Universum.Base

-- | Type representing arbitrary-precision non-negative integers.
--   
--   Operations whose result would be negative <tt><tt>throw</tt>
--   (<tt>Underflow</tt> :: <tt>ArithException</tt>)</tt>.
data Natural :: *

-- | The kind of types with values. For example <tt>Int :: Type</tt>.
type Type = *

-- | Stricter version of <a>$</a> operator. Default Prelude defines this at
--   the toplevel module, so we do as well.
--   
--   <pre>
--   &gt;&gt;&gt; const 3 $ Prelude.undefined
--   3
--   
--   &gt;&gt;&gt; const 3 $! Prelude.undefined
--   *** Exception: Prelude.undefined
--   CallStack (from HasCallStack):
--     error, called at libraries/base/GHC/Err.hs:79:14 in base:GHC.Err
--   ...
--   </pre>
($!) :: (a -> b) -> a -> b
infixr 0 $!


-- | This module reexports functions to work with <a>Bool</a> type.
module Universum.Bool.Reexport


-- | This module reexports all container related stuff from
--   <tt>Prelude</tt>.
module Universum.Container.Reexport


-- | This module reexports very basic and primitive functions and function
--   combinators.
module Universum.Function

-- | Renamed version of <a>id</a>.
identity :: a -> a


-- | This module reexports functionality regarding <a>Functor</a> type
--   class.
module Universum.Functor.Reexport


-- | This module contains useful functions to work with <a>Functor</a> type
--   class.
module Universum.Functor.Fmap

-- | <a>map</a> generalized to <a>Functor</a>.
--   
--   <pre>
--   &gt;&gt;&gt; map not (Just True)
--   Just False
--   
--   &gt;&gt;&gt; map not [True,False,True,True]
--   [False,True,False,False]
--   </pre>
map :: Functor f => (a -> b) -> f a -> f b

-- | Alias for <tt>fmap . fmap</tt>. Convenient to work with two nested
--   <a>Functor</a>s.
--   
--   <pre>
--   &gt;&gt;&gt; negate &lt;&lt;$&gt;&gt; Just [1,2,3]
--   Just [-1,-2,-3]
--   </pre>
(<<$>>) :: (Functor f, Functor g) => (a -> b) -> f (g a) -> f (g b)
infixl 4 <<$>>


-- | Convenient functions to work with <a>Functor</a>.
module Universum.Functor


-- | Concurrency useful and common functions.
module Universum.Lifted.Concurrent

-- | An <a>MVar</a> (pronounced "em-var") is a synchronising variable, used
--   for communication between concurrent threads. It can be thought of as
--   a a box, which may be empty or full.
data MVar a :: * -> *

-- | Lifted to <a>MonadIO</a> version of <a>newEmptyMVar</a>.
newEmptyMVar :: MonadIO m => m (MVar a)

-- | Lifted to <a>MonadIO</a> version of <a>newMVar</a>.
newMVar :: MonadIO m => a -> m (MVar a)

-- | Lifted to <a>MonadIO</a> version of <a>putMVar</a>.
putMVar :: MonadIO m => MVar a -> a -> m ()

-- | Lifted to <a>MonadIO</a> version of <a>readMVar</a>.
readMVar :: MonadIO m => MVar a -> m a

-- | Lifted to <a>MonadIO</a> version of <a>swapMVar</a>.
swapMVar :: MonadIO m => MVar a -> a -> m a

-- | Lifted to <a>MonadIO</a> version of <a>takeMVar</a>.
takeMVar :: MonadIO m => MVar a -> m a

-- | Lifted to <a>MonadIO</a> version of <a>tryPutMVar</a>.
tryPutMVar :: MonadIO m => MVar a -> a -> m Bool

-- | Lifted to <a>MonadIO</a> version of <a>tryReadMVar</a>.
tryReadMVar :: MonadIO m => MVar a -> m (Maybe a)

-- | Lifted to <a>MonadIO</a> version of <a>tryTakeMVar</a>.
tryTakeMVar :: MonadIO m => MVar a -> m (Maybe a)

-- | A monad supporting atomic memory transactions.
data STM a :: * -> *

-- | Shared memory locations that support atomic memory transactions.
data TVar a :: * -> *

-- | Lifted to <a>MonadIO</a> version of <a>atomically</a>.
atomically :: MonadIO m => STM a -> m a

-- | Lifted to <a>MonadIO</a> version of <a>newTVarIO</a>.
newTVarIO :: MonadIO m => a -> m (TVar a)

-- | Lifted to <a>MonadIO</a> version of <a>readTVarIO</a>.
readTVarIO :: MonadIO m => TVar a -> m a

-- | Strict version of <a>modifyTVar</a>.
modifyTVar' :: () => TVar a -> (a -> a) -> STM ()

-- | Create a new TVar holding a value supplied
newTVar :: () => a -> STM TVar a

-- | Return the current value stored in a TVar
readTVar :: () => TVar a -> STM a

-- | Write the supplied value into a TVar
writeTVar :: () => TVar a -> a -> STM ()


-- | Lifted versions of functions that work with environment.
module Universum.Lifted.Env

-- | Lifted version of <a>getArgs</a>.
getArgs :: MonadIO m => m [String]

-- | Lifted version of <a>exitWith</a>.
exitWith :: MonadIO m => ExitCode -> m a

-- | Lifted version of <a>exitFailure</a>.
exitFailure :: MonadIO m => m a

-- | Lifted version of <a>exitSuccess</a>.
exitSuccess :: MonadIO m => m a

-- | Lifted version of <a>die</a>. <a>die</a> is available since base-4.8,
--   but it's more convenient to redefine it instead of using CPP.
die :: MonadIO m => String -> m ()


-- | Lifted versions of functions working with files and common IO. All
--   functions are specialized to <a>Text</a>.
module Universum.Lifted.File

-- | Lifted version of <a>appendFile</a>.
appendFile :: MonadIO m => FilePath -> Text -> m ()

-- | Lifted version of <a>getContents</a>.
getContents :: MonadIO m => m Text

-- | Lifted version of <a>getLine</a>.
getLine :: MonadIO m => m Text

-- | Lifted version of <a>interact</a>.
interact :: MonadIO m => (Text -> Text) -> m ()

-- | Lifted version of <a>openFile</a>.
openFile :: MonadIO m => FilePath -> IOMode -> m Handle

-- | Lifted version of <a>readFile</a>.
readFile :: MonadIO m => FilePath -> m Text

-- | Lifted version of <a>writeFile</a>.
writeFile :: MonadIO m => FilePath -> Text -> m ()


-- | Lifted reexports from <a>IORef</a> module.
module Universum.Lifted.IORef

-- | A mutable variable in the <a>IO</a> monad
data IORef a :: * -> *

-- | Lifted version of <a>atomicModifyIORef</a>.
atomicModifyIORef :: MonadIO m => IORef a -> (a -> (a, b)) -> m b

-- | Lifted version of <a>atomicModifyIORef'</a>.
atomicModifyIORef' :: MonadIO m => IORef a -> (a -> (a, b)) -> m b

-- | Lifted version of <a>atomicWriteIORef</a>.
atomicWriteIORef :: MonadIO m => IORef a -> a -> m ()

-- | Lifted version of <a>modifyIORef</a>.
modifyIORef :: MonadIO m => IORef a -> (a -> a) -> m ()

-- | Lifted version of <a>modifyIORef'</a>.
modifyIORef' :: MonadIO m => IORef a -> (a -> a) -> m ()

-- | Lifted version of <a>newIORef</a>.
newIORef :: MonadIO m => a -> m (IORef a)

-- | Lifted version of <a>readIORef</a>.
readIORef :: MonadIO m => IORef a -> m a

-- | Lifted version of <a>writeIORef</a>.
writeIORef :: MonadIO m => IORef a -> a -> m ()


-- | This module contains lifted version of <a>stToIO</a> function.
module Universum.Lifted.ST

-- | Lifted version of <a>stToIO</a>.
stToIO :: MonadIO m => ST RealWorld a -> m a


-- | Lifted versions of base functions.
module Universum.Lifted


-- | This module reexports functinons to work with list, <a>NonEmpty</a>
--   and String types.
module Universum.List.Reexport


-- | This module reexports functions to work with monads.
module Universum.Monad.Reexport

-- | The <a>Monad</a> class defines the basic operations over a
--   <i>monad</i>, a concept from a branch of mathematics known as
--   <i>category theory</i>. From the perspective of a Haskell programmer,
--   however, it is best to think of a monad as an <i>abstract datatype</i>
--   of actions. Haskell's <tt>do</tt> expressions provide a convenient
--   syntax for writing monadic expressions.
--   
--   Instances of <a>Monad</a> should satisfy the following laws:
--   
--   <ul>
--   <li><pre><a>return</a> a <a>&gt;&gt;=</a> k = k a</pre></li>
--   <li><pre>m <a>&gt;&gt;=</a> <a>return</a> = m</pre></li>
--   <li><pre>m <a>&gt;&gt;=</a> (\x -&gt; k x <a>&gt;&gt;=</a> h) = (m
--   <a>&gt;&gt;=</a> k) <a>&gt;&gt;=</a> h</pre></li>
--   </ul>
--   
--   Furthermore, the <a>Monad</a> and <a>Applicative</a> operations should
--   relate as follows:
--   
--   <ul>
--   <li><pre><a>pure</a> = <a>return</a></pre></li>
--   <li><pre>(<a>&lt;*&gt;</a>) = <a>ap</a></pre></li>
--   </ul>
--   
--   The above laws imply:
--   
--   <ul>
--   <li><pre><a>fmap</a> f xs = xs <a>&gt;&gt;=</a> <a>return</a> .
--   f</pre></li>
--   <li><pre>(<a>&gt;&gt;</a>) = (<a>*&gt;</a>)</pre></li>
--   </ul>
--   
--   and that <a>pure</a> and (<a>&lt;*&gt;</a>) satisfy the applicative
--   functor laws.
--   
--   The instances of <a>Monad</a> for lists, <a>Maybe</a> and <a>IO</a>
--   defined in the <a>Prelude</a> satisfy these laws.
class Applicative m => Monad (m :: * -> *)

-- | Sequentially compose two actions, passing any value produced by the
--   first as an argument to the second.
(>>=) :: Monad m => m a -> (a -> m b) -> m b

-- | Sequentially compose two actions, discarding any value produced by the
--   first, like sequencing operators (such as the semicolon) in imperative
--   languages.
(>>) :: Monad m => m a -> m b -> m b

-- | Inject a value into the monadic type.
return :: Monad m => a -> m a

-- | When a value is bound in <tt>do</tt>-notation, the pattern on the left
--   hand side of <tt>&lt;-</tt> might not match. In this case, this class
--   provides a function to recover.
--   
--   A <a>Monad</a> without a <a>MonadFail</a> instance may only be used in
--   conjunction with pattern that always match, such as newtypes, tuples,
--   data types with only a single data constructor, and irrefutable
--   patterns (<tt>~pat</tt>).
--   
--   Instances of <a>MonadFail</a> should satisfy the following law:
--   <tt>fail s</tt> should be a left zero for <tt>&gt;&gt;=</tt>,
--   
--   <pre>
--   fail s &gt;&gt;= f  =  fail s
--   </pre>
--   
--   If your <a>Monad</a> is also <tt>MonadPlus</tt>, a popular definition
--   is
--   
--   <pre>
--   fail _ = mzero
--   </pre>
class Monad m => MonadFail (m :: * -> *)
fail :: MonadFail m => String -> m a

-- | Monads that also support choice and failure.
class (Alternative m, Monad m) => MonadPlus (m :: * -> *)

-- | the identity of <a>mplus</a>. It should also satisfy the equations
--   
--   <pre>
--   mzero &gt;&gt;= f  =  mzero
--   v &gt;&gt; mzero   =  mzero
--   </pre>
mzero :: MonadPlus m => m a

-- | an associative operation
mplus :: MonadPlus m => m a -> m a -> m a

-- | Same as <a>&gt;&gt;=</a>, but with the arguments interchanged.
(=<<) :: Monad m => (a -> m b) -> m a -> m b
infixr 1 =<<

-- | Left-to-right Kleisli composition of monads.
(>=>) :: Monad m => (a -> m b) -> (b -> m c) -> a -> m c
infixr 1 >=>

-- | Right-to-left Kleisli composition of monads.
--   <tt>(<a>&gt;=&gt;</a>)</tt>, with the arguments flipped.
--   
--   Note how this operator resembles function composition
--   <tt>(<a>.</a>)</tt>:
--   
--   <pre>
--   (.)   ::            (b -&gt;   c) -&gt; (a -&gt;   b) -&gt; a -&gt;   c
--   (&lt;=&lt;) :: Monad m =&gt; (b -&gt; m c) -&gt; (a -&gt; m b) -&gt; a -&gt; m c
--   </pre>
(<=<) :: Monad m => (b -> m c) -> (a -> m b) -> a -> m c
infixr 1 <=<

-- | <tt><a>forever</a> act</tt> repeats the action infinitely.
forever :: Applicative f => f a -> f b

-- | The <a>join</a> function is the conventional monad join operator. It
--   is used to remove one level of monadic structure, projecting its bound
--   argument into the outer level.
join :: Monad m => m m a -> m a

-- | Direct <a>MonadPlus</a> equivalent of <tt>filter</tt>
--   <tt><tt>filter</tt></tt> = <tt>(mfilter:: (a -&gt; Bool) -&gt; [a]
--   -&gt; [a]</tt> applicable to any <a>MonadPlus</a>, for example
--   <tt>mfilter odd (Just 1) == Just 1</tt> <tt>mfilter odd (Just 2) ==
--   Nothing</tt>
mfilter :: MonadPlus m => (a -> Bool) -> m a -> m a

-- | This generalizes the list-based <tt>filter</tt> function.
filterM :: Applicative m => (a -> m Bool) -> [a] -> m [a]

-- | The <a>mapAndUnzipM</a> function maps its first argument over a list,
--   returning the result as a pair of lists. This function is mainly used
--   with complicated data structures or a state-transforming monad.
mapAndUnzipM :: Applicative m => (a -> m (b, c)) -> [a] -> m ([b], [c])

-- | The <a>zipWithM</a> function generalizes <a>zipWith</a> to arbitrary
--   applicative functors.
zipWithM :: Applicative m => (a -> b -> m c) -> [a] -> [b] -> m [c]

-- | <a>zipWithM_</a> is the extension of <a>zipWithM</a> which ignores the
--   final result.
zipWithM_ :: Applicative m => (a -> b -> m c) -> [a] -> [b] -> m ()

-- | The <a>foldM</a> function is analogous to <tt>foldl</tt>, except that
--   its result is encapsulated in a monad. Note that <a>foldM</a> works
--   from left-to-right over the list arguments. This could be an issue
--   where <tt>(<a>&gt;&gt;</a>)</tt> and the `folded function' are not
--   commutative.
--   
--   <pre>
--   foldM f a1 [x1, x2, ..., xm]
--   </pre>
--   
--   ==
--   
--   <pre>
--   do
--     a2 &lt;- f a1 x1
--     a3 &lt;- f a2 x2
--     ...
--     f am xm
--   </pre>
--   
--   If right-to-left evaluation is required, the input list should be
--   reversed.
--   
--   Note: <a>foldM</a> is the same as <a>foldlM</a>
foldM :: (Foldable t, Monad m) => (b -> a -> m b) -> b -> t a -> m b

-- | Like <a>foldM</a>, but discards the result.
foldM_ :: (Foldable t, Monad m) => (b -> a -> m b) -> b -> t a -> m ()

-- | <tt><a>replicateM</a> n act</tt> performs the action <tt>n</tt> times,
--   gathering the results.
replicateM :: Applicative m => Int -> m a -> m [a]

-- | Like <a>replicateM</a>, but discards the result.
replicateM_ :: Applicative m => Int -> m a -> m ()

-- | Promote a function to a monad, scanning the monadic arguments from
--   left to right. For example,
--   
--   <pre>
--   liftM2 (+) [0,1] [0,2] = [0,2,1,3]
--   liftM2 (+) (Just 1) Nothing = Nothing
--   </pre>
liftM2 :: Monad m => (a1 -> a2 -> r) -> m a1 -> m a2 -> m r

-- | Promote a function to a monad, scanning the monadic arguments from
--   left to right (cf. <a>liftM2</a>).
liftM3 :: Monad m => (a1 -> a2 -> a3 -> r) -> m a1 -> m a2 -> m a3 -> m r

-- | Promote a function to a monad, scanning the monadic arguments from
--   left to right (cf. <a>liftM2</a>).
liftM4 :: Monad m => (a1 -> a2 -> a3 -> a4 -> r) -> m a1 -> m a2 -> m a3 -> m a4 -> m r

-- | Promote a function to a monad, scanning the monadic arguments from
--   left to right (cf. <a>liftM2</a>).
liftM5 :: Monad m => (a1 -> a2 -> a3 -> a4 -> a5 -> r) -> m a1 -> m a2 -> m a3 -> m a4 -> m a5 -> m r

-- | In many situations, the <a>liftM</a> operations can be replaced by
--   uses of <a>ap</a>, which promotes function application.
--   
--   <pre>
--   return f `ap` x1 `ap` ... `ap` xn
--   </pre>
--   
--   is equivalent to
--   
--   <pre>
--   liftMn f x1 x2 ... xn
--   </pre>
ap :: Monad m => m (a -> b) -> m a -> m b

-- | Strict version of <a>&lt;$&gt;</a>.
(<$!>) :: Monad m => (a -> b) -> m a -> m b
infixl 4 <$!>


-- | Utility functions to work with <a>Maybe</a> data type as monad.
module Universum.Monad.Maybe

-- | Similar to <a>fromMaybe</a> but with flipped arguments.
--   
--   <pre>
--   &gt;&gt;&gt; readMaybe "True" ?: False
--   True
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; readMaybe "Tru" ?: False
--   False
--   </pre>
(?:) :: Maybe a -> a -> a
infixr 0 ?:

-- | Specialized version of <tt>for_</tt> for <a>Maybe</a>. It's used for
--   code readability. Also helps to avoid space leaks: <a>Foldable.mapM_
--   space leak</a>.
--   
--   <pre>
--   &gt;&gt;&gt; whenJust Nothing $ \b -&gt; print (not b)
--   
--   &gt;&gt;&gt; whenJust (Just True) $ \b -&gt; print (not b)
--   False
--   </pre>
whenJust :: Applicative f => Maybe a -> (a -> f ()) -> f ()

-- | Monadic version of <a>whenJust</a>.
whenJustM :: Monad m => m (Maybe a) -> (a -> m ()) -> m ()

-- | Performs default <a>Applicative</a> action if <a>Nothing</a> is given.
--   Otherwise returns content of <a>Just</a> pured to <a>Applicative</a>.
--   
--   <pre>
--   &gt;&gt;&gt; whenNothing Nothing [True, False]
--   [True,False]
--   
--   &gt;&gt;&gt; whenNothing (Just True) [True, False]
--   [True]
--   </pre>
whenNothing :: Applicative f => Maybe a -> f a -> f a

-- | Performs default <a>Applicative</a> action if <a>Nothing</a> is given.
--   Do nothing for <a>Just</a>. Convenient for discarding <a>Just</a>
--   content.
--   
--   <pre>
--   &gt;&gt;&gt; whenNothing_ Nothing $ putTextLn "Nothing!"
--   Nothing!
--   
--   &gt;&gt;&gt; whenNothing_ (Just True) $ putTextLn "Nothing!"
--   </pre>
whenNothing_ :: Applicative f => Maybe a -> f () -> f ()

-- | Monadic version of <a>whenNothing</a>.
whenNothingM :: Monad m => m (Maybe a) -> m a -> m a

-- | Monadic version of <a>whenNothingM_</a>.
whenNothingM_ :: Monad m => m (Maybe a) -> m () -> m ()


-- | Utilites to work with <tt>Either</tt> data type.
module Universum.Monad.Either

-- | Extracts value from <a>Left</a> or return given default value.
--   
--   <pre>
--   &gt;&gt;&gt; fromLeft 0 (Left 3)
--   3
--   
--   &gt;&gt;&gt; fromLeft 0 (Right 5)
--   0
--   </pre>
fromLeft :: a -> Either a b -> a

-- | Extracts value from <a>Right</a> or return given default value.
--   
--   <pre>
--   &gt;&gt;&gt; fromRight 0 (Left 3)
--   0
--   
--   &gt;&gt;&gt; fromRight 0 (Right 5)
--   5
--   </pre>
fromRight :: b -> Either a b -> b

-- | Maps <a>Maybe</a> to <a>Either</a> wrapping default value into
--   <a>Right</a>.
--   
--   <pre>
--   &gt;&gt;&gt; maybeToLeft True (Just "aba")
--   Left "aba"
--   
--   &gt;&gt;&gt; maybeToLeft True Nothing
--   Right True
--   </pre>
maybeToLeft :: r -> Maybe l -> Either l r

-- | Maps <a>Maybe</a> to <a>Either</a> wrapping default value into
--   <a>Left</a>.
--   
--   <pre>
--   &gt;&gt;&gt; maybeToRight True (Just "aba")
--   Right "aba"
--   
--   &gt;&gt;&gt; maybeToRight True Nothing
--   Left True
--   </pre>
maybeToRight :: l -> Maybe r -> Either l r

-- | Maps left part of <a>Either</a> to <a>Maybe</a>.
--   
--   <pre>
--   &gt;&gt;&gt; leftToMaybe (Left True)
--   Just True
--   
--   &gt;&gt;&gt; leftToMaybe (Right "aba")
--   Nothing
--   </pre>
leftToMaybe :: Either l r -> Maybe l

-- | Maps right part of <a>Either</a> to <a>Maybe</a>.
--   
--   <pre>
--   &gt;&gt;&gt; rightToMaybe (Left True)
--   Nothing
--   
--   &gt;&gt;&gt; rightToMaybe (Right "aba")
--   Just "aba"
--   </pre>
rightToMaybe :: Either l r -> Maybe r

-- | Applies given action to <a>Either</a> content if <a>Left</a> is given.
whenLeft :: Applicative f => Either l r -> (l -> f ()) -> f ()

-- | Monadic version of <a>whenLeft</a>.
whenLeftM :: Monad m => m (Either l r) -> (l -> m ()) -> m ()

-- | Applies given action to <a>Either</a> content if <a>Right</a> is
--   given.
whenRight :: Applicative f => Either l r -> (r -> f ()) -> f ()

-- | Monadic version of <a>whenRight</a>.
whenRightM :: Monad m => m (Either l r) -> (r -> m ()) -> m ()


-- | Monad transformers utilities.
module Universum.Monad.Trans

-- | Shorter and more readable alias for <tt>flip runReader</tt>.
usingReader :: r -> Reader r a -> a

-- | Shorter and more readable alias for <tt>flip runReaderT</tt>.
usingReaderT :: r -> ReaderT r m a -> m a

-- | Alias for <tt>flip evalState</tt>. It's not shorter but sometimes more
--   readable. Done by analogy with <tt>using*</tt> functions family.
evaluatingState :: s -> State s a -> a

-- | Alias for <tt>flip evalStateT</tt>. It's not shorter but sometimes
--   more readable. Done by analogy with <tt>using*</tt> functions family.
evaluatingStateT :: Functor f => s -> StateT s f a -> f a

-- | Alias for <tt>flip execState</tt>. It's not shorter but sometimes more
--   readable. Done by analogy with <tt>using*</tt> functions family.
executingState :: s -> State s a -> s

-- | Alias for <tt>flip execStateT</tt>. It's not shorter but sometimes
--   more readable. Done by analogy with <tt>using*</tt> functions family.
executingStateT :: Functor f => s -> StateT s f a -> f s

-- | Shorter and more readable alias for <tt>flip runState</tt>.
usingState :: s -> State s a -> (a, s)

-- | Shorter and more readable alias for <tt>flip runStateT</tt>.
usingStateT :: s -> StateT s m a -> m (a, s)


-- | This module reexports functions to work with monoids plus adds extra
--   useful functions.
module Universum.Monoid

-- | Extracts <a>Monoid</a> value from <a>Maybe</a> returning <a>mempty</a>
--   if <tt>Nothing</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; maybeToMonoid (Just [1,2,3] :: Maybe [Int])
--   [1,2,3]
--   
--   &gt;&gt;&gt; maybeToMonoid (Nothing :: Maybe [Int])
--   []
--   </pre>
maybeToMonoid :: Monoid m => Maybe m -> m


-- | Reimagined approach for <a>Foldable</a> type hierarchy. Forbids usages
--   of <a>length</a> function and similar over <a>Maybe</a> and other
--   potentially unsafe data types. It was proposed to use
--   <tt>-XTypeApplication</tt> for such cases. But this approach is not
--   robust enough because programmers are human and can easily forget to
--   do this. For discussion see this topic: <a>Suggest explicit type
--   application for Foldable length and friends</a>
module Universum.Container.Class

-- | Type class for data types that can be converted to List of Pairs. You
--   can define <a>ToPairs</a> by just defining <a>toPairs</a> function.
--   
--   But the following laws should be met:
--   
--   <pre>
--   <a>toPairs</a> m ≡ <a>zip</a> (<a>keys</a> m) (<a>elems</a> m)
--   <a>keys</a>      ≡ <a>map</a> <a>fst</a> . <a>toPairs</a>
--   <a>elems</a>     ≡ <a>map</a> <a>snd</a> . <a>toPairs</a>
--   </pre>
class ToPairs t where {
    type family Key t :: *;
    type family Val t :: *;
}

-- | Converts the structure to the list of the key-value pairs.
--   &gt;&gt;&gt; toPairs (HashMap.fromList [(<tt>a</tt>, "xxx"),
--   (<tt>b</tt>, "yyy")]) [(<tt>a</tt>,"xxx"),(<tt>b</tt>,"yyy")]
toPairs :: ToPairs t => t -> [(Key t, Val t)]

-- | Converts the structure to the list of the keys.
--   
--   <pre>
--   &gt;&gt;&gt; keys (HashMap.fromList [('a', "xxx"), ('b', "yyy")])
--   "ab"
--   </pre>
keys :: ToPairs t => t -> [Key t]

-- | Converts the structure to the list of the values.
--   
--   <pre>
--   &gt;&gt;&gt; elems (HashMap.fromList [('a', "xxx"), ('b', "yyy")])
--   ["xxx","yyy"]
--   </pre>
elems :: ToPairs t => t -> [Val t]

-- | Very similar to <a>Foldable</a> but also allows instances for
--   monomorphic types like <a>Text</a> but forbids instances for
--   <a>Maybe</a> and similar. This class is used as a replacement for
--   <a>Foldable</a> type class. It solves the following problems:
--   
--   <ol>
--   <li><a>length</a>, <a>foldr</a> and other functions work on more types
--   for which it makes sense.</li>
--   <li>You can't accidentally use <a>length</a> on polymorphic
--   <a>Foldable</a> (like list), replace list with <a>Maybe</a> and then
--   debug error for two days.</li>
--   <li>More efficient implementaions of functions for polymorphic types
--   (like <a>elem</a> for <a>Set</a>).</li>
--   </ol>
--   
--   The drawbacks:
--   
--   <ol>
--   <li>Type signatures of polymorphic functions look more scary.</li>
--   <li>Orphan instances are involved if you want to use <a>foldr</a> (and
--   similar) on types from libraries.</li>
--   </ol>
class Container t where {
    type family Element t :: *;
    type family ElementConstraint t :: * -> Constraint;
    type Element t = ElementDefault t;
    type ElementConstraint t = Eq;
}

-- | Convert container to list of elements.
--   
--   <pre>
--   &gt;&gt;&gt; toList @Text "aba"
--   "aba"
--   
--   &gt;&gt;&gt; :t toList @Text "aba"
--   toList @Text "aba" :: [Char]
--   </pre>
toList :: Container t => t -> [Element t]

-- | Convert container to list of elements.
--   
--   <pre>
--   &gt;&gt;&gt; toList @Text "aba"
--   "aba"
--   
--   &gt;&gt;&gt; :t toList @Text "aba"
--   toList @Text "aba" :: [Char]
--   </pre>
toList :: (Container t, Foldable f, t ~ f a, Element t ~ a) => t -> [Element t]

-- | Checks whether container is empty.
--   
--   <pre>
--   &gt;&gt;&gt; null @Text ""
--   True
--   
--   &gt;&gt;&gt; null @Text "aba"
--   False
--   </pre>
null :: Container t => t -> Bool

-- | Checks whether container is empty.
--   
--   <pre>
--   &gt;&gt;&gt; null @Text ""
--   True
--   
--   &gt;&gt;&gt; null @Text "aba"
--   False
--   </pre>
null :: (Container t, Foldable f, t ~ f a, Element t ~ a) => t -> Bool
foldr :: Container t => (Element t -> b -> b) -> b -> t -> b
foldr :: (Container t, Foldable f, t ~ f a, Element t ~ a) => (Element t -> b -> b) -> b -> t -> b
foldl :: Container t => (b -> Element t -> b) -> b -> t -> b
foldl :: (Container t, Foldable f, t ~ f a, Element t ~ a) => (b -> Element t -> b) -> b -> t -> b
foldl' :: Container t => (b -> Element t -> b) -> b -> t -> b
foldl' :: (Container t, Foldable f, t ~ f a, Element t ~ a) => (b -> Element t -> b) -> b -> t -> b
length :: Container t => t -> Int
length :: (Container t, Foldable f, t ~ f a, Element t ~ a) => t -> Int
elem :: (Container t, ElementConstraint t (Element t)) => Element t -> t -> Bool
elem :: (Container t, Foldable f, t ~ f a, Element t ~ a, ElementConstraint t ~ Eq, ElementConstraint t (Element t)) => Element t -> t -> Bool
maximum :: (Container t, Ord (Element t)) => t -> Element t
maximum :: (Container t, Foldable f, t ~ f a, Element t ~ a, Ord (Element t)) => t -> Element t
minimum :: (Container t, Ord (Element t)) => t -> Element t
minimum :: (Container t, Foldable f, t ~ f a, Element t ~ a, Ord (Element t)) => t -> Element t
foldMap :: (Container t, Monoid m) => (Element t -> m) -> t -> m
fold :: (Container t, Monoid (Element t)) => t -> Element t
foldr' :: Container t => (Element t -> b -> b) -> b -> t -> b
foldr1 :: Container t => (Element t -> Element t -> Element t) -> t -> Element t
foldl1 :: Container t => (Element t -> Element t -> Element t) -> t -> Element t
notElem :: (Container t, ElementConstraint t (Element t)) => Element t -> t -> Bool
all :: Container t => (Element t -> Bool) -> t -> Bool
any :: Container t => (Element t -> Bool) -> t -> Bool
and :: (Container t, (Element t ~ Bool)) => t -> Bool
or :: (Container t, (Element t ~ Bool)) => t -> Bool
find :: Container t => (Element t -> Bool) -> t -> Maybe (Element t)
safeHead :: Container t => t -> Maybe (Element t)

-- | Similar to <a>foldl'</a> but takes a function with its arguments
--   flipped.
--   
--   <pre>
--   &gt;&gt;&gt; flipfoldl' (/) 5 [2,3] :: Rational
--   15 % 2
--   </pre>
flipfoldl' :: (Container t, Element t ~ a) => (a -> b -> b) -> b -> t -> b

-- | Stricter version of <a>sum</a>.
--   
--   <pre>
--   &gt;&gt;&gt; sum [1..10]
--   55
--   
--   &gt;&gt;&gt; sum (Just 3)
--   ...
--       • Do not use 'Foldable' methods on Maybe
--         Suggestions:
--             Instead of
--                 for_ :: (Foldable t, Applicative f) =&gt; t a -&gt; (a -&gt; f b) -&gt; f ()
--             use
--                 whenJust  :: Applicative f =&gt; Maybe a    -&gt; (a -&gt; f ()) -&gt; f ()
--                 whenRight :: Applicative f =&gt; Either l r -&gt; (r -&gt; f ()) -&gt; f ()
--   ...
--             Instead of
--                 fold :: (Foldable t, Monoid m) =&gt; t m -&gt; m
--             use
--                 maybeToMonoid :: Monoid m =&gt; Maybe m -&gt; m
--   ...
--   </pre>
sum :: (Container t, Num (Element t)) => t -> Element t

-- | Stricter version of <a>product</a>.
--   
--   <pre>
--   &gt;&gt;&gt; product [1..10]
--   3628800
--   
--   &gt;&gt;&gt; product (Right 3)
--   ...
--       • Do not use 'Foldable' methods on Either
--         Suggestions:
--             Instead of
--                 for_ :: (Foldable t, Applicative f) =&gt; t a -&gt; (a -&gt; f b) -&gt; f ()
--             use
--                 whenJust  :: Applicative f =&gt; Maybe a    -&gt; (a -&gt; f ()) -&gt; f ()
--                 whenRight :: Applicative f =&gt; Either l r -&gt; (r -&gt; f ()) -&gt; f ()
--   ...
--             Instead of
--                 fold :: (Foldable t, Monoid m) =&gt; t m -&gt; m
--             use
--                 maybeToMonoid :: Monoid m =&gt; Maybe m -&gt; m
--   ...
--   </pre>
product :: (Container t, Num (Element t)) => t -> Element t

-- | Constrained to <a>Container</a> version of <a>mapM_</a>.
--   
--   <pre>
--   &gt;&gt;&gt; mapM_ print [True, False]
--   True
--   False
--   </pre>
mapM_ :: (Container t, Monad m) => (Element t -> m b) -> t -> m ()

-- | Constrained to <a>Container</a> version of <a>forM_</a>.
--   
--   <pre>
--   &gt;&gt;&gt; forM_ [True, False] print
--   True
--   False
--   </pre>
forM_ :: (Container t, Monad m) => t -> (Element t -> m b) -> m ()

-- | Constrained to <a>Container</a> version of <a>traverse_</a>.
--   
--   <pre>
--   &gt;&gt;&gt; traverse_ putTextLn ["foo", "bar"]
--   foo
--   bar
--   </pre>
traverse_ :: (Container t, Applicative f) => (Element t -> f b) -> t -> f ()

-- | Constrained to <a>Container</a> version of <a>for_</a>.
--   
--   <pre>
--   &gt;&gt;&gt; for_ [1 .. 5 :: Int] $ \i -&gt; when (even i) (print i)
--   2
--   4
--   </pre>
for_ :: (Container t, Applicative f) => t -> (Element t -> f b) -> f ()

-- | Constrained to <a>Container</a> version of <a>sequenceA_</a>.
--   
--   <pre>
--   &gt;&gt;&gt; sequenceA_ [putTextLn "foo", print True]
--   foo
--   True
--   </pre>
sequenceA_ :: (Container t, Applicative f, Element t ~ f a) => t -> f ()

-- | Constrained to <a>Container</a> version of <a>sequence_</a>.
--   
--   <pre>
--   &gt;&gt;&gt; sequence_ [putTextLn "foo", print True]
--   foo
--   True
--   </pre>
sequence_ :: (Container t, Monad m, Element t ~ m a) => t -> m ()

-- | Constrained to <a>Container</a> version of <a>asum</a>.
--   
--   <pre>
--   &gt;&gt;&gt; asum [Nothing, Just [False, True], Nothing, Just [True]]
--   Just [False,True]
--   </pre>
asum :: (Container t, Alternative f, Element t ~ f a) => t -> f a

-- | Type class for types that can be created from one element.
--   <tt>singleton</tt> is lone name for this function. Also constructions
--   of different type differ: <tt>:[]</tt> for lists, two arguments for
--   Maps. Also some data types are monomorphic.
--   
--   <pre>
--   &gt;&gt;&gt; one True :: [Bool]
--   [True]
--   
--   &gt;&gt;&gt; one 'a' :: Text
--   "a"
--   
--   &gt;&gt;&gt; one (3, "hello") :: HashMap Int String
--   fromList [(3,"hello")]
--   </pre>
class One x where {
    type family OneItem x;
}

-- | Create a list, map, <a>Text</a>, etc from a single element.
one :: One x => OneItem x -> x
instance Universum.Container.Class.One [a]
instance Universum.Container.Class.One (Data.List.NonEmpty.NonEmpty a)
instance Universum.Container.Class.One (Data.Sequence.Internal.Seq a)
instance Universum.Container.Class.One Data.Text.Internal.Text
instance Universum.Container.Class.One Data.Text.Internal.Lazy.Text
instance Universum.Container.Class.One Data.ByteString.Internal.ByteString
instance Universum.Container.Class.One Data.ByteString.Lazy.Internal.ByteString
instance Universum.Container.Class.One (Data.Map.Internal.Map k v)
instance Data.Hashable.Class.Hashable k => Universum.Container.Class.One (Data.HashMap.Base.HashMap k v)
instance Universum.Container.Class.One (Data.IntMap.Internal.IntMap v)
instance Universum.Container.Class.One (Data.Set.Internal.Set v)
instance Data.Hashable.Class.Hashable v => Universum.Container.Class.One (Data.HashSet.HashSet v)
instance Universum.Container.Class.One Data.IntSet.Internal.IntSet
instance Universum.Container.Class.One (Data.Vector.Vector a)
instance Data.Vector.Unboxed.Base.Unbox a => Universum.Container.Class.One (Data.Vector.Unboxed.Base.Vector a)
instance Data.Primitive.Types.Prim a => Universum.Container.Class.One (Data.Vector.Primitive.Vector a)
instance Foreign.Storable.Storable a => Universum.Container.Class.One (Data.Vector.Storable.Vector a)
instance (TypeError ...) => Universum.Container.Class.Container (a, b)
instance (TypeError ...) => Universum.Container.Class.Container (GHC.Base.Maybe a)
instance (TypeError ...) => Universum.Container.Class.Container (Data.Either.Either a b)
instance (TypeError ...) => Universum.Container.Class.Container (Data.Functor.Identity.Identity a)
instance (GHC.Classes.Eq a, Data.Hashable.Class.Hashable a) => Universum.Container.Class.CanHash a
instance Universum.Container.Class.Container (Data.HashSet.HashSet v)
instance Universum.Container.Class.Container Data.Text.Internal.Text
instance Universum.Container.Class.Container Data.Text.Internal.Lazy.Text
instance Universum.Container.Class.Container Data.ByteString.Internal.ByteString
instance Universum.Container.Class.Container Data.ByteString.Lazy.Internal.ByteString
instance Universum.Container.Class.Container Data.IntSet.Internal.IntSet
instance Universum.Container.Class.Container (Data.Set.Internal.Set v)
instance Universum.Container.Class.Container [a]
instance Universum.Container.Class.Container (Data.Functor.Const.Const a b)
instance Universum.Container.Class.Container (Data.Monoid.Dual a)
instance Universum.Container.Class.Container (Data.Monoid.First a)
instance Universum.Container.Class.Container (Data.Monoid.Last a)
instance Universum.Container.Class.Container (Data.Monoid.Product a)
instance Universum.Container.Class.Container (Data.Monoid.Sum a)
instance Universum.Container.Class.Container (Data.List.NonEmpty.NonEmpty a)
instance Universum.Container.Class.Container (Control.Applicative.ZipList a)
instance Universum.Container.Class.Container (Data.HashMap.Base.HashMap k v)
instance Universum.Container.Class.Container (Data.IntMap.Internal.IntMap v)
instance Universum.Container.Class.Container (Data.Map.Internal.Map k v)
instance Universum.Container.Class.Container (Data.Sequence.Internal.Seq a)
instance Universum.Container.Class.Container (Data.Vector.Vector a)
instance Universum.Container.Class.ToPairs (Data.HashMap.Base.HashMap k v)
instance Universum.Container.Class.ToPairs (Data.IntMap.Internal.IntMap v)
instance Universum.Container.Class.ToPairs (Data.Map.Internal.Map k v)


-- | This module exports all container-related stuff.
module Universum.Container


-- | This module exports functions which allow to process instances of
--   <a>Container</a> type class in monadic way.
module Universum.Monad.Container

-- | Lifting bind into a monad. Generalized version of <tt>concatMap</tt>
--   that works with a monadic predicate. Old and simpler specialized to
--   list version had next type:
--   
--   <pre>
--   concatMapM :: Monad m =&gt; (a -&gt; m [b]) -&gt; [a] -&gt; m [b]
--   </pre>
--   
--   Side note: previously it had type
--   
--   <pre>
--   concatMapM :: (Applicative q, Monad m, Traversable m)
--              =&gt; (a -&gt; q (m b)) -&gt; m a -&gt; q (m b)
--   </pre>
--   
--   Such signature didn't allow to use this function when traversed
--   container type and type of returned by function-argument differed. Now
--   you can use it like e.g.
--   
--   <pre>
--   concatMapM readFile files &gt;&gt;= putTextLn
--   </pre>
concatMapM :: (Applicative f, Monoid m, Container (l m), Element (l m) ~ m, Traversable l) => (a -> f m) -> l a -> f m

-- | Like <a>concatMapM</a>, but has its arguments flipped, so can be used
--   instead of the common <tt>fmap concat $ forM</tt> pattern.
concatForM :: (Applicative f, Monoid m, Container (l m), Element (l m) ~ m, Traversable l) => l a -> (a -> f m) -> f m

-- | Monadic and constrained to <a>Container</a> version of <a>all</a>.
--   
--   <pre>
--   &gt;&gt;&gt; allM (readMaybe &gt;=&gt; pure . even) ["6", "10"]
--   Just True
--   
--   &gt;&gt;&gt; allM (readMaybe &gt;=&gt; pure . even) ["5", "aba"]
--   Just False
--   
--   &gt;&gt;&gt; allM (readMaybe &gt;=&gt; pure . even) ["aba", "10"]
--   Nothing
--   </pre>
allM :: (Container f, Monad m) => (Element f -> m Bool) -> f -> m Bool

-- | Monadic and constrained to <a>Container</a> version of <a>any</a>.
--   
--   <pre>
--   &gt;&gt;&gt; anyM (readMaybe &gt;=&gt; pure . even) ["5", "10"]
--   Just True
--   
--   &gt;&gt;&gt; anyM (readMaybe &gt;=&gt; pure . even) ["10", "aba"]
--   Just True
--   
--   &gt;&gt;&gt; anyM (readMaybe &gt;=&gt; pure . even) ["aba", "10"]
--   Nothing
--   </pre>
anyM :: (Container f, Monad m) => (Element f -> m Bool) -> f -> m Bool

-- | Monadic and constrained to <a>Container</a> version of <a>and</a>.
--   
--   <pre>
--   &gt;&gt;&gt; andM [Just True, Just False]
--   Just False
--   
--   &gt;&gt;&gt; andM [Just True]
--   Just True
--   
--   &gt;&gt;&gt; andM [Just True, Just False, Nothing]
--   Just False
--   
--   &gt;&gt;&gt; andM [Just True, Nothing]
--   Nothing
--   
--   &gt;&gt;&gt; andM [putTextLn "1" &gt;&gt; pure True, putTextLn "2" &gt;&gt; pure False, putTextLn "3" &gt;&gt; pure True]
--   1
--   2
--   False
--   </pre>
andM :: (Container f, Element f ~ m Bool, Monad m) => f -> m Bool

-- | Monadic and constrained to <a>Container</a> version of <a>or</a>.
--   
--   <pre>
--   &gt;&gt;&gt; orM [Just True, Just False]
--   Just True
--   
--   &gt;&gt;&gt; orM [Just True, Nothing]
--   Just True
--   
--   &gt;&gt;&gt; orM [Nothing, Just True]
--   Nothing
--   </pre>
orM :: (Container f, Element f ~ m Bool, Monad m) => f -> m Bool


-- | Reexporting useful monadic stuff.
module Universum.Monad


-- | This module contains safe functions to work with list type (mostly
--   with <a>NonEmpty</a>).
module Universum.List.Safe

-- | Returns default list if given list is empty. Otherwise applies given
--   function to every element.
--   
--   <pre>
--   &gt;&gt;&gt; list [True] even []
--   [True]
--   
--   &gt;&gt;&gt; list [True] even [1..5]
--   [False,True,False,True,False]
--   </pre>
list :: [b] -> (a -> b) -> [a] -> [b]

-- | Destructuring list into its head and tail if possible. This function
--   is total.
--   
--   <pre>
--   &gt;&gt;&gt; uncons []
--   Nothing
--   
--   &gt;&gt;&gt; uncons [1..5]
--   Just (1,[2,3,4,5])
--   
--   &gt;&gt;&gt; uncons (5 : [1..5]) &gt;&gt;= \(f, l) -&gt; pure $ f == length l
--   Just True
--   </pre>
uncons :: [a] -> Maybe (a, [a])

-- | Performs given action over <a>NonEmpty</a> list if given list is non
--   empty.
--   
--   <pre>
--   &gt;&gt;&gt; whenNotNull [] $ \(b :| _) -&gt; print (not b)
--   
--   &gt;&gt;&gt; whenNotNull [False,True] $ \(b :| _) -&gt; print (not b)
--   True
--   </pre>
whenNotNull :: Applicative f => [a] -> (NonEmpty a -> f ()) -> f ()

-- | Monadic version of <a>whenNotNull</a>.
whenNotNullM :: Monad m => m [a] -> (NonEmpty a -> m ()) -> m ()


-- | Utility functions to work with lists.
module Universum.List


-- | Re-exports most useful functionality from 'safe-exceptions'. Also
--   provides some functions to work with exceptions over
--   <a>MonadError</a>.
module Universum.Exception

-- | Type that represents exceptions used in cases when a particular
--   codepath is not meant to be ever executed, but happens to be executed
--   anyway.
data Bug
Bug :: SomeException -> CallStack -> Bug

-- | Generate a pure value which, when forced, will synchronously throw the
--   exception wrapped into <a>Bug</a> data type.
bug :: (HasCallStack, Exception e) => e -> a

-- | Pattern synonym to easy pattern matching on exceptions. So intead of
--   writing something like this:
--   
--   <pre>
--   isNonCriticalExc e
--       | Just (_ :: NodeAttackedError) &lt;- fromException e = True
--       | Just DialogUnexpected{} &lt;- fromException e = True
--       | otherwise = False
--   </pre>
--   
--   you can use <a>Exc</a> pattern synonym:
--   
--   <pre>
--   isNonCriticalExc = case
--       Exc (_ :: NodeAttackedError) -&gt; True  -- matching all exceptions of type <tt>NodeAttackedError</tt>
--       Exc DialogUnexpected{} -&gt; True
--       _ -&gt; False
--   </pre>
--   
--   This pattern is bidirectional. You can use <tt>Exc e</tt> instead of
--   <tt>toException e</tt>.

-- | Throws error for <a>Maybe</a> if <a>Nothing</a> is given. Operates
--   over <a>MonadError</a>.
note :: (MonadError e m) => e -> Maybe a -> m a
instance GHC.Show.Show Universum.Exception.Bug
instance GHC.Exception.Exception Universum.Exception.Bug


-- | This module contains useful functions to evaluate expressions to
--   weak-head normal form or just normal form. Useful to force traces or
--   <tt>error</tt> inside monadic computation or to remove space leaks.
module Universum.DeepSeq

-- | Alias for <tt>evaluateWHNF . force</tt> with clearer name.
evaluateNF :: (NFData a, MonadIO m) => a -> m a

-- | Alias for <tt>evaluateWHNF . rnf</tt>. Similar to <a>evaluateNF</a>
--   but discards resulting value.
evaluateNF_ :: (NFData a, MonadIO m) => a -> m ()

-- | Lifted alias for <a>evaluate</a> with clearer name.
evaluateWHNF :: MonadIO m => a -> m a

-- | Like <tt>evaluateWNHF</tt> but discards value.
evaluateWHNF_ :: MonadIO m => a -> m ()


-- | This module contains monadic predicates.
module Universum.Bool.Guard

-- | Monadic version of <a>guard</a>. Occasionally useful. Here some
--   complex but real-life example:
--   
--   <pre>
--   findSomePath :: IO (Maybe FilePath)
--   
--   somePath :: MaybeT IO FilePath
--   somePath = do
--       path &lt;- MaybeT findSomePath
--       guardM $ liftIO $ doesDirectoryExist path
--       return path
--   </pre>
guardM :: MonadPlus m => m Bool -> m ()

-- | Monadic version of <tt>if-then-else</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; ifM (pure True) (putTextLn "True text") (putTextLn "False text")
--   True text
--   </pre>
ifM :: Monad m => m Bool -> m a -> m a -> m a

-- | Monadic version of <a>unless</a>.
--   
--   <pre>
--   &gt;&gt;&gt; unlessM (pure False) $ putTextLn "No text :("
--   No text :(
--   
--   &gt;&gt;&gt; unlessM (pure True) $ putTextLn "Yes text :)"
--   </pre>
unlessM :: Monad m => m Bool -> m () -> m ()

-- | Monadic version of <a>when</a>.
--   
--   <pre>
--   &gt;&gt;&gt; whenM (pure False) $ putTextLn "No text :("
--   
--   &gt;&gt;&gt; whenM (pure True)  $ putTextLn "Yes text :)"
--   Yes text :)
--   
--   &gt;&gt;&gt; whenM (Just True) (pure ())
--   Just ()
--   
--   &gt;&gt;&gt; whenM (Just False) (pure ())
--   Just ()
--   
--   &gt;&gt;&gt; whenM Nothing (pure ())
--   Nothing
--   </pre>
whenM :: Monad m => m Bool -> m () -> m ()


-- | Convenient commonly used and very helpful functions to work with
--   <a>Bool</a> and also with monads.
module Universum.Bool


-- | Functions to remove duplicates from a list.
--   
--   <h1>Performance</h1>
--   
--   To check the performance there was done a bunch of benchmarks.
--   Benchmarks were made on lists of <a>Int</a>s and <a>Text</a>s. There
--   were two types of list to use:
--   
--   <ul>
--   <li>Lists which consist of many different elements</li>
--   <li>Lists which consist of many same elements</li>
--   </ul>
--   
--   Here are some recomendations for usage of particular functions based
--   on benchmarking resutls.
--   
--   <ul>
--   <li><a>hashNub</a> is faster than <a>ordNub</a> when there're not so
--   many different values in the list.</li>
--   <li><a>hashNub</a> is the fastest with <a>Text</a>.</li>
--   <li><a>sortNub</a> has better performance than <a>ordNub</a> but
--   should be used when sorting is also needed.</li>
--   <li><a>unstableNub</a> has better performance than <a>hashNub</a> but
--   doesn't save the original order.</li>
--   </ul>
module Universum.Nub

-- | Like <a>nub</a> but runs in <tt>O(n * log_16(n))</tt> time and
--   requires <a>Hashable</a>.
--   
--   <pre>
--   &gt;&gt;&gt; hashNub [3, 3, 3, 2, 2, -1, 1]
--   [3,2,-1,1]
--   </pre>
hashNub :: (Eq a, Hashable a) => [a] -> [a]

-- | Like <a>nub</a> but runs in <tt>O(n * log n)</tt> time and requires
--   <a>Ord</a>.
--   
--   <pre>
--   &gt;&gt;&gt; ordNub [3, 3, 3, 2, 2, -1, 1]
--   [3,2,-1,1]
--   </pre>
ordNub :: (Ord a) => [a] -> [a]

-- | Like <a>ordNub</a> but also sorts a list.
--   
--   <pre>
--   &gt;&gt;&gt; sortNub [3, 3, 3, 2, 2, -1, 1]
--   [-1,1,2,3]
--   </pre>
sortNub :: (Ord a) => [a] -> [a]

-- | Like <a>hashNub</a> but has better performance and also doesn't save
--   the order.
--   
--   <pre>
--   &gt;&gt;&gt; unstableNub [3, 3, 3, 2, 2, -1, 1]
--   [1,2,3,-1]
--   </pre>
unstableNub :: (Eq a, Hashable a) => [a] -> [a]


-- | Generalization of <a>putStr</a> and <a>putStrLn</a> functions.
module Universum.Print

-- | Polymorfic over string and lifted to <a>MonadIO</a> printing
--   functions.
class Print a
putStr :: (Print a, MonadIO m) => a -> m ()
putStrLn :: (Print a, MonadIO m) => a -> m ()

-- | Lifted version of <a>print</a>.
print :: forall a m. (MonadIO m, Show a) => a -> m ()

-- | Specialized to <a>Text</a> version of <a>putStr</a> or forcing type
--   inference.
putText :: MonadIO m => Text -> m ()

-- | Specialized to <a>Text</a> version of <a>putStrLn</a> or forcing type
--   inference.
putTextLn :: MonadIO m => Text -> m ()

-- | Specialized to <a>Text</a> version of <a>putStr</a> or forcing type
--   inference.
putLText :: MonadIO m => Text -> m ()

-- | Specialized to <a>Text</a> version of <a>putStrLn</a> or forcing type
--   inference.
putLTextLn :: MonadIO m => Text -> m ()
instance Universum.Print.Print Data.Text.Internal.Text
instance Universum.Print.Print Data.Text.Internal.Lazy.Text
instance Universum.Print.Print Data.ByteString.Internal.ByteString
instance Universum.Print.Print Data.ByteString.Lazy.Internal.ByteString
instance Universum.Print.Print [GHC.Types.Char]


-- | Functions for debugging. If you left these functions in your code then
--   warning is generated to remind you about left usages. Also some
--   functions (and data types) are convenient for prototyping.
module Universum.Debug

-- | Similar to <a>undefined</a> but data type.

-- | <i>Warning: <a>Undefined</a> type remains in code</i>
data Undefined

-- | <i>Warning: <a>Undefined</a> type remains in code</i>
Undefined :: Undefined

-- | <a>error</a> that takes <a>Text</a> as an argument.
error :: forall (r :: RuntimeRep). forall (a :: TYPE r). HasCallStack => Text -> a

-- | Generalized over string version of <a>trace</a> that leaves warnings.

-- | <i>Warning: <a>trace</a> remains in code</i>
trace :: Print b => b -> a -> a

-- | Version of <a>traceM</a> that leaves warning and takes <a>Text</a>.

-- | <i>Warning: <a>traceM</a> remains in code</i>
traceM :: (Monad m) => Text -> m ()

-- | Version of <a>traceId</a> that leaves warning and takes <a>Text</a>.

-- | <i>Warning: <a>traceId</a> remains in code</i>
traceId :: Text -> Text

-- | Version of <a>traceShow</a> that leaves warning.

-- | <i>Warning: <a>traceShow</a> remains in code</i>
traceShow :: Show a => a -> b -> b

-- | Version of <a>traceShow</a> that leaves warning.

-- | <i>Warning: <a>traceShowId</a> remains in code</i>
traceShowId :: Show a => a -> a

-- | Version of <a>traceShowM</a> that leaves warning.

-- | <i>Warning: <a>traceShowM</a> remains in code</i>
traceShowM :: (Show a, Monad m) => a -> m ()

-- | <a>undefined</a> that leaves warning in code on every usage.

-- | <i>Warning: <a>undefined</a> function remains in code (or use
--   <a>error</a>)</i>
undefined :: forall (r :: RuntimeRep). forall (a :: TYPE r). HasCallStack => a
instance GHC.Generics.Generic Universum.Debug.Undefined
instance Data.Data.Data Universum.Debug.Undefined
instance GHC.Enum.Bounded Universum.Debug.Undefined
instance GHC.Enum.Enum Universum.Debug.Undefined
instance GHC.Read.Read Universum.Debug.Undefined
instance GHC.Show.Show Universum.Debug.Undefined
instance GHC.Classes.Ord Universum.Debug.Undefined
instance GHC.Classes.Eq Universum.Debug.Undefined


-- | This module reexports functions to work with <a>Text</a> and
--   <a>ByteString</a> types.
module Universum.String.Reexport


-- | This module implements type class which allow to have conversion to
--   and from <a>Text</a>, <a>String</a> and <a>ByteString</a> types
--   (including both strict and lazy versions). Usually you need to export
--   <a>Text</a> modules qualified and use <a>pack</a> / <a>unpack</a>
--   functions to convert to/from <a>Text</a>. Now you can just use
--   <a>toText</a> / <a>toString</a> functions.
module Universum.String.Conversion

-- | Type synonym for <a>Text</a>.
type LText = Text

-- | Type synonym for <a>ByteString</a>.
type LByteString = ByteString

-- | Type class for conversion to utf8 representation of text.
class ConvertUtf8 a b

-- | Encode as utf8 string (usually <a>ByteString</a>).
--   
--   <pre>
--   &gt;&gt;&gt; encodeUtf8 @Text @ByteString "патак"
--   "\208\191\208\176\209\130\208\176\208\186"
--   </pre>
encodeUtf8 :: ConvertUtf8 a b => a -> b

-- | Decode from utf8 string.
--   
--   <pre>
--   &gt;&gt;&gt; decodeUtf8 @Text @ByteString "\208\191\208\176\209\130\208\176\208\186"
--   "\1087\1072\1090\1072\1082"
--   
--   &gt;&gt;&gt; putStrLn $ decodeUtf8 @Text @ByteString "\208\191\208\176\209\130\208\176\208\186"
--   патак
--   </pre>
decodeUtf8 :: ConvertUtf8 a b => b -> a

-- | Decode as utf8 string but returning execption if byte sequence is
--   malformed.
--   
--   <pre>
--   &gt;&gt;&gt; decodeUtf8 @Text @ByteString "\208\208\176\209\130\208\176\208\186"
--   "\65533\1072\1090\1072\1082"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeUtf8Strict @Text @ByteString "\208\208\176\209\130\208\176\208\186"
--   Left Cannot decode byte '\xd0': Data.Text.Internal.Encoding.decodeUtf8: Invalid UTF-8 stream
--   </pre>
decodeUtf8Strict :: ConvertUtf8 a b => b -> Either UnicodeException a

-- | Type class for converting other strings to <a>String</a>.
class ToString a
toString :: ToString a => a -> String

-- | Type class for converting other strings to <a>Text</a>.
class ToLText a
toLText :: ToLText a => a -> Text

-- | Type class for converting other strings to <a>Text</a>.
class ToText a
toText :: ToText a => a -> Text

-- | Polymorhpic version of <a>readEither</a>.
--   
--   <pre>
--   &gt;&gt;&gt; readEither @Text @Int "123"
--   Right 123
--   
--   &gt;&gt;&gt; readEither @Text @Int "aa"
--   Left "Prelude.read: no parse"
--   </pre>
readEither :: (ToString a, Read b) => a -> Either Text b

-- | Generalized version of <a>show</a>.
show :: forall b a. (Show a, IsString b) => a -> b

-- | Functions to show pretty output for buildable data types.
pretty :: Buildable a => a -> Text

-- | Similar to <a>pretty</a> but for <a>LText</a>.
prettyL :: Buildable a => a -> LText
instance Universum.String.Conversion.ToString GHC.Base.String
instance Universum.String.Conversion.ToString Data.Text.Internal.Text
instance Universum.String.Conversion.ToString Data.Text.Internal.Lazy.Text
instance Universum.String.Conversion.ToLText GHC.Base.String
instance Universum.String.Conversion.ToLText Data.Text.Internal.Text
instance Universum.String.Conversion.ToLText Data.Text.Internal.Lazy.Text
instance Universum.String.Conversion.ToText GHC.Base.String
instance Universum.String.Conversion.ToText Data.Text.Internal.Text
instance Universum.String.Conversion.ToText Data.Text.Internal.Lazy.Text
instance Universum.String.Conversion.ConvertUtf8 GHC.Base.String Data.ByteString.Internal.ByteString
instance Universum.String.Conversion.ConvertUtf8 Data.Text.Internal.Text Data.ByteString.Internal.ByteString
instance Universum.String.Conversion.ConvertUtf8 Data.Text.Internal.Lazy.Text Data.ByteString.Internal.ByteString
instance Universum.String.Conversion.ConvertUtf8 GHC.Base.String Data.ByteString.Lazy.Internal.ByteString
instance Universum.String.Conversion.ConvertUtf8 Data.Text.Internal.Text Data.ByteString.Lazy.Internal.ByteString
instance Universum.String.Conversion.ConvertUtf8 Data.Text.Internal.Lazy.Text Data.ByteString.Lazy.Internal.ByteString


-- | Type classes for convertion between different string representations.
module Universum.String


-- | Type operators for writing convenient type signatures.
module Universum.TypeOps

-- | Map several constraints over several variables.
--   
--   <pre>
--   f :: Each [Show, Read] [a, b] =&gt; a -&gt; b -&gt; String
--   =
--   f :: (Show a, Show b, Read a, Read b) =&gt; a -&gt; b -&gt; String
--   </pre>
--   
--   To specify list with single constraint / variable, don't forget to
--   prefix it with <tt>'</tt>:
--   
--   <pre>
--   f :: Each '[Show] [a, b] =&gt; a -&gt; b -&gt; String
--   </pre>

-- | Map several constraints over a single variable. Note, that <tt>With a
--   b ≡ Each a '[b]</tt>
--   
--   <pre>
--   a :: With [Show, Read] a =&gt; a -&gt; a
--   =
--   a :: (Show a, Read a) =&gt; a -&gt; a
--   </pre>
type With a b = a <+> b

-- | Infix application.
--   
--   <pre>
--   f :: Either String $ Maybe Int
--   =
--   f :: Either String (Maybe Int)
--   </pre>
type ($) k k1 (f :: k -> k1) (a :: k) = f a


-- | Unsafe functions to work with lists and <tt>Maybe</tt>. Sometimes
--   unavoidable but better don't use them. This module is intended to be
--   imported qualified and it's not even included in default prelude
--   exports.
--   
--   <pre>
--   import qualified Universum.Unsafe as Unsafe
--   
--   foo :: [a] -&gt; a
--   foo = Unsafe.head
--   </pre>
module Universum.Unsafe

-- | Extract the first element of a list, which must be non-empty.
head :: () => [a] -> a

-- | Extract the elements after the head of a list, which must be
--   non-empty.
tail :: () => [a] -> [a]

-- | Return all the elements of a list except the last one. The list must
--   be non-empty.
init :: () => [a] -> [a]

-- | Extract the last element of a list, which must be finite and
--   non-empty.
last :: () => [a] -> a

-- | Similar to <a>!!</a> but with flipped arguments.
at :: Int -> [a] -> a

-- | List index (subscript) operator, starting from 0. It is an instance of
--   the more general <a>genericIndex</a>, which takes an index of any
--   integral type.
(!!) :: () => [a] -> Int -> a
infixl 9 !!

-- | The <a>fromJust</a> function extracts the element out of a <a>Just</a>
--   and throws an error if its argument is <a>Nothing</a>.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; fromJust (Just 1)
--   1
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; 2 * (fromJust (Just 10))
--   20
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; 2 * (fromJust Nothing)
--   *** Exception: Maybe.fromJust: Nothing
--   </pre>
fromJust :: () => Maybe a -> a


-- | Provides operator of variable-arguments function composition.
module Universum.VarArg

-- | This type class allows to implement variadic composition operator.
class SuperComposition a b c | a b -> c

-- | Allows to apply function to result of another function with multiple
--   arguments.
--   
--   <pre>
--   &gt;&gt;&gt; (show ... (+)) 1 2
--   "3"
--   
--   &gt;&gt;&gt; show ... 5
--   "5"
--   
--   &gt;&gt;&gt; (null ... zip5) [1] [2] [3] [] [5]
--   True
--   </pre>
--   
--   Inspired by
--   <a>http://stackoverflow.com/questions/9656797/variadic-compose-function</a>.
--   
--   <h4>Performance</h4>
--   
--   To check the performance there was done a bunch of benchmarks.
--   Benchmarks were made on examples given above and also on the functions
--   of many arguments. The results are showing that the operator
--   (<a>...</a>) performs as fast as plain applications of the operator
--   (<a>.</a>) on almost all the tests, but (<a>...</a>) leads to the
--   performance draw-down if <tt>ghc</tt> fails to inline it. Slow
--   behavior was noticed on functions without type specifications. That's
--   why keep in mind that providing explicit type declarations for
--   functions is very important when using (<a>...</a>). Relying on type
--   inference will lead to the situation when all optimizations disappear
--   due to very general inferred type. However, functions without type
--   specification but with applied <tt>INLINE</tt> pragma are fast again.
(...) :: SuperComposition a b c => a -> b -> c
instance (a ~ c, r ~ b) => Universum.VarArg.SuperComposition (a -> b) c r
instance (Universum.VarArg.SuperComposition (a -> b) d r1, r ~ (c -> r1)) => Universum.VarArg.SuperComposition (a -> b) (c -> d) r


-- | Main module that reexports all functionality allowed to use without
--   importing any other modules. Just add next lines to your module to
--   replace default <tt>Prelude</tt> with better one.
--   
--   <pre>
--   {-# LANGUAGE NoImplicitPrelude #-}
--   
--   <b>import</b> <a>Universum</a>
--   </pre>
--   
--   This documentation section contains description of internal module
--   structure to help navigate between modules, search for interesting
--   functionalities and understand where you need to put your new changes.
--   
--   Functions and types are distributed across multiple modules and
--   grouped by meaning or <b>theme</b>. Name of the module should give you
--   hints regarding what this module contains. Some <i>themes</i> contain
--   a great amount of both reexported functions and functions of our own.
--   To make it easier to understand these huge chunks of functions, all
--   reexported stuff is moved into separate module with name
--   <tt>Universum.SomeTheme.Reexport</tt> and our own functions and types
--   are in <tt>Universum.SomeTheme.SomeName</tt>. For example, see modules
--   <a>Universum.Container.Class</a> and
--   <a>Universum.Container.Reexport</a>.
--   
--   Below is a short description of what you can find under different
--   modules:
--   
--   <ul>
--   <li><b><a>Universum.Applicative</a></b>: reexports from
--   <a>Control.Applicative</a> and some general-purpose applicative
--   combinators.</li>
--   <li><b><a>Universum.Base</a></b>: different general types and type
--   classes from <tt>base</tt> package (<a>Int</a>, <a>Num</a>,
--   <a>Generic</a>, etc.) not exported by other modules.</li>
--   <li><b><a>Universum.Bool</a></b>: <a>Bool</a> data type with different
--   predicates and combinators.</li>
--   <li><b><a>Universum.Container</a></b>: <a>Foldable</a> replacement,
--   types from <tt>containers</tt> and <tt>unordered-containers</tt> and
--   <tt>vector</tt> packages.</li>
--   <li><b><a>Universum.Debug</a></b>: <tt>trace</tt>-like debugging
--   functions with compile-time warnings (so you don't forget to remove
--   them)</li>
--   <li><b><a>Universum.DeepSeq</a></b>: reexports from
--   <a>Control.DeepSeq</a> module and functions to evaluate expressions to
--   weak-head normal form or normal form.</li>
--   <li><b><a>Universum.Exception</a></b>: reexports
--   <a>Control.Exception.Safe</a> from <tt>safe-exceptions</tt> package,
--   <a>bug</a> as better <a>error</a>, <a>Exc</a> pattern synonym for
--   convenient pattern-matching on exceptions.</li>
--   <li><b><a>Universum.Function</a></b>: almost everything from
--   <a>Data.Function</a> module.</li>
--   <li><b><a>Universum.Functor</a></b>: reexports from
--   <a>Data.Functor</a>, <a>Data.Bifunctor</a>, other useful
--   <a>Functor</a> combinators.</li>
--   <li><b><a>Universum.Lifted</a></b>: lifted to <a>MonadIO</a> functions
--   to work with console, files, <a>IORef</a>s, <a>MVar</a>s, etc.</li>
--   <li><b><a>Universum.List</a></b>: big chunk of <a>Data.List</a>,
--   <a>NonEmpty</a> type and functions for this type (<a>head</a>,
--   <a>tail</a>, <a>last</a>, <a>init</a>).</li>
--   <li><b><a>Universum.Monad</a></b>: monad transormers, combinators for
--   <a>Maybe</a> and <a>Either</a>.</li>
--   <li><b><a>Universum.Monoid</a></b>: reexports from <a>Data.Monoid</a>
--   and <a>Data.Semigroup</a>.</li>
--   <li><b><a>Universum.Nub</a></b>: better versions of <tt>nub</tt>
--   function for list.</li>
--   <li><b><a>Universum.Print</a></b>: polymorphic <a>putStrLn</a>
--   function and functions to print <a>Text</a>.</li>
--   <li><b><a>Universum.String</a></b>: reexports from <tt>text</tt> and
--   <tt>bytestring</tt> packages with conversion functions between
--   different textual types.</li>
--   <li><b><a>Universum.TypeOps</a></b>: convenient and fancy type-level
--   operators.</li>
--   <li><b><a>Universum.Unsafe</a></b>: unsafe functions (produce
--   <a>error</a>). Not exported by <a>Universum</a> module by
--   default.</li>
--   <li><b><a>Universum.VarArg</a></b>: variadic composition operator
--   <a>...</a>.</li>
--   </ul>
module Universum
