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


-- | Extra functions I use.
--   
--   A library of extra functions for the standard Haskell libraries. Most
--   functions are simple additions, filling out missing functionality. A
--   few functions are available in later versions of GHC, but this package
--   makes them available back to GHC 7.2.
--   
--   The module <a>Extra</a> documents all functions provided by this
--   library. Modules such as <a>Data.List.Extra</a> provide extra
--   functions over <a>Data.List</a> and also reexport <a>Data.List</a>.
--   Users are recommended to replace <a>Data.List</a> imports with
--   <a>Data.List.Extra</a> if they need the extra functionality.
@package extra
@version 1.7.10


-- | This module extends <a>Data.IORef</a> with operations forcing the
--   value written to the IORef. Some of these functions are available in
--   later versions of GHC, but not all.
module Data.IORef.Extra

-- | Evaluates the value before calling <a>writeIORef</a>.
writeIORef' :: IORef a -> a -> IO ()

-- | Evaluates the value before calling <a>atomicWriteIORef</a>.
atomicWriteIORef' :: IORef a -> a -> IO ()

-- | Variant of <a>atomicModifyIORef</a> which ignores the return value
atomicModifyIORef_ :: IORef a -> (a -> a) -> IO ()

-- | Variant of <a>atomicModifyIORef'</a> which ignores the return value
atomicModifyIORef'_ :: IORef a -> (a -> a) -> IO ()


-- | Extra functions for working with pairs and triples. Some of these
--   functions are available in the <a>Control.Arrow</a> module, but here
--   are available specialised to pairs. Some operations work on triples.
module Data.Tuple.Extra

-- | Update the first component of a pair.
--   
--   <pre>
--   first succ (1,"test") == (2,"test")
--   </pre>
first :: (a -> a') -> (a, b) -> (a', b)

-- | Update the second component of a pair.
--   
--   <pre>
--   second reverse (1,"test") == (1,"tset")
--   </pre>
second :: (b -> b') -> (a, b) -> (a, b')

-- | Given two functions, apply one to the first component and one to the
--   second. A specialised version of <a>***</a>.
--   
--   <pre>
--   (succ *** reverse) (1,"test") == (2,"tset")
--   </pre>
(***) :: (a -> a') -> (b -> b') -> (a, b) -> (a', b')
infixr 3 ***

-- | Given two functions, apply both to a single argument to form a pair. A
--   specialised version of <a>&amp;&amp;&amp;</a>.
--   
--   <pre>
--   (succ &amp;&amp;&amp; pred) 1 == (2,0)
--   </pre>
(&&&) :: (a -> b) -> (a -> c) -> a -> (b, c)
infixr 3 &&&

-- | Duplicate a single value into a pair.
--   
--   <pre>
--   dupe 12 == (12, 12)
--   </pre>
dupe :: a -> (a, a)

-- | Apply a single function to both components of a pair.
--   
--   <pre>
--   both succ (1,2) == (2,3)
--   </pre>
both :: (a -> b) -> (a, a) -> (b, b)

-- | Update the first component of a pair.
--   
--   <pre>
--   firstM (\x -&gt; [x-1, x+1]) (1,"test") == [(0,"test"),(2,"test")]
--   </pre>
firstM :: Functor m => (a -> m a') -> (a, b) -> m (a', b)

-- | Update the second component of a pair.
--   
--   <pre>
--   secondM (\x -&gt; [reverse x, x]) (1,"test") == [(1,"tset"),(1,"test")]
--   </pre>
secondM :: Functor m => (b -> m b') -> (a, b) -> m (a, b')

-- | Extract the <a>fst</a> of a triple.
fst3 :: (a, b, c) -> a

-- | Extract the <a>snd</a> of a triple.
snd3 :: (a, b, c) -> b

-- | Extract the final element of a triple.
thd3 :: (a, b, c) -> c

-- | Update the first component of a triple.
--   
--   <pre>
--   first3 succ (1,1,1) == (2,1,1)
--   </pre>
first3 :: (a -> a') -> (a, b, c) -> (a', b, c)

-- | Update the second component of a triple.
--   
--   <pre>
--   second3 succ (1,1,1) == (1,2,1)
--   </pre>
second3 :: (b -> b') -> (a, b, c) -> (a, b', c)

-- | Update the third component of a triple.
--   
--   <pre>
--   third3 succ (1,1,1) == (1,1,2)
--   </pre>
third3 :: (c -> c') -> (a, b, c) -> (a, b, c')

-- | Converts an uncurried function to a curried function.
curry3 :: ((a, b, c) -> d) -> a -> b -> c -> d

-- | Converts a curried function to a function on a triple.
uncurry3 :: (a -> b -> c -> d) -> (a, b, c) -> d


-- | This module extends <a>Data.Typeable</a> with extra functions
--   available in later GHC versions. The package also exports the existing
--   <a>Data.Typeable</a> functions.
--   
--   Currently this module has no functionality beyond
--   <a>Data.Typeable</a>.

-- | <i>Deprecated: Use Data.Typeable directly</i>
module Data.Typeable.Extra


-- | Extra numeric functions - formatting and specialised conversions.
module Numeric.Extra

-- | Show a number to a fixed number of decimal places.
--   
--   <pre>
--   showDP 4 pi == "3.1416"
--   showDP 0 pi == "3"
--   showDP 2 3  == "3.00"
--   </pre>
showDP :: RealFloat a => Int -> a -> String

-- | Specialised numeric conversion, type restricted version of
--   <a>fromIntegral</a>.
intToDouble :: Int -> Double

-- | Specialised numeric conversion, type restricted version of
--   <a>fromIntegral</a>.
intToFloat :: Int -> Float

-- | Specialised numeric conversion, type restricted version of
--   <a>realToFrac</a>.
floatToDouble :: Float -> Double

-- | Specialised numeric conversion, type restricted version of
--   <a>realToFrac</a>.
doubleToFloat :: Double -> Float


-- | This module extends <a>Data.List</a> with extra functions of a similar
--   nature. The package also exports the existing <a>Data.List</a>
--   functions. Some of the names and semantics were inspired by the
--   <a>text</a> package.
module Data.List.Extra

-- | Convert a string to lower case.
--   
--   <pre>
--   lower "This is A TEST" == "this is a test"
--   lower "" == ""
--   </pre>
lower :: String -> String

-- | Convert a string to upper case.
--   
--   <pre>
--   upper "This is A TEST" == "THIS IS A TEST"
--   upper "" == ""
--   </pre>
upper :: String -> String

-- | Remove spaces from either side of a string. A combination of
--   <a>trimEnd</a> and <a>trimStart</a>.
--   
--   <pre>
--   trim      "  hello   " == "hello"
--   trimStart "  hello   " == "hello   "
--   trimEnd   "  hello   " == "  hello"
--   \s -&gt; trim s == trimEnd (trimStart s)
--   </pre>
trim :: String -> String

-- | Remove spaces from the start of a string, see <a>trim</a>.
trimStart :: String -> String

-- | Remove spaces from the end of a string, see <a>trim</a>.
trimEnd :: String -> String

-- | Split the first word off a string. Useful for when starting to parse
--   the beginning of a string, but you want to accurately preserve
--   whitespace in the rest of the string.
--   
--   <pre>
--   word1 "" == ("", "")
--   word1 "keyword rest of string" == ("keyword","rest of string")
--   word1 "  keyword\n  rest of string" == ("keyword","rest of string")
--   \s -&gt; fst (word1 s) == concat (take 1 $ words s)
--   \s -&gt; words (snd $ word1 s) == drop 1 (words s)
--   </pre>
word1 :: String -> (String, String)

-- | Split the first line off a string.
--   
--   <pre>
--   line1 "" == ("", "")
--   line1 "test" == ("test","")
--   line1 "test\n" == ("test","")
--   line1 "test\nrest" == ("test","rest")
--   line1 "test\nrest\nmore" == ("test","rest\nmore")
--   </pre>
line1 :: String -> (String, String)

-- | Escape a string such that it can be inserted into an HTML document or
--   <tt>"</tt> attribute without any special interpretation. This requires
--   escaping the <tt>&lt;</tt>, <tt>&gt;</tt>, <tt>&amp;</tt> and
--   <tt>"</tt> characters. Note that it will escape <tt>"</tt> and
--   <tt>'</tt> even though that is not required in an HTML body (but is
--   not harmful).
--   
--   <pre>
--   escapeHTML "this is a test" == "this is a test"
--   escapeHTML "&lt;b&gt;\"g&amp;t\"&lt;/n&gt;" == "&amp;lt;b&amp;gt;&amp;quot;g&amp;amp;t&amp;quot;&amp;lt;/n&amp;gt;"
--   escapeHTML "t'was another test" == "t&amp;#39;was another test"
--   </pre>
escapeHTML :: String -> String

-- | Escape a string so it can form part of a JSON literal. This requires
--   escaping the special whitespace and control characters. Additionally,
--   Note that it does <i>not</i> add quote characters around the string.
--   
--   <pre>
--   escapeJSON "this is a test" == "this is a test"
--   escapeJSON "\ttab\nnewline\\" == "\\ttab\\nnewline\\\\"
--   escapeJSON "\ESC[0mHello" == "\\u001b[0mHello"
--   </pre>
escapeJSON :: String -> String

-- | Invert of <a>escapeHTML</a> (does not do general HTML unescaping)
--   
--   <pre>
--   \xs -&gt; unescapeHTML (escapeHTML xs) == xs
--   </pre>
unescapeHTML :: String -> String

-- | General JSON unescaping, inversion of <a>escapeJSON</a> and all other
--   JSON escapes.
--   
--   <pre>
--   \xs -&gt; unescapeJSON (escapeJSON xs) == xs
--   </pre>
unescapeJSON :: String -> String

-- | Drop a number of elements from the end of the list.
--   
--   <pre>
--   dropEnd 3 "hello"  == "he"
--   dropEnd 5 "bye"    == ""
--   dropEnd (-1) "bye" == "bye"
--   \i xs -&gt; dropEnd i xs `isPrefixOf` xs
--   \i xs -&gt; length (dropEnd i xs) == max 0 (length xs - max 0 i)
--   \i -&gt; take 3 (dropEnd 5 [i..]) == take 3 [i..]
--   </pre>
dropEnd :: Int -> [a] -> [a]

-- | Take a number of elements from the end of the list.
--   
--   <pre>
--   takeEnd 3 "hello"  == "llo"
--   takeEnd 5 "bye"    == "bye"
--   takeEnd (-1) "bye" == ""
--   \i xs -&gt; takeEnd i xs `isSuffixOf` xs
--   \i xs -&gt; length (takeEnd i xs) == min (max 0 i) (length xs)
--   </pre>
takeEnd :: Int -> [a] -> [a]

-- | <tt><a>splitAtEnd</a> n xs</tt> returns a split where the second
--   element tries to contain <tt>n</tt> elements.
--   
--   <pre>
--   splitAtEnd 3 "hello" == ("he","llo")
--   splitAtEnd 3 "he"    == ("", "he")
--   \i xs -&gt; uncurry (++) (splitAt i xs) == xs
--   \i xs -&gt; splitAtEnd i xs == (dropEnd i xs, takeEnd i xs)
--   </pre>
splitAtEnd :: Int -> [a] -> ([a], [a])

-- | Break, but from the end.
--   
--   <pre>
--   breakEnd isLower "youRE" == ("you","RE")
--   breakEnd isLower "youre" == ("youre","")
--   breakEnd isLower "YOURE" == ("","YOURE")
--   \f xs -&gt; breakEnd (not . f) xs == spanEnd f  xs
--   </pre>
breakEnd :: (a -> Bool) -> [a] -> ([a], [a])

-- | Span, but from the end.
--   
--   <pre>
--   spanEnd isUpper "youRE" == ("you","RE")
--   spanEnd (not . isSpace) "x y z" == ("x y ","z")
--   \f xs -&gt; uncurry (++) (spanEnd f xs) == xs
--   \f xs -&gt; spanEnd f xs == swap (both reverse (span f (reverse xs)))
--   </pre>
spanEnd :: (a -> Bool) -> [a] -> ([a], [a])

-- | A version of <a>dropWhileEnd</a> but with different strictness
--   properties. The function <a>dropWhileEnd</a> can be used on an
--   infinite list and tests the property on each character. In contrast,
--   <a>dropWhileEnd'</a> is strict in the spine of the list but only tests
--   the trailing suffix. This version usually outperforms
--   <a>dropWhileEnd</a> if the list is short or the test is expensive.
--   Note the tests below cover both the prime and non-prime variants.
--   
--   <pre>
--   dropWhileEnd  isSpace "ab cde  " == "ab cde"
--   dropWhileEnd' isSpace "ab cde  " == "ab cde"
--   last (dropWhileEnd  even [undefined,3]) == undefined
--   last (dropWhileEnd' even [undefined,3]) == 3
--   head (dropWhileEnd  even (3:undefined)) == 3
--   head (dropWhileEnd' even (3:undefined)) == undefined
--   </pre>
dropWhileEnd' :: (a -> Bool) -> [a] -> [a]

-- | A version of <a>takeWhile</a> operating from the end.
--   
--   <pre>
--   takeWhileEnd even [2,3,4,6] == [4,6]
--   </pre>
takeWhileEnd :: (a -> Bool) -> [a] -> [a]

-- | Return the prefix of the second list if its suffix matches the entire
--   first list.
--   
--   Examples:
--   
--   <pre>
--   stripSuffix "bar" "foobar" == Just "foo"
--   stripSuffix ""    "baz"    == Just "baz"
--   stripSuffix "foo" "quux"   == Nothing
--   </pre>
stripSuffix :: Eq a => [a] -> [a] -> Maybe [a]

-- | Return the the string before and after the search string, or
--   <a>Nothing</a> if the search string is not present.
--   
--   Examples:
--   
--   <pre>
--   stripInfix "::" "a::b::c" == Just ("a", "b::c")
--   stripInfix "/" "foobar"   == Nothing
--   </pre>
stripInfix :: Eq a => [a] -> [a] -> Maybe ([a], [a])

-- | Similar to <a>stripInfix</a>, but searches from the end of the string.
--   
--   <pre>
--   stripInfixEnd "::" "a::b::c" == Just ("a::b", "c")
--   </pre>
stripInfixEnd :: Eq a => [a] -> [a] -> Maybe ([a], [a])

-- | Drops the given prefix from a list. It returns the original sequence
--   if the sequence doesn't start with the given prefix.
--   
--   <pre>
--   dropPrefix "Mr. " "Mr. Men" == "Men"
--   dropPrefix "Mr. " "Dr. Men" == "Dr. Men"
--   </pre>
dropPrefix :: Eq a => [a] -> [a] -> [a]

-- | Drops the given suffix from a list. It returns the original sequence
--   if the sequence doesn't end with the given suffix.
--   
--   <pre>
--   dropSuffix "!" "Hello World!"  == "Hello World"
--   dropSuffix "!" "Hello World!!" == "Hello World!"
--   dropSuffix "!" "Hello World."  == "Hello World."
--   </pre>
dropSuffix :: Eq a => [a] -> [a] -> [a]

-- | A variant of <a>words</a> with a custom test. In particular, adjacent
--   separators are discarded, as are leading or trailing separators.
--   
--   <pre>
--   wordsBy (== ':') "::xyz:abc::123::" == ["xyz","abc","123"]
--   \s -&gt; wordsBy isSpace s == words s
--   </pre>
wordsBy :: (a -> Bool) -> [a] -> [[a]]

-- | A variant of <a>lines</a> with a custom test. In particular, if there
--   is a trailing separator it will be discarded.
--   
--   <pre>
--   linesBy (== ':') "::xyz:abc::123::" == ["","","xyz","abc","","123",""]
--   \s -&gt; linesBy (== '\n') s == lines s
--   linesBy (== ';') "my;list;here;" == ["my","list","here"]
--   </pre>
linesBy :: (a -> Bool) -> [a] -> [[a]]

-- | Find the first instance of <tt>needle</tt> in <tt>haystack</tt>. The
--   first element of the returned tuple is the prefix of <tt>haystack</tt>
--   before <tt>needle</tt> is matched. The second is the remainder of
--   <tt>haystack</tt>, starting with the match. If you want the remainder
--   <i>without</i> the match, use <a>stripInfix</a>.
--   
--   <pre>
--   breakOn "::" "a::b::c" == ("a", "::b::c")
--   breakOn "/" "foobar"   == ("foobar", "")
--   \needle haystack -&gt; let (prefix,match) = breakOn needle haystack in prefix ++ match == haystack
--   </pre>
breakOn :: Eq a => [a] -> [a] -> ([a], [a])

-- | Similar to <a>breakOn</a>, but searches from the end of the string.
--   
--   The first element of the returned tuple is the prefix of
--   <tt>haystack</tt> up to and including the last match of
--   <tt>needle</tt>. The second is the remainder of <tt>haystack</tt>,
--   following the match.
--   
--   <pre>
--   breakOnEnd "::" "a::b::c" == ("a::b::", "c")
--   </pre>
breakOnEnd :: Eq a => [a] -> [a] -> ([a], [a])

-- | Break a list into pieces separated by the first list argument,
--   consuming the delimiter. An empty delimiter is invalid, and will cause
--   an error to be raised.
--   
--   <pre>
--   splitOn "\r\n" "a\r\nb\r\nd\r\ne" == ["a","b","d","e"]
--   splitOn "aaa"  "aaaXaaaXaaaXaaa"  == ["","X","X","X",""]
--   splitOn "x"    "x"                == ["",""]
--   splitOn "x"    ""                 == [""]
--   \s x -&gt; s /= "" ==&gt; intercalate s (splitOn s x) == x
--   \c x -&gt; splitOn [c] x                           == split (==c) x
--   </pre>
splitOn :: (Partial, Eq a) => [a] -> [a] -> [[a]]

-- | Splits a list into components delimited by separators, where the
--   predicate returns True for a separator element. The resulting
--   components do not contain the separators. Two adjacent separators
--   result in an empty component in the output.
--   
--   <pre>
--   split (== 'a') "aabbaca" == ["","","bb","c",""]
--   split (== 'a') ""        == [""]
--   split (== ':') "::xyz:abc::123::" == ["","","xyz","abc","","123","",""]
--   split (== ',') "my,list,here" == ["my","list","here"]
--   </pre>
split :: (a -> Bool) -> [a] -> [[a]]

-- | Split a list into chunks of a given size. The last chunk may contain
--   fewer than n elements. The chunk size must be positive.
--   
--   <pre>
--   chunksOf 3 "my test" == ["my ","tes","t"]
--   chunksOf 3 "mytest"  == ["myt","est"]
--   chunksOf 8 ""        == []
--   chunksOf 0 "test"    == undefined
--   </pre>
chunksOf :: Partial => Int -> [a] -> [[a]]

-- | A total <a>head</a> with a default value.
--   
--   <pre>
--   headDef 1 []      == 1
--   headDef 1 [2,3,4] == 2
--   \x xs -&gt; headDef x xs == fromMaybe x (listToMaybe xs)
--   </pre>
headDef :: a -> [a] -> a

-- | A total <a>last</a> with a default value.
--   
--   <pre>
--   lastDef 1 []      == 1
--   lastDef 1 [2,3,4] == 4
--   \x xs -&gt; lastDef x xs == last (x:xs)
--   </pre>
lastDef :: a -> [a] -> a

-- | A total variant of the list index function <a>(!!)</a>.
--   
--   <pre>
--   [2,3,4] !? 1    == Just 3
--   [2,3,4] !? (-1) == Nothing
--   []      !? 0    == Nothing
--   </pre>
(!?) :: [a] -> Int -> Maybe a

-- | A composition of <a>not</a> and <a>null</a>.
--   
--   <pre>
--   notNull []  == False
--   notNull [1] == True
--   \xs -&gt; notNull xs == not (null xs)
--   </pre>
notNull :: [a] -> Bool

-- | Non-recursive transform over a list, like <a>maybe</a>.
--   
--   <pre>
--   list 1 (\v _ -&gt; v - 2) [5,6,7] == 3
--   list 1 (\v _ -&gt; v - 2) []      == 1
--   \nil cons xs -&gt; maybe nil (uncurry cons) (uncons xs) == list nil cons xs
--   </pre>
list :: b -> (a -> [a] -> b) -> [a] -> b

-- | If the list is empty returns <a>Nothing</a>, otherwise returns the
--   <a>init</a> and the <a>last</a>.
--   
--   <pre>
--   unsnoc "test" == Just ("tes",'t')
--   unsnoc ""     == Nothing
--   \xs -&gt; unsnoc xs == if null xs then Nothing else Just (init xs, last xs)
--   </pre>
unsnoc :: [a] -> Maybe ([a], a)

-- | Append an element to the start of a list, an alias for <tt>(:)</tt>.
--   
--   <pre>
--   cons 't' "est" == "test"
--   \x xs -&gt; uncons (cons x xs) == Just (x,xs)
--   </pre>
cons :: a -> [a] -> [a]

-- | Append an element to the end of a list, takes <i>O(n)</i> time.
--   
--   <pre>
--   snoc "tes" 't' == "test"
--   \xs x -&gt; unsnoc (snoc xs x) == Just (xs,x)
--   </pre>
snoc :: [a] -> a -> [a]

-- | Equivalent to <tt>drop 1</tt>, but likely to be faster and a single
--   lexeme.
--   
--   <pre>
--   drop1 ""         == ""
--   drop1 "test"     == "est"
--   \xs -&gt; drop 1 xs == drop1 xs
--   </pre>
drop1 :: [a] -> [a]

-- | Equivalent to <tt>dropEnd 1</tt>, but likely to be faster and a single
--   lexeme.
--   
--   <pre>
--   dropEnd1 ""         == ""
--   dropEnd1 "test"     == "tes"
--   \xs -&gt; dropEnd 1 xs == dropEnd1 xs
--   </pre>
dropEnd1 :: [a] -> [a]

-- | Version on <a>concatMap</a> generalised to a <a>Monoid</a> rather than
--   just a list.
--   
--   <pre>
--   mconcatMap Sum [1,2,3] == Sum 6
--   \f xs -&gt; mconcatMap f xs == concatMap f xs
--   </pre>
mconcatMap :: Monoid b => (a -> b) -> [a] -> b

-- | Lazily compare the length of a <a>Foldable</a> with a number.
--   
--   <pre>
--   compareLength [1,2,3] 1 == GT
--   compareLength [1,2] 2 == EQ
--   \(xs :: [Int]) n -&gt; compareLength xs n == compare (length xs) n
--   compareLength (1:2:3:undefined) 2 == GT
--   </pre>
compareLength :: (Ord b, Num b, Foldable f) => f a -> b -> Ordering

-- | Lazily compare the length of two <a>Foldable</a>s. &gt;
--   comparingLength [1,2,3] [False] == GT &gt; comparingLength [1,2] "ab"
--   == EQ &gt; (xs :: [Int]) (ys :: [Int]) -&gt; comparingLength xs ys ==
--   Data.Ord.comparing length xs ys &gt; comparingLength <a>1,2</a> == LT
--   &gt; comparingLength (1:2:3:undefined) [1,2] == GT
comparingLength :: (Foldable f1, Foldable f2) => f1 a -> f2 b -> Ordering

-- | Enumerate all the values of an <a>Enum</a>, from <a>minBound</a> to
--   <a>maxBound</a>.
--   
--   <pre>
--   enumerate == [False, True]
--   </pre>
enumerate :: (Enum a, Bounded a) => [a]

-- | A combination of <a>group</a> and <a>sort</a>.
--   
--   <pre>
--   groupSort [(1,'t'),(3,'t'),(2,'e'),(2,'s')] == [(1,"t"),(2,"es"),(3,"t")]
--   \xs -&gt; map fst (groupSort xs) == sort (nub (map fst xs))
--   \xs -&gt; concatMap snd (groupSort xs) == map snd (sortOn fst xs)
--   </pre>
groupSort :: Ord k => [(k, v)] -> [(k, [v])]

-- | A combination of <a>group</a> and <a>sort</a>, using a part of the
--   value to compare on.
--   
--   <pre>
--   groupSortOn length ["test","of","sized","item"] == [["of"],["test","item"],["sized"]]
--   </pre>
groupSortOn :: Ord b => (a -> b) -> [a] -> [[a]]

-- | A combination of <a>group</a> and <a>sort</a>, using a predicate to
--   compare on.
--   
--   <pre>
--   groupSortBy (compare `on` length) ["test","of","sized","item"] == [["of"],["test","item"],["sized"]]
--   </pre>
groupSortBy :: (a -> a -> Ordering) -> [a] -> [[a]]

-- | <i>O(n log n)</i>. The <a>nubOrd</a> function removes duplicate
--   elements from a list. In particular, it keeps only the first
--   occurrence of each element. Unlike the standard <a>nub</a> operator,
--   this version requires an <a>Ord</a> instance and consequently runs
--   asymptotically faster.
--   
--   <pre>
--   nubOrd "this is a test" == "this ae"
--   nubOrd (take 4 ("this" ++ undefined)) == "this"
--   \xs -&gt; nubOrd xs == nub xs
--   </pre>
nubOrd :: Ord a => [a] -> [a]

-- | A version of <a>nubOrd</a> with a custom predicate.
--   
--   <pre>
--   nubOrdBy (compare `on` length) ["a","test","of","this"] == ["a","test","of"]
--   </pre>
nubOrdBy :: (a -> a -> Ordering) -> [a] -> [a]

-- | A version of <a>nubOrd</a> which operates on a portion of the value.
--   
--   <pre>
--   nubOrdOn length ["a","test","of","this"] == ["a","test","of"]
--   </pre>
nubOrdOn :: Ord b => (a -> b) -> [a] -> [a]

-- | <i>DEPRECATED</i> Use <a>nubOrdOn</a>, since this function is
--   _O(n^2)_.
--   
--   A version of <a>nub</a> where the equality is done on some extracted
--   value. <tt>nubOn f</tt> is equivalent to <tt>nubBy ((==) <a>on</a>
--   f)</tt>, but has the performance advantage of only evaluating
--   <tt>f</tt> once for each element in the input list.

-- | <i>Deprecated: Use nubOrdOn, since this function is O(n^2)</i>
nubOn :: Eq b => (a -> b) -> [a] -> [a]

-- | A version of <a>group</a> where the equality is done on some extracted
--   value.
groupOn :: Eq b => (a -> b) -> [a] -> [[a]]

-- | <i>O(n log n)</i>. The <a>nubSort</a> function sorts and removes
--   duplicate elements from a list. In particular, it keeps only the first
--   occurrence of each element.
--   
--   <pre>
--   nubSort "this is a test" == " aehist"
--   \xs -&gt; nubSort xs == nub (sort xs)
--   </pre>
nubSort :: Ord a => [a] -> [a]

-- | A version of <a>nubSort</a> with a custom predicate.
--   
--   <pre>
--   nubSortBy (compare `on` length) ["a","test","of","this"] == ["a","of","test"]
--   </pre>
nubSortBy :: (a -> a -> Ordering) -> [a] -> [a]

-- | A version of <a>nubSort</a> which operates on a portion of the value.
--   
--   <pre>
--   nubSortOn length ["a","test","of","this"] == ["a","of","test"]
--   </pre>
nubSortOn :: Ord b => (a -> b) -> [a] -> [a]

-- | A version of <a>maximum</a> where the comparison is done on some
--   extracted value. Raises an error if the list is empty. Only calls the
--   function once per element.
--   
--   <pre>
--   maximumOn id [] == undefined
--   maximumOn length ["test","extra","a"] == "extra"
--   </pre>
maximumOn :: (Partial, Ord b) => (a -> b) -> [a] -> a

-- | A version of <a>minimum</a> where the comparison is done on some
--   extracted value. Raises an error if the list is empty. Only calls the
--   function once per element.
--   
--   <pre>
--   minimumOn id [] == undefined
--   minimumOn length ["test","extra","a"] == "a"
--   </pre>
minimumOn :: (Partial, Ord b) => (a -> b) -> [a] -> a

-- | A strict version of <a>sum</a>. Unlike <a>sum</a> this function is
--   always strict in the <a>Num</a> argument, whereas the standard version
--   is only strict if the optimiser kicks in.
--   
--   <pre>
--   sum' [1, 2, 3] == 6
--   </pre>
sum' :: Num a => [a] -> a

-- | A strict version of <a>product</a>.
--   
--   <pre>
--   product' [1, 2, 4] == 8
--   </pre>
product' :: Num a => [a] -> a

-- | A strict version of <a>sum</a>, using a custom valuation function.
--   
--   <pre>
--   sumOn' read ["1", "2", "3"] == 6
--   </pre>
sumOn' :: Num b => (a -> b) -> [a] -> b

-- | A strict version of <a>product</a>, using a custom valuation function.
--   
--   <pre>
--   productOn' read ["1", "2", "4"] == 8
--   </pre>
productOn' :: Num b => (a -> b) -> [a] -> b

-- | Are two lists disjoint, with no elements in common.
--   
--   <pre>
--   disjoint [1,2,3] [4,5] == True
--   disjoint [1,2,3] [4,1] == False
--   </pre>
disjoint :: Eq a => [a] -> [a] -> Bool

-- | <i>O((m+n) log m), m &lt;= n</i>. Are two lists disjoint, with no
--   elements in common.
--   
--   <tt>disjointOrd</tt> is more strict than <a>disjoint</a>. For example,
--   <tt>disjointOrd</tt> cannot terminate if both lists are inifite, while
--   <a>disjoint</a> can.
--   
--   <pre>
--   disjointOrd [1,2,3] [4,5] == True
--   disjointOrd [1,2,3] [4,1] == False
--   </pre>
disjointOrd :: Ord a => [a] -> [a] -> Bool

-- | A version of <a>disjointOrd</a> with a custom predicate.
--   
--   <pre>
--   disjointOrdBy (compare `on` (`mod` 7)) [1,2,3] [4,5] == True
--   disjointOrdBy (compare `on` (`mod` 7)) [1,2,3] [4,8] == False
--   </pre>
disjointOrdBy :: (a -> a -> Ordering) -> [a] -> [a] -> Bool

-- | Are all elements the same.
--   
--   <pre>
--   allSame [1,1,2] == False
--   allSame [1,1,1] == True
--   allSame [1]     == True
--   allSame []      == True
--   allSame (1:1:2:undefined) == False
--   \xs -&gt; allSame xs == (length (nub xs) &lt;= 1)
--   </pre>
allSame :: Eq a => [a] -> Bool

-- | Is there any element which occurs more than once.
--   
--   <pre>
--   anySame [1,1,2] == True
--   anySame [1,2,3] == False
--   anySame (1:2:1:undefined) == True
--   anySame [] == False
--   \xs -&gt; anySame xs == (length (nub xs) &lt; length xs)
--   </pre>
anySame :: Eq a => [a] -> Bool

-- | Apply some operation repeatedly, producing an element of output and
--   the remainder of the list.
--   
--   <pre>
--   \xs -&gt; repeatedly (splitAt 3) xs  == chunksOf 3 xs
--   \xs -&gt; repeatedly word1 (trim xs) == words xs
--   \xs -&gt; repeatedly line1 xs == lines xs
--   </pre>
repeatedly :: ([a] -> (b, [a])) -> [a] -> [b]

-- | Find the first element of a list for which the operation returns
--   <a>Just</a>, along with the result of the operation. Like <a>find</a>
--   but useful where the function also computes some expensive information
--   that can be reused. Particular useful when the function is monadic,
--   see <tt>firstJustM</tt>.
--   
--   <pre>
--   firstJust id [Nothing,Just 3]  == Just 3
--   firstJust id [Nothing,Nothing] == Nothing
--   </pre>
firstJust :: (a -> Maybe b) -> [a] -> Maybe b

-- | A merging of <a>unzip</a> and <a>concat</a>.
--   
--   <pre>
--   concatUnzip [("a","AB"),("bc","C")] == ("abc","ABC")
--   </pre>
concatUnzip :: [([a], [b])] -> ([a], [b])

-- | A merging of <a>unzip3</a> and <a>concat</a>.
--   
--   <pre>
--   concatUnzip3 [("a","AB",""),("bc","C","123")] == ("abc","ABC","123")
--   </pre>
concatUnzip3 :: [([a], [b], [c])] -> ([a], [b], [c])

-- | <a>zip</a> against an enumeration. Truncates the output if the
--   enumeration runs out.
--   
--   <pre>
--   \i xs -&gt; zip [i..] xs == zipFrom i xs
--   zipFrom False [1..3] == [(False,1),(True, 2)]
--   </pre>
zipFrom :: Enum a => a -> [b] -> [(a, b)]

-- | <a>zipFrom</a> generalised to any combining operation. Truncates the
--   output if the enumeration runs out.
--   
--   <pre>
--   \i xs -&gt; zipWithFrom (,) i xs == zipFrom i xs
--   </pre>
zipWithFrom :: Enum a => (a -> b -> c) -> a -> [b] -> [c]

-- | Like <a>zipWith</a>, but keep going to the longest value. The function
--   argument will always be given at least one <a>Just</a>, and while both
--   lists have items, two <a>Just</a> values.
--   
--   <pre>
--   zipWithLongest (,) "a" "xyz" == [(Just 'a', Just 'x'), (Nothing, Just 'y'), (Nothing, Just 'z')]
--   zipWithLongest (,) "a" "x" == [(Just 'a', Just 'x')]
--   zipWithLongest (,) "" "x" == [(Nothing, Just 'x')]
--   </pre>
zipWithLongest :: (Maybe a -> Maybe b -> c) -> [a] -> [b] -> [c]

-- | Replace a subsequence everywhere it occurs. The first argument must
--   not be the empty list.
--   
--   <pre>
--   replace "el" "_" "Hello Bella" == "H_lo B_la"
--   replace "el" "e" "Hello"       == "Helo"
--   replace "" "e" "Hello"         == undefined
--   \xs ys -&gt; not (null xs) ==&gt; replace xs xs ys == ys
--   </pre>
replace :: (Partial, Eq a) => [a] -> [a] -> [a] -> [a]

-- | Merge two lists which are assumed to be ordered.
--   
--   <pre>
--   merge "ace" "bd" == "abcde"
--   \xs ys -&gt; merge (sort xs) (sort ys) == sort (xs ++ ys)
--   </pre>
merge :: Ord a => [a] -> [a] -> [a]

-- | Like <a>merge</a>, but with a custom ordering function.
mergeBy :: (a -> a -> Ordering) -> [a] -> [a] -> [a]
instance GHC.Show.Show a => GHC.Show.Show (Data.List.Extra.RB a)


-- | This module extends <a>Data.Version</a> with extra utilities. The
--   package also exports the existing <a>Data.Version</a> functions.
module Data.Version.Extra

-- | Read a <a>Version</a> or throw an exception.
--   
--   <pre>
--   \x -&gt; readVersion (showVersion x) == x
--   readVersion "hello" == undefined
--   </pre>
readVersion :: Partial => String -> Version


-- | Extra functions for working with <a>NonEmpty</a> lists. The package
--   also exports the existing <a>Data.List.NonEmpty</a> functions.
module Data.List.NonEmpty.Extra

-- | <i>O(n)</i>. Append an element to a list.
--   
--   <pre>
--   [1,2,3] |: 4 |&gt; 5 == 1 :| [2,3,4,5]
--   </pre>
(|:) :: [a] -> a -> NonEmpty a
infixl 5 |:

-- | <i>O(n)</i>. Append an element to a non-empty list.
--   
--   <pre>
--   (1 :| [2,3]) |&gt; 4 |&gt; 5 == 1 :| [2,3,4,5]
--   </pre>
(|>) :: NonEmpty a -> a -> NonEmpty a
infixl 5 |>

-- | Synonym for <a>|&gt;</a>.
snoc :: NonEmpty a -> a -> NonEmpty a

-- | A total variant of the list index function <a>(!?)</a>.
--   
--   <pre>
--   (2 :| [3,4]) !? 1    == Just 3
--   (2 :| [3,4]) !? (-1) == Nothing
--   (1 :| [])    !? 1    == Nothing
--   </pre>
(!?) :: NonEmpty a -> Int -> Maybe a
infixl 9 !?

-- | Append a list to a non-empty list.
--   
--   <pre>
--   appendl (1 :| [2,3]) [4,5] == 1 :| [2,3,4,5]
--   </pre>
appendl :: NonEmpty a -> [a] -> NonEmpty a

-- | Append a non-empty list to a list.
--   
--   <pre>
--   appendr [1,2,3] (4 :| [5]) == 1 :| [2,3,4,5]
--   </pre>
appendr :: [a] -> NonEmpty a -> NonEmpty a

-- | Sort by comparing the results of a function applied to each element.
--   The sort is stable, and the function is evaluated only once for each
--   element.
sortOn :: Ord b => (a -> b) -> NonEmpty a -> NonEmpty a

-- | Return the union of two non-empty lists. Duplicates, and elements of
--   the first list, are removed from the the second list, but if the first
--   list contains duplicates, so will the result.
--   
--   <pre>
--   (1 :| [3, 5, 3]) `union` (4 :| [5, 3, 5, 2]) == 1 :| [3, 5, 3, 4, 2]
--   </pre>
union :: Eq a => NonEmpty a -> NonEmpty a -> NonEmpty a

-- | The non-overloaded version of <a>union</a>.
unionBy :: (a -> a -> Bool) -> NonEmpty a -> NonEmpty a -> NonEmpty a

-- | <tt>nubOrd</tt> for <a>NonEmpty</a>. Behaves the same as
--   <a>nubOrd</a>.
--   
--   <pre>
--   Data.List.NonEmpty.Extra.nubOrd (1 :| [2, 3, 3, 4, 1, 2]) == 1 :| [2, 3, 4]
--   \xs -&gt; Data.List.NonEmpty.Extra.nubOrd xs == Data.List.NonEmpty.Extra.nub xs
--   </pre>
nubOrd :: Ord a => NonEmpty a -> NonEmpty a

-- | <tt>nubOrdBy</tt> for <a>NonEmpty</a>. Behaves the same as
--   <a>nubOrdBy</a>.
--   
--   <pre>
--   Data.List.NonEmpty.Extra.nubOrdBy (compare `on` Data.List.length) ("a" :| ["test","of","this"]) == "a" :| ["test","of"]
--   </pre>
nubOrdBy :: (a -> a -> Ordering) -> NonEmpty a -> NonEmpty a

-- | <tt>nubOrdOn</tt> for <a>NonEmpty</a>. Behaves the same as
--   <a>nubOrdOn</a>.
--   
--   <pre>
--   Data.List.NonEmpty.Extra.nubOrdOn Data.List.length ("a" :| ["test","of","this"]) == "a" :| ["test","of"]
--   </pre>
nubOrdOn :: Ord b => (a -> b) -> NonEmpty a -> NonEmpty a

-- | The largest element of a non-empty list.
maximum1 :: Ord a => NonEmpty a -> a

-- | The least element of a non-empty list.
minimum1 :: Ord a => NonEmpty a -> a

-- | The largest element of a non-empty list with respect to the given
--   comparison function.
maximumBy1 :: (a -> a -> Ordering) -> NonEmpty a -> a

-- | The least element of a non-empty list with respect to the given
--   comparison function.
minimumBy1 :: (a -> a -> Ordering) -> NonEmpty a -> a

-- | A version of <a>maximum1</a> where the comparison is done on some
--   extracted value.
maximumOn1 :: Ord b => (a -> b) -> NonEmpty a -> a

-- | A version of <a>minimum1</a> where the comparison is done on some
--   extracted value.
minimumOn1 :: Ord b => (a -> b) -> NonEmpty a -> a


-- | This module extends <a>Data.Either</a> with extra operations,
--   particularly to quickly extract from inside an <a>Either</a>. Some of
--   these operations are partial, and should be used with care in
--   production-quality code.
--   
--   If you need more <a>Either</a> functions see the <a>either</a>.
module Data.Either.Extra

-- | Return the contents of a <a>Left</a>-value or a default value
--   otherwise.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; fromLeft 1 (Left 3)
--   3
--   
--   &gt;&gt;&gt; fromLeft 1 (Right "foo")
--   1
--   </pre>
fromLeft :: a -> Either a b -> a

-- | Return the contents of a <a>Right</a>-value or a default value
--   otherwise.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; fromRight 1 (Right 3)
--   3
--   
--   &gt;&gt;&gt; fromRight 1 (Left "foo")
--   1
--   </pre>
fromRight :: b -> Either a b -> b

-- | Pull the value out of an <a>Either</a> where both alternatives have
--   the same type.
--   
--   <pre>
--   \x -&gt; fromEither (Left x ) == x
--   \x -&gt; fromEither (Right x) == x
--   </pre>
fromEither :: Either a a -> a

-- | The <a>fromLeft'</a> function extracts the element out of a
--   <a>Left</a> and throws an error if its argument is <a>Right</a>. Much
--   like <tt>fromJust</tt>, using this function in polished code is
--   usually a bad idea.
--   
--   <pre>
--   \x -&gt; fromLeft' (Left  x) == x
--   \x -&gt; fromLeft' (Right x) == undefined
--   </pre>
fromLeft' :: Partial => Either l r -> l

-- | The <a>fromRight'</a> function extracts the element out of a
--   <a>Right</a> and throws an error if its argument is <a>Left</a>. Much
--   like <tt>fromJust</tt>, using this function in polished code is
--   usually a bad idea.
--   
--   <pre>
--   \x -&gt; fromRight' (Right x) == x
--   \x -&gt; fromRight' (Left  x) == undefined
--   </pre>
fromRight' :: Partial => Either l r -> r

-- | Given an <a>Either</a>, convert it to a <a>Maybe</a>, where
--   <a>Left</a> becomes <a>Nothing</a>.
--   
--   <pre>
--   \x -&gt; eitherToMaybe (Left x) == Nothing
--   \x -&gt; eitherToMaybe (Right x) == Just x
--   </pre>
eitherToMaybe :: Either a b -> Maybe b

-- | Given a <a>Maybe</a>, convert it to an <a>Either</a>, providing a
--   suitable value for the <a>Left</a> should the value be <a>Nothing</a>.
--   
--   <pre>
--   \a b -&gt; maybeToEither a (Just b) == Right b
--   \a -&gt; maybeToEither a Nothing == Left a
--   </pre>
maybeToEither :: a -> Maybe b -> Either a b

-- | The <a>mapLeft</a> function takes a function and applies it to an
--   Either value iff the value takes the form <tt><a>Left</a> _</tt>.
--   
--   <pre>
--   mapLeft show (Left 1) == Left "1"
--   mapLeft show (Right True) == Right True
--   </pre>
mapLeft :: (a -> c) -> Either a b -> Either c b

-- | The <a>mapRight</a> function takes a function and applies it to an
--   Either value iff the value takes the form <tt><a>Right</a> _</tt>.
--   
--   <pre>
--   mapRight show (Left 1) == Left 1
--   mapRight show (Right True) == Right "True"
--   </pre>
mapRight :: (b -> c) -> Either a b -> Either a c


-- | Extra functions for <a>Control.Exception</a>. These functions provide
--   retrying, showing in the presence of exceptions, and functions to
--   catch/ignore exceptions, including monomorphic (no <a>Exception</a>
--   context) versions.
--   
--   If you want to use a safer set of exceptions see the
--   <a>safe-exceptions</a> package.
module Control.Exception.Extra

-- | A constraint which documents that a function is partial, and on GHC
--   8.0 and above produces a stack trace on failure. For example:
--   
--   <pre>
--   myHead :: <a>Partial</a> =&gt; [a] -&gt; a
--   myHead [] = error "bad"
--   myHead (x:xs) = x
--   </pre>
--   
--   When using <a>Partial</a> with GHC 7.8 or below you need to enable the
--   language feature <tt>ConstraintKinds</tt>, e.g. <tt>{-# LANGUAGE
--   ConstraintKinds #-}</tt> at the top of the file.
type Partial = HasCallStack

-- | Retry an operation at most <i>n</i> times (<i>n</i> must be positive).
--   If the operation fails the <i>n</i>th time it will throw that final
--   exception.
--   
--   <pre>
--   retry 1 (print "x")  == print "x"
--   retry 3 (fail "die") == fail "die"
--   </pre>
retry :: Int -> IO a -> IO a

-- | Retry an operation at most <i>n</i> times (<i>n</i> must be positive),
--   while the exception value and type match a predicate. If the operation
--   fails the <i>n</i>th time it will throw that final exception.
retryBool :: Exception e => (e -> Bool) -> Int -> IO a -> IO a

-- | A variant of <a>error</a> that does not produce a stack trace.
errorWithoutStackTrace :: forall (r :: RuntimeRep) (a :: TYPE r). [Char] -> a

-- | Show a value, but if the result contains exceptions, produce
--   <tt>&lt;Exception&gt;</tt>. Defined as <tt><a>stringException</a> .
--   show</tt>. Particularly useful for printing exceptions to users,
--   remembering that exceptions can themselves contain undefined values.
showException :: Show e => e -> IO String

-- | Fully evaluate an input String. If the String contains embedded
--   exceptions it will produce <tt>&lt;Exception&gt;</tt>.
--   
--   <pre>
--   stringException "test"                           == pure "test"
--   stringException ("test" ++ undefined)            == pure "test&lt;Exception&gt;"
--   stringException ("test" ++ undefined ++ "hello") == pure "test&lt;Exception&gt;"
--   stringException ['t','e','s','t',undefined]      == pure "test&lt;Exception&gt;"
--   </pre>
stringException :: String -> IO String

-- | An <a>IO</a> action that when evaluated calls <a>error</a>, in the
--   <a>IO</a> monad. Note that while <a>fail</a> in <a>IO</a> raises an
--   <a>IOException</a>, this function raises an <a>ErrorCall</a> exception
--   with a call stack.
--   
--   <pre>
--   catch (errorIO "Hello") (\(ErrorCall x) -&gt; pure x) == pure "Hello"
--   seq (errorIO "foo") (print 1) == print 1
--   </pre>
errorIO :: Partial => String -> IO a

-- | An <a>IO</a> action that when evaluated calls <a>assert</a> in the
--   <a>IO</a> monad, which throws an <a>AssertionFailed</a> exception if
--   the argument is <a>False</a>. With optimizations enabled (and
--   <tt>-fgnore-asserts</tt>) this function ignores its argument and does
--   nothing.
--   
--   <pre>
--   catch (assertIO True  &gt;&gt; pure 1) (\(x :: AssertionFailed) -&gt; pure 2) == pure 1
--   seq (assertIO False) (print 1) == print 1
--   </pre>
assertIO :: Partial => Bool -> IO ()

-- | Ignore any exceptions thrown by the action.
--   
--   <pre>
--   ignore (print 1)    == print 1
--   ignore (fail "die") == pure ()
--   </pre>
ignore :: IO () -> IO ()

-- | A version of <a>catch</a> without the <a>Exception</a> context,
--   restricted to <a>SomeException</a>, so catches all exceptions.
catch_ :: IO a -> (SomeException -> IO a) -> IO a

-- | Like <a>catch_</a> but for <a>handle</a>
handle_ :: (SomeException -> IO a) -> IO a -> IO a

-- | Like <a>catch_</a> but for <a>try</a>
try_ :: IO a -> IO (Either SomeException a)

-- | Like <a>catch_</a> but for <a>catchJust</a>
catchJust_ :: (SomeException -> Maybe b) -> IO a -> (b -> IO a) -> IO a

-- | Like <a>catch_</a> but for <a>handleJust</a>
handleJust_ :: (SomeException -> Maybe b) -> (b -> IO a) -> IO a -> IO a

-- | Like <a>catch_</a> but for <a>tryJust</a>
tryJust_ :: (SomeException -> Maybe b) -> IO a -> IO (Either b a)

-- | Catch an exception if the predicate passes, then call the handler with
--   the original exception. As an example:
--   
--   <pre>
--   readFileExists x == catchBool isDoesNotExistError (readFile "myfile") (const $ pure "")
--   </pre>
catchBool :: Exception e => (e -> Bool) -> IO a -> (e -> IO a) -> IO a

-- | Like <a>catchBool</a> but for <a>handle</a>.
handleBool :: Exception e => (e -> Bool) -> (e -> IO a) -> IO a -> IO a

-- | Like <a>catchBool</a> but for <a>try</a>.
tryBool :: Exception e => (e -> Bool) -> IO a -> IO (Either e a)


-- | Extra functions for <a>Control.Monad</a>. These functions provide
--   looping, list operations and booleans. If you need a wider selection
--   of monad loops and list generalisations, see <a>monad-loops</a>.
module Control.Monad.Extra

-- | Perform some operation on <a>Just</a>, given the field inside the
--   <a>Just</a>.
--   
--   <pre>
--   whenJust Nothing  print == pure ()
--   whenJust (Just 1) print == print 1
--   </pre>
whenJust :: Applicative m => Maybe a -> (a -> m ()) -> m ()

-- | Like <a>whenJust</a>, but where the test can be monadic.
whenJustM :: Monad m => m (Maybe a) -> (a -> m ()) -> m ()

-- | Return either a <a>pure</a> value if a condition is <a>True</a>,
--   otherwise <a>empty</a>.
--   
--   <pre>
--   pureIf @Maybe True  5 == Just 5
--   pureIf @Maybe False 5 == Nothing
--   pureIf @[]    True  5 == [5]
--   pureIf @[]    False 5 == []
--   </pre>
pureIf :: Alternative m => Bool -> a -> m a

-- | Like <a>when</a>, but return either <a>Nothing</a> if the predicate
--   was <a>False</a>, of <a>Just</a> with the result of the computation.
--   
--   <pre>
--   whenMaybe True  (print 1) == fmap Just (print 1)
--   whenMaybe False (print 1) == pure Nothing
--   </pre>
whenMaybe :: Applicative m => Bool -> m a -> m (Maybe a)

-- | Like <a>whenMaybe</a>, but where the test can be monadic.
whenMaybeM :: Monad m => m Bool -> m a -> m (Maybe a)

-- | The identity function which requires the inner argument to be
--   <tt>()</tt>. Useful for functions with overloaded return types.
--   
--   <pre>
--   \(x :: Maybe ()) -&gt; unit x == x
--   </pre>
unit :: m () -> m ()

-- | Monadic generalisation of <a>maybe</a>.
maybeM :: Monad m => m b -> (a -> m b) -> m (Maybe a) -> m b

-- | Monadic generalisation of <a>fromMaybe</a>.
fromMaybeM :: Monad m => m a -> m (Maybe a) -> m a

-- | Monadic generalisation of <a>either</a>.
eitherM :: Monad m => (a -> m c) -> (b -> m c) -> m (Either a b) -> m c

-- | A looping operation, where the predicate returns <a>Left</a> as a seed
--   for the next loop or <a>Right</a> to abort the loop.
--   
--   <pre>
--   loop (\x -&gt; if x &lt; 10 then Left $ x * 2 else Right $ show x) 1 == "16"
--   </pre>
loop :: (a -> Either a b) -> a -> b

-- | A monadic version of <a>loop</a>, where the predicate returns
--   <a>Left</a> as a seed for the next loop or <a>Right</a> to abort the
--   loop.
loopM :: Monad m => (a -> m (Either a b)) -> a -> m b

-- | Keep running an operation until it becomes <a>False</a>. As an
--   example:
--   
--   <pre>
--   whileM $ do sleep 0.1; notM $ doesFileExist "foo.txt"
--   readFile "foo.txt"
--   </pre>
--   
--   If you need some state persisted between each test, use <a>loopM</a>.
whileM :: Monad m => m Bool -> m ()

-- | Keep running an operation until it becomes a <a>Nothing</a>,
--   accumulating the monoid results inside the <a>Just</a>s as the result
--   of the overall loop.
whileJustM :: (Monad m, Monoid a) => m (Maybe a) -> m a

-- | Keep running an operation until it becomes a <a>Just</a>, then return
--   the value inside the <a>Just</a> as the result of the overall loop.
untilJustM :: Monad m => m (Maybe a) -> m a

-- | A version of <tt>partition</tt> that works with a monadic predicate.
--   
--   <pre>
--   partitionM (Just . even) [1,2,3] == Just ([2], [1,3])
--   partitionM (const Nothing) [1,2,3] == Nothing
--   </pre>
partitionM :: Monad m => (a -> m Bool) -> [a] -> m ([a], [a])

-- | A version of <a>concatMap</a> that works with a monadic predicate.
concatMapM :: Monad m => (a -> m [b]) -> [a] -> m [b]

-- | Like <a>concatMapM</a>, but has its arguments flipped, so can be used
--   instead of the common <tt>fmap concat $ forM</tt> pattern.
concatForM :: Monad m => [a] -> (a -> m [b]) -> m [b]

-- | A version of <tt>mconcatMap</tt> that works with a monadic predicate.
mconcatMapM :: (Monad m, Monoid b) => (a -> m b) -> [a] -> m b

-- | A version of <a>mapMaybe</a> that works with a monadic predicate.
mapMaybeM :: Monad m => (a -> m (Maybe b)) -> [a] -> m [b]

-- | Like <tt>find</tt>, but where the test can be monadic.
--   
--   <pre>
--   findM (Just . isUpper) "teST"             == Just (Just 'S')
--   findM (Just . isUpper) "test"             == Just Nothing
--   findM (Just . const True) ["x",undefined] == Just (Just "x")
--   </pre>
findM :: Monad m => (a -> m Bool) -> [a] -> m (Maybe a)

-- | Like <a>findM</a>, but also allows you to compute some additional
--   information in the predicate.
firstJustM :: Monad m => (a -> m (Maybe b)) -> [a] -> m (Maybe b)

-- | A variant of <a>foldM</a> that has no base case, and thus may only be
--   applied to non-empty lists.
--   
--   <pre>
--   fold1M (\x y -&gt; Just x) [] == undefined
--   fold1M (\x y -&gt; Just $ x + y) [1, 2, 3] == Just 6
--   </pre>
fold1M :: (Partial, Monad m) => (a -> a -> m a) -> [a] -> m a

-- | Like <a>fold1M</a> but discards the result.
fold1M_ :: (Partial, Monad m) => (a -> a -> m a) -> [a] -> m ()

-- | Like <a>when</a>, but where the test can be monadic.
whenM :: Monad m => m Bool -> m () -> m ()

-- | Like <a>unless</a>, but where the test can be monadic.
unlessM :: Monad m => m Bool -> m () -> m ()

-- | Like <tt>if</tt>, but where the test can be monadic.
ifM :: Monad m => m Bool -> m a -> m a -> m a

-- | Like <a>not</a>, but where the test can be monadic.
notM :: Functor m => m Bool -> m Bool

-- | The lazy <a>||</a> operator lifted to a monad. If the first argument
--   evaluates to <a>True</a> the second argument will not be evaluated.
--   
--   <pre>
--   Just True  ||^ undefined  == Just True
--   Just False ||^ Just True  == Just True
--   Just False ||^ Just False == Just False
--   </pre>
(||^) :: Monad m => m Bool -> m Bool -> m Bool

-- | The lazy <a>&amp;&amp;</a> operator lifted to a monad. If the first
--   argument evaluates to <a>False</a> the second argument will not be
--   evaluated.
--   
--   <pre>
--   Just False &amp;&amp;^ undefined  == Just False
--   Just True  &amp;&amp;^ Just True  == Just True
--   Just True  &amp;&amp;^ Just False == Just False
--   </pre>
(&&^) :: Monad m => m Bool -> m Bool -> m Bool

-- | A version of <a>or</a> lifted to a monad. Retains the short-circuiting
--   behaviour.
--   
--   <pre>
--   orM [Just False,Just True ,undefined] == Just True
--   orM [Just False,Just False,undefined] == undefined
--   \xs -&gt; Just (or xs) == orM (map Just xs)
--   </pre>
orM :: Monad m => [m Bool] -> m Bool

-- | A version of <a>and</a> lifted to a monad. Retains the
--   short-circuiting behaviour.
--   
--   <pre>
--   andM [Just True,Just False,undefined] == Just False
--   andM [Just True,Just True ,undefined] == undefined
--   \xs -&gt; Just (and xs) == andM (map Just xs)
--   </pre>
andM :: Monad m => [m Bool] -> m Bool

-- | A version of <a>any</a> lifted to a monad. Retains the
--   short-circuiting behaviour.
--   
--   <pre>
--   anyM Just [False,True ,undefined] == Just True
--   anyM Just [False,False,undefined] == undefined
--   \(f :: Int -&gt; Maybe Bool) xs -&gt; anyM f xs == orM (map f xs)
--   </pre>
anyM :: Monad m => (a -> m Bool) -> [a] -> m Bool

-- | A version of <a>all</a> lifted to a monad. Retains the
--   short-circuiting behaviour.
--   
--   <pre>
--   allM Just [True,False,undefined] == Just False
--   allM Just [True,True ,undefined] == undefined
--   \(f :: Int -&gt; Maybe Bool) xs -&gt; anyM f xs == orM (map f xs)
--   </pre>
allM :: Monad m => (a -> m Bool) -> [a] -> m Bool

module Data.Foldable.Extra

-- | A generalization of <a>sum'</a> to <a>Foldable</a> instances.
sum' :: (Foldable f, Num a) => f a -> a

-- | A generalization of <a>product'</a> to <a>Foldable</a> instances.
product' :: (Foldable f, Num a) => f a -> a

-- | A generalization of <a>sumOn'</a> to <a>Foldable</a> instances.
sumOn' :: (Foldable f, Num b) => (a -> b) -> f a -> b

-- | A generalization of <a>productOn'</a> to <a>Foldable</a> instances.
productOn' :: (Foldable f, Num b) => (a -> b) -> f a -> b

-- | A generalization of <a>anyM</a> to <a>Foldable</a> instances. Retains
--   the short-circuiting behaviour.
anyM :: (Foldable f, Monad m) => (a -> m Bool) -> f a -> m Bool

-- | A generalization of <a>allM</a> to <a>Foldable</a> instances. Retains
--   the short-circuiting behaviour.
allM :: (Foldable f, Monad m) => (a -> m Bool) -> f a -> m Bool

-- | A generalization of <a>orM</a> to <a>Foldable</a> instances. Retains
--   the short-circuiting behaviour.
orM :: (Foldable f, Monad m) => f (m Bool) -> m Bool

-- | A generalization of <a>andM</a> to <a>Foldable</a> instances. Retains
--   the short-circuiting behaviour.
andM :: (Foldable f, Monad m) => f (m Bool) -> m Bool

-- | A generalization of <a>findM</a> to <a>Foldable</a> instances.
findM :: (Foldable f, Monad m) => (a -> m Bool) -> f a -> m (Maybe a)

-- | A generalization of <a>firstJustM</a> to <a>Foldable</a> instances.
firstJustM :: (Foldable f, Monad m) => (a -> m (Maybe b)) -> f a -> m (Maybe b)


-- | Extra functions for <a>Control.Concurrent</a>.
--   
--   This module includes three new types of <a>MVar</a>, namely
--   <a>Lock</a> (no associated value), <a>Var</a> (never empty) and
--   <a>Barrier</a> (filled at most once). See <a>this blog post</a> for
--   examples and justification.
--   
--   If you need greater control of exceptions and threads see the
--   <a>slave-thread</a> package. If you need elaborate relationships
--   between threads see the <a>async</a> package.
module Control.Concurrent.Extra

-- | On GHC 7.6 and above with the <tt>-threaded</tt> flag, brackets a call
--   to <a>setNumCapabilities</a>. On lower versions (which lack
--   <a>setNumCapabilities</a>) this function just runs the argument
--   action.
withNumCapabilities :: Int -> IO a -> IO a

-- | Given an action, produce a wrapped action that runs at most once. If
--   the function raises an exception, the same exception will be reraised
--   each time.
--   
--   <pre>
--   let x ||| y = do t1 &lt;- onceFork x; t2 &lt;- onceFork y; t1; t2
--   \(x :: IO Int) -&gt; void (once x) == pure ()
--   \(x :: IO Int) -&gt; join (once x) == x
--   \(x :: IO Int) -&gt; (do y &lt;- once x; y; y) == x
--   \(x :: IO Int) -&gt; (do y &lt;- once x; y ||| y) == x
--   </pre>
once :: IO a -> IO (IO a)

-- | Like <a>once</a>, but immediately starts running the computation on a
--   background thread.
--   
--   <pre>
--   \(x :: IO Int) -&gt; join (onceFork x) == x
--   \(x :: IO Int) -&gt; (do a &lt;- onceFork x; a; a) == x
--   </pre>
onceFork :: IO a -> IO (IO a)

-- | Like an <a>MVar</a>, but has no value. Used to guarantee
--   single-threaded access, typically to some system resource. As an
--   example:
--   
--   <pre>
--   lock &lt;- <a>newLock</a>
--   let output = <a>withLock</a> lock . putStrLn
--   forkIO $ do ...; output "hello"
--   forkIO $ do ...; output "world"
--   </pre>
--   
--   Here we are creating a lock to ensure that when writing output our
--   messages do not get interleaved. This use of <a>MVar</a> never blocks
--   on a put. It is permissible, but rare, that a withLock contains a
--   withLock inside it - but if so, watch out for deadlocks.
data Lock

-- | Create a new <a>Lock</a>.
newLock :: IO Lock

-- | Perform some operation while holding <a>Lock</a>. Will prevent all
--   other operations from using the <a>Lock</a> while the action is
--   ongoing.
withLock :: Lock -> IO a -> IO a

-- | Like <a>withLock</a> but will never block. If the operation cannot be
--   executed immediately it will return <a>Nothing</a>.
withLockTry :: Lock -> IO a -> IO (Maybe a)

-- | Like an <a>MVar</a>, but must always be full. Used to operate on a
--   mutable variable in a thread-safe way. As an example:
--   
--   <pre>
--   hits &lt;- <a>newVar</a> 0
--   forkIO $ do ...; <a>modifyVar_</a> hits (+1); ...
--   i &lt;- <a>readVar</a> hits
--   print ("HITS",i)
--   </pre>
--   
--   Here we have a variable which we modify atomically, so modifications
--   are not interleaved. This use of <a>MVar</a> never blocks on a put. No
--   modifyVar operation should ever block, and they should always complete
--   in a reasonable timeframe. A <a>Var</a> should not be used to protect
--   some external resource, only the variable contained within.
--   Information from a <a>readVar</a> should not be subsequently inserted
--   back into the <a>Var</a>.
data Var a

-- | Create a new <a>Var</a> with a value.
newVar :: a -> IO (Var a)

-- | Read the current value of the <a>Var</a>.
readVar :: Var a -> IO a

-- | Write a value to become the new value of <a>Var</a>.
writeVar :: Var a -> a -> IO ()

-- | Strict variant of <a>writeVar</a>
writeVar' :: Var a -> a -> IO ()

-- | Modify a <a>Var</a> producing a new value and a return result.
modifyVar :: Var a -> (a -> IO (a, b)) -> IO b

-- | Strict variant of <a>modifyVar'</a>
modifyVar' :: Var a -> (a -> IO (a, b)) -> IO b

-- | Modify a <a>Var</a>, a restricted version of <a>modifyVar</a>.
modifyVar_ :: Var a -> (a -> IO a) -> IO ()

-- | Strict variant of <a>modifyVar_</a>
modifyVar_' :: Var a -> (a -> IO a) -> IO ()

-- | Perform some operation using the value in the <a>Var</a>, a restricted
--   version of <a>modifyVar</a>.
withVar :: Var a -> (a -> IO b) -> IO b

-- | Starts out empty, then is filled exactly once. As an example:
--   
--   <pre>
--   bar &lt;- <a>newBarrier</a>
--   forkIO $ do ...; val &lt;- ...; <a>signalBarrier</a> bar val
--   print =&lt;&lt; <a>waitBarrier</a> bar
--   </pre>
--   
--   Here we create a barrier which will contain some computed value. A
--   thread is forked to fill the barrier, while the main thread waits for
--   it to complete. A barrier has similarities to a future or promise from
--   other languages, has been known as an IVar in other Haskell work, and
--   in some ways is like a manually managed thunk.
data Barrier a

-- | Create a new <a>Barrier</a>.
newBarrier :: IO (Barrier a)

-- | Write a value into the Barrier, releasing anyone at
--   <a>waitBarrier</a>. Any subsequent attempts to signal the
--   <a>Barrier</a> will throw an exception.
signalBarrier :: Partial => Barrier a -> a -> IO ()

-- | Wait until a barrier has been signaled with <a>signalBarrier</a>.
waitBarrier :: Barrier a -> IO a

-- | A version of <a>waitBarrier</a> that never blocks, returning
--   <a>Nothing</a> if the barrier has not yet been signaled.
waitBarrierMaybe :: Barrier a -> IO (Maybe a)


-- | Extra directory functions. Most of these functions provide cleaned up
--   and generalised versions of <a>getDirectoryContents</a>, see
--   <a>listContents</a> for the differences.
module System.Directory.Extra

-- | Create a directory with permissions so that only the current user can
--   view it. On Windows this function is equivalent to
--   <a>createDirectory</a>.
createDirectoryPrivate :: String -> IO ()

-- | List the files and directories directly within a directory. Each
--   result will be prefixed by the query directory, and the special
--   directories <tt>.</tt> and <tt>..</tt> will be ignored. Intended as a
--   cleaned up version of <a>getDirectoryContents</a>.
--   
--   <pre>
--   withTempDir $ \dir -&gt; do writeFile (dir &lt;/&gt; "test.txt") ""; (== [dir &lt;/&gt; "test.txt"]) &lt;$&gt; listContents dir
--   let touch = mapM_ $ \x -&gt; createDirectoryIfMissing True (takeDirectory x) &gt;&gt; writeFile x ""
--   let listTest op as bs = withTempDir $ \dir -&gt; do touch $ map (dir &lt;/&gt;) as; res &lt;- op dir; pure $ map (drop (length dir + 1)) res == bs
--   listTest listContents ["bar.txt","foo/baz.txt","zoo"] ["bar.txt","foo","zoo"]
--   </pre>
listContents :: FilePath -> IO [FilePath]

-- | Like <a>listContents</a>, but only returns the directories in a
--   directory, not the files. Each directory will be prefixed by the query
--   directory.
--   
--   <pre>
--   listTest listDirectories ["bar.txt","foo/baz.txt","zoo"] ["foo"]
--   </pre>
listDirectories :: FilePath -> IO [FilePath]

-- | Like <a>listContents</a>, but only returns the files in a directory,
--   not other directories. Each file will be prefixed by the query
--   directory.
--   
--   <pre>
--   listTest listFiles ["bar.txt","foo/baz.txt","zoo"] ["bar.txt","zoo"]
--   </pre>
listFiles :: FilePath -> IO [FilePath]

-- | Like <a>listFilesRecursive</a>, but with a predicate to decide where
--   to recurse into. Typically directories starting with <tt>.</tt> would
--   be ignored. The initial argument directory will have the test applied
--   to it.
--   
--   <pre>
--   listTest (listFilesInside $ pure . not . isPrefixOf "." . takeFileName)
--       ["bar.txt","foo" &lt;/&gt; "baz.txt",".foo" &lt;/&gt; "baz2.txt", "zoo"] ["bar.txt","zoo","foo" &lt;/&gt; "baz.txt"]
--   listTest (listFilesInside $ const $ pure False) ["bar.txt"] []
--   </pre>
listFilesInside :: (FilePath -> IO Bool) -> FilePath -> IO [FilePath]

-- | Like <a>listFiles</a>, but goes recursively through all
--   subdirectories. This function will follow symlinks, and if they form a
--   loop, this function will not terminate.
--   
--   <pre>
--   listTest listFilesRecursive ["bar.txt","zoo","foo" &lt;/&gt; "baz.txt"] ["bar.txt","zoo","foo" &lt;/&gt; "baz.txt"]
--   </pre>
listFilesRecursive :: FilePath -> IO [FilePath]


-- | Extra functions for <a>System.Environment</a>.
--   
--   Currently this module has no functionality beyond
--   <a>System.Environment</a>.

-- | <i>Deprecated: Use System.Environment directly</i>
module System.Environment.Extra


-- | More IO functions. The functions include ones for reading files with
--   specific encodings, strictly reading files, and writing files with
--   encodings. There are also some simple temporary file functions, more
--   advanced alternatives can be found in the <a>exceptions</a> package.
module System.IO.Extra

-- | Capture the <a>stdout</a> and <a>stderr</a> of a computation.
--   
--   <pre>
--   captureOutput (print 1) == pure ("1\n",())
--   </pre>
captureOutput :: IO a -> IO (String, a)

-- | Execute an action with a custom <a>BufferMode</a>, a wrapper around
--   <a>hSetBuffering</a>.
withBuffering :: Handle -> BufferMode -> IO a -> IO a

-- | Like <a>readFile</a>, but setting an encoding.
readFileEncoding :: TextEncoding -> FilePath -> IO String

-- | Like <a>readFile</a>, but with the encoding <a>utf8</a>.
readFileUTF8 :: FilePath -> IO String

-- | Like <a>readFile</a>, but for binary files.
readFileBinary :: FilePath -> IO String

-- | A strict version of <a>readFile</a>. When the string is produced, the
--   entire file will have been read into memory and the file handle will
--   have been closed. Closing the file handle does not rely on the garbage
--   collector.
--   
--   <pre>
--   \(filter isHexDigit -&gt; s) -&gt; fmap (== s) $ withTempFile $ \file -&gt; do writeFile file s; readFile' file
--   </pre>
readFile' :: FilePath -> IO String

-- | A strict version of <a>readFileEncoding</a>, see <a>readFile'</a> for
--   details.
readFileEncoding' :: TextEncoding -> FilePath -> IO String

-- | A strict version of <a>readFileUTF8</a>, see <a>readFile'</a> for
--   details.
readFileUTF8' :: FilePath -> IO String

-- | A strict version of <a>readFileBinary</a>, see <a>readFile'</a> for
--   details.
readFileBinary' :: FilePath -> IO String

-- | Write a file with a particular encoding.
writeFileEncoding :: TextEncoding -> FilePath -> String -> IO ()

-- | Write a file with the <a>utf8</a> encoding.
--   
--   <pre>
--   \s -&gt; withTempFile $ \file -&gt; do writeFileUTF8 file s; fmap (== s) $ readFileUTF8' file
--   </pre>
writeFileUTF8 :: FilePath -> String -> IO ()

-- | Write a binary file.
--   
--   <pre>
--   \(ASCIIString s) -&gt; withTempFile $ \file -&gt; do writeFileBinary file s; fmap (== s) $ readFileBinary' file
--   </pre>
writeFileBinary :: FilePath -> String -> IO ()

-- | Create a temporary file in the temporary directory. The file will be
--   deleted after the action completes (provided the file is not still
--   open). The <a>FilePath</a> will not have any file extension, will
--   exist, and will be zero bytes long. If you require a file with a
--   specific name, use <a>withTempDir</a>.
--   
--   <pre>
--   withTempFile doesFileExist == pure True
--   (doesFileExist =&lt;&lt; withTempFile pure) == pure False
--   withTempFile readFile' == pure ""
--   </pre>
withTempFile :: (FilePath -> IO a) -> IO a

-- | Create a temporary directory inside the system temporary directory.
--   The directory will be deleted after the action completes.
--   
--   <pre>
--   withTempDir doesDirectoryExist == pure True
--   (doesDirectoryExist =&lt;&lt; withTempDir pure) == pure False
--   withTempDir listFiles == pure []
--   </pre>
withTempDir :: (FilePath -> IO a) -> IO a

-- | Provide a function to create a temporary file, and a way to delete a
--   temporary file. Most users should use <a>withTempFile</a> which
--   combines these operations.
newTempFile :: IO (FilePath, IO ())

-- | Provide a function to create a temporary directory, and a way to
--   delete a temporary directory. Most users should use <a>withTempDir</a>
--   which combines these operations.
newTempDir :: IO (FilePath, IO ())

-- | Like <a>newTempFile</a> but using a custom temporary directory.
newTempFileWithin :: FilePath -> IO (FilePath, IO ())

-- | Like <a>newTempDir</a> but using a custom temporary directory.
newTempDirWithin :: FilePath -> IO (FilePath, IO ())

-- | Returns <a>True</a> if both files have the same content. Raises an
--   error if either file is missing.
--   
--   <pre>
--   fileEq "does_not_exist1" "does_not_exist2" == undefined
--   fileEq "does_not_exist" "does_not_exist" == undefined
--   withTempFile $ \f1 -&gt; fileEq "does_not_exist" f1 == undefined
--   withTempFile $ \f1 -&gt; withTempFile $ \f2 -&gt; fileEq f1 f2
--   withTempFile $ \f1 -&gt; withTempFile $ \f2 -&gt; writeFile f1 "a" &gt;&gt; writeFile f2 "a" &gt;&gt; fileEq f1 f2
--   withTempFile $ \f1 -&gt; withTempFile $ \f2 -&gt; writeFile f1 "a" &gt;&gt; writeFile f2 "b" &gt;&gt; notM (fileEq f1 f2)
--   </pre>
fileEq :: FilePath -> FilePath -> IO Bool


-- | Extra functions for the current system info.
module System.Info.Extra

-- | Return <a>True</a> on Windows and <a>False</a> otherwise. A runtime
--   version of <tt>#ifdef minw32_HOST_OS</tt>. Equivalent to <tt>os ==
--   "mingw32"</tt>, but: more efficient; doesn't require typing an easily
--   mistypeable string; actually asks about your OS not a library; doesn't
--   bake in 32bit assumptions that are already false. &lt;/rant&gt;
--   
--   <pre>
--   isWindows == (os == "mingw32")
--   </pre>
isWindows :: Bool

-- | Return <a>True</a> on Mac OS X and <a>False</a> otherwise.
isMac :: Bool


-- | Extra functions for creating processes. Specifically variants that
--   automatically check the <a>ExitCode</a> and capture the <a>stdout</a>
--   / <a>stderr</a> handles.
module System.Process.Extra

-- | A version of <a>system</a> that throws an error if the <a>ExitCode</a>
--   is not <a>ExitSuccess</a>.
system_ :: Partial => String -> IO ()

-- | A version of <a>system</a> that also captures the output, both
--   <a>stdout</a> and <a>stderr</a>. Returns a pair of the <a>ExitCode</a>
--   and the output.
systemOutput :: String -> IO (ExitCode, String)

-- | A version of <a>system</a> that captures the output (both
--   <a>stdout</a> and <a>stderr</a>) and throws an error if the
--   <a>ExitCode</a> is not <a>ExitSuccess</a>.
systemOutput_ :: Partial => String -> IO String


-- | Extra functions for working with times. Unlike the other modules in
--   this package, there is no corresponding <tt>System.Time</tt> module.
--   This module enhances the functionality from <a>Data.Time.Clock</a>,
--   but in quite different ways.
--   
--   Throughout, time is measured in <a>Seconds</a>, which is a type alias
--   for <a>Double</a>.
module System.Time.Extra

-- | A type alias for seconds, which are stored as <a>Double</a>.
type Seconds = Double

-- | Sleep for a number of seconds.
--   
--   <pre>
--   fmap (round . fst) (duration $ sleep 1) == pure 1
--   </pre>
sleep :: Seconds -> IO ()

-- | A version of <a>timeout</a> that takes <a>Seconds</a> and never
--   overflows the bounds of an <a>Int</a>. In addition, the bug that
--   negative timeouts run for ever has been fixed.
--   
--   <pre>
--   timeout (-3) (print 1) == pure Nothing
--   timeout 0.1  (print 1) == fmap Just (print 1)
--   do (t, _) &lt;- duration $ timeout 0.1 $ sleep 1000; print t; pure $ t &lt; 1
--   timeout 0.1  (sleep 2 &gt;&gt; print 1) == pure Nothing
--   </pre>
timeout :: Seconds -> IO a -> IO (Maybe a)

-- | Show a number of seconds, typically a duration, in a suitable manner
--   with reasonable precision for a human.
--   
--   <pre>
--   showDuration 3.435   == "3.44s"
--   showDuration 623.8   == "10m24s"
--   showDuration 62003.8 == "17h13m"
--   showDuration 1e8     == "27777h47m"
--   </pre>
showDuration :: Seconds -> String

-- | Call once to start, then call repeatedly to get the elapsed time since
--   the first call. The time is guaranteed to be monotonic. This function
--   is robust to system time changes.
--   
--   <pre>
--   do f &lt;- offsetTime; xs &lt;- replicateM 10 f; pure $ xs == sort xs
--   </pre>
offsetTime :: IO (IO Seconds)

-- | A synonym for <a>offsetTime</a>.

-- | <i>Deprecated: Use <a>offsetTime</a> instead, which is guaranteed to
--   always increase.</i>
offsetTimeIncrease :: IO (IO Seconds)

-- | Record how long a computation takes in <a>Seconds</a>.
--   
--   <pre>
--   do (a,_) &lt;- duration $ sleep 1; pure $ a &gt;= 1 &amp;&amp; a &lt;= 1.5
--   </pre>
duration :: MonadIO m => m a -> m (Seconds, a)
instance GHC.Classes.Eq System.Time.Extra.Timeout
instance GHC.Show.Show System.Time.Extra.Timeout
instance GHC.Exception.Type.Exception System.Time.Extra.Timeout


-- | This module documents all the functions available in this package.
--   
--   Most users should import the specific modules (e.g.
--   <tt><a>Data.List.Extra</a></tt>), which also reexport their
--   non-<tt>Extra</tt> modules (e.g. <tt><a>Data.List</a></tt>).

-- | <i>Deprecated: This module is provided as documentation of all new
--   functions, you should import the more specific modules directly.</i>
module Extra

-- | On GHC 7.6 and above with the <tt>-threaded</tt> flag, brackets a call
--   to <a>setNumCapabilities</a>. On lower versions (which lack
--   <a>setNumCapabilities</a>) this function just runs the argument
--   action.
withNumCapabilities :: Int -> IO a -> IO a

-- | Given an action, produce a wrapped action that runs at most once. If
--   the function raises an exception, the same exception will be reraised
--   each time.
--   
--   <pre>
--   let x ||| y = do t1 &lt;- onceFork x; t2 &lt;- onceFork y; t1; t2
--   \(x :: IO Int) -&gt; void (once x) == pure ()
--   \(x :: IO Int) -&gt; join (once x) == x
--   \(x :: IO Int) -&gt; (do y &lt;- once x; y; y) == x
--   \(x :: IO Int) -&gt; (do y &lt;- once x; y ||| y) == x
--   </pre>
once :: IO a -> IO (IO a)

-- | Like <a>once</a>, but immediately starts running the computation on a
--   background thread.
--   
--   <pre>
--   \(x :: IO Int) -&gt; join (onceFork x) == x
--   \(x :: IO Int) -&gt; (do a &lt;- onceFork x; a; a) == x
--   </pre>
onceFork :: IO a -> IO (IO a)

-- | Like an <a>MVar</a>, but has no value. Used to guarantee
--   single-threaded access, typically to some system resource. As an
--   example:
--   
--   <pre>
--   lock &lt;- <a>newLock</a>
--   let output = <a>withLock</a> lock . putStrLn
--   forkIO $ do ...; output "hello"
--   forkIO $ do ...; output "world"
--   </pre>
--   
--   Here we are creating a lock to ensure that when writing output our
--   messages do not get interleaved. This use of <a>MVar</a> never blocks
--   on a put. It is permissible, but rare, that a withLock contains a
--   withLock inside it - but if so, watch out for deadlocks.
data Lock

-- | Create a new <a>Lock</a>.
newLock :: IO Lock

-- | Perform some operation while holding <a>Lock</a>. Will prevent all
--   other operations from using the <a>Lock</a> while the action is
--   ongoing.
withLock :: Lock -> IO a -> IO a

-- | Like <a>withLock</a> but will never block. If the operation cannot be
--   executed immediately it will return <a>Nothing</a>.
withLockTry :: Lock -> IO a -> IO (Maybe a)

-- | Like an <a>MVar</a>, but must always be full. Used to operate on a
--   mutable variable in a thread-safe way. As an example:
--   
--   <pre>
--   hits &lt;- <a>newVar</a> 0
--   forkIO $ do ...; <a>modifyVar_</a> hits (+1); ...
--   i &lt;- <a>readVar</a> hits
--   print ("HITS",i)
--   </pre>
--   
--   Here we have a variable which we modify atomically, so modifications
--   are not interleaved. This use of <a>MVar</a> never blocks on a put. No
--   modifyVar operation should ever block, and they should always complete
--   in a reasonable timeframe. A <a>Var</a> should not be used to protect
--   some external resource, only the variable contained within.
--   Information from a <a>readVar</a> should not be subsequently inserted
--   back into the <a>Var</a>.
data Var a

-- | Create a new <a>Var</a> with a value.
newVar :: a -> IO (Var a)

-- | Read the current value of the <a>Var</a>.
readVar :: Var a -> IO a

-- | Write a value to become the new value of <a>Var</a>.
writeVar :: Var a -> a -> IO ()

-- | Strict variant of <a>writeVar</a>
writeVar' :: Var a -> a -> IO ()

-- | Modify a <a>Var</a> producing a new value and a return result.
modifyVar :: Var a -> (a -> IO (a, b)) -> IO b

-- | Strict variant of <a>modifyVar'</a>
modifyVar' :: Var a -> (a -> IO (a, b)) -> IO b

-- | Modify a <a>Var</a>, a restricted version of <a>modifyVar</a>.
modifyVar_ :: Var a -> (a -> IO a) -> IO ()

-- | Strict variant of <a>modifyVar_</a>
modifyVar_' :: Var a -> (a -> IO a) -> IO ()

-- | Perform some operation using the value in the <a>Var</a>, a restricted
--   version of <a>modifyVar</a>.
withVar :: Var a -> (a -> IO b) -> IO b

-- | Starts out empty, then is filled exactly once. As an example:
--   
--   <pre>
--   bar &lt;- <a>newBarrier</a>
--   forkIO $ do ...; val &lt;- ...; <a>signalBarrier</a> bar val
--   print =&lt;&lt; <a>waitBarrier</a> bar
--   </pre>
--   
--   Here we create a barrier which will contain some computed value. A
--   thread is forked to fill the barrier, while the main thread waits for
--   it to complete. A barrier has similarities to a future or promise from
--   other languages, has been known as an IVar in other Haskell work, and
--   in some ways is like a manually managed thunk.
data Barrier a

-- | Create a new <a>Barrier</a>.
newBarrier :: IO (Barrier a)

-- | Write a value into the Barrier, releasing anyone at
--   <a>waitBarrier</a>. Any subsequent attempts to signal the
--   <a>Barrier</a> will throw an exception.
signalBarrier :: Partial => Barrier a -> a -> IO ()

-- | Wait until a barrier has been signaled with <a>signalBarrier</a>.
waitBarrier :: Barrier a -> IO a

-- | A version of <a>waitBarrier</a> that never blocks, returning
--   <a>Nothing</a> if the barrier has not yet been signaled.
waitBarrierMaybe :: Barrier a -> IO (Maybe a)

-- | A constraint which documents that a function is partial, and on GHC
--   8.0 and above produces a stack trace on failure. For example:
--   
--   <pre>
--   myHead :: <a>Partial</a> =&gt; [a] -&gt; a
--   myHead [] = error "bad"
--   myHead (x:xs) = x
--   </pre>
--   
--   When using <a>Partial</a> with GHC 7.8 or below you need to enable the
--   language feature <tt>ConstraintKinds</tt>, e.g. <tt>{-# LANGUAGE
--   ConstraintKinds #-}</tt> at the top of the file.
type Partial = HasCallStack

-- | Retry an operation at most <i>n</i> times (<i>n</i> must be positive).
--   If the operation fails the <i>n</i>th time it will throw that final
--   exception.
--   
--   <pre>
--   retry 1 (print "x")  == print "x"
--   retry 3 (fail "die") == fail "die"
--   </pre>
retry :: Int -> IO a -> IO a

-- | Retry an operation at most <i>n</i> times (<i>n</i> must be positive),
--   while the exception value and type match a predicate. If the operation
--   fails the <i>n</i>th time it will throw that final exception.
retryBool :: Exception e => (e -> Bool) -> Int -> IO a -> IO a

-- | A variant of <a>error</a> that does not produce a stack trace.
errorWithoutStackTrace :: forall (r :: RuntimeRep) (a :: TYPE r). [Char] -> a

-- | Show a value, but if the result contains exceptions, produce
--   <tt>&lt;Exception&gt;</tt>. Defined as <tt><a>stringException</a> .
--   show</tt>. Particularly useful for printing exceptions to users,
--   remembering that exceptions can themselves contain undefined values.
showException :: Show e => e -> IO String

-- | Fully evaluate an input String. If the String contains embedded
--   exceptions it will produce <tt>&lt;Exception&gt;</tt>.
--   
--   <pre>
--   stringException "test"                           == pure "test"
--   stringException ("test" ++ undefined)            == pure "test&lt;Exception&gt;"
--   stringException ("test" ++ undefined ++ "hello") == pure "test&lt;Exception&gt;"
--   stringException ['t','e','s','t',undefined]      == pure "test&lt;Exception&gt;"
--   </pre>
stringException :: String -> IO String

-- | An <a>IO</a> action that when evaluated calls <a>error</a>, in the
--   <a>IO</a> monad. Note that while <a>fail</a> in <a>IO</a> raises an
--   <a>IOException</a>, this function raises an <a>ErrorCall</a> exception
--   with a call stack.
--   
--   <pre>
--   catch (errorIO "Hello") (\(ErrorCall x) -&gt; pure x) == pure "Hello"
--   seq (errorIO "foo") (print 1) == print 1
--   </pre>
errorIO :: Partial => String -> IO a

-- | An <a>IO</a> action that when evaluated calls <a>assert</a> in the
--   <a>IO</a> monad, which throws an <a>AssertionFailed</a> exception if
--   the argument is <a>False</a>. With optimizations enabled (and
--   <tt>-fgnore-asserts</tt>) this function ignores its argument and does
--   nothing.
--   
--   <pre>
--   catch (assertIO True  &gt;&gt; pure 1) (\(x :: AssertionFailed) -&gt; pure 2) == pure 1
--   seq (assertIO False) (print 1) == print 1
--   </pre>
assertIO :: Partial => Bool -> IO ()

-- | Ignore any exceptions thrown by the action.
--   
--   <pre>
--   ignore (print 1)    == print 1
--   ignore (fail "die") == pure ()
--   </pre>
ignore :: IO () -> IO ()

-- | A version of <a>catch</a> without the <a>Exception</a> context,
--   restricted to <a>SomeException</a>, so catches all exceptions.
catch_ :: IO a -> (SomeException -> IO a) -> IO a

-- | Like <a>catch_</a> but for <a>handle</a>
handle_ :: (SomeException -> IO a) -> IO a -> IO a

-- | Like <a>catch_</a> but for <a>try</a>
try_ :: IO a -> IO (Either SomeException a)

-- | Like <a>catch_</a> but for <a>catchJust</a>
catchJust_ :: (SomeException -> Maybe b) -> IO a -> (b -> IO a) -> IO a

-- | Like <a>catch_</a> but for <a>handleJust</a>
handleJust_ :: (SomeException -> Maybe b) -> (b -> IO a) -> IO a -> IO a

-- | Like <a>catch_</a> but for <a>tryJust</a>
tryJust_ :: (SomeException -> Maybe b) -> IO a -> IO (Either b a)

-- | Catch an exception if the predicate passes, then call the handler with
--   the original exception. As an example:
--   
--   <pre>
--   readFileExists x == catchBool isDoesNotExistError (readFile "myfile") (const $ pure "")
--   </pre>
catchBool :: Exception e => (e -> Bool) -> IO a -> (e -> IO a) -> IO a

-- | Like <a>catchBool</a> but for <a>handle</a>.
handleBool :: Exception e => (e -> Bool) -> (e -> IO a) -> IO a -> IO a

-- | Like <a>catchBool</a> but for <a>try</a>.
tryBool :: Exception e => (e -> Bool) -> IO a -> IO (Either e a)

-- | Perform some operation on <a>Just</a>, given the field inside the
--   <a>Just</a>.
--   
--   <pre>
--   whenJust Nothing  print == pure ()
--   whenJust (Just 1) print == print 1
--   </pre>
whenJust :: Applicative m => Maybe a -> (a -> m ()) -> m ()

-- | Like <a>whenJust</a>, but where the test can be monadic.
whenJustM :: Monad m => m (Maybe a) -> (a -> m ()) -> m ()

-- | Return either a <a>pure</a> value if a condition is <a>True</a>,
--   otherwise <a>empty</a>.
--   
--   <pre>
--   pureIf @Maybe True  5 == Just 5
--   pureIf @Maybe False 5 == Nothing
--   pureIf @[]    True  5 == [5]
--   pureIf @[]    False 5 == []
--   </pre>
pureIf :: Alternative m => Bool -> a -> m a

-- | Like <a>when</a>, but return either <a>Nothing</a> if the predicate
--   was <a>False</a>, of <a>Just</a> with the result of the computation.
--   
--   <pre>
--   whenMaybe True  (print 1) == fmap Just (print 1)
--   whenMaybe False (print 1) == pure Nothing
--   </pre>
whenMaybe :: Applicative m => Bool -> m a -> m (Maybe a)

-- | Like <a>whenMaybe</a>, but where the test can be monadic.
whenMaybeM :: Monad m => m Bool -> m a -> m (Maybe a)

-- | The identity function which requires the inner argument to be
--   <tt>()</tt>. Useful for functions with overloaded return types.
--   
--   <pre>
--   \(x :: Maybe ()) -&gt; unit x == x
--   </pre>
unit :: m () -> m ()

-- | Monadic generalisation of <a>maybe</a>.
maybeM :: Monad m => m b -> (a -> m b) -> m (Maybe a) -> m b

-- | Monadic generalisation of <a>fromMaybe</a>.
fromMaybeM :: Monad m => m a -> m (Maybe a) -> m a

-- | Monadic generalisation of <a>either</a>.
eitherM :: Monad m => (a -> m c) -> (b -> m c) -> m (Either a b) -> m c

-- | A looping operation, where the predicate returns <a>Left</a> as a seed
--   for the next loop or <a>Right</a> to abort the loop.
--   
--   <pre>
--   loop (\x -&gt; if x &lt; 10 then Left $ x * 2 else Right $ show x) 1 == "16"
--   </pre>
loop :: (a -> Either a b) -> a -> b

-- | A monadic version of <a>loop</a>, where the predicate returns
--   <a>Left</a> as a seed for the next loop or <a>Right</a> to abort the
--   loop.
loopM :: Monad m => (a -> m (Either a b)) -> a -> m b

-- | Keep running an operation until it becomes <a>False</a>. As an
--   example:
--   
--   <pre>
--   whileM $ do sleep 0.1; notM $ doesFileExist "foo.txt"
--   readFile "foo.txt"
--   </pre>
--   
--   If you need some state persisted between each test, use <a>loopM</a>.
whileM :: Monad m => m Bool -> m ()

-- | Keep running an operation until it becomes a <a>Nothing</a>,
--   accumulating the monoid results inside the <a>Just</a>s as the result
--   of the overall loop.
whileJustM :: (Monad m, Monoid a) => m (Maybe a) -> m a

-- | Keep running an operation until it becomes a <a>Just</a>, then return
--   the value inside the <a>Just</a> as the result of the overall loop.
untilJustM :: Monad m => m (Maybe a) -> m a

-- | A version of <tt>partition</tt> that works with a monadic predicate.
--   
--   <pre>
--   partitionM (Just . even) [1,2,3] == Just ([2], [1,3])
--   partitionM (const Nothing) [1,2,3] == Nothing
--   </pre>
partitionM :: Monad m => (a -> m Bool) -> [a] -> m ([a], [a])

-- | A version of <a>concatMap</a> that works with a monadic predicate.
concatMapM :: Monad m => (a -> m [b]) -> [a] -> m [b]

-- | Like <a>concatMapM</a>, but has its arguments flipped, so can be used
--   instead of the common <tt>fmap concat $ forM</tt> pattern.
concatForM :: Monad m => [a] -> (a -> m [b]) -> m [b]

-- | A version of <tt>mconcatMap</tt> that works with a monadic predicate.
mconcatMapM :: (Monad m, Monoid b) => (a -> m b) -> [a] -> m b

-- | A version of <a>mapMaybe</a> that works with a monadic predicate.
mapMaybeM :: Monad m => (a -> m (Maybe b)) -> [a] -> m [b]

-- | Like <tt>find</tt>, but where the test can be monadic.
--   
--   <pre>
--   findM (Just . isUpper) "teST"             == Just (Just 'S')
--   findM (Just . isUpper) "test"             == Just Nothing
--   findM (Just . const True) ["x",undefined] == Just (Just "x")
--   </pre>
findM :: Monad m => (a -> m Bool) -> [a] -> m (Maybe a)

-- | Like <a>findM</a>, but also allows you to compute some additional
--   information in the predicate.
firstJustM :: Monad m => (a -> m (Maybe b)) -> [a] -> m (Maybe b)

-- | A variant of <a>foldM</a> that has no base case, and thus may only be
--   applied to non-empty lists.
--   
--   <pre>
--   fold1M (\x y -&gt; Just x) [] == undefined
--   fold1M (\x y -&gt; Just $ x + y) [1, 2, 3] == Just 6
--   </pre>
fold1M :: (Partial, Monad m) => (a -> a -> m a) -> [a] -> m a

-- | Like <a>fold1M</a> but discards the result.
fold1M_ :: (Partial, Monad m) => (a -> a -> m a) -> [a] -> m ()

-- | Like <a>when</a>, but where the test can be monadic.
whenM :: Monad m => m Bool -> m () -> m ()

-- | Like <a>unless</a>, but where the test can be monadic.
unlessM :: Monad m => m Bool -> m () -> m ()

-- | Like <tt>if</tt>, but where the test can be monadic.
ifM :: Monad m => m Bool -> m a -> m a -> m a

-- | Like <a>not</a>, but where the test can be monadic.
notM :: Functor m => m Bool -> m Bool

-- | The lazy <a>||</a> operator lifted to a monad. If the first argument
--   evaluates to <a>True</a> the second argument will not be evaluated.
--   
--   <pre>
--   Just True  ||^ undefined  == Just True
--   Just False ||^ Just True  == Just True
--   Just False ||^ Just False == Just False
--   </pre>
(||^) :: Monad m => m Bool -> m Bool -> m Bool

-- | The lazy <a>&amp;&amp;</a> operator lifted to a monad. If the first
--   argument evaluates to <a>False</a> the second argument will not be
--   evaluated.
--   
--   <pre>
--   Just False &amp;&amp;^ undefined  == Just False
--   Just True  &amp;&amp;^ Just True  == Just True
--   Just True  &amp;&amp;^ Just False == Just False
--   </pre>
(&&^) :: Monad m => m Bool -> m Bool -> m Bool

-- | A version of <a>or</a> lifted to a monad. Retains the short-circuiting
--   behaviour.
--   
--   <pre>
--   orM [Just False,Just True ,undefined] == Just True
--   orM [Just False,Just False,undefined] == undefined
--   \xs -&gt; Just (or xs) == orM (map Just xs)
--   </pre>
orM :: Monad m => [m Bool] -> m Bool

-- | A version of <a>and</a> lifted to a monad. Retains the
--   short-circuiting behaviour.
--   
--   <pre>
--   andM [Just True,Just False,undefined] == Just False
--   andM [Just True,Just True ,undefined] == undefined
--   \xs -&gt; Just (and xs) == andM (map Just xs)
--   </pre>
andM :: Monad m => [m Bool] -> m Bool

-- | A version of <a>any</a> lifted to a monad. Retains the
--   short-circuiting behaviour.
--   
--   <pre>
--   anyM Just [False,True ,undefined] == Just True
--   anyM Just [False,False,undefined] == undefined
--   \(f :: Int -&gt; Maybe Bool) xs -&gt; anyM f xs == orM (map f xs)
--   </pre>
anyM :: Monad m => (a -> m Bool) -> [a] -> m Bool

-- | A version of <a>all</a> lifted to a monad. Retains the
--   short-circuiting behaviour.
--   
--   <pre>
--   allM Just [True,False,undefined] == Just False
--   allM Just [True,True ,undefined] == undefined
--   \(f :: Int -&gt; Maybe Bool) xs -&gt; anyM f xs == orM (map f xs)
--   </pre>
allM :: Monad m => (a -> m Bool) -> [a] -> m Bool

-- | Return the contents of a <a>Left</a>-value or a default value
--   otherwise.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; fromLeft 1 (Left 3)
--   3
--   
--   &gt;&gt;&gt; fromLeft 1 (Right "foo")
--   1
--   </pre>
fromLeft :: a -> Either a b -> a

-- | Return the contents of a <a>Right</a>-value or a default value
--   otherwise.
--   
--   <h4><b>Examples</b></h4>
--   
--   Basic usage:
--   
--   <pre>
--   &gt;&gt;&gt; fromRight 1 (Right 3)
--   3
--   
--   &gt;&gt;&gt; fromRight 1 (Left "foo")
--   1
--   </pre>
fromRight :: b -> Either a b -> b

-- | Pull the value out of an <a>Either</a> where both alternatives have
--   the same type.
--   
--   <pre>
--   \x -&gt; fromEither (Left x ) == x
--   \x -&gt; fromEither (Right x) == x
--   </pre>
fromEither :: Either a a -> a

-- | The <a>fromLeft'</a> function extracts the element out of a
--   <a>Left</a> and throws an error if its argument is <a>Right</a>. Much
--   like <tt>fromJust</tt>, using this function in polished code is
--   usually a bad idea.
--   
--   <pre>
--   \x -&gt; fromLeft' (Left  x) == x
--   \x -&gt; fromLeft' (Right x) == undefined
--   </pre>
fromLeft' :: Partial => Either l r -> l

-- | The <a>fromRight'</a> function extracts the element out of a
--   <a>Right</a> and throws an error if its argument is <a>Left</a>. Much
--   like <tt>fromJust</tt>, using this function in polished code is
--   usually a bad idea.
--   
--   <pre>
--   \x -&gt; fromRight' (Right x) == x
--   \x -&gt; fromRight' (Left  x) == undefined
--   </pre>
fromRight' :: Partial => Either l r -> r

-- | Given an <a>Either</a>, convert it to a <a>Maybe</a>, where
--   <a>Left</a> becomes <a>Nothing</a>.
--   
--   <pre>
--   \x -&gt; eitherToMaybe (Left x) == Nothing
--   \x -&gt; eitherToMaybe (Right x) == Just x
--   </pre>
eitherToMaybe :: Either a b -> Maybe b

-- | Given a <a>Maybe</a>, convert it to an <a>Either</a>, providing a
--   suitable value for the <a>Left</a> should the value be <a>Nothing</a>.
--   
--   <pre>
--   \a b -&gt; maybeToEither a (Just b) == Right b
--   \a -&gt; maybeToEither a Nothing == Left a
--   </pre>
maybeToEither :: a -> Maybe b -> Either a b

-- | The <a>mapLeft</a> function takes a function and applies it to an
--   Either value iff the value takes the form <tt><a>Left</a> _</tt>.
--   
--   <pre>
--   mapLeft show (Left 1) == Left "1"
--   mapLeft show (Right True) == Right True
--   </pre>
mapLeft :: (a -> c) -> Either a b -> Either c b

-- | The <a>mapRight</a> function takes a function and applies it to an
--   Either value iff the value takes the form <tt><a>Right</a> _</tt>.
--   
--   <pre>
--   mapRight show (Left 1) == Left 1
--   mapRight show (Right True) == Right "True"
--   </pre>
mapRight :: (b -> c) -> Either a b -> Either a c

-- | Evaluates the value before calling <a>writeIORef</a>.
writeIORef' :: IORef a -> a -> IO ()

-- | Evaluates the value before calling <a>atomicWriteIORef</a>.
atomicWriteIORef' :: IORef a -> a -> IO ()

-- | Variant of <a>atomicModifyIORef</a> which ignores the return value
atomicModifyIORef_ :: IORef a -> (a -> a) -> IO ()

-- | Variant of <a>atomicModifyIORef'</a> which ignores the return value
atomicModifyIORef'_ :: IORef a -> (a -> a) -> IO ()

-- | Convert a string to lower case.
--   
--   <pre>
--   lower "This is A TEST" == "this is a test"
--   lower "" == ""
--   </pre>
lower :: String -> String

-- | Convert a string to upper case.
--   
--   <pre>
--   upper "This is A TEST" == "THIS IS A TEST"
--   upper "" == ""
--   </pre>
upper :: String -> String

-- | Remove spaces from either side of a string. A combination of
--   <a>trimEnd</a> and <a>trimStart</a>.
--   
--   <pre>
--   trim      "  hello   " == "hello"
--   trimStart "  hello   " == "hello   "
--   trimEnd   "  hello   " == "  hello"
--   \s -&gt; trim s == trimEnd (trimStart s)
--   </pre>
trim :: String -> String

-- | Remove spaces from the start of a string, see <a>trim</a>.
trimStart :: String -> String

-- | Remove spaces from the end of a string, see <a>trim</a>.
trimEnd :: String -> String

-- | Split the first word off a string. Useful for when starting to parse
--   the beginning of a string, but you want to accurately preserve
--   whitespace in the rest of the string.
--   
--   <pre>
--   word1 "" == ("", "")
--   word1 "keyword rest of string" == ("keyword","rest of string")
--   word1 "  keyword\n  rest of string" == ("keyword","rest of string")
--   \s -&gt; fst (word1 s) == concat (take 1 $ words s)
--   \s -&gt; words (snd $ word1 s) == drop 1 (words s)
--   </pre>
word1 :: String -> (String, String)

-- | Split the first line off a string.
--   
--   <pre>
--   line1 "" == ("", "")
--   line1 "test" == ("test","")
--   line1 "test\n" == ("test","")
--   line1 "test\nrest" == ("test","rest")
--   line1 "test\nrest\nmore" == ("test","rest\nmore")
--   </pre>
line1 :: String -> (String, String)

-- | Escape a string such that it can be inserted into an HTML document or
--   <tt>"</tt> attribute without any special interpretation. This requires
--   escaping the <tt>&lt;</tt>, <tt>&gt;</tt>, <tt>&amp;</tt> and
--   <tt>"</tt> characters. Note that it will escape <tt>"</tt> and
--   <tt>'</tt> even though that is not required in an HTML body (but is
--   not harmful).
--   
--   <pre>
--   escapeHTML "this is a test" == "this is a test"
--   escapeHTML "&lt;b&gt;\"g&amp;t\"&lt;/n&gt;" == "&amp;lt;b&amp;gt;&amp;quot;g&amp;amp;t&amp;quot;&amp;lt;/n&amp;gt;"
--   escapeHTML "t'was another test" == "t&amp;#39;was another test"
--   </pre>
escapeHTML :: String -> String

-- | Escape a string so it can form part of a JSON literal. This requires
--   escaping the special whitespace and control characters. Additionally,
--   Note that it does <i>not</i> add quote characters around the string.
--   
--   <pre>
--   escapeJSON "this is a test" == "this is a test"
--   escapeJSON "\ttab\nnewline\\" == "\\ttab\\nnewline\\\\"
--   escapeJSON "\ESC[0mHello" == "\\u001b[0mHello"
--   </pre>
escapeJSON :: String -> String

-- | Invert of <a>escapeHTML</a> (does not do general HTML unescaping)
--   
--   <pre>
--   \xs -&gt; unescapeHTML (escapeHTML xs) == xs
--   </pre>
unescapeHTML :: String -> String

-- | General JSON unescaping, inversion of <a>escapeJSON</a> and all other
--   JSON escapes.
--   
--   <pre>
--   \xs -&gt; unescapeJSON (escapeJSON xs) == xs
--   </pre>
unescapeJSON :: String -> String

-- | Drop a number of elements from the end of the list.
--   
--   <pre>
--   dropEnd 3 "hello"  == "he"
--   dropEnd 5 "bye"    == ""
--   dropEnd (-1) "bye" == "bye"
--   \i xs -&gt; dropEnd i xs `isPrefixOf` xs
--   \i xs -&gt; length (dropEnd i xs) == max 0 (length xs - max 0 i)
--   \i -&gt; take 3 (dropEnd 5 [i..]) == take 3 [i..]
--   </pre>
dropEnd :: Int -> [a] -> [a]

-- | Take a number of elements from the end of the list.
--   
--   <pre>
--   takeEnd 3 "hello"  == "llo"
--   takeEnd 5 "bye"    == "bye"
--   takeEnd (-1) "bye" == ""
--   \i xs -&gt; takeEnd i xs `isSuffixOf` xs
--   \i xs -&gt; length (takeEnd i xs) == min (max 0 i) (length xs)
--   </pre>
takeEnd :: Int -> [a] -> [a]

-- | <tt><a>splitAtEnd</a> n xs</tt> returns a split where the second
--   element tries to contain <tt>n</tt> elements.
--   
--   <pre>
--   splitAtEnd 3 "hello" == ("he","llo")
--   splitAtEnd 3 "he"    == ("", "he")
--   \i xs -&gt; uncurry (++) (splitAt i xs) == xs
--   \i xs -&gt; splitAtEnd i xs == (dropEnd i xs, takeEnd i xs)
--   </pre>
splitAtEnd :: Int -> [a] -> ([a], [a])

-- | Break, but from the end.
--   
--   <pre>
--   breakEnd isLower "youRE" == ("you","RE")
--   breakEnd isLower "youre" == ("youre","")
--   breakEnd isLower "YOURE" == ("","YOURE")
--   \f xs -&gt; breakEnd (not . f) xs == spanEnd f  xs
--   </pre>
breakEnd :: (a -> Bool) -> [a] -> ([a], [a])

-- | Span, but from the end.
--   
--   <pre>
--   spanEnd isUpper "youRE" == ("you","RE")
--   spanEnd (not . isSpace) "x y z" == ("x y ","z")
--   \f xs -&gt; uncurry (++) (spanEnd f xs) == xs
--   \f xs -&gt; spanEnd f xs == swap (both reverse (span f (reverse xs)))
--   </pre>
spanEnd :: (a -> Bool) -> [a] -> ([a], [a])

-- | A version of <a>dropWhileEnd</a> but with different strictness
--   properties. The function <a>dropWhileEnd</a> can be used on an
--   infinite list and tests the property on each character. In contrast,
--   <a>dropWhileEnd'</a> is strict in the spine of the list but only tests
--   the trailing suffix. This version usually outperforms
--   <a>dropWhileEnd</a> if the list is short or the test is expensive.
--   Note the tests below cover both the prime and non-prime variants.
--   
--   <pre>
--   dropWhileEnd  isSpace "ab cde  " == "ab cde"
--   dropWhileEnd' isSpace "ab cde  " == "ab cde"
--   last (dropWhileEnd  even [undefined,3]) == undefined
--   last (dropWhileEnd' even [undefined,3]) == 3
--   head (dropWhileEnd  even (3:undefined)) == 3
--   head (dropWhileEnd' even (3:undefined)) == undefined
--   </pre>
dropWhileEnd' :: (a -> Bool) -> [a] -> [a]

-- | A version of <a>takeWhile</a> operating from the end.
--   
--   <pre>
--   takeWhileEnd even [2,3,4,6] == [4,6]
--   </pre>
takeWhileEnd :: (a -> Bool) -> [a] -> [a]

-- | Return the prefix of the second list if its suffix matches the entire
--   first list.
--   
--   Examples:
--   
--   <pre>
--   stripSuffix "bar" "foobar" == Just "foo"
--   stripSuffix ""    "baz"    == Just "baz"
--   stripSuffix "foo" "quux"   == Nothing
--   </pre>
stripSuffix :: Eq a => [a] -> [a] -> Maybe [a]

-- | Return the the string before and after the search string, or
--   <a>Nothing</a> if the search string is not present.
--   
--   Examples:
--   
--   <pre>
--   stripInfix "::" "a::b::c" == Just ("a", "b::c")
--   stripInfix "/" "foobar"   == Nothing
--   </pre>
stripInfix :: Eq a => [a] -> [a] -> Maybe ([a], [a])

-- | Similar to <a>stripInfix</a>, but searches from the end of the string.
--   
--   <pre>
--   stripInfixEnd "::" "a::b::c" == Just ("a::b", "c")
--   </pre>
stripInfixEnd :: Eq a => [a] -> [a] -> Maybe ([a], [a])

-- | Drops the given prefix from a list. It returns the original sequence
--   if the sequence doesn't start with the given prefix.
--   
--   <pre>
--   dropPrefix "Mr. " "Mr. Men" == "Men"
--   dropPrefix "Mr. " "Dr. Men" == "Dr. Men"
--   </pre>
dropPrefix :: Eq a => [a] -> [a] -> [a]

-- | Drops the given suffix from a list. It returns the original sequence
--   if the sequence doesn't end with the given suffix.
--   
--   <pre>
--   dropSuffix "!" "Hello World!"  == "Hello World"
--   dropSuffix "!" "Hello World!!" == "Hello World!"
--   dropSuffix "!" "Hello World."  == "Hello World."
--   </pre>
dropSuffix :: Eq a => [a] -> [a] -> [a]

-- | A variant of <a>words</a> with a custom test. In particular, adjacent
--   separators are discarded, as are leading or trailing separators.
--   
--   <pre>
--   wordsBy (== ':') "::xyz:abc::123::" == ["xyz","abc","123"]
--   \s -&gt; wordsBy isSpace s == words s
--   </pre>
wordsBy :: (a -> Bool) -> [a] -> [[a]]

-- | A variant of <a>lines</a> with a custom test. In particular, if there
--   is a trailing separator it will be discarded.
--   
--   <pre>
--   linesBy (== ':') "::xyz:abc::123::" == ["","","xyz","abc","","123",""]
--   \s -&gt; linesBy (== '\n') s == lines s
--   linesBy (== ';') "my;list;here;" == ["my","list","here"]
--   </pre>
linesBy :: (a -> Bool) -> [a] -> [[a]]

-- | Find the first instance of <tt>needle</tt> in <tt>haystack</tt>. The
--   first element of the returned tuple is the prefix of <tt>haystack</tt>
--   before <tt>needle</tt> is matched. The second is the remainder of
--   <tt>haystack</tt>, starting with the match. If you want the remainder
--   <i>without</i> the match, use <a>stripInfix</a>.
--   
--   <pre>
--   breakOn "::" "a::b::c" == ("a", "::b::c")
--   breakOn "/" "foobar"   == ("foobar", "")
--   \needle haystack -&gt; let (prefix,match) = breakOn needle haystack in prefix ++ match == haystack
--   </pre>
breakOn :: Eq a => [a] -> [a] -> ([a], [a])

-- | Similar to <a>breakOn</a>, but searches from the end of the string.
--   
--   The first element of the returned tuple is the prefix of
--   <tt>haystack</tt> up to and including the last match of
--   <tt>needle</tt>. The second is the remainder of <tt>haystack</tt>,
--   following the match.
--   
--   <pre>
--   breakOnEnd "::" "a::b::c" == ("a::b::", "c")
--   </pre>
breakOnEnd :: Eq a => [a] -> [a] -> ([a], [a])

-- | Break a list into pieces separated by the first list argument,
--   consuming the delimiter. An empty delimiter is invalid, and will cause
--   an error to be raised.
--   
--   <pre>
--   splitOn "\r\n" "a\r\nb\r\nd\r\ne" == ["a","b","d","e"]
--   splitOn "aaa"  "aaaXaaaXaaaXaaa"  == ["","X","X","X",""]
--   splitOn "x"    "x"                == ["",""]
--   splitOn "x"    ""                 == [""]
--   \s x -&gt; s /= "" ==&gt; intercalate s (splitOn s x) == x
--   \c x -&gt; splitOn [c] x                           == split (==c) x
--   </pre>
splitOn :: (Partial, Eq a) => [a] -> [a] -> [[a]]

-- | Splits a list into components delimited by separators, where the
--   predicate returns True for a separator element. The resulting
--   components do not contain the separators. Two adjacent separators
--   result in an empty component in the output.
--   
--   <pre>
--   split (== 'a') "aabbaca" == ["","","bb","c",""]
--   split (== 'a') ""        == [""]
--   split (== ':') "::xyz:abc::123::" == ["","","xyz","abc","","123","",""]
--   split (== ',') "my,list,here" == ["my","list","here"]
--   </pre>
split :: (a -> Bool) -> [a] -> [[a]]

-- | Split a list into chunks of a given size. The last chunk may contain
--   fewer than n elements. The chunk size must be positive.
--   
--   <pre>
--   chunksOf 3 "my test" == ["my ","tes","t"]
--   chunksOf 3 "mytest"  == ["myt","est"]
--   chunksOf 8 ""        == []
--   chunksOf 0 "test"    == undefined
--   </pre>
chunksOf :: Partial => Int -> [a] -> [[a]]

-- | A total <a>head</a> with a default value.
--   
--   <pre>
--   headDef 1 []      == 1
--   headDef 1 [2,3,4] == 2
--   \x xs -&gt; headDef x xs == fromMaybe x (listToMaybe xs)
--   </pre>
headDef :: a -> [a] -> a

-- | A total <a>last</a> with a default value.
--   
--   <pre>
--   lastDef 1 []      == 1
--   lastDef 1 [2,3,4] == 4
--   \x xs -&gt; lastDef x xs == last (x:xs)
--   </pre>
lastDef :: a -> [a] -> a

-- | A total variant of the list index function <a>(!!)</a>.
--   
--   <pre>
--   [2,3,4] !? 1    == Just 3
--   [2,3,4] !? (-1) == Nothing
--   []      !? 0    == Nothing
--   </pre>
(!?) :: [a] -> Int -> Maybe a

-- | A composition of <a>not</a> and <a>null</a>.
--   
--   <pre>
--   notNull []  == False
--   notNull [1] == True
--   \xs -&gt; notNull xs == not (null xs)
--   </pre>
notNull :: [a] -> Bool

-- | Non-recursive transform over a list, like <a>maybe</a>.
--   
--   <pre>
--   list 1 (\v _ -&gt; v - 2) [5,6,7] == 3
--   list 1 (\v _ -&gt; v - 2) []      == 1
--   \nil cons xs -&gt; maybe nil (uncurry cons) (uncons xs) == list nil cons xs
--   </pre>
list :: b -> (a -> [a] -> b) -> [a] -> b

-- | If the list is empty returns <a>Nothing</a>, otherwise returns the
--   <a>init</a> and the <a>last</a>.
--   
--   <pre>
--   unsnoc "test" == Just ("tes",'t')
--   unsnoc ""     == Nothing
--   \xs -&gt; unsnoc xs == if null xs then Nothing else Just (init xs, last xs)
--   </pre>
unsnoc :: [a] -> Maybe ([a], a)

-- | Append an element to the start of a list, an alias for <tt>(:)</tt>.
--   
--   <pre>
--   cons 't' "est" == "test"
--   \x xs -&gt; uncons (cons x xs) == Just (x,xs)
--   </pre>
cons :: a -> [a] -> [a]

-- | Append an element to the end of a list, takes <i>O(n)</i> time.
--   
--   <pre>
--   snoc "tes" 't' == "test"
--   \xs x -&gt; unsnoc (snoc xs x) == Just (xs,x)
--   </pre>
snoc :: [a] -> a -> [a]

-- | Equivalent to <tt>drop 1</tt>, but likely to be faster and a single
--   lexeme.
--   
--   <pre>
--   drop1 ""         == ""
--   drop1 "test"     == "est"
--   \xs -&gt; drop 1 xs == drop1 xs
--   </pre>
drop1 :: [a] -> [a]

-- | Equivalent to <tt>dropEnd 1</tt>, but likely to be faster and a single
--   lexeme.
--   
--   <pre>
--   dropEnd1 ""         == ""
--   dropEnd1 "test"     == "tes"
--   \xs -&gt; dropEnd 1 xs == dropEnd1 xs
--   </pre>
dropEnd1 :: [a] -> [a]

-- | Version on <a>concatMap</a> generalised to a <a>Monoid</a> rather than
--   just a list.
--   
--   <pre>
--   mconcatMap Sum [1,2,3] == Sum 6
--   \f xs -&gt; mconcatMap f xs == concatMap f xs
--   </pre>
mconcatMap :: Monoid b => (a -> b) -> [a] -> b

-- | Lazily compare the length of a <a>Foldable</a> with a number.
--   
--   <pre>
--   compareLength [1,2,3] 1 == GT
--   compareLength [1,2] 2 == EQ
--   \(xs :: [Int]) n -&gt; compareLength xs n == compare (length xs) n
--   compareLength (1:2:3:undefined) 2 == GT
--   </pre>
compareLength :: (Ord b, Num b, Foldable f) => f a -> b -> Ordering

-- | Lazily compare the length of two <a>Foldable</a>s. &gt;
--   comparingLength [1,2,3] [False] == GT &gt; comparingLength [1,2] "ab"
--   == EQ &gt; (xs :: [Int]) (ys :: [Int]) -&gt; comparingLength xs ys ==
--   Data.Ord.comparing length xs ys &gt; comparingLength <a>1,2</a> == LT
--   &gt; comparingLength (1:2:3:undefined) [1,2] == GT
comparingLength :: (Foldable f1, Foldable f2) => f1 a -> f2 b -> Ordering

-- | Enumerate all the values of an <a>Enum</a>, from <a>minBound</a> to
--   <a>maxBound</a>.
--   
--   <pre>
--   enumerate == [False, True]
--   </pre>
enumerate :: (Enum a, Bounded a) => [a]

-- | A combination of <a>group</a> and <a>sort</a>.
--   
--   <pre>
--   groupSort [(1,'t'),(3,'t'),(2,'e'),(2,'s')] == [(1,"t"),(2,"es"),(3,"t")]
--   \xs -&gt; map fst (groupSort xs) == sort (nub (map fst xs))
--   \xs -&gt; concatMap snd (groupSort xs) == map snd (sortOn fst xs)
--   </pre>
groupSort :: Ord k => [(k, v)] -> [(k, [v])]

-- | A combination of <a>group</a> and <a>sort</a>, using a part of the
--   value to compare on.
--   
--   <pre>
--   groupSortOn length ["test","of","sized","item"] == [["of"],["test","item"],["sized"]]
--   </pre>
groupSortOn :: Ord b => (a -> b) -> [a] -> [[a]]

-- | A combination of <a>group</a> and <a>sort</a>, using a predicate to
--   compare on.
--   
--   <pre>
--   groupSortBy (compare `on` length) ["test","of","sized","item"] == [["of"],["test","item"],["sized"]]
--   </pre>
groupSortBy :: (a -> a -> Ordering) -> [a] -> [[a]]

-- | <i>O(n log n)</i>. The <a>nubOrd</a> function removes duplicate
--   elements from a list. In particular, it keeps only the first
--   occurrence of each element. Unlike the standard <a>nub</a> operator,
--   this version requires an <a>Ord</a> instance and consequently runs
--   asymptotically faster.
--   
--   <pre>
--   nubOrd "this is a test" == "this ae"
--   nubOrd (take 4 ("this" ++ undefined)) == "this"
--   \xs -&gt; nubOrd xs == nub xs
--   </pre>
nubOrd :: Ord a => [a] -> [a]

-- | A version of <a>nubOrd</a> with a custom predicate.
--   
--   <pre>
--   nubOrdBy (compare `on` length) ["a","test","of","this"] == ["a","test","of"]
--   </pre>
nubOrdBy :: (a -> a -> Ordering) -> [a] -> [a]

-- | A version of <a>nubOrd</a> which operates on a portion of the value.
--   
--   <pre>
--   nubOrdOn length ["a","test","of","this"] == ["a","test","of"]
--   </pre>
nubOrdOn :: Ord b => (a -> b) -> [a] -> [a]

-- | <i>DEPRECATED</i> Use <a>nubOrdOn</a>, since this function is
--   _O(n^2)_.
--   
--   A version of <a>nub</a> where the equality is done on some extracted
--   value. <tt>nubOn f</tt> is equivalent to <tt>nubBy ((==) <a>on</a>
--   f)</tt>, but has the performance advantage of only evaluating
--   <tt>f</tt> once for each element in the input list.

-- | <i>Deprecated: Use nubOrdOn, since this function is O(n^2)</i>
nubOn :: Eq b => (a -> b) -> [a] -> [a]

-- | A version of <a>group</a> where the equality is done on some extracted
--   value.
groupOn :: Eq b => (a -> b) -> [a] -> [[a]]

-- | <i>O(n log n)</i>. The <a>nubSort</a> function sorts and removes
--   duplicate elements from a list. In particular, it keeps only the first
--   occurrence of each element.
--   
--   <pre>
--   nubSort "this is a test" == " aehist"
--   \xs -&gt; nubSort xs == nub (sort xs)
--   </pre>
nubSort :: Ord a => [a] -> [a]

-- | A version of <a>nubSort</a> with a custom predicate.
--   
--   <pre>
--   nubSortBy (compare `on` length) ["a","test","of","this"] == ["a","of","test"]
--   </pre>
nubSortBy :: (a -> a -> Ordering) -> [a] -> [a]

-- | A version of <a>nubSort</a> which operates on a portion of the value.
--   
--   <pre>
--   nubSortOn length ["a","test","of","this"] == ["a","of","test"]
--   </pre>
nubSortOn :: Ord b => (a -> b) -> [a] -> [a]

-- | A version of <a>maximum</a> where the comparison is done on some
--   extracted value. Raises an error if the list is empty. Only calls the
--   function once per element.
--   
--   <pre>
--   maximumOn id [] == undefined
--   maximumOn length ["test","extra","a"] == "extra"
--   </pre>
maximumOn :: (Partial, Ord b) => (a -> b) -> [a] -> a

-- | A version of <a>minimum</a> where the comparison is done on some
--   extracted value. Raises an error if the list is empty. Only calls the
--   function once per element.
--   
--   <pre>
--   minimumOn id [] == undefined
--   minimumOn length ["test","extra","a"] == "a"
--   </pre>
minimumOn :: (Partial, Ord b) => (a -> b) -> [a] -> a

-- | A strict version of <a>sum</a>. Unlike <a>sum</a> this function is
--   always strict in the <a>Num</a> argument, whereas the standard version
--   is only strict if the optimiser kicks in.
--   
--   <pre>
--   sum' [1, 2, 3] == 6
--   </pre>
sum' :: Num a => [a] -> a

-- | A strict version of <a>product</a>.
--   
--   <pre>
--   product' [1, 2, 4] == 8
--   </pre>
product' :: Num a => [a] -> a

-- | A strict version of <a>sum</a>, using a custom valuation function.
--   
--   <pre>
--   sumOn' read ["1", "2", "3"] == 6
--   </pre>
sumOn' :: Num b => (a -> b) -> [a] -> b

-- | A strict version of <a>product</a>, using a custom valuation function.
--   
--   <pre>
--   productOn' read ["1", "2", "4"] == 8
--   </pre>
productOn' :: Num b => (a -> b) -> [a] -> b

-- | Are two lists disjoint, with no elements in common.
--   
--   <pre>
--   disjoint [1,2,3] [4,5] == True
--   disjoint [1,2,3] [4,1] == False
--   </pre>
disjoint :: Eq a => [a] -> [a] -> Bool

-- | <i>O((m+n) log m), m &lt;= n</i>. Are two lists disjoint, with no
--   elements in common.
--   
--   <tt>disjointOrd</tt> is more strict than <a>disjoint</a>. For example,
--   <tt>disjointOrd</tt> cannot terminate if both lists are inifite, while
--   <a>disjoint</a> can.
--   
--   <pre>
--   disjointOrd [1,2,3] [4,5] == True
--   disjointOrd [1,2,3] [4,1] == False
--   </pre>
disjointOrd :: Ord a => [a] -> [a] -> Bool

-- | A version of <a>disjointOrd</a> with a custom predicate.
--   
--   <pre>
--   disjointOrdBy (compare `on` (`mod` 7)) [1,2,3] [4,5] == True
--   disjointOrdBy (compare `on` (`mod` 7)) [1,2,3] [4,8] == False
--   </pre>
disjointOrdBy :: (a -> a -> Ordering) -> [a] -> [a] -> Bool

-- | Are all elements the same.
--   
--   <pre>
--   allSame [1,1,2] == False
--   allSame [1,1,1] == True
--   allSame [1]     == True
--   allSame []      == True
--   allSame (1:1:2:undefined) == False
--   \xs -&gt; allSame xs == (length (nub xs) &lt;= 1)
--   </pre>
allSame :: Eq a => [a] -> Bool

-- | Is there any element which occurs more than once.
--   
--   <pre>
--   anySame [1,1,2] == True
--   anySame [1,2,3] == False
--   anySame (1:2:1:undefined) == True
--   anySame [] == False
--   \xs -&gt; anySame xs == (length (nub xs) &lt; length xs)
--   </pre>
anySame :: Eq a => [a] -> Bool

-- | Apply some operation repeatedly, producing an element of output and
--   the remainder of the list.
--   
--   <pre>
--   \xs -&gt; repeatedly (splitAt 3) xs  == chunksOf 3 xs
--   \xs -&gt; repeatedly word1 (trim xs) == words xs
--   \xs -&gt; repeatedly line1 xs == lines xs
--   </pre>
repeatedly :: ([a] -> (b, [a])) -> [a] -> [b]

-- | Find the first element of a list for which the operation returns
--   <a>Just</a>, along with the result of the operation. Like <a>find</a>
--   but useful where the function also computes some expensive information
--   that can be reused. Particular useful when the function is monadic,
--   see <tt>firstJustM</tt>.
--   
--   <pre>
--   firstJust id [Nothing,Just 3]  == Just 3
--   firstJust id [Nothing,Nothing] == Nothing
--   </pre>
firstJust :: (a -> Maybe b) -> [a] -> Maybe b

-- | A merging of <a>unzip</a> and <a>concat</a>.
--   
--   <pre>
--   concatUnzip [("a","AB"),("bc","C")] == ("abc","ABC")
--   </pre>
concatUnzip :: [([a], [b])] -> ([a], [b])

-- | A merging of <a>unzip3</a> and <a>concat</a>.
--   
--   <pre>
--   concatUnzip3 [("a","AB",""),("bc","C","123")] == ("abc","ABC","123")
--   </pre>
concatUnzip3 :: [([a], [b], [c])] -> ([a], [b], [c])

-- | <a>zip</a> against an enumeration. Truncates the output if the
--   enumeration runs out.
--   
--   <pre>
--   \i xs -&gt; zip [i..] xs == zipFrom i xs
--   zipFrom False [1..3] == [(False,1),(True, 2)]
--   </pre>
zipFrom :: Enum a => a -> [b] -> [(a, b)]

-- | <a>zipFrom</a> generalised to any combining operation. Truncates the
--   output if the enumeration runs out.
--   
--   <pre>
--   \i xs -&gt; zipWithFrom (,) i xs == zipFrom i xs
--   </pre>
zipWithFrom :: Enum a => (a -> b -> c) -> a -> [b] -> [c]

-- | Like <a>zipWith</a>, but keep going to the longest value. The function
--   argument will always be given at least one <a>Just</a>, and while both
--   lists have items, two <a>Just</a> values.
--   
--   <pre>
--   zipWithLongest (,) "a" "xyz" == [(Just 'a', Just 'x'), (Nothing, Just 'y'), (Nothing, Just 'z')]
--   zipWithLongest (,) "a" "x" == [(Just 'a', Just 'x')]
--   zipWithLongest (,) "" "x" == [(Nothing, Just 'x')]
--   </pre>
zipWithLongest :: (Maybe a -> Maybe b -> c) -> [a] -> [b] -> [c]

-- | Replace a subsequence everywhere it occurs. The first argument must
--   not be the empty list.
--   
--   <pre>
--   replace "el" "_" "Hello Bella" == "H_lo B_la"
--   replace "el" "e" "Hello"       == "Helo"
--   replace "" "e" "Hello"         == undefined
--   \xs ys -&gt; not (null xs) ==&gt; replace xs xs ys == ys
--   </pre>
replace :: (Partial, Eq a) => [a] -> [a] -> [a] -> [a]

-- | Merge two lists which are assumed to be ordered.
--   
--   <pre>
--   merge "ace" "bd" == "abcde"
--   \xs ys -&gt; merge (sort xs) (sort ys) == sort (xs ++ ys)
--   </pre>
merge :: Ord a => [a] -> [a] -> [a]

-- | Like <a>merge</a>, but with a custom ordering function.
mergeBy :: (a -> a -> Ordering) -> [a] -> [a] -> [a]

-- | <i>O(n)</i>. Append an element to a list.
--   
--   <pre>
--   [1,2,3] |: 4 |&gt; 5 == 1 :| [2,3,4,5]
--   </pre>
(|:) :: [a] -> a -> NonEmpty a
infixl 5 |:

-- | <i>O(n)</i>. Append an element to a non-empty list.
--   
--   <pre>
--   (1 :| [2,3]) |&gt; 4 |&gt; 5 == 1 :| [2,3,4,5]
--   </pre>
(|>) :: NonEmpty a -> a -> NonEmpty a
infixl 5 |>

-- | Append a list to a non-empty list.
--   
--   <pre>
--   appendl (1 :| [2,3]) [4,5] == 1 :| [2,3,4,5]
--   </pre>
appendl :: NonEmpty a -> [a] -> NonEmpty a

-- | Append a non-empty list to a list.
--   
--   <pre>
--   appendr [1,2,3] (4 :| [5]) == 1 :| [2,3,4,5]
--   </pre>
appendr :: [a] -> NonEmpty a -> NonEmpty a

-- | The largest element of a non-empty list.
maximum1 :: Ord a => NonEmpty a -> a

-- | The least element of a non-empty list.
minimum1 :: Ord a => NonEmpty a -> a

-- | The largest element of a non-empty list with respect to the given
--   comparison function.
maximumBy1 :: (a -> a -> Ordering) -> NonEmpty a -> a

-- | The least element of a non-empty list with respect to the given
--   comparison function.
minimumBy1 :: (a -> a -> Ordering) -> NonEmpty a -> a

-- | A version of <a>maximum1</a> where the comparison is done on some
--   extracted value.
maximumOn1 :: Ord b => (a -> b) -> NonEmpty a -> a

-- | A version of <a>minimum1</a> where the comparison is done on some
--   extracted value.
minimumOn1 :: Ord b => (a -> b) -> NonEmpty a -> a

-- | Update the first component of a pair.
--   
--   <pre>
--   first succ (1,"test") == (2,"test")
--   </pre>
first :: (a -> a') -> (a, b) -> (a', b)

-- | Update the second component of a pair.
--   
--   <pre>
--   second reverse (1,"test") == (1,"tset")
--   </pre>
second :: (b -> b') -> (a, b) -> (a, b')

-- | Given two functions, apply one to the first component and one to the
--   second. A specialised version of <a>***</a>.
--   
--   <pre>
--   (succ *** reverse) (1,"test") == (2,"tset")
--   </pre>
(***) :: (a -> a') -> (b -> b') -> (a, b) -> (a', b')
infixr 3 ***

-- | Given two functions, apply both to a single argument to form a pair. A
--   specialised version of <a>&amp;&amp;&amp;</a>.
--   
--   <pre>
--   (succ &amp;&amp;&amp; pred) 1 == (2,0)
--   </pre>
(&&&) :: (a -> b) -> (a -> c) -> a -> (b, c)
infixr 3 &&&

-- | Duplicate a single value into a pair.
--   
--   <pre>
--   dupe 12 == (12, 12)
--   </pre>
dupe :: a -> (a, a)

-- | Apply a single function to both components of a pair.
--   
--   <pre>
--   both succ (1,2) == (2,3)
--   </pre>
both :: (a -> b) -> (a, a) -> (b, b)

-- | Update the first component of a pair.
--   
--   <pre>
--   firstM (\x -&gt; [x-1, x+1]) (1,"test") == [(0,"test"),(2,"test")]
--   </pre>
firstM :: Functor m => (a -> m a') -> (a, b) -> m (a', b)

-- | Update the second component of a pair.
--   
--   <pre>
--   secondM (\x -&gt; [reverse x, x]) (1,"test") == [(1,"tset"),(1,"test")]
--   </pre>
secondM :: Functor m => (b -> m b') -> (a, b) -> m (a, b')

-- | Extract the <a>fst</a> of a triple.
fst3 :: (a, b, c) -> a

-- | Extract the <a>snd</a> of a triple.
snd3 :: (a, b, c) -> b

-- | Extract the final element of a triple.
thd3 :: (a, b, c) -> c

-- | Update the first component of a triple.
--   
--   <pre>
--   first3 succ (1,1,1) == (2,1,1)
--   </pre>
first3 :: (a -> a') -> (a, b, c) -> (a', b, c)

-- | Update the second component of a triple.
--   
--   <pre>
--   second3 succ (1,1,1) == (1,2,1)
--   </pre>
second3 :: (b -> b') -> (a, b, c) -> (a, b', c)

-- | Update the third component of a triple.
--   
--   <pre>
--   third3 succ (1,1,1) == (1,1,2)
--   </pre>
third3 :: (c -> c') -> (a, b, c) -> (a, b, c')

-- | Converts an uncurried function to a curried function.
curry3 :: ((a, b, c) -> d) -> a -> b -> c -> d

-- | Converts a curried function to a function on a triple.
uncurry3 :: (a -> b -> c -> d) -> (a, b, c) -> d

-- | Read a <a>Version</a> or throw an exception.
--   
--   <pre>
--   \x -&gt; readVersion (showVersion x) == x
--   readVersion "hello" == undefined
--   </pre>
readVersion :: Partial => String -> Version

-- | Show a number to a fixed number of decimal places.
--   
--   <pre>
--   showDP 4 pi == "3.1416"
--   showDP 0 pi == "3"
--   showDP 2 3  == "3.00"
--   </pre>
showDP :: RealFloat a => Int -> a -> String

-- | Specialised numeric conversion, type restricted version of
--   <a>fromIntegral</a>.
intToDouble :: Int -> Double

-- | Specialised numeric conversion, type restricted version of
--   <a>fromIntegral</a>.
intToFloat :: Int -> Float

-- | Specialised numeric conversion, type restricted version of
--   <a>realToFrac</a>.
floatToDouble :: Float -> Double

-- | Specialised numeric conversion, type restricted version of
--   <a>realToFrac</a>.
doubleToFloat :: Double -> Float

-- | Run an <a>IO</a> action with the given working directory and restore
--   the original working directory afterwards, even if the given action
--   fails due to an exception.
--   
--   The operation may fail with the same exceptions as
--   <a>getCurrentDirectory</a> and <a>setCurrentDirectory</a>.
withCurrentDirectory :: FilePath -> IO a -> IO a

-- | Create a directory with permissions so that only the current user can
--   view it. On Windows this function is equivalent to
--   <a>createDirectory</a>.
createDirectoryPrivate :: String -> IO ()

-- | List the files and directories directly within a directory. Each
--   result will be prefixed by the query directory, and the special
--   directories <tt>.</tt> and <tt>..</tt> will be ignored. Intended as a
--   cleaned up version of <a>getDirectoryContents</a>.
--   
--   <pre>
--   withTempDir $ \dir -&gt; do writeFile (dir &lt;/&gt; "test.txt") ""; (== [dir &lt;/&gt; "test.txt"]) &lt;$&gt; listContents dir
--   let touch = mapM_ $ \x -&gt; createDirectoryIfMissing True (takeDirectory x) &gt;&gt; writeFile x ""
--   let listTest op as bs = withTempDir $ \dir -&gt; do touch $ map (dir &lt;/&gt;) as; res &lt;- op dir; pure $ map (drop (length dir + 1)) res == bs
--   listTest listContents ["bar.txt","foo/baz.txt","zoo"] ["bar.txt","foo","zoo"]
--   </pre>
listContents :: FilePath -> IO [FilePath]

-- | Like <a>listContents</a>, but only returns the directories in a
--   directory, not the files. Each directory will be prefixed by the query
--   directory.
--   
--   <pre>
--   listTest listDirectories ["bar.txt","foo/baz.txt","zoo"] ["foo"]
--   </pre>
listDirectories :: FilePath -> IO [FilePath]

-- | Like <a>listContents</a>, but only returns the files in a directory,
--   not other directories. Each file will be prefixed by the query
--   directory.
--   
--   <pre>
--   listTest listFiles ["bar.txt","foo/baz.txt","zoo"] ["bar.txt","zoo"]
--   </pre>
listFiles :: FilePath -> IO [FilePath]

-- | Like <a>listFilesRecursive</a>, but with a predicate to decide where
--   to recurse into. Typically directories starting with <tt>.</tt> would
--   be ignored. The initial argument directory will have the test applied
--   to it.
--   
--   <pre>
--   listTest (listFilesInside $ pure . not . isPrefixOf "." . takeFileName)
--       ["bar.txt","foo" &lt;/&gt; "baz.txt",".foo" &lt;/&gt; "baz2.txt", "zoo"] ["bar.txt","zoo","foo" &lt;/&gt; "baz.txt"]
--   listTest (listFilesInside $ const $ pure False) ["bar.txt"] []
--   </pre>
listFilesInside :: (FilePath -> IO Bool) -> FilePath -> IO [FilePath]

-- | Like <a>listFiles</a>, but goes recursively through all
--   subdirectories. This function will follow symlinks, and if they form a
--   loop, this function will not terminate.
--   
--   <pre>
--   listTest listFilesRecursive ["bar.txt","zoo","foo" &lt;/&gt; "baz.txt"] ["bar.txt","zoo","foo" &lt;/&gt; "baz.txt"]
--   </pre>
listFilesRecursive :: FilePath -> IO [FilePath]

-- | Return <a>True</a> on Windows and <a>False</a> otherwise. A runtime
--   version of <tt>#ifdef minw32_HOST_OS</tt>. Equivalent to <tt>os ==
--   "mingw32"</tt>, but: more efficient; doesn't require typing an easily
--   mistypeable string; actually asks about your OS not a library; doesn't
--   bake in 32bit assumptions that are already false. &lt;/rant&gt;
--   
--   <pre>
--   isWindows == (os == "mingw32")
--   </pre>
isWindows :: Bool

-- | Return <a>True</a> on Mac OS X and <a>False</a> otherwise.
isMac :: Bool

-- | Capture the <a>stdout</a> and <a>stderr</a> of a computation.
--   
--   <pre>
--   captureOutput (print 1) == pure ("1\n",())
--   </pre>
captureOutput :: IO a -> IO (String, a)

-- | Execute an action with a custom <a>BufferMode</a>, a wrapper around
--   <a>hSetBuffering</a>.
withBuffering :: Handle -> BufferMode -> IO a -> IO a

-- | Like <a>readFile</a>, but setting an encoding.
readFileEncoding :: TextEncoding -> FilePath -> IO String

-- | Like <a>readFile</a>, but with the encoding <a>utf8</a>.
readFileUTF8 :: FilePath -> IO String

-- | Like <a>readFile</a>, but for binary files.
readFileBinary :: FilePath -> IO String

-- | A strict version of <a>readFile</a>. When the string is produced, the
--   entire file will have been read into memory and the file handle will
--   have been closed. Closing the file handle does not rely on the garbage
--   collector.
--   
--   <pre>
--   \(filter isHexDigit -&gt; s) -&gt; fmap (== s) $ withTempFile $ \file -&gt; do writeFile file s; readFile' file
--   </pre>
readFile' :: FilePath -> IO String

-- | A strict version of <a>readFileEncoding</a>, see <a>readFile'</a> for
--   details.
readFileEncoding' :: TextEncoding -> FilePath -> IO String

-- | A strict version of <a>readFileUTF8</a>, see <a>readFile'</a> for
--   details.
readFileUTF8' :: FilePath -> IO String

-- | A strict version of <a>readFileBinary</a>, see <a>readFile'</a> for
--   details.
readFileBinary' :: FilePath -> IO String

-- | Write a file with a particular encoding.
writeFileEncoding :: TextEncoding -> FilePath -> String -> IO ()

-- | Write a file with the <a>utf8</a> encoding.
--   
--   <pre>
--   \s -&gt; withTempFile $ \file -&gt; do writeFileUTF8 file s; fmap (== s) $ readFileUTF8' file
--   </pre>
writeFileUTF8 :: FilePath -> String -> IO ()

-- | Write a binary file.
--   
--   <pre>
--   \(ASCIIString s) -&gt; withTempFile $ \file -&gt; do writeFileBinary file s; fmap (== s) $ readFileBinary' file
--   </pre>
writeFileBinary :: FilePath -> String -> IO ()

-- | Create a temporary file in the temporary directory. The file will be
--   deleted after the action completes (provided the file is not still
--   open). The <a>FilePath</a> will not have any file extension, will
--   exist, and will be zero bytes long. If you require a file with a
--   specific name, use <a>withTempDir</a>.
--   
--   <pre>
--   withTempFile doesFileExist == pure True
--   (doesFileExist =&lt;&lt; withTempFile pure) == pure False
--   withTempFile readFile' == pure ""
--   </pre>
withTempFile :: (FilePath -> IO a) -> IO a

-- | Create a temporary directory inside the system temporary directory.
--   The directory will be deleted after the action completes.
--   
--   <pre>
--   withTempDir doesDirectoryExist == pure True
--   (doesDirectoryExist =&lt;&lt; withTempDir pure) == pure False
--   withTempDir listFiles == pure []
--   </pre>
withTempDir :: (FilePath -> IO a) -> IO a

-- | Provide a function to create a temporary file, and a way to delete a
--   temporary file. Most users should use <a>withTempFile</a> which
--   combines these operations.
newTempFile :: IO (FilePath, IO ())

-- | Provide a function to create a temporary directory, and a way to
--   delete a temporary directory. Most users should use <a>withTempDir</a>
--   which combines these operations.
newTempDir :: IO (FilePath, IO ())

-- | Like <a>newTempFile</a> but using a custom temporary directory.
newTempFileWithin :: FilePath -> IO (FilePath, IO ())

-- | Like <a>newTempDir</a> but using a custom temporary directory.
newTempDirWithin :: FilePath -> IO (FilePath, IO ())

-- | Returns <a>True</a> if both files have the same content. Raises an
--   error if either file is missing.
--   
--   <pre>
--   fileEq "does_not_exist1" "does_not_exist2" == undefined
--   fileEq "does_not_exist" "does_not_exist" == undefined
--   withTempFile $ \f1 -&gt; fileEq "does_not_exist" f1 == undefined
--   withTempFile $ \f1 -&gt; withTempFile $ \f2 -&gt; fileEq f1 f2
--   withTempFile $ \f1 -&gt; withTempFile $ \f2 -&gt; writeFile f1 "a" &gt;&gt; writeFile f2 "a" &gt;&gt; fileEq f1 f2
--   withTempFile $ \f1 -&gt; withTempFile $ \f2 -&gt; writeFile f1 "a" &gt;&gt; writeFile f2 "b" &gt;&gt; notM (fileEq f1 f2)
--   </pre>
fileEq :: FilePath -> FilePath -> IO Bool

-- | A version of <a>system</a> that throws an error if the <a>ExitCode</a>
--   is not <a>ExitSuccess</a>.
system_ :: Partial => String -> IO ()

-- | A version of <a>system</a> that also captures the output, both
--   <a>stdout</a> and <a>stderr</a>. Returns a pair of the <a>ExitCode</a>
--   and the output.
systemOutput :: String -> IO (ExitCode, String)

-- | A version of <a>system</a> that captures the output (both
--   <a>stdout</a> and <a>stderr</a>) and throws an error if the
--   <a>ExitCode</a> is not <a>ExitSuccess</a>.
systemOutput_ :: Partial => String -> IO String

-- | A type alias for seconds, which are stored as <a>Double</a>.
type Seconds = Double

-- | Sleep for a number of seconds.
--   
--   <pre>
--   fmap (round . fst) (duration $ sleep 1) == pure 1
--   </pre>
sleep :: Seconds -> IO ()

-- | A version of <a>timeout</a> that takes <a>Seconds</a> and never
--   overflows the bounds of an <a>Int</a>. In addition, the bug that
--   negative timeouts run for ever has been fixed.
--   
--   <pre>
--   timeout (-3) (print 1) == pure Nothing
--   timeout 0.1  (print 1) == fmap Just (print 1)
--   do (t, _) &lt;- duration $ timeout 0.1 $ sleep 1000; print t; pure $ t &lt; 1
--   timeout 0.1  (sleep 2 &gt;&gt; print 1) == pure Nothing
--   </pre>
timeout :: Seconds -> IO a -> IO (Maybe a)

-- | Show a number of seconds, typically a duration, in a suitable manner
--   with reasonable precision for a human.
--   
--   <pre>
--   showDuration 3.435   == "3.44s"
--   showDuration 623.8   == "10m24s"
--   showDuration 62003.8 == "17h13m"
--   showDuration 1e8     == "27777h47m"
--   </pre>
showDuration :: Seconds -> String

-- | Call once to start, then call repeatedly to get the elapsed time since
--   the first call. The time is guaranteed to be monotonic. This function
--   is robust to system time changes.
--   
--   <pre>
--   do f &lt;- offsetTime; xs &lt;- replicateM 10 f; pure $ xs == sort xs
--   </pre>
offsetTime :: IO (IO Seconds)

-- | A synonym for <a>offsetTime</a>.

-- | <i>Deprecated: Use <a>offsetTime</a> instead, which is guaranteed to
--   always increase.</i>
offsetTimeIncrease :: IO (IO Seconds)

-- | Record how long a computation takes in <a>Seconds</a>.
--   
--   <pre>
--   do (a,_) &lt;- duration $ sleep 1; pure $ a &gt;= 1 &amp;&amp; a &lt;= 1.5
--   </pre>
duration :: MonadIO m => m a -> m (Seconds, a)


-- | This module provides <a>Text.Read</a> with functions added in later
--   versions.
--   
--   Currently this module has no functionality beyond <a>Text.Read</a>.

-- | <i>Deprecated: Use Text.Read directly</i>
module Text.Read.Extra
