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


-- | Custom prelude from Kowainik
--   
--   <h2>Goals</h2>
--   
--   <ul>
--   <li><b>Avoid all <a>partial functions</a></b> (like <tt>head :: [a]
--   -&gt; a</tt>). The types of partial functions lie about their behavior
--   and usage of such functions can lead to the unexpected bugs. Though
--   you can still use some unsafe functions from <tt>Relude.Unsafe</tt>
--   module, but they are not exported by default.</li>
--   <li><b>Type-safety</b>. We like to make invalid states
--   unrepresantable. And if it's possible to express this concept through
--   the types then we will do it. <i>Example:</i> <tt> whenNotNull ::
--   Applicative f =&gt; [a] -&gt; (NonEmpty a -&gt; f ()) -&gt; f ()
--   </tt></li>
--   <li><b>Performance.</b> Prefer <tt>Text</tt> over
--   <tt><a>String</a></tt>, use spaceleak-free functions (like our custom
--   <tt>sum</tt> and <tt>product</tt>).</li>
--   <li><b>Minimalism</b> (low number of dependencies). We don't force
--   users of <tt>relude</tt> to stick to some specific lens or text
--   formatting or logging library.</li>
--   <li><b>Convenience</b> (like lifted to <tt>MonadIO</tt> functions,
--   more reexports). But we want to bring common types and functions (like
--   <tt>containers</tt> and <tt>bytestrng</tt>) into scope because they
--   are used in almost every application anyways.</li>
--   <li><b>Provide excellent documentation.</b></li>
--   </ul>
--   
--   <ol>
--   <li>Tutorial</li>
--   <li>Migration guide from <tt>Prelude</tt></li>
--   <li>Haddock with examples for (almost) every function (all examples
--   are tested with <a>`doctest`</a>)</li>
--   <li>Documentation regarding <a>internal module structure</a>)</li>
--   <li><tt>relude</tt>-specific <a>HLint</a> rules:
--   <tt><a>.hlint.yaml</a></tt></li>
--   </ol>
--   
--   <ul>
--   <li><b>User-friendliness.</b> Ability to quickly migrate to
--   <tt>relude</tt> if you're familiar with the common libraries like
--   <tt>text</tt> and <tt>containers</tt>.</li>
--   <li><b>Exploration.</b> Experiment with new ideas and proposals
--   without introducing breaking changes.</li>
--   </ul>
@package relude
@version 0.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 Relude.Applicative

-- | A functor with application, providing operations to
--   
--   <ul>
--   <li>embed pure expressions (<a>pure</a>), and</li>
--   <li>sequence computations and combine their results (<a>&lt;*&gt;</a>
--   and <a>liftA2</a>).</li>
--   </ul>
--   
--   A minimal complete definition must include implementations of
--   <a>pure</a> and of either <a>&lt;*&gt;</a> or <a>liftA2</a>. If it
--   defines both, then they must behave the same as their default
--   definitions:
--   
--   <pre>
--   (<a>&lt;*&gt;</a>) = <a>liftA2</a> <a>id</a>
--   </pre>
--   
--   <pre>
--   <a>liftA2</a> f x y = f <tt>&lt;$&gt;</tt> x <a>&lt;*&gt;</a> y
--   </pre>
--   
--   Further, any definition must satisfy the following:
--   
--   <ul>
--   <li><i><i>identity</i></i> <pre><a>pure</a> <a>id</a> <a>&lt;*&gt;</a>
--   v = v</pre></li>
--   <li><i><i>composition</i></i> <pre><a>pure</a> (.) <a>&lt;*&gt;</a> u
--   <a>&lt;*&gt;</a> v <a>&lt;*&gt;</a> w = u <a>&lt;*&gt;</a> (v
--   <a>&lt;*&gt;</a> w)</pre></li>
--   <li><i><i>homomorphism</i></i> <pre><a>pure</a> f <a>&lt;*&gt;</a>
--   <a>pure</a> x = <a>pure</a> (f x)</pre></li>
--   <li><i><i>interchange</i></i> <pre>u <a>&lt;*&gt;</a> <a>pure</a> y =
--   <a>pure</a> (<a>$</a> y) <a>&lt;*&gt;</a> u</pre></li>
--   </ul>
--   
--   The other methods have the following default definitions, which may be
--   overridden with equivalent specialized implementations:
--   
--   <ul>
--   <li><pre>u <a>*&gt;</a> v = (<a>id</a> <a>&lt;$</a> u)
--   <a>&lt;*&gt;</a> v</pre></li>
--   <li><pre>u <a>&lt;*</a> v = <a>liftA2</a> <a>const</a> u v</pre></li>
--   </ul>
--   
--   As a consequence of these laws, the <a>Functor</a> instance for
--   <tt>f</tt> will satisfy
--   
--   <ul>
--   <li><pre><a>fmap</a> f x = <a>pure</a> f <a>&lt;*&gt;</a> x</pre></li>
--   </ul>
--   
--   It may be useful to note that supposing
--   
--   <pre>
--   forall x y. p (q x y) = f x . g y
--   </pre>
--   
--   it follows from the above that
--   
--   <pre>
--   <a>liftA2</a> p (<a>liftA2</a> q u v) = <a>liftA2</a> f u . <a>liftA2</a> g v
--   </pre>
--   
--   If <tt>f</tt> is also a <a>Monad</a>, it should satisfy
--   
--   <ul>
--   <li><pre><a>pure</a> = <a>return</a></pre></li>
--   <li><pre>(<a>&lt;*&gt;</a>) = <a>ap</a></pre></li>
--   <li><pre>(<a>*&gt;</a>) = (<a>&gt;&gt;</a>)</pre></li>
--   </ul>
--   
--   (which implies that <a>pure</a> and <a>&lt;*&gt;</a> satisfy the
--   applicative functor laws).
class Functor f => Applicative (f :: * -> *)

-- | Lift a value.
pure :: Applicative f => a -> f a

-- | Sequential application.
--   
--   A few functors support an implementation of <a>&lt;*&gt;</a> that is
--   more efficient than the default one.
(<*>) :: Applicative f => f a -> b -> f a -> f b

-- | Lift a binary function to actions.
--   
--   Some functors support an implementation of <a>liftA2</a> that is more
--   efficient than the default one. In particular, if <a>fmap</a> is an
--   expensive operation, it is likely better to use <a>liftA2</a> than to
--   <a>fmap</a> over the structure and then use <a>&lt;*&gt;</a>.
liftA2 :: Applicative f => a -> b -> c -> f a -> f b -> f c

-- | Sequence actions, discarding the value of the first argument.
(*>) :: Applicative f => f a -> f b -> f b

-- | Sequence actions, discarding the value of the second argument.
(<*) :: Applicative f => f a -> f b -> f a

-- | One or none.
optional :: Alternative f => f a -> f Maybe a

-- | Lists, but with an <a>Applicative</a> functor based on zipping.
newtype ZipList a
ZipList :: [a] -> ZipList a
[getZipList] :: ZipList a -> [a]

-- | The <a>Const</a> functor.
newtype Const a (b :: k) :: forall k. () => * -> k -> *
Const :: a -> Const a
[getConst] :: Const a -> a

-- | Lift a ternary function to actions.
liftA3 :: Applicative f => a -> b -> c -> d -> f a -> f b -> f c -> f d

-- | A variant of <a>&lt;*&gt;</a> with the arguments reversed.
(<**>) :: Applicative f => f a -> f a -> b -> f b
infixl 4 <**>

-- | A monoid on applicative functors.
--   
--   If defined, <a>some</a> and <a>many</a> should be the least solutions
--   of the equations:
--   
--   <ul>
--   <li><pre><a>some</a> v = (:) <tt>&lt;$&gt;</tt> v <a>&lt;*&gt;</a>
--   <a>many</a> v</pre></li>
--   <li><pre><a>many</a> v = <a>some</a> v <a>&lt;|&gt;</a> <a>pure</a>
--   []</pre></li>
--   </ul>
class Applicative f => Alternative (f :: * -> *)

-- | The identity of <a>&lt;|&gt;</a>
empty :: Alternative f => f a

-- | An associative binary operation
(<|>) :: Alternative f => f a -> f a -> f a

-- | One or more.
some :: Alternative f => f a -> f [a]

-- | Zero or more.
many :: Alternative f => f a -> f [a]

-- | 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 Relude.Base

-- | Bitwise "xor"
xor :: Bits a => a -> a -> a
infixl 6 `xor`

-- | The character type <a>Char</a> is an enumeration whose values
--   represent Unicode (or equivalently ISO/IEC 10646) code points (i.e.
--   characters, see <a>http://www.unicode.org/</a> for details). This set
--   extends the ISO 8859-1 (Latin-1) character set (the first 256
--   characters), which is itself an extension of the ASCII character set
--   (the first 128 characters). A character literal in Haskell has type
--   <a>Char</a>.
--   
--   To convert a <a>Char</a> to or from the corresponding <a>Int</a> value
--   defined by Unicode, use <a>toEnum</a> and <a>fromEnum</a> from the
--   <a>Enum</a> class respectively (or equivalently <tt>ord</tt> and
--   <tt>chr</tt>).
data Char

-- | The <a>toEnum</a> method restricted to the type <a>Char</a>.
chr :: Int -> Char

-- | A fixed-precision integer type with at least the range <tt>[-2^29 ..
--   2^29-1]</tt>. The exact range for a given implementation can be
--   determined by using <a>minBound</a> and <a>maxBound</a> from the
--   <a>Bounded</a> class.
data Int

-- | 8-bit signed integer type
data Int8

-- | 16-bit signed integer type
data Int16

-- | 32-bit signed integer type
data Int32

-- | 64-bit signed integer type
data Int64

-- | A <a>Word</a> is an unsigned integral type, with the same size as
--   <a>Int</a>.
data Word

-- | 8-bit unsigned integer type
data Word8

-- | 16-bit unsigned integer type
data Word16

-- | 32-bit unsigned integer type
data Word32

-- | 64-bit unsigned integer type
data Word64

-- | Reverse order of bytes in <a>Word64</a>.
byteSwap64 :: Word64 -> Word64

-- | Reverse order of bytes in <a>Word32</a>.
byteSwap32 :: Word32 -> Word32

-- | Swap bytes in <a>Word16</a>.
byteSwap16 :: Word16 -> Word16

-- | Type representing arbitrary-precision non-negative integers.
--   
--   <pre>
--   &gt;&gt;&gt; 2^20 :: Natural
--   1267650600228229401496703205376
--   </pre>
--   
--   Operations whose result would be negative <tt><tt>throw</tt>
--   (<tt>Underflow</tt> :: <tt>ArithException</tt>)</tt>,
--   
--   <pre>
--   &gt;&gt;&gt; -1 :: Natural
--   *** Exception: arithmetic underflow
--   </pre>
data Natural

-- | The <a>Eq</a> class defines equality (<a>==</a>) and inequality
--   (<a>/=</a>). All the basic datatypes exported by the <a>Prelude</a>
--   are instances of <a>Eq</a>, and <a>Eq</a> may be derived for any
--   datatype whose constituents are also instances of <a>Eq</a>.
--   
--   Minimal complete definition: either <a>==</a> or <a>/=</a>.
class Eq a
(==) :: Eq a => a -> a -> Bool
(/=) :: Eq a => a -> a -> Bool

-- | The <a>Ord</a> class is used for totally ordered datatypes.
--   
--   Instances of <a>Ord</a> can be derived for any user-defined datatype
--   whose constituent types are in <a>Ord</a>. The declared order of the
--   constructors in the data declaration determines the ordering in
--   derived <a>Ord</a> instances. The <a>Ordering</a> datatype allows a
--   single comparison to determine the precise ordering of two objects.
--   
--   Minimal complete definition: either <a>compare</a> or <a>&lt;=</a>.
--   Using <a>compare</a> can be more efficient for complex types.
class Eq a => Ord a
compare :: Ord a => a -> a -> Ordering
(<) :: Ord a => a -> a -> Bool
(<=) :: Ord a => a -> a -> Bool
(>) :: Ord a => a -> a -> Bool
(>=) :: Ord a => a -> a -> Bool
max :: Ord a => a -> a -> a
min :: Ord a => a -> a -> a
data Ordering
LT :: Ordering
EQ :: Ordering
GT :: Ordering

-- | <pre>
--   comparing p x y = compare (p x) (p y)
--   </pre>
--   
--   Useful combinator for use in conjunction with the <tt>xxxBy</tt>
--   family of functions from <a>Data.List</a>, for example:
--   
--   <pre>
--   ... sortBy (comparing fst) ...
--   </pre>
comparing :: Ord a => b -> a -> b -> b -> Ordering

-- | The <a>Down</a> type allows you to reverse sort order conveniently. A
--   value of type <tt><a>Down</a> a</tt> contains a value of type
--   <tt>a</tt> (represented as <tt><a>Down</a> a</tt>). If <tt>a</tt> has
--   an <tt><a>Ord</a></tt> instance associated with it then comparing two
--   values thus wrapped will give you the opposite of their normal sort
--   order. This is particularly useful when sorting in generalised list
--   comprehensions, as in: <tt>then sortWith by <a>Down</a> x</tt>
newtype Down a
Down :: a -> Down a

-- | A value of type <tt><a>IO</a> a</tt> is a computation which, when
--   performed, does some I/O before returning a value of type <tt>a</tt>.
--   
--   There is really only one way to "perform" an I/O action: bind it to
--   <tt>Main.main</tt> in your program. When your program is run, the I/O
--   will be performed. It isn't possible to perform I/O from an arbitrary
--   function, unless that function is itself in the <a>IO</a> monad and
--   called at some point, directly or indirectly, from <tt>Main.main</tt>.
--   
--   <a>IO</a> is a monad, so <a>IO</a> actions can be combined using
--   either the do-notation or the <tt>&gt;&gt;</tt> and <tt>&gt;&gt;=</tt>
--   operations from the <tt>Monad</tt> class.
data IO a

-- | Haskell defines operations to read and write characters from and to
--   files, represented by values of type <tt>Handle</tt>. Each value of
--   this type is a <i>handle</i>: a record used by the Haskell run-time
--   system to <i>manage</i> I/O with file system objects. A handle has at
--   least the following properties:
--   
--   <ul>
--   <li>whether it manages input or output or both;</li>
--   <li>whether it is <i>open</i>, <i>closed</i> or
--   <i>semi-closed</i>;</li>
--   <li>whether the object is seekable;</li>
--   <li>whether buffering is disabled, or enabled on a line or block
--   basis;</li>
--   <li>a buffer (whose length may be zero).</li>
--   </ul>
--   
--   Most handles will also have a current I/O position indicating where
--   the next input or output operation will occur. A handle is
--   <i>readable</i> if it manages only input or both input and output;
--   likewise, it is <i>writable</i> if it manages only output or both
--   input and output. A handle is <i>open</i> when first allocated. Once
--   it is closed it can no longer be used for either input or output,
--   though an implementation cannot re-use its storage while references
--   remain to it. Handles are in the <a>Show</a> and <a>Eq</a> classes.
--   The string produced by showing a handle is system dependent; it should
--   include enough information to identify the handle for debugging. A
--   handle is equal according to <a>==</a> only to itself; no attempt is
--   made to compare the internal state of different handles for equality.
data Handle

-- | <tt><a>withFile</a> name mode act</tt> opens a file using
--   <a>openFile</a> and passes the resulting handle to the computation
--   <tt>act</tt>. The handle will be closed on exit from <a>withFile</a>,
--   whether by normal termination or by raising an exception. If closing
--   the handle raises an exception, then this exception will be raised by
--   <a>withFile</a> rather than any exception raised by <tt>act</tt>.
withFile :: () => FilePath -> IOMode -> Handle -> IO r -> IO r

-- | A handle managing output to the Haskell program's standard error
--   channel.
stderr :: Handle

-- | A handle managing input from the Haskell program's standard input
--   channel.
stdin :: Handle

-- | A handle managing output to the Haskell program's standard output
--   channel.
stdout :: Handle

-- | File and directory names are values of type <a>String</a>, whose
--   precise meaning is operating system dependent. Files can be opened,
--   yielding a handle which can then be used to operate on the contents of
--   that file.
type FilePath = String

-- | See <a>openFile</a>
data IOMode
ReadMode :: IOMode
WriteMode :: IOMode
AppendMode :: IOMode
ReadWriteMode :: IOMode

-- | The function <tt>coerce</tt> allows you to safely convert between
--   values of types that have the same representation with no run-time
--   overhead. In the simplest case you can use it instead of a newtype
--   constructor, to go from the newtype's concrete type to the abstract
--   type. But it also works in more complicated settings, e.g. converting
--   a list of newtypes to a list of concrete types.
coerce :: Coercible a b => a -> b

-- | <tt>Coercible</tt> is a two-parameter class that has instances for
--   types <tt>a</tt> and <tt>b</tt> if the compiler can infer that they
--   have the same representation. This class does not have regular
--   instances; instead they are created on-the-fly during type-checking.
--   Trying to manually declare an instance of <tt>Coercible</tt> is an
--   error.
--   
--   Nevertheless one can pretend that the following three kinds of
--   instances exist. First, as a trivial base-case:
--   
--   <pre>
--   instance Coercible a a
--   </pre>
--   
--   Furthermore, for every type constructor there is an instance that
--   allows to coerce under the type constructor. For example, let
--   <tt>D</tt> be a prototypical type constructor (<tt>data</tt> or
--   <tt>newtype</tt>) with three type arguments, which have roles
--   <tt>nominal</tt>, <tt>representational</tt> resp. <tt>phantom</tt>.
--   Then there is an instance of the form
--   
--   <pre>
--   instance Coercible b b' =&gt; Coercible (D a b c) (D a b' c')
--   </pre>
--   
--   Note that the <tt>nominal</tt> type arguments are equal, the
--   <tt>representational</tt> type arguments can differ, but need to have
--   a <tt>Coercible</tt> instance themself, and the <tt>phantom</tt> type
--   arguments can be changed arbitrarily.
--   
--   The third kind of instance exists for every <tt>newtype NT = MkNT
--   T</tt> and comes in two variants, namely
--   
--   <pre>
--   instance Coercible a T =&gt; Coercible a NT
--   </pre>
--   
--   <pre>
--   instance Coercible T b =&gt; Coercible NT b
--   </pre>
--   
--   This instance is only usable if the constructor <tt>MkNT</tt> is in
--   scope.
--   
--   If, as a library author of a type constructor like <tt>Set a</tt>, you
--   want to prevent a user of your module to write <tt>coerce :: Set T
--   -&gt; Set NT</tt>, you need to set the role of <tt>Set</tt>'s type
--   parameter to <tt>nominal</tt>, by writing
--   
--   <pre>
--   type role Set nominal
--   </pre>
--   
--   For more details about this feature, please refer to <a>Safe
--   Coercions</a> by Joachim Breitner, Richard A. Eisenberg, Simon Peyton
--   Jones and Stephanie Weirich.
class a ~R# b => Coercible (a :: k0) (b :: k0)

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

-- | The kind of constraints, like <tt>Show a</tt>
data Constraint

-- | <a>Proxy</a> is a type that holds no data, but has a phantom parameter
--   of arbitrary type (or even kind). Its use is to provide type
--   information, even though there is no value available of that type (or
--   it may be too costly to create one).
--   
--   Historically, <tt><a>Proxy</a> :: <a>Proxy</a> a</tt> is a safer
--   alternative to the <tt>'undefined :: a'</tt> idiom.
--   
--   <pre>
--   &gt;&gt;&gt; Proxy :: Proxy (Void, Int -&gt; Int)
--   Proxy
--   </pre>
--   
--   Proxy can even hold types of higher kinds,
--   
--   <pre>
--   &gt;&gt;&gt; Proxy :: Proxy Either
--   Proxy
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; Proxy :: Proxy Functor
--   Proxy
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; Proxy :: Proxy complicatedStructure
--   Proxy
--   </pre>
data Proxy (t :: k) :: forall k. () => k -> *
Proxy :: Proxy

-- | The class <a>Typeable</a> allows a concrete representation of a type
--   to be calculated.
class Typeable (a :: k)

-- | If <a>Void</a> is uninhabited then any <a>Functor</a> that holds only
--   values of type <a>Void</a> is holding no values.
vacuous :: Functor f => f Void -> f a

-- | Since <a>Void</a> values logically don't exist, this witnesses the
--   logical reasoning tool of "ex falso quodlibet".
--   
--   <pre>
--   &gt;&gt;&gt; let x :: Either Void Int; x = Right 5
--   
--   &gt;&gt;&gt; :{
--   case x of
--       Right r -&gt; r
--       Left l  -&gt; absurd l
--   :}
--   5
--   </pre>
absurd :: () => Void -> a

-- | Uninhabited data type
data Void

-- | The value of <tt>seq a b</tt> is bottom if <tt>a</tt> is bottom, and
--   otherwise equal to <tt>b</tt>. In other words, it evaluates the first
--   argument <tt>a</tt> to weak head normal form (WHNF). <tt>seq</tt> is
--   usually introduced to improve performance by avoiding unneeded
--   laziness.
--   
--   A note on evaluation order: the expression <tt>seq a b</tt> does
--   <i>not</i> guarantee that <tt>a</tt> will be evaluated before
--   <tt>b</tt>. The only guarantee given by <tt>seq</tt> is that the both
--   <tt>a</tt> and <tt>b</tt> will be evaluated before <tt>seq</tt>
--   returns a value. In particular, this means that <tt>b</tt> may be
--   evaluated before <tt>a</tt>. If you need to guarantee a specific order
--   of evaluation, you must use the function <tt>pseq</tt> from the
--   "parallel" package.
seq :: () => a -> b -> b
maxInt :: Int
minInt :: Int

-- | <a>asTypeOf</a> is a type-restricted version of <a>const</a>. It is
--   usually used as an infix operator, and its typing forces its first
--   argument (which is usually overloaded) to have the same type as the
--   second.
asTypeOf :: () => a -> a -> a

-- | The <a>fromEnum</a> method restricted to the type <a>Char</a>.
ord :: Char -> Int

-- | A <a>String</a> is a list of characters. String constants in Haskell
--   are values of type <a>String</a>.
type String = [Char]

-- | The <a>Bounded</a> class is used to name the upper and lower limits of
--   a type. <a>Ord</a> is not a superclass of <a>Bounded</a> since types
--   that are not totally ordered may also have upper and lower bounds.
--   
--   The <a>Bounded</a> class may be derived for any enumeration type;
--   <a>minBound</a> is the first constructor listed in the <tt>data</tt>
--   declaration and <a>maxBound</a> is the last. <a>Bounded</a> may also
--   be derived for single-constructor datatypes whose constituent types
--   are in <a>Bounded</a>.
class Bounded a
minBound :: Bounded a => a
maxBound :: Bounded a => a

-- | Class <a>Enum</a> defines operations on sequentially ordered types.
--   
--   The <tt>enumFrom</tt>... methods are used in Haskell's translation of
--   arithmetic sequences.
--   
--   Instances of <a>Enum</a> may be derived for any enumeration type
--   (types whose constructors have no fields). The nullary constructors
--   are assumed to be numbered left-to-right by <a>fromEnum</a> from
--   <tt>0</tt> through <tt>n-1</tt>. See Chapter 10 of the <i>Haskell
--   Report</i> for more details.
--   
--   For any type that is an instance of class <a>Bounded</a> as well as
--   <a>Enum</a>, the following should hold:
--   
--   <ul>
--   <li>The calls <tt><a>succ</a> <a>maxBound</a></tt> and <tt><a>pred</a>
--   <a>minBound</a></tt> should result in a runtime error.</li>
--   <li><a>fromEnum</a> and <a>toEnum</a> should give a runtime error if
--   the result value is not representable in the result type. For example,
--   <tt><a>toEnum</a> 7 :: <a>Bool</a></tt> is an error.</li>
--   <li><a>enumFrom</a> and <a>enumFromThen</a> should be defined with an
--   implicit bound, thus:</li>
--   </ul>
--   
--   <pre>
--   enumFrom     x   = enumFromTo     x maxBound
--   enumFromThen x y = enumFromThenTo x y bound
--     where
--       bound | fromEnum y &gt;= fromEnum x = maxBound
--             | otherwise                = minBound
--   </pre>
class Enum a

-- | the successor of a value. For numeric types, <a>succ</a> adds 1.
succ :: Enum a => a -> a

-- | the predecessor of a value. For numeric types, <a>pred</a> subtracts
--   1.
pred :: Enum a => a -> a

-- | Convert from an <a>Int</a>.
toEnum :: Enum a => Int -> a

-- | Convert to an <a>Int</a>. It is implementation-dependent what
--   <a>fromEnum</a> returns when applied to a value that is too large to
--   fit in an <a>Int</a>.
fromEnum :: Enum a => a -> Int

-- | Used in Haskell's translation of <tt>[n..]</tt>.
enumFrom :: Enum a => a -> [a]

-- | Used in Haskell's translation of <tt>[n,n'..]</tt>.
enumFromThen :: Enum a => a -> a -> [a]

-- | Used in Haskell's translation of <tt>[n..m]</tt>.
enumFromTo :: Enum a => a -> a -> [a]

-- | Used in Haskell's translation of <tt>[n,n'..m]</tt>.
enumFromThenTo :: Enum a => a -> a -> a -> [a]
boundedEnumFromThen :: (Enum a, Bounded a) => a -> a -> [a]
boundedEnumFrom :: (Enum a, Bounded a) => a -> [a]

-- | Trigonometric and hyperbolic functions and related functions.
class Fractional a => Floating a
pi :: Floating a => a
exp :: Floating a => a -> a
sqrt :: Floating a => a -> a
(**) :: Floating a => a -> a -> a
logBase :: Floating a => a -> a -> a
sin :: Floating a => a -> a
cos :: Floating a => a -> a
tan :: Floating a => a -> a
asin :: Floating a => a -> a
acos :: Floating a => a -> a
atan :: Floating a => a -> a
sinh :: Floating a => a -> a
cosh :: Floating a => a -> a
tanh :: Floating a => a -> a
asinh :: Floating a => a -> a
acosh :: Floating a => a -> a
atanh :: Floating a => a -> a

-- | Double-precision floating point numbers. It is desirable that this
--   type be at least equal in range and precision to the IEEE
--   double-precision type.
data Double
D# :: Double# -> Double

-- | Single-precision floating point numbers. It is desirable that this
--   type be at least equal in range and precision to the IEEE
--   single-precision type.
data Float
F# :: Float# -> Float

-- | Representable types of kind <tt>*</tt>. This class is derivable in GHC
--   with the <tt>DeriveGeneric</tt> flag on.
--   
--   A <a>Generic</a> instance must satisfy the following laws:
--   
--   <pre>
--   <a>from</a> . <a>to</a> ≡ <tt>id</tt>
--   <a>to</a> . <a>from</a> ≡ <tt>id</tt>
--   </pre>
class Generic a

-- | Basic numeric class.
class Num a
(+) :: Num a => a -> a -> a
(-) :: Num a => a -> a -> a
(*) :: Num a => a -> a -> a

-- | Unary negation.
negate :: Num a => a -> a

-- | Absolute value.
abs :: Num a => a -> a

-- | Sign of a number. The functions <a>abs</a> and <a>signum</a> should
--   satisfy the law:
--   
--   <pre>
--   abs x * signum x == x
--   </pre>
--   
--   For real numbers, the <a>signum</a> is either <tt>-1</tt> (negative),
--   <tt>0</tt> (zero) or <tt>1</tt> (positive).
signum :: Num a => a -> a

-- | Conversion from an <a>Integer</a>. An integer literal represents the
--   application of the function <a>fromInteger</a> to the appropriate
--   value of type <a>Integer</a>, so such literals have type
--   <tt>(<a>Num</a> a) =&gt; a</tt>.
fromInteger :: Num a => Integer -> a

-- | Invariant: <a>Jn#</a> and <a>Jp#</a> are used iff value doesn't fit in
--   <a>S#</a>
--   
--   Useful properties resulting from the invariants:
--   
--   <ul>
--   <li><pre>abs (<a>S#</a> _) &lt;= abs (<a>Jp#</a> _)</pre></li>
--   <li><pre>abs (<a>S#</a> _) &lt; abs (<a>Jn#</a> _)</pre></li>
--   </ul>
data Integer

-- | the same as <tt><a>flip</a> (<a>-</a>)</tt>.
--   
--   Because <tt>-</tt> is treated specially in the Haskell grammar,
--   <tt>(-</tt> <i>e</i><tt>)</tt> is not a section, but an application of
--   prefix negation. However, <tt>(<a>subtract</a></tt>
--   <i>exp</i><tt>)</tt> is equivalent to the disallowed section.
subtract :: Num a => a -> a -> a

-- | general coercion from integral types
fromIntegral :: (Integral a, Num b) => a -> b

-- | general coercion to fractional types
realToFrac :: (Real a, Fractional b) => a -> b

-- | Fractional numbers, supporting real division.
class Num a => Fractional a

-- | fractional division
(/) :: Fractional a => a -> a -> a

-- | reciprocal fraction
recip :: Fractional a => a -> a

-- | Conversion from a <a>Rational</a> (that is <tt><a>Ratio</a>
--   <a>Integer</a></tt>). A floating literal stands for an application of
--   <a>fromRational</a> to a value of type <a>Rational</a>, so such
--   literals have type <tt>(<a>Fractional</a> a) =&gt; a</tt>.
fromRational :: Fractional a => Rational -> a

-- | Integral numbers, supporting integer division.
class (Real a, Enum a) => Integral a

-- | integer division truncated toward zero
quot :: Integral a => a -> a -> a

-- | integer remainder, satisfying
--   
--   <pre>
--   (x `quot` y)*y + (x `rem` y) == x
--   </pre>
rem :: Integral a => a -> a -> a

-- | integer division truncated toward negative infinity
div :: Integral a => a -> a -> a

-- | integer modulus, satisfying
--   
--   <pre>
--   (x `div` y)*y + (x `mod` y) == x
--   </pre>
mod :: Integral a => a -> a -> a

-- | simultaneous <a>quot</a> and <a>rem</a>
quotRem :: Integral a => a -> a -> (a, a)

-- | simultaneous <a>div</a> and <a>mod</a>
divMod :: Integral a => a -> a -> (a, a)

-- | conversion to <a>Integer</a>
toInteger :: Integral a => a -> Integer
class (Num a, Ord a) => Real a

-- | the rational equivalent of its real argument with full precision
toRational :: Real a => a -> Rational

-- | Extracting components of fractions.
class (Real a, Fractional a) => RealFrac a

-- | The function <a>properFraction</a> takes a real fractional number
--   <tt>x</tt> and returns a pair <tt>(n,f)</tt> such that <tt>x =
--   n+f</tt>, and:
--   
--   <ul>
--   <li><tt>n</tt> is an integral number with the same sign as <tt>x</tt>;
--   and</li>
--   <li><tt>f</tt> is a fraction with the same type and sign as
--   <tt>x</tt>, and with absolute value less than <tt>1</tt>.</li>
--   </ul>
--   
--   The default definitions of the <a>ceiling</a>, <a>floor</a>,
--   <a>truncate</a> and <a>round</a> functions are in terms of
--   <a>properFraction</a>.
properFraction :: (RealFrac a, Integral b) => a -> (b, a)

-- | <tt><a>truncate</a> x</tt> returns the integer nearest <tt>x</tt>
--   between zero and <tt>x</tt>
truncate :: (RealFrac a, Integral b) => a -> b

-- | <tt><a>round</a> x</tt> returns the nearest integer to <tt>x</tt>; the
--   even integer if <tt>x</tt> is equidistant between two integers
round :: (RealFrac a, Integral b) => a -> b

-- | <tt><a>ceiling</a> x</tt> returns the least integer not less than
--   <tt>x</tt>
ceiling :: (RealFrac a, Integral b) => a -> b

-- | <tt><a>floor</a> x</tt> returns the greatest integer not greater than
--   <tt>x</tt>
floor :: (RealFrac a, Integral b) => a -> b

-- | Rational numbers, with numerator and denominator of some
--   <a>Integral</a> type.
data Ratio a
(:%) :: !a -> !a -> Ratio a

-- | Arbitrary-precision rational numbers, represented as a ratio of two
--   <a>Integer</a> values. A rational number may be constructed using the
--   <a>%</a> operator.
type Rational = Ratio Integer
integralEnumFromThenTo :: Integral a => a -> a -> a -> [a]
integralEnumFromTo :: Integral a => a -> a -> [a]
integralEnumFromThen :: (Integral a, Bounded a) => a -> a -> [a]
integralEnumFrom :: (Integral a, Bounded a) => a -> [a]
gcdWord' :: Word -> Word -> Word
gcdInt' :: Int -> Int -> Int
(^^%^^) :: Integral a => Rational -> a -> Rational
(^%^) :: Integral a => Rational -> a -> Rational
numericEnumFromThenTo :: (Ord a, Fractional a) => a -> a -> a -> [a]
numericEnumFromTo :: (Ord a, Fractional a) => a -> a -> [a]
numericEnumFromThen :: Fractional a => a -> a -> [a]
numericEnumFrom :: Fractional a => a -> [a]
notANumber :: Rational
infinity :: Rational
ratioPrec1 :: Int
ratioPrec :: Int
overflowError :: () => a
ratioZeroDenominatorError :: () => a
divZeroError :: () => a

-- | <a>reduce</a> is a subsidiary function used only in this module. It
--   normalises a ratio by dividing both numerator and denominator by their
--   greatest common divisor.
reduce :: Integral a => a -> a -> Ratio a

-- | <tt><a>lcm</a> x y</tt> is the smallest positive integer that both
--   <tt>x</tt> and <tt>y</tt> divide.
lcm :: Integral a => a -> a -> a

-- | <tt><a>gcd</a> x y</tt> is the non-negative factor of both <tt>x</tt>
--   and <tt>y</tt> of which every common factor of <tt>x</tt> and
--   <tt>y</tt> is also a factor; for example <tt><a>gcd</a> 4 2 = 2</tt>,
--   <tt><a>gcd</a> (-4) 6 = 2</tt>, <tt><a>gcd</a> 0 4</tt> = <tt>4</tt>.
--   <tt><a>gcd</a> 0 0</tt> = <tt>0</tt>. (That is, the common divisor
--   that is "greatest" in the divisibility preordering.)
--   
--   Note: Since for signed fixed-width integer types, <tt><a>abs</a>
--   <a>minBound</a> &lt; 0</tt>, the result may be negative if one of the
--   arguments is <tt><a>minBound</a></tt> (and necessarily is if the other
--   is <tt>0</tt> or <tt><a>minBound</a></tt>) for such types.
gcd :: Integral a => a -> a -> a

-- | raise a number to an integral power
(^^) :: (Fractional a, Integral b) => a -> b -> a
infixr 8 ^^

-- | raise a number to a non-negative integral power
(^) :: (Num a, Integral b) => a -> b -> a
infixr 8 ^
odd :: Integral a => a -> Bool
even :: Integral a => a -> Bool

-- | Extract the denominator of the ratio in reduced form: the numerator
--   and denominator have no common factor and the denominator is positive.
denominator :: () => Ratio a -> a

-- | Extract the numerator of the ratio in reduced form: the numerator and
--   denominator have no common factor and the denominator is positive.
numerator :: () => Ratio a -> a

-- | Conversion of values to readable <a>String</a>s.
--   
--   Derived instances of <a>Show</a> have the following properties, which
--   are compatible with derived instances of <a>Read</a>:
--   
--   <ul>
--   <li>The result of <a>show</a> is a syntactically correct Haskell
--   expression containing only constants, given the fixity declarations in
--   force at the point where the type is declared. It contains only the
--   constructor names defined in the data type, parentheses, and spaces.
--   When labelled constructor fields are used, braces, commas, field
--   names, and equal signs are also used.</li>
--   <li>If the constructor is defined to be an infix operator, then
--   <a>showsPrec</a> will produce infix applications of the
--   constructor.</li>
--   <li>the representation will be enclosed in parentheses if the
--   precedence of the top-level constructor in <tt>x</tt> is less than
--   <tt>d</tt> (associativity is ignored). Thus, if <tt>d</tt> is
--   <tt>0</tt> then the result is never surrounded in parentheses; if
--   <tt>d</tt> is <tt>11</tt> it is always surrounded in parentheses,
--   unless it is an atomic expression.</li>
--   <li>If the constructor is defined using record syntax, then
--   <a>show</a> will produce the record-syntax form, with the fields given
--   in the same order as the original declaration.</li>
--   </ul>
--   
--   For example, given the declarations
--   
--   <pre>
--   infixr 5 :^:
--   data Tree a =  Leaf a  |  Tree a :^: Tree a
--   </pre>
--   
--   the derived instance of <a>Show</a> is equivalent to
--   
--   <pre>
--   instance (Show a) =&gt; Show (Tree a) where
--   
--          showsPrec d (Leaf m) = showParen (d &gt; app_prec) $
--               showString "Leaf " . showsPrec (app_prec+1) m
--            where app_prec = 10
--   
--          showsPrec d (u :^: v) = showParen (d &gt; up_prec) $
--               showsPrec (up_prec+1) u .
--               showString " :^: "      .
--               showsPrec (up_prec+1) v
--            where up_prec = 5
--   </pre>
--   
--   Note that right-associativity of <tt>:^:</tt> is ignored. For example,
--   
--   <ul>
--   <li><tt><a>show</a> (Leaf 1 :^: Leaf 2 :^: Leaf 3)</tt> produces the
--   string <tt>"Leaf 1 :^: (Leaf 2 :^: Leaf 3)"</tt>.</li>
--   </ul>
class Show a

-- | This class gives the integer associated with a type-level natural.
--   There are instances of the class for every concrete literal: 0, 1, 2,
--   etc.
class KnownNat (n :: Nat)

-- | (Kind) This is the kind of type-level natural numbers.
data Nat

-- | Comparison of type-level naturals, as a function.

-- | Convert an integer into an unknown type-level natural.
someNatVal :: Natural -> SomeNat

natVal :: KnownNat n => proxy n -> Natural

-- | This type represents unknown type-level natural numbers.
data SomeNat
[SomeNat] :: SomeNat
class IsLabel (x :: Symbol) a
fromLabel :: IsLabel x a => a

-- | Get a string representation of the current execution stack state.
showStackTrace :: IO Maybe String

-- | Get a trace of the current execution stack state.
--   
--   Returns <tt>Nothing</tt> if stack trace support isn't available on
--   host machine.
getStackTrace :: IO Maybe [Location]

-- | <a>CallStack</a>s are a lightweight method of obtaining a partial
--   call-stack at any point in the program.
--   
--   A function can request its call-site with the <a>HasCallStack</a>
--   constraint. For example, we can define
--   
--   <pre>
--   putStrLnWithCallStack :: HasCallStack =&gt; String -&gt; IO ()
--   </pre>
--   
--   as a variant of <tt>putStrLn</tt> that will get its call-site and
--   print it, along with the string given as argument. We can access the
--   call-stack inside <tt>putStrLnWithCallStack</tt> with
--   <a>callStack</a>.
--   
--   <pre>
--   putStrLnWithCallStack :: HasCallStack =&gt; String -&gt; IO ()
--   putStrLnWithCallStack msg = do
--     putStrLn msg
--     putStrLn (prettyCallStack callStack)
--   </pre>
--   
--   Thus, if we call <tt>putStrLnWithCallStack</tt> we will get a
--   formatted call-stack alongside our string.
--   
--   <pre>
--   &gt;&gt;&gt; putStrLnWithCallStack "hello"
--   hello
--   CallStack (from HasCallStack):
--     putStrLnWithCallStack, called at &lt;interactive&gt;:2:1 in interactive:Ghci1
--   </pre>
--   
--   GHC solves <a>HasCallStack</a> constraints in three steps:
--   
--   <ol>
--   <li>If there is a <a>CallStack</a> in scope -- i.e. the enclosing
--   function has a <a>HasCallStack</a> constraint -- GHC will append the
--   new call-site to the existing <a>CallStack</a>.</li>
--   <li>If there is no <a>CallStack</a> in scope -- e.g. in the GHCi
--   session above -- and the enclosing definition does not have an
--   explicit type signature, GHC will infer a <a>HasCallStack</a>
--   constraint for the enclosing definition (subject to the monomorphism
--   restriction).</li>
--   <li>If there is no <a>CallStack</a> in scope and the enclosing
--   definition has an explicit type signature, GHC will solve the
--   <a>HasCallStack</a> constraint for the singleton <a>CallStack</a>
--   containing just the current call-site.</li>
--   </ol>
--   
--   <a>CallStack</a>s do not interact with the RTS and do not require
--   compilation with <tt>-prof</tt>. On the other hand, as they are built
--   up explicitly via the <a>HasCallStack</a> constraints, they will
--   generally not contain as much information as the simulated call-stacks
--   maintained by the RTS.
--   
--   A <a>CallStack</a> is a <tt>[(String, SrcLoc)]</tt>. The
--   <tt>String</tt> is the name of function that was called, the
--   <a>SrcLoc</a> is the call-site. The list is ordered with the most
--   recently called function at the head.
--   
--   NOTE: The intrepid user may notice that <a>HasCallStack</a> is just an
--   alias for an implicit parameter <tt>?callStack :: CallStack</tt>. This
--   is an implementation detail and <b>should not</b> be considered part
--   of the <a>CallStack</a> API, we may decide to change the
--   implementation in the future.
data CallStack

-- | Perform some computation without adding new entries to the
--   <a>CallStack</a>.
withFrozenCallStack :: HasCallStack => HasCallStack -> a -> a

-- | Return the current <a>CallStack</a>.
--   
--   Does *not* include the call-site of <a>callStack</a>.
callStack :: HasCallStack -> CallStack

-- | Pretty print a <a>CallStack</a>.
prettyCallStack :: CallStack -> String

-- | Pretty print a <a>SrcLoc</a>.
prettySrcLoc :: SrcLoc -> String

-- | Returns a <tt>[String]</tt> representing the current call stack. This
--   can be useful for debugging.
--   
--   The implementation uses the call-stack simulation maintained by the
--   profiler, so it only works if the program was compiled with
--   <tt>-prof</tt> and contains suitable SCC annotations (e.g. by using
--   <tt>-fprof-auto</tt>). Otherwise, the list returned is likely to be
--   empty or uninformative.
currentCallStack :: IO [String]

-- | Extract a list of call-sites from the <a>CallStack</a>.
--   
--   The list is ordered by most recent call.
getCallStack :: CallStack -> [([Char], SrcLoc)]

-- | Request a CallStack.
--   
--   NOTE: The implicit parameter <tt>?callStack :: CallStack</tt> is an
--   implementation detail and <b>should not</b> be considered part of the
--   <a>CallStack</a> API, we may decide to change the implementation in
--   the future.
type HasCallStack = ?callStack :: CallStack

-- | 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 Relude.Bool.Reexport

-- | Conditional failure of <a>Alternative</a> computations. Defined by
--   
--   <pre>
--   guard True  = <a>pure</a> ()
--   guard False = <a>empty</a>
--   </pre>
--   
--   <h4><b>Examples</b></h4>
--   
--   Common uses of <a>guard</a> include conditionally signaling an error
--   in an error monad and conditionally rejecting the current choice in an
--   <a>Alternative</a>-based parser.
--   
--   As an example of signaling an error in the error monad <a>Maybe</a>,
--   consider a safe division function <tt>safeDiv x y</tt> that returns
--   <a>Nothing</a> when the denominator <tt>y</tt> is zero and
--   <tt><a>Just</a> (x `div` y)</tt> otherwise. For example:
--   
--   <pre>
--   &gt;&gt;&gt; safeDiv 4 0
--   Nothing
--   &gt;&gt;&gt; safeDiv 4 2
--   Just 2
--   </pre>
--   
--   A definition of <tt>safeDiv</tt> using guards, but not <a>guard</a>:
--   
--   <pre>
--   safeDiv :: Int -&gt; Int -&gt; Maybe Int
--   safeDiv x y | y /= 0    = Just (x `div` y)
--               | otherwise = Nothing
--   </pre>
--   
--   A definition of <tt>safeDiv</tt> using <a>guard</a> and <a>Monad</a>
--   <tt>do</tt>-notation:
--   
--   <pre>
--   safeDiv :: Int -&gt; Int -&gt; Maybe Int
--   safeDiv x y = do
--     guard (y /= 0)
--     return (x `div` y)
--   </pre>
guard :: Alternative f => Bool -> f ()

-- | The reverse of <a>when</a>.
unless :: Applicative f => Bool -> f () -> f ()

-- | Conditional execution of <a>Applicative</a> expressions. For example,
--   
--   <pre>
--   when debug (putStrLn "Debugging")
--   </pre>
--   
--   will output the string <tt>Debugging</tt> if the Boolean value
--   <tt>debug</tt> is <a>True</a>, and otherwise do nothing.
when :: Applicative f => Bool -> f () -> f ()

-- | <a>otherwise</a> is defined as the value <a>True</a>. It helps to make
--   guards more readable. eg.
--   
--   <pre>
--   f x | x &lt; 0     = ...
--       | otherwise = ...
--   </pre>
otherwise :: Bool
data Bool
False :: Bool
True :: Bool

-- | Case analysis for the <a>Bool</a> type. <tt><a>bool</a> x y p</tt>
--   evaluates to <tt>x</tt> when <tt>p</tt> is <a>False</a>, and evaluates
--   to <tt>y</tt> when <tt>p</tt> is <a>True</a>.
--   
--   This is equivalent to <tt>if p then y else x</tt>; that is, one can
--   think of it as an if-then-else construct with its arguments reordered.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; bool "foo" "bar" True
--   "bar"
--   
--   &gt;&gt;&gt; bool "foo" "bar" False
--   "foo"
--   </pre>
--   
--   Confirm that <tt><a>bool</a> x y p</tt> and <tt>if p then y else
--   x</tt> are equivalent:
--   
--   <pre>
--   &gt;&gt;&gt; let p = True; x = "bar"; y = "foo"
--   
--   &gt;&gt;&gt; bool x y p == if p then y else x
--   True
--   
--   &gt;&gt;&gt; let p = False
--   
--   &gt;&gt;&gt; bool x y p == if p then y else x
--   True
--   </pre>
bool :: () => a -> a -> Bool -> a

-- | Boolean "and"
(&&) :: Bool -> Bool -> Bool
infixr 3 &&

-- | Boolean "or"
(||) :: Bool -> Bool -> Bool
infixr 2 ||

-- | Boolean "not"
not :: Bool -> Bool


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

-- | The class of types that can be converted to a hash value.
--   
--   Minimal implementation: <a>hashWithSalt</a>.
class Hashable a

-- | Return a hash value for the argument, using the given salt.
--   
--   The general contract of <a>hashWithSalt</a> is:
--   
--   <ul>
--   <li>If two values are equal according to the <a>==</a> method, then
--   applying the <a>hashWithSalt</a> method on each of the two values
--   <i>must</i> produce the same integer result if the same salt is used
--   in each case.</li>
--   <li>It is <i>not</i> required that if two values are unequal according
--   to the <a>==</a> method, then applying the <a>hashWithSalt</a> method
--   on each of the two values must produce distinct integer results.
--   However, the programmer should be aware that producing distinct
--   integer results for unequal values may improve the performance of
--   hashing-based data structures.</li>
--   <li>This method can be used to compute different hash values for the
--   same input by providing a different salt in each application of the
--   method. This implies that any instance that defines
--   <a>hashWithSalt</a> <i>must</i> make use of the salt in its
--   implementation.</li>
--   </ul>
hashWithSalt :: Hashable a => Int -> a -> Int

-- | A map from keys to values. A map cannot contain duplicate keys; each
--   key can map to at most one value.
data HashMap k v

-- | A set of values. A set cannot contain duplicate values.
data HashSet a

-- | A map of integers to values <tt>a</tt>.
data IntMap a

-- | A set of integers.
data IntSet

-- | A Map from keys <tt>k</tt> to values <tt>a</tt>.
data Map k a

-- | General-purpose finite sequences.
data Seq a

-- | A set of values <tt>a</tt>.
data Set a

-- | Extract the first component of a pair.
fst :: () => (a, b) -> a

-- | Extract the second component of a pair.
snd :: () => (a, b) -> b

-- | Swap the components of a pair.
swap :: () => (a, b) -> (b, a)

-- | <a>uncurry</a> converts a curried function to a function on pairs.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; uncurry (+) (1,2)
--   3
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; uncurry ($) (show, 1)
--   "1"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; map (uncurry max) [(1,2), (3,4), (6,8)]
--   [2,4,8]
--   </pre>
uncurry :: () => a -> b -> c -> (a, b) -> c

-- | <a>curry</a> converts an uncurried function to a curried function.
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; curry fst 1 2
--   1
--   </pre>
curry :: () => (a, b) -> c -> a -> b -> c

-- | The <a>IsList</a> class and its methods are intended to be used in
--   conjunction with the OverloadedLists extension.
class IsList l

-- | The <a>fromList</a> function constructs the structure <tt>l</tt> from
--   the given list of <tt>Item l</tt>
fromList :: IsList l => [Item l] -> l

-- | The <a>fromListN</a> function takes the input list's length as a hint.
--   Its behaviour should be equivalent to <a>fromList</a>. The hint can be
--   used to construct the structure <tt>l</tt> more efficiently compared
--   to <a>fromList</a>. If the given hint does not equal to the input
--   list's length the behaviour of <a>fromListN</a> is not specified.
fromListN :: IsList l => Int -> [Item l] -> l


-- | Typeclass for creating structures from singleton element.
module Relude.Container.One

-- | Type class for types that can be created from one element.
--   <tt>singleton</tt> is lone name for this function. 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, <tt>Text</tt>, etc from a single element.
one :: One x => OneItem x -> x
instance Relude.Container.One.One [a]
instance Relude.Container.One.One (GHC.Base.NonEmpty a)
instance Relude.Container.One.One (Data.Sequence.Internal.Seq a)
instance Relude.Container.One.One Data.Text.Internal.Text
instance Relude.Container.One.One Data.Text.Internal.Lazy.Text
instance Relude.Container.One.One Data.ByteString.Internal.ByteString
instance Relude.Container.One.One Data.ByteString.Lazy.Internal.ByteString
instance Relude.Container.One.One (Data.Map.Internal.Map k v)
instance Data.Hashable.Class.Hashable k => Relude.Container.One.One (Data.HashMap.Base.HashMap k v)
instance Relude.Container.One.One (Data.IntMap.Internal.IntMap v)
instance Relude.Container.One.One (Data.Set.Internal.Set v)
instance Data.Hashable.Class.Hashable v => Relude.Container.One.One (Data.HashSet.HashSet v)
instance Relude.Container.One.One Data.IntSet.Internal.IntSet


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

module Relude.Foldable.Reexport

-- | Data structures that can be folded.
--   
--   For example, given a data type
--   
--   <pre>
--   data Tree a = Empty | Leaf a | Node (Tree a) a (Tree a)
--   </pre>
--   
--   a suitable instance would be
--   
--   <pre>
--   instance Foldable Tree where
--      foldMap f Empty = mempty
--      foldMap f (Leaf x) = f x
--      foldMap f (Node l k r) = foldMap f l `mappend` f k `mappend` foldMap f r
--   </pre>
--   
--   This is suitable even for abstract types, as the monoid is assumed to
--   satisfy the monoid laws. Alternatively, one could define
--   <tt>foldr</tt>:
--   
--   <pre>
--   instance Foldable Tree where
--      foldr f z Empty = z
--      foldr f z (Leaf x) = f x z
--      foldr f z (Node l k r) = foldr f (f k (foldr f z r)) l
--   </pre>
--   
--   <tt>Foldable</tt> instances are expected to satisfy the following
--   laws:
--   
--   <pre>
--   foldr f z t = appEndo (foldMap (Endo . f) t ) z
--   </pre>
--   
--   <pre>
--   foldl f z t = appEndo (getDual (foldMap (Dual . Endo . flip f) t)) z
--   </pre>
--   
--   <pre>
--   fold = foldMap id
--   </pre>
--   
--   <pre>
--   length = getSum . foldMap (Sum . const  1)
--   </pre>
--   
--   <tt>sum</tt>, <tt>product</tt>, <tt>maximum</tt>, and <tt>minimum</tt>
--   should all be essentially equivalent to <tt>foldMap</tt> forms, such
--   as
--   
--   <pre>
--   sum = getSum . foldMap Sum
--   </pre>
--   
--   but may be less defined.
--   
--   If the type is also a <a>Functor</a> instance, it should satisfy
--   
--   <pre>
--   foldMap f = fold . fmap f
--   </pre>
--   
--   which implies that
--   
--   <pre>
--   foldMap f . fmap g = foldMap (f . g)
--   </pre>
class Foldable (t :: * -> *)

-- | Combine the elements of a structure using a monoid.
fold :: (Foldable t, Monoid m) => t m -> m

-- | Map each element of the structure to a monoid, and combine the
--   results.
foldMap :: (Foldable t, Monoid m) => a -> m -> t a -> m

-- | Right-associative fold of a structure.
--   
--   In the case of lists, <a>foldr</a>, when applied to a binary operator,
--   a starting value (typically the right-identity of the operator), and a
--   list, reduces the list using the binary operator, from right to left:
--   
--   <pre>
--   foldr f z [x1, x2, ..., xn] == x1 `f` (x2 `f` ... (xn `f` z)...)
--   </pre>
--   
--   Note that, since the head of the resulting expression is produced by
--   an application of the operator to the first element of the list,
--   <a>foldr</a> can produce a terminating expression from an infinite
--   list.
--   
--   For a general <a>Foldable</a> structure this should be semantically
--   identical to,
--   
--   <pre>
--   foldr f z = <a>foldr</a> f z . <a>toList</a>
--   </pre>
foldr :: Foldable t => a -> b -> b -> b -> t a -> b

-- | Left-associative fold of a structure but with strict application of
--   the operator.
--   
--   This ensures that each step of the fold is forced to weak head normal
--   form before being applied, avoiding the collection of thunks that
--   would otherwise occur. This is often what you want to strictly reduce
--   a finite list to a single, monolithic result (e.g. <a>length</a>).
--   
--   For a general <a>Foldable</a> structure this should be semantically
--   identical to,
--   
--   <pre>
--   foldl f z = <a>foldl'</a> f z . <a>toList</a>
--   </pre>
foldl' :: Foldable t => b -> a -> b -> b -> t a -> b

-- | List of elements of a structure, from left to right.
toList :: Foldable t => t a -> [a]

-- | Test whether the structure is empty. The default implementation is
--   optimized for structures that are similar to cons-lists, because there
--   is no general way to do better.
null :: Foldable t => t a -> Bool

-- | Returns the size/length of a finite structure as an <a>Int</a>. The
--   default implementation is optimized for structures that are similar to
--   cons-lists, because there is no general way to do better.
length :: Foldable t => t a -> Int

-- | The <a>find</a> function takes a predicate and a structure and returns
--   the leftmost element of the structure matching the predicate, or
--   <a>Nothing</a> if there is no such element.
find :: Foldable t => a -> Bool -> t a -> Maybe a

-- | Determines whether all elements of the structure satisfy the
--   predicate.
all :: Foldable t => a -> Bool -> t a -> Bool

-- | Determines whether any element of the structure satisfies the
--   predicate.
any :: Foldable t => a -> Bool -> t a -> Bool

-- | <a>or</a> returns the disjunction of a container of Bools. For the
--   result to be <a>False</a>, the container must be finite; <a>True</a>,
--   however, results from a <a>True</a> value finitely far from the left
--   end.
or :: Foldable t => t Bool -> Bool

-- | <a>and</a> returns the conjunction of a container of Bools. For the
--   result to be <a>True</a>, the container must be finite; <a>False</a>,
--   however, results from a <a>False</a> value finitely far from the left
--   end.
and :: Foldable t => t Bool -> Bool

-- | Map a function over all the elements of a container and concatenate
--   the resulting lists.
concatMap :: Foldable t => a -> [b] -> t a -> [b]

-- | The concatenation of all the elements of a container of lists.
concat :: Foldable t => t [a] -> [a]

-- | The sum of a collection of actions, generalizing <a>concat</a>.
--   
--   asum [Just <a>Hello</a>, Nothing, Just <a>World</a>] Just <a>Hello</a>
asum :: (Foldable t, Alternative f) => t f a -> f a

-- | Evaluate each monadic action in the structure from left to right, and
--   ignore the results. For a version that doesn't ignore the results see
--   <a>sequence</a>.
--   
--   As of base 4.8.0.0, <a>sequence_</a> is just <a>sequenceA_</a>,
--   specialized to <a>Monad</a>.
sequence_ :: (Foldable t, Monad m) => t m a -> m ()

-- | Evaluate each action in the structure from left to right, and ignore
--   the results. For a version that doesn't ignore the results see
--   <a>sequenceA</a>.
sequenceA_ :: (Foldable t, Applicative f) => t f a -> f ()

-- | <a>forM_</a> is <a>mapM_</a> with its arguments flipped. For a version
--   that doesn't ignore the results see <a>forM</a>.
--   
--   As of base 4.8.0.0, <a>forM_</a> is just <a>for_</a>, specialized to
--   <a>Monad</a>.
forM_ :: (Foldable t, Monad m) => t a -> a -> m b -> m ()

-- | Map each element of a structure to a monadic action, evaluate these
--   actions from left to right, and ignore the results. For a version that
--   doesn't ignore the results see <a>mapM</a>.
--   
--   As of base 4.8.0.0, <a>mapM_</a> is just <a>traverse_</a>, specialized
--   to <a>Monad</a>.
mapM_ :: (Foldable t, Monad m) => a -> m b -> t a -> m ()

-- | <a>for_</a> is <a>traverse_</a> with its arguments flipped. For a
--   version that doesn't ignore the results see <a>for</a>.
--   
--   <pre>
--   &gt;&gt;&gt; for_ [1..4] print
--   1
--   2
--   3
--   4
--   </pre>
for_ :: (Foldable t, Applicative f) => t a -> a -> f b -> f ()

-- | Map each element of a structure to an action, evaluate these actions
--   from left to right, and ignore the results. For a version that doesn't
--   ignore the results see <a>traverse</a>.
traverse_ :: (Foldable t, Applicative f) => a -> f b -> t a -> f ()

-- | Monadic fold over the elements of a structure, associating to the
--   left, i.e. from left to right.
foldlM :: (Foldable t, Monad m) => b -> a -> m b -> b -> t a -> m b

-- | Functors representing data structures that can be traversed from left
--   to right.
--   
--   A definition of <a>traverse</a> must satisfy the following laws:
--   
--   <ul>
--   <li><i><i>naturality</i></i> <tt>t . <a>traverse</a> f =
--   <a>traverse</a> (t . f)</tt> for every applicative transformation
--   <tt>t</tt></li>
--   <li><i><i>identity</i></i> <tt><a>traverse</a> Identity =
--   Identity</tt></li>
--   <li><i><i>composition</i></i> <tt><a>traverse</a> (Compose .
--   <a>fmap</a> g . f) = Compose . <a>fmap</a> (<a>traverse</a> g) .
--   <a>traverse</a> f</tt></li>
--   </ul>
--   
--   A definition of <a>sequenceA</a> must satisfy the following laws:
--   
--   <ul>
--   <li><i><i>naturality</i></i> <tt>t . <a>sequenceA</a> =
--   <a>sequenceA</a> . <a>fmap</a> t</tt> for every applicative
--   transformation <tt>t</tt></li>
--   <li><i><i>identity</i></i> <tt><a>sequenceA</a> . <a>fmap</a> Identity
--   = Identity</tt></li>
--   <li><i><i>composition</i></i> <tt><a>sequenceA</a> . <a>fmap</a>
--   Compose = Compose . <a>fmap</a> <a>sequenceA</a> .
--   <a>sequenceA</a></tt></li>
--   </ul>
--   
--   where an <i>applicative transformation</i> is a function
--   
--   <pre>
--   t :: (Applicative f, Applicative g) =&gt; f a -&gt; g a
--   </pre>
--   
--   preserving the <a>Applicative</a> operations, i.e.
--   
--   <ul>
--   <li><pre>t (<a>pure</a> x) = <a>pure</a> x</pre></li>
--   <li><pre>t (x <a>&lt;*&gt;</a> y) = t x <a>&lt;*&gt;</a> t
--   y</pre></li>
--   </ul>
--   
--   and the identity functor <tt>Identity</tt> and composition of functors
--   <tt>Compose</tt> are defined as
--   
--   <pre>
--   newtype Identity a = Identity a
--   
--   instance Functor Identity where
--     fmap f (Identity x) = Identity (f x)
--   
--   instance Applicative Identity where
--     pure x = Identity x
--     Identity f &lt;*&gt; Identity x = Identity (f x)
--   
--   newtype Compose f g a = Compose (f (g a))
--   
--   instance (Functor f, Functor g) =&gt; Functor (Compose f g) where
--     fmap f (Compose x) = Compose (fmap (fmap f) x)
--   
--   instance (Applicative f, Applicative g) =&gt; Applicative (Compose f g) where
--     pure x = Compose (pure (pure x))
--     Compose f &lt;*&gt; Compose x = Compose ((&lt;*&gt;) &lt;$&gt; f &lt;*&gt; x)
--   </pre>
--   
--   (The naturality law is implied by parametricity.)
--   
--   Instances are similar to <a>Functor</a>, e.g. given a data type
--   
--   <pre>
--   data Tree a = Empty | Leaf a | Node (Tree a) a (Tree a)
--   </pre>
--   
--   a suitable instance would be
--   
--   <pre>
--   instance Traversable Tree where
--      traverse f Empty = pure Empty
--      traverse f (Leaf x) = Leaf &lt;$&gt; f x
--      traverse f (Node l k r) = Node &lt;$&gt; traverse f l &lt;*&gt; f k &lt;*&gt; traverse f r
--   </pre>
--   
--   This is suitable even for abstract types, as the laws for
--   <a>&lt;*&gt;</a> imply a form of associativity.
--   
--   The superclass instances should satisfy the following:
--   
--   <ul>
--   <li>In the <a>Functor</a> instance, <a>fmap</a> should be equivalent
--   to traversal with the identity applicative functor
--   (<a>fmapDefault</a>).</li>
--   <li>In the <a>Foldable</a> instance, <a>foldMap</a> should be
--   equivalent to traversal with a constant applicative functor
--   (<a>foldMapDefault</a>).</li>
--   </ul>
class (Functor t, Foldable t) => Traversable (t :: * -> *)

-- | Map each element of a structure to an action, evaluate these actions
--   from left to right, and collect the results. For a version that
--   ignores the results see <a>traverse_</a>.
traverse :: (Traversable t, Applicative f) => a -> f b -> t a -> f t b

-- | Evaluate each action in the structure from left to right, and and
--   collect the results. For a version that ignores the results see
--   <a>sequenceA_</a>.
sequenceA :: (Traversable t, Applicative f) => t f a -> f t a

-- | Map each element of a structure to a monadic action, evaluate these
--   actions from left to right, and collect the results. For a version
--   that ignores the results see <a>mapM_</a>.
mapM :: (Traversable t, Monad m) => a -> m b -> t a -> m t b

-- | Evaluate each monadic action in the structure from left to right, and
--   collect the results. For a version that ignores the results see
--   <a>sequence_</a>.
sequence :: (Traversable t, Monad m) => t m a -> m t a

-- | The <a>mapAccumR</a> function behaves like a combination of
--   <a>fmap</a> and <tt>foldr</tt>; it applies a function to each element
--   of a structure, passing an accumulating parameter from right to left,
--   and returning a final value of this accumulator together with the new
--   structure.
mapAccumR :: Traversable t => a -> b -> (a, c) -> a -> t b -> (a, t c)

-- | The <a>mapAccumL</a> function behaves like a combination of
--   <a>fmap</a> and <tt>foldl</tt>; it applies a function to each element
--   of a structure, passing an accumulating parameter from left to right,
--   and returning a final value of this accumulator together with the new
--   structure.
mapAccumL :: Traversable t => a -> b -> (a, c) -> a -> t b -> (a, t c)

-- | <a>forM</a> is <a>mapM</a> with its arguments flipped. For a version
--   that ignores the results see <a>forM_</a>.
forM :: (Traversable t, Monad m) => t a -> a -> m b -> m t b


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

-- | Application operator. This operator is redundant, since ordinary
--   application <tt>(f x)</tt> means the same as <tt>(f <a>$</a> x)</tt>.
--   However, <a>$</a> has low, right-associative binding precedence, so it
--   sometimes allows parentheses to be omitted; for example:
--   
--   <pre>
--   f $ g $ h x  =  f (g (h x))
--   </pre>
--   
--   It is also useful in higher-order situations, such as <tt><a>map</a>
--   (<a>$</a> 0) xs</tt>, or <tt><a>zipWith</a> (<a>$</a>) fs xs</tt>.
($) :: () => a -> b -> a -> b
infixr 0 $

-- | <a>&amp;</a> is a reverse application operator. This provides
--   notational convenience. Its precedence is one higher than that of the
--   forward application operator <a>$</a>, which allows <a>&amp;</a> to be
--   nested in <a>$</a>.
--   
--   <pre>
--   &gt;&gt;&gt; 5 &amp; (+1) &amp; show
--   "6"
--   </pre>
(&) :: () => a -> a -> b -> b
infixl 1 &
on :: () => b -> b -> c -> a -> b -> a -> a -> c
infixl 0 `on`

-- | <tt><a>fix</a> f</tt> is the least fixed point of the function
--   <tt>f</tt>, i.e. the least defined <tt>x</tt> such that <tt>f x =
--   x</tt>.
--   
--   For example, we can write the factorial function using direct
--   recursion as
--   
--   <pre>
--   &gt;&gt;&gt; let fac n = if n &lt;= 1 then 1 else n * fac (n-1) in fac 5
--   120
--   </pre>
--   
--   This uses the fact that Haskell’s <tt>let</tt> introduces recursive
--   bindings. We can rewrite this definition using <a>fix</a>,
--   
--   <pre>
--   &gt;&gt;&gt; fix (\rec n -&gt; if n &lt;= 1 then 1 else n * rec (n-1)) 5
--   120
--   </pre>
--   
--   Instead of making a recursive call, we introduce a dummy parameter
--   <tt>rec</tt>; when used within <a>fix</a>, this parameter then refers
--   to <tt>fix'</tt> argument, hence the recursion is reintroduced.
fix :: () => a -> a -> a

-- | <tt><a>flip</a> f</tt> takes its (first) two arguments in the reverse
--   order of <tt>f</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; flip (++) "hello" "world"
--   "worldhello"
--   </pre>
flip :: () => a -> b -> c -> b -> a -> c

-- | Function composition.
(.) :: () => b -> c -> a -> b -> a -> c
infixr 9 .

-- | <tt>const x</tt> is a unary function which evaluates to <tt>x</tt> for
--   all inputs.
--   
--   <pre>
--   &gt;&gt;&gt; const 42 "hello"
--   42
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; map (const 42) [0..3]
--   [42,42,42,42]
--   </pre>
const :: () => a -> b -> a

-- | Identity function.
--   
--   <pre>
--   id x = x
--   </pre>
id :: () => a -> a

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


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

-- | Fanout: send the input to both argument arrows and combine their
--   output.
--   
--   The default definition may be overridden with a more efficient version
--   if desired.
(&&&) :: Arrow a => a b c -> a b c' -> a b (c, c')
infixr 3 &&&

-- | A bifunctor is a type constructor that takes two type arguments and is
--   a functor in <i>both</i> arguments. That is, unlike with
--   <a>Functor</a>, a type constructor such as <a>Either</a> does not need
--   to be partially applied for a <a>Bifunctor</a> instance, and the
--   methods in this class permit mapping functions over the <a>Left</a>
--   value or the <a>Right</a> value, or both at the same time.
--   
--   Formally, the class <a>Bifunctor</a> represents a bifunctor from
--   <tt>Hask</tt> -&gt; <tt>Hask</tt>.
--   
--   Intuitively it is a bifunctor where both the first and second
--   arguments are covariant.
--   
--   You can define a <a>Bifunctor</a> by either defining <a>bimap</a> or
--   by defining both <a>first</a> and <a>second</a>.
--   
--   If you supply <a>bimap</a>, you should ensure that:
--   
--   <pre>
--   <a>bimap</a> <a>id</a> <a>id</a> ≡ <a>id</a>
--   </pre>
--   
--   If you supply <a>first</a> and <a>second</a>, ensure:
--   
--   <pre>
--   <a>first</a> <a>id</a> ≡ <a>id</a>
--   <a>second</a> <a>id</a> ≡ <a>id</a>
--   </pre>
--   
--   If you supply both, you should also ensure:
--   
--   <pre>
--   <a>bimap</a> f g ≡ <a>first</a> f <a>.</a> <a>second</a> g
--   </pre>
--   
--   These ensure by parametricity:
--   
--   <pre>
--   <a>bimap</a>  (f <a>.</a> g) (h <a>.</a> i) ≡ <a>bimap</a> f h <a>.</a> <a>bimap</a> g i
--   <a>first</a>  (f <a>.</a> g) ≡ <a>first</a>  f <a>.</a> <a>first</a>  g
--   <a>second</a> (f <a>.</a> g) ≡ <a>second</a> f <a>.</a> <a>second</a> g
--   </pre>
class Bifunctor (p :: * -> * -> *)

-- | Map over both arguments at the same time.
--   
--   <pre>
--   <a>bimap</a> f g ≡ <a>first</a> f <a>.</a> <a>second</a> g
--   </pre>
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; bimap toUpper (+1) ('j', 3)
--   ('J',4)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; bimap toUpper (+1) (Left 'j')
--   Left 'J'
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; bimap toUpper (+1) (Right 3)
--   Right 4
--   </pre>
bimap :: Bifunctor p => a -> b -> c -> d -> p a c -> p b d

-- | Map covariantly over the first argument.
--   
--   <pre>
--   <a>first</a> f ≡ <a>bimap</a> f <a>id</a>
--   </pre>
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; first toUpper ('j', 3)
--   ('J',3)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; first toUpper (Left 'j')
--   Left 'J'
--   </pre>
first :: Bifunctor p => a -> b -> p a c -> p b c

-- | Map covariantly over the second argument.
--   
--   <pre>
--   <a>second</a> ≡ <a>bimap</a> <a>id</a>
--   </pre>
--   
--   <h4><b>Examples</b></h4>
--   
--   <pre>
--   &gt;&gt;&gt; second (+1) ('j', 3)
--   ('j',4)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; second (+1) (Right 3)
--   Right 4
--   </pre>
second :: Bifunctor p => b -> c -> p a b -> p a c

-- | The <a>Functor</a> class is used for types that can be mapped over.
--   Instances of <a>Functor</a> should satisfy the following laws:
--   
--   <pre>
--   fmap id  ==  id
--   fmap (f . g)  ==  fmap f . fmap g
--   </pre>
--   
--   The instances of <a>Functor</a> for lists, <a>Maybe</a> and <a>IO</a>
--   satisfy these laws.
class Functor (f :: * -> *)
fmap :: Functor f => a -> b -> f a -> f b

-- | Replace all locations in the input with the same value. The default
--   definition is <tt><a>fmap</a> . <a>const</a></tt>, but this may be
--   overridden with a more efficient version.
(<$) :: Functor f => a -> f b -> f a

-- | <tt><a>void</a> value</tt> discards or ignores the result of
--   evaluation, such as the return value of an <a>IO</a> action.
--   
--   <h4><b>Examples</b></h4>
--   
--   Replace the contents of a <tt><tt>Maybe</tt> <tt>Int</tt></tt> with
--   unit:
--   
--   <pre>
--   &gt;&gt;&gt; void Nothing
--   Nothing
--   
--   &gt;&gt;&gt; void (Just 3)
--   Just ()
--   </pre>
--   
--   Replace the contents of an <tt><tt>Either</tt> <tt>Int</tt>
--   <tt>Int</tt></tt> with unit, resulting in an <tt><tt>Either</tt>
--   <tt>Int</tt> '()'</tt>:
--   
--   <pre>
--   &gt;&gt;&gt; void (Left 8675309)
--   Left 8675309
--   
--   &gt;&gt;&gt; void (Right 8675309)
--   Right ()
--   </pre>
--   
--   Replace every element of a list with unit:
--   
--   <pre>
--   &gt;&gt;&gt; void [1,2,3]
--   [(),(),()]
--   </pre>
--   
--   Replace the second element of a pair with unit:
--   
--   <pre>
--   &gt;&gt;&gt; void (1,2)
--   (1,())
--   </pre>
--   
--   Discard the result of an <a>IO</a> action:
--   
--   <pre>
--   &gt;&gt;&gt; mapM print [1,2]
--   1
--   2
--   [(),()]
--   
--   &gt;&gt;&gt; void $ mapM print [1,2]
--   1
--   2
--   </pre>
void :: Functor f => f a -> f ()

-- | Flipped version of <a>&lt;$</a>.
--   
--   <h4><b>Examples</b></h4>
--   
--   Replace the contents of a <tt><tt>Maybe</tt> <tt>Int</tt></tt> with a
--   constant <tt>String</tt>:
--   
--   <pre>
--   &gt;&gt;&gt; Nothing $&gt; "foo"
--   Nothing
--   
--   &gt;&gt;&gt; Just 90210 $&gt; "foo"
--   Just "foo"
--   </pre>
--   
--   Replace the contents of an <tt><tt>Either</tt> <tt>Int</tt>
--   <tt>Int</tt></tt> with a constant <tt>String</tt>, resulting in an
--   <tt><tt>Either</tt> <tt>Int</tt> <tt>String</tt></tt>:
--   
--   <pre>
--   &gt;&gt;&gt; Left 8675309 $&gt; "foo"
--   Left 8675309
--   
--   &gt;&gt;&gt; Right 8675309 $&gt; "foo"
--   Right "foo"
--   </pre>
--   
--   Replace each element of a list with a constant <tt>String</tt>:
--   
--   <pre>
--   &gt;&gt;&gt; [1,2,3] $&gt; "foo"
--   ["foo","foo","foo"]
--   </pre>
--   
--   Replace the second element of a pair with a constant <tt>String</tt>:
--   
--   <pre>
--   &gt;&gt;&gt; (1,2) $&gt; "foo"
--   (1,"foo")
--   </pre>
($>) :: Functor f => f a -> b -> f b
infixl 4 $>

-- | An infix synonym for <a>fmap</a>.
--   
--   The name of this operator is an allusion to <tt>$</tt>. Note the
--   similarities between their types:
--   
--   <pre>
--    ($)  ::              (a -&gt; b) -&gt;   a -&gt;   b
--   (&lt;$&gt;) :: Functor f =&gt; (a -&gt; b) -&gt; f a -&gt; f b
--   </pre>
--   
--   Whereas <tt>$</tt> is function application, <a>&lt;$&gt;</a> is
--   function application lifted over a <a>Functor</a>.
--   
--   <h4><b>Examples</b></h4>
--   
--   Convert from a <tt><tt>Maybe</tt> <tt>Int</tt></tt> to a
--   <tt><tt>Maybe</tt> <tt>String</tt></tt> using <tt>show</tt>:
--   
--   <pre>
--   &gt;&gt;&gt; show &lt;$&gt; Nothing
--   Nothing
--   
--   &gt;&gt;&gt; show &lt;$&gt; Just 3
--   Just "3"
--   </pre>
--   
--   Convert from an <tt><tt>Either</tt> <tt>Int</tt> <tt>Int</tt></tt> to
--   an <tt><tt>Either</tt> <tt>Int</tt></tt> <tt>String</tt> using
--   <tt>show</tt>:
--   
--   <pre>
--   &gt;&gt;&gt; show &lt;$&gt; Left 17
--   Left 17
--   
--   &gt;&gt;&gt; show &lt;$&gt; Right 17
--   Right "17"
--   </pre>
--   
--   Double each element of a list:
--   
--   <pre>
--   &gt;&gt;&gt; (*2) &lt;$&gt; [1,2,3]
--   [2,4,6]
--   </pre>
--   
--   Apply <tt>even</tt> to the second element of a pair:
--   
--   <pre>
--   &gt;&gt;&gt; even &lt;$&gt; (2,2)
--   (2,True)
--   </pre>
(<$>) :: Functor f => a -> b -> f a -> f b
infixl 4 <$>

-- | Right-to-left composition of functors. The composition of applicative
--   functors is always applicative, but the composition of monads is not
--   always a monad.
newtype Compose (f :: k -> *) (g :: k1 -> k) (a :: k1) :: forall k k1. () => k -> * -> k1 -> k -> k1 -> *
Compose :: f g a -> Compose
[getCompose] :: Compose -> f g a

-- | Identity functor and monad. (a non-strict monad)
newtype Identity a
Identity :: a -> Identity a
[runIdentity] :: Identity a -> a


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

-- | 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 Relude.Functor


-- | Concurrency useful and common functions.
module Relude.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 <a>TVar</a> holding a value supplied
newTVar :: () => a -> STM TVar a

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

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


-- | Lifted versions of functions that work with exit processes.
module Relude.Lifted.Exit

-- | 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 Relude.Lifted.File

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

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

-- | 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 Relude.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 ()


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


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

-- | Append two lists, i.e.,
--   
--   <pre>
--   [x1, ..., xm] ++ [y1, ..., yn] == [x1, ..., xm, y1, ..., yn]
--   [x1, ..., xm] ++ [y1, ...] == [x1, ..., xm, y1, ...]
--   </pre>
--   
--   If the first list is not finite, the result is the first list.
(++) :: () => [a] -> [a] -> [a]
infixr 5 ++

-- | <a>filter</a>, applied to a predicate and a list, returns the list of
--   those elements that satisfy the predicate; i.e.,
--   
--   <pre>
--   filter p xs = [ x | x &lt;- xs, p x]
--   </pre>
filter :: () => a -> Bool -> [a] -> [a]

-- | <a>zip</a> takes two lists and returns a list of corresponding pairs.
--   If one input list is short, excess elements of the longer list are
--   discarded.
--   
--   <a>zip</a> is right-lazy:
--   
--   <pre>
--   zip [] _|_ = []
--   </pre>
zip :: () => [a] -> [b] -> [(a, b)]

-- | <a>map</a> <tt>f xs</tt> is the list obtained by applying <tt>f</tt>
--   to each element of <tt>xs</tt>, i.e.,
--   
--   <pre>
--   map f [x1, x2, ..., xn] == [f x1, f x2, ..., f xn]
--   map f [x1, x2, ...] == [f x1, f x2, ...]
--   </pre>
map :: () => a -> b -> [a] -> [b]

-- | The <a>unfoldr</a> function is a `dual' to <a>foldr</a>: while
--   <a>foldr</a> reduces a list to a summary value, <a>unfoldr</a> builds
--   a list from a seed value. The function takes the element and returns
--   <a>Nothing</a> if it is done producing the list or returns <a>Just</a>
--   <tt>(a,b)</tt>, in which case, <tt>a</tt> is a prepended to the list
--   and <tt>b</tt> is used as the next element in a recursive call. For
--   example,
--   
--   <pre>
--   iterate f == unfoldr (\x -&gt; Just (x, f x))
--   </pre>
--   
--   In some cases, <a>unfoldr</a> can undo a <a>foldr</a> operation:
--   
--   <pre>
--   unfoldr f' (foldr f z xs) == xs
--   </pre>
--   
--   if the following holds:
--   
--   <pre>
--   f' (f x y) = Just (x,y)
--   f' z       = Nothing
--   </pre>
--   
--   A simple use of unfoldr:
--   
--   <pre>
--   &gt;&gt;&gt; unfoldr (\b -&gt; if b == 0 then Nothing else Just (b, b-1)) 10
--   [10,9,8,7,6,5,4,3,2,1]
--   </pre>
unfoldr :: () => b -> Maybe (a, b) -> b -> [a]

-- | Sort a list by comparing the results of a key function applied to each
--   element. <tt>sortOn f</tt> is equivalent to <tt>sortBy (comparing
--   f)</tt>, but has the performance advantage of only evaluating
--   <tt>f</tt> once for each element in the input list. This is called the
--   decorate-sort-undecorate paradigm, or Schwartzian transform.
--   
--   Elements are arranged from from lowest to highest, keeping duplicates
--   in the order they appeared in the input.
--   
--   <pre>
--   &gt;&gt;&gt; sortOn fst [(2, "world"), (4, "!"), (1, "Hello")]
--   [(1,"Hello"),(2,"world"),(4,"!")]
--   </pre>
sortOn :: Ord b => a -> b -> [a] -> [a]

-- | The <a>sortBy</a> function is the non-overloaded version of
--   <a>sort</a>.
--   
--   <pre>
--   &gt;&gt;&gt; sortBy (\(a,_) (b,_) -&gt; compare a b) [(2, "world"), (4, "!"), (1, "Hello")]
--   [(1,"Hello"),(2,"world"),(4,"!")]
--   </pre>
sortBy :: () => a -> a -> Ordering -> [a] -> [a]

-- | The <a>sort</a> function implements a stable sorting algorithm. It is
--   a special case of <a>sortBy</a>, which allows the programmer to supply
--   their own comparison function.
--   
--   Elements are arranged from from lowest to highest, keeping duplicates
--   in the order they appeared in the input.
--   
--   <pre>
--   &gt;&gt;&gt; sort [1,6,4,3,2,5]
--   [1,2,3,4,5,6]
--   </pre>
sort :: Ord a => [a] -> [a]

-- | The <a>permutations</a> function returns the list of all permutations
--   of the argument.
--   
--   <pre>
--   &gt;&gt;&gt; permutations "abc"
--   ["abc","bac","cba","bca","cab","acb"]
--   </pre>
permutations :: () => [a] -> [[a]]

-- | The <a>subsequences</a> function returns the list of all subsequences
--   of the argument.
--   
--   <pre>
--   &gt;&gt;&gt; subsequences "abc"
--   ["","a","b","ab","c","ac","bc","abc"]
--   </pre>
subsequences :: () => [a] -> [[a]]

-- | The <a>tails</a> function returns all final segments of the argument,
--   longest first. For example,
--   
--   <pre>
--   &gt;&gt;&gt; tails "abc"
--   ["abc","bc","c",""]
--   </pre>
--   
--   Note that <a>tails</a> has the following strictness property:
--   <tt>tails _|_ = _|_ : _|_</tt>
tails :: () => [a] -> [[a]]

-- | The <a>inits</a> function returns all initial segments of the
--   argument, shortest first. For example,
--   
--   <pre>
--   &gt;&gt;&gt; inits "abc"
--   ["","a","ab","abc"]
--   </pre>
--   
--   Note that <a>inits</a> has the following strictness property:
--   <tt>inits (xs ++ _|_) = inits xs ++ _|_</tt>
--   
--   In particular, <tt>inits _|_ = [] : _|_</tt>
inits :: () => [a] -> [[a]]

-- | The <a>group</a> function takes a list and returns a list of lists
--   such that the concatenation of the result is equal to the argument.
--   Moreover, each sublist in the result contains only equal elements. For
--   example,
--   
--   <pre>
--   &gt;&gt;&gt; group "Mississippi"
--   ["M","i","ss","i","ss","i","pp","i"]
--   </pre>
--   
--   It is a special case of <a>groupBy</a>, which allows the programmer to
--   supply their own equality test.
group :: Eq a => [a] -> [[a]]

-- | The <a>genericReplicate</a> function is an overloaded version of
--   <a>replicate</a>, which accepts any <a>Integral</a> value as the
--   number of repetitions to make.
genericReplicate :: Integral i => i -> a -> [a]

-- | The <a>genericSplitAt</a> function is an overloaded version of
--   <a>splitAt</a>, which accepts any <a>Integral</a> value as the
--   position at which to split.
genericSplitAt :: Integral i => i -> [a] -> ([a], [a])

-- | The <a>genericDrop</a> function is an overloaded version of
--   <a>drop</a>, which accepts any <a>Integral</a> value as the number of
--   elements to drop.
genericDrop :: Integral i => i -> [a] -> [a]

-- | The <a>genericTake</a> function is an overloaded version of
--   <a>take</a>, which accepts any <a>Integral</a> value as the number of
--   elements to take.
genericTake :: Integral i => i -> [a] -> [a]

-- | The <a>genericLength</a> function is an overloaded version of
--   <a>length</a>. In particular, instead of returning an <a>Int</a>, it
--   returns any type which is an instance of <a>Num</a>. It is, however,
--   less efficient than <a>length</a>.
genericLength :: Num i => [a] -> i

-- | The <a>transpose</a> function transposes the rows and columns of its
--   argument. For example,
--   
--   <pre>
--   &gt;&gt;&gt; transpose [[1,2,3],[4,5,6]]
--   [[1,4],[2,5],[3,6]]
--   </pre>
--   
--   If some of the rows are shorter than the following rows, their
--   elements are skipped:
--   
--   <pre>
--   &gt;&gt;&gt; transpose [[10,11],[20],[],[30,31,32]]
--   [[10,20,30],[11,31],[32]]
--   </pre>
transpose :: () => [[a]] -> [[a]]

-- | <a>intercalate</a> <tt>xs xss</tt> is equivalent to <tt>(<a>concat</a>
--   (<a>intersperse</a> xs xss))</tt>. It inserts the list <tt>xs</tt> in
--   between the lists in <tt>xss</tt> and concatenates the result.
--   
--   <pre>
--   &gt;&gt;&gt; intercalate ", " ["Lorem", "ipsum", "dolor"]
--   "Lorem, ipsum, dolor"
--   </pre>
intercalate :: () => [a] -> [[a]] -> [a]

-- | The <a>intersperse</a> function takes an element and a list and
--   `intersperses' that element between the elements of the list. For
--   example,
--   
--   <pre>
--   &gt;&gt;&gt; intersperse ',' "abcde"
--   "a,b,c,d,e"
--   </pre>
intersperse :: () => a -> [a] -> [a]

-- | The <a>isPrefixOf</a> function takes two lists and returns <a>True</a>
--   iff the first list is a prefix of the second.
--   
--   <pre>
--   &gt;&gt;&gt; "Hello" `isPrefixOf` "Hello World!"
--   True
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; "Hello" `isPrefixOf` "Wello Horld!"
--   False
--   </pre>
isPrefixOf :: Eq a => [a] -> [a] -> Bool

-- | The <a>unzip3</a> function takes a list of triples and returns three
--   lists, analogous to <a>unzip</a>.
unzip3 :: () => [(a, b, c)] -> ([a], [b], [c])

-- | <a>unzip</a> transforms a list of pairs into a list of first
--   components and a list of second components.
unzip :: () => [(a, b)] -> ([a], [b])

-- | <a>zipWith</a> generalises <a>zip</a> by zipping with the function
--   given as the first argument, instead of a tupling function. For
--   example, <tt><a>zipWith</a> (+)</tt> is applied to two lists to
--   produce the list of corresponding sums.
--   
--   <a>zipWith</a> is right-lazy:
--   
--   <pre>
--   zipWith f [] _|_ = []
--   </pre>
zipWith :: () => a -> b -> c -> [a] -> [b] -> [c]

-- | <a>zip3</a> takes three lists and returns a list of triples, analogous
--   to <a>zip</a>.
zip3 :: () => [a] -> [b] -> [c] -> [(a, b, c)]

-- | <a>reverse</a> <tt>xs</tt> returns the elements of <tt>xs</tt> in
--   reverse order. <tt>xs</tt> must be finite.
reverse :: () => [a] -> [a]

-- | <a>break</a>, applied to a predicate <tt>p</tt> and a list
--   <tt>xs</tt>, returns a tuple where first element is longest prefix
--   (possibly empty) of <tt>xs</tt> of elements that <i>do not satisfy</i>
--   <tt>p</tt> and second element is the remainder of the list:
--   
--   <pre>
--   break (&gt; 3) [1,2,3,4,1,2,3,4] == ([1,2,3],[4,1,2,3,4])
--   break (&lt; 9) [1,2,3] == ([],[1,2,3])
--   break (&gt; 9) [1,2,3] == ([1,2,3],[])
--   </pre>
--   
--   <a>break</a> <tt>p</tt> is equivalent to <tt><a>span</a> (<a>not</a> .
--   p)</tt>.
break :: () => a -> Bool -> [a] -> ([a], [a])

-- | <a>splitAt</a> <tt>n xs</tt> returns a tuple where first element is
--   <tt>xs</tt> prefix of length <tt>n</tt> and second element is the
--   remainder of the list:
--   
--   <pre>
--   splitAt 6 "Hello World!" == ("Hello ","World!")
--   splitAt 3 [1,2,3,4,5] == ([1,2,3],[4,5])
--   splitAt 1 [1,2,3] == ([1],[2,3])
--   splitAt 3 [1,2,3] == ([1,2,3],[])
--   splitAt 4 [1,2,3] == ([1,2,3],[])
--   splitAt 0 [1,2,3] == ([],[1,2,3])
--   splitAt (-1) [1,2,3] == ([],[1,2,3])
--   </pre>
--   
--   It is equivalent to <tt>(<a>take</a> n xs, <a>drop</a> n xs)</tt> when
--   <tt>n</tt> is not <tt>_|_</tt> (<tt>splitAt _|_ xs = _|_</tt>).
--   <a>splitAt</a> is an instance of the more general
--   <a>genericSplitAt</a>, in which <tt>n</tt> may be of any integral
--   type.
splitAt :: () => Int -> [a] -> ([a], [a])

-- | <a>drop</a> <tt>n xs</tt> returns the suffix of <tt>xs</tt> after the
--   first <tt>n</tt> elements, or <tt>[]</tt> if <tt>n &gt; <a>length</a>
--   xs</tt>:
--   
--   <pre>
--   drop 6 "Hello World!" == "World!"
--   drop 3 [1,2,3,4,5] == [4,5]
--   drop 3 [1,2] == []
--   drop 3 [] == []
--   drop (-1) [1,2] == [1,2]
--   drop 0 [1,2] == [1,2]
--   </pre>
--   
--   It is an instance of the more general <a>genericDrop</a>, in which
--   <tt>n</tt> may be of any integral type.
drop :: () => Int -> [a] -> [a]

-- | <a>take</a> <tt>n</tt>, applied to a list <tt>xs</tt>, returns the
--   prefix of <tt>xs</tt> of length <tt>n</tt>, or <tt>xs</tt> itself if
--   <tt>n &gt; <a>length</a> xs</tt>:
--   
--   <pre>
--   take 5 "Hello World!" == "Hello"
--   take 3 [1,2,3,4,5] == [1,2,3]
--   take 3 [1,2] == [1,2]
--   take 3 [] == []
--   take (-1) [1,2] == []
--   take 0 [1,2] == []
--   </pre>
--   
--   It is an instance of the more general <a>genericTake</a>, in which
--   <tt>n</tt> may be of any integral type.
take :: () => Int -> [a] -> [a]

-- | <a>dropWhile</a> <tt>p xs</tt> returns the suffix remaining after
--   <a>takeWhile</a> <tt>p xs</tt>:
--   
--   <pre>
--   dropWhile (&lt; 3) [1,2,3,4,5,1,2,3] == [3,4,5,1,2,3]
--   dropWhile (&lt; 9) [1,2,3] == []
--   dropWhile (&lt; 0) [1,2,3] == [1,2,3]
--   </pre>
dropWhile :: () => a -> Bool -> [a] -> [a]

-- | <a>takeWhile</a>, applied to a predicate <tt>p</tt> and a list
--   <tt>xs</tt>, returns the longest prefix (possibly empty) of
--   <tt>xs</tt> of elements that satisfy <tt>p</tt>:
--   
--   <pre>
--   takeWhile (&lt; 3) [1,2,3,4,1,2,3,4] == [1,2]
--   takeWhile (&lt; 9) [1,2,3] == [1,2,3]
--   takeWhile (&lt; 0) [1,2,3] == []
--   </pre>
takeWhile :: () => a -> Bool -> [a] -> [a]

-- | <a>cycle</a> ties a finite list into a circular one, or equivalently,
--   the infinite repetition of the original list. It is the identity on
--   infinite lists.
cycle :: () => [a] -> [a]

-- | <a>replicate</a> <tt>n x</tt> is a list of length <tt>n</tt> with
--   <tt>x</tt> the value of every element. It is an instance of the more
--   general <a>genericReplicate</a>, in which <tt>n</tt> may be of any
--   integral type.
replicate :: () => Int -> a -> [a]

-- | <a>repeat</a> <tt>x</tt> is an infinite list, with <tt>x</tt> the
--   value of every element.
repeat :: () => a -> [a]

-- | <a>iterate</a> <tt>f x</tt> returns an infinite list of repeated
--   applications of <tt>f</tt> to <tt>x</tt>:
--   
--   <pre>
--   iterate f x == [x, f x, f (f x), ...]
--   </pre>
--   
--   Note that <a>iterate</a> is lazy, potentially leading to thunk
--   build-up if the consumer doesn't force each iterate. See 'iterate\''
--   for a strict variant of this function.
iterate :: () => a -> a -> a -> [a]

-- | <a>scanr</a> is the right-to-left dual of <a>scanl</a>. Note that
--   
--   <pre>
--   head (scanr f z xs) == foldr f z xs.
--   </pre>
scanr :: () => a -> b -> b -> b -> [a] -> [b]

-- | <a>scanl</a> is similar to <a>foldl</a>, but returns a list of
--   successive reduced values from the left:
--   
--   <pre>
--   scanl f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...]
--   </pre>
--   
--   Note that
--   
--   <pre>
--   last (scanl f z xs) == foldl f z xs.
--   </pre>
scanl :: () => b -> a -> b -> b -> [a] -> [b]

-- | Extract everything except the last element of the stream.
init :: () => NonEmpty a -> [a]

-- | Extract the last element of the stream.
last :: () => NonEmpty a -> a

-- | Extract the possibly-empty tail of the stream.
tail :: () => NonEmpty a -> [a]

-- | Extract the first element of the stream.
head :: () => NonEmpty a -> a

-- | <a>nonEmpty</a> efficiently turns a normal list into a <a>NonEmpty</a>
--   stream, producing <a>Nothing</a> if the input is empty.
nonEmpty :: () => [a] -> Maybe NonEmpty a

-- | Non-empty (and non-strict) list type.
data NonEmpty a
(:|) :: a -> [a] -> NonEmpty a

-- | The <a>sortWith</a> function sorts a list of elements using the user
--   supplied function to project something out of each element
sortWith :: Ord b => a -> b -> [a] -> [a]


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

-- | A monad transformer that adds exceptions to other monads.
--   
--   <tt>ExceptT</tt> constructs a monad parameterized over two things:
--   
--   <ul>
--   <li>e - The exception type.</li>
--   <li>m - The inner monad.</li>
--   </ul>
--   
--   The <a>return</a> function yields a computation that produces the
--   given value, while <tt>&gt;&gt;=</tt> sequences two subcomputations,
--   exiting on the first exception.
newtype ExceptT e (m :: * -> *) a
ExceptT :: m Either e a -> ExceptT e a

-- | The inverse of <a>ExceptT</a>.
runExceptT :: () => ExceptT e m a -> m Either e a

-- | Retrieves a function of the current environment.
asks :: MonadReader r m => r -> a -> m a

-- | See examples in <a>Control.Monad.Reader</a>. Note, the partially
--   applied function type <tt>(-&gt;) r</tt> is a simple reader monad. See
--   the <tt>instance</tt> declaration below.
class Monad m => MonadReader r (m :: * -> *) | m -> r

-- | Retrieves the monad environment.
ask :: MonadReader r m => m r

-- | Executes a computation in a modified environment.
local :: MonadReader r m => r -> r -> m a -> m a

-- | Retrieves a function of the current environment.
reader :: MonadReader r m => r -> a -> m a

-- | The reader monad transformer, which adds a read-only environment to
--   the given monad.
--   
--   The <a>return</a> function ignores the environment, while
--   <tt>&gt;&gt;=</tt> passes the inherited environment to both
--   subcomputations.
newtype ReaderT r (m :: k -> *) (a :: k) :: forall k. () => * -> k -> * -> k -> *
ReaderT :: r -> m a -> ReaderT r
[runReaderT] :: ReaderT r -> r -> m a

-- | The parameterizable reader monad.
--   
--   Computations are functions of a shared environment.
--   
--   The <a>return</a> function ignores the environment, while
--   <tt>&gt;&gt;=</tt> passes the inherited environment to both
--   subcomputations.
type Reader r = ReaderT r Identity

-- | Runs a <tt>Reader</tt> and extracts the final value from it. (The
--   inverse of <a>reader</a>.)
runReader :: () => Reader r a -> r -> a

-- | Gets specific component of the state, using a projection function
--   supplied.
gets :: MonadState s m => s -> a -> m a

-- | A variant of <a>modify</a> in which the computation is strict in the
--   new state.
modify' :: MonadState s m => s -> s -> m ()

-- | Monadic state transformer.
--   
--   Maps an old state to a new state inside a state monad. The old state
--   is thrown away.
--   
--   <pre>
--   Main&gt; :t modify ((+1) :: Int -&gt; Int)
--   modify (...) :: (MonadState Int a) =&gt; a ()
--   </pre>
--   
--   This says that <tt>modify (+1)</tt> acts over any Monad that is a
--   member of the <tt>MonadState</tt> class, with an <tt>Int</tt> state.
modify :: MonadState s m => s -> s -> m ()

-- | Minimal definition is either both of <tt>get</tt> and <tt>put</tt> or
--   just <tt>state</tt>
class Monad m => MonadState s (m :: * -> *) | m -> s

-- | Return the state from the internals of the monad.
get :: MonadState s m => m s

-- | Replace the state inside the monad.
put :: MonadState s m => s -> m ()

-- | Embed a simple state action into the monad.
state :: MonadState s m => s -> (a, s) -> m a

-- | A state transformer monad parameterized by:
--   
--   <ul>
--   <li><tt>s</tt> - The state.</li>
--   <li><tt>m</tt> - The inner monad.</li>
--   </ul>
--   
--   The <a>return</a> function leaves the state unchanged, while
--   <tt>&gt;&gt;=</tt> uses the final state of the first computation as
--   the initial state of the second.
newtype StateT s (m :: * -> *) a
StateT :: s -> m (a, s) -> StateT s a
[runStateT] :: StateT s a -> s -> m (a, s)

-- | A state monad parameterized by the type <tt>s</tt> of the state to
--   carry.
--   
--   The <a>return</a> function leaves the state unchanged, while
--   <tt>&gt;&gt;=</tt> uses the final state of the first computation as
--   the initial state of the second.
type State s = StateT s Identity

-- | Unwrap a state monad computation as a function. (The inverse of
--   <a>state</a>.)
runState :: () => State s a -> s -> (a, s)

-- | Evaluate a state computation with the given initial state and return
--   the final value, discarding the final state.
--   
--   <ul>
--   <li><pre><a>evalState</a> m s = <a>fst</a> (<a>runState</a> m
--   s)</pre></li>
--   </ul>
evalState :: () => State s a -> s -> a

-- | Evaluate a state computation with the given initial state and return
--   the final state, discarding the final value.
--   
--   <ul>
--   <li><pre><a>execState</a> m s = <a>snd</a> (<a>runState</a> m
--   s)</pre></li>
--   </ul>
execState :: () => State s a -> s -> s

-- | <tt><a>withState</a> f m</tt> executes action <tt>m</tt> on a state
--   modified by applying <tt>f</tt>.
--   
--   <ul>
--   <li><pre><a>withState</a> f m = <a>modify</a> f &gt;&gt; m</pre></li>
--   </ul>
withState :: () => s -> s -> State s a -> State s a

-- | Evaluate a state computation with the given initial state and return
--   the final value, discarding the final state.
--   
--   <ul>
--   <li><pre><a>evalStateT</a> m s = <a>liftM</a> <a>fst</a>
--   (<a>runStateT</a> m s)</pre></li>
--   </ul>
evalStateT :: Monad m => StateT s m a -> s -> m a

-- | Evaluate a state computation with the given initial state and return
--   the final state, discarding the final value.
--   
--   <ul>
--   <li><pre><a>execStateT</a> m s = <a>liftM</a> <a>snd</a>
--   (<a>runStateT</a> m s)</pre></li>
--   </ul>
execStateT :: Monad m => StateT s m a -> s -> m s

-- | Monads in which <a>IO</a> computations may be embedded. Any monad
--   built by applying a sequence of monad transformers to the <a>IO</a>
--   monad will be an instance of this class.
--   
--   Instances should satisfy the following laws, which state that
--   <a>liftIO</a> is a transformer of monads:
--   
--   <ul>
--   <li><pre><a>liftIO</a> . <a>return</a> = <a>return</a></pre></li>
--   <li><pre><a>liftIO</a> (m &gt;&gt;= f) = <a>liftIO</a> m &gt;&gt;=
--   (<a>liftIO</a> . f)</pre></li>
--   </ul>
class Monad m => MonadIO (m :: * -> *)

-- | Lift a computation from the <a>IO</a> monad.
liftIO :: MonadIO m => IO a -> m a

-- | The class of monad transformers. Instances should satisfy the
--   following laws, which state that <a>lift</a> is a monad
--   transformation:
--   
--   <ul>
--   <li><pre><a>lift</a> . <a>return</a> = <a>return</a></pre></li>
--   <li><pre><a>lift</a> (m &gt;&gt;= f) = <a>lift</a> m &gt;&gt;=
--   (<a>lift</a> . f)</pre></li>
--   </ul>
class MonadTrans (t :: * -> * -> * -> *)

-- | Lift a computation from the argument monad to the constructed monad.
lift :: (MonadTrans t, Monad m) => m a -> t m a

-- | The trivial monad transformer, which maps a monad to an equivalent
--   monad.
data IdentityT (f :: k -> *) (a :: k) :: forall k. () => k -> * -> k -> *

-- | Convert a <a>ExceptT</a> computation to <a>MaybeT</a>, discarding the
--   value of any exception.
exceptToMaybeT :: Functor m => ExceptT e m a -> MaybeT m a

-- | Convert a <a>MaybeT</a> computation to <a>ExceptT</a>, with a default
--   exception value.
maybeToExceptT :: Functor m => e -> MaybeT m a -> ExceptT e m a

-- | The parameterizable maybe monad, obtained by composing an arbitrary
--   monad with the <a>Maybe</a> monad.
--   
--   Computations are actions that may produce a value or exit.
--   
--   The <a>return</a> function yields a computation that produces that
--   value, while <tt>&gt;&gt;=</tt> sequences two subcomputations, exiting
--   if either computation does.
newtype MaybeT (m :: * -> *) a
MaybeT :: m Maybe a -> MaybeT a
[runMaybeT] :: MaybeT a -> m Maybe a

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

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

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

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

-- | Like <a>replicateM</a>, but discards the result.
replicateM_ :: Applicative m => Int -> m 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]

-- | <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>zipWithM</a> function generalizes <a>zipWith</a> to arbitrary
--   applicative functors.
zipWithM :: Applicative m => a -> b -> m c -> [a] -> [b] -> m [c]

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

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

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

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

-- | This generalizes the list-based <tt>filter</tt> function.
filterM :: Applicative m => a -> m Bool -> [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 =<<

-- | 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>
--   
--   The default definition is
--   
--   <pre>
--   mzero = <a>empty</a>
--   </pre>
mzero :: MonadPlus m => m a

-- | An associative operation. The default definition is
--   
--   <pre>
--   mplus = (<a>&lt;|&gt;</a>)
--   </pre>
mplus :: MonadPlus m => m a -> 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

-- | The <a>Maybe</a> type encapsulates an optional value. A value of type
--   <tt><a>Maybe</a> a</tt> either contains a value of type <tt>a</tt>
--   (represented as <tt><a>Just</a> a</tt>), or it is empty (represented
--   as <a>Nothing</a>). Using <a>Maybe</a> is a good way to deal with
--   errors or exceptional cases without resorting to drastic measures such
--   as <a>error</a>.
--   
--   The <a>Maybe</a> type is also a monad. It is a simple kind of error
--   monad, where all errors are represented by <a>Nothing</a>. A richer
--   error monad can be built using the <a>Either</a> type.
data Maybe a
Nothing :: Maybe a
Just :: a -> Maybe a

-- | The <a>mapMaybe</a> function is a version of <a>map</a> which can
--   throw out elements. In particular, the functional argument returns
--   something of type <tt><a>Maybe</a> b</tt>. If this is <a>Nothing</a>,
--   no element is added on to the result list. If it is <tt><a>Just</a>
--   b</tt>, then <tt>b</tt> is included in the result list.
--   
--   <h4><b>Examples</b></h4>
--   
--   Using <tt><a>mapMaybe</a> f x</tt> is a shortcut for
--   <tt><a>catMaybes</a> $ <a>map</a> f x</tt> in most cases:
--   
--   <pre>
--   &gt;&gt;&gt; import Text.Read ( readMaybe )
--   
--   &gt;&gt;&gt; let readMaybeInt = readMaybe :: String -&gt; Maybe Int
--   
--   &gt;&gt;&gt; mapMaybe readMaybeInt ["1", "Foo", "3"]
--   [1,3]
--   
--   &gt;&gt;&gt; catMaybes $ map readMaybeInt ["1", "Foo", "3"]
--   [1,3]
--   </pre>
--   
--   If we map the <a>Just</a> constructor, the entire list should be
--   returned:
--   
--   <pre>
--   &gt;&gt;&gt; mapMaybe Just [1,2,3]
--   [1,2,3]
--   </pre>
mapMaybe :: () => a -> Maybe b -> [a] -> [b]

-- | The <a>catMaybes</a> function takes a list of <a>Maybe</a>s and
--   returns a list of all the <a>Just</a> values.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; catMaybes [Just 1, Nothing, Just 3]
--   [1,3]
--   </pre>
--   
--   When constructing a list of <a>Maybe</a> values, <a>catMaybes</a> can
--   be used to return all of the "success" results (if the list is the
--   result of a <a>map</a>, then <a>mapMaybe</a> would be more
--   appropriate):
--   
--   <pre>
--   &gt;&gt;&gt; import Text.Read ( readMaybe )
--   
--   &gt;&gt;&gt; [readMaybe x :: Maybe Int | x &lt;- ["1", "Foo", "3"] ]
--   [Just 1,Nothing,Just 3]
--   
--   &gt;&gt;&gt; catMaybes $ [readMaybe x :: Maybe Int | x &lt;- ["1", "Foo", "3"] ]
--   [1,3]
--   </pre>
catMaybes :: () => [Maybe a] -> [a]

-- | The <a>listToMaybe</a> function returns <a>Nothing</a> on an empty
--   list or <tt><a>Just</a> a</tt> where <tt>a</tt> is the first element
--   of the list.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; listToMaybe []
--   Nothing
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; listToMaybe [9]
--   Just 9
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; listToMaybe [1,2,3]
--   Just 1
--   </pre>
--   
--   Composing <a>maybeToList</a> with <a>listToMaybe</a> should be the
--   identity on singleton/empty lists:
--   
--   <pre>
--   &gt;&gt;&gt; maybeToList $ listToMaybe [5]
--   [5]
--   
--   &gt;&gt;&gt; maybeToList $ listToMaybe []
--   []
--   </pre>
--   
--   But not on lists with more than one element:
--   
--   <pre>
--   &gt;&gt;&gt; maybeToList $ listToMaybe [1,2,3]
--   [1]
--   </pre>
listToMaybe :: () => [a] -> Maybe a

-- | The <a>maybeToList</a> function returns an empty list when given
--   <a>Nothing</a> or a singleton list when not given <a>Nothing</a>.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; maybeToList (Just 7)
--   [7]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; maybeToList Nothing
--   []
--   </pre>
--   
--   One can use <a>maybeToList</a> to avoid pattern matching when combined
--   with a function that (safely) works on lists:
--   
--   <pre>
--   &gt;&gt;&gt; import Text.Read ( readMaybe )
--   
--   &gt;&gt;&gt; sum $ maybeToList (readMaybe "3")
--   3
--   
--   &gt;&gt;&gt; sum $ maybeToList (readMaybe "")
--   0
--   </pre>
maybeToList :: () => Maybe a -> [a]

-- | The <a>fromMaybe</a> function takes a default value and and
--   <a>Maybe</a> value. If the <a>Maybe</a> is <a>Nothing</a>, it returns
--   the default values; otherwise, it returns the value contained in the
--   <a>Maybe</a>.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; fromMaybe "" (Just "Hello, World!")
--   "Hello, World!"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fromMaybe "" Nothing
--   ""
--   </pre>
--   
--   Read an integer from a string using <tt>readMaybe</tt>. If we fail to
--   parse an integer, we want to return <tt>0</tt> by default:
--   
--   <pre>
--   &gt;&gt;&gt; import Text.Read ( readMaybe )
--   
--   &gt;&gt;&gt; fromMaybe 0 (readMaybe "5")
--   5
--   
--   &gt;&gt;&gt; fromMaybe 0 (readMaybe "")
--   0
--   </pre>
fromMaybe :: () => a -> Maybe a -> a

-- | The <a>isNothing</a> function returns <a>True</a> iff its argument is
--   <a>Nothing</a>.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; isNothing (Just 3)
--   False
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; isNothing (Just ())
--   False
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; isNothing Nothing
--   True
--   </pre>
--   
--   Only the outer constructor is taken into consideration:
--   
--   <pre>
--   &gt;&gt;&gt; isNothing (Just Nothing)
--   False
--   </pre>
isNothing :: () => Maybe a -> Bool

-- | The <a>isJust</a> function returns <a>True</a> iff its argument is of
--   the form <tt>Just _</tt>.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; isJust (Just 3)
--   True
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; isJust (Just ())
--   True
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; isJust Nothing
--   False
--   </pre>
--   
--   Only the outer constructor is taken into consideration:
--   
--   <pre>
--   &gt;&gt;&gt; isJust (Just Nothing)
--   True
--   </pre>
isJust :: () => Maybe a -> Bool

-- | The <a>maybe</a> function takes a default value, a function, and a
--   <a>Maybe</a> value. If the <a>Maybe</a> value is <a>Nothing</a>, the
--   function returns the default value. Otherwise, it applies the function
--   to the value inside the <a>Just</a> and returns the result.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; maybe False odd (Just 3)
--   True
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; maybe False odd Nothing
--   False
--   </pre>
--   
--   Read an integer from a string using <tt>readMaybe</tt>. If we succeed,
--   return twice the integer; that is, apply <tt>(*2)</tt> to it. If
--   instead we fail to parse an integer, return <tt>0</tt> by default:
--   
--   <pre>
--   &gt;&gt;&gt; import Text.Read ( readMaybe )
--   
--   &gt;&gt;&gt; maybe 0 (*2) (readMaybe "5")
--   10
--   
--   &gt;&gt;&gt; maybe 0 (*2) (readMaybe "")
--   0
--   </pre>
--   
--   Apply <tt>show</tt> to a <tt>Maybe Int</tt>. If we have <tt>Just
--   n</tt>, we want to show the underlying <a>Int</a> <tt>n</tt>. But if
--   we have <a>Nothing</a>, we return the empty string instead of (for
--   example) "Nothing":
--   
--   <pre>
--   &gt;&gt;&gt; maybe "" show (Just 5)
--   "5"
--   
--   &gt;&gt;&gt; maybe "" show Nothing
--   ""
--   </pre>
maybe :: () => b -> a -> b -> Maybe a -> b

-- | The <a>Either</a> type represents values with two possibilities: a
--   value of type <tt><a>Either</a> a b</tt> is either <tt><a>Left</a>
--   a</tt> or <tt><a>Right</a> b</tt>.
--   
--   The <a>Either</a> type is sometimes used to represent a value which is
--   either correct or an error; by convention, the <a>Left</a> constructor
--   is used to hold an error value and the <a>Right</a> constructor is
--   used to hold a correct value (mnemonic: "right" also means "correct").
--   
--   <h4><b>Examples</b></h4>
--   
--   The type <tt><a>Either</a> <a>String</a> <a>Int</a></tt> is the type
--   of values which can be either a <a>String</a> or an <a>Int</a>. The
--   <a>Left</a> constructor can be used only on <a>String</a>s, and the
--   <a>Right</a> constructor can be used only on <a>Int</a>s:
--   
--   <pre>
--   &gt;&gt;&gt; let s = Left "foo" :: Either String Int
--   
--   &gt;&gt;&gt; s
--   Left "foo"
--   
--   &gt;&gt;&gt; let n = Right 3 :: Either String Int
--   
--   &gt;&gt;&gt; n
--   Right 3
--   
--   &gt;&gt;&gt; :type s
--   s :: Either String Int
--   
--   &gt;&gt;&gt; :type n
--   n :: Either String Int
--   </pre>
--   
--   The <a>fmap</a> from our <a>Functor</a> instance will ignore
--   <a>Left</a> values, but will apply the supplied function to values
--   contained in a <a>Right</a>:
--   
--   <pre>
--   &gt;&gt;&gt; let s = Left "foo" :: Either String Int
--   
--   &gt;&gt;&gt; let n = Right 3 :: Either String Int
--   
--   &gt;&gt;&gt; fmap (*2) s
--   Left "foo"
--   
--   &gt;&gt;&gt; fmap (*2) n
--   Right 6
--   </pre>
--   
--   The <a>Monad</a> instance for <a>Either</a> allows us to chain
--   together multiple actions which may fail, and fail overall if any of
--   the individual steps failed. First we'll write a function that can
--   either parse an <a>Int</a> from a <a>Char</a>, or fail.
--   
--   <pre>
--   &gt;&gt;&gt; import Data.Char ( digitToInt, isDigit )
--   
--   &gt;&gt;&gt; :{
--       let parseEither :: Char -&gt; Either String Int
--           parseEither c
--             | isDigit c = Right (digitToInt c)
--             | otherwise = Left "parse error"
--   
--   &gt;&gt;&gt; :}
--   </pre>
--   
--   The following should work, since both <tt>'1'</tt> and <tt>'2'</tt>
--   can be parsed as <a>Int</a>s.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--       let parseMultiple :: Either String Int
--           parseMultiple = do
--             x &lt;- parseEither '1'
--             y &lt;- parseEither '2'
--             return (x + y)
--   
--   &gt;&gt;&gt; :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; parseMultiple
--   Right 3
--   </pre>
--   
--   But the following should fail overall, since the first operation where
--   we attempt to parse <tt>'m'</tt> as an <a>Int</a> will fail:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--       let parseMultiple :: Either String Int
--           parseMultiple = do
--             x &lt;- parseEither 'm'
--             y &lt;- parseEither '2'
--             return (x + y)
--   
--   &gt;&gt;&gt; :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; parseMultiple
--   Left "parse error"
--   </pre>
data Either a b
Left :: a -> Either a b
Right :: b -> Either a b

-- | Return <a>True</a> if the given value is a <a>Right</a>-value,
--   <a>False</a> otherwise.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; isRight (Left "foo")
--   False
--   
--   &gt;&gt;&gt; isRight (Right 3)
--   True
--   </pre>
--   
--   Assuming a <a>Left</a> value signifies some sort of error, we can use
--   <a>isRight</a> to write a very simple reporting function that only
--   outputs "SUCCESS" when a computation has succeeded.
--   
--   This example shows how <a>isRight</a> might be used to avoid pattern
--   matching when one does not care about the value contained in the
--   constructor:
--   
--   <pre>
--   &gt;&gt;&gt; import Control.Monad ( when )
--   
--   &gt;&gt;&gt; let report e = when (isRight e) $ putStrLn "SUCCESS"
--   
--   &gt;&gt;&gt; report (Left "parse error")
--   
--   &gt;&gt;&gt; report (Right 1)
--   SUCCESS
--   </pre>
isRight :: () => Either a b -> Bool

-- | Return <a>True</a> if the given value is a <a>Left</a>-value,
--   <a>False</a> otherwise.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; isLeft (Left "foo")
--   True
--   
--   &gt;&gt;&gt; isLeft (Right 3)
--   False
--   </pre>
--   
--   Assuming a <a>Left</a> value signifies some sort of error, we can use
--   <a>isLeft</a> to write a very simple error-reporting function that
--   does absolutely nothing in the case of success, and outputs "ERROR" if
--   any error occurred.
--   
--   This example shows how <a>isLeft</a> might be used to avoid pattern
--   matching when one does not care about the value contained in the
--   constructor:
--   
--   <pre>
--   &gt;&gt;&gt; import Control.Monad ( when )
--   
--   &gt;&gt;&gt; let report e = when (isLeft e) $ putStrLn "ERROR"
--   
--   &gt;&gt;&gt; report (Right 1)
--   
--   &gt;&gt;&gt; report (Left "parse error")
--   ERROR
--   </pre>
isLeft :: () => Either a b -> Bool

-- | Partitions a list of <a>Either</a> into two lists. All the <a>Left</a>
--   elements are extracted, in order, to the first component of the
--   output. Similarly the <a>Right</a> elements are extracted to the
--   second component of the output.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; let list = [ Left "foo", Right 3, Left "bar", Right 7, Left "baz" ]
--   
--   &gt;&gt;&gt; partitionEithers list
--   (["foo","bar","baz"],[3,7])
--   </pre>
--   
--   The pair returned by <tt><a>partitionEithers</a> x</tt> should be the
--   same pair as <tt>(<a>lefts</a> x, <a>rights</a> x)</tt>:
--   
--   <pre>
--   &gt;&gt;&gt; let list = [ Left "foo", Right 3, Left "bar", Right 7, Left "baz" ]
--   
--   &gt;&gt;&gt; partitionEithers list == (lefts list, rights list)
--   True
--   </pre>
partitionEithers :: () => [Either a b] -> ([a], [b])

-- | Extracts from a list of <a>Either</a> all the <a>Right</a> elements.
--   All the <a>Right</a> elements are extracted in order.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; let list = [ Left "foo", Right 3, Left "bar", Right 7, Left "baz" ]
--   
--   &gt;&gt;&gt; rights list
--   [3,7]
--   </pre>
rights :: () => [Either a b] -> [b]

-- | Extracts from a list of <a>Either</a> all the <a>Left</a> elements.
--   All the <a>Left</a> elements are extracted in order.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; let list = [ Left "foo", Right 3, Left "bar", Right 7, Left "baz" ]
--   
--   &gt;&gt;&gt; lefts list
--   ["foo","bar","baz"]
--   </pre>
lefts :: () => [Either a b] -> [a]

-- | Case analysis for the <a>Either</a> type. If the value is
--   <tt><a>Left</a> a</tt>, apply the first function to <tt>a</tt>; if it
--   is <tt><a>Right</a> b</tt>, apply the second function to <tt>b</tt>.
--   
--   <h4><b>Examples</b></h4>
--   
--   We create two values of type <tt><a>Either</a> <a>String</a>
--   <a>Int</a></tt>, one using the <a>Left</a> constructor and another
--   using the <a>Right</a> constructor. Then we apply "either" the
--   <tt>length</tt> function (if we have a <a>String</a>) or the
--   "times-two" function (if we have an <a>Int</a>):
--   
--   <pre>
--   &gt;&gt;&gt; let s = Left "foo" :: Either String Int
--   
--   &gt;&gt;&gt; let n = Right 3 :: Either String Int
--   
--   &gt;&gt;&gt; either length (*2) s
--   3
--   
--   &gt;&gt;&gt; either length (*2) n
--   6
--   </pre>
either :: () => a -> c -> b -> c -> Either a b -> c


-- | Utility functions to work with <a>Maybe</a> data type as monad.
module Relude.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 ()


-- | Monad transformers utilities.
module Relude.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 Relude.Monoid

-- | The class of monoids (types with an associative binary operation that
--   has an identity). Instances should satisfy the following laws:
--   
--   <ul>
--   <li><pre>x <a>&lt;&gt;</a> <a>mempty</a> = x</pre></li>
--   <li><pre><a>mempty</a> <a>&lt;&gt;</a> x = x</pre></li>
--   <li><tt>x <a>&lt;&gt;</a> (y <a>&lt;&gt;</a> z) = (x <a>&lt;&gt;</a>
--   y) <a>&lt;&gt;</a> z</tt> (<a>Semigroup</a> law)</li>
--   <li><pre><a>mconcat</a> = <a>foldr</a> '(&lt;&gt;)'
--   <a>mempty</a></pre></li>
--   </ul>
--   
--   The method names refer to the monoid of lists under concatenation, but
--   there are many other instances.
--   
--   Some types can be viewed as a monoid in more than one way, e.g. both
--   addition and multiplication on numbers. In such cases we often define
--   <tt>newtype</tt>s and make those instances of <a>Monoid</a>, e.g.
--   <tt>Sum</tt> and <tt>Product</tt>.
--   
--   <b>NOTE</b>: <a>Semigroup</a> is a superclass of <a>Monoid</a> since
--   <i>base-4.11.0.0</i>.
class Semigroup a => Monoid a

-- | Identity of <a>mappend</a>
mempty :: Monoid a => a

-- | An associative operation
--   
--   <b>NOTE</b>: This method is redundant and has the default
--   implementation <tt><a>mappend</a> = '(&lt;&gt;)'</tt> since
--   <i>base-4.11.0.0</i>.
mappend :: Monoid a => a -> a -> a

-- | Fold a list using the monoid.
--   
--   For most types, the default definition for <a>mconcat</a> will be
--   used, but the function is included in the class definition so that an
--   optimized version can be provided for specific types.
mconcat :: Monoid a => [a] -> a

-- | Maybe monoid returning the leftmost non-Nothing value.
--   
--   <tt><a>First</a> a</tt> is isomorphic to <tt><a>Alt</a> <a>Maybe</a>
--   a</tt>, but precedes it historically.
--   
--   <pre>
--   &gt;&gt;&gt; getFirst (First (Just "hello") &lt;&gt; First Nothing &lt;&gt; First (Just "world"))
--   Just "hello"
--   </pre>
newtype First a
First :: Maybe a -> First a
[getFirst] :: First a -> Maybe a

-- | Maybe monoid returning the rightmost non-Nothing value.
--   
--   <tt><a>Last</a> a</tt> is isomorphic to <tt><a>Dual</a> (<a>First</a>
--   a)</tt>, and thus to <tt><a>Dual</a> (<a>Alt</a> <a>Maybe</a> a)</tt>
--   
--   <pre>
--   &gt;&gt;&gt; getLast (Last (Just "hello") &lt;&gt; Last Nothing &lt;&gt; Last (Just "world"))
--   Just "world"
--   </pre>
newtype Last a
Last :: Maybe a -> Last a
[getLast] :: Last a -> Maybe a

-- | The dual of a <a>Monoid</a>, obtained by swapping the arguments of
--   <a>mappend</a>.
--   
--   <pre>
--   &gt;&gt;&gt; getDual (mappend (Dual "Hello") (Dual "World"))
--   "WorldHello"
--   </pre>
newtype Dual a
Dual :: a -> Dual a
[getDual] :: Dual a -> a

-- | The monoid of endomorphisms under composition.
--   
--   <pre>
--   &gt;&gt;&gt; let computation = Endo ("Hello, " ++) &lt;&gt; Endo (++ "!")
--   
--   &gt;&gt;&gt; appEndo computation "Haskell"
--   "Hello, Haskell!"
--   </pre>
newtype Endo a
Endo :: a -> a -> Endo a
[appEndo] :: Endo a -> a -> a

-- | Boolean monoid under conjunction (<a>&amp;&amp;</a>).
--   
--   <pre>
--   &gt;&gt;&gt; getAll (All True &lt;&gt; mempty &lt;&gt; All False)
--   False
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; getAll (mconcat (map (\x -&gt; All (even x)) [2,4,6,7,8]))
--   False
--   </pre>
newtype All
All :: Bool -> All
[getAll] :: All -> Bool

-- | Boolean monoid under disjunction (<a>||</a>).
--   
--   <pre>
--   &gt;&gt;&gt; getAny (Any True &lt;&gt; mempty &lt;&gt; Any False)
--   True
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; getAny (mconcat (map (\x -&gt; Any (even x)) [2,4,6,7,8]))
--   True
--   </pre>
newtype Any
Any :: Bool -> Any
[getAny] :: Any -> Bool

-- | Monoid under addition.
--   
--   <pre>
--   &gt;&gt;&gt; getSum (Sum 1 &lt;&gt; Sum 2 &lt;&gt; mempty)
--   3
--   </pre>
newtype Sum a
Sum :: a -> Sum a
[getSum] :: Sum a -> a

-- | Monoid under multiplication.
--   
--   <pre>
--   &gt;&gt;&gt; getProduct (Product 3 &lt;&gt; Product 4 &lt;&gt; mempty)
--   12
--   </pre>
newtype Product a
Product :: a -> Product a
[getProduct] :: Product a -> a

-- | Monoid under <a>&lt;|&gt;</a>.
newtype Alt (f :: k -> *) (a :: k) :: forall k. () => k -> * -> k -> *
Alt :: f a -> Alt
[getAlt] :: Alt -> f a

-- | The class of semigroups (types with an associative binary operation).
--   
--   Instances should satisfy the associativity law:
--   
--   <ul>
--   <li><pre>x <a>&lt;&gt;</a> (y <a>&lt;&gt;</a> z) = (x <a>&lt;&gt;</a>
--   y) <a>&lt;&gt;</a> z</pre></li>
--   </ul>
class Semigroup a

-- | An associative operation.
(<>) :: Semigroup a => a -> a -> a

-- | Reduce a non-empty list with <tt>&lt;&gt;</tt>
--   
--   The default definition should be sufficient, but this can be
--   overridden for efficiency.
sconcat :: Semigroup a => NonEmpty a -> a

-- | Repeat a value <tt>n</tt> times.
--   
--   Given that this works on a <a>Semigroup</a> it is allowed to fail if
--   you request 0 or fewer repetitions, and the default definition will do
--   so.
--   
--   By making this a member of the class, idempotent semigroups and
--   monoids can upgrade this to execute in <i>O(1)</i> by picking
--   <tt>stimes = <tt>stimesIdempotent</tt></tt> or <tt>stimes =
--   <a>stimesIdempotentMonoid</a></tt> respectively.
stimes :: (Semigroup a, Integral b) => b -> a -> a

-- | Repeat a value <tt>n</tt> times.
--   
--   <pre>
--   mtimesDefault n a = a &lt;&gt; a &lt;&gt; ... &lt;&gt; a  -- using &lt;&gt; (n-1) times
--   </pre>
--   
--   Implemented using <a>stimes</a> and <a>mempty</a>.
--   
--   This is a suitable definition for an <tt>mtimes</tt> member of
--   <a>Monoid</a>.
mtimesDefault :: (Integral b, Monoid a) => b -> a -> a

-- | A generalization of <a>cycle</a> to an arbitrary <a>Semigroup</a>. May
--   fail to terminate for some values in some semigroups.
cycle1 :: Semigroup m => m -> m

-- | Provide a Semigroup for an arbitrary Monoid.
--   
--   <b>NOTE</b>: This is not needed anymore since <a>Semigroup</a> became
--   a superclass of <a>Monoid</a> in <i>base-4.11</i> and this newtype be
--   deprecated at some point in the future.
data WrappedMonoid m

-- | <a>Option</a> is effectively <a>Maybe</a> with a better instance of
--   <a>Monoid</a>, built off of an underlying <a>Semigroup</a> instead of
--   an underlying <a>Monoid</a>.
--   
--   Ideally, this type would not exist at all and we would just fix the
--   <a>Monoid</a> instance of <a>Maybe</a>
newtype Option a
Option :: Maybe a -> Option a
[getOption] :: Option a -> Maybe a

-- | This is a valid definition of <a>stimes</a> for a <a>Monoid</a>.
--   
--   Unlike the default definition of <a>stimes</a>, it is defined for 0
--   and so it should be preferred where possible.
stimesMonoid :: (Integral b, Monoid a) => b -> a -> a

-- | This is a valid definition of <a>stimes</a> for an idempotent
--   <a>Semigroup</a>.
--   
--   When <tt>x &lt;&gt; x = x</tt>, this definition should be preferred,
--   because it works in <i>O(1)</i> rather than <i>O(log n)</i>.
stimesIdempotent :: Integral b => b -> a -> a

-- | This is a valid definition of <a>stimes</a> for an idempotent
--   <a>Monoid</a>.
--   
--   When <tt>mappend x x = x</tt>, this definition should be preferred,
--   because it works in <i>O(1)</i> rather than <i>O(log n)</i>
stimesIdempotentMonoid :: (Integral b, Monoid a) => b -> a -> a

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


-- | 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 Relude.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 Relude.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 Relude.Print.Print Data.Text.Internal.Text
instance Relude.Print.Print Data.Text.Internal.Lazy.Text
instance Relude.Print.Print Data.ByteString.Internal.ByteString
instance Relude.Print.Print Data.ByteString.Lazy.Internal.ByteString
instance Relude.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 Relude.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 Relude.Debug.Undefined
instance Data.Data.Data Relude.Debug.Undefined
instance GHC.Enum.Bounded Relude.Debug.Undefined
instance GHC.Enum.Enum Relude.Debug.Undefined
instance GHC.Read.Read Relude.Debug.Undefined
instance GHC.Show.Show Relude.Debug.Undefined
instance GHC.Classes.Ord Relude.Debug.Undefined
instance GHC.Classes.Eq Relude.Debug.Undefined


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

-- | Class for string-like datastructures; used by the overloaded string
--   extension (-XOverloadedStrings in GHC).
class IsString a
fromString :: IsString a => String -> a

-- | <i>O(n)</i> Joins words using single space characters.
unwords :: [Text] -> Text

-- | <i>O(n)</i> Joins lines, after appending a terminating newline to
--   each.
unlines :: [Text] -> Text

-- | <i>O(n)</i> Breaks a <a>Text</a> up into a list of <a>Text</a>s at
--   newline <a>Char</a>s. The resulting strings do not contain newlines.
lines :: Text -> [Text]

-- | <i>O(n)</i> Breaks a <a>Text</a> up into a list of words, delimited by
--   <a>Char</a>s representing white space.
words :: Text -> [Text]

-- | A space efficient, packed, unboxed Unicode text type.
data Text

-- | Decode a <a>ByteString</a> containing UTF-8 encoded text.
--   
--   If the input contains any invalid UTF-8 data, the relevant exception
--   will be returned, otherwise the decoded text.
decodeUtf8' :: ByteString -> Either UnicodeException Text

-- | Decode a <a>ByteString</a> containing UTF-8 encoded text.
--   
--   <b>NOTE</b>: The replacement character returned by
--   <a>OnDecodeError</a> MUST be within the BMP plane; surrogate code
--   points will automatically be remapped to the replacement char
--   <tt>U+FFFD</tt> (<i>since 0.11.3.0</i>), whereas code points beyond
--   the BMP will throw an <a>error</a> (<i>since 1.2.3.1</i>); For earlier
--   versions of <tt>text</tt> using those unsupported code points would
--   result in undefined behavior.
decodeUtf8With :: OnDecodeError -> ByteString -> Text

-- | Replace an invalid input byte with the Unicode replacement character
--   U+FFFD.
lenientDecode :: OnDecodeError

-- | Throw a <a>UnicodeException</a> if decoding fails.
strictDecode :: OnDecodeError

-- | Function type for handling a coding error. It is supplied with two
--   inputs:
--   
--   <ul>
--   <li>A <a>String</a> that describes the error.</li>
--   <li>The input value that caused the error. If the error arose because
--   the end of input was reached or could not be identified precisely,
--   this value will be <a>Nothing</a>.</li>
--   </ul>
--   
--   If the handler returns a value wrapped with <a>Just</a>, that value
--   will be used in the output as the replacement for the invalid input.
--   If it returns <a>Nothing</a>, no value will be used in the output.
--   
--   Should the handler need to abort processing, it should use
--   <a>error</a> or <a>throw</a> an exception (preferably a
--   <a>UnicodeException</a>). It may use the description provided to
--   construct a more helpful error report.
type OnError a b = String -> Maybe a -> Maybe b

-- | A handler for a decoding error.
type OnDecodeError = OnError Word8 Char

-- | An exception type for representing Unicode encoding errors.
data UnicodeException

-- | Parsing of <a>String</a>s, producing values.
--   
--   Derived instances of <a>Read</a> make the following assumptions, which
--   derived instances of <a>Show</a> obey:
--   
--   <ul>
--   <li>If the constructor is defined to be an infix operator, then the
--   derived <a>Read</a> instance will parse only infix applications of the
--   constructor (not the prefix form).</li>
--   <li>Associativity is not used to reduce the occurrence of parentheses,
--   although precedence may be.</li>
--   <li>If the constructor is defined using record syntax, the derived
--   <a>Read</a> will parse only the record-syntax form, and furthermore,
--   the fields must be given in the same order as the original
--   declaration.</li>
--   <li>The derived <a>Read</a> instance allows arbitrary Haskell
--   whitespace between tokens of the input string. Extra parentheses are
--   also allowed.</li>
--   </ul>
--   
--   For example, given the declarations
--   
--   <pre>
--   infixr 5 :^:
--   data Tree a =  Leaf a  |  Tree a :^: Tree a
--   </pre>
--   
--   the derived instance of <a>Read</a> in Haskell 2010 is equivalent to
--   
--   <pre>
--   instance (Read a) =&gt; Read (Tree a) where
--   
--           readsPrec d r =  readParen (d &gt; app_prec)
--                            (\r -&gt; [(Leaf m,t) |
--                                    ("Leaf",s) &lt;- lex r,
--                                    (m,t) &lt;- readsPrec (app_prec+1) s]) r
--   
--                         ++ readParen (d &gt; up_prec)
--                            (\r -&gt; [(u:^:v,w) |
--                                    (u,s) &lt;- readsPrec (up_prec+1) r,
--                                    (":^:",t) &lt;- lex s,
--                                    (v,w) &lt;- readsPrec (up_prec+1) t]) r
--   
--             where app_prec = 10
--                   up_prec = 5
--   </pre>
--   
--   Note that right-associativity of <tt>:^:</tt> is unused.
--   
--   The derived instance in GHC is equivalent to
--   
--   <pre>
--   instance (Read a) =&gt; Read (Tree a) where
--   
--           readPrec = parens $ (prec app_prec $ do
--                                    Ident "Leaf" &lt;- lexP
--                                    m &lt;- step readPrec
--                                    return (Leaf m))
--   
--                        +++ (prec up_prec $ do
--                                    u &lt;- step readPrec
--                                    Symbol ":^:" &lt;- lexP
--                                    v &lt;- step readPrec
--                                    return (u :^: v))
--   
--             where app_prec = 10
--                   up_prec = 5
--   
--           readListPrec = readListPrecDefault
--   </pre>
--   
--   Why do both <a>readsPrec</a> and <a>readPrec</a> exist, and why does
--   GHC opt to implement <a>readPrec</a> in derived <a>Read</a> instances
--   instead of <a>readsPrec</a>? The reason is that <a>readsPrec</a> is
--   based on the <a>ReadS</a> type, and although <a>ReadS</a> is mentioned
--   in the Haskell 2010 Report, it is not a very efficient parser data
--   structure.
--   
--   <a>readPrec</a>, on the other hand, is based on a much more efficient
--   <a>ReadPrec</a> datatype (a.k.a "new-style parsers"), but its
--   definition relies on the use of the <tt>RankNTypes</tt> language
--   extension. Therefore, <a>readPrec</a> (and its cousin,
--   <a>readListPrec</a>) are marked as GHC-only. Nevertheless, it is
--   recommended to use <a>readPrec</a> instead of <a>readsPrec</a>
--   whenever possible for the efficiency improvements it brings.
--   
--   As mentioned above, derived <a>Read</a> instances in GHC will
--   implement <a>readPrec</a> instead of <a>readsPrec</a>. The default
--   implementations of <a>readsPrec</a> (and its cousin, <a>readList</a>)
--   will simply use <a>readPrec</a> under the hood. If you are writing a
--   <a>Read</a> instance by hand, it is recommended to write it like so:
--   
--   <pre>
--   instance <a>Read</a> T where
--     <a>readPrec</a>     = ...
--     <a>readListPrec</a> = <a>readListPrecDefault</a>
--   </pre>
class Read a

-- | Parse a string using the <a>Read</a> instance. Succeeds if there is
--   exactly one valid result.
--   
--   <pre>
--   &gt;&gt;&gt; readMaybe "123" :: Maybe Int
--   Just 123
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; readMaybe "hello" :: Maybe Int
--   Nothing
--   </pre>
readMaybe :: Read a => String -> Maybe a

-- | equivalent to <a>readsPrec</a> with a precedence of 0.
reads :: Read a => ReadS a

-- | A space-efficient representation of a <a>Word8</a> vector, supporting
--   many efficient operations.
--   
--   A <a>ByteString</a> contains 8-bit bytes, or by using the operations
--   from <a>Data.ByteString.Char8</a> it can be interpreted as containing
--   8-bit characters.
data ByteString


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

-- | Type class for lazy-strict conversions.
class LazyStrict l s | l -> s, s -> l
toLazy :: LazyStrict l s => s -> l
toStrict :: LazyStrict l s => l -> s
fromLazy :: LazyStrict l s => l -> s
fromStrict :: LazyStrict l s => s -> l

-- | 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
instance Relude.String.Conversion.LazyStrict Relude.String.Conversion.LByteString Data.ByteString.Internal.ByteString
instance Relude.String.Conversion.LazyStrict Relude.String.Conversion.LText Data.Text.Internal.Text
instance Relude.String.Conversion.ToString GHC.Base.String
instance Relude.String.Conversion.ToString Data.Text.Internal.Text
instance Relude.String.Conversion.ToString Data.Text.Internal.Lazy.Text
instance Relude.String.Conversion.ToLText GHC.Base.String
instance Relude.String.Conversion.ToLText Data.Text.Internal.Text
instance Relude.String.Conversion.ToLText Data.Text.Internal.Lazy.Text
instance Relude.String.Conversion.ToText GHC.Base.String
instance Relude.String.Conversion.ToText Data.Text.Internal.Text
instance Relude.String.Conversion.ToText Data.Text.Internal.Lazy.Text
instance Relude.String.Conversion.ConvertUtf8 GHC.Base.String Data.ByteString.Internal.ByteString
instance Relude.String.Conversion.ConvertUtf8 Data.Text.Internal.Text Data.ByteString.Internal.ByteString
instance Relude.String.Conversion.ConvertUtf8 Data.Text.Internal.Lazy.Text Data.ByteString.Internal.ByteString
instance Relude.String.Conversion.ConvertUtf8 GHC.Base.String Data.ByteString.Lazy.Internal.ByteString
instance Relude.String.Conversion.ConvertUtf8 Data.Text.Internal.Text Data.ByteString.Lazy.Internal.ByteString
instance Relude.String.Conversion.ConvertUtf8 Data.Text.Internal.Lazy.Text Data.ByteString.Lazy.Internal.ByteString


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


-- | Utilites to work with <tt>Either</tt> data type.
module Relude.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
--   and returns the result. In case of <a>Right</a> the default value will
--   be returned.
whenLeft :: Applicative f => a -> Either l r -> (l -> f a) -> f a

-- | 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 => a -> m (Either l r) -> (l -> m a) -> m a

-- | 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
--   and returns the result. In case of <a>Left</a> the default value will
--   be returned.
whenRight :: Applicative f => a -> Either l r -> (r -> f a) -> f a

-- | 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 => a -> m (Either l r) -> (r -> m a) -> m a

-- | Monadic version of <a>whenRight_</a>.
whenRightM_ :: Monad m => m (Either l r) -> (r -> m ()) -> m ()
instance Data.String.IsString str => Control.Monad.Fail.MonadFail (Data.Either.Either str)


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


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

-- | For safe work with lists using functinons for <a>NonEmpty</a>.
--   
--   <pre>
--   &gt;&gt;&gt; viaNonEmpty head [1]
--   Just 1
--   
--   &gt;&gt;&gt; viaNonEmpty head []
--   Nothing
--   </pre>
viaNonEmpty :: (NonEmpty a -> b) -> [a] -> Maybe 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 Relude.List


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

-- | Any type that you wish to throw or catch as an exception must be an
--   instance of the <tt>Exception</tt> class. The simplest case is a new
--   exception type directly below the root:
--   
--   <pre>
--   data MyException = ThisException | ThatException
--       deriving Show
--   
--   instance Exception MyException
--   </pre>
--   
--   The default method definitions in the <tt>Exception</tt> class do what
--   we need in this case. You can now throw and catch
--   <tt>ThisException</tt> and <tt>ThatException</tt> as exceptions:
--   
--   <pre>
--   *Main&gt; throw ThisException `catch` \e -&gt; putStrLn ("Caught " ++ show (e :: MyException))
--   Caught ThisException
--   </pre>
--   
--   In more complicated examples, you may wish to define a whole hierarchy
--   of exceptions:
--   
--   <pre>
--   ---------------------------------------------------------------------
--   -- Make the root exception type for all the exceptions in a compiler
--   
--   data SomeCompilerException = forall e . Exception e =&gt; SomeCompilerException e
--   
--   instance Show SomeCompilerException where
--       show (SomeCompilerException e) = show e
--   
--   instance Exception SomeCompilerException
--   
--   compilerExceptionToException :: Exception e =&gt; e -&gt; SomeException
--   compilerExceptionToException = toException . SomeCompilerException
--   
--   compilerExceptionFromException :: Exception e =&gt; SomeException -&gt; Maybe e
--   compilerExceptionFromException x = do
--       SomeCompilerException a &lt;- fromException x
--       cast a
--   
--   ---------------------------------------------------------------------
--   -- Make a subhierarchy for exceptions in the frontend of the compiler
--   
--   data SomeFrontendException = forall e . Exception e =&gt; SomeFrontendException e
--   
--   instance Show SomeFrontendException where
--       show (SomeFrontendException e) = show e
--   
--   instance Exception SomeFrontendException where
--       toException = compilerExceptionToException
--       fromException = compilerExceptionFromException
--   
--   frontendExceptionToException :: Exception e =&gt; e -&gt; SomeException
--   frontendExceptionToException = toException . SomeFrontendException
--   
--   frontendExceptionFromException :: Exception e =&gt; SomeException -&gt; Maybe e
--   frontendExceptionFromException x = do
--       SomeFrontendException a &lt;- fromException x
--       cast a
--   
--   ---------------------------------------------------------------------
--   -- Make an exception type for a particular frontend compiler exception
--   
--   data MismatchedParentheses = MismatchedParentheses
--       deriving Show
--   
--   instance Exception MismatchedParentheses where
--       toException   = frontendExceptionToException
--       fromException = frontendExceptionFromException
--   </pre>
--   
--   We can now catch a <tt>MismatchedParentheses</tt> exception as
--   <tt>MismatchedParentheses</tt>, <tt>SomeFrontendException</tt> or
--   <tt>SomeCompilerException</tt>, but not other types, e.g.
--   <tt>IOException</tt>:
--   
--   <pre>
--   *Main&gt; throw MismatchedParentheses `catch` \e -&gt; putStrLn ("Caught " ++ show (e :: MismatchedParentheses))
--   Caught MismatchedParentheses
--   *Main&gt; throw MismatchedParentheses `catch` \e -&gt; putStrLn ("Caught " ++ show (e :: SomeFrontendException))
--   Caught MismatchedParentheses
--   *Main&gt; throw MismatchedParentheses `catch` \e -&gt; putStrLn ("Caught " ++ show (e :: SomeCompilerException))
--   Caught MismatchedParentheses
--   *Main&gt; throw MismatchedParentheses `catch` \e -&gt; putStrLn ("Caught " ++ show (e :: IOException))
--   *** Exception: MismatchedParentheses
--   </pre>
class (Typeable e, Show e) => Exception e
toException :: Exception e => e -> SomeException
fromException :: Exception e => SomeException -> Maybe e

-- | Render this exception value in a human-friendly manner.
--   
--   Default implementation: <tt><a>show</a></tt>.
displayException :: Exception e => e -> String

-- | The <tt>SomeException</tt> type is the root of the exception type
--   hierarchy. When an exception of type <tt>e</tt> is thrown, behind the
--   scenes it is encapsulated in a <tt>SomeException</tt>.
data SomeException
[SomeException] :: SomeException

-- | 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>.
instance GHC.Show.Show Relude.Exception.Bug
instance GHC.Exception.Exception Relude.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 Relude.DeepSeq

-- | a variant of <a>deepseq</a> that is useful in some circumstances:
--   
--   <pre>
--   force x = x `deepseq` x
--   </pre>
--   
--   <tt>force x</tt> fully evaluates <tt>x</tt>, and then returns it. Note
--   that <tt>force x</tt> only performs evaluation when the value of
--   <tt>force x</tt> itself is demanded, so essentially it turns shallow
--   evaluation into deep evaluation.
--   
--   <a>force</a> can be conveniently used in combination with
--   <tt>ViewPatterns</tt>:
--   
--   <pre>
--   {-# LANGUAGE BangPatterns, ViewPatterns #-}
--   import Control.DeepSeq
--   
--   someFun :: ComplexData -&gt; SomeResult
--   someFun (force -&gt; !arg) = {- 'arg' will be fully evaluated -}
--   </pre>
--   
--   Another useful application is to combine <a>force</a> with
--   <a>evaluate</a> in order to force deep evaluation relative to other
--   <a>IO</a> operations:
--   
--   <pre>
--   import Control.Exception (evaluate)
--   import Control.DeepSeq
--   
--   main = do
--     result &lt;- evaluate $ force $ pureComputation
--     {- 'result' will be fully evaluated at this point -}
--     return ()
--   </pre>
--   
--   Finally, here's an exception safe variant of the <tt>readFile'</tt>
--   example:
--   
--   <pre>
--   readFile' :: FilePath -&gt; IO String
--   readFile' fn = bracket (openFile fn ReadMode) hClose $ \h -&gt;
--                          evaluate . force =&lt;&lt; hGetContents h
--   </pre>
force :: NFData a => a -> a

-- | the deep analogue of <a>$!</a>. In the expression <tt>f $!! x</tt>,
--   <tt>x</tt> is fully evaluated before the function <tt>f</tt> is
--   applied to it.
($!!) :: NFData a => a -> b -> a -> b
infixr 0 $!!

-- | <a>deepseq</a>: fully evaluates the first argument, before returning
--   the second.
--   
--   The name <a>deepseq</a> is used to illustrate the relationship to
--   <a>seq</a>: where <a>seq</a> is shallow in the sense that it only
--   evaluates the top level of its argument, <a>deepseq</a> traverses the
--   entire data structure evaluating it completely.
--   
--   <a>deepseq</a> can be useful for forcing pending exceptions,
--   eradicating space leaks, or forcing lazy I/O to happen. It is also
--   useful in conjunction with parallel Strategies (see the
--   <tt>parallel</tt> package).
--   
--   There is no guarantee about the ordering of evaluation. The
--   implementation may evaluate the components of the structure in any
--   order or in parallel. To impose an actual order on evaluation, use
--   <tt>pseq</tt> from <a>Control.Parallel</a> in the <tt>parallel</tt>
--   package.
deepseq :: NFData a => a -> b -> b

-- | A class of types that can be fully evaluated.
class NFData a

-- | <a>rnf</a> should reduce its argument to normal form (that is, fully
--   evaluate all sub-components), and then return '()'.
--   
--   <h3><a>Generic</a> <a>NFData</a> deriving</h3>
--   
--   Starting with GHC 7.2, you can automatically derive instances for
--   types possessing a <a>Generic</a> instance.
--   
--   Note: <a>Generic1</a> can be auto-derived starting with GHC 7.4
--   
--   <pre>
--   {-# LANGUAGE DeriveGeneric #-}
--   
--   import GHC.Generics (Generic, Generic1)
--   import Control.DeepSeq
--   
--   data Foo a = Foo a String
--                deriving (Eq, Generic, Generic1)
--   
--   instance NFData a =&gt; NFData (Foo a)
--   instance NFData1 Foo
--   
--   data Colour = Red | Green | Blue
--                 deriving Generic
--   
--   instance NFData Colour
--   </pre>
--   
--   Starting with GHC 7.10, the example above can be written more
--   concisely by enabling the new <tt>DeriveAnyClass</tt> extension:
--   
--   <pre>
--   {-# LANGUAGE DeriveGeneric, DeriveAnyClass #-}
--   
--   import GHC.Generics (Generic)
--   import Control.DeepSeq
--   
--   data Foo a = Foo a String
--                deriving (Eq, Generic, Generic1, NFData, NFData1)
--   
--   data Colour = Red | Green | Blue
--                 deriving (Generic, NFData)
--   </pre>
--   
--   <h3>Compatibility with previous <tt>deepseq</tt> versions</h3>
--   
--   Prior to version 1.4.0.0, the default implementation of the <a>rnf</a>
--   method was defined as
--   
--   <pre>
--   <a>rnf</a> a = <a>seq</a> a ()
--   </pre>
--   
--   However, starting with <tt>deepseq-1.4.0.0</tt>, the default
--   implementation is based on <tt>DefaultSignatures</tt> allowing for
--   more accurate auto-derived <a>NFData</a> instances. If you need the
--   previously used exact default <a>rnf</a> method implementation
--   semantics, use
--   
--   <pre>
--   instance NFData Colour where rnf x = seq x ()
--   </pre>
--   
--   or alternatively
--   
--   <pre>
--   instance NFData Colour where rnf = rwhnf
--   </pre>
--   
--   or
--   
--   <pre>
--   {-# LANGUAGE BangPatterns #-}
--   instance NFData Colour where rnf !_ = ()
--   </pre>
rnf :: NFData a => a -> ()

-- | 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 Relude.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 Relude.Bool


-- | Fixes and additions to <a>Foldable</a>.
module Relude.Foldable.Fold

-- | 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' :: Foldable f => (a -> b -> b) -> b -> f a -> b
foldMapA :: (Monoid b, Applicative m, Foldable f) => (a -> m b) -> f a -> m b
foldMapM :: (Monoid b, Monad m, Foldable f) => (a -> m b) -> f a -> m b
safeHead :: Foldable f => f a -> Maybe a

-- | Stricter version of <a>sum</a>.
--   
--   <pre>
--   &gt;&gt;&gt; sum [1..10]
--   55
--   </pre>
sum :: forall a f. (Foldable f, Num a) => f a -> a

-- | Stricter version of <a>product</a>.
--   
--   <pre>
--   &gt;&gt;&gt; product [1..10]
--   3628800
--   </pre>
product :: forall a f. (Foldable f, Num a) => f a -> a

-- | Like <a>elem</a> but doesn't work on <a>Set</a> and <a>HashSet</a> for
--   performance reasons.
--   
--   <pre>
--   &gt;&gt;&gt; elem 'x' ("abc" :: String)
--   False
--   
--   &gt;&gt;&gt; elem False (one True :: Set Bool)
--   ...
--       • Do not use 'elem' and 'notElem' methods from 'Foldable' on Set
--         Suggestions:
--             Instead of
--                 elem :: (Foldable t, Eq a) =&gt; a -&gt; t a -&gt; Bool
--             use
--                 member :: ??? -- TODO
--   ...
--             Instead of
--                 notElem :: (Foldable t, Eq a) =&gt; a -&gt; t a -&gt; Bool
--             use
--                 notMember :: ??? -- TODO
--   ...
--   </pre>
elem :: (Foldable f, DisallowElem f, Eq a) => a -> f a -> Bool

-- | Like <a>notElem</a> but doesn't work on <a>Set</a> and <a>HashSet</a>
--   for performance reasons.
--   
--   <pre>
--   &gt;&gt;&gt; notElem 'x' ("abc" :: String)
--   True
--   
--   &gt;&gt;&gt; notElem False (one True :: Set Bool)
--   ...
--       • Do not use 'elem' and 'notElem' methods from 'Foldable' on Set
--         Suggestions:
--             Instead of
--                 elem :: (Foldable t, Eq a) =&gt; a -&gt; t a -&gt; Bool
--             use
--                 member :: ??? -- TODO
--   ...
--             Instead of
--                 notElem :: (Foldable t, Eq a) =&gt; a -&gt; t a -&gt; Bool
--             use
--                 notMember :: ??? -- TODO
--   ...
--   </pre>
notElem :: (Foldable f, DisallowElem f, Eq a) => a -> f a -> Bool

-- | Monadic 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 :: (Foldable f, Monad m) => (a -> m Bool) -> f a -> m Bool

-- | Monadic 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 :: (Foldable f, Monad m) => (a -> m Bool) -> f a -> m Bool

-- | Monadic 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 :: (Foldable f, Monad m) => f (m Bool) -> m Bool

-- | Monadic 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 :: (Foldable f, Monad m) => f (m Bool) -> m Bool


-- | This module exports all <a>Foldable</a> and <a>Traversable</a> related
--   stuff.
module Relude.Foldable


-- | Contains implememtation of polymorhic type classes for things like
--   <a>Set</a> and <a>Map</a>.
module Relude.Extra.Map

-- | Read-only map or set. Contains polymorhic functions which work for
--   both sets and maps.
class StaticMap t where {
    type family Key t :: Type;
    type family Val t :: Type;
}
size :: StaticMap t => t -> Int
lookup :: StaticMap t => Key t -> t -> Maybe (Val t)
member :: StaticMap t => Key t -> t -> Bool

-- | Modifiable Map.
class StaticMap t => DynamicMap t
insert :: DynamicMap t => Key t -> Val t -> t -> t
insertWith :: DynamicMap t => (Val t -> Val t -> Val t) -> Key t -> Val t -> t -> t
delete :: DynamicMap t => Key t -> t -> t
alter :: DynamicMap t => (Maybe (Val t) -> Maybe (Val t)) -> Key t -> t -> t

-- | Operator version of <a>lookup</a> function.
(!?) :: StaticMap t => t -> Key t -> Maybe (Val t)
infixl 9 !?

-- | Inverse of <a>member</a> function.
notMember :: StaticMap t => Key t -> t -> Bool

-- | Return the value to which the specified key is mapped, or the default
--   value if this map contains no mapping for the key.
lookupDefault :: StaticMap t => Val t -> Key t -> t -> Val t

-- | Converts the structure to the list of the key-value pairs.
--   
--   <pre>
--   &gt;&gt;&gt; toPairs (HashMap.fromList [('a', "xxx"), ('b', "yyy")])
--   [('a',"xxx"),('b',"yyy")]
--   </pre>
toPairs :: (IsList t, Item t ~ (a, b)) => t -> [(a, b)]

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

-- | Converts the structure to the list of the values.
--   
--   <pre>
--   &gt;&gt;&gt; elems (HashMap.fromList [('a', "xxx"), ('b', "yyy")])
--   ["xxx","yyy"]
--   </pre>
elems :: (IsList t, Item t ~ (a, b)) => t -> [b]
instance GHC.Classes.Ord k => Relude.Extra.Map.DynamicMap (Data.Map.Internal.Map k v)
instance (GHC.Classes.Eq k, Data.Hashable.Class.Hashable k) => Relude.Extra.Map.DynamicMap (Data.HashMap.Base.HashMap k v)
instance Relude.Extra.Map.DynamicMap (Data.IntMap.Internal.IntMap v)
instance GHC.Classes.Ord k => Relude.Extra.Map.StaticMap (Data.Map.Internal.Map k v)
instance (GHC.Classes.Eq k, Data.Hashable.Class.Hashable k) => Relude.Extra.Map.StaticMap (Data.HashMap.Base.HashMap k v)
instance Relude.Extra.Map.StaticMap (Data.IntMap.Internal.IntMap v)
instance GHC.Classes.Ord a => Relude.Extra.Map.StaticMap (Data.Set.Internal.Set a)
instance (GHC.Classes.Eq a, Data.Hashable.Class.Hashable a) => Relude.Extra.Map.StaticMap (Data.HashSet.HashSet a)
instance Relude.Extra.Map.StaticMap Data.IntSet.Internal.IntSet


-- | 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>Relude</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>Relude.SomeTheme.Reexport</tt> and our own functions and types are
--   in <tt>Relude.SomeTheme.SomeName</tt>. For example, see modules
--   <a>Relude.Container.Class</a> and <a>Relude.Container.Reexport</a>.
--   
--   Below is a short description of what you can find under different
--   modules:
--   
--   <ul>
--   <li><b><a>Relude.Applicative</a></b>: reexports from
--   <a>Control.Applicative</a> and some general-purpose applicative
--   combinators.</li>
--   <li><b><a>Relude.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>Relude.Bool</a></b>: <a>Bool</a> data type with different
--   predicates and combinators.</li>
--   <li><b><a>Relude.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>Relude.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>Relude.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>Relude.Foldable</a></b>: reexports functions for
--   <a>Foldable</a> and <a>Traversable</a>.</li>
--   <li><b><a>Relude.Function</a></b>: almost everything from
--   <a>Data.Function</a> module.</li>
--   <li><b><a>Relude.Functor</a></b>: reexports from <a>Data.Functor</a>,
--   <a>Data.Bifunctor</a>, other useful <a>Functor</a> combinators.</li>
--   <li><b><a>Relude.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>Relude.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>Relude.Monad</a></b>: monad transormers, combinators for
--   <a>Maybe</a> and <a>Either</a>.</li>
--   <li><b><a>Relude.Monoid</a></b>: reexports from <a>Data.Monoid</a> and
--   <a>Data.Semigroup</a>.</li>
--   <li><b><a>Relude.Nub</a></b>: better versions of <tt>nub</tt> function
--   for list.</li>
--   <li><b><a>Relude.Print</a></b>: polymorphic <a>putStrLn</a> function
--   and functions to print <a>Text</a>.</li>
--   <li><b><a>Relude.String</a></b>: reexports from <tt>text</tt> and
--   <tt>bytestring</tt> packages with conversion functions between
--   different textual types.</li>
--   <li><b><a>Relude.Unsafe</a></b>: unsafe functions (produce
--   <a>error</a>). Not exported by <a>Relude</a> module by default.</li>
--   </ul>
module Relude

module Relude.Extra.Group

-- | Groups elements using results of the given function as keys.
--   
--   <pre>
--   &gt;&gt;&gt; groupBy even [1..6] :: HashMap Bool (NonEmpty Int)
--   fromList [(False,5 :| [3,1]),(True,6 :| [4,2])]
--   </pre>
groupBy :: forall f t a. (Foldable f, DynamicMap t, Val t ~ NonEmpty a, Monoid t) => (a -> Key t) -> f a -> t

-- | Similar to <a>groupBy</a> but keeps only one element as value.
--   
--   <pre>
--   &gt;&gt;&gt; groupOneBy even [1 .. 6] :: HashMap Bool Int
--   fromList [(False,1),(True,2)]
--   </pre>
groupOneBy :: forall f t a. (Foldable f, DynamicMap t, Val t ~ a, Monoid t) => (a -> Key t) -> f a -> t

module Relude.Extra.Enum

-- | Returns all values of some <a>Bounded</a> <a>Enum</a> in ascending
--   order.
--   
--   <pre>
--   &gt;&gt;&gt; data TrafficLight = Red | Blue | Green deriving (Show, Enum, Bounded)
--   
--   &gt;&gt;&gt; universe :: [TrafficLight]
--   [Red,Blue,Green]
--   
--   &gt;&gt;&gt; universe :: [Bool]
--   [False,True]
--   </pre>
universe :: (Bounded a, Enum a) => [a]

-- | Creates a function that is the inverse of a given function <tt>f</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; data Color = Red | Green | Blue deriving (Show, Enum, Bounded)
--   
--   &gt;&gt;&gt; parse = inverseMap show :: String -&gt; Maybe Color
--   
--   &gt;&gt;&gt; parse "Red"
--   Just Red
--   
--   &gt;&gt;&gt; parse "Black"
--   Nothing
--   </pre>
inverseMap :: forall a k. (Bounded a, Enum a, Ord k) => (a -> k) -> k -> Maybe a

-- | Like <a>succ</a>, but doesn't fail on <a>maxBound</a>. Instead it
--   returns <a>minBound</a>.
--   
--   <pre>
--   &gt;&gt;&gt; next False
--   True
--   
--   &gt;&gt;&gt; next True
--   False
--   
--   &gt;&gt;&gt; succ True
--   *** Exception: Prelude.Enum.Bool.succ: bad argument
--   </pre>
next :: (Eq a, Bounded a, Enum a) => a -> a

-- | Returns <a>Nothing</a> if given <a>Int</a> outside range.
--   
--   <pre>
--   &gt;&gt;&gt; safeToEnum @Bool 0
--   Just False
--   
--   &gt;&gt;&gt; safeToEnum @Bool 1
--   Just True
--   
--   &gt;&gt;&gt; safeToEnum @Bool 2
--   Nothing
--   
--   &gt;&gt;&gt; safeToEnum @Bool (-1)
--   Nothing
--   </pre>
safeToEnum :: forall a. (Bounded a, Enum a) => Int -> Maybe a

module Relude.Extra.Bifunctor
bimapF :: (Functor f, Bifunctor p) => (a -> c) -> (b -> d) -> f (p a b) -> f (p c d)
firstF :: (Functor f, Bifunctor p) => (a -> c) -> f (p a b) -> f (p c b)
secondF :: (Functor f, Bifunctor p) => (b -> d) -> f (p a b) -> f (p a d)


-- | 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 Relude.Unsafe as Unsafe
--   
--   foo :: [a] -&gt; a
--   foo = Unsafe.head
--   </pre>
module Relude.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
