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


-- | Safe, performant, user-friendly and lightweight Haskell Standard Library
--   
--   <tt><b>relude</b></tt> is an alternative prelude library. If you find
--   the default <tt>Prelude</tt> unsatisfying, despite its advantages,
--   consider using <tt>relude</tt> instead.
--   
--   <h2>Relude goals and design principles</h2>
--   
--   <ul>
--   <li><b>Productivity.</b> You can be more productive with a
--   "non-standard" standard library, and <tt>relude</tt> helps you with
--   writing safer and more efficient code faster.</li>
--   <li><b>Total programming</b>. Usage of <a><i>partial functions</i></a>
--   can lead to unexpected bugs and runtime exceptions in pure code. The
--   types of partial functions lie about their behaviour. And even if it
--   is not always possible to rely only on total functions,
--   <tt>relude</tt> strives to encourage best-practices and reduce the
--   chances of introducing a bug.TODO: table</li>
--   </ul>
--   
--   <ul>
--   <li><b>Type-safety</b>. We use the <i>"make invalid states
--   unrepresentable"</i> motto as one of our guiding principles. If it is
--   possible, we express this concept through the types.<i>Example:</i>
--   <tt> whenNotNull :: Applicative f =&gt; [a] -&gt; (NonEmpty a -&gt; f
--   ()) -&gt; f () </tt></li>
--   <li><b>Performance.</b> We prefer <tt>Text</tt> over
--   <tt><a>String</a></tt>, use space-leaks-free functions (e.g. our
--   custom performant <tt>sum</tt> and <tt>product</tt>), introduce
--   <tt>{-# INLINE #-}</tt> and <tt>{-# SPECIALIZE #-}</tt> pragmas where
--   appropriate, and make efficient container types (e.g. <tt>Map</tt>,
--   <tt>HashMap</tt>, <tt>Set</tt>) more accessible.</li>
--   <li><b>Minimalism</b> (low number of dependencies). We do not force
--   users of <tt>relude</tt> to stick to any specific lens or text
--   formatting or logging library. Where possible, <tt>relude</tt> depends
--   only on boot libraries. The <a>Dependency graph</a> of <tt>relude</tt>
--   can give you a clearer picture.</li>
--   <li><b>Convenience</b>. Despite minimalism, we want to bring commonly
--   used types and functions into scope, and make available functions
--   easier to use. Some examples of conveniences:<ol><li>No need to add
--   <tt>containers</tt>, <tt>unordered-containers</tt>, <tt>text</tt> and
--   <tt>bytestring</tt> to dependencies in your <tt>.cabal</tt> file to
--   use the main API of these libraries</li><li>No need to import types
--   like <tt>NonEmpty</tt>, <tt>Text</tt>, <tt>Set</tt>,
--   <tt>Reader[T]</tt>, <tt>MVar</tt>, <tt>STM</tt></li><li>Functions like
--   <tt>liftIO</tt>, <tt>fromMaybe</tt>, <tt>sortWith</tt> are available
--   by default as well</li><li><tt>IO</tt> actions are lifted to
--   <tt>MonadIO</tt></li></ol></li>
--   <li><b>Excellent documentation.</b><ol><li>Tutorial</li><li>Migration
--   guide from <tt>Prelude</tt></li><li>Haddock for every function with
--   examples tested by <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></li>
--   <li><b>User-friendliness.</b> Anyone should be able to quickly migrate
--   to <tt>relude</tt>. Only some basic familiarity with the common
--   libraries like <tt>text</tt> and <tt>containers</tt> should be enough
--   (but not necessary).</li>
--   <li><b>Exploration.</b> We have space to experiment with new ideas and
--   proposals without introducing breaking changes. <tt>relude</tt> uses
--   the approach with <tt>Extra.*</tt> modules which are not exported by
--   default. The chosen approach makes it quite easy for us to provide new
--   functionality without breaking anything and let the users decide to
--   use it or not.</li>
--   </ul>
@package relude
@version 1.2.2.2


-- | This module contains reexports of <a>Applicative</a> and related
--   functional. Additionally, it provides convenient combinators to work
--   with <a>Applicative</a>.
module Relude.Applicative
class Applicative f => Alternative (f :: Type -> Type)
empty :: Alternative f => f a
(<|>) :: Alternative f => f a -> f a -> f a
some :: Alternative f => f a -> f [a]
many :: Alternative f => f a -> f [a]
class Functor f => Applicative (f :: Type -> Type)
pure :: Applicative f => a -> f a
(<*>) :: Applicative f => f (a -> b) -> f a -> f b
liftA2 :: Applicative f => (a -> b -> c) -> f a -> f b -> f c
(*>) :: Applicative f => f a -> f b -> f b
(<*) :: Applicative f => f a -> f b -> f a
newtype Const a (b :: k)
Const :: a -> Const a (b :: k)
[getConst] :: Const a (b :: k) -> a
newtype ZipList a
ZipList :: [a] -> ZipList a
[getZipList] :: ZipList a -> [a]
liftA3 :: Applicative f => (a -> b -> c -> d) -> f a -> f b -> f c -> f d
optional :: Alternative f => f a -> f (Maybe a)
(<**>) :: Applicative f => f a -> f (a -> b) -> f b

-- | Shorter alias for <tt>pure ()</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; pass :: Maybe ()
--   Just ()
--   </pre>
--   
--   Useful shortcut when need an empty action:
--   
--   <pre>
--   printJust :: Maybe Int -&gt; IO ()
--   printJust mInt = case mInt of
--       Just i -&gt; putStrLn $ "Number: " ++ show i
--       Nothing -&gt; pass
--   </pre>
pass :: Applicative f => f ()

-- | Named version of the <a>&lt;**&gt;</a> operator, which is
--   <a>&lt;*&gt;</a> but flipped. It is helpful for chaining applicative
--   operations in forward applications using <a>&amp;</a>.
--   
--   <pre>
--   &gt;&gt;&gt; Just (+ 1) &amp; appliedTo (Just 2)
--   Just 3
--   
--   &gt;&gt;&gt; Just (+) &amp; appliedTo (Just 1) &amp; appliedTo (Just 2)
--   Just 3
--   
--   &gt;&gt;&gt; Nothing &amp; appliedTo (Just 2)
--   Nothing
--   </pre>
appliedTo :: Applicative f => f a -> f (a -> b) -> f b


-- | Reexports from <tt>Data.*</tt> and <tt>GHC.*</tt> modules of
--   <a>base</a> package.
module Relude.Base
data Char
chr :: Int -> Char
class Eq a
(==) :: Eq a => a -> a -> Bool
(/=) :: Eq a => a -> a -> Bool
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
newtype Down a
Down :: a -> Down a
[getDown] :: Down a -> a
data Ordering
LT :: Ordering
EQ :: Ordering
GT :: Ordering
comparing :: Ord a => (b -> a) -> b -> b -> Ordering
type FilePath = String
data IO a
data IOMode
ReadMode :: IOMode
WriteMode :: IOMode
AppendMode :: IOMode
ReadWriteMode :: IOMode
class a ~R# b => Coercible (a :: k) (b :: k)
coerce :: Coercible a b => a -> b
type Constraint = CONSTRAINT LiftedRep
type Type = TYPE LiftedRep
data Proxy (t :: k)
Proxy :: Proxy (t :: k)
class a ~# b => (a :: k) ~ (b :: k)
class Typeable (a :: k)
data Void
absurd :: Void -> a
vacuous :: Functor f => f Void -> f a
asTypeOf :: a -> a -> a
ord :: Char -> Int
seq :: a -> b -> b
($!) :: (a -> b) -> a -> b
class Generic a
class Show a
type family CmpNat (a :: Natural) (b :: Natural) :: Ordering
class KnownNat (n :: Nat)
type Nat = Natural
data SomeNat
SomeNat :: Proxy n -> SomeNat
natVal :: forall (n :: Nat) proxy. KnownNat n => proxy n -> Natural
someNatVal :: Natural -> SomeNat
class IsLabel (x :: Symbol) a
fromLabel :: IsLabel x a => a
getStackTrace :: IO (Maybe [Location])
showStackTrace :: IO (Maybe String)
data CallStack
type HasCallStack = ?callStack :: CallStack
callStack :: HasCallStack => CallStack
currentCallStack :: IO [String]
getCallStack :: CallStack -> [([Char], SrcLoc)]
prettyCallStack :: CallStack -> String
prettySrcLoc :: SrcLoc -> String
withFrozenCallStack :: HasCallStack => (HasCallStack => a) -> a


-- | Reexports functions to work with <a>Bool</a> type.
module Relude.Bool.Reexport
data Bool
False :: Bool
True :: Bool
bool :: a -> a -> Bool -> a
not :: Bool -> Bool
otherwise :: Bool
(&&) :: Bool -> Bool -> Bool
(||) :: Bool -> Bool -> Bool
guard :: Alternative f => Bool -> f ()
when :: Applicative f => Bool -> f () -> f ()
unless :: Applicative f => Bool -> f () -> f ()


-- | Reexports container-related data types, functions and typeclasses from
--   <tt>base</tt>, <tt>containers</tt> and <tt>unordered-containers</tt>
--   packages.
module Relude.Container.Reexport
class Eq a => Hashable a
hashWithSalt :: Hashable a => Int -> a -> Int
data HashMap k v
data HashSet a
data IntMap a
data IntSet
data Map k a
data Seq a
data Set a
curry :: ((a, b) -> c) -> a -> b -> c
fst :: (a, b) -> a
snd :: (a, b) -> b
swap :: (a, b) -> (b, a)
uncurry :: (a -> b -> c) -> (a, b) -> c
class IsList l
fromList :: IsList l => [Item l] -> l
fromListN :: IsList l => Int -> [Item l] -> l


-- | Reexports <a>Data.Foldable</a> and <a>Data.Traversable</a>.
module Relude.Foldable.Reexport
class Foldable (t :: Type -> Type)
fold :: (Foldable t, Monoid m) => t m -> m
foldMap :: (Foldable t, Monoid m) => (a -> m) -> t a -> m
foldMap' :: (Foldable t, Monoid m) => (a -> m) -> t a -> m
foldr :: Foldable t => (a -> b -> b) -> b -> t a -> b
foldl' :: Foldable t => (b -> a -> b) -> b -> t a -> b
toList :: Foldable t => t a -> [a]
null :: Foldable t => t a -> Bool
length :: Foldable t => t a -> Int
all :: Foldable t => (a -> Bool) -> t a -> Bool
and :: Foldable t => t Bool -> Bool
any :: Foldable t => (a -> Bool) -> t a -> Bool
asum :: (Foldable t, Alternative f) => t (f a) -> f a
concat :: Foldable t => t [a] -> [a]
concatMap :: Foldable t => (a -> [b]) -> t a -> [b]
find :: Foldable t => (a -> Bool) -> t a -> Maybe a
foldlM :: (Foldable t, Monad m) => (b -> a -> m b) -> b -> t a -> m b
forM_ :: (Foldable t, Monad m) => t a -> (a -> m b) -> m ()
for_ :: (Foldable t, Applicative f) => t a -> (a -> f b) -> f ()
mapM_ :: (Foldable t, Monad m) => (a -> m b) -> t a -> m ()
or :: Foldable t => t Bool -> Bool
sequenceA_ :: (Foldable t, Applicative f) => t (f a) -> f ()
sequence_ :: (Foldable t, Monad m) => t (m a) -> m ()
traverse_ :: (Foldable t, Applicative f) => (a -> f b) -> t a -> f ()
class (Functor t, Foldable t) => Traversable (t :: Type -> Type)
traverse :: (Traversable t, Applicative f) => (a -> f b) -> t a -> f (t b)
sequenceA :: (Traversable t, Applicative f) => t (f a) -> f (t a)
mapM :: (Traversable t, Monad m) => (a -> m b) -> t a -> m (t b)
sequence :: (Traversable t, Monad m) => t (m a) -> m (t a)
forM :: (Traversable t, Monad m) => t a -> (a -> m b) -> m (t b)
mapAccumL :: Traversable t => (s -> a -> (s, b)) -> s -> t a -> (s, t b)
mapAccumR :: Traversable t => (s -> a -> (s, b)) -> s -> t a -> (s, t b)
class Bifoldable (p :: Type -> Type -> Type)
bifold :: (Bifoldable p, Monoid m) => p m m -> m
bifoldMap :: (Bifoldable p, Monoid m) => (a -> m) -> (b -> m) -> p a b -> m
bifoldr :: Bifoldable p => (a -> c -> c) -> (b -> c -> c) -> c -> p a b -> c
bifoldl :: Bifoldable p => (c -> a -> c) -> (c -> b -> c) -> c -> p a b -> c
biList :: Bifoldable t => t a a -> [a]
biall :: Bifoldable t => (a -> Bool) -> (b -> Bool) -> t a b -> Bool
biand :: Bifoldable t => t Bool Bool -> Bool
biany :: Bifoldable t => (a -> Bool) -> (b -> Bool) -> t a b -> Bool
biasum :: (Bifoldable t, Alternative f) => t (f a) (f a) -> f a
bielem :: (Bifoldable t, Eq a) => a -> t a a -> Bool
bifind :: Bifoldable t => (a -> Bool) -> t a a -> Maybe a
bifoldl' :: Bifoldable t => (a -> b -> a) -> (a -> c -> a) -> a -> t b c -> a
bifoldlM :: (Bifoldable t, Monad m) => (a -> b -> m a) -> (a -> c -> m a) -> a -> t b c -> m a
bifoldr' :: Bifoldable t => (a -> c -> c) -> (b -> c -> c) -> c -> t a b -> c
bifoldrM :: (Bifoldable t, Monad m) => (a -> c -> m c) -> (b -> c -> m c) -> c -> t a b -> m c
bifor_ :: (Bifoldable t, Applicative f) => t a b -> (a -> f c) -> (b -> f d) -> f ()
bilength :: Bifoldable t => t a b -> Int
binull :: Bifoldable t => t a b -> Bool
bior :: Bifoldable t => t Bool Bool -> Bool
bisequence_ :: (Bifoldable t, Applicative f) => t (f a) (f b) -> f ()
bitraverse_ :: (Bifoldable t, Applicative f) => (a -> f c) -> (b -> f d) -> t a b -> f ()
class (Bifunctor t, Bifoldable t) => Bitraversable (t :: Type -> Type -> Type)
bitraverse :: (Bitraversable t, Applicative f) => (a -> f c) -> (b -> f d) -> t a b -> f (t c d)
bifoldMapDefault :: (Bitraversable t, Monoid m) => (a -> m) -> (b -> m) -> t a b -> m
bifor :: (Bitraversable t, Applicative f) => t a b -> (a -> f c) -> (b -> f d) -> f (t c d)
bimapDefault :: Bitraversable t => (a -> b) -> (c -> d) -> t a c -> t b d
bisequence :: (Bitraversable t, Applicative f) => t (f a) (f b) -> f (t a b)


-- | This module reexports very basic and primitive functions and function
--   combinators.
module Relude.Function
(.) :: (b -> c) -> (a -> b) -> a -> c
($) :: (a -> b) -> a -> b
(&) :: a -> (a -> b) -> b
id :: a -> a
const :: a -> b -> a
flip :: (a -> b -> c) -> b -> a -> c
fix :: (a -> a) -> a
on :: (b -> b -> c) -> (a -> b) -> a -> a -> c
(>>>) :: forall {k} cat (a :: k) (b :: k) (c :: k). Category cat => cat a b -> cat b c -> cat a c
(<<<) :: forall {k} cat (b :: k) (c :: k) (a :: k). Category cat => cat b c -> cat a b -> cat a c
(&&&) :: Arrow a => a b c -> a b c' -> a b (c, c')

-- | Renamed version of <a>id</a>.
--   
--   <pre>
--   &gt;&gt;&gt; identity 10
--   10
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fmap identity [1,2,3]
--   [1,2,3]
--   </pre>
identity :: a -> a


-- | Reexports functionality regarding <a>Functor</a> and <a>Bifunctor</a>
--   typeclasses.
module Relude.Functor.Reexport
class Functor (f :: Type -> Type)
fmap :: Functor f => (a -> b) -> f a -> f b
(<$) :: Functor f => a -> f b -> f a
(<$>) :: Functor f => (a -> b) -> f a -> f b
void :: Functor f => f a -> f ()
($>) :: Functor f => f a -> b -> f b
newtype Compose (f :: k -> Type) (g :: k1 -> k) (a :: k1)
Compose :: f (g a) -> Compose (f :: k -> Type) (g :: k1 -> k) (a :: k1)
[getCompose] :: Compose (f :: k -> Type) (g :: k1 -> k) (a :: k1) -> f (g a)
newtype Identity a
Identity :: a -> Identity a
[runIdentity] :: Identity a -> a
class Contravariant (f :: Type -> Type)
contramap :: Contravariant f => (a' -> a) -> f a -> f a'
(>$) :: Contravariant f => b -> f b -> f a
newtype Comparison a
Comparison :: (a -> a -> Ordering) -> Comparison a
[getComparison] :: Comparison a -> a -> a -> Ordering
newtype Equivalence a
Equivalence :: (a -> a -> Bool) -> Equivalence a
[getEquivalence] :: Equivalence a -> a -> a -> Bool
newtype Op a b
Op :: (b -> a) -> Op a b
[getOp] :: Op a b -> b -> a
newtype Predicate a
Predicate :: (a -> Bool) -> Predicate a
[getPredicate] :: Predicate a -> a -> Bool
comparisonEquivalence :: Comparison a -> Equivalence a
defaultComparison :: Ord a => Comparison a
defaultEquivalence :: Eq a => Equivalence a
phantom :: (Functor f, Contravariant f) => f a -> f b
($<) :: Contravariant f => f b -> b -> f a
(>$$<) :: Contravariant f => f b -> (a -> b) -> f a
(>$<) :: Contravariant f => (a -> b) -> f b -> f a
class forall a. () => Functor p a => Bifunctor (p :: Type -> Type -> Type)
bimap :: Bifunctor p => (a -> b) -> (c -> d) -> p a c -> p b d
first :: Bifunctor p => (a -> b) -> p a c -> p b c
second :: Bifunctor p => (b -> c) -> p a b -> p a c


-- | 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 <<$>>
(<&>) :: Functor f => f a -> (a -> b) -> f b

-- | Takes a function in a <a>Functor</a> context and applies it to a
--   normal value.
--   
--   <pre>
--   &gt;&gt;&gt; flap (++) "relude" "P"
--   "Prelude"
--   </pre>
flap :: Functor f => f (a -> b) -> a -> f b

-- | Operator version of the <a>flap</a> function.
--   
--   <pre>
--   &gt;&gt;&gt; [(+2), (*3)] ?? 5
--   [7,15]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; Just (+3) ?? 5
--   Just 8
--   </pre>
(??) :: Functor f => f (a -> b) -> a -> f b
infixl 4 ??


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


-- | Contains utility functions for working with tuples.
module Relude.Extra.Tuple

-- | Creates a tuple by pairing something with itself.
--   
--   <pre>
--   &gt;&gt;&gt; dup "foo"
--   ("foo","foo")
--   
--   &gt;&gt;&gt; dup ()
--   ((),())
--   </pre>
dup :: a -> (a, a)

-- | Apply a function, with the result in the fst slot, and the value in
--   the other.
--   
--   A dual to <a>toSnd</a>.
--   
--   <pre>
--   &gt;&gt;&gt; toFst length [3, 1, 0, 2]
--   (4,[3,1,0,2])
--   
--   &gt;&gt;&gt; toFst (+5) 10
--   (15,10)
--   </pre>
toFst :: (a -> b) -> a -> (b, a)

-- | Apply a function, with the result in the snd slot, and the value in
--   the other.
--   
--   A dual to <a>toFst</a>.
--   
--   <pre>
--   &gt;&gt;&gt; toSnd length [3, 1, 0, 2]
--   ([3,1,0,2],4)
--   
--   &gt;&gt;&gt; toSnd (+5) 10
--   (10,15)
--   </pre>
toSnd :: (a -> b) -> a -> (a, b)

-- | Like <a>fmap</a>, but also keep the original value in the snd
--   position.
--   
--   A dual to <a>fmapToSnd</a>.
--   
--   <pre>
--   &gt;&gt;&gt; fmapToFst show [3, 10, 2]
--   [("3",3),("10",10),("2",2)]
--   </pre>
fmapToFst :: Functor f => (a -> b) -> f a -> f (b, a)

-- | Like <a>fmap</a>, but also keep the original value in the fst
--   position.
--   
--   A dual to <a>fmapToFst</a>.
--   
--   <pre>
--   &gt;&gt;&gt; fmapToSnd show [3, 10, 2]
--   [(3,"3"),(10,"10"),(2,"2")]
--   </pre>
fmapToSnd :: Functor f => (a -> b) -> f a -> f (a, b)

-- | Apply a function, with the result in the fst slot, and the value in
--   the other.
--   
--   A dual to <a>mapToSnd</a>
--   
--   <pre>
--   &gt;&gt;&gt; mapToFst (+1) 10
--   (11,10)
--   </pre>

-- | <i>Deprecated: Use <a>toFst</a> from <a>Tuple</a> instead</i>
mapToFst :: (a -> b) -> a -> (b, a)

-- | Apply a function, with the result in the second slot, and the value in
--   the other.
--   
--   A dual to <a>mapToFst</a>.
--   
--   <pre>
--   &gt;&gt;&gt; mapToSnd (+1) 10
--   (10,11)
--   </pre>

-- | <i>Deprecated: Use <a>toSnd</a> from <a>Tuple</a> instead</i>
mapToSnd :: (a -> b) -> a -> (a, b)

-- | Apply a function that returns a value inside of a functor, with the
--   output in the first slot, the input in the second, and the entire
--   tuple inside the functor.
--   
--   A dual to <a>traverseToSnd</a>
--   
--   <pre>
--   &gt;&gt;&gt; traverseToFst (Just . (+1)) 10
--   Just (11,10)
--   
--   &gt;&gt;&gt; traverseToFst (const Nothing) 10
--   Nothing
--   </pre>
traverseToFst :: Functor t => (a -> t b) -> a -> t (b, a)

-- | Apply a function that returns a value inside of a functor, with the
--   output in the second slot, the input in the first, and the entire
--   tuple inside the functor.
--   
--   A dual to <a>traverseToFst</a>.
--   
--   <pre>
--   &gt;&gt;&gt; traverseToSnd (Just . (+1)) 10
--   Just (10,11)
--   
--   &gt;&gt;&gt; traverseToSnd (const Nothing) 10
--   Nothing
--   </pre>
traverseToSnd :: Functor t => (a -> t b) -> a -> t (a, b)

-- | Maps a function that returns a value inside of an applicative functor
--   over both elements of a tuple, with the entire tuple inside the
--   applicative functor.
--   
--   <pre>
--   &gt;&gt;&gt; traverseBoth (Just . ("Hello " &lt;&gt;)) ("Alice", "Bob")
--   Just ("Hello Alice","Hello Bob")
--   
--   &gt;&gt;&gt; traverseBoth (const Nothing) ("Alice", "Bob")
--   Nothing
--   </pre>
traverseBoth :: Applicative t => (a -> t b) -> (a, a) -> t (b, b)


-- | Reexports <a>Enum</a> related typeclasses and functions. Also
--   introduces a few useful helpers to work with Enums.
--   
--   <b>Note:</b> <a>universe</a>, <a>universeNonEmpty</a> and
--   <a>inverseMap</a> were previously in the extra modules, but due to
--   their benefit in different use cases. If you imported
--   <tt>Relude.Extra.Enum</tt> module, you can remove it now, as these
--   functions are reexported in the main <a>Relude</a> module.
module Relude.Enum

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

-- | Like <a>universe</a>, but returns <a>NonEmpty</a> list of some
--   enumeration
--   
--   <pre>
--   &gt;&gt;&gt; universeNonEmpty :: NonEmpty Bool
--   False :| [True]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; universeNonEmpty @Ordering
--   LT :| [EQ,GT]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; data TrafficLight = Red | Blue | Green deriving (Show, Eq, Enum, Bounded)
--   
--   &gt;&gt;&gt; universeNonEmpty :: NonEmpty TrafficLight
--   Red :| [Blue,Green]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; data Singleton = Singleton deriving (Show, Eq, Enum, Bounded)
--   
--   &gt;&gt;&gt; universeNonEmpty @Singleton
--   Singleton :| []
--   </pre>
universeNonEmpty :: (Bounded a, Enum a) => NonEmpty a

-- | <tt>inverseMap f</tt> creates a function that is the inverse of a
--   given function <tt>f</tt>. It does so by constructing <a>Map</a>
--   internally for each value <tt>f a</tt>. The implementation makes sure
--   that the <a>Map</a> is constructed only once and then shared for every
--   call.
--   
--   <b>Memory usage note:</b> don't inverse functions that have types like
--   <tt>Int</tt> as their input. In this case the created <a>Map</a> will
--   have huge size.
--   
--   The complexity of reversed mapping is &lt;math&gt;.
--   
--   <b>Performance note:</b> make sure to specialize monomorphic type of
--   your functions that use <a>inverseMap</a> to avoid <a>Map</a>
--   reconstruction.
--   
--   One of the common <a>inverseMap</a> use-case is inverting the
--   <tt>show</tt> or a <tt>show</tt>-like function.
--   
--   <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>
--   
--   <b>Correctness note:</b> <a>inverseMap</a> expects <i>injective
--   function</i> as its argument, i.e. the function must map distinct
--   arguments to distinct values.
--   
--   Typical usage of this function looks like this:
--   
--   <pre>
--   <b>data</b> GhcVer
--       = Ghc802
--       | Ghc822
--       | Ghc844
--       | Ghc865
--       | Ghc881
--       <b>deriving</b> (<tt>Eq</tt>, <a>Ord</a>, <tt>Show</tt>, <a>Enum</a>, <a>Bounded</a>)
--   
--   showGhcVer :: GhcVer -&gt; <tt>Text</tt>
--   showGhcVer = \<b>case</b>
--       Ghc802 -&gt; "8.0.2"
--       Ghc822 -&gt; "8.2.2"
--       Ghc844 -&gt; "8.4.4"
--       Ghc865 -&gt; "8.6.5"
--       Ghc881 -&gt; "8.8.1"
--   
--   parseGhcVer :: <tt>Text</tt> -&gt; <a>Maybe</a> GhcVer
--   parseGhcVer = <a>inverseMap</a> showGhcVer
--   </pre>
inverseMap :: (Bounded a, Enum a, Ord k) => (a -> k) -> k -> Maybe a
class Enum a
succ :: Enum a => a -> a
pred :: Enum a => a -> a
toEnum :: Enum a => Int -> a
fromEnum :: Enum a => a -> Int
enumFrom :: Enum a => a -> [a]
enumFromThen :: Enum a => a -> a -> [a]
enumFromTo :: Enum a => a -> a -> [a]
enumFromThenTo :: Enum a => a -> a -> a -> [a]
class Bounded a
minBound :: Bounded a => a
maxBound :: Bounded a => a
boundedEnumFrom :: (Enum a, Bounded a) => a -> [a]
boundedEnumFromThen :: (Enum a, Bounded a) => a -> a -> [a]


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

-- | Lifted version of <a>exitWith</a>.
--   
--   <pre>
--   &gt;&gt;&gt; exitWith (ExitFailure 3)
--   *** Exception: ExitFailure 3
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; exitWith ExitSuccess
--   *** Exception: ExitSuccess
--   </pre>
exitWith :: MonadIO m => ExitCode -> m a

-- | Lifted version of <a>exitFailure</a>.
--   
--   <pre>
--   &gt;&gt;&gt; exitFailure
--   *** Exception: ExitFailure 1
--   </pre>
exitFailure :: MonadIO m => m a

-- | Lifted version of <a>exitSuccess</a>.
--   
--   <pre>
--   &gt;&gt;&gt; exitSuccess
--   *** Exception: ExitSuccess
--   </pre>
exitSuccess :: MonadIO m => m a

-- | Lifted version of <a>die</a>.
--   
--   <pre>
--   &gt;&gt;&gt; die "Goodbye!"
--   Goodbye!
--   *** Exception: ExitFailure 1
--   </pre>
die :: MonadIO m => String -> m a


-- | Lifted reexports from <a>Data.IORef</a> module.
module Relude.Lifted.IORef
data IORef a

-- | Lifted version of <a>atomicModifyIORef</a>.
--   
--   <pre>
--   &gt;&gt;&gt; ref &lt;- newIORef 42
--   
--   &gt;&gt;&gt; atomicModifyIORef ref (\a -&gt; (a, a + 3))
--   45
--   
--   &gt;&gt;&gt; readIORef ref
--   42
--   </pre>
--   
--   <ul>
--   <li>To avoid space-leaks, see <a>atomicModifyIORef'</a> for stricter
--   updates</li>
--   <li>If you are not interested in the return value, see
--   <a>atomicModifyIORef_</a></li>
--   </ul>
atomicModifyIORef :: MonadIO m => IORef a -> (a -> (a, b)) -> m b

-- | Lifted version of <a>atomicModifyIORef'</a>.
--   
--   <pre>
--   &gt;&gt;&gt; ref &lt;- newIORef 42
--   
--   &gt;&gt;&gt; atomicModifyIORef' ref (\a -&gt; (a, a + 3))
--   45
--   
--   &gt;&gt;&gt; readIORef ref
--   42
--   </pre>
--   
--   <ul>
--   <li>For lazier updates, see <a>atomicModifyIORef</a></li>
--   <li>If you are not interested in the return value, see
--   <a>atomicModifyIORef'_</a></li>
--   </ul>
atomicModifyIORef' :: MonadIO m => IORef a -> (a -> (a, b)) -> m b

-- | Version of <a>atomicModifyIORef</a> that discards return value. Useful
--   when you want to update <a>IORef</a> but not interested in the
--   returning result.
--   
--   <pre>
--   &gt;&gt;&gt; ref &lt;- newIORef 42
--   
--   &gt;&gt;&gt; atomicModifyIORef_ ref (`div` 2)
--   
--   &gt;&gt;&gt; readIORef ref
--   21
--   </pre>
atomicModifyIORef_ :: MonadIO m => IORef a -> (a -> a) -> m ()

-- | Version of <a>atomicModifyIORef'</a> that discards return value.
--   Useful when you want to update <a>IORef</a> but not interested in the
--   returning result.
--   
--   <pre>
--   &gt;&gt;&gt; ref &lt;- newIORef 42
--   
--   &gt;&gt;&gt; atomicModifyIORef'_ ref (`div` 2)
--   
--   &gt;&gt;&gt; readIORef ref
--   21
--   </pre>
atomicModifyIORef'_ :: MonadIO m => IORef a -> (a -> a) -> m ()

-- | Lifted version of <a>atomicWriteIORef</a>.
--   
--   <pre>
--   &gt;&gt;&gt; ref &lt;- newIORef 42
--   
--   &gt;&gt;&gt; atomicWriteIORef ref 45
--   
--   &gt;&gt;&gt; readIORef ref
--   45
--   </pre>
atomicWriteIORef :: MonadIO m => IORef a -> a -> m ()

-- | Lifted version of <a>modifyIORef</a>.
--   
--   <pre>
--   &gt;&gt;&gt; ref &lt;- newIORef 42
--   
--   &gt;&gt;&gt; modifyIORef ref (\a -&gt; a + 6)
--   
--   &gt;&gt;&gt; readIORef ref
--   48
--   </pre>
--   
--   <ul>
--   <li>To avoid space-leaks, see <a>modifyIORef'</a> for stricter
--   updates</li>
--   <li>For atomic updates, see <a>atomicModifyIORef</a></li>
--   </ul>
modifyIORef :: MonadIO m => IORef a -> (a -> a) -> m ()

-- | Lifted version of <a>modifyIORef'</a>.
--   
--   <pre>
--   &gt;&gt;&gt; ref &lt;- newIORef 42
--   
--   &gt;&gt;&gt; modifyIORef' ref (\a -&gt; a + 3)
--   
--   &gt;&gt;&gt; readIORef ref
--   45
--   </pre>
--   
--   <ul>
--   <li>For lazier updates, see <a>modifyIORef</a></li>
--   <li>For atomic updates, see <a>atomicModifyIORef'</a></li>
--   </ul>
modifyIORef' :: MonadIO m => IORef a -> (a -> a) -> m ()

-- | Lifted version of <a>newIORef</a>.
--   
--   <pre>
--   &gt;&gt;&gt; ref &lt;- newIORef False
--   
--   &gt;&gt;&gt; :t ref
--   ref :: IORef Bool
--   </pre>
newIORef :: MonadIO m => a -> m (IORef a)

-- | Lifted version of <a>readIORef</a>.
--   
--   <pre>
--   &gt;&gt;&gt; ref &lt;- newIORef 42
--   
--   &gt;&gt;&gt; readIORef ref
--   42
--   </pre>
readIORef :: MonadIO m => IORef a -> m a

-- | Lifted version of <a>writeIORef</a>.
--   
--   <pre>
--   &gt;&gt;&gt; ref &lt;- newIORef 42
--   
--   &gt;&gt;&gt; writeIORef ref 43
--   
--   &gt;&gt;&gt; readIORef ref
--   43
--   </pre>
writeIORef :: MonadIO m => IORef a -> a -> m ()


-- | Reexports most of the <a>Data.List</a>.
module Relude.List.Reexport
group :: Eq a => [a] -> [[a]]
drop :: Int -> [a] -> [a]
(++) :: [a] -> [a] -> [a]
break :: (a -> Bool) -> [a] -> ([a], [a])
dropWhile :: (a -> Bool) -> [a] -> [a]
filter :: (a -> Bool) -> [a] -> [a]
genericDrop :: Integral i => i -> [a] -> [a]
genericLength :: Num i => [a] -> i
genericReplicate :: Integral i => i -> a -> [a]
genericSplitAt :: Integral i => i -> [a] -> ([a], [a])
genericTake :: Integral i => i -> [a] -> [a]
inits :: [a] -> [[a]]
intercalate :: [a] -> [[a]] -> [a]
intersperse :: a -> [a] -> [a]
isPrefixOf :: Eq a => [a] -> [a] -> Bool
iterate :: (a -> a) -> a -> [a]
map :: (a -> b) -> [a] -> [b]
permutations :: [a] -> [[a]]
repeat :: a -> [a]
replicate :: Int -> a -> [a]
reverse :: [a] -> [a]
scanl :: (b -> a -> b) -> b -> [a] -> [b]
scanl' :: (b -> a -> b) -> b -> [a] -> [b]
scanl1 :: (a -> a -> a) -> [a] -> [a]
scanr :: (a -> b -> b) -> b -> [a] -> [b]
scanr1 :: (a -> a -> a) -> [a] -> [a]
sort :: Ord a => [a] -> [a]
sortBy :: (a -> a -> Ordering) -> [a] -> [a]
sortOn :: Ord b => (a -> b) -> [a] -> [a]
span :: (a -> Bool) -> [a] -> ([a], [a])
splitAt :: Int -> [a] -> ([a], [a])
subsequences :: [a] -> [[a]]
tails :: [a] -> [[a]]
take :: Int -> [a] -> [a]
takeWhile :: (a -> Bool) -> [a] -> [a]
transpose :: [[a]] -> [[a]]
uncons :: [a] -> Maybe (a, [a])
unfoldr :: (b -> Maybe (a, b)) -> b -> [a]
unzip :: [(a, b)] -> ([a], [b])
unzip3 :: [(a, b, c)] -> ([a], [b], [c])
zip :: [a] -> [b] -> [(a, b)]
zip3 :: [a] -> [b] -> [c] -> [(a, b, c)]
zipWith :: (a -> b -> c) -> [a] -> [b] -> [c]

-- | Creates an infinite list from a finite list by appending the list to
--   itself infinite times (i.e. by cycling the list). Unlike
--   <tt>cycle</tt> from <a>Data.List</a>, this implementation doesn't
--   throw error on empty lists, but returns an empty list instead.
--   
--   <pre>
--   &gt;&gt;&gt; cycle []
--   []
--   
--   &gt;&gt;&gt; take 10 $ cycle [1,2,3]
--   [1,2,3,1,2,3,1,2,3,1]
--   </pre>
cycle :: [a] -> [a]
sortWith :: Ord b => (a -> b) -> [a] -> [a]


-- | Reexports functions to work with monads.
module Relude.Monad.Reexport
class Monad m => MonadIO (m :: Type -> Type)
liftIO :: MonadIO m => IO a -> m a
newtype ExceptT e (m :: Type -> Type) a
ExceptT :: m (Either e a) -> ExceptT e (m :: Type -> Type) a
runExceptT :: ExceptT e m a -> m (Either e a)
type Reader r = ReaderT r Identity
class Monad m => MonadReader r (m :: Type -> Type) | m -> r
ask :: MonadReader r m => m r
local :: MonadReader r m => (r -> r) -> m a -> m a
reader :: MonadReader r m => (r -> a) -> m a
newtype ReaderT r (m :: Type -> Type) a
ReaderT :: (r -> m a) -> ReaderT r (m :: Type -> Type) a
[runReaderT] :: ReaderT r (m :: Type -> Type) a -> r -> m a
asks :: MonadReader r m => (r -> a) -> m a
runReader :: Reader r a -> r -> a
withReader :: (r' -> r) -> Reader r a -> Reader r' a
withReaderT :: forall r' r (m :: Type -> Type) a. (r' -> r) -> ReaderT r m a -> ReaderT r' m a
class Monad m => MonadState s (m :: Type -> Type) | m -> s
get :: MonadState s m => m s
put :: MonadState s m => s -> m ()
state :: MonadState s m => (s -> (a, s)) -> m a
type State s = StateT s Identity
newtype StateT s (m :: Type -> Type) a
StateT :: (s -> m (a, s)) -> StateT s (m :: Type -> Type) a
[runStateT] :: StateT s (m :: Type -> Type) a -> s -> m (a, s)
evalState :: State s a -> s -> a
evalStateT :: Monad m => StateT s m a -> s -> m a
execState :: State s a -> s -> s
execStateT :: Monad m => StateT s m a -> s -> m s
gets :: MonadState s m => (s -> a) -> m a
modify :: MonadState s m => (s -> s) -> m ()
modify' :: MonadState s m => (s -> s) -> m ()
runState :: State s a -> s -> (a, s)
withState :: (s -> s) -> State s a -> State s a
class forall (m :: Type -> Type). Monad m => Monad t m => MonadTrans (t :: Type -> Type -> Type -> Type)
lift :: (MonadTrans t, Monad m) => m a -> t m a
data IdentityT (f :: k -> Type) (a :: k)
newtype MaybeT (m :: Type -> Type) a
MaybeT :: m (Maybe a) -> MaybeT (m :: Type -> Type) a
[runMaybeT] :: MaybeT (m :: Type -> Type) a -> m (Maybe a)
exceptToMaybeT :: forall (m :: Type -> Type) e a. Functor m => ExceptT e m a -> MaybeT m a
maybeToExceptT :: forall (m :: Type -> Type) e a. Functor m => e -> MaybeT m a -> ExceptT e m a
class Applicative m => Monad (m :: Type -> Type)
(>>=) :: Monad m => m a -> (a -> m b) -> m b
(>>) :: Monad m => m a -> m b -> m b
return :: Monad m => a -> m a
class (Alternative m, Monad m) => MonadPlus (m :: Type -> Type)
mzero :: MonadPlus m => m a
mplus :: MonadPlus m => m a -> m a -> m a
(<$!>) :: Monad m => (a -> b) -> m a -> m b
filterM :: Applicative m => (a -> m Bool) -> [a] -> m [a]
forever :: Applicative f => f a -> f b
join :: Monad m => m (m a) -> m a
mapAndUnzipM :: Applicative m => (a -> m (b, c)) -> [a] -> m ([b], [c])
mfilter :: MonadPlus m => (a -> Bool) -> m a -> m a
replicateM :: Applicative m => Int -> m a -> m [a]
replicateM_ :: Applicative m => Int -> m a -> m ()
zipWithM :: Applicative m => (a -> b -> m c) -> [a] -> [b] -> m [c]
zipWithM_ :: Applicative m => (a -> b -> m c) -> [a] -> [b] -> m ()
(<=<) :: Monad m => (b -> m c) -> (a -> m b) -> a -> m c
(=<<) :: Monad m => (a -> m b) -> m a -> m b
(>=>) :: Monad m => (a -> m b) -> (b -> m c) -> a -> m c
class Monad m => MonadFail (m :: Type -> Type)
fail :: MonadFail m => String -> m a
data Maybe a
Nothing :: Maybe a
Just :: a -> Maybe a
maybe :: b -> (a -> b) -> Maybe a -> b
catMaybes :: [Maybe a] -> [a]
fromMaybe :: a -> Maybe a -> a
isJust :: Maybe a -> Bool
isNothing :: Maybe a -> Bool
listToMaybe :: [a] -> Maybe a
mapMaybe :: (a -> Maybe b) -> [a] -> [b]
maybeToList :: Maybe a -> [a]
data Either a b
Left :: a -> Either a b
Right :: b -> Either a b
partitionEithers :: [Either a b] -> ([a], [b])
either :: (a -> c) -> (b -> c) -> Either a b -> c
isLeft :: Either a b -> Bool
isRight :: Either a b -> Bool
lefts :: [Either a b] -> [a]
rights :: [Either a b] -> [b]


-- | 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 <a>for_</a> 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>.
--   
--   <pre>
--   &gt;&gt;&gt; whenJustM (pure Nothing) $ \b -&gt; print (not b)
--   
--   &gt;&gt;&gt; whenJustM (pure $ Just True) $ \b -&gt; print (not b)
--   False
--   </pre>
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>.
--   
--   <pre>
--   &gt;&gt;&gt; whenNothingM (pure $ Just True) $ True &lt;$ putTextLn "Is Just!"
--   True
--   
--   &gt;&gt;&gt; whenNothingM (pure Nothing) $ False &lt;$ putTextLn "Is Nothing!"
--   Is Nothing!
--   False
--   </pre>
whenNothingM :: Monad m => m (Maybe a) -> m a -> m a

-- | Monadic version of <a>whenNothing_</a>.
--   
--   <pre>
--   &gt;&gt;&gt; whenNothingM_ (pure $ Just True) $ putTextLn "Is Just!"
--   
--   &gt;&gt;&gt; whenNothingM_ (pure Nothing) $ putTextLn "Is Nothing!"
--   Is Nothing!
--   </pre>
whenNothingM_ :: Monad m => m (Maybe a) -> m () -> m ()

-- | The monadic version of the <a>mapMaybe</a> function.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   evenInHalf :: Int -&gt; IO (Maybe Int)
--   evenInHalf n
--       | even n = pure $ Just $ n `div` 2
--       | otherwise = pure Nothing
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; mapMaybeM evenInHalf [1..10]
--   [1,2,3,4,5]
--   </pre>
mapMaybeM :: Monad m => (a -> m (Maybe b)) -> [a] -> m [b]


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

-- | Shorter and more readable alias for <tt>flip runReader</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; usingReader 42 $ asks (+5)
--   47
--   </pre>
usingReader :: r -> Reader r a -> a

-- | Shorter and more readable alias for <tt>flip runReaderT</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; usingReaderT 42 $ asks (+5)
--   47
--   </pre>
usingReaderT :: r -> ReaderT r m a -> m a

-- | This function helps with optimizing performance when working with the
--   <a>ReaderT</a> transformer. If you have code like below, that is
--   called in a loop
--   
--   <pre>
--   step :: Instruction -&gt; <a>ReaderT</a> Config IO Result
--   step instruction = <b>case</b> instruction <b>of</b>
--       Add -&gt; <b>do</b> stuff ...
--       Del -&gt; <b>do</b> stuff ...
--   </pre>
--   
--   you can improve performance of your Haskell applications by using
--   <a>etaReaderT</a> in the following way:
--   
--   <pre>
--   step :: Instruction -&gt; <a>ReaderT</a> Config IO Result
--   step instruction = <a>etaReaderT</a> $ <b>case</b> instruction <b>of</b>
--       Add -&gt; <b>do</b> stuff ...
--       Del -&gt; <b>do</b> stuff ...
--   </pre>
--   
--   For a detailed explanation, refer to the following blog post:
--   
--   <ul>
--   <li><a>Faster Winter 5: Eta-Expanding ReaderT (by Joachim
--   Breitner)</a></li>
--   </ul>
etaReaderT :: forall r (m :: Type -> Type) a. ReaderT r m a -> ReaderT r 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>.
--   
--   <pre>
--   &gt;&gt;&gt; usingStateT 0 $ put 42 &gt;&gt; pure False
--   (False,42)
--   </pre>
usingStateT :: s -> StateT s m a -> m (a, s)

-- | Lift a <a>Maybe</a> to the <a>MaybeT</a> monad
hoistMaybe :: forall (m :: Type -> Type) a. Applicative m => Maybe a -> MaybeT m a

-- | Lift a <a>Either</a> to the <a>ExceptT</a> monad
hoistEither :: forall (m :: Type -> Type) e a. Applicative m => Either e a -> ExceptT e m a


-- | Reexports functions to work with monoids plus adds extra useful
--   functions.
module Relude.Monoid
class Semigroup a => Monoid a
mempty :: Monoid a => a
mappend :: Monoid a => a -> a -> a
mconcat :: Monoid a => [a] -> a
newtype Alt (f :: k -> Type) (a :: k)
Alt :: f a -> Alt (f :: k -> Type) (a :: k)
[getAlt] :: Alt (f :: k -> Type) (a :: k) -> f a
newtype Ap (f :: k -> Type) (a :: k)
Ap :: f a -> Ap (f :: k -> Type) (a :: k)
[getAp] :: Ap (f :: k -> Type) (a :: k) -> f a
newtype All
All :: Bool -> All
[getAll] :: All -> Bool
newtype Any
Any :: Bool -> Any
[getAny] :: Any -> Bool
newtype Dual a
Dual :: a -> Dual a
[getDual] :: Dual a -> a
newtype Endo a
Endo :: (a -> a) -> Endo a
[appEndo] :: Endo a -> a -> a
newtype First a
First :: Maybe a -> First a
[getFirst] :: First a -> Maybe a
newtype Last a
Last :: Maybe a -> Last a
[getLast] :: Last a -> Maybe a
newtype Product a
Product :: a -> Product a
[getProduct] :: Product a -> a
newtype Sum a
Sum :: a -> Sum a
[getSum] :: Sum a -> a
class Semigroup a
(<>) :: Semigroup a => a -> a -> a
sconcat :: Semigroup a => NonEmpty a -> a
stimes :: (Semigroup a, Integral b) => b -> a -> a
data WrappedMonoid m
cycle1 :: Semigroup m => m -> m
mtimesDefault :: (Integral b, Monoid a) => b -> a -> a
stimesIdempotent :: Integral b => b -> a -> a
stimesIdempotentMonoid :: (Integral b, Monoid a) => b -> a -> a
stimesMonoid :: (Integral b, Monoid a) => b -> a -> a
newtype Ap (f :: k -> Type) (a :: k)
Ap :: f a -> Ap (f :: k -> Type) (a :: k)
[getAp] :: Ap (f :: k -> Type) (a :: k) -> f a

-- | Extracts <a>Monoid</a> value from <a>Maybe</a> returning <a>mempty</a>
--   if <a>Nothing</a>.
--   
--   <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

-- | Returns the given value in case of the given predicate is satisfied
--   (is <a>True</a>). Otherwise, it returns <a>mempty</a>.
--   
--   <pre>
--   &gt;&gt;&gt; memptyIfFalse True (Just "Hello")
--   Just "Hello"
--   
--   &gt;&gt;&gt; memptyIfFalse False "Doesn't matter"
--   ""
--   </pre>
memptyIfFalse :: Monoid m => Bool -> m -> m

-- | Returns the given value in case of the given predicate is unsatisfied
--   (is <a>False</a>). Otherwise, it returns <a>mempty</a>.
--   
--   <pre>
--   &gt;&gt;&gt; memptyIfTrue True (Just "Hello")
--   Nothing
--   
--   &gt;&gt;&gt; memptyIfTrue False "Does matter"
--   "Does matter"
--   </pre>
memptyIfTrue :: Monoid m => Bool -> 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 recommendations for usage of particular functions based
--   on benchmarking results.
--   
--   <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>intNub</a> is faster when you work with lists of
--   <a>Int</a>s.</li>
--   <li><a>intNubOn</a> is fast with the lists of type that can have fixed
--   number representations.</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 &lt;math&gt; time and requires
--   <a>Hashable</a>.
--   
--   <pre>
--   &gt;&gt;&gt; hashNub [3, 3, 3, 2, 2, -1, 1]
--   [3,2,-1,1]
--   </pre>
hashNub :: Hashable a => [a] -> [a]

-- | Removes duplicate elements from a list, keeping only the first
--   occurrence of the element.
--   
--   Like <a>nub</a> but runs in &lt;math&gt; 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]

-- | Similar to <a>ordNub</a> but performs nub through the mapped list on
--   the given function.
--   
--   <pre>
--   &gt;&gt;&gt; ordNubOn (`div` 10) [3, 3, 3, 13, 2, 22, -1, 1, 66]
--   [3,13,22,-1,66]
--   </pre>
ordNubOn :: Ord b => (a -> b) -> [a] -> [a]

-- | Removes duplicate elements from a list, keeping only the first
--   occurance of the element.
--   
--   Like <a>nub</a> but runs in &lt;math&gt; time and requires <a>Ord</a>.
--   
--   <pre>
--   &gt;&gt;&gt; intNub [3, 3, 3, 2, 2, -1, 1]
--   [3,2,-1,1]
--   </pre>
intNub :: [Int] -> [Int]

-- | Similar to <a>intNub</a> but works on lists of any types by performing
--   "nubbing" through <a>Int</a>s.
--   
--   <pre>
--   &gt;&gt;&gt; intNubOn fromEnum "ababbbcdaffee"
--   "abcdfe"
--   </pre>
intNubOn :: (a -> Int) -> [a] -> [a]

-- | Like <a>ordNub</a> runs in &lt;math&gt; 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> runs in &lt;math&gt; but has better performance;
--   it doesn't save the order.
--   
--   <pre>
--   &gt;&gt;&gt; unstableNub [3, 3, 3, 2, 2, -1, 1]
--   [1,2,3,-1]
--   </pre>
unstableNub :: Hashable a => [a] -> [a]


-- | Reexports functions to work with <a>Text</a>, <a>ByteString</a> and
--   <a>ShortByteString</a> types.
module Relude.String.Reexport
type String = [Char]
class IsString a
fromString :: IsString a => String -> a
class Read a
readMaybe :: Read a => String -> Maybe a
reads :: Read a => ReadS a
data Text

-- | <a>lines</a> takes <a>Text</a> and splits it into the list by lines.
--   
--   Actual type of this function is the following:
--   
--   <pre>
--   lines :: <a>Text</a> -&gt; [<a>Text</a>]
--   </pre>
--   
--   but it was given a more complex type to provide friendlier compile
--   time errors.
--   
--   <pre>
--   &gt;&gt;&gt; lines ""
--   []
--   
--   &gt;&gt;&gt; lines "one line"
--   ["one line"]
--   
--   &gt;&gt;&gt; lines "line 1\nline 2"
--   ["line 1","line 2"]
--   
--   &gt;&gt;&gt; lines ("string line" :: String)
--   ...
--   ... 'lines' works with 'Text', not 'String'.
--         Possible fixes:
--             1. Make sure OverloadedStrings extension is enabled.
--             2. Apply 'toText' to a single value.
--             3. Apply 'map toText' to the list value.
--   ...
--   
--   &gt;&gt;&gt; lines True
--   ...
--   ... 'lines' works with 'Text'
--         But given: 'Bool'
--   ...
--   </pre>
lines :: IsText t "lines" => t -> [t]

-- | <a>unlines</a> takes list of <a>Text</a> values and joins them with
--   line separator.
--   
--   Actual type of this function is the following:
--   
--   <pre>
--   unlines :: [<a>Text</a>] -&gt; <a>Text</a>
--   </pre>
--   
--   but it was given a more complex type to provide friendlier compile
--   time errors.
--   
--   <pre>
--   &gt;&gt;&gt; unlines []
--   ""
--   
--   &gt;&gt;&gt; unlines ["line 1"]
--   "line 1\n"
--   
--   &gt;&gt;&gt; unlines ["first line", "second line"]
--   "first line\nsecond line\n"
--   
--   &gt;&gt;&gt; unlines (["line 1", "line 2"] :: [String])
--   ...
--   ... 'unlines' works with 'Text', not 'String'.
--         Possible fixes:
--             1. Make sure OverloadedStrings extension is enabled.
--             2. Apply 'toText' to a single value.
--             3. Apply 'map toText' to the list value.
--   ...
--   
--   &gt;&gt;&gt; unlines [True, False]
--   ...
--   ... 'unlines' works with 'Text'
--         But given: 'Bool'
--   ...
--   </pre>
unlines :: IsText t "unlines" => [t] -> t

-- | <a>words</a> takes <a>Text</a> and splits it into the list by words.
--   
--   Actual type of this function is the following:
--   
--   <pre>
--   words :: <a>Text</a> -&gt; [<a>Text</a>]
--   </pre>
--   
--   but it was given a more complex type to provide friendlier compile
--   time errors.
--   
--   <pre>
--   &gt;&gt;&gt; words ""
--   []
--   
--   &gt;&gt;&gt; words "one line"
--   ["one","line"]
--   
--   &gt;&gt;&gt; words "   &gt;_&lt;   "
--   ["&gt;_&lt;"]
--   
--   &gt;&gt;&gt; words ("string words" :: String)
--   ...
--   ... 'words' works with 'Text', not 'String'.
--         Possible fixes:
--             1. Make sure OverloadedStrings extension is enabled.
--             2. Apply 'toText' to a single value.
--             3. Apply 'map toText' to the list value.
--   ...
--   
--   &gt;&gt;&gt; words True
--   ...
--   ... 'words' works with 'Text'
--         But given: 'Bool'
--   ...
--   </pre>
words :: IsText t "words" => t -> [t]

-- | <a>unwords</a> takes list of <a>Text</a> values and joins them with
--   space character.
--   
--   Actual type of this function is the following:
--   
--   <pre>
--   unwords :: [<a>Text</a>] -&gt; <a>Text</a>
--   </pre>
--   
--   but it was given a more complex type to provide friendlier compile
--   time errors.
--   
--   <pre>
--   &gt;&gt;&gt; unwords []
--   ""
--   
--   &gt;&gt;&gt; unwords ["singleWord"]
--   "singleWord"
--   
--   &gt;&gt;&gt; unwords ["word", "another"]
--   "word another"
--   
--   &gt;&gt;&gt; unwords (["word", "another"] :: [String])
--   ...
--   ... 'unwords' works with 'Text', not 'String'.
--         Possible fixes:
--             1. Make sure OverloadedStrings extension is enabled.
--             2. Apply 'toText' to a single value.
--             3. Apply 'map toText' to the list value.
--   ...
--   
--   &gt;&gt;&gt; unwords [True, False]
--   ...
--   ... 'unwords' works with 'Text'
--         But given: 'Bool'
--   ...
--   </pre>
unwords :: IsText t "unwords" => [t] -> t
decodeUtf8' :: ByteString -> Either UnicodeException Text
decodeUtf8With :: OnDecodeError -> ByteString -> Text
type OnDecodeError = OnError Word8 Char
type OnError a b = String -> Maybe a -> Maybe b
data UnicodeException
lenientDecode :: OnDecodeError
strictDecode :: OnDecodeError
data ByteString
data ShortByteString
toShort :: ByteString -> ShortByteString
fromShort :: ShortByteString -> 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; putTextLn $ 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': ...: Invalid UTF-8 stream
--   </pre>
decodeUtf8Strict :: ConvertUtf8 a b => b -> Either UnicodeException a

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

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

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

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

-- | Alias for <a>toStrict</a> function.
fromLazy :: LazyStrict l s => l -> s

-- | Alias for <a>toLazy</a> function.
fromStrict :: LazyStrict l s => s -> l

-- | Version of <a>readEither</a> that returns <a>Text</a> in case of the
--   parse error.
--   
--   <pre>
--   &gt;&gt;&gt; readEither @Int "123"
--   Right 123
--   
--   &gt;&gt;&gt; readEither @Int "aa"
--   Left "Prelude.read: no parse"
--   </pre>
readEither :: Read a => String -> Either Text a

-- | Generalized version of <a>show</a>. Unlike <a>show</a> this function
--   is polymorphic in its result type. This makes it more convenient to
--   work with data types like <a>Text</a> or <a>ByteString</a>. However,
--   if you pass the result of <a>show</a> to a function that expects
--   polymorphic argument, this can break type inference, so use
--   <tt>-XTypeApplications</tt> to specify the textual type explicitly.
--   
--   <pre>
--   &gt;&gt;&gt; show (42 :: Int)
--   "42"
--   
--   &gt;&gt;&gt; show (42 :: Double)
--   "42.0"
--   
--   &gt;&gt;&gt; print (show @Text True)
--   "True"
--   </pre>
show :: forall b a. (Show a, IsString b) => a -> b
instance Relude.String.Conversion.ConvertUtf8 GHC.Internal.Base.String Relude.String.Conversion.LByteString
instance Relude.String.Conversion.ConvertUtf8 GHC.Internal.Base.String Data.ByteString.Internal.Type.ByteString
instance Relude.String.Conversion.ConvertUtf8 GHC.Internal.Base.String Data.ByteString.Short.Internal.ShortByteString
instance Relude.String.Conversion.ConvertUtf8 Relude.String.Conversion.LText Relude.String.Conversion.LByteString
instance Relude.String.Conversion.ConvertUtf8 Relude.String.Conversion.LText Data.ByteString.Internal.Type.ByteString
instance Relude.String.Conversion.ConvertUtf8 Relude.String.Conversion.LText Data.ByteString.Short.Internal.ShortByteString
instance Relude.String.Conversion.ConvertUtf8 Data.Text.Internal.Text Relude.String.Conversion.LByteString
instance Relude.String.Conversion.ConvertUtf8 Data.Text.Internal.Text Data.ByteString.Internal.Type.ByteString
instance Relude.String.Conversion.ConvertUtf8 Data.Text.Internal.Text Data.ByteString.Short.Internal.ShortByteString
instance Relude.String.Conversion.LazyStrict Relude.String.Conversion.LByteString Data.ByteString.Internal.Type.ByteString
instance Relude.String.Conversion.LazyStrict Relude.String.Conversion.LText Data.Text.Internal.Text
instance Relude.String.Conversion.EncodingError Relude.String.Conversion.ToLText "LByteString" "LText" => Relude.String.Conversion.ToLText Relude.String.Conversion.LByteString
instance Relude.String.Conversion.EncodingError Relude.String.Conversion.ToLText "ByteString" "LText" => Relude.String.Conversion.ToLText Data.ByteString.Internal.Type.ByteString
instance Relude.String.Conversion.ToLText GHC.Internal.Base.String
instance Relude.String.Conversion.EncodingError Relude.String.Conversion.ToLText "ShortByteString" "LText" => Relude.String.Conversion.ToLText Data.ByteString.Short.Internal.ShortByteString
instance Relude.String.Conversion.ToLText Data.Text.Internal.Lazy.Text
instance Relude.String.Conversion.ToLText Data.Text.Internal.Text
instance Relude.String.Conversion.EncodingError Relude.String.Conversion.ToString "LByteString" "String" => Relude.String.Conversion.ToString Relude.String.Conversion.LByteString
instance Relude.String.Conversion.EncodingError Relude.String.Conversion.ToString "ByteString" "String" => Relude.String.Conversion.ToString Data.ByteString.Internal.Type.ByteString
instance Relude.String.Conversion.ToString GHC.Internal.Base.String
instance Relude.String.Conversion.EncodingError Relude.String.Conversion.ToString "ShortByteString" "String" => Relude.String.Conversion.ToString Data.ByteString.Short.Internal.ShortByteString
instance Relude.String.Conversion.ToString Relude.String.Conversion.LText
instance Relude.String.Conversion.ToString Data.Text.Internal.Text
instance Relude.String.Conversion.EncodingError Relude.String.Conversion.ToText "LByteString" "Text" => Relude.String.Conversion.ToText Relude.String.Conversion.LByteString
instance Relude.String.Conversion.EncodingError Relude.String.Conversion.ToText "ByteString" "Text" => Relude.String.Conversion.ToText Data.ByteString.Internal.Type.ByteString
instance Relude.String.Conversion.ToText GHC.Internal.Base.String
instance Relude.String.Conversion.EncodingError Relude.String.Conversion.ToText "ShortByteString" "Text" => Relude.String.Conversion.ToText Data.ByteString.Short.Internal.ShortByteString
instance Relude.String.Conversion.ToText Relude.String.Conversion.LText
instance Relude.String.Conversion.ToText Data.Text.Internal.Text


-- | Type classes for conversion between different string representations.
--   
--   The table below represents the <tt>relude</tt> concept of conversion
--   between the following types:
--   
--   <ul>
--   <li><a>Text</a></li>
--   <li><a>String</a></li>
--   <li><a>ByteString</a></li>
--   <li><a>LText</a></li>
--   <li><a>LByteString</a></li>
--   <li><a>ShortByteString</a></li>
--   </ul>
--   
--   TODO: table
module Relude.String


-- | Functions like <a>putStr</a> and <a>putStrLn</a> but for <a>Text</a>,
--   <a>LText</a>, <a>ByteString</a> and <a>LByteString</a>.
module Relude.Print

-- | Lifted version of <a>putStr</a>.
--   
--   <pre>
--   &gt;&gt;&gt; putText "Hello, world!"
--   Hello, world!
--   </pre>
putText :: MonadIO m => Text -> m ()

-- | Lifted version of <a>putStrLn</a>.
--   
--   <pre>
--   &gt;&gt;&gt; putTextLn "Hello, world!"
--   Hello, world!
--   </pre>
putTextLn :: MonadIO m => Text -> m ()

-- | Lifted version of <a>putStr</a>.
--   
--   <pre>
--   &gt;&gt;&gt; putLText "Hello, world!"
--   Hello, world!
--   </pre>
putLText :: MonadIO m => LText -> m ()

-- | Lifted version of <a>putStrLn</a>.
--   
--   <pre>
--   &gt;&gt;&gt; putLTextLn "Hello, world!"
--   Hello, world!
--   </pre>
putLTextLn :: MonadIO m => LText -> m ()

-- | Lifted version of <a>putStr</a>.
--   
--   <pre>
--   &gt;&gt;&gt; putBS ("Hello, world!" :: ByteString)
--   Hello, world!
--   </pre>
putBS :: MonadIO m => ByteString -> m ()

-- | Lifted version of <a>putStrLn</a>.
--   
--   <pre>
--   &gt;&gt;&gt; putBSLn ("Hello, world!" :: ByteString)
--   Hello, world!
--   </pre>
putBSLn :: MonadIO m => ByteString -> m ()

-- | Lifted version of <a>putStr</a>.
--   
--   <pre>
--   &gt;&gt;&gt; putLBS ("Hello, world!" :: LByteString)
--   Hello, world!
--   </pre>
putLBS :: MonadIO m => LByteString -> m ()

-- | Lifted version of <a>putStrLn</a>.
--   
--   <pre>
--   &gt;&gt;&gt; putLBSLn ("Hello, world!" :: LByteString)
--   Hello, world!
--   </pre>
putLBSLn :: MonadIO m => LByteString -> m ()


-- | Lifted versions of functions working with files and common IO.
module Relude.Lifted.File

-- | Lifted version of <a>readFile</a>.

-- | <i>Warning: <a>readFile</a> depends on the system's locale settings
--   and can throw unexpected exceptions.Use <tt>readFileBS</tt> or
--   <tt>readFileLBS</tt> instead.</i>
readFile :: MonadIO m => FilePath -> m String

-- | Lifted version of <a>readFile'</a>. Strict version of <a>readFile</a>.

-- | <i>Warning: readFile' depends on the system's locale settings and can
--   throw unexpected exceptions.Use <tt>readFileBS</tt> or
--   <tt>readFileLBS</tt> instead.</i>
readFile' :: MonadIO m => FilePath -> m String

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

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


-- | Lifted to <a>MonadIO</a> families of file processing functions for the
--   <a>Text</a>, <a>LText</a>, <a>ByteString</a> and <a>LByteString</a>
--   types.
--   
--   These functions are lifted which means that you can also use them
--   inside various Monad Transformers without adding <a>liftIO</a> call
--   explicitly.
--   
--   <b>NOTE:</b> These functions are for working with textual data.
--   Functions that work with <a>Text</a> or <a>LText</a> types are system
--   and locale-sensitive (encoding, line-endings). If you want binary
--   data, use <a>ByteString</a> functions (they are also faster since they
--   don't check encoding). However, you can then decode that data with the
--   help of functions from the <a>Relude.String.Conversion</a> module, e.
--   g. <a>decodeUtf8</a>.
--   
--   To be more precise, avoid the following functions:
--   
--   <ul>
--   <li><a>readFileText</a></li>
--   <li><a>readFileLText</a></li>
--   </ul>
--   
--   See the following blog post for more details:
--   
--   <ul>
--   <li><a>Beware of readFile by Michael Snoyman</a></li>
--   </ul>
module Relude.File

-- | Lifted version of <a>readFile</a>.

-- | <i>Warning: <a>readFileText</a> depends on the system's locale
--   settings and can throw unexpected exceptions.Use <a>readFileBS</a>
--   instead.</i>
readFileText :: MonadIO m => FilePath -> m Text

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

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

-- | Lifted version of <a>readFile</a>.

-- | <i>Warning: <a>readFileLText</a> depends on the system's locale
--   settings and can throw unexpected exceptions.Use <a>readFileLBS</a>
--   instead.</i>
readFileLText :: MonadIO m => FilePath -> m LText

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

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

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

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

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

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

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

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


-- | This module contains functions for debugging <b>pure</b> functions.
--   You can't use functions like <a>putStrLn</a> for this purpose because
--   they require changes to the type signature, but functions in this
--   module avoid this problem by being pure on their own.
--   
--   Additionally, these functions produce compile-time warnings, if you
--   leave them in your code. Warnings help you to cleanup all debugging
--   usages before releasing.
--   
--   <pre>
--   <b>ghci&gt;</b> foo = trace "I forgot trace in code"
--   
--   &lt;interactive&gt;:4:7: <b>warning</b>: [-Wdeprecations]
--       In the use of ‘trace’ (imported from <a>Relude</a>):
--       "<a>trace</a> remains in code"
--   </pre>
--   
--   The following table briefly shows names and types of all functions in
--   this module.
--   
--   TODO: table
--   
--   <b>⚠ NOTE:</b> Use these functions only for local debugging purposes.
--   They break referential transparency, they are only useful when you
--   want to observe intermediate values of your pure functions and to
--   understand the behaviour locally. If you want to log debug messages in
--   your application, consider using a logging library instead.
module Relude.Debug

-- | Prints the given <a>String</a> message and returns the passed value of
--   type <tt>a</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; increment l = map (+1) l
--   
--   &gt;&gt;&gt; increment [2, 3, 4]
--   [3,4,5]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; increment l = trace ("incrementing each value of: " ++ show l) (map (+1) l)
--   
--   &gt;&gt;&gt; increment [2, 3, 4]
--   incrementing each value of: [2,3,4]
--   [3,4,5]
--   </pre>
--   
--   <ul>
--   <li>If you want to print a <a>Show</a>able value instead of
--   <a>String</a>, use <a>traceShow</a>.</li>
--   <li>If you want to print the value itself, use
--   <a>traceShowId</a>.</li>
--   <li>If you want to print by specifying a custom formatting function,
--   use <a>traceShowWith</a>.</li>
--   </ul>

-- | <i>Warning: <a>trace</a> remains in code</i>
trace :: String -> a -> a

-- | Similar to <a>trace</a> but prints a given value with the <a>Show</a>
--   instance instead of a <a>String</a>.
--   
--   <pre>
--   &gt;&gt;&gt; increment l = map (+1) l
--   
--   &gt;&gt;&gt; increment [2, 3, 4]
--   [3,4,5]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; increment l = traceShow l (map (+1) l)
--   
--   &gt;&gt;&gt; increment [2, 3, 4]
--   [2,3,4]
--   [3,4,5]
--   </pre>
--   
--   <ul>
--   <li>If you want to print a specific <a>String</a> instead, use
--   <a>trace</a></li>
--   <li>If you want to print and return the same value, use
--   <a>traceShowId</a></li>
--   <li>If you want to specify a custom printing function, use
--   <a>traceShowWith</a></li>
--   </ul>

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

-- | Similar to <a>traceShow</a> but prints the given value itself instead
--   of a separate value.
--   
--   <pre>
--   &gt;&gt;&gt; traceShowId (1+2+3, "hello" ++ "world")
--   (6,"helloworld")
--   (6,"helloworld")
--   </pre>
--   
--   <ul>
--   <li>If you to specify a different value to print, use <a>trace</a> or
--   <a>traceShow</a></li>
--   <li>If you want to have more control over printing, use
--   <a>traceShowWith</a></li>
--   </ul>

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

-- | Similar <a>traceShowId</a>, but uses a provided function to convert
--   the argument to a value with the <a>Show</a> constraint.
--   
--   <pre>
--   &gt;&gt;&gt; traceShowWith fst (1, "ABC")
--   1
--   (1,"ABC")
--   </pre>
--   
--   In other words, <tt><a>traceShowId</a> ≡ <a>traceShowWith</a> id</tt>.
--   
--   This function is useful for debugging values that do not have
--   <a>Show</a> instance:
--   
--   <pre>
--   &gt;&gt;&gt; fst $ traceShowWith fst (1, id)
--   1
--   1
--   </pre>
--   
--   <ul>
--   <li>If you don't need such flexibility, use simpler <a>trace</a>,
--   <a>traceShow</a> or <a>traceShowId</a></li>
--   </ul>

-- | <i>Warning: 'traceShowWith remains in code</i>
traceShowWith :: Show b => (a -> b) -> a -> a

-- | Similar to <a>traceShowId</a> but specialised for <a>String</a>.
--   
--   <pre>
--   &gt;&gt;&gt; traceId "hello"
--   "hello
--   hello"
--   </pre>

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

-- | Trace function to print values while working a pure monad (e.g.
--   <tt>Maybe</tt>, <tt>State</tt>, etc.)
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   let action :: Maybe Int
--       action = do
--           x &lt;- Just 3
--           traceM ("x: " ++ show x)
--           y &lt;- pure 12
--           traceM ("y: " ++ show y)
--           pure (x*2 + y)
--   in action
--   :}
--   x: 3
--   y: 12
--   Just 18
--   </pre>
--   
--   <ul>
--   <li>If you want to print a value with the <a>Show</a> instance
--   instead, use <a>traceShowM</a></li>
--   </ul>

-- | <i>Warning: <a>traceM</a> remains in code</i>
traceM :: Applicative f => String -> f ()

-- | Like <a>traceM</a>, but uses <a>show</a> on the argument to convert it
--   to a <a>String</a>.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   let action :: Maybe Int
--       action = do
--           x &lt;- Just 3
--           traceShowM x
--           y &lt;- pure 12
--           traceShowM y
--           pure (x*2 + y)
--   in action
--   :}
--   3
--   12
--   Just 18
--   </pre>

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

-- | Throw pure errors. Use this function only to when you are sure that
--   this branch of code execution is not possible. <b>DO NOT USE</b>
--   <a>error</a> as a normal error handling mechanism.
--   
--   ⚠️<b>CAUTION</b>⚠️ Unlike <a>Prelude</a> version, <a>error</a> takes
--   <a>Text</a> as an argument. In case it used by mistake, the user will
--   see the following:
--   
--   <pre>
--   &gt;&gt;&gt; error ("oops" :: String)
--   ...
--   ... 'error' expects 'Text' but was given 'String'.
--         Possible fixes:
--             * Make sure OverloadedStrings extension is enabled
--             * Use 'error (toText msg)' instead of 'error msg'
--   ...
--   
--   &gt;&gt;&gt; error False
--   ...
--   ... 'error' works with 'Text'
--         But given: Bool
--   ...
--   </pre>
error :: forall a t. (HasCallStack, IsText t) => t -> a

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

-- | <i>Warning: <a>undefined</a> function remains in code</i>
undefined :: HasCallStack => a
instance GHC.Internal.Enum.Bounded Relude.Debug.Undefined
instance GHC.Internal.Data.Data.Data Relude.Debug.Undefined
instance GHC.Internal.Enum.Enum Relude.Debug.Undefined
instance GHC.Classes.Eq Relude.Debug.Undefined
instance GHC.Internal.Generics.Generic Relude.Debug.Undefined
instance GHC.Classes.Ord Relude.Debug.Undefined
instance GHC.Internal.Read.Read Relude.Debug.Undefined
instance GHC.Internal.Show.Show Relude.Debug.Undefined


-- | Utilities to work with <a>Either</a> data type.
module Relude.Monad.Either
fromLeft :: a -> Either a b -> a
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.
--   
--   <pre>
--   &gt;&gt;&gt; whenLeft "bar" (Left 42) (\a -&gt; "success!" &lt;$ print a)
--   42
--   "success!"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; whenLeft "bar" (Right 42) (\a -&gt; "success!" &lt;$ print a)
--   "bar"
--   </pre>
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.
--   
--   <pre>
--   &gt;&gt;&gt; whenLeft_ (Right 42) putTextLn
--   
--   &gt;&gt;&gt; whenLeft_ (Left "foo") putTextLn
--   foo
--   </pre>
whenLeft_ :: Applicative f => Either l r -> (l -> f ()) -> f ()

-- | Monadic version of <a>whenLeft</a>.
--   
--   <pre>
--   &gt;&gt;&gt; whenLeftM "bar" (pure $ Left 42) (\a -&gt; "success!" &lt;$ print a)
--   42
--   "success!"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; whenLeftM "bar" (pure $ Right 42) (\a -&gt; "success!" &lt;$ print a)
--   "bar"
--   </pre>
whenLeftM :: Monad m => a -> m (Either l r) -> (l -> m a) -> m a

-- | Monadic version of <a>whenLeft_</a>.
--   
--   <pre>
--   &gt;&gt;&gt; whenLeftM_ (pure $ Right 42) putTextLn
--   
--   &gt;&gt;&gt; whenLeftM_ (pure $ Left "foo") putTextLn
--   foo
--   </pre>
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.
--   
--   <pre>
--   &gt;&gt;&gt; whenRight "bar" (Left "foo") (\a -&gt; "success!" &lt;$ print a)
--   "bar"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; whenRight "bar" (Right 42) (\a -&gt; "success!" &lt;$ print a)
--   42
--   "success!"
--   </pre>
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.
--   
--   <pre>
--   &gt;&gt;&gt; whenRight_ (Left "foo") print
--   
--   &gt;&gt;&gt; whenRight_ (Right 42) print
--   42
--   </pre>
whenRight_ :: Applicative f => Either l r -> (r -> f ()) -> f ()

-- | Monadic version of <a>whenRight</a>.
--   
--   <pre>
--   &gt;&gt;&gt; whenRightM "bar" (pure $ Left "foo") (\a -&gt; "success!" &lt;$ print a)
--   "bar"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; whenRightM "bar" (pure $ Right 42) (\a -&gt; "success!" &lt;$ print a)
--   42
--   "success!"
--   </pre>
whenRightM :: Monad m => a -> m (Either l r) -> (r -> m a) -> m a

-- | Monadic version of <a>whenRight_</a>.
--   
--   <pre>
--   &gt;&gt;&gt; whenRightM_ (pure $ Left "foo") print
--   
--   &gt;&gt;&gt; whenRightM_ (pure $ Right 42) print
--   42
--   </pre>
whenRightM_ :: Monad m => m (Either l r) -> (r -> m ()) -> m ()
instance GHC.Internal.Data.String.IsString str => GHC.Internal.Control.Monad.Fail.MonadFail (GHC.Internal.Data.Either.Either str)


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

-- | For chaining monadic operations in forward applications using
--   <tt>(&amp;)</tt> Named version of <a>=&lt;&lt;</a>.
--   
--   <pre>
--   &gt;&gt;&gt; Just [ 1 :: Int ] &amp; chainedTo (viaNonEmpty head)
--   Just 1
--   
--   &gt;&gt;&gt; Nothing &amp; chainedTo (viaNonEmpty head)
--   Nothing
--   </pre>
chainedTo :: Monad m => (a -> m b) -> m a -> m b

-- | Repeat a monadic action indefinitely.
--   
--   This is a more type safe version of <a>forever</a>, which has a
--   convenient but unsafe type.
--   
--   Consider the following two examples. In the <tt>getIntForever</tt>
--   functions, it falsely expects <tt>Int</tt> as the result of the
--   <a>forever</a> function. But it would need to wait *forever* to get
--   that, and this mistake won't be caught by the type system and
--   compiler:
--   
--   <pre>
--   getIntForever :: IO Int
--   getIntForever = do
--       i &lt;- forever $ do ...
--       pure i
--   </pre>
--   
--   In contrast, using <a>infinitely</a> instead of <a>forever</a> in
--   <tt>foo</tt> is a type error.
infinitely :: Applicative f => f a -> f Void


-- | This module contains reexports from <a>Data.List.NonEmpty</a> and safe
--   functions to work with list type in terms of <a>NonEmpty</a>.
--   
--   Note, that <a>Relude</a> reexports <a>head</a>, <a>tail</a>,
--   <a>init</a>, <a>last</a> from <a>Data.List.NonEmpty</a> instead of the
--   <a>Data.List</a>, so these functions are safe to use.
--   
--   TODO: table
--   
--   <tt>relude</tt> also provides custom type error for better experience
--   with transition from lists to <a>NonEmpty</a> with those functions.
--   
--   Let's examine the behaviour of the <tt>relude</tt> list functions
--   comparing to the corresponding <tt>base</tt> one on the example of the
--   <a>head</a> function:
--   
--   TODO: table
module Relude.List.NonEmpty
data NonEmpty a
(:|) :: a -> [a] -> NonEmpty a
nonEmpty :: [a] -> Maybe (NonEmpty a)

-- | <tt>O(1)</tt>. Extracts the first element of a <a>NonEmpty</a> list.
--   
--   Actual type of this function is the following:
--   
--   <pre>
--   head :: <a>NonEmpty</a> a -&gt; a
--   </pre>
--   
--   but it was given a more complex type to provide friendlier compile
--   time errors.
--   
--   <pre>
--   &gt;&gt;&gt; head ('a' :| "bcde")
--   'a'
--   
--   &gt;&gt;&gt; head [0..5 :: Int]
--   ...
--   ... 'head' works with 'NonEmpty', not ordinary lists.
--         Possible fix:
--             Replace: [Int]
--             With:    NonEmpty Int
--   ...
--         However, you can use 'head' with the ordinary lists.
--         Apply 'viaNonEmpty' function from relude:
--             viaNonEmpty head (yourList)
--         Note, that this will return 'Maybe Int'
--         therefore it is a safe function unlike 'head' from the standard Prelude
--   ...
--   
--   &gt;&gt;&gt; head (Just 'a')
--   ...
--   ... 'head' works with 'NonEmpty Char' lists
--         But given: Maybe Char
--   ...
--   </pre>
head :: IsNonEmpty f a a "head" => f a -> a

-- | <tt>O(1)</tt>. Return all the elements of a <a>NonEmpty</a> list after
--   the head element.
--   
--   Actual type of this function is the following:
--   
--   <pre>
--   tail :: <a>NonEmpty</a> a -&gt; [a]
--   </pre>
--   
--   but it was given a more complex type to provide friendlier compile
--   time errors.
--   
--   <pre>
--   &gt;&gt;&gt; tail ('a' :| "bcde")
--   "bcde"
--   
--   &gt;&gt;&gt; tail [0..5 :: Int]
--   ...
--   ... 'tail' works with 'NonEmpty', not ordinary lists.
--         Possible fix:
--             Replace: [Int]
--             With:    NonEmpty Int
--   ...
--         However, you can use 'tail' with the ordinary lists.
--         Apply 'viaNonEmpty' function from relude:
--             viaNonEmpty tail (yourList)
--         Note, that this will return 'Maybe [Int]'
--         therefore it is a safe function unlike 'tail' from the standard Prelude
--   ...
--   
--   &gt;&gt;&gt; tail (Just 'a')
--   ...
--   ... 'tail' works with 'NonEmpty Char' lists
--         But given: Maybe Char
--   ...
--   </pre>
tail :: IsNonEmpty f a [a] "tail" => f a -> [a]

-- | <tt>O(n)</tt>. Extracts the last element of a <a>NonEmpty</a> list.
--   
--   Actual type of this function is the following:
--   
--   <pre>
--   last :: <a>NonEmpty</a> a -&gt; a
--   </pre>
--   
--   but it was given a more complex type to provide friendlier compile
--   time errors.
--   
--   <pre>
--   &gt;&gt;&gt; last ('a' :| "bcde")
--   'e'
--   
--   &gt;&gt;&gt; last [0..5 :: Int]
--   ...
--   ... 'last' works with 'NonEmpty', not ordinary lists.
--         Possible fix:
--             Replace: [Int]
--             With:    NonEmpty Int
--   ...
--         However, you can use 'last' with the ordinary lists.
--         Apply 'viaNonEmpty' function from relude:
--             viaNonEmpty last (yourList)
--         Note, that this will return 'Maybe Int'
--         therefore it is a safe function unlike 'last' from the standard Prelude
--   ...
--   
--   &gt;&gt;&gt; last (Just 'a')
--   ...
--   ... 'last' works with 'NonEmpty Char' lists
--         But given: Maybe Char
--   ...
--   </pre>
last :: IsNonEmpty f a a "last" => f a -> a

-- | <tt>O(n)</tt>. Return all the elements of a <a>NonEmpty</a> list
--   except the last one element.
--   
--   Actual type of this function is the following:
--   
--   <pre>
--   init :: <a>NonEmpty</a> a -&gt; [a]
--   </pre>
--   
--   but it was given a more complex type to provide friendlier compile
--   time errors.
--   
--   <pre>
--   &gt;&gt;&gt; init ('a' :| "bcde")
--   "abcd"
--   
--   &gt;&gt;&gt; init [0..5 :: Int]
--   ...
--   ... 'init' works with 'NonEmpty', not ordinary lists.
--         Possible fix:
--             Replace: [Int]
--             With:    NonEmpty Int
--   ...
--         However, you can use 'init' with the ordinary lists.
--         Apply 'viaNonEmpty' function from relude:
--             viaNonEmpty init (yourList)
--         Note, that this will return 'Maybe [Int]'
--         therefore it is a safe function unlike 'init' from the standard Prelude
--   ...
--   
--   &gt;&gt;&gt; init (Just 'a')
--   ...
--   ... 'init' works with 'NonEmpty Char' lists
--         But given: Maybe Char
--   ...
--   </pre>
init :: IsNonEmpty f a [a] "init" => f a -> [a]

-- | For safe work with lists using functions 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

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


-- | Re-exports most useful functionality from the <a>Control.Exception</a>
--   module. Also provides some convenient utilities to throw and handle
--   exceptions.
module Relude.Exception
class (Typeable e, Show e) => Exception e
toException :: Exception e => e -> SomeException
fromException :: Exception e => SomeException -> Maybe e
displayException :: Exception e => e -> String
backtraceDesired :: Exception e => e -> Bool
data SomeException
SomeException :: e -> 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 instead of
--   writing something like this:
--   
--   <pre>
--   isNonCriticalExc :: SomeException -&gt; Bool
--   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 :: SomeException -&gt; Bool
--   isNonCriticalExc = case
--       Exc (_ :: NodeAttackedError) -&gt; True  -- matching all exceptions of type NodeAttackedError
--       Exc DialogUnexpected{} -&gt; True
--       _ -&gt; False
--   </pre>
--   
--   This pattern is bidirectional. You can use <tt>Exc e</tt> instead of
--   <tt>toException e</tt>.
pattern Exc :: Exception e => e -> SomeException
instance GHC.Internal.Exception.Type.Exception Relude.Exception.Bug
instance GHC.Internal.Show.Show Relude.Exception.Bug


-- | This module contains useful functions to evaluate expressions to
--   weak-head normal form (WHNF) or just normal form (NF). Useful to force
--   traces or <tt>error</tt>s inside monadic computations or to remove
--   space leaks.
module Relude.DeepSeq
class NFData a
rnf :: NFData a => a -> ()
deepseq :: NFData a => a -> b -> b
force :: NFData a => a -> a
($!!) :: NFData a => (a -> b) -> a -> b

-- | Alias for <tt>evaluateWHNF . force</tt> with a clearer name.
--   
--   <pre>
--   &gt;&gt;&gt; let list = [1..5] :: [Int]
--   
--   &gt;&gt;&gt; :sprint list
--   list = _
--   
--   &gt;&gt;&gt; () &lt;$ evaluateNF list
--   
--   &gt;&gt;&gt; :sprint list
--   list = [1,2,3,4,5]
--   </pre>
evaluateNF :: (NFData a, MonadIO m) => a -> m a

-- | Alias for <tt>evaluateWHNF . rnf</tt>. Similar to <a>evaluateNF</a>
--   but discards the resulting value.
--   
--   <pre>
--   &gt;&gt;&gt; let list = [1..5] :: [Int]
--   
--   &gt;&gt;&gt; :sprint list
--   list = _
--   
--   &gt;&gt;&gt; evaluateNF_ list
--   
--   &gt;&gt;&gt; :sprint list
--   list = [1,2,3,4,5]
--   </pre>
evaluateNF_ :: (NFData a, MonadIO m) => a -> m ()

-- | Lifted alias for <a>evaluate</a> with a clearer name.
--   
--   <pre>
--   &gt;&gt;&gt; let list = [1..5] :: [Int]
--   
--   &gt;&gt;&gt; :sprint list
--   list = _
--   
--   &gt;&gt;&gt; () &lt;$ evaluateWHNF list
--   
--   &gt;&gt;&gt; :sprint list
--   list = 1 : _
--   </pre>
evaluateWHNF :: MonadIO m => a -> m a

-- | Like <a>evaluateWHNF</a> but discards value.
--   
--   <pre>
--   &gt;&gt;&gt; let list = [1..5] :: [Int]
--   
--   &gt;&gt;&gt; :sprint list
--   list = _
--   
--   &gt;&gt;&gt; evaluateWHNF_ list
--   
--   &gt;&gt;&gt; :sprint list
--   list = 1 : _
--   </pre>
evaluateWHNF_ :: MonadIO m => a -> m ()


-- | Monadic boolean combinators.
module Relude.Bool.Guard

-- | Either lifts a value into an alternative context or gives a minimal
--   value depending on a predicate. Works with <a>Alternative</a>s.
--   
--   <pre>
--   &gt;&gt;&gt; guarded even 3 :: [Int]
--   []
--   
--   &gt;&gt;&gt; guarded even 2 :: [Int]
--   [2]
--   
--   &gt;&gt;&gt; guarded (const True) "hello" :: Maybe String
--   Just "hello"
--   
--   &gt;&gt;&gt; guarded (const False) "world" :: Maybe String
--   Nothing
--   </pre>
--   
--   You can use this function to implement smart constructors simpler:
--   
--   <pre>
--   <b>newtype</b> HttpHost = HttpHost
--       { unHttpHost :: Text
--       }
--   
--   mkHttpHost :: Text -&gt; Maybe HttpHost
--   mkHttpHost host = HttpHost &lt;$&gt; <a>guarded</a> (not . Text.null) host
--   </pre>
guarded :: Alternative f => (a -> Bool) -> a -> f a

-- | Monadic version of <a>guard</a> that help to check that a condition
--   (<a>Bool</a>) holds inside. Works with <a>Monad</a>s that are also
--   <a>Alternative</a>.
--   
--   <pre>
--   &gt;&gt;&gt; guardM (Just True)
--   Just ()
--   
--   &gt;&gt;&gt; guardM (Just False)
--   Nothing
--   
--   &gt;&gt;&gt; guardM Nothing
--   Nothing
--   </pre>
--   
--   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
--   
--   &gt;&gt;&gt; ifM (pure False) (putTextLn "True text") (putTextLn "False text")
--   False text
--   </pre>
ifM :: Monad m => m Bool -> m a -> m a -> m a

-- | Monadic version of <a>unless</a>. Reverse of <a>whenM</a>.
--   Conditionally don't execute the provided action.
--   
--   <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>. Conditionally executes the provided
--   action.
--   
--   <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 ()

-- | Monadic version of <a>(&amp;&amp;)</a> operator.
--   
--   It is lazy by the second argument (similar to <a>(||)</a>), meaning
--   that if the first argument is <a>False</a>, the function will return
--   <a>False</a> without evaluating the second argument.
--   
--   <pre>
--   &gt;&gt;&gt; Just False &amp;&amp;^ Just True
--   Just False
--   
--   &gt;&gt;&gt; Just True &amp;&amp;^ Just True
--   Just True
--   
--   &gt;&gt;&gt; Just True &amp;&amp;^ Nothing
--   Nothing
--   
--   &gt;&gt;&gt; Just False &amp;&amp;^ Nothing
--   Just False
--   
--   &gt;&gt;&gt; Just False &amp;&amp;^ error "Shouldn't be evaluated"
--   Just False
--   </pre>
(&&^) :: Monad m => m Bool -> m Bool -> m Bool

-- | Monadic version of <a>(||)</a> operator.
--   
--   It is lazy by the second argument (similar to <a>(||)</a>), meaning
--   that if the first argument is <a>True</a>, the function will return
--   <a>True</a> without evaluating the second argument.
--   
--   <pre>
--   &gt;&gt;&gt; Just False ||^ Just True
--   Just True
--   
--   &gt;&gt;&gt; Just False ||^ Just False
--   Just False
--   
--   &gt;&gt;&gt; Just False ||^ Nothing
--   Nothing
--   
--   &gt;&gt;&gt; Just True ||^ Nothing
--   Just True
--   
--   &gt;&gt;&gt; Just True ||^ error "Shouldn't be evaluated"
--   Just True
--   </pre>
(||^) :: Monad m => m Bool -> m Bool -> m Bool


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


-- | Provides numerical data types and functions.
module Relude.Numeric
toIntegralSized :: (Integral a, Integral b, Bits a, Bits b) => a -> Maybe b
xor :: Bits a => a -> a -> a
data Int
data Int16
data Int32
data Int64
data Int8
data Word8
data Word
data Word16
data Word32
data Word64
byteSwap16 :: Word16 -> Word16
byteSwap32 :: Word32 -> Word32
byteSwap64 :: Word64 -> Word64
maxInt :: Int
minInt :: Int
data Double
D# :: Double# -> Double
data Float
F# :: Float# -> Float
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
class (RealFrac a, Floating a) => RealFloat a
floatRadix :: RealFloat a => a -> Integer
floatDigits :: RealFloat a => a -> Int
floatRange :: RealFloat a => a -> (Int, Int)
decodeFloat :: RealFloat a => a -> (Integer, Int)
encodeFloat :: RealFloat a => Integer -> Int -> a
isNaN :: RealFloat a => a -> Bool
isInfinite :: RealFloat a => a -> Bool
isDenormalized :: RealFloat a => a -> Bool
isNegativeZero :: RealFloat a => a -> Bool
isIEEE :: RealFloat a => a -> Bool
atan2 :: RealFloat a => a -> a -> a
class Num a
(+) :: Num a => a -> a -> a
(-) :: Num a => a -> a -> a
(*) :: Num a => a -> a -> a
negate :: Num a => a -> a
abs :: Num a => a -> a
signum :: Num a => a -> a
fromInteger :: Num a => Integer -> a
data Integer
subtract :: Num a => a -> a -> a
class (Num a, Ord a) => Real a
toRational :: Real a => a -> Rational
class Num a => Fractional a
(/) :: Fractional a => a -> a -> a
recip :: Fractional a => a -> a
fromRational :: Fractional a => Rational -> a
class (Real a, Enum a) => Integral a
quot :: Integral a => a -> a -> a
rem :: Integral a => a -> a -> a
div :: Integral a => a -> a -> a
mod :: Integral a => a -> a -> a
quotRem :: Integral a => a -> a -> (a, a)
divMod :: Integral a => a -> a -> (a, a)
toInteger :: Integral a => a -> Integer
data Ratio a
type Rational = Ratio Integer
class (Real a, Fractional a) => RealFrac a
properFraction :: (RealFrac a, Integral b) => a -> (b, a)
truncate :: (RealFrac a, Integral b) => a -> b
round :: (RealFrac a, Integral b) => a -> b
ceiling :: (RealFrac a, Integral b) => a -> b
floor :: (RealFrac a, Integral b) => a -> b
denominator :: Ratio a -> a
even :: Integral a => a -> Bool
fromIntegral :: (Integral a, Num b) => a -> b
gcd :: Integral a => a -> a -> a
lcm :: Integral a => a -> a -> a
numerator :: Ratio a -> a
odd :: Integral a => a -> Bool
realToFrac :: (Real a, Fractional b) => a -> b
(^) :: (Num a, Integral b) => a -> b -> a
(^^) :: (Fractional a, Integral b) => a -> b -> a
data Natural

-- | Transforms an integer number to a bounded integral. It returns
--   <a>Nothing</a> for integers outside the bound of the return type.
--   
--   <pre>
--   &gt;&gt;&gt; integerToBounded @Int 42
--   Just 42
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; integerToBounded @Int8 1024
--   Nothing
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; integerToBounded @Int (toInteger (minBound :: Int))
--   Just (-9223372036854775808)
--   
--   &gt;&gt;&gt; integerToBounded @Int $ (toInteger (minBound :: Int)) - 1
--   Nothing
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; integerToBounded @Int (toInteger (maxBound :: Int))
--   Just 9223372036854775807
--   
--   &gt;&gt;&gt; integerToBounded @Int $ (toInteger (maxBound :: Int)) + 1
--   Nothing
--   </pre>
--   
--   If you want to convert <a>Int</a> or <a>Word</a> to a bounded type,
--   take a look at <a>toIntegralSized</a> function instead.
integerToBounded :: (Integral a, Bounded a) => Integer -> Maybe a

-- | Transforms an integer number to a natural. Only non-negative integers
--   are considered natural, everything else will return <a>Nothing</a>.
--   
--   <pre>
--   &gt;&gt;&gt; integerToNatural (-1)
--   Nothing
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; integerToNatural 0
--   Just 0
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; integerToNatural 10
--   Just 10
--   </pre>
integerToNatural :: Integer -> Maybe Natural


-- | <a>One</a> is a typeclass for creating structures from a singleton
--   element. It has three main goals:
--   
--   <ol>
--   <li>Give a shorter name for the construction: uses <a>one</a> instead
--   of common <tt>singleton</tt>.</li>
--   <li>Work with monomorphic structures like <a>Text</a> or
--   <a>IntSet</a>.</li>
--   <li>Give a clearer and less scary name for cases where you can use
--   <a>pure</a> or <tt>(:[])</tt>.</li>
--   </ol>
module Relude.Container.One

-- | Typeclass for data types that can be created from one element. E.g.
--   lists, non-empty containers, maps.
--   
--   <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>
--   
--   <b>Laws:</b>
--   
--   <ul>
--   <li><b><tt>single-size</tt></b>: <tt>∀ x . size (one x) ≡ 1</tt></li>
--   </ul>
--   
--   (where <tt>size</tt> is a specific function for each container that
--   returns the size of this container)
class One x where {
    
    -- | Type of a single element of the structure.
    type OneItem x;
}

-- | Create a list, map, <a>Text</a>, etc from a single element.
one :: One x => OneItem x -> x
instance Relude.Container.One.One Data.ByteString.Lazy.Internal.ByteString
instance Relude.Container.One.One Data.ByteString.Internal.Type.ByteString
instance Data.Hashable.Class.Hashable k => Relude.Container.One.One (Data.HashMap.Internal.HashMap k v)
instance Data.Hashable.Class.Hashable a => Relude.Container.One.One (Data.HashSet.Internal.HashSet a)
instance Relude.Container.One.One (Data.IntMap.Internal.IntMap v)
instance Relude.Container.One.One Data.IntSet.Internal.IntSet
instance Relude.Container.One.One [a]
instance Relude.Container.One.One (Data.Map.Internal.Map k v)
instance Relude.Container.One.One (GHC.Internal.Base.NonEmpty a)
instance Relude.Container.One.One (Data.Sequence.Internal.Seq a)
instance Relude.Container.One.One (Data.Set.Internal.Set a)
instance Relude.Container.One.One Data.ByteString.Short.Internal.ShortByteString
instance Relude.Container.One.One Data.Text.Internal.Lazy.Text
instance Relude.Container.One.One Data.Text.Internal.Text


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


-- | Utility functions to work with lists and <a>NonEmpty</a> lists.
module Relude.List

-- | Safer version of <a>!!</a>, returns a Maybe.
--   
--   Get element from list using index value starting from `0`.
--   
--   <pre>
--   &gt;&gt;&gt; [] !!? 0
--   Nothing
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; ["a", "b", "c"] !!? 3
--   Nothing
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; [1, 2, 3] !!? (-1)
--   Nothing
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; ["a", "b", "c"] !!? 2
--   Just "c"
--   </pre>
(!!?) :: [a] -> Int -> Maybe a
infix 9 !!?

-- | <a>!!?</a> with its arguments flipped.
--   
--   Get element from list using index value starting from `0`.
--   
--   <pre>
--   &gt;&gt;&gt; maybeAt 0 []
--   Nothing
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; maybeAt 3 ["a", "b", "c"]
--   Nothing
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; maybeAt (-1) [1, 2, 3]
--   Nothing
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; maybeAt 2 ["a", "b", "c"]
--   Just "c"
--   </pre>
maybeAt :: Int -> [a] -> Maybe a

-- | Partitions a list based on the result of function which produces an
--   Either value. List of all elements producing Left are extracted, in
--   order, to the first element of the output tuple. Similarly, a list of
--   all elements producing Right are extracted to the second element of
--   output.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--    divideEvenOrShow :: Int -&gt; Either Int String
--    divideEvenOrShow n
--        | even n = Left $ n `div` 2
--        | otherwise = Right $ "Odd: " &lt;&gt; show n
--    :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; partitionWith divideEvenOrShow [1 .. 6]
--   ([1,2,3],["Odd: 1","Odd: 3","Odd: 5"])
--   </pre>
partitionWith :: (a -> Either b c) -> [a] -> ([b], [c])


-- | Lifted functions to work with <a>IO</a> <a>Handle</a>s.
module Relude.Lifted.Handle

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

-- | Lifted version of <a>hIsEOF</a>.
hIsEOF :: MonadIO m => Handle -> m Bool

-- | Lifted version of <a>hSetBuffering</a>.
hSetBuffering :: MonadIO m => Handle -> BufferMode -> m ()

-- | Lifted version of <a>hGetBuffering</a>.
hGetBuffering :: MonadIO m => Handle -> m BufferMode
data Handle
stdin :: Handle
stdout :: Handle
stderr :: Handle
withFile :: FilePath -> IOMode -> (Handle -> IO r) -> IO r
data BufferMode
NoBuffering :: BufferMode
LineBuffering :: BufferMode
BlockBuffering :: Maybe Int -> BufferMode


-- | Lifted <a>MVar</a> and <a>STM</a> functions.
module Relude.Lifted.Concurrent
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)
data STM a

-- | Lifted to <a>MonadIO</a> version of <a>atomically</a>.
atomically :: MonadIO m => STM a -> m a
throwSTM :: Exception e => e -> STM a
catchSTM :: Exception e => STM a -> (e -> STM a) -> STM a
data TVar 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
modifyTVar' :: TVar a -> (a -> a) -> STM ()
newTVar :: a -> STM (TVar a)
readTVar :: TVar a -> STM a
writeTVar :: TVar a -> a -> STM ()
data TMVar a
newTMVar :: a -> STM (TMVar a)
newEmptyTMVar :: STM (TMVar a)

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

-- | Lifted to <a>MonadIO</a> version of <a>newEmptyTMVarIO</a>.
newEmptyTMVarIO :: MonadIO m => m (TMVar a)
takeTMVar :: TMVar a -> STM a
putTMVar :: TMVar a -> a -> STM ()
readTMVar :: TMVar a -> STM a
tryReadTMVar :: TMVar a -> STM (Maybe a)
swapTMVar :: TMVar a -> a -> STM a
tryTakeTMVar :: TMVar a -> STM (Maybe a)
tryPutTMVar :: TMVar a -> a -> STM Bool
isEmptyTMVar :: TMVar a -> STM Bool
mkWeakTMVar :: TMVar a -> IO () -> IO (Weak (TMVar a))


-- | Fixes and additions to <a>Foldable</a>. Specifically:
--   
--   <ul>
--   <li>Space-leak free <a>sum</a> and <a>product</a></li>
--   <li><a>elem</a> and <a>notElem</a> are forbidden for <a>Set</a> and
--   <a>HashSet</a></li>
--   <li>Additional combinators for common idioms</li>
--   </ul>
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>
--   
--   This function can be useful for constructing containers from lists.
flipfoldl' :: Foldable f => (a -> b -> b) -> b -> f a -> b

-- | Alternative version of <a>asum</a> that takes a function to map over.
--   
--   <pre>
--   &gt;&gt;&gt; asumMap (\x -&gt; if x &gt; 2 then Just x else Nothing) [1..4]
--   Just 3
--   </pre>
asumMap :: forall b m f a. (Foldable f, Alternative m) => (a -> m b) -> f a -> m b

-- | Polymorphic version of the <tt>concatMapA</tt> function.
--   
--   <pre>
--   &gt;&gt;&gt; foldMapA @[Int] (Just . replicate 3) [1..3]
--   Just [1,1,1,2,2,2,3,3,3]
--   </pre>
foldMapA :: (Semigroup b, Monoid b, Applicative m, Foldable f) => (a -> m b) -> f a -> m b

-- | Polymorphic version of the <a>concatMapM</a> function.
--   
--   <pre>
--   &gt;&gt;&gt; foldMapM @[Int] (Just . replicate 3) [1..3]
--   Just [1,1,1,2,2,2,3,3,3]
--   </pre>
foldMapM :: (Monoid b, Monad m, Foldable f) => (a -> m b) -> f a -> m b

-- | 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 :: Ord a =&gt; a -&gt; Set a -&gt; Bool
--   ...
--             Instead of
--                 notElem :: (Foldable t, Eq a) =&gt; a -&gt; t a -&gt; Bool
--             use
--                 not . member
--   ...
--   </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 :: Ord a =&gt; a -&gt; Set a -&gt; Bool
--   ...
--             Instead of
--                 notElem :: (Foldable t, Eq a) =&gt; a -&gt; t a -&gt; Bool
--             use
--                 not . member
--   ...
--   </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 provides <a>Foldable</a> and <a>Traversable</a> related
--   types and functions.
module Relude.Foldable


-- | Contains implementation of polymorphic type classes for data types
--   <a>Set</a> and <a>Map</a>.
module Relude.Extra.Map

-- | Read-only map or set. Contains polymorphic functions which work for
--   both sets and maps.
class StaticMap t where {
    type Key t;
    type Val t;
}
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.
--   
--   <pre>
--   &gt;&gt;&gt; let myHashMap = HashMap.fromList [('a', "xxx"), ('b', "yyy")]
--   
--   &gt;&gt;&gt; myHashMap !? 'b'
--   Just "yyy"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; myHashMap !? 'd'
--   Nothing
--   </pre>
(!?) :: StaticMap t => t -> Key t -> Maybe (Val t)
infixl 9 !?

-- | Inverse of <a>member</a> function.
--   
--   <pre>
--   &gt;&gt;&gt; let myHashMap = HashMap.fromList [('a', "xxx"), ('b', "yyy")]
--   
--   &gt;&gt;&gt; notMember 'b' myHashMap
--   False
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; notMember 'c' myHashMap
--   True
--   </pre>
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.
--   
--   <pre>
--   &gt;&gt;&gt; let myHashMap = HashMap.fromList [('a', "xxx"), ('b', "yyy")]
--   
--   &gt;&gt;&gt; lookupDefault "zzz" 'b' myHashMap
--   "yyy"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; lookupDefault "zzz" 'c' myHashMap
--   "zzz"
--   </pre>
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 Data.Hashable.Class.Hashable k => Relude.Extra.Map.DynamicMap (Data.HashMap.Internal.HashMap k v)
instance Relude.Extra.Map.DynamicMap (Data.IntMap.Internal.IntMap v)
instance GHC.Classes.Ord k => Relude.Extra.Map.DynamicMap (Data.Map.Internal.Map k v)
instance Data.Hashable.Class.Hashable k => Relude.Extra.Map.StaticMap (Data.HashMap.Internal.HashMap k v)
instance Data.Hashable.Class.Hashable a => Relude.Extra.Map.StaticMap (Data.HashSet.Internal.HashSet a)
instance Relude.Extra.Map.StaticMap (Data.IntMap.Internal.IntMap v)
instance Relude.Extra.Map.StaticMap Data.IntSet.Internal.IntSet
instance GHC.Classes.Ord k => Relude.Extra.Map.StaticMap (Data.Map.Internal.Map k v)
instance GHC.Classes.Ord a => Relude.Extra.Map.StaticMap (Data.Set.Internal.Set a)


-- | Lifted functions to work with stdin and stdout.
module Relude.Lifted.Terminal

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

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

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

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


-- | Lifted functions to work with system environment.
module Relude.Lifted.Env

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

-- | Lifted version of <a>lookupEnv</a>.
lookupEnv :: MonadIO m => String -> m (Maybe String)


-- | Lifted versions of base functions.
--   
--   These functions are lifted in a sense that you can use them inside
--   various monad transformers without adding <a>liftIO</a> calls
--   explicitly. However, you still can use all these functions inside
--   plain <a>IO</a> monad as usual.
--   
--   <h3>Example</h3>
--   
--   <h4><tt>base</tt></h4>
--   
--   With the <tt>base</tt> function, you can easily work with these
--   functions in the <a>IO</a> monad:
--   
--   <pre>
--   <b>main</b> :: <a>IO</a> ()
--   <b>main</b> = <b>do</b>
--       x &lt;- <a>getLine</a>
--       <a>print</a> x
--   </pre>
--   
--   However, to work in <a>MonadIO</a> you already need to "lift" them:
--   
--   <pre>
--   <b>main</b> :: <a>MonadIO</a> m =&gt; m ()
--   <b>main</b> = <b>do</b>
--       x &lt;- <a>liftIO</a> <a>getLine</a>
--       <a>liftIO</a> (<a>print</a> x)
--   </pre>
--   
--   <h4><tt>relude</tt></h4>
--   
--   In the meantime, <tt>relude</tt> provides these function that can work
--   in <a>IO</a> the same way:
--   
--   <pre>
--   <b>main</b> :: <a>IO</a> ()
--   <b>main</b> = <b>do</b>
--       x &lt;- <a>getLine</a>
--       <a>print</a> x
--   </pre>
--   
--   But also allows you to work in the <a>MonadIO</a> monads more easily:
--   
--   <pre>
--   <b>main</b> :: <a>MonadIO</a> m =&gt; m ()
--   <b>main</b> = <b>do</b>
--       x &lt;- <a>getLine</a>
--       <a>print</a> x
--   </pre>
module Relude.Lifted


-- | <tt>relude</tt> is a safe, performant, user-friendly and lightweight
--   Haskell standard library.
--   
--   <a>Relude</a> is the main module that reexports all functionality
--   provided by the library that will replace the default <tt>Prelude</tt>
--   in your project.
--   
--   <h2>Usage</h2>
--   
--   To start using <tt>relude</tt> in your project, you can set the
--   library up for you by one of the following ways.
--   
--   <h3>mixins</h3>
--   
--   One of the most convenient ways to use <tt>relude</tt> is via the
--   <tt>mixins</tt> feature. This feature is available since <tt>Cabal
--   &gt;= 2.2</tt>. In order to use the <tt>mixins</tt> feature one needs
--   to specify supported <tt>cabal-version</tt> in your package
--   description. And then the following lines should be added to the
--   required stanza to replace default <a>Prelude</a> with
--   <tt>relude</tt>.
--   
--   <pre>
--   cabal-version: 2.4
--   ...
--   library
--     ...
--     mixins: base hiding (Prelude)
--           , relude (Relude as Prelude)
--           , relude
--   </pre>
--   
--   <h3><tt>base-noprelude</tt></h3>
--   
--   Alternatively, you can replace <tt>base</tt> package in your
--   dependencies with <tt><a>base-noprelude</a></tt> and add the following
--   <a>Prelude</a> module to your package to use <tt>relude</tt> by
--   default in every module instead of <tt>base</tt> <a>Prelude</a>:
--   
--   <pre>
--   <b>module</b> Prelude
--       ( <b>module</b> <a>Relude</a>
--       ) <b>where</b>
--   
--   <b>import</b> <a>Relude</a>
--   </pre>
--   
--   <h3><tt>NoImplicitPrelude</tt></h3>
--   
--   If you want to use <tt>relude</tt> per-module basis then just add next
--   lines to your module to replace default <a>Prelude</a>:
--   
--   <pre>
--   {-# LANGUAGE NoImplicitPrelude #-}
--   
--   <b>import</b> <a>Relude</a>
--   </pre>
--   
--   <h2>Structure</h2>
--   
--   This documentation section contains the description of internal module
--   structure to help navigate between modules, search for interesting
--   functionalities and understand where you need to put your new changes
--   (if you're a contributor).
--   
--   Functions and types are distributed across multiple modules and
--   grouped by meaning or <b>category</b>. Name of the module should give
--   you hints regarding what this module contains. Some <i>categories</i>
--   contain a significant amount of both reexported functions and
--   functions of our own. To make it easier to understand these enormous
--   chunks of functions, all reexported stuff is moved into the separate
--   module with name <tt>Relude.SomeCategory.Reexport</tt> and our own
--   functions and types are in <tt>Relude.SomeCategory.SomeName</tt>. For
--   example, see modules <a>Relude.Foldable.Fold</a> and
--   <a>Relude.Foldable.Reexport</a>.
module Relude


-- | Contains useful utilities to work with Types.
module Relude.Extra.Type

-- | Gets a string representation of a type.
--   
--   <b>NOTE:</b> This must be used with <b>TypeApplications</b> language
--   extension.
--   
--   <pre>
--   &gt;&gt;&gt; typeName @()
--   "()"
--   
--   &gt;&gt;&gt; typeName @Int
--   "Int"
--   
--   &gt;&gt;&gt; typeName @String
--   "[Char]"
--   
--   &gt;&gt;&gt; typeName @(Maybe Int)
--   "Maybe Int"
--   </pre>
typeName :: forall {k} (a :: k). Typeable a => Text

-- | Concatenates type-level lists.
--   
--   <pre>
--   &gt;&gt;&gt; :kind! '[ 'Just 5, 'Nothing] ++ '[ 'Just 3, 'Nothing, 'Just 1]
--   '[ 'Just 5, 'Nothing] ++ '[ 'Just 3, 'Nothing, 'Just 1] :: [Maybe
--                                                                 Natural]
--   = '[ 'Just 5, 'Nothing, 'Just 3, 'Nothing, 'Just 1]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :kind! '[] ++ '[ 'Just 3, 'Nothing, 'Just 1]
--   '[] ++ '[ 'Just 3, 'Nothing, 'Just 1] :: [Maybe Natural]
--   = '[ 'Just 3, 'Nothing, 'Just 1]
--   </pre>
--   
--   # 91 "src<i>Relude</i>Extra/Type.hs"
type family (xs :: [k]) ++ (ys :: [k]) :: [k]
infixr 5 ++

-- | Builds combined <a>Constraint</a> by applying Constraint constructor
--   to all elements of type-level list.
--   
--   <pre>
--   &gt;&gt;&gt; :kind! AllHave Show '[Int, Text, Double]
--   AllHave Show '[Int, Text, Double] :: Constraint
--   = (Show Int, (Show Text, (Show Double, () :: Constraint)))
--   </pre>
--   
--   which is equivalent to:
--   
--   <pre>
--   (Show Int, Show Text, Show Double) :: Constraint
--   </pre>
type family AllHave (f :: k -> Constraint) (xs :: [k])

-- | Check that a type is an element of a list:
--   
--   <pre>
--   &gt;&gt;&gt; :kind! Elem String '[]
--   Elem String '[] :: Bool
--   = 'False
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :kind! Elem String '[Int, String]
--   Elem String '[Int, String] :: Bool
--   = 'True
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :kind! Elem String '[Int, Bool]
--   Elem String '[Int, Bool] :: Bool
--   = 'False
--   </pre>
type family Elem (e :: t) (es :: [t]) :: Bool

-- | Returns first element of tuple type (with kind <tt>*</tt>) or
--   type-level tuple (with kind <tt>(k1, k2)</tt>, marked by prefix
--   quote).
--   
--   <pre>
--   &gt;&gt;&gt; :kind! Maybe (Fst '(Int, Text))
--   Maybe (Fst '(Int, Text)) :: *
--   = Maybe Int
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :kind! Maybe (Fst (Int, Text))
--   Maybe (Fst (Int, Text)) :: *
--   = Maybe Int
--   </pre>
type family Fst (t :: k) :: k'

-- | Returns second element of tuple type (with kind <tt>*</tt>) or
--   type-level tuple (with kind <tt>(k1, k2)</tt>, marked by prefix
--   quote).
--   
--   <pre>
--   &gt;&gt;&gt; :kind! Maybe (Snd '(Int, Text))
--   Maybe (Snd '(Int, Text)) :: *
--   = Maybe Text
--   
--   &gt;&gt;&gt; :kind! Maybe (Snd (Int, Text))
--   Maybe (Snd (Int, Text)) :: *
--   = Maybe Text
--   </pre>
type family Snd (t :: k) :: k'


-- | Functions to ease work with <tt>newtypes</tt>.
module Relude.Extra.Newtype

-- | Unwraps value from <tt>newtype</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; newtype Size = Size Int deriving Show
--   
--   &gt;&gt;&gt; un @Int (Size 5)
--   5
--   
--   &gt;&gt;&gt; un (Size 5) == length ['a', 'x', 'b']
--   False
--   </pre>
un :: Coercible a n => n -> a

-- | Wraps value to <tt>newtype</tt>. Behaves exactly as <a>un</a> but has
--   more meaningful name in case you need to convert some value to
--   <tt>newtype</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; newtype Flag = Flag Bool deriving (Show, Eq)
--   
--   &gt;&gt;&gt; wrap False == Flag True
--   False
--   </pre>
wrap :: forall n a. Coercible a n => a -> n

-- | Applies function to the content of <tt>newtype</tt>. This function is
--   not supposed to be used on <tt>newtype</tt>s that are created with the
--   help of smart constructors.
--   
--   <pre>
--   &gt;&gt;&gt; newtype Foo = Foo Bool deriving Show
--   
--   &gt;&gt;&gt; under not (Foo True)
--   Foo False
--   
--   &gt;&gt;&gt; newtype Bar = Bar String deriving Show
--   
--   &gt;&gt;&gt; under (filter (== 'a')) (Bar "abacaba")
--   Bar "aaaa"
--   </pre>
under :: forall n a. Coercible a n => (n -> n) -> a -> a

-- | Lift binary function for <tt>newtype</tt>s to work over underlying
--   <tt>newtype</tt> representation.
--   
--   <pre>
--   &gt;&gt;&gt; under2 @(Sum Int) (&lt;&gt;) (3 :: Int) 4
--   7
--   
--   &gt;&gt;&gt; under2 @All (&lt;&gt;) True False
--   False
--   </pre>
under2 :: forall n a. Coercible a n => (n -> n -> n) -> a -> a -> a

-- | Version of <a>under2</a> that works on <tt>newtype</tt>s parametrized
--   by their representation. Provided for convenience.
--   
--   <pre>
--   &gt;&gt;&gt; underF2 @Sum (&lt;&gt;) (3 :: Int) 4
--   7
--   
--   &gt;&gt;&gt; underF2 @Max (&lt;&gt;) 'p' 't'
--   't'
--   </pre>
underF2 :: forall n a. Coercible a (n a) => (n a -> n a -> n a) -> a -> a -> a

-- | Coercible composition. This function allows to write more efficient
--   implementations of function compositions over <tt>newtypes</tt>.
(#.) :: Coercible b c => (b -> c) -> (a -> b) -> a -> c


-- | This module aims to provide a minimal implementation of <tt>lens</tt>
--   package required for basic usage. All functions are compatible with
--   the real <tt>lens</tt> package therefore if you need to expand to the
--   full version the process should be straightforward.
--   
--   Main ideas implemented in this module are described in the following
--   blog post:
--   
--   <ul>
--   <li><a>Write yourself a lens (by Veronika Romashkina)</a></li>
--   </ul>
--   
--   <h2>Usage</h2>
--   
--   To use lenses in your project, you don't need to add any other
--   dependency rather than <tt>relude</tt>. You should add the import of
--   this module in the place of lenses usage:
--   
--   <pre>
--   <b>import</b> Relude.Extra.Lens
--   </pre>
--   
--   <h2>Example</h2>
--   
--   To understand better how to use this module lets look at some simple
--   example. Let's say we have the user data type in our system:
--   
--   <pre>
--   <b>data</b> User = User
--       { userName    :: <a>Text</a>
--       , userAge     :: <a>Int</a>
--       , userAddress :: Address
--       } <b>deriving</b> (<a>Show</a>)
--   
--   <b>data</b> Address = Address
--       { addressCountry :: <a>Text</a>
--       , addressCity    :: <a>Text</a>
--       , addressIndex   :: <a>Text</a>
--       } <b>deriving</b> (<a>Show</a>)
--   </pre>
--   
--   To create the lens for the <tt>userName</tt> field we can use
--   <a>lens</a> function and manually writing getter and setter function:
--   
--   <pre>
--   nameL :: <a>Lens'</a> User <a>Text</a>
--   nameL = <a>lens</a> getter setter
--     <b>where</b>
--       getter :: User -&gt; <a>Text</a>
--       getter = userName
--   
--       setter :: User -&gt; <a>Text</a> -&gt; User
--       setter user newName = user {userName = newName}
--   </pre>
--   
--   In this manner, we can create other lenses for our User data type.
--   
--   <pre>
--   ageL     :: <a>Lens'</a> User <a>Int</a>
--   addressL :: <a>Lens'</a> User Address
--   countryL :: <a>Lens'</a> User <a>Text</a>
--   cityL    :: <a>Lens'</a> User <a>Text</a>
--   indexL   :: <a>Lens'</a> User <a>Text</a>
--   </pre>
--   
--   <i>Note:</i> here we are using composition of the lenses for
--   <tt>userAddress</tt> field. If we have
--   
--   <pre>
--   addressCityL :: <a>Lens'</a> Address <a>Text</a>
--   </pre>
--   
--   then
--   
--   <pre>
--   cityL = addressL . addressCityL
--   </pre>
--   
--   Let's say we have some sample user
--   
--   <pre>
--   user :: User
--   user = User
--       { userName = "John"
--       , userAge  = 42
--       , userAddress = Address
--           { addressCountry = "UK"
--           , addressCity    = "London"
--           , addressIndex   = "XXX"
--           }
--       }
--   </pre>
--   
--   To view the fields of the User data type we can use <a>view</a> or
--   <a>^.</a>
--   
--   <pre>
--   <b>&gt;&gt;&gt;</b> <a>view</a> ageL user
--   42
--   <b>&gt;&gt;&gt;</b> user <a>^.</a> cityL
--   "London"
--   </pre>
--   
--   If we want to change any of the user's data, we should use <a>set</a>
--   or <a>.~</a>
--   
--   <pre>
--   <b>&gt;&gt;&gt;</b> <a>set</a> nameL "Johnny" user
--   <b>&gt;&gt;&gt;</b> user <a>&amp;</a> indexL <a>.~</a> "YYY"
--   </pre>
--   
--   <a>over</a> or <a>%~</a> operator could be useful when, for example,
--   you want to increase the age by one on the user's birthday:
--   
--   <pre>
--   <b>&gt;&gt;&gt;</b> <a>over</a> ageL <a>succ</a> user
--   <b>&gt;&gt;&gt;</b> user <a>&amp;</a> ageL <a>%~</a> <a>succ</a>
--   </pre>
--   
--   <h2>Migration</h2>
--   
--   This module is not supposed to be the replacement for the
--   <tt>lens</tt> package. One of the reasons why one would want to
--   migrate to <tt>lens</tt> or <tt>microlens</tt> is that the functional
--   in <tt>relude</tt> is limited to just vital lens functions.
--   
--   To migrate to <tt>lens</tt> or <tt>microlens</tt> package add the
--   required library to the dependencies list in the <tt>.cabal</tt> file
--   and replace the import from <tt>relude</tt> library
--   
--   <pre>
--   <b>import</b> Relude.Extra.Lens
--   </pre>
--   
--   to the one of this correspondingly:
--   
--   <ul>
--   <li><tt>lens</tt>:<pre><b>import</b> Control.Lens </pre></li>
--   <li><tt>microlens</tt>:<pre><b>import</b> Lens.Micro </pre></li>
--   </ul>
--   
--   And that's all! No need to change the types or implementation of the
--   functions you used <tt>Relude.Extra.Lens</tt> in.
--   
--   <h2>Links</h2>
--   
--   <ul>
--   <li><a>lens</a></li>
--   <li><a>microlens</a></li>
--   <li><a>lens tutorial</a></li>
--   </ul>
module Relude.Extra.Lens

-- | The monomorphic lenses which don't change the type of the container
--   (or of the value inside). It has a <a>Functor</a> constraint, and
--   since both <a>Const</a> and <a>Identity</a> are functors, it can be
--   used whenever a getter or a setter is needed.
--   
--   <ul>
--   <li><tt>a</tt> is the type of the value inside of structure</li>
--   <li><tt>s</tt> is the type of the whole structure</li>
--   </ul>
type Lens' s a = forall (f :: Type -> Type). Functor f => a -> f a -> s -> f s

-- | Creates <a>Lens'</a> from the getter and setter.
lens :: (s -> a) -> (s -> a -> s) -> Lens' s a

-- | Gets a value out of a structure using a getter.
view :: Lens' s a -> s -> a

-- | Sets the given value to the structure using a setter.
set :: Lens' s a -> a -> s -> s

-- | Applies the given function to the target.
over :: Lens' s a -> (a -> a) -> s -> s

-- | The operator form of <a>view</a> with the arguments flipped.
(^.) :: s -> Lens' s a -> a
infixl 8 ^.

-- | The operator form of <a>set</a>.
(.~) :: Lens' s a -> a -> s -> s
infixr 4 .~

-- | The operator form of <a>over</a>.
(%~) :: Lens' s a -> (a -> a) -> s -> s
infixr 4 %~


-- | Polymorphic grouping functions.
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 :: (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 :: (Foldable f, DynamicMap t, Val t ~ a, Monoid t) => (a -> Key t) -> f a -> t


-- | <a>Foldable1</a> is a typeclass like <a>Foldable</a> but for non-empty
--   structures. For example, <a>NonEmpty</a>, <a>Identity</a>.
--   
--   <a>Foldable1</a> has all type-safe and total methods like
--   <a>head1</a>, <a>maximum1</a> in contradiction with <a>Foldable</a>.
module Relude.Extra.Foldable1

-- | The class of foldable data structures that cannot be empty.
class Foldable f => Foldable1 (f :: Type -> Type)

-- | Map each element of the non-empty structure to a semigroup, and
--   combine the results.
--   
--   <pre>
--   &gt;&gt;&gt; foldMap1 SG.Sum (1 :| [2, 3, 4])
--   Sum {getSum = 10}
--   
--   &gt;&gt;&gt; foldMap1 show (123 :| [456, 789, 0])
--   "1234567890"
--   </pre>
foldMap1 :: (Foldable1 f, Semigroup m) => (a -> m) -> f a -> m

-- | Combine the elements of a non-empty structure using a semigroup.
--   
--   <pre>
--   &gt;&gt;&gt; fold1 (1 :| [2, 3, 4 :: SG.Sum Int])
--   Sum {getSum = 10}
--   
--   &gt;&gt;&gt; fold1 (4 :| [5, 10 :: SG.Product Int])
--   Product {getProduct = 200}
--   </pre>
fold1 :: (Foldable1 f, Semigroup m) => f m -> m

-- | Combines the elements of a non-empty structure using a binary function
--   <tt>f</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; foldr1 (+) 0 (1 :| [2, 3])
--   6
--   
--   &gt;&gt;&gt; foldr1 (+) 1 $ Identity 3
--   4
--   </pre>
foldr1 :: Foldable1 f => (a -> b -> b) -> b -> f a -> b

-- | Convert a non-empty data structure to a NonEmpty list.
--   
--   <pre>
--   &gt;&gt;&gt; toNonEmpty (Identity 2)
--   2 :| []
--   </pre>
toNonEmpty :: Foldable1 f => f a -> NonEmpty a

-- | The first element of a non-empty data structure.
--   
--   <pre>
--   &gt;&gt;&gt; head1 (1 :| [2, 3, 4])
--   1
--   </pre>
head1 :: Foldable1 f => f a -> a

-- | The last element of a non-empty data structure.
--   
--   <pre>
--   &gt;&gt;&gt; last1 (1 :| [2, 3, 4])
--   4
--   </pre>
last1 :: Foldable1 f => f a -> a

-- | The largest element of a non-empty data structure.
--   
--   <pre>
--   &gt;&gt;&gt; maximum1 (32 :| [64, 8, 128, 16])
--   128
--   </pre>
maximum1 :: (Foldable1 f, Ord a) => f a -> a

-- | The smallest element of a non-empty data structure.
--   
--   <pre>
--   &gt;&gt;&gt; minimum1 (32 :| [64, 8, 128, 16])
--   8
--   </pre>
minimum1 :: (Foldable1 f, Ord a) => f a -> a

-- | The largest element of a non-empty data structure with respect to the
--   given comparison function.
--   
--   <pre>
--   &gt;&gt;&gt; maximumOn1 abs (0 :| [2, 1, -3, -2])
--   -3
--   </pre>
maximumOn1 :: (Foldable1 f, Ord b) => (a -> b) -> f a -> a

-- | The smallest element of a non-empty data structure with respect to the
--   given comparison function.
--   
--   <pre>
--   &gt;&gt;&gt; minimumOn1 abs (0 :| [2, 1, -3, -2])
--   0
--   </pre>
minimumOn1 :: (Foldable1 f, Ord b) => (a -> b) -> f a -> a

-- | Strictly folds non-empty structure with given function <tt>f</tt>:
--   
--   <pre>
--   foldl1' f [x0, x1, x2 ...] = f (f x0 x1) x2 ...
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; foldl1' (++) ([1,2] :| [[3,4], [5,6]])
--   [1,2,3,4,5,6]
--   </pre>
foldl1' :: (a -> a -> a) -> NonEmpty a -> a

-- | Given a <a>Foldable1</a> of <a>Fractional</a> elements, computes the
--   average if possible and returns the resulting element.
--   
--   <pre>
--   &gt;&gt;&gt; average1 (42 :| [])
--   42.0
--   
--   &gt;&gt;&gt; average1 (1 :| [2,3,4])
--   2.5
--   </pre>
average1 :: forall a f. (Foldable1 f, Fractional a) => f a -> a
instance (Relude.Extra.Foldable1.Foldable1 f, Relude.Extra.Foldable1.Foldable1 g) => Relude.Extra.Foldable1.Foldable1 (Data.Functor.Compose.Compose f g)
instance Relude.Extra.Foldable1.Foldable1 GHC.Internal.Data.Functor.Identity.Identity
instance Relude.Extra.Foldable1.IsListError => Relude.Extra.Foldable1.Foldable1 []
instance Relude.Extra.Foldable1.Foldable1 GHC.Internal.Base.NonEmpty
instance (Relude.Extra.Foldable1.Foldable1 f, Relude.Extra.Foldable1.Foldable1 g) => Relude.Extra.Foldable1.Foldable1 (Data.Functor.Product.Product f g)
instance (Relude.Extra.Foldable1.Foldable1 f, Relude.Extra.Foldable1.Foldable1 g) => Relude.Extra.Foldable1.Foldable1 (Data.Functor.Sum.Sum f g)
instance Relude.Extra.Foldable1.Foldable1 ((,) c)


-- | Contains utility functions for working with tuples.
module Relude.Extra.Foldable

-- | A left-associative fold that's tail-recursive but can still
--   short-circuit. Returning a <a>Left</a> short-circuits and immediately
--   returns the value inside. Returning a <a>Right</a> continues the fold
--   as usual with the value inside.
--   
--   <pre>
--   &gt;&gt;&gt; foldlSC (\acc x -&gt; if x == 0 then Left 0 else Right $! acc * x) 1 [1..6]
--   720
--   
--   &gt;&gt;&gt; foldlSC (\acc x -&gt; if x == 0 then Left 0 else Right $! acc * x) 1 (0:error "Short-circuiting should keep this from happening")
--   0
--   </pre>
foldlSC :: Foldable t => (b -> a -> Either b b) -> b -> t a -> b

-- | Given a <a>Foldable</a> of <a>Fractional</a> elements, computes the
--   average if possible and returns <a>Maybe</a> element.
--   
--   <pre>
--   &gt;&gt;&gt; average [42]
--   Just 42.0
--   
--   &gt;&gt;&gt; average @Double [1, 2, 3, 4]
--   Just 2.5
--   
--   &gt;&gt;&gt; average @Float [1.5, 2.5, 3 ,4]
--   Just 2.75
--   
--   &gt;&gt;&gt; average []
--   Nothing
--   </pre>
average :: forall a f. (Foldable f, Fractional a) => f a -> Maybe a


-- | Mini <tt>bounded-enum</tt> framework inside <tt>relude</tt>.
module Relude.Extra.Enum

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

-- | Like <a>pred</a>, but doesn't fail on <a>minBound</a>. Instead it
--   returns <a>maxBound</a>.
--   
--   <pre>
--   &gt;&gt;&gt; prev True
--   False
--   
--   &gt;&gt;&gt; prev False
--   True
--   
--   &gt;&gt;&gt; pred False
--   *** Exception: Prelude.Enum.Bool.pred: bad argument
--   </pre>
prev :: (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 :: (Bounded a, Enum a) => Int -> Maybe a


-- | Contains useful functions to work with GHC callstack.
module Relude.Extra.CallStack

-- | This function returns the name of its caller function, but it requires
--   that the caller function has <a>HasCallStack</a> constraint.
--   Otherwise, it returns <tt>"<a>unknown</a>"</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; foo :: HasCallStack =&gt; String; foo = ownName
--   
--   &gt;&gt;&gt; foo
--   "foo"
--   
--   &gt;&gt;&gt; bar :: HasCallStack =&gt; String; bar = foo
--   
--   &gt;&gt;&gt; bar
--   "foo"
--   </pre>
ownName :: HasCallStack => String

-- | This function returns the name of its caller of the caller function,
--   but it requires that the caller function and caller of the caller
--   function have <a>HasCallStack</a> constraint. Otherwise, it returns
--   <tt>"<a>unknown</a>"</tt>. It's useful for logging:
--   
--   <pre>
--   &gt;&gt;&gt; log :: HasCallStack =&gt; String -&gt; IO (); log s = putStrLn $ callerName ++ ":" ++ s
--   
--   &gt;&gt;&gt; greeting :: HasCallStack =&gt; IO (); greeting = log "Starting..." &gt;&gt; putStrLn "Hello!" &gt;&gt; log "Ending..."
--   
--   &gt;&gt;&gt; greeting
--   greeting:Starting...
--   Hello!
--   greeting:Ending...
--   </pre>
callerName :: HasCallStack => String


-- | Useful combinators for bifunctors inside functors. This set of
--   functions is useful when you want to work with types like these ones:
--   
--   <pre>
--   foo :: IO (Either a b)
--   bar :: IO (a, b)
--   
--   baz :: Maybe (Either a b)
--   qux :: Maybe (a, b)
--   
--   doo :: (a, a)
--   dee :: Either a a
--   </pre>
module Relude.Extra.Bifunctor

-- | Maps a function over both elements of a bifunctor.
--   
--   <pre>
--   &gt;&gt;&gt; bimapBoth length ([True], [False, True])
--   (1,2)
--   
--   &gt;&gt;&gt; map (bimapBoth not) [Left True, Right False]
--   [Left False,Right True]
--   </pre>
bimapBoth :: Bifunctor f => (a -> b) -> f a a -> f b b

-- | Fmaps functions for nested bifunctor. Short for <tt>fmap (bimap f
--   g)</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; bimapF not length $ Just (False, ['a', 'b'])
--   Just (True,2)
--   </pre>
bimapF :: (Functor f, Bifunctor p) => (a -> c) -> (b -> d) -> f (p a b) -> f (p c d)

-- | Short for <tt>fmap . first</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; firstF not $ Just (False, ['a', 'b'])
--   Just (True,"ab")
--   </pre>
firstF :: (Functor f, Bifunctor p) => (a -> c) -> f (p a b) -> f (p c b)

-- | Short for <tt>fmap . second</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; secondF length  $ Just (False, ['a', 'b'])
--   Just (False,2)
--   </pre>
secondF :: (Functor f, Bifunctor p) => (b -> d) -> f (p a b) -> f (p a d)


-- | This module exports all extra-related stuff. The extra modules are not
--   exported by default, but you can easily bring them to every module in
--   your package by modifying your <a>Prelude</a> file.
module Relude.Extra


-- | <b>⚠️ Warning ⚠️</b>
--   
--   This module contains unsafe partial functions. They are unavoidable
--   sometimes, but we encourage you to use safer analogues:
--   
--   TODO: table
--   
--   This module is intended to be imported qualified and it is not
--   included in default prelude exports.
--   
--   <pre>
--   <b>import qualified</b> Relude.Unsafe as Unsafe
--   
--   foo :: [a] -&gt; a
--   foo = Unsafe.<a>head</a>
--   </pre>
module Relude.Unsafe
head :: HasCallStack => [a] -> a
tail :: HasCallStack => [a] -> [a]
last :: HasCallStack => [a] -> a
init :: HasCallStack => [a] -> [a]
(!!) :: HasCallStack => [a] -> Int -> a

-- | Similar to <a>!!</a> but with flipped arguments. get element from list
--   using index value starting from `0`.
--   
--   <pre>
--   &gt;&gt;&gt; at 2 ["a", "b", "c"]
--   "c"
--   </pre>
--   
--   it is also useful when used in a partially applied position like:
--   
--   <pre>
--   &gt;&gt;&gt; map (at 1) [["a","b","c"], ["a","b","c"], ["a","b","c"]]
--   ["b","b","b"]
--   </pre>
at :: Int -> [a] -> a
fromJust :: HasCallStack => Maybe a -> a
read :: Read a => String -> a
