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


-- | Various small helper functions for Lists, Maybes, Tuples, Functions
--   
--   Various small helper functions for Lists, Maybes, Tuples, Functions.
--   Some of these functions are improved implementations of standard
--   functions. They have the same name as their standard counterparts. The
--   package only contains functions that do not require packages other
--   than the base package. Thus you do not risk a dependency avalanche by
--   importing it. However, further splitting the base package might
--   invalidate this statement.
@package utility-ht
@version 0.0.5.1

module Text.Show.HT

-- | Show a value using an infix operator.
showsInfixPrec :: (Show a, Show b) => String -> Int -> Int -> a -> b -> ShowS

module Text.Read.HT

-- | Parse a string containing an infix operator.
readsInfixPrec :: (Read a, Read b) => String -> Int -> Int -> (a -> b -> c) -> ReadS c

-- | Compose two parsers sequentially.
(.>) :: ReadS (b -> c) -> ReadS b -> ReadS c
readMany :: Read a => String -> [a]
maybeRead :: Read a => String -> Maybe a

module Data.Strictness.HT
arguments1 :: (a -> x) -> a -> x
arguments2 :: (a -> b -> x) -> a -> b -> x
arguments3 :: (a -> b -> c -> x) -> a -> b -> c -> x
arguments4 :: (a -> b -> c -> d -> x) -> a -> b -> c -> d -> x
arguments5 :: (a -> b -> c -> d -> e -> x) -> a -> b -> c -> d -> e -> x

module Control.Monad.HT

-- | Also present in newer versions of the <tt>base</tt> package.
(<=<) :: Monad m => (b -> m c) -> (a -> m b) -> (a -> m c)

-- | Monadic <a>repeat</a>.
repeat :: Monad m => m a -> m [a]

-- | repeat action until result fulfills condition
until :: Monad m => (a -> Bool) -> m a -> m a

-- | repeat action until result fulfills condition

-- | <i>Deprecated: use M.until </i>
untilM :: Monad m => (a -> Bool) -> m a -> m a

-- | parameter order equal to that of <tt>nest</tt>
iterateLimit :: Monad m => Int -> (a -> m a) -> a -> m [a]

-- | parameter order equal to that of <tt>nest</tt>

-- | <i>Deprecated: use M.iterateLimit </i>
iterateLimitM :: Monad m => Int -> (a -> m a) -> a -> m [a]

-- | Lazy monadic conjunction. That is, when the first action returns
--   <tt>False</tt>, then <tt>False</tt> is immediately returned, without
--   running the second action.
andLazy :: Monad m => m Bool -> m Bool -> m Bool

-- | Lazy monadic disjunction. That is, when the first action returns
--   <tt>True</tt>, then <tt>True</tt> is immediately returned, without
--   running the second action.
orLazy :: Monad m => m Bool -> m Bool -> m Bool

module Data.Tuple.HT

-- | Cf. '(Control.Arrow.***)'.
--   
--   Apply two functions on corresponding values in a pair, where the
--   pattern match on the pair constructor is lazy. This is crucial in
--   recursions such as the of <tt>partition</tt>.
mapPair :: (a -> c, b -> d) -> (a, b) -> (c, d)

-- | <a>first</a>
mapFst :: (a -> c) -> (a, b) -> (c, b)

-- | <a>second</a>
mapSnd :: (b -> c) -> (a, b) -> (a, c)
swap :: (a, b) -> (b, a)
forcePair :: (a, b) -> (a, b)
fst3 :: (a, b, c) -> a
snd3 :: (a, b, c) -> b
thd3 :: (a, b, c) -> c
curry3 :: ((a, b, c) -> d) -> a -> b -> c -> d
uncurry3 :: (a -> b -> c -> d) -> ((a, b, c) -> d)

module Data.Maybe.HT

-- | Returns <a>Just</a> if the precondition is fulfilled.
toMaybe :: Bool -> a -> Maybe a

-- | This is an infix version of <a>fmap</a> for writing <a>select</a>
--   style expressions using test functions, that produce <a>Maybe</a>s.
--   
--   The precedence is chosen to be higher than '(:)', in order to allow:
--   
--   <pre>
--   alternatives default $
--      checkForA ?-&gt; (\a -&gt; f a) :
--      checkForB ?-&gt; (\b -&gt; g b) :
--      []
--   </pre>
--   
--   The operation is left associative in order to allow to write
--   
--   <pre>
--   checkForA ?-&gt; f ?-&gt; g
--   </pre>
--   
--   which is equivalent to
--   
--   <pre>
--   checkForA ?-&gt; g . f
--   </pre>
--   
--   due to the functor law.
(?->) :: Maybe a -> (a -> b) -> Maybe b
alternatives :: a -> [Maybe a] -> a

module Data.Function.HT

-- | Compositional power of a function, i.e. apply the function <tt>n</tt>
--   times to a value. It is rather the same as <tt>iter</tt> in Simon
--   Thompson: "The Craft of Functional Programming", page 172
nest :: Int -> (a -> a) -> a -> a

-- | <tt>powerAssociative</tt> is an auxiliary function that, for an
--   associative operation <tt>op</tt>, computes the same value as
--   
--   <pre>
--   powerAssociative op a0 a n = foldr op a0 (genericReplicate n a)
--   </pre>
--   
--   but applies <a>op</a> O(log n) times and works for large n.
powerAssociative :: (a -> a -> a) -> a -> a -> Integer -> a

-- | Known as <tt>on</tt> in newer versions of the <tt>base</tt> package.
compose2 :: (b -> b -> c) -> (a -> b) -> (a -> a -> c)


-- | Variant of <a>Data.List</a> functions like <a>group</a>, <a>sort</a>
--   where the comparison is performed on a key computed from the list
--   elements. In principle these functions could be replaced by e.g.
--   <tt>sortBy (compare <tt>on</tt> f)</tt>, but <tt>f</tt> will be
--   re-computed for every comparison. If the evaluation of <tt>f</tt> is
--   expensive, our functions are better, since they buffer the results of
--   <tt>f</tt>.
module Data.List.Key
nub :: Eq b => (a -> b) -> [a] -> [a]
sort :: Ord b => (a -> b) -> [a] -> [a]

-- | argmin
minimum :: Ord b => (a -> b) -> [a] -> a

-- | argmax
maximum :: Ord b => (a -> b) -> [a] -> a

-- | Divides a list into sublists such that the members in a sublist share
--   the same key. It uses semantics of <a>groupBy</a>, not that of
--   <a>groupBy</a>.
group :: Eq b => (a -> b) -> [a] -> [[a]]
merge :: Ord b => (a -> b) -> [a] -> [a] -> [a]

module Data.Ord.HT
comparing :: Ord b => (a -> b) -> a -> a -> Ordering

-- | <tt>limit (lower,upper) x</tt> restricts <tt>x</tt> to the range from
--   <tt>lower</tt> to <tt>upper</tt>. Don't expect a sensible result for
--   <tt>lower&gt;upper</tt>.
limit :: Ord a => (a, a) -> a -> a

-- | <tt>limit (lower,upper) x</tt> checks whether <tt>x</tt> is in the
--   range from <tt>lower</tt> to <tt>upper</tt>. Don't expect a sensible
--   result for <tt>lower&gt;upper</tt>.
inRange :: Ord a => (a, a) -> a -> Bool

module Data.Eq.HT
equating :: Eq b => (a -> b) -> a -> a -> Bool

module Data.Bool.HT

-- | <tt>if-then-else</tt> as function.
--   
--   Example:
--   
--   <pre>
--   if' (even n) "even" $
--   if' (isPrime n) "prime" $
--   "boring"
--   </pre>
if' :: Bool -> a -> a -> a

-- | From a list of expressions choose the one, whose condition is true.
--   
--   Example:
--   
--   <pre>
--   select "boring" $
--     (even n, "even") :
--     (isPrime n, "prime") :
--     []
--   </pre>
select :: a -> [(Bool, a)] -> a

-- | Like the <tt>?</tt> operator of the C progamming language. Example:
--   <tt>bool ?: (<a>yes</a>, <a>no</a>)</tt>.
(?:) :: Bool -> (a, a) -> a

-- | Logical operator for implication.
--   
--   Funnily because of the ordering of <a>Bool</a> it holds <tt>implies ==
--   (&lt;=)</tt>.
implies :: Bool -> Bool -> Bool

module Data.List.HT

-- | This function is lazier than the one suggested in the Haskell 98
--   report. It is <tt>inits undefined = [] : undefined</tt>, in contrast
--   to <tt>Data.List.inits undefined = undefined</tt>.
inits :: [a] -> [[a]]

-- | This function is lazier than the one suggested in the Haskell 98
--   report. It is <tt>tails undefined = ([] : undefined) : undefined</tt>,
--   in contrast to <tt>Data.List.tails undefined = undefined</tt>.
tails :: [a] -> [[a]]

-- | This function compares adjacent elements of a list. If two adjacent
--   elements satisfy a relation then they are put into the same sublist.
--   Example:
--   
--   <pre>
--   groupBy (&lt;) "abcdebcdef"  ==  ["abcde","bcdef"]
--   </pre>
--   
--   In contrast to that <a>groupBy</a> compares the head of each sublist
--   with each candidate for this sublist. This yields
--   
--   <pre>
--   List.groupBy (&lt;) "abcdebcdef"  ==  ["abcdebcdef"]
--   </pre>
--   
--   The second <tt><tt>b</tt></tt> is compared with the leading
--   <tt><tt>a</tt></tt>. Thus it is put into the same sublist as
--   <tt><tt>a</tt></tt>.
--   
--   The sublists are never empty. Thus the more precise result type would
--   be <tt>[(a,[a])]</tt>.
groupBy :: (a -> a -> Bool) -> [a] -> [[a]]
group :: Eq a => [a] -> [[a]]

-- | Like standard <a>unzip</a> but more lazy. It is <tt>Data.List.unzip
--   undefined == undefined</tt>, but <tt>unzip undefined == (undefined,
--   undefined)</tt>.
unzip :: [(a, b)] -> ([a], [b])

-- | <a>partition</a> of GHC 6.2.1 fails on infinite lists. But this one
--   does not.
partition :: (a -> Bool) -> [a] -> ([a], [a])

-- | It is <tt>Data.List.span f undefined = undefined</tt>, whereas
--   <tt>span f undefined = (undefined, undefined)</tt>.
span :: (a -> Bool) -> [a] -> ([a], [a])

-- | It is <tt>Data.List.span f undefined = undefined</tt>, whereas
--   <tt>span f undefined = (undefined, undefined)</tt>.
break :: (a -> Bool) -> [a] -> ([a], [a])

-- | Split the list at the occurrences of a separator into sub-lists.
--   Remove the separators. This is a generalization of <a>words</a>.
chop :: (a -> Bool) -> [a] -> [[a]]

-- | Like <a>break</a>, but splits after the matching element.
breakAfter :: (a -> Bool) -> [a] -> ([a], [a])

-- | Split the list after each occurence of a terminator. Keep the
--   terminator. There is always a list for the part after the last
--   terminator. It may be empty.
segmentAfter :: (a -> Bool) -> [a] -> [[a]]

-- | Split the list before each occurence of a leading character. Keep
--   these characters. There is always a list for the part before the first
--   leading character. It may be empty.
segmentBefore :: (a -> Bool) -> [a] -> [[a]]

-- | <tt>removeEach xs</tt> represents a list of sublists of <tt>xs</tt>,
--   where each element of <tt>xs</tt> is removed and the removed element
--   is separated. It seems to be much simpler to achieve with <tt>zip xs
--   (map (flip List.delete xs) xs)</tt>, but the implementation of
--   <a>removeEach</a> does not need the <a>Eq</a> instance and thus can
--   also be used for lists of functions.
removeEach :: [a] -> [(a, [a])]
splitEverywhere :: [a] -> [([a], a, [a])]

-- | It holds <tt>splitLast xs == (init xs, last xs)</tt>, but
--   <a>splitLast</a> is more efficient if the last element is accessed
--   after the initial ones, because it avoids memoizing list.

-- | <i>Deprecated: use viewR instead </i>
splitLast :: [a] -> ([a], a)

-- | Should be prefered to <a>head</a> and <a>tail</a>.
viewL :: [a] -> Maybe (a, [a])

-- | Should be prefered to <a>init</a> and <a>last</a>.
viewR :: [a] -> Maybe ([a], a)

-- | Should be prefered to <a>head</a> and <a>tail</a>.
switchL :: b -> (a -> [a] -> b) -> [a] -> b

-- | Should be prefered to <a>init</a> and <a>last</a>.
switchR :: b -> ([a] -> a -> b) -> [a] -> b

-- | Remove the longest suffix of elements satisfying p. In contrast to
--   <tt>reverse . dropWhile p . reverse</tt> this works for infinite
--   lists, too.
dropWhileRev :: (a -> Bool) -> [a] -> [a]

-- | Alternative version of <tt>reverse . takeWhile p . reverse</tt>.
takeWhileRev :: (a -> Bool) -> [a] -> [a]

-- | <tt>maybePrefixOf xs ys</tt> is <tt>Just zs</tt> if <tt>xs</tt> is a
--   prefix of <tt>ys</tt>, where <tt>zs</tt> is <tt>ys</tt> without the
--   prefix <tt>xs</tt>. Otherwise it is <tt>Nothing</tt>.
maybePrefixOf :: Eq a => [a] -> [a] -> Maybe [a]

-- | Partition a list into elements which evaluate to <tt>Just</tt> or
--   <tt>Nothing</tt> by <tt>f</tt>.
--   
--   It holds <tt>mapMaybe f == fst . partitionMaybe f</tt> and
--   <tt>partition p == partitionMaybe ( x -&gt; toMaybe (p x) x)</tt>.
partitionMaybe :: (a -> Maybe b) -> [a] -> ([b], [a])

-- | This is the cousin of <a>takeWhile</a> analogously to <a>catMaybes</a>
--   being the cousin of <a>filter</a>.
--   
--   Example: Keep the heads of sublists until an empty list occurs.
--   
--   <pre>
--   takeWhileJust $ map (fmap fst . viewL) xs
--   </pre>
takeWhileJust :: [Maybe a] -> [a]
unzipEithers :: [Either a b] -> ([a], [b])

-- | keep every k-th value from the list
sieve :: Int -> [a] -> [a]
sliceHorizontal :: Int -> [a] -> [[a]]
sliceVertical :: Int -> [a] -> [[a]]
search :: Eq a => [a] -> [a] -> [Int]
replace :: Eq a => [a] -> [a] -> [a] -> [a]
multiReplace :: Eq a => [([a], [a])] -> [a] -> [a]

-- | Transform
--   
--   <pre>
--   [[00,01,02,...],          [[00],
--    [10,11,12,...],   --&gt;     [10,01],
--    [20,21,22,...],           [20,11,02],
--    ...]                      ...]
--   </pre>
--   
--   With <tt>concat . shear</tt> you can perform a Cantor diagonalization,
--   that is an enumeration of all elements of the sub-lists where each
--   element is reachable within a finite number of steps. It is also
--   useful for polynomial multiplication (convolution).
shear :: [[a]] -> [[a]]

-- | Transform
--   
--   <pre>
--   [[00,01,02,...],          [[00],
--    [10,11,12,...],   --&gt;     [01,10],
--    [20,21,22,...],           [02,11,20],
--    ...]                      ...]
--   </pre>
--   
--   It's like <a>shear</a> but the order of elements in the sub list is
--   reversed. Its implementation seems to be more efficient than that of
--   <a>shear</a>. If the order does not matter, better choose
--   <a>shearTranspose</a>.
shearTranspose :: [[a]] -> [[a]]

-- | Operate on each combination of elements of the first and the second
--   list. In contrast to the list instance of <a>liftM2</a> in holds the
--   results in a list of lists. It holds <tt>concat (outerProduct f xs ys)
--   == liftM2 f xs ys</tt>
outerProduct :: (a -> b -> c) -> [a] -> [b] -> [[c]]

-- | Take while first predicate holds, then continue taking while second
--   predicate holds, and so on.
takeWhileMulti :: [a -> Bool] -> [a] -> [a]

-- | rotate left
rotate :: Int -> [a] -> [a]

-- | Given two lists that are ordered (i.e. <tt>p x y</tt> holds for
--   subsequent <tt>x</tt> and <tt>y</tt>) <a>mergeBy</a> them into a list
--   that is ordered, again.
mergeBy :: (a -> a -> Bool) -> [a] -> [a] -> [a]
allEqual :: Eq a => [a] -> Bool
isAscending :: Ord a => [a] -> Bool
isAscendingLazy :: Ord a => [a] -> [Bool]

-- | This function combines every pair of neighbour elements in a list with
--   a certain function.
mapAdjacent :: (a -> a -> b) -> [a] -> [b]

-- | Enumerate without Enum context. For Enum equivalent to enumFrom.
range :: Num a => Int -> [a]
padLeft :: a -> Int -> [a] -> [a]
padRight :: a -> Int -> [a] -> [a]

-- | For an associative operation <tt>op</tt> this computes
--   <tt>iterateAssociative op a = iterate (op a) a</tt> but it is even
--   faster than <tt>map (powerAssociative op a a) [0..]</tt> since it
--   shares temporary results.
--   
--   The idea is: From the list <tt>map (powerAssociative op a a)
--   [0,(2*n)..]</tt> we compute the list <tt>map (powerAssociative op a a)
--   [0,n..]</tt>, and iterate that until <tt>n==1</tt>.
iterateAssociative :: (a -> a -> a) -> a -> [a]

-- | This is equal to <a>iterateAssociative</a>. The idea is the following:
--   The list we search is the fixpoint of the function: <a>Square all
--   elements of the list, then spread it and fill the holes with
--   successive numbers of their left neighbour.</a> This also preserves
--   log n applications per value. However it has a space leak, because for
--   the value with index <tt>n</tt> all elements starting at <tt>div n
--   2</tt> must be kept.
iterateLeaky :: (a -> a -> a) -> a -> [a]

module Data.Record.HT

-- | Lexicographically compare a list of attributes of two records.
--   
--   Example:
--   
--   <pre>
--   compare [comparing fst, comparing snd]
--   </pre>
compare :: [a -> a -> Ordering] -> a -> a -> Ordering

-- | Check whether a selected set of fields of two records is equal.
--   
--   Example:
--   
--   <pre>
--   equal [equating fst, equating snd]
--   </pre>
equal :: [a -> a -> Bool] -> a -> a -> Bool

module Data.String.HT

-- | remove leading and trailing spaces
trim :: String -> String

module Data.List.Match

-- | Make a list as long as another one
take :: [b] -> [a] -> [a]

-- | Drop as many elements as the first list is long
drop :: [b] -> [a] -> [a]
splitAt :: [b] -> [a] -> ([a], [a])
replicate :: [a] -> b -> [b]

-- | Compare the length of two lists over different types. It is equivalent
--   to <tt>(compare (length xs) (length ys))</tt> but more efficient.
compareLength :: [a] -> [b] -> Ordering

-- | <tt>lessOrEqualLength x y</tt> is almost the same as <tt>compareLength
--   x y &lt;= EQ</tt>, but <tt>lessOrEqualLength [] undefined = True</tt>,
--   whereas <tt>compareLength [] undefined &lt;= EQ = undefined</tt>.
lessOrEqualLength :: [a] -> [b] -> Bool

-- | Returns the shorter one of two lists. It works also for infinite lists
--   as much as possible. E.g. <tt>shortList (shorterList (repeat 1)
--   (repeat 2)) [1,2,3]</tt> can be computed. The trick is, that the
--   skeleton of the resulting list is constructed using <a>zipWith</a>
--   without touching the elements. The contents is then computed (only) if
--   requested.
shorterList :: [a] -> [a] -> [a]
