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


-- | Some useful functions and shorthands.
--   
--   A library of some useful functions and some other short-hand or alias
--   functions which I commonly use to make coding quicker and easier. This
--   also includes a lightweight implementation of a dictionary using
--   Data.Map.
@package Useful
@version 0.0.5


-- | A lightweight Dictionary implementation based on Data.Map, part of the
--   <a>Useful</a> module.
--   
--   I like dictionaries, and use them often for small things when I'm
--   coding, but the functions and syntax by default are hardly as elegant
--   as something like python. This is one thing I feel is missing in the
--   default implementation of data types. Also, the clashing namespace
--   when importing Data.Map makes code often hard to read and long.
--   Completely inconvenient for small, simple tasks. This isn't a complete
--   solution and nor is it optimal but it's lightweight and pretty. Keys
--   must have some ordering defined over them. In the function
--   descriptions, listed in square brackets are the Data.Map functions
--   used - this does not mean it is an exact alias though, it make just
--   use it.
module Useful.Dictionary

-- | Alias of Data.Map.fromList, takes a list of key value tuples and
--   creates a dictionary out of them.
--   
--   <pre>
--   dict [("hello",1),("there",2)]
--   fromList [("hello",1),("there",2)]
--   dict []
--   fromList []
--   </pre>
dict :: Ord k => [(k, a)] -> Map k a

-- | Returns a List of key-value pairs
dictToList :: Map k a -> [(k, a)]

-- | Returns the size of a dictionary [Data.Map.size]
dictSize :: Map k a -> Int

-- | Returns Maybe v from key k [Data.Map.lookup]
(#!) :: Ord k => k -> Map k a -> Maybe a

-- | Returns v from key k or error [Data.Map.!]
(#!!) :: Ord k => Map k a -> k -> a

-- | Adds key-value pair to a dictionary. If key is already in dict will
--   update value. [Data.Map.insert]
(#+) :: Ord k => Map k a -> (k, a) -> Map k a

-- | Checks for a key in a dictionary. [Data.Map.member]
(#?) :: Ord k => Map k a -> k -> Bool

-- | Checks if a value is in a dictionary
(#*?) :: (Eq a, Ord k) => Map k a -> a -> Bool

-- | Deletes a key-pair from a dictionary given a key [Data.Map.delete]
(#-) :: Ord k => Map k a -> k -> Map k a

-- | Deletes ALL key-pairs from a dictionary given they match a value
--   [Data.Map.filter]
(#*-) :: (Eq a, Ord k) => Map k a -> a -> Map k a

-- | Intersects two dictionaries [Data.Map.\]
(#\\) :: Ord k => Map k a -> Map k b -> Map k a

-- | Unions two dictionaries [Data.Map.union]
(#++) :: Ord k => Map k a -> Map k a -> Map k a

-- | Tests if d1 is a sub-dictionary of d2 [Data.Map.isSubmapOf]
(#??) :: (Ord k, Eq a) => Map k a -> Map k a -> Bool

-- | Returns a the first occurance of a key from a value. Otherwise error.
(#?!) :: (Eq a, Ord k) => Map k a -> a -> k

-- | Maps a function to all values in a dictionary [Data.Map.map]
mapD :: (a -> b) -> Map k a -> Map k b

-- | Maps a function to all keys in a dictionary [Data.Map.mapKeys]
mapDkeys :: Ord k2 => (k1 -> k2) -> Map k1 a -> Map k2 a

-- | Filter over dictionary values [Data.Map.filter]
filterD :: Ord k => (a -> Bool) -> Map k a -> Map k a

-- | Filter over keys in a dictionary [Data.Map.filterWithKey]
filterDkeys :: Ord k => (k -> a -> Bool) -> Map k a -> Map k a


-- | General shorthands and other small operations. Part of the
--   <a>Useful</a> module.
module Useful.General

-- | Alias of as /= (not equal to)
(!=) :: Eq a => a -> a -> Bool

-- | Alias of mod
(%) :: Integral a => a -> a -> a

-- | Works like python's "in" function. (Alias of elem). Simply checks if
--   an item is in a list.
--   
--   <pre>
--   $ "Hello" ? ["Hello","there","people"]
--   True
--   $ "Bonjour" ? ["Hello","there","people"]
--   False
--   </pre>
(?) :: Eq a => a -> [a] -> Bool

-- | Alias of as isInFixOf. Checks if list is a sublist of another list
--   
--   <pre>
--   $ "hello" ?? "Why hello there people"
--   True
--   $ [2,3] ?? [1,2,3,4]
--   True
--   $ "bonjour" ?? "why hello there people"
--   False 
--   </pre>
(??) :: Eq a => [a] -> [a] -> Bool

-- | Returns the index of the first occurance of an item if it is in a
--   list. Otherwise gives an error. Starts counting from 0!
--   
--   NOTE: This is not like elemIndex! It does not return a Maybe Int it
--   returns an error if the item is not in a list. Either use elemIndex or
--   test using ? first.
--   
--   <pre>
--   $ 'n' ?! "banana"
--   2
--   $ 'v' ?! "banana"
--   *** Exception: Item not in list
--   </pre>
(?!) :: Eq a => a -> [a] -> Int

-- | Takes a list and a pair (x,y) and inserts the item y into the list at
--   position x
--   
--   <pre>
--   $ ["hello","there","people"]  !/ (0,"bonjour")
--   ["bonjour","there","people"]
--   </pre>
(!/) :: [a] -> (Int, a) -> [a]

-- | Like !! but returns Maybe a
--   
--   <pre>
--   $ [1,2,3,4] ! 5
--   Nothing
--   $ [1,2,3,4] ! 1
--   Just 2
--   </pre>
(!) :: [a] -> Int -> Maybe a

-- | alias of length
len :: [a] -> Int

-- | alias of length
count :: [a] -> Int

-- | Takes the unit list and returns the unit
--   
--   NOTE: Will return an error if not supplied with the unit list
--   
--   <pre>
--   $ the ["hello"]
--   "hello"
--   $ the ["hello","there"]
--   "*** Exception: function 'the' called with a list other than the unit list.
--   </pre>
the :: [a] -> a


-- | List operations, part of the <a>Useful</a> module.
module Useful.List

-- | Takes a list item and splits a list around it, removing the item.
--   
--   <pre>
--   $ explodeI "Hello there people" ' '
--   ["Hello","there","people"]
--   </pre>
explodeI :: Eq a => [a] -> a -> [[a]]

-- | Alias of explodeI
splitI :: Eq a => [a] -> a -> [[a]]

-- | Take a list item and concatinates each element of it around another
--   given item.
--   
--   <pre>
--   $implodeI "askjdnaskd" '!'
--   "a!s!k!j!d!n!a!s!k!d"
--   </pre>
implodeI :: Eq a => [a] -> a -> [a]

-- | alias of implodeI
joinI :: Eq a => [a] -> a -> [a]

-- | Takes a two lists and explodes the first into a new list, around the
--   second. Removing the second list where it occurs.
--   
--   <pre>
--   $explode "hello there people" "ll"
--   ["he","o there people"]
--   $explode "hello there people" " "
--   ["hello","there","people"]
--   </pre>
explode :: Eq a => [a] -> [a] -> [[a]]

-- | alias of explode
split :: Eq a => [a] -> [a] -> [[a]]

-- | Takes a list of lists and an extra list and concatinates the list of
--   lists with the second list inbetween. When used with the empty list
--   mimics concat
--   
--   <pre>
--   $ implode ["helloasdad","asd hello","hello"] "!!"
--   "helloasdad!!asd hello!!hello"
--   </pre>
implode :: Eq a => [[a]] -> [a] -> [a]

-- | Alias of implode
join :: Eq a => [[a]] -> [a] -> [a]

-- | In a list of lists this removes any occurances of the empty list. Can
--   also be used to remove occurances of the empty string.
--   
--   <pre>
--   $rmEmpty ["hello","","there","","people",""]
--   ["hello","there","people"]
--   </pre>
rmEmpty :: Eq a => [[a]] -> [[a]]

-- | maps a function in depth N to the given list. map3, map4, map5 are
--   also defined.
--   
--   <pre>
--   $ map2 (*2) [[1,2,3,4],[1,1,1,2]]
--   [[2,4,6,8],[2,2,2,4]]
--   </pre>
map2 :: (a -> b) -> [[a]] -> [[b]]
map3 :: (a -> b) -> [[[a]]] -> [[[b]]]
map4 :: (a -> b) -> [[[[a]]]] -> [[[[b]]]]
map5 :: (a -> b) -> [[[[[a]]]]] -> [[[[[b]]]]]

-- | Replaces any occurrences of the second list, with the third list, in
--   the first list.
--   
--   <pre>
--   $ replace "why hello hello there" "hello" "bonjour"
--   "why bonjour bonjour there"
--   </pre>
replace :: Eq a => [a] -> [a] -> [a] -> [a]

-- | Takes a list of items and returns a list with each element in it's own
--   single list.
--   
--   <pre>
--   $ each "hello"
--   ["h","e","l","l","o"]
--   </pre>
each :: [a] -> [[a]]


-- | String operations, part of the <a>Useful</a> module.
module Useful.String

-- | Strips whitespace from either side of a string.
--   
--   <pre>
--   $ strip " \v\r  asdsadasds   \r\n"
--   "asdsadasds"	
--   </pre>
strip :: String -> String

-- | Strips whitespace from the right of a string
--   
--   <pre>
--   $ stripr "  asdioamlksd   \n\n"
--   "  asdioamlksd"
--   </pre>
stripr :: String -> String

-- | Strips whitespace from the left of a string
--   
--   <pre>
--   $ stripl " \n\n  askdjnasdnaskd"
--   "askdjnasdnaskd"
--   </pre>
stripl :: String -> String

-- | Alias of <a>strip</a>
chomp :: String -> String

-- | List of whitespace characters:
--   
--   <pre>
--   $whiteSpaceChars
--   [' ','\r','\n','\t','\f','\v']
--   </pre>
whiteSpaceChars :: [Char]


-- | IO operations, part of the <a>Useful</a> module.
module Useful.IO

-- | repeats an IO function n number of times.
replicateM :: Monad m => Int -> m a -> m [a]

-- | Like replicateM but stores the returns
replicateM_ :: Monad m => Int -> m a -> m ()

-- | repeats an IO function for every member of a list, using the list item
--   as an arguement
--   
--   <pre>
--   $ do foreach [1..3] print
--   1
--   2
--   3
--   $ do foreach "asjkdnsd" putChar
--   asjkdnsd
--   </pre>
foreach :: Monad m => [a] -> (a -> m b) -> m ()

-- | repeats an IO function until a IO Bool is true
--   
--   NOTE: Be careful with this function! Better to use recursion. Testing
--   against an item created in the loop will not work.
while :: Monad m => m Bool -> m a -> m ()

-- | like putStr or putChar but works on any type with "show" defined in a
--   similar way to how print does. Can be thought of as "print" without
--   the trailing linebreak.
--   
--   NOTE: This means it will print strings with quotes around them. To
--   print strings without quotes use putStr or putStrLn
put :: Show a => a -> IO ()

-- | Alias of put
write :: Show a => a -> IO ()

-- | Alias of print
writeln :: Show a => a -> IO ()

-- | Alias of print
putln :: Show a => a -> IO ()

-- | maps an IO function in depth N to the given list. Also versions
--   without _ for storing of the returns.
--   
--   Again there are also mapM_3, mapM_4 and mapM_5 defined (as well as
--   versions without underscores)
--   
--   <pre>
--   $ mapM_2 write [[1,2,3,4,5],[1,2]]
--   1234512
--   </pre>
mapM_2 :: Monad m => (a -> m b) -> [[a]] -> m ()

-- | takes a list and returns a random element from that list
--   
--   <pre>
--   $ rand [1..5]
--   5
--   $ rand "hello there people"
--   'l'
--   </pre>
rand :: [a] -> IO a

module Useful