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


-- | General purpose utility library
--   
--   A miscellaneous collection of re-usable functions and data structures.
--   Many of Rosso's modules are direct extensions of the Haskell base
--   libraries; for example, Data.Map.Rosso1 extends Data.Map,
--   Control.Monad.Rosso1 extends Control.Monad, etc.
--   
--   Rosso is designed to remain backward-compatible with any client code
--   that works with an older version of itself. To this end, all module
--   names include explicit version numbers.
@package rosso
@version 1.0


-- | Extends <a>System.IO</a>
module System.IO.Rosso1

-- | Like <a>readFile</a>, but reads the entire contents of the file into
--   the string, and then closes the file, before the computation
--   completes.
readFileStrict :: FilePath -> IO String


-- | Extends <a>Data.Set</a>
module Data.Set.Rosso1

-- | Inserts each element of the list into the set in turn, from left to
--   right.
insertMany :: Ord a => [a] -> Set a -> Set a


-- | Extends <a>Data.Tuple</a>
module Data.Tuple.Rosso1

-- | Applies a function to the first component of a pair.
mapFst :: (a -> c) -> (a, b) -> (c, b)

-- | Applies a function to the second component of a pair.
mapSnd :: (b -> c) -> (a, b) -> (a, c)

-- | Applies a pair of functions to a pair of values.
pairApply :: (a -> c) -> (b -> d) -> (a, b) -> (c, d)


-- | Extends <a>Data.Maybe</a>
module Data.Maybe.Rosso1

-- | Dual of <a>fromMaybe</a>. Wraps the value in <a>Just</a> if the
--   predicate succeeds, otherwise returns <a>Nothing</a>.
toMaybe :: (a -> Bool) -> a -> Maybe a


-- | Extends <a>Data.Map</a>
module Data.Map.Rosso1

-- | Passes down the list from left to right, inserting each entry into the
--   map.
insertMany :: Ord k => [(k, a)] -> Map k a -> Map k a

-- | Simultaneous lookup and delete.
extract :: Ord k => k -> Map k a -> (Maybe a, Map k a)


-- | <a>MultiMap</a> data structure: similar to a map (<a>Data.Map</a>),
--   but allows multiple values with the same key.
module Data.MultiMap.Rosso1
data MultiMap k a

-- | Converts an association list into a multimap. If the association list
--   contains duplicate keys, then the corresponding lists of values become
--   concatenated.
--   
--   <pre>
--   &gt;&gt;&gt; fromList [(4, "dca"), (1, "aba"), (2, "b"), (1, "ac"), (3, "")]
--   fromList [(1,"abaac"),(2,"b"),(4,"dca")]
--   </pre>
fromList :: Ord k => [(k, [a])] -> MultiMap k a

-- | Converts a multimap into an association list, with the keys in
--   ascending order.
--   
--   <pre>
--   &gt;&gt;&gt; toList $ fromList [(4, "dca"), (1, "aba"), (2, "b"), (1, "ac"), (3, "")]
--   [(1,"abaac"),(2,"b"),(4,"dca")]
--   </pre>
toList :: MultiMap k a -> [(k, [a])]

-- | The empty multimap.
empty :: MultiMap k a

-- | A multimap with a single entry.
singleton :: k -> a -> MultiMap k a

-- | Inserts a new key-value pair. If other entries already exist with the
--   same key, then the new entry is inserted just before them.
--   
--   <pre>
--   &gt;&gt;&gt; insert 2 'a' $ fromList [(1, "efg"), (2, "jzw"), (3, "abc")]
--   fromList [(1,"efg"),(2,"ajzw"),(3,"abc")]
--   </pre>
insert :: Ord k => k -> a -> MultiMap k a -> MultiMap k a

-- | Passes down the list from left to right, inserting each entry into the
--   multimap.
--   
--   <pre>
--   &gt;&gt;&gt; insertMany [(1, 'a'), (5, 'a'), (1, 'a'), (1, 'b')] empty
--   fromList [(1,"baa"),(5,"a")]
--   </pre>
insertMany :: Ord k => [(k, a)] -> MultiMap k a -> MultiMap k a

-- | Prepends a list of values onto the entry with the given key.
--   
--   <pre>
--   &gt;&gt;&gt; insertList 7 "hello" $ fromList [(5, "ab"), (7, "efg")]
--   fromList [(5,"ab"),(7,"helloefg")]
--   </pre>
insertList :: Ord k => k -> [a] -> MultiMap k a -> MultiMap k a

-- | Passes down the given list from left to right invoking
--   <a>insertList</a>.
insertManyLists :: Ord k => [(k, [a])] -> MultiMap k a -> MultiMap k a

-- | Tests if the multimap is empty.
null :: MultiMap k a -> Bool

-- | Returns the list of values associated with the given key.
--   
--   <pre>
--   &gt;&gt;&gt; lookup 5 $ fromList [(1, "abc"), (5, "aagf"), (6, "c")]
--   "aagf"
--   </pre>
lookup :: Ord k => k -> MultiMap k a -> [a]

-- | Deletes all the values associated with the given key.
deleteList :: Ord k => k -> MultiMap k a -> MultiMap k a

-- | Simultaneous lookup and deleteList.
extractList :: Ord k => k -> MultiMap k a -> ([a], MultiMap k a)

-- | For each key that maps to a non-empty list of values, returns that key
--   and its corresponding values as well as the multimap with those values
--   removed. The keys are enumerated in ascending order.
extractEachListWithKey :: Ord k => MultiMap k a -> [((k, [a]), MultiMap k a)]

-- | Modifies the list of values associated with a given key.
alter :: Ord k => ([a] -> [a]) -> k -> MultiMap k a -> MultiMap k a

-- | Returns <a>Nothing</a> if the multimap is empty, otherwise returns the
--   first value associated with the maximal key of the multimap, and the
--   multimap stripped of that value.
--   
--   <pre>
--   &gt;&gt;&gt; maxView $ fromList [(1, "ab"), (2, "efg")]
--   Just ('e',fromList [(1,"ab"),(2,"fg")])
--   </pre>
maxView :: MultiMap k a -> Maybe (a, MultiMap k a)

-- | Returns all of the values in the multimap in ascending order of their
--   keys.
--   
--   <pre>
--   &gt;&gt;&gt; elems $ fromList [(1, "aba"), (2, "adf"), (3, "z")]
--   "abaadfz"
--   </pre>
elems :: MultiMap k a -> [a]

-- | Returns all of the values in the multimap in descending order of their
--   keys. The values are enumerated in the same order as with
--   <a>maxView</a>.
--   
--   <pre>
--   &gt;&gt;&gt; descElems $ fromList [(1, "aba"), (2, "adf"), (3, "z")]
--   "zadfaba"
--   </pre>
descElems :: MultiMap k a -> [a]

-- | Returns all of the key-value pairs in the multimap in ascending order
--   of keys.
--   
--   <pre>
--   &gt;&gt;&gt; assocs $ fromList [(1, "ab"), (4, "cda")]
--   [(1,'a'),(1,'b'),(4,'c'),(4,'d'),(4,'a')]
--   </pre>
assocs :: MultiMap k a -> [(k, a)]

-- | Returns all of the key-value pairs in the multimap in descending order
--   of keys. The values are enumerated in the same order as with
--   <a>maxView</a>.
--   
--   <pre>
--   &gt;&gt;&gt; descAssocs (fromList [(1, "ab"), (4, "cda")])
--   [(4,'c'),(4,'d'),(4,'a'),(1,'a'),(1,'b')]
--   </pre>
descAssocs :: MultiMap k a -> [(k, a)]
instance (Show k, Show a) => Show (MultiMap k a)


-- | Extends <a>Data.List</a>
module Data.List.Rosso1

-- | Returns a list of lists, each obtained by dropping a single element of
--   the argument.
--   
--   <pre>
--   &gt;&gt;&gt; dropEachElem "abcd"
--   ["bcd","acd","abd","abc"]
--   </pre>
dropEachElem :: [a] -> [[a]]

-- | Similar to <a>dropEachElem</a>, but each output list is paired with
--   the element that was dropped.
--   
--   <pre>
--   &gt;&gt;&gt; extractEachElem "abcd"
--   [('a',"bcd"),('b',"acd"),('c',"abd"),('d',"abc")]
--   </pre>
extractEachElem :: [a] -> [(a, [a])]

-- | Sorts, then groups the elements of a list, using a specified key
--   function. The sorting process is stable, i.e. elements with equal keys
--   remain in the same order.
--   
--   <pre>
--   &gt;&gt;&gt; sortAndGroupOn (`mod` 3) [1..10]
--   [[3,6,9],[1,4,7,10],[2,5,8]]
--   </pre>
sortAndGroupOn :: Ord b => (a -> b) -> [a] -> [[a]]

-- | Collects together the list of values corresponding to each unique key
--   in an association list. Entries in the output list are arranged in
--   ascending order of key. The ordering of values corresponding to a
--   given key is preserved from input to output.
--   
--   <pre>
--   &gt;&gt;&gt; alistCollect [(7, 'a'), (3, 'a'), (5, 'x'), (3, 'a'), (3, 'b')]
--   [(3,"aab"),(5,"x"),(7,"a")]
--   </pre>
alistCollect :: Ord k => [(k, a)] -> [(k, [a])]

-- | Filters a list of values according to a list of corresponding boolean
--   flags.
--   
--   <pre>
--   &gt;&gt;&gt; zipFilter [False, True, False, True, True] [0..]
--   [1,3,4]
--   </pre>
zipFilter :: [Bool] -> [a] -> [a]


-- | Extends <a>Data.Either</a>
module Data.Either.Rosso1

-- | Applies a function to the left component.
mapLeft :: (a -> c) -> Either a b -> Either c b

-- | Applies a function to the right component.
mapRight :: (b -> c) -> Either a b -> Either a c


-- | Extends <a>Data.Bool</a>
module Data.Bool.Rosso1

-- | Exclusive OR.
xor :: Bool -> Bool -> Bool


-- | Extends <a>Control.Monad</a>
module Control.Monad.Rosso1

-- | Synonym for <tt>return ()</tt>
nop :: Monad m => m ()

-- | Monadic generalisation of <a>concatMap</a>.
concatMapM :: Monad m => (a -> m [b]) -> [a] -> m [b]

-- | Monadic generalisation of 'if'.
ifM :: Monad m => m Bool -> m a -> m a -> m a

-- | Like <a>when</a>, but the condition is also monadic.
whenM :: Monad m => m Bool -> m () -> m ()