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


-- | A lightweight Dictionary implementation based on Data.Map, part of the
--   <a>Useful</a> module.
--   
--   So I kinda like dictionaries, but the functions and syntax by default
--   are hardly as elegant as something like python. This isn't a complete
--   solution and nor is it optimal but it's pretty lightweight and pretty
--   and stuff. You get it. It's based off Data.Map so uses a binary tree
--   and therefore the keys have to have some ordering defined over them.
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 Maybe v from key k
(#!) :: (Ord k) => k -> Map k a -> Maybe a

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

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

-- | checks for a key in a dictionary.
(#?) :: (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
(#-) :: (Ord k) => Map k a -> k -> Map k a

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

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

-- | Unions two dictionaries
(#++) :: (Ord k) => Map k a -> Map k a -> Map k a

-- | Tests if d1 is a sub-dictionary of d2
(#??) :: (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

-- | Returns the size of a dictionary
dictSize :: Map k a -> Int

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

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

-- | filter on a dincationy, you get the idea
filterD :: (Ord k) => (a -> Bool) -> Map k a -> Map k a

-- | filter for keys
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
--   
--   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. Also remember, 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. THIS FUNCTION IS NOT COMPLETE.
--   
--   <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

-- | Simple function that 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


-- | Useful 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.
--   
--   THIS NEEDS FIXING
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]

-- | takes n number of items from the front of a list, alias of take
--   
--   <pre>
--   $ takeFor 5 "Hello there people"
--   "Hello"
--   </pre>
takeFor :: (Eq a) => Int -> [a] -> [a]

-- | drops n number of items from the front of a list, alias of drop
--   
--   <pre>
--   $ dropFor 5 "Hello there people"
--   " there people"
--   </pre>
dropFor :: (Eq a) => Int -> [a] -> [a]

-- | takes a number of items from a list before it reaches the index n
--   
--   <pre>
--   $ takeBefore 5 "Hello there people"
--   "Hello there p"
--   </pre>
takeBefore :: (Eq a) => Int -> [a] -> [a]

-- | drops a number of items from a list before it reaches the index n
--   
--   <pre>
--   $ dropBefore 5 "Hello there people"
--   "eople"
--   </pre>
dropBefore :: (Eq a) => Int -> [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.
rmEmptyList :: (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]]

-- | Replaces any occuranses 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 "   asdsadasds   \r\n" \n
--   "asdsadasds"	
--   </pre>
strip :: String -> String

-- | Strips whitespace from the right of a string
--   
--   <pre>
--   $ stripr "  asdioamlksd   \n\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>
--   [' ','\r','\n','\t']
--   </pre>
stripset :: [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 ()
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


-- | These are a selection of useful haskell functions which I've written.
--   
--   It is split into 5 sections so as to allow you to import just one if
--   you think the whole lot will clutter up the namepsace.
--   
--   <ul>
--   <li><a>Useful.General</a> - General shorthands and the most commonly
--   used.</li>
--   <li><a>Useful.Dictionary</a> - A lightweight dictionary implementation
--   using Data.Map</li>
--   <li><a>Useful.List</a> - Some general purpose list functions which are
--   missing from Data.List as well as some other shorthands/aliases</li>
--   <li><a>Useful.String</a> - A few string only functions which don't
--   make sense over just lists</li>
--   <li><a>Useful.IO</a> - Some shorthand and general purpose IO
--   functions</li>
--   </ul>
module Useful