Ticket #1611: Map.diff

Data/IntMap.hs

@@ -1 @@
-{-# OPTIONS -cpp -fglasgow-exts -fno-bang-patterns #-} 
+{-TODO - enable # OPTIONS -cpp -fglasgow-exts -fno-bang-patterns #-} 
 -----------------------------------------------------------------------------
 -- |
 -- Module      :  Data.IntMap
@@ -30 +30 @@
 --      Information Coded In Alphanumeric/\", Journal of the ACM, 15(4),
 --      October 1968, pages 514-534.
 --
+-- Operation comments contain the operation time complexity in
+-- the Big-O notation <http://en.wikipedia.org/wiki/Big_O_notation>.
 -- Many operations have a worst-case complexity of /O(min(n,W))/.
 -- This means that the operation can become linear in the number of
 -- elements with a maximum of /W/ -- the number of bits in an 'Int'
@@ -215 +217 @@
   Operators
 --------------------------------------------------------------------}
 
--- | /O(min(n,W))/. Find the value at a key.
--- Calls 'error' when the element can not be found.
+-- | Find the value at a key.
+-- Calls 'error' when the element can not be found. /O(min(n,W))/.
 
 (!) :: IntMap a -> Key -> a
 m ! k    = find' k m
 
--- | /O(n+m)/. See 'difference'.
+-- | See 'difference'. /O(n+m)/.
 (\\) :: IntMap a -> IntMap b -> IntMap a
 m1 \\ m2 = difference m1 m2
 
@@ -268 +270 @@
 {--------------------------------------------------------------------
   Query
 --------------------------------------------------------------------}
--- | /O(1)/. Is the map empty?
+-- | Is the map empty? /O(1)/.
 null :: IntMap a -> Bool
 null Nil   = True
 null other = False
 
--- | /O(n)/. Number of elements in the map.
+-- | Number of elements in the map. /O(n)/.
 size :: IntMap a -> Int
 size t
   = case t of
@@ -281 +283 @@
       Tip k x -> 1
       Nil     -> 0
 
--- | /O(min(n,W))/. Is the key a member of the map?
+-- | Is the key a member of the map? /O(min(n,W))/.
 member :: Key -> IntMap a -> Bool
 member k m
   = case lookup k m of
       Nothing -> False
       Just x  -> True
     
--- | /O(log n)/. Is the key not a member of the map?
+-- | Is the key not a member of the map? /O(log n)/.
 notMember :: Key -> IntMap a -> Bool
 notMember k m = not $ member k m
 
--- | /O(min(n,W))/. Lookup the value at a key in the map.
+-- | Lookup the value at a key in the map. /O(min(n,W))/.
 lookup :: (Monad m) => Key -> IntMap a -> m a
 lookup k t = case lookup' k t of
     Just x -> return x
@@ -320 +322 @@
       Just x  -> x
 
 
--- | /O(min(n,W))/. The expression @('findWithDefault' def k map)@
+-- | The expression @('findWithDefault' def k map)@
 -- returns the value at key @k@ or returns @def@ when the key is not an
--- element of the map.
+-- element of the map. /O(min(n,W))/.
 findWithDefault :: a -> Key -> IntMap a -> a
 findWithDefault def k m
   = case lookup k m of
@@ -332 +334 @@
 {--------------------------------------------------------------------
   Construction
 --------------------------------------------------------------------}
--- | /O(1)/. The empty map.
+-- | The empty map. /O(1)/.
 empty :: IntMap a
 empty
   = Nil
 
--- | /O(1)/. A map of one element.
+-- | A map of one element. /O(1)/.
 singleton :: Key -> a -> IntMap a
 singleton k x
   = Tip k x
@@ -345 +347 @@
 {--------------------------------------------------------------------
   Insert
 --------------------------------------------------------------------}
--- | /O(min(n,W))/. Insert a new key\/value pair in the map.
+-- | Insert a new key\/value pair in the map.
 -- If the key is already present in the map, the associated value is
 -- replaced with the supplied value, i.e. 'insert' is equivalent to
--- @'insertWith' 'const'@.
+-- @'insertWith' 'const'@. /O(min(n,W))/.
 insert :: Key -> a -> IntMap a -> IntMap a
 insert k x t
   = case t of
@@ -362 +364 @@
       Nil -> Tip k x
 
 -- right-biased insertion, used by 'union'
--- | /O(min(n,W))/. Insert with a combining function.
+-- | Insert with a combining function.
 -- @'insertWith' f key value mp@ 
 -- will insert the pair (key, value) into @mp@ if key does
 -- not exist in the map. If the key does exist, the function will
--- insert @f new_value old_value@.
+-- insert @f new_value old_value@. /O(min(n,W))/.
 insertWith :: (a -> a -> a) -> Key -> a -> IntMap a -> IntMap a
 insertWith f k x t
   = insertWithKey (\k x y -> f x y) k x t
 
--- | /O(min(n,W))/. Insert with a combining function.
+-- | Insert with a combining function.
 -- @'insertWithKey' f key value mp@ 
 -- will insert the pair (key, value) into @mp@ if key does
 -- not exist in the map. If the key does exist, the function will
--- insert @f key new_value old_value@.
+-- insert @f key new_value old_value@. /O(min(n,W))/.
 insertWithKey :: (Key -> a -> a -> a) -> Key -> a -> IntMap a -> IntMap a
 insertWithKey f k x t
   = case t of
@@ -389 +391 @@
       Nil -> Tip k x
 
 
--- | /O(min(n,W))/. The expression (@'insertLookupWithKey' f k x map@)
+-- | The expression (@'insertLookupWithKey' f k x map@)
 -- is a pair where the first element is equal to (@'lookup' k map@)
--- and the second element equal to (@'insertWithKey' f k x map@).
+-- and the second element equal to (@'insertWithKey' f k x map@). /O(min(n,W))/.
 insertLookupWithKey :: (Key -> a -> a -> a) -> Key -> a -> IntMap a -> (Maybe a, IntMap a)
 insertLookupWithKey f k x t
   = case t of
@@ -409 +411 @@
   Deletion
   [delete] is the inlined version of [deleteWith (\k x -> Nothing)]
 --------------------------------------------------------------------}
--- | /O(min(n,W))/. Delete a key and its value from the map. When the key is not
--- a member of the map, the original map is returned.
+-- | Delete a key and its value from the map. When the key is not
+-- a member of the map, the original map is returned. /O(min(n,W))/.
 delete :: Key -> IntMap a -> IntMap a
 delete k t
   = case t of
@@ -423 +425 @@
         | otherwise     -> t
       Nil -> Nil
 
--- | /O(min(n,W))/. Adjust a value at a specific key. When the key is not
--- a member of the map, the original map is returned.
+-- | Adjust a value at a specific key. When the key is not
+-- a member of the map, the original map is returned. /O(min(n,W))/.
 adjust ::  (a -> a) -> Key -> IntMap a -> IntMap a
 adjust f k m
   = adjustWithKey (\k x -> f x) k m
 
--- | /O(min(n,W))/. Adjust a value at a specific key. When the key is not
--- a member of the map, the original map is returned.
+-- | Adjust a value at a specific key. When the key is not
+-- a member of the map, the original map is returned. /O(min(n,W))/.
 adjustWithKey ::  (Key -> a -> a) -> Key -> IntMap a -> IntMap a
 adjustWithKey f k m
   = updateWithKey (\k x -> Just (f k x)) k m
 
--- | /O(min(n,W))/. The expression (@'update' f k map@) updates the value @x@
+-- | The expression (@'update' f k map@) updates the value @x@
 -- at @k@ (if it is in the map). If (@f x@) is 'Nothing', the element is
 -- deleted. If it is (@'Just' y@), the key @k@ is bound to the new value @y@.
+-- /O(min(n,W))/.
 update ::  (a -> Maybe a) -> Key -> IntMap a -> IntMap a
 update f k m
   = updateWithKey (\k x -> f x) k m
 
--- | /O(min(n,W))/. The expression (@'update' f k map@) updates the value @x@
+-- | The expression (@'update' f k map@) updates the value @x@
 -- at @k@ (if it is in the map). If (@f k x@) is 'Nothing', the element is
 -- deleted. If it is (@'Just' y@), the key @k@ is bound to the new value @y@.
+-- /O(min(n,W))/.
 updateWithKey ::  (Key -> a -> Maybe a) -> Key -> IntMap a -> IntMap a
 updateWithKey f k t
   = case t of
@@ -459 +463 @@
         | otherwise     -> t
       Nil -> Nil
 
--- | /O(min(n,W))/. Lookup and update.
+-- | Lookup and update. /O(min(n,W))/.
 updateLookupWithKey ::  (Key -> a -> Maybe a) -> Key -> IntMap a -> (Maybe a,IntMap a)
 updateLookupWithKey f k t
   = case t of
@@ -476 +480 @@
 
 
 
--- | /O(log n)/. The expression (@'alter' f k map@) alters the value @x@ at @k@, or absence thereof.
+-- | The expression (@'alter' f k map@) alters the value @x@ at @k@, or absence thereof.
 -- 'alter' can be used to insert, delete, or update a value in a 'Map'.
--- In short : @'lookup' k ('alter' f k m) = f ('lookup' k m)@
+-- In short : @'lookup' k ('alter' f k m) = f ('lookup' k m)@. /O(log n)/.
 alter f k t
   = case t of
       Bin p m l r 
@@ -512 +516 @@
 unionsWith f ts
   = foldlStrict (unionWith f) empty ts
 
--- | /O(n+m)/. The (left-biased) union of two maps. 
+-- | The (left-biased) union of two maps. 
 -- It prefers the first map when duplicate keys are encountered,
--- i.e. (@'union' == 'unionWith' 'const'@).
+-- i.e. (@'union' == 'unionWith' 'const'@). /O(n+m)/.
 union :: IntMap a -> IntMap a -> IntMap a
 union t1@(Bin p1 m1 l1 r1) t2@(Bin p2 m2 l2 r2)
   | shorter m1 m2  = union1
@@ -535 +539 @@
 union Nil t       = t
 union t Nil       = t
 
--- | /O(n+m)/. The union with a combining function. 
+-- | The union with a combining function. /O(n+m)/.
 unionWith :: (a -> a -> a) -> IntMap a -> IntMap a -> IntMap a
 unionWith f m1 m2
   = unionWithKey (\k x y -> f x y) m1 m2
 
--- | /O(n+m)/. The union with a combining function. 
+-- | The union with a combining function. /O(n+m)/.
 unionWithKey :: (Key -> a -> a -> a) -> IntMap a -> IntMap a -> IntMap a
 unionWithKey f t1@(Bin p1 m1 l1 r1) t2@(Bin p2 m2 l2 r2)
   | shorter m1 m2  = union1
@@ -564 +568 @@
 {--------------------------------------------------------------------
   Difference
 --------------------------------------------------------------------}
--- | /O(n+m)/. Difference between two maps (based on keys). 
+-- | Difference between two maps (based on keys). /O(n+m)/.
 difference :: IntMap a -> IntMap b -> IntMap a
 difference t1@(Bin p1 m1 l1 r1) t2@(Bin p2 m2 l2 r2)
   | shorter m1 m2  = difference1
@@ -588 +592 @@
 difference t (Tip k x) = delete k t
 difference t Nil       = t
 
--- | /O(n+m)/. Difference with a combining function. 
+-- | Difference with a combining function. /O(n+m)/.
 differenceWith :: (a -> b -> Maybe a) -> IntMap a -> IntMap b -> IntMap a
 differenceWith f m1 m2
   = differenceWithKey (\k x y -> f x y) m1 m2
 
--- | /O(n+m)/. Difference with a combining function. When two equal keys are
+-- | Difference with a combining function. When two equal keys are
 -- encountered, the combining function is applied to the key and both values.
 -- If it returns 'Nothing', the element is discarded (proper set difference).
 -- If it returns (@'Just' y@), the element is updated with a new value @y@. 
+-- /O(n+m)/.
 differenceWithKey :: (Key -> a -> b -> Maybe a) -> IntMap a -> IntMap b -> IntMap a
 differenceWithKey f t1@(Bin p1 m1 l1 r1) t2@(Bin p2 m2 l2 r2)
   | shorter m1 m2  = difference1
@@ -627 +632 @@
 {--------------------------------------------------------------------
   Intersection
 --------------------------------------------------------------------}
--- | /O(n+m)/. The (left-biased) intersection of two maps (based on keys). 
+-- | The (left-biased) intersection of two maps (based on keys). /O(n+m)/.
 intersection :: IntMap a -> IntMap b -> IntMap a
 intersection t1@(Bin p1 m1 l1 r1) t2@(Bin p2 m2 l2 r2)
   | shorter m1 m2  = intersection1
@@ -653 +658 @@
 intersection Nil t = Nil
 intersection t Nil = Nil
 
--- | /O(n+m)/. The intersection with a combining function. 
+-- | The intersection with a combining function. /O(n+m)/.
 intersectionWith :: (a -> b -> a) -> IntMap a -> IntMap b -> IntMap a
 intersectionWith f m1 m2
   = intersectionWithKey (\k x y -> f x y) m1 m2
 
--- | /O(n+m)/. The intersection with a combining function. 
+-- | The intersection with a combining function. /O(n+m)/.
 intersectionWithKey :: (Key -> a -> b -> a) -> IntMap a -> IntMap b -> IntMap a
 intersectionWithKey f t1@(Bin p1 m1 l1 r1) t2@(Bin p2 m2 l2 r2)
   | shorter m1 m2  = intersection1
@@ -690 +695 @@
   Min\/Max
 --------------------------------------------------------------------}
 
--- | /O(log n)/. Update the value at the minimal key.
+-- | Update the value at the minimal key. /O(log n)/.
 updateMinWithKey :: (Key -> a -> a) -> IntMap a -> IntMap a
 updateMinWithKey f t
     = case t of
@@ -704 +709 @@
         Bin p m l r -> let t' = updateMinWithKeyUnsigned f r in Bin p m l t'
         Tip k y -> Tip k (f k y)
 
--- | /O(log n)/. Update the value at the maximal key.
+-- | Update the value at the maximal key. /O(log n)/.
 updateMaxWithKey :: (Key -> a -> a) -> IntMap a -> IntMap a
 updateMaxWithKey f t
     = case t of
@@ -719 +724 @@
         Tip k y -> Tip k (f k y)
 
 
--- | /O(log n)/. Retrieves the maximal (key,value) couple of the map, and the map stripped from that element.
--- @fail@s (in the monad) when passed an empty map.
+-- | Retrieves the maximal (key,value) couple of the map, and the map stripped from that element.
+-- @fail@s (in the monad) when passed an empty map. /O(log n)/.
 maxViewWithKey :: (Monad m) => IntMap a -> m ((Key, a), IntMap a)
 maxViewWithKey t
     = case t of
@@ -734 +739 @@
         Bin p m l r -> let (result,t') = maxViewUnsigned r in (result,bin p m l t')
         Tip k y -> ((k,y), Nil)
 
--- | /O(log n)/. Retrieves the minimal (key,value) couple of the map, and the map stripped from that element.
--- @fail@s (in the monad) when passed an empty map.
+-- | Retrieves the minimal (key,value) couple of the map, and the map stripped from that element.
+-- @fail@s (in the monad) when passed an empty map. /O(log n)/.
 minViewWithKey :: (Monad m) => IntMap a -> m ((Key, a), IntMap a)
 minViewWithKey t
     = case t of
@@ -750 +755 @@
         Tip k y -> ((k,y),Nil)
 
 
--- | /O(log n)/. Update the value at the maximal key.
+-- | Update the value at the maximal key. /O(log n)/.
 updateMax :: (a -> a) -> IntMap a -> IntMap a
 updateMax f = updateMaxWithKey (const f)
 
--- | /O(log n)/. Update the value at the minimal key.
+-- | Update the value at the minimal key. /O(log n)/.
 updateMin :: (a -> a) -> IntMap a -> IntMap a
 updateMin f = updateMinWithKey (const f)
 
@@ -768 +773 @@
 first f (x,y) = (f x,y)
 
 
--- | /O(log n)/. Retrieves the maximal key of the map, and the map stripped from that element.
--- @fail@s (in the monad) when passed an empty map.
+-- | Retrieves the maximal key of the map, and the map stripped from that element.
+-- @fail@s (in the monad) when passed an empty map. /O(log n)/.
 maxView t = liftM (first snd) (maxViewWithKey t)
 
--- | /O(log n)/. Retrieves the minimal key of the map, and the map stripped from that element.
+-- | Retrieves the minimal key of the map, and the map stripped from that element.
 -- @fail@s (in the monad) when passed an empty map.
+-- /O(log n)/.
 minView t = liftM (first snd) (minViewWithKey t)
 
--- | /O(log n)/. Delete and find the maximal element.
+-- | Delete and find the maximal element. /O(log n)/.
 deleteFindMax = runIdentity . maxView
 
--- | /O(log n)/. Delete and find the minimal element.
+-- | Delete and find the minimal element. /O(log n)/.
 deleteFindMin = runIdentity . minView
 
--- | /O(log n)/. The minimal key of the map.
+-- | The minimal key of the map. /O(log n)/.
 findMin = fst . runIdentity . minView
 
--- | /O(log n)/. The maximal key of the map.
+-- | The maximal key of the map. /O(log n)/.
 findMax = fst . runIdentity . maxView
 
--- | /O(log n)/. Delete the minimal key.
+-- | Delete the minimal key. /O(log n)/.
 deleteMin = snd . runIdentity . minView
 
--- | /O(log n)/. Delete the maximal key.
+-- | Delete the maximal key. /O(log n)/.
 deleteMax = snd . runIdentity . maxView
 
 
 {--------------------------------------------------------------------
   Submap
 --------------------------------------------------------------------}
--- | /O(n+m)/. Is this a proper submap? (ie. a submap but not equal). 
--- Defined as (@'isProperSubmapOf' = 'isProperSubmapOfBy' (==)@).
+-- | Is this a proper submap? (ie. a submap but not equal). 
+-- Defined as (@'isProperSubmapOf' = 'isProperSubmapOfBy' (==)@). /O(n+m)/.
 isProperSubmapOf :: Eq a => IntMap a -> IntMap a -> Bool
 isProperSubmapOf m1 m2
   = isProperSubmapOfBy (==) m1 m2
 
-{- | /O(n+m)/. Is this a proper submap? (ie. a submap but not equal).
+{- | Is this a proper submap? (ie. a submap but not equal).
  The expression (@'isProperSubmapOfBy' f m1 m2@) returns 'True' when
  @m1@ and @m2@ are not equal,
  all keys in @m1@ are in @m2@, and when @f@ returns 'True' when
@@ -819 +825 @@
   > isProperSubmapOfBy (==) (fromList [(1,1),(2,2)]) (fromList [(1,1),(2,2)])
   > isProperSubmapOfBy (==) (fromList [(1,1),(2,2)]) (fromList [(1,1)])
   > isProperSubmapOfBy (<)  (fromList [(1,1)])       (fromList [(1,1),(2,2)])
+
+ /O(n+m)/.
 -}
 isProperSubmapOfBy :: (a -> b -> Bool) -> IntMap a -> IntMap b -> Bool
 isProperSubmapOfBy pred t1 t2
@@ -852 +860 @@
 submapCmp pred Nil Nil = EQ
 submapCmp pred Nil t   = LT
 
--- | /O(n+m)/. Is this a submap?
--- Defined as (@'isSubmapOf' = 'isSubmapOfBy' (==)@).
+-- | Is this a submap?
+-- Defined as (@'isSubmapOf' = 'isSubmapOfBy' (==)@). /O(n+m)/.
 isSubmapOf :: Eq a => IntMap a -> IntMap a -> Bool
 isSubmapOf m1 m2
   = isSubmapOfBy (==) m1 m2
 
-{- | /O(n+m)/. 
- The expression (@'isSubmapOfBy' f m1 m2@) returns 'True' if
+{- | The expression (@'isSubmapOfBy' f m1 m2@) returns 'True' if
  all keys in @m1@ are in @m2@, and when @f@ returns 'True' when
  applied to their respective values. For example, the following 
  expressions are all 'True':
@@ -873 +880 @@
   > isSubmapOfBy (==) (fromList [(1,2)]) (fromList [(1,1),(2,2)])
   > isSubmapOfBy (<) (fromList [(1,1)]) (fromList [(1,1),(2,2)])
   > isSubmapOfBy (==) (fromList [(1,1),(2,2)]) (fromList [(1,1)])
+
+ /O(n+m)/. 
 -}
 
 isSubmapOfBy :: (a -> b -> Bool) -> IntMap a -> IntMap b -> Bool
@@ -890 +899 @@
 {--------------------------------------------------------------------
   Mapping
 --------------------------------------------------------------------}
--- | /O(n)/. Map a function over all values in the map.
+-- | Map a function over all values in the map. /O(n)/.
 map :: (a -> b) -> IntMap a -> IntMap b
 map f m
   = mapWithKey (\k x -> f x) m
 
--- | /O(n)/. Map a function over all values in the map.
+-- | Map a function over all values in the map. /O(n)/.
 mapWithKey :: (Key -> a -> b) -> IntMap a -> IntMap b
 mapWithKey f t  
   = case t of
@@ -903 +912 @@
       Tip k x     -> Tip k (f k x)
       Nil         -> Nil
 
--- | /O(n)/. The function @'mapAccum'@ threads an accumulating
--- argument through the map in ascending order of keys.
+-- | The function @'mapAccum'@ threads an accumulating
+-- argument through the map in ascending order of keys. /O(n)/.
 mapAccum :: (a -> b -> (a,c)) -> a -> IntMap b -> (a,IntMap c)
 mapAccum f a m
   = mapAccumWithKey (\a k x -> f a x) a m
 
--- | /O(n)/. The function @'mapAccumWithKey'@ threads an accumulating
--- argument through the map in ascending order of keys.
+-- | The function @'mapAccumWithKey'@ threads an accumulating
+-- argument through the map in ascending order of keys. /O(n)/.
 mapAccumWithKey :: (a -> Key -> b -> (a,c)) -> a -> IntMap b -> (a,IntMap c)
 mapAccumWithKey f a t
   = mapAccumL f a t
 
--- | /O(n)/. The function @'mapAccumL'@ threads an accumulating
--- argument through the map in ascending order of keys.
+-- | The function @'mapAccumL'@ threads an accumulating
+-- argument through the map in ascending order of keys. /O(n)/.
 mapAccumL :: (a -> Key -> b -> (a,c)) -> a -> IntMap b -> (a,IntMap c)
 mapAccumL f a t
   = case t of
@@ -927 +936 @@
       Nil         -> (a,Nil)
 
 
--- | /O(n)/. The function @'mapAccumR'@ threads an accumulating
--- argument throught the map in descending order of keys.
+-- | The function @'mapAccumR'@ threads an accumulating
+-- argument throught the map in descending order of keys. /O(n)/.
 mapAccumR :: (a -> Key -> b -> (a,c)) -> a -> IntMap b -> (a,IntMap c)
 mapAccumR f a t
   = case t of
@@ -941 +950 @@
 {--------------------------------------------------------------------
   Filter
 --------------------------------------------------------------------}
--- | /O(n)/. Filter all values that satisfy some predicate.
+-- | Filter all values that satisfy some predicate. /O(n)/.
 filter :: (a -> Bool) -> IntMap a -> IntMap a
 filter p m
   = filterWithKey (\k x -> p x) m
 
--- | /O(n)/. Filter all keys\/values that satisfy some predicate.
+-- | Filter all keys\/values that satisfy some predicate. /O(n)/.
 filterWithKey :: (Key -> a -> Bool) -> IntMap a -> IntMap a
 filterWithKey pred t
   = case t of
@@ -957 +966 @@
         | otherwise -> Nil
       Nil -> Nil
 
--- | /O(n)/. partition the map according to some predicate. The first
+-- | Partition the map according to some predicate. The first
 -- map contains all elements that satisfy the predicate, the second all
--- elements that fail the predicate. See also 'split'.
+-- elements that fail the predicate. See also 'split'. /O(n)/.
 partition :: (a -> Bool) -> IntMap a -> (IntMap a,IntMap a)
 partition p m
   = partitionWithKey (\k x -> p x) m
 
--- | /O(n)/. partition the map according to some predicate. The first
+-- | Partition the map according to some predicate. The first
 -- map contains all elements that satisfy the predicate, the second all
--- elements that fail the predicate. See also 'split'.
+-- elements that fail the predicate. See also 'split'. /O(n)/.
 partitionWithKey :: (Key -> a -> Bool) -> IntMap a -> (IntMap a,IntMap a)
 partitionWithKey pred t
   = case t of
@@ -979 +988 @@
         | otherwise -> (Nil,t)
       Nil -> (Nil,Nil)
 
--- | /O(n)/. Map values and collect the 'Just' results.
+-- | Map values and collect the 'Just' results. /O(n)/.
 mapMaybe :: (a -> Maybe b) -> IntMap a -> IntMap b
 mapMaybe f m
   = mapMaybeWithKey (\k x -> f x) m
 
--- | /O(n)/. Map keys\/values and collect the 'Just' results.
+-- | Map keys\/values and collect the 'Just' results. /O(n)/.
 mapMaybeWithKey :: (Key -> a -> Maybe b) -> IntMap a -> IntMap b
 mapMaybeWithKey f (Bin p m l r)
   = bin p m (mapMaybeWithKey f l) (mapMaybeWithKey f r)
@@ -993 +1002 @@
   Nothing -> Nil
 mapMaybeWithKey f Nil = Nil
 
--- | /O(n)/. Map values and separate the 'Left' and 'Right' results.
+-- | Map values and separate the 'Left' and 'Right' results. /O(n)/.
 mapEither :: (a -> Either b c) -> IntMap a -> (IntMap b, IntMap c)
 mapEither f m
   = mapEitherWithKey (\k x -> f x) m
 
--- | /O(n)/. Map keys\/values and separate the 'Left' and 'Right' results.
+-- | Map keys\/values and separate the 'Left' and 'Right' results. /O(n)/.
 mapEitherWithKey :: (Key -> a -> Either b c) -> IntMap a -> (IntMap b, IntMap c)
 mapEitherWithKey f (Bin p m l r)
   = (bin p m l1 r1, bin p m l2 r2)
@@ -1010 +1019 @@
   Right z -> (Nil, Tip k z)
 mapEitherWithKey f Nil = (Nil, Nil)
 
--- | /O(log n)/. The expression (@'split' k map@) is a pair @(map1,map2)@
+-- | The expression (@'split' k map@) is a pair @(map1,map2)@
 -- where all keys in @map1@ are lower than @k@ and all keys in
 -- @map2@ larger than @k@. Any key equal to @k@ is found in neither @map1@ nor @map2@.
+-- /O(log n)/.
 split :: Key -> IntMap a -> (IntMap a,IntMap a)
 split k t
   = case t of
@@ -1040 +1050 @@
         | otherwise -> (Nil,Nil)
       Nil -> (Nil,Nil)
 
--- | /O(log n)/. Performs a 'split' but also returns whether the pivot
--- key was found in the original map.
+-- | Performs a 'split' but also returns whether the pivot
+-- key was found in the original map. /O(log n)/.
 splitLookup :: Key -> IntMap a -> (IntMap a,Maybe a,IntMap a)
 splitLookup k t
   = case t of
@@ -1072 +1082 @@
 {--------------------------------------------------------------------
   Fold
 --------------------------------------------------------------------}
--- | /O(n)/. Fold the values in the map, such that
+-- |  Fold the values in the map, such that
 -- @'fold' f z == 'Prelude.foldr' f z . 'elems'@.
 -- For example,
 --
 -- > elems map = fold (:) [] map
 --
+-- /O(n)/.
 fold :: (a -> b -> b) -> b -> IntMap a -> b
 fold f z t
   = foldWithKey (\k x y -> f x y) z t
 
--- | /O(n)/. Fold the keys and values in the map, such that
+-- | Fold the keys and values in the map, such that
 -- @'foldWithKey' f z == 'Prelude.foldr' ('uncurry' f) z . 'toAscList'@.
 -- For example,
 --
 -- > keys map = foldWithKey (\k x ks -> k:ks) [] map
 --
+-- /O(n)/.
 foldWithKey :: (Key -> a -> b -> b) -> b -> IntMap a -> b
 foldWithKey f z t
   = foldr f z t
@@ -1112 +1124 @@
 {--------------------------------------------------------------------
   List variations 
 --------------------------------------------------------------------}
--- | /O(n)/.
--- Return all elements of the map in the ascending order of their keys.
+-- | Return all elements of the map in the ascending order of their keys.
+-- /O(n)/.
 elems :: IntMap a -> [a]
 elems m
   = foldWithKey (\k x xs -> x:xs) [] m  
 
--- | /O(n)/. Return all keys of the map in ascending order.
+-- | Return all keys of the map in ascending order. /O(n)/.
 keys  :: IntMap a -> [Key]
 keys m
   = foldWithKey (\k x ks -> k:ks) [] m
 
--- | /O(n*min(n,W))/. The set of all keys of the map.
+-- | The set of all keys of the map. /O(n*min(n,W))/.
 keysSet :: IntMap a -> IntSet.IntSet
 keysSet m = IntSet.fromDistinctAscList (keys m)
 
 
--- | /O(n)/. Return all key\/value pairs in the map in ascending key order.
+-- | Return all key\/value pairs in the map in ascending key order. /O(n)/.
 assocs :: IntMap a -> [(Key,a)]
 assocs m
   = toList m
@@ -1137 +1149 @@
 {--------------------------------------------------------------------
   Lists 
 --------------------------------------------------------------------}
--- | /O(n)/. Convert the map to a list of key\/value pairs.
+-- | Convert the map to a list of key\/value pairs. /O(n)/.
 toList :: IntMap a -> [(Key,a)]
 toList t
   = foldWithKey (\k x xs -> (k,x):xs) [] t
 
--- | /O(n)/. Convert the map to a list of key\/value pairs where the
--- keys are in ascending order.
+-- | Convert the map to a list of key\/value pairs where the
+-- keys are in ascending order. /O(n)/.
 toAscList :: IntMap a -> [(Key,a)]
 toAscList t   
   = -- NOTE: the following algorithm only works for big-endian trees
     let (pos,neg) = span (\(k,x) -> k >=0) (foldr (\k x xs -> (k,x):xs) [] t) in neg ++ pos
 
--- | /O(n*min(n,W))/. Create a map from a list of key\/value pairs.
+-- | Create a map from a list of key\/value pairs. /O(n*min(n,W))/.
 fromList :: [(Key,a)] -> IntMap a
 fromList xs
   = foldlStrict ins empty xs
   where
     ins t (k,x)  = insert k x t
 
--- | /O(n*min(n,W))/.  Create a map from a list of key\/value pairs with a combining function. See also 'fromAscListWith'.
+-- | Create a map from a list of key\/value pairs with a combining function. See also 'fromAscListWith'.
+-- /O(n*min(n,W))/.
 fromListWith :: (a -> a -> a) -> [(Key,a)] -> IntMap a 
 fromListWith f xs
   = fromListWithKey (\k x y -> f x y) xs
 
--- | /O(n*min(n,W))/.  Build a map from a list of key\/value pairs with a combining function. See also fromAscListWithKey'.
+-- | Build a map from a list of key\/value pairs with a combining function. See also fromAscListWithKey'.
+-- /O(n*min(n,W))/.
 fromListWithKey :: (Key -> a -> a -> a) -> [(Key,a)] -> IntMap a 
 fromListWithKey f xs 
   = foldlStrict ins empty xs
   where
     ins t (k,x) = insertWithKey f k x t
 
--- | /O(n*min(n,W))/. Build a map from a list of key\/value pairs where
--- the keys are in ascending order.
+-- | Build a map from a list of key\/value pairs where
+-- the keys are in ascending order. /O(n*min(n,W))/.
 fromAscList :: [(Key,a)] -> IntMap a
 fromAscList xs
   = fromList xs
 
--- | /O(n*min(n,W))/. Build a map from a list of key\/value pairs where
+-- | Build a map from a list of key\/value pairs where
 -- the keys are in ascending order, with a combining function on equal keys.
+-- /O(n*min(n,W))/.
 fromAscListWith :: (a -> a -> a) -> [(Key,a)] -> IntMap a
 fromAscListWith f xs
   = fromListWith f xs
 
--- | /O(n*min(n,W))/. Build a map from a list of key\/value pairs where
+-- | Build a map from a list of key\/value pairs where
 -- the keys are in ascending order, with a combining function on equal keys.
+-- /O(n*min(n,W))/.
 fromAscListWithKey :: (Key -> a -> a -> a) -> [(Key,a)] -> IntMap a
 fromAscListWithKey f xs
   = fromListWithKey f xs
 
--- | /O(n*min(n,W))/. Build a map from a list of key\/value pairs where
--- the keys are in ascending order and all distinct.
+-- | Build a map from a list of key\/value pairs where
+-- the keys are in ascending order and all distinct. /O(n*min(n,W))/.
 fromDistinctAscList :: [(Key,a)] -> IntMap a
 fromDistinctAscList xs
   = fromList xs
@@ -1277 +1293 @@
 {--------------------------------------------------------------------
   Debugging
 --------------------------------------------------------------------}
--- | /O(n)/. Show the tree that implements the map. The tree is shown
--- in a compressed, hanging format.
+-- | Show the tree that implements the map. The tree is shown
+-- in a compressed, hanging format. /O(n)/.
 showTree :: Show a => IntMap a -> String
 showTree s
   = showTreeWith True False s
 
 
-{- | /O(n)/. The expression (@'showTreeWith' hang wide map@) shows
+{- | The expression (@'showTreeWith' hang wide map@) shows
  the tree that implements the map. If @hang@ is
  'True', a /hanging/ tree is shown otherwise a rotated tree is shown. If
- @wide@ is 'True', an extra wide version is shown.
+ @wide@ is 'True', an extra wide version is shown. /O(n)/.
 -}
 showTreeWith :: Show a => Bool -> Bool -> IntMap a -> String
 showTreeWith hang wide t

Data/Map.hs

@@ -1 @@
-{-# OPTIONS_GHC -fno-bang-patterns #-}
+{-TODO - enable # OPTIONS_GHC -fno-bang-patterns #-}
 
 -----------------------------------------------------------------------------
 -- |
 -- Module      :  Data.Map
 -- Copyright   :  (c) Daan Leijen 2002
+--                (c) Andriy Palamarchuk 2007
 -- License     :  BSD-style
 -- Maintainer  :  libraries@haskell.org
 -- Stability   :  provisional
@@ -31 +32 @@
 -- Note that the implementation is /left-biased/ -- the elements of a
 -- first argument are always preferred to the second, for example in
 -- 'union' or 'insert'.
+--
+-- Operation comments contain the operation time complexity in
+-- the Big-O notation <http://en.wikipedia.org/wiki/Big_O_notation>.
 -----------------------------------------------------------------------------
 
 module Data.Map  ( 
@@ -194 +198 @@
 --------------------------------------------------------------------}
 infixl 9 !,\\ --
 
--- | /O(log n)/. Find the value at a key.
--- Calls 'error' when the element can not be found.
+-- | Find the value at a key.
+-- Calls 'error' when the element can not be found. /O(log n)/.
+--
+-- > let m = fromList [(5,'a'), (3,'b'), (7,'c')]
+-- > m
+-- >   {3:='b',5:='a',7:='c'}
+-- > m!1
+-- >   Error: element not in the map
+-- > m!5
+-- >   'a'
+
 (!) :: Ord k => Map k a -> k -> a
 m ! k    = find k m
 
--- | /O(n+m)/. See 'difference'.
+-- | Same as 'difference'.
 (\\) :: Ord k => Map k a -> Map k b -> Map k a
 m1 \\ m2 = difference m1 m2
 
@@ -238 +251 @@
 {--------------------------------------------------------------------
   Query
 --------------------------------------------------------------------}
--- | /O(1)/. Is the map empty?
+-- | Is the map empty? /O(1)/.
+--
+-- > Data.Map.null (fromList([]))
+-- >   True
+-- > Data.Map.null (fromList([('a',1)]))
+-- >   False
+-- > Data.Map.null (empty)
+-- >   True
+-- > Data.Map.null (singleton 'a' 1)
+-- >   False
+
 null :: Map k a -> Bool
 null t
   = case t of
       Tip             -> True
       Bin sz k x l r  -> False
 
--- | /O(1)/. The number of elements in the map.
+-- | The number of elements in the map. /O(1)/.
+--
+-- > size empty
+-- >   0
+-- > size (singleton 'a' 1)
+-- >   1
+-- > size (fromList([('a',1), ('c', 2), ('b', 3)]))
+-- >   3
+
 size :: Map k a -> Int
 size t
   = case t of
@@ -253 +284 @@
       Bin sz k x l r  -> sz
 
 
--- | /O(log n)/. Lookup the value at a key in the map. 
+-- | Lookup the value at a key in the map.
 --
 -- The function will 
 -- @return@ the result in the monad or @fail@ in it the key isn't in the 
 -- map. Often, the monad to use is 'Maybe', so you get either 
--- @('Just' result)@ or @'Nothing'@.
+-- @('Just' result)@ or @'Nothing'@. /O(log n)/.
+--
+-- > let m = fromList [(5,'a'), (3,'b'), (7,'c')]
+-- > m
+-- >   {3:='b',5:='a',7:='c'}
+-- > value1 <- Data.Map.lookup 5 m
+-- > value1
+-- >   'a'
+-- > value2 <- Data.Map.lookup 1 m
+-- >   Error: Key not found
+--
+-- An example of using @lookup@ with @Maybe@ monad:
+--
+-- > import Prelude hiding (lookup)
+-- > import Data.Map
+-- >
+-- > employeeDept = fromList([("John","Sales"), ("Bob","IT")])
+-- > deptCountry = fromList([("IT","USA"), ("Sales","France")])
+-- > countryCurrency = fromList([("USA", "Dollar"), ("France", "Euro")])
+-- >
+-- > employeeCurrency :: String -> Maybe String
+-- > employeeCurrency name = do
+-- >     dept <- lookup name employeeDept
+-- >     country <- lookup dept deptCountry
+-- >     lookup country countryCurrency
+-- >
+-- > main = do
+-- >     putStrLn $ "John's currency: " ++ (show (employeeCurrency "John"))
+-- >     putStrLn $ "Pete's currency: " ++ (show (employeeCurrency "Pete"))
+--
+-- The output of this program:
+--
+-- >   John's currency: Just "Euro"
+-- >   Pete's currency: Nothing
+
 lookup :: (Monad m,Ord k) => k -> Map k a -> m a
 lookup k t = case lookup' k t of
     Just x -> return x
@@ -283 +348 @@
                GT -> lookupAssoc k r
                EQ -> Just (kx,x)
 
--- | /O(log n)/. Is the key a member of the map?
+-- | Is the key a member of the map? See also 'notMember'. /O(log n)/.
+--
+-- > let m = fromList [(5,'a'), (3,'b'), (7,'c')]
+-- > m
+-- >   {3:='b',5:='a',7:='c'}
+-- > member 5 m
+-- >   True
+-- > member 1 m
+-- >   False
+
 member :: Ord k => k -> Map k a -> Bool
 member k m
   = case lookup k m of
       Nothing -> False
       Just x  -> True
 
--- | /O(log n)/. Is the key not a member of the map?
+-- | Is the key not a member of the map? See also 'member'. /O(log n)/.
+--
+-- > let m = fromList [(5,'a'), (3,'b'), (7,'c')]
+-- > m
+-- >   {3:='b',5:='a',7:='c'}
+-- > notMember 5 m
+-- >   False
+-- > notMember 1 m
+-- >   True
+
 notMember :: Ord k => k -> Map k a -> Bool
 notMember k m = not $ member k m
 
--- | /O(log n)/. Find the value at a key.
+-- | Find the value at a key. /O(log n)/.
 -- Calls 'error' when the element can not be found.
 find :: Ord k => k -> Map k a -> a
 find k m
@@ -302 +385 @@
       Nothing -> error "Map.find: element not in the map"
       Just x  -> x
 
--- | /O(log n)/. The expression @('findWithDefault' def k map)@ returns
--- the value at key @k@ or returns @def@ when the key is not in the map.
+-- | The expression @('findWithDefault' def k map)@ returns
+-- the value at key @k@ or returns default value @def@
+-- when the key is not in the map.
+-- /O(log n)/.
+--
+-- > let m = fromList [(5,'a'), (3,'b'), (7,'c')]
+-- > m
+-- >   {3:='b',5:='a',7:='c'}
+-- > findWithDefault '?' 1 m
+-- >   '?'
+-- > findWithDefault '?' 5 m
+-- >   'a'
+
 findWithDefault :: Ord k => a -> k -> Map k a -> a
 findWithDefault def k m
   = case lookup k m of
@@ -315 +409 @@
 {--------------------------------------------------------------------
   Construction
 --------------------------------------------------------------------}
--- | /O(1)/. The empty map.
+-- | The empty map. /O(1)/.
+--
+-- > empty
+-- >   {}
+-- > size empty
+-- >   0
+
 empty :: Map k a
 empty 
   = Tip
 
--- | /O(1)/. A map with a single element.
+-- | A map with a single element. /O(1)/.
+--
+-- > singleton 1 'a'
+-- >   {1:='a'}
+-- > size (singleton 1 'a')
+-- >   1
+
 singleton :: k -> a -> Map k a
 singleton k x  
   = Bin 1 k x Tip Tip
@@ -328 +434 @@
 {--------------------------------------------------------------------
   Insertion
 --------------------------------------------------------------------}
--- | /O(log n)/. Insert a new key and value in the map.
+-- | Insert a new key and value in the map.
 -- If the key is already present in the map, the associated value is
--- replaced with the supplied value, i.e. 'insert' is equivalent to
--- @'insertWith' 'const'@.
+-- replaced with the supplied value. 'insert' is equivalent to
+-- @'insertWith' 'const'@. /O(log n)/.
+--
+-- > let m = fromList [(5,'a'), (3,'b')]
+-- > m
+-- >   {3:='b',5:='a'}
+-- > insert 5 'x' m
+-- >   {3:='b',5:='x'}
+-- > insert 10 'x' m
+-- >   {3:='b',5:='a',10:='x'}
+-- > insert 5 'x' empty
+-- >   {5:='x'}
+
 insert :: Ord k => k -> a -> Map k a -> Map k a
 insert kx x t
   = case t of
@@ -342 +459 @@
                GT -> balance ky y l (insert kx x r)
                EQ -> Bin sz kx x l r
 
--- | /O(log n)/. Insert with a combining function.
+-- | Insert with a function, combining new value and old value.
 -- @'insertWith' f key value mp@ 
 -- will insert the pair (key, value) into @mp@ if key does
 -- not exist in the map. If the key does exist, the function will
--- insert the pair @(key, f new_value old_value)@.
+-- insert the pair @(key, f new_value old_value)@. /O(log n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- > insertWith (++) 5 "xxx" m
+-- >   {3:="b",5:="xxxa"}
+-- > insertWith (++) 10 "xxx" m
+-- >   {3:="b",5:="a",10:="xxx"}
+-- > insertWith (++) 5 "xxx" empty
+-- >   {5:="xxx"}
+
 insertWith :: Ord k => (a -> a -> a) -> k -> a -> Map k a -> Map k a
 insertWith f k x m          
   = insertWithKey (\k x y -> f x y) k x m
@@ -357 +485 @@
   = insertWithKey' (\k x y -> f x y) k x m
 
 
--- | /O(log n)/. Insert with a combining function.
+-- | Insert with a function, combining key, new value and old value.
 -- @'insertWithKey' f key value mp@ 
 -- will insert the pair (key, value) into @mp@ if key does
 -- not exist in the map. If the key does exist, the function will
 -- insert the pair @(key,f key new_value old_value)@.
 -- Note that the key passed to f is the same key passed to 'insertWithKey'.
+-- /O(log n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- > let f key new_value old_value = (show key) ++ ":" ++ new_value ++ "|" ++ old_value
+-- > insertWithKey f 5 "xxx" m
+-- >   {3:="b",5:="5:xxx|a"}
+-- > insertWithKey f 10 "xxx" m
+-- >   {3:="b",5:="a",10:="xxx"}
+-- > insertWithKey f 5 "xxx" empty
+-- >   {5:="xxx"}
+
 insertWithKey :: Ord k => (k -> a -> a -> a) -> k -> a -> Map k a -> Map k a
 insertWithKey f kx x t
   = case t of
@@ -385 +526 @@
                EQ -> let x' = f kx x y in seq x' (Bin sy kx x' l r)
 
 
--- | /O(log n)/. The expression (@'insertLookupWithKey' f k x map@)
+-- | Combines insert operation with old value retrieval.
+-- The expression (@'insertLookupWithKey' f k x map@)
 -- is a pair where the first element is equal to (@'lookup' k map@)
--- and the second element equal to (@'insertWithKey' f k x map@).
+-- and the second element equal to (@'insertWithKey' f k x map@). /O(log n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- > let f key new_value old_value = (show key) ++ ":" ++ new_value ++ "|" ++ old_value
+-- > insertLookupWithKey f 5 "xxx" m
+-- >   (Just "a",{3:="b",5:="5:xxx|a"})
+-- > insertLookupWithKey f 10 "xxx" m
+-- >   (Nothing,{3:="b",5:="a",10:="xxx"})
+-- > insertLookupWithKey f 5 "xxx" empty
+-- >   (Nothing,{5:="xxx"})
+--
+-- This is how to define @insertLookup@ using @insertLookupWithKey@:
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- > let insertLookup kx x t = insertLookupWithKey (\_ a _ -> a) kx x t
+-- > insertLookup 5 "x" m
+-- >   (Just "a",{3:="b",5:="x"})
+-- > insertLookup 10 "x" m
+-- >   (Nothing,{3:="b",5:="a",10:="x"})
+
 insertLookupWithKey :: Ord k => (k -> a -> a -> a) -> k -> a -> Map k a -> (Maybe a,Map k a)
 insertLookupWithKey f kx x t
   = case t of
@@ -402 +567 @@
   Deletion
   [delete] is the inlined version of [deleteWith (\k x -> Nothing)]
 --------------------------------------------------------------------}
--- | /O(log n)/. Delete a key and its value from the map. When the key is not
--- a member of the map, the original map is returned.
+-- | Delete a key and its value from the map. When the key is not
+-- a member of the map, the original map is returned. /O(log n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- > delete 5 m
+-- >   {3:="b"}
+-- > delete 10 m
+-- >   {3:="b",5:="a"}
+-- > delete 5 empty
+-- >   {}
+
 delete :: Ord k => k -> Map k a -> Map k a
 delete k t
   = case t of
@@ -414 +590 @@
                GT -> balance kx x l (delete k r)
                EQ -> glue l r
 
--- | /O(log n)/. Adjust a value at a specific key. When the key is not
--- a member of the map, the original map is returned.
+-- | Update a value at a specific key with the result of the provided function.
+-- When the key is not
+-- a member of the map, the original map is returned. /O(log n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- > adjust ("new " ++) 5 m
+-- >   {3:="b",5:="new a"}
+-- > adjust ("new " ++) 10 m
+-- >   {3:="b",5:="a"}
+-- > adjust ("new " ++) 10 empty
+-- >   {}
+
 adjust :: Ord k => (a -> a) -> k -> Map k a -> Map k a
 adjust f k m
   = adjustWithKey (\k x -> f x) k m
 
--- | /O(log n)/. Adjust a value at a specific key. When the key is not
--- a member of the map, the original map is returned.
+-- | Adjust a value at a specific key. When the key is not
+-- a member of the map, the original map is returned. /O(log n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- > let f key x = (show key) ++ ":new " ++ x
+-- > adjustWithKey f 5 m
+-- >   {3:="b",5:="5:new a"}
+-- > adjustWithKey f 10 m
+-- >   {3:="b",5:="a"}
+-- > adjustWithKey f 10 empty
+-- >   {}
+
 adjustWithKey :: Ord k => (k -> a -> a) -> k -> Map k a -> Map k a
 adjustWithKey f k m
   = updateWithKey (\k x -> Just (f k x)) k m
 
--- | /O(log n)/. The expression (@'update' f k map@) updates the value @x@
+-- | The expression (@'update' f k map@) updates the value @x@
 -- at @k@ (if it is in the map). If (@f x@) is 'Nothing', the element is
 -- deleted. If it is (@'Just' y@), the key @k@ is bound to the new value @y@.
+-- /O(log n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- > let f x = if x == "a" then Just "new a" else Nothing
+-- >
+-- > -- f "a" returns Just "new a"
+-- > update f 5 m
+-- >   {3:="b",5:="new a"}
+-- >
+-- > -- key does not exist
+-- > update f 10 m
+-- >   {3:="b",5:="a"}
+-- >
+-- > -- f "b" returns Nothing
+-- > update f 3 m
+-- >   {5:="a"}
+
 update :: Ord k => (a -> Maybe a) -> k -> Map k a -> Map k a
 update f k m
   = updateWithKey (\k x -> f x) k m
 
--- | /O(log n)/. The expression (@'updateWithKey' f k map@) updates the
+-- | The expression (@'updateWithKey' f k map@) updates the
 -- value @x@ at @k@ (if it is in the map). If (@f k x@) is 'Nothing',
 -- the element is deleted. If it is (@'Just' y@), the key @k@ is bound
--- to the new value @y@.
+-- to the new value @y@. /O(log n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- > let f k x = if x == "a" then Just ((show k) ++ ":new a") else Nothing
+-- >
+-- > -- f 5 "a" returns Just "5:new a"
+-- > updateWithKey f 5 m
+-- >   {3:="b",5:="5:new a"}
+-- >
+-- > -- key does not exist
+-- > updateWithKey f 10 m
+-- >   {3:="b",5:="a"}
+-- >
+-- > -- f 3 "b" returns Nothing
+-- > updateWithKey f 3 m
+-- >   {5:="a"}
+
 updateWithKey :: Ord k => (k -> a -> Maybe a) -> k -> Map k a -> Map k a
 updateWithKey f k t
   = case t of
@@ -449 +686 @@
                        Just x' -> Bin sx kx x' l r
                        Nothing -> glue l r
 
--- | /O(log n)/. Lookup and update.
+-- | Lookup and update. See also 'updateWithKey'. /O(log n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- > let f k x = if x == "a" then Just ((show k) ++ ":new a") else Nothing
+-- >
+-- > -- f 5 "a" returns Just "5:new a"
+-- > updateLookupWithKey f 5 m
+-- >   (Just "5:new a",{3:="b",5:="5:new a"})
+-- >
+-- > -- key does not exist
+-- > updateLookupWithKey f 10 m
+-- >   (Nothing,{3:="b",5:="a"})
+-- >
+-- > -- f 3 "b" returns Nothing
+-- > updateLookupWithKey f 3 m
+-- >   (Just "b",{5:="a"})
+
 updateLookupWithKey :: Ord k => (k -> a -> Maybe a) -> k -> Map k a -> (Maybe a,Map k a)
 updateLookupWithKey f k t
   = case t of
@@ -462 +717 @@
                        Just x' -> (Just x',Bin sx kx x' l r)
                        Nothing -> (Just x,glue l r)
 
--- | /O(log n)/. The expression (@'alter' f k map@) alters the value @x@ at @k@, or absence thereof.
+-- | The expression (@'alter' f k map@) alters the value @x@ at @k@, or absence thereof.
 -- 'alter' can be used to insert, delete, or update a value in a 'Map'.
--- In short : @'lookup' k ('alter' f k m) = f ('lookup' k m)@
+-- In short : @'lookup' k ('alter' f k m) = f ('lookup' k m)@. /O(log n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- >
+-- > -- always returns Nothing
+-- > let f _ = Nothing
+-- > alter f 10 m
+-- >   {3:="b",5:="a"}
+-- > alter f 5 m
+-- >   {3:="b"}
+-- >
+-- > -- always returns Just "c"
+-- > let f _ = Just "c"
+-- > alter f 10 m
+-- >   {3:="b",5:="a",10:="c")}
+-- > alter f 5 m
+-- >   {3:="b",5:="c")}
+
 alter :: Ord k => (Maybe a -> Maybe a) -> k -> Map k a -> Map k a
 alter f k t
   = case t of
@@ -482 +756 @@
 {--------------------------------------------------------------------
   Indexing
 --------------------------------------------------------------------}
--- | /O(log n)/. Return the /index/ of a key. The index is a number from
+-- | Return the /index/ of a key. The index is a number from
 -- /0/ up to, but not including, the 'size' of the map. Calls 'error' when
--- the key is not a 'member' of the map.
+-- the key is not a 'member' of the map. /O(log n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- > findIndex 2 m
+-- >   Exception: Key not found.
+-- > findIndex 3 m
+-- >   0
+-- > findIndex 4 m
+-- >   Exception: Key not found.
+-- > findIndex 5 m
+-- >   1
+-- > findIndex 6 m
+-- >   Exception: Key not found.
+
 findIndex :: Ord k => k -> Map k a -> Int
 findIndex k t
   = case lookupIndex k t of
       Nothing  -> error "Map.findIndex: element is not in the map"
       Just idx -> idx
 
--- | /O(log n)/. Lookup the /index/ of a key. The index is a number from
--- /0/ up to, but not including, the 'size' of the map. 
+-- | Lookup the /index/ of a key. The index is a number from
+-- /0/ up to, but not including, the 'size' of the map. /O(log n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- > isJust (lookupIndex 2 m)
+-- >   False
+-- > isJust (lookupIndex 3 m)
+-- >   True
+-- > fromJust (lookupIndex 3 m)
+-- >   0
+-- > isJust (lookupIndex 4 m)
+-- >   False
+-- > isJust (lookupIndex 5 m)
+-- >   True
+-- > fromJust (lookupIndex 5 m)
+-- >   1
+-- > isJust (lookupIndex 6 m)
+-- >   False
+
 lookupIndex :: (Monad m,Ord k) => k -> Map k a -> m Int
 lookupIndex k t = case lookup 0 t of
     Nothing -> fail "Data.Map.lookupIndex: Key not found."
@@ -505 +813 @@
           GT -> lookup (idx + size l + 1) r 
           EQ -> Just (idx + size l)
 
--- | /O(log n)/. Retrieve an element by /index/. Calls 'error' when an
--- invalid index is used.
+-- | Retrieve an element by /index/. Calls 'error' when an
+-- invalid index is used. /O(log n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- > elemAt 0 m
+-- >   (3,"b")
+-- > elemAt 1 m
+-- >   (5,"a")
+-- > elemAt 2 m
+-- >   Exception: Map.elemAt: index out of range
+
 elemAt :: Int -> Map k a -> (k,a)
 elemAt i Tip = error "Map.elemAt: index out of range"
 elemAt i (Bin _ kx x l r)
@@ -517 +836 @@
   where
     sizeL = size l
 
--- | /O(log n)/. Update the element at /index/. Calls 'error' when an
--- invalid index is used.
+-- | Update the element at /index/. Calls 'error' when an
+-- invalid index is used. /O(log n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- >
+-- > -- always returns Just "x"
+-- > let f _ _ = Just "x"
+-- > updateAt f 0 m
+-- >   {3:="x",5:="a"}
+-- > updateAt f 1 m
+-- >   {3:="b",5:="x"}
+-- > updateAt f 2 m
+-- >   Exception: Map.updateAt: index out of range
+-- > updateAt f (-1) m
+-- >   Exception: Map.updateAt: index out of range
+-- >
+-- > -- always returns Nothing
+-- > let f _ _ = Nothing
+-- > updateAt f 0 m
+-- >   {5:="a"}
+-- > updateAt f 1 m
+-- >   {3:="b"}
+-- > updateAt f 2 m
+-- >   Exception: Map.updateAt: index out of range
+-- > updateAt f (-1) m
+-- >   Exception: Map.updateAt: index out of range
+
 updateAt :: (k -> a -> Maybe a) -> Int -> Map k a -> Map k a
 updateAt f i Tip  = error "Map.updateAt: index out of range"
 updateAt f i (Bin sx kx x l r)
@@ -531 +877 @@
   where
     sizeL = size l
 
--- | /O(log n)/. Delete the element at /index/.
+-- | Delete the element at /index/.
 -- Defined as (@'deleteAt' i map = 'updateAt' (\k x -> 'Nothing') i map@).
+-- /O(log n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- > deleteAt 0 m
+-- >   {5:="a"}
+-- > deleteAt 1 m
+-- >   {3:="b"}
+-- > deleteAt 2 m
+-- >   Exception: Map.updateAt: index out of range
+-- > deleteAt (-1) m
+-- >   Exception: Map.updateAt: index out of range
+
 deleteAt :: Int -> Map k a -> Map k a
 deleteAt i map
   = updateAt (\k x -> Nothing) i map
@@ -541 +901 @@
 {--------------------------------------------------------------------
   Minimal, Maximal
 --------------------------------------------------------------------}
--- | /O(log n)/. The minimal key of the map.
+-- | The minimal key of the map. /O(log n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- > findMin m
+-- >   (3,"b")
+-- > findMin empty
+-- >   Exception: Map.findMin: empty map has no minimal element
+
 findMin :: Map k a -> (k,a)
 findMin (Bin _ kx x Tip r)  = (kx,x)
 findMin (Bin _ kx x l r)    = findMin l
 findMin Tip                 = error "Map.findMin: empty map has no minimal element"
 
--- | /O(log n)/. The maximal key of the map.
+-- | The maximal key of the map. /O(log n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- > findMax m
+-- >   (5,"a")
+-- > findMax empty
+-- >   Exception: Map.findMax: empty map has no maximal element
+
 findMax :: Map k a -> (k,a)
 findMax (Bin _ kx x l Tip)  = (kx,x)
 findMax (Bin _ kx x l r)    = findMax r
 findMax Tip                 = error "Map.findMax: empty map has no maximal element"
 
--- | /O(log n)/. Delete the minimal key.
+-- | Delete the minimal key. /O(log n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b"), (10,"c")]
+-- > m
+-- >   {3:="b",5:="a",10:="c"}
+-- > deleteMin m
+-- >   {5:="a",10:="c"}
+-- > deleteMin empty
+-- >   {}
+
 deleteMin :: Map k a -> Map k a
 deleteMin (Bin _ kx x Tip r)  = r
 deleteMin (Bin _ kx x l r)    = balance kx x (deleteMin l) r
 deleteMin Tip                 = Tip
 
--- | /O(log n)/. Delete the maximal key.
+-- | Delete the maximal key. /O(log n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b"), (10,"c")]
+-- > m
+-- >   {3:="b",5:="a",10:="c"}
+-- > deleteMax m
+-- >   {3:="b",5:="a"}
+-- > deleteMax empty
+-- >   {}
+
 deleteMax :: Map k a -> Map k a
 deleteMax (Bin _ kx x l Tip)  = l
 deleteMax (Bin _ kx x l r)    = balance kx x l (deleteMax r)
 deleteMax Tip                 = Tip
 
--- | /O(log n)/. Update the value at the minimal key.
+-- | Update the value at the minimal key. /O(log n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b"), (10,"c")]
+-- > m
+-- >   {3:="b",5:="a",10:="c"}
+-- > updateMin (\ a -> Just ("X" ++ a)) m
+-- >   {3:="Xb",5:="a",10:="c"}
+-- > updateMin (\ _ -> Nothing) m
+-- >   {5:="a",10:="c"}
+
 updateMin :: (a -> Maybe a) -> Map k a -> Map k a
 updateMin f m
   = updateMinWithKey (\k x -> f x) m
 
--- | /O(log n)/. Update the value at the maximal key.
+-- | Update the value at the maximal key. /O(log n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b"), (10,"c")]
+-- > m
+-- >   {3:="b",5:="a",10:="c"}
+-- > updateMax (\ a -> Just ("X" ++ a)) m
+-- >   {3:="b",5:="a",10:="Xc"}
+-- > updateMax (\ _ -> Nothing) m
+-- >   {3:="b",5,"a"}
+
 updateMax :: (a -> Maybe a) -> Map k a -> Map k a
 updateMax f m
   = updateMaxWithKey (\k x -> f x) m
 
 
--- | /O(log n)/. Update the value at the minimal key.
+-- | Update the value at the minimal key. /O(log n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b"), (10,"c")]
+-- > m
+-- >   {3:="b",5:="a",10:="c"}
+-- > updateMinWithKey (\ k a -> Just ((show k) ++ ":" ++ a)) m
+-- >   {3:="3:b",5:="a",10:="c"}
+-- > updateMinWithKey (\ _ _ -> Nothing) m
+-- >   {5:="a",10:="c"}
+
 updateMinWithKey :: (k -> a -> Maybe a) -> Map k a -> Map k a
 updateMinWithKey f t
   = case t of
@@ -586 +1009 @@
       Bin sx kx x l r    -> balance kx x (updateMinWithKey f l) r
       Tip                -> Tip
 
--- | /O(log n)/. Update the value at the maximal key.
+-- | Update the value at the maximal key. /O(log n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b"), (10,"c")]
+-- > m
+-- >   {3:="b",5:="a",10:="c"}
+-- > updateMaxWithKey (\ k a -> Just ((show k) ++ ":" ++ a)) m
+-- >   {3:="b",5:="a",10:="10:c"}
+-- > updateMaxWithKey (\ _ _ -> Nothing) m
+-- >   {3:="b",5:="a"}
+
 updateMaxWithKey :: (k -> a -> Maybe a) -> Map k a -> Map k a
 updateMaxWithKey f t
   = case t of
@@ -596 +1028 @@
       Bin sx kx x l r    -> balance kx x l (updateMaxWithKey f r)
       Tip                -> Tip
 
--- | /O(log n)/. Retrieves the minimal (key,value) pair of the map, and the map stripped from that element
+-- | Retrieves the minimal (key,value) pair of the map, and the map stripped from that element
 -- @fail@s (in the monad) when passed an empty map.
+-- /O(log n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- > minViewWithKey m
+-- >   ((3,"b"), {5:="a"})
+-- > minViewWithKey empty
+-- >   Exception: user error (Map.minViewWithKey: empty map)
+
 minViewWithKey :: Monad m => Map k a -> m ((k,a), Map k a)
-minViewWithKey Tip = fail "Map.minView: empty map"
+minViewWithKey Tip = fail "Map.minViewWithKey: empty map"
 minViewWithKey x = return (deleteFindMin x)
 
--- | /O(log n)/. Retrieves the maximal (key,value) pair of the map, and the map stripped from that element
--- @fail@s (in the monad) when passed an empty map.
+-- | Retrieves the maximal (key,value) pair of the map, and the map stripped from that element
+-- @fail@s (in the monad) when passed an empty map. /O(log n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- > maxViewWithKey m
+-- >   ((5,"a"), {3:="b"})
+-- > maxViewWithKey empty
+-- >   Exception: user error (Map.maxViewWithKey: empty map)
+
 maxViewWithKey :: Monad m => Map k a -> m ((k,a), Map k a)
-maxViewWithKey Tip = fail "Map.maxView: empty map"
+maxViewWithKey Tip = fail "Map.maxViewWithKey: empty map"
 maxViewWithKey x = return (deleteFindMax x)
 
--- | /O(log n)/. Retrieves the minimal key\'s value of the map, and the map stripped from that element
--- @fail@s (in the monad) when passed an empty map.
+-- | Retrieves the minimal key\'s value of the map, and the map stripped from that element
+-- @fail@s (in the monad) when passed an empty map. /O(log n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- > minView m
+-- >   ("b", {5:="a"})
+-- > minView empty
+-- >   Exception: user error (Map.minView: empty map)
+
 minView :: Monad m => Map k a -> m (a, Map k a)
 minView Tip = fail "Map.minView: empty map"
 minView x = return (first snd $ deleteFindMin x)
 
--- | /O(log n)/. Retrieves the maximal key\'s value of the map, and the map stripped from that element
--- @fail@s (in the monad) when passed an empty map.
+-- | Retrieves the maximal key\'s value of the map, and the map stripped from that element
+-- @fail@s (in the monad) when passed an empty map. /O(log n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- > maxView m
+-- >   ("a", {3:="b"})
+-- > maxView empty
+-- >   Exception: user error (Map.maxView: empty map)
+
 maxView :: Monad m => Map k a -> m (a, Map k a)
 maxView Tip = fail "Map.maxView: empty map"
 maxView x = return (first snd $ deleteFindMax x)
@@ -629 +1098 @@
 --------------------------------------------------------------------}
 -- | The union of a list of maps:
 --   (@'unions' == 'Prelude.foldl' 'union' 'empty'@).
+--
+-- > let map1 = fromList [(5, "a"), (3, "b")]
+-- > let map2 = fromList [(5, "A"), (10, "C")]
+-- > let map3 = fromList [(5, "A3"), (3, "B3")]
+-- > unions [map1, map2, map3]
+-- >   {3:="b",5:="a",10:="C"}
+-- > unions [map3, map2, map1]
+-- >   {3:="B3",5:="A3",10:="C"}
+
 unions :: Ord k => [Map k a] -> Map k a
 unions ts
   = foldlStrict union empty ts
 
 -- | The union of a list of maps, with a combining operation:
 --   (@'unionsWith' f == 'Prelude.foldl' ('unionWith' f) 'empty'@).
+--
+-- > let map1 = fromList [(5, "a"), (3, "b")]
+-- > let map2 = fromList [(5, "A"), (10, "C")]
+-- > let map3 = fromList [(5, "A3"), (3, "B3")]
+-- > unionsWith (++) [map1, map2, map3]
+-- >   {3:="bB3",5:="aAA3",10:="C"}
+
 unionsWith :: Ord k => (a->a->a) -> [Map k a] -> Map k a
 unionsWith f ts
   = foldlStrict (unionWith f) empty ts
 
--- | /O(n+m)/.
--- The expression (@'union' t1 t2@) takes the left-biased union of @t1@ and @t2@. 
+-- | The expression (@'union' t1 t2@) takes the left-biased union of @t1@ and @t2@. 
 -- It prefers @t1@ when duplicate keys are encountered,
 -- i.e. (@'union' == 'unionWith' 'const'@).
 -- The implementation uses the efficient /hedge-union/ algorithm.
--- Hedge-union is more efficient on (bigset `union` smallset)
+-- Hedge-union is more efficient on (bigset \``union`\` smallset). /O(n+m)/.
+--
+-- > let map1 = fromList [(5, "a"), (3, "b")]
+-- > let map2 = fromList [(5, "A"), (10, "C")]
+-- > union map1 map2
+-- >   {3:="b",5:="a",10:="C"}
+
 union :: Ord k => Map k a -> Map k a -> Map k a
 union Tip t2  = t2
 union t1 Tip  = t1
@@ -680 +1170 @@
 {--------------------------------------------------------------------
   Union with a combining function
 --------------------------------------------------------------------}
--- | /O(n+m)/. Union with a combining function. The implementation uses the efficient /hedge-union/ algorithm.
+-- | Union with a combining function. The implementation uses the efficient /hedge-union/ algorithm.
+-- /O(n+m)/.
+--
+-- > let map1 = fromList [(5, "a"), (3, "b")]
+-- > let map2 = fromList [(5, "A"), (10, "C")]
+-- > unionWith (++) map1 map2
+-- >   {3:="b",5:="aA",10:="C"}
+
 unionWith :: Ord k => (a -> a -> a) -> Map k a -> Map k a -> Map k a
 unionWith f m1 m2
   = unionWithKey (\k x y -> f x y) m1 m2
 
--- | /O(n+m)/.
--- Union with a combining function. The implementation uses the efficient /hedge-union/ algorithm.
--- Hedge-union is more efficient on (bigset `union` smallset).
+-- | Union with a combining function. The implementation uses the efficient /hedge-union/ algorithm.
+-- Hedge-union is more efficient on (bigset \``union`\` smallset).
+-- /O(n+m)/.
+--
+-- > let map1 = fromList [(5, "a"), (3, "b")]
+-- > let map2 = fromList [(5, "A"), (10, "C")]
+-- > let f key new_value old_value = (show key) ++ ":" ++ new_value ++ "|" ++ old_value
+-- > unionWithKey f map1 map2
+-- >   {3:="b",5:="5:a|A",10:="C"}
+
 unionWithKey :: Ord k => (k -> a -> a -> a) -> Map k a -> Map k a -> Map k a
 unionWithKey f Tip t2  = t2
 unionWithKey f t1 Tip  = t1
@@ -711 +1215 @@
 {--------------------------------------------------------------------
   Difference
 --------------------------------------------------------------------}
--- | /O(n+m)/. Difference of two maps. 
+-- | Difference of two maps. 
+-- Return elements of the first map not existing in the second map.
 -- The implementation uses an efficient /hedge/ algorithm comparable with /hedge-union/.
+-- /O(n+m)/.
+--
+-- > let map1 = fromList [(5, "a"), (3, "b")]
+-- > let map2 = fromList [(5, "A"), (10, "C")]
+-- > difference map1 map2
+-- >   {3:="b"}
+
 difference :: Ord k => Map k a -> Map k b -> Map k a
 difference Tip t2  = Tip
 difference t1 Tip  = t1
@@ -728 +1240 @@
   where
     cmpkx k = compare kx k   
 
--- | /O(n+m)/. Difference with a combining function. 
+-- | Difference with a combining function. 
+-- When two equal keys are
+-- encountered, the combining function is applied to the values of these keys.
+-- If it returns 'Nothing', the element is discarded (proper set difference). If
+-- it returns (@'Just' y@), the element is updated with a new value @y@. 
 -- The implementation uses an efficient /hedge/ algorithm comparable with /hedge-union/.
+-- /O(n+m)/.
+--
+-- > -- 3 and 5 are common keys
+-- > let map1 = fromList [(5, "a"), (3, "b")]
+-- > let map2 = fromList [(5, "A"), (3, "B"), (10, "C")]
+-- > map1
+-- >   {3:="b",5:="a"}
+-- > map2
+-- >   {3:="B",5:="A",10:="C"}
+-- > let f al ar = if al == "b" then Just (al ++ ":" ++ ar) else Nothing
+-- >
+-- > -- f returns Nothing for 5, Just "b:B" for 3
+-- > differenceWith f map1 map2
+-- >   {3:="b:B"}
+
 differenceWith :: Ord k => (a -> b -> Maybe a) -> Map k a -> Map k b -> Map k a
 differenceWith f m1 m2
   = differenceWithKey (\k x y -> f x y) m1 m2
 
--- | /O(n+m)/. Difference with a combining function. When two equal keys are
+-- | Difference with a combining function. When two equal keys are
 -- encountered, the combining function is applied to the key and both values.
 -- If it returns 'Nothing', the element is discarded (proper set difference). If
 -- it returns (@'Just' y@), the element is updated with a new value @y@. 
 -- The implementation uses an efficient /hedge/ algorithm comparable with /hedge-union/.
+-- /O(n+m)/.
+--
+-- > -- 3 and 5 are common keys
+-- > let map1 = fromList [(5, "a"), (3, "b")]
+-- > let map2 = fromList [(5, "A"), (3, "B"), (10, "C")]
+-- > map1
+-- >   {3:="b",5:="a"}
+-- > map2
+-- >   {3:="B",5:="A",10:="C"}
+-- > let f k al ar = if al == "b" then Just ((show k) ++ ":" ++ al ++ "|" ++ ar) else Nothing
+-- >
+-- > -- f returns Nothing for 5, Just "3:b|B" for 3
+-- > differenceWithKey f map1 map2
+-- >   {3:="3:b|B"}
+
 differenceWithKey :: Ord k => (k -> a -> b -> Maybe a) -> Map k a -> Map k b -> Map k a
 differenceWithKey f Tip t2  = Tip
 differenceWithKey f t1 Tip  = t1
@@ -767 +1313 @@
 {--------------------------------------------------------------------
   Intersection
 --------------------------------------------------------------------}
--- | /O(n+m)/. Intersection of two maps. The values in the first
--- map are returned, i.e. (@'intersection' m1 m2 == 'intersectionWith' 'const' m1 m2@).
+-- | Intersection of two maps.
+-- Return data in the first map for the keys existing in both maps.
+-- (@'intersection' m1 m2 == 'intersectionWith' 'const' m1 m2@).
+-- /O(n+m)/.
+--
+-- > let map1 = fromList [(5, "a"), (3, "b")]
+-- > let map2 = fromList [(5, "A"), (10, "C")]
+-- > intersection map1 map2
+-- >   {5:="a"}
+
 intersection :: Ord k => Map k a -> Map k b -> Map k a
 intersection m1 m2
   = intersectionWithKey (\k x y -> x) m1 m2
 
--- | /O(n+m)/. Intersection with a combining function.
+-- | Intersection with a combining function.
+-- /O(n+m)/.
+--
+-- > let map1 = fromList [(5, "a"), (3, "b")]
+-- > let map2 = fromList [(5, "A"), (10, "C")]
+-- > intersectionWith (++) map1 map2
+-- >   {5:="aA"}
+
 intersectionWith :: Ord k => (a -> b -> c) -> Map k a -> Map k b -> Map k c
 intersectionWith f m1 m2
   = intersectionWithKey (\k x y -> f x y) m1 m2
 
--- | /O(n+m)/. Intersection with a combining function.
--- Intersection is more efficient on (bigset `intersection` smallset)
+-- | Intersection with a combining function.
+-- Intersection is more efficient on (bigset \``intersection`\` smallset). /O(n+m)/.
+--
+-- > let map1 = fromList [(5, "a"), (3, "b")]
+-- > let map2 = fromList [(5, "A"), (10, "C")]
+-- > let f k al ar = (show k) ++ ":" ++ al ++ "|" ++ ar
+-- > intersectionWithKey f map1 map2
+-- >   {5:="5:a|A"}
+
 --intersectionWithKey :: Ord k => (k -> a -> b -> c) -> Map k a -> Map k b -> Map k c
 --intersectionWithKey f Tip t = Tip
 --intersectionWithKey f t Tip = Tip
@@ -796 +1364 @@
 --    tl            = intersectWithKey f lt l
 --    tr            = intersectWithKey f gt r
 
-
 intersectionWithKey :: Ord k => (k -> a -> b -> c) -> Map k a -> Map k b -> Map k c
 intersectionWithKey f Tip t = Tip
 intersectionWithKey f t Tip = Tip
@@ -820 +1387 @@
 {--------------------------------------------------------------------
   Submap
 --------------------------------------------------------------------}
--- | /O(n+m)/. 
--- This function is defined as (@'isSubmapOf' = 'isSubmapOfBy' (==)@).
+-- | This function is defined as (@'isSubmapOf' = 'isSubmapOfBy' (==)@).
+-- /O(n+m)/.
 isSubmapOf :: (Ord k,Eq a) => Map k a -> Map k a -> Bool
 isSubmapOf m1 m2
   = isSubmapOfBy (==) m1 m2
 
-{- | /O(n+m)/. 
- The expression (@'isSubmapOfBy' f t1 t2@) returns 'True' if
+{- | The expression (@'isSubmapOfBy' f t1 t2@) returns 'True' if
  all keys in @t1@ are in tree @t2@, and when @f@ returns 'True' when
  applied to their respective values. For example, the following 
  expressions are all 'True':
@@ -841 +1407 @@
  > isSubmapOfBy (==) (fromList [('a',2)]) (fromList [('a',1),('b',2)])
  > isSubmapOfBy (<)  (fromList [('a',1)]) (fromList [('a',1),('b',2)])
  > isSubmapOfBy (==) (fromList [('a',1),('b',2)]) (fromList [('a',1)])
+ 
+ /O(n+m)/.
 -}
 isSubmapOfBy :: Ord k => (a->b->Bool) -> Map k a -> Map k b -> Bool
 isSubmapOfBy f t1 t2
@@ -855 +1423 @@
   where
     (lt,found,gt) = splitLookup kx t
 
--- | /O(n+m)/. Is this a proper submap? (ie. a submap but not equal). 
--- Defined as (@'isProperSubmapOf' = 'isProperSubmapOfBy' (==)@).
+-- | Is this a proper submap? (ie. a submap but not equal). 
+-- Defined as (@'isProperSubmapOf' = 'isProperSubmapOfBy' (==)@). /O(n+m)/.
 isProperSubmapOf :: (Ord k,Eq a) => Map k a -> Map k a -> Bool
 isProperSubmapOf m1 m2
   = isProperSubmapOfBy (==) m1 m2
 
-{- | /O(n+m)/. Is this a proper submap? (ie. a submap but not equal).
+{- | Is this a proper submap? (ie. a submap but not equal).
  The expression (@'isProperSubmapOfBy' f m1 m2@) returns 'True' when
  @m1@ and @m2@ are not equal,
  all keys in @m1@ are in @m2@, and when @f@ returns 'True' when
@@ -876 +1444 @@
   > isProperSubmapOfBy (==) (fromList [(1,1),(2,2)]) (fromList [(1,1),(2,2)])
   > isProperSubmapOfBy (==) (fromList [(1,1),(2,2)]) (fromList [(1,1)])
   > isProperSubmapOfBy (<)  (fromList [(1,1)])       (fromList [(1,1),(2,2)])
+  
+  /O(n+m)/.
 -}
 isProperSubmapOfBy :: Ord k => (a -> b -> Bool) -> Map k a -> Map k b -> Bool
 isProperSubmapOfBy f t1 t2
@@ -884 +1454 @@
 {--------------------------------------------------------------------
   Filter and partition
 --------------------------------------------------------------------}
--- | /O(n)/. Filter all values that satisfy the predicate.
+-- | Filter all values that satisfy the predicate. /O(n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- > filter (> "a") m
+-- >   {3:="b"}
+-- > filter (> "x") m
+-- >   {}
+-- > filter (< "a") m
+-- >   {}
+
 filter :: Ord k => (a -> Bool) -> Map k a -> Map k a
 filter p m
   = filterWithKey (\k x -> p x) m
 
--- | /O(n)/. Filter all keys\/values that satisfy the predicate.
+-- | Filter all keys\/values that satisfy the predicate. /O(n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- > let f k a = k > 4
+-- > filterWithKey f m
+-- >   {5:="a"}
+
 filterWithKey :: Ord k => (k -> a -> Bool) -> Map k a -> Map k a
 filterWithKey p Tip = Tip
 filterWithKey p (Bin _ kx x l r)
@@ -897 +1486 @@
   | otherwise = merge (filterWithKey p l) (filterWithKey p r)
 
 
--- | /O(n)/. partition the map according to a predicate. The first
+-- | Partition the map according to a predicate. The first
 -- map contains all elements that satisfy the predicate, the second all
 -- elements that fail the predicate. See also 'split'.
+-- /O(n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- > partition (> "a") m
+-- >   ({3:="b"},{5:="a"})
+-- > partition (< "x") m
+-- >   ({3:="b",5:="a"},{})
+-- > partition (> "x") m
+-- >   ({},{3:="b",5:="a"})
+
 partition :: Ord k => (a -> Bool) -> Map k a -> (Map k a,Map k a)
 partition p m
   = partitionWithKey (\k x -> p x) m
 
--- | /O(n)/. partition the map according to a predicate. The first
+-- | Partition the map according to a predicate. The first
 -- map contains all elements that satisfy the predicate, the second all
--- elements that fail the predicate. See also 'split'.
+-- elements that fail the predicate. See also 'split'. /O(n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- > partitionWithKey (\ k _ -> k > 3) m
+-- >   ({5:="a"},{3:="b"})
+-- > partitionWithKey (\ k _ -> k < 10) m
+-- >   ({3:="b",5:="a"},{})
+-- > partitionWithKey (\ k _ -> k > 10) m
+-- >   ({},{3:="b",5:="a"})
+
 partitionWithKey :: Ord k => (k -> a -> Bool) -> Map k a -> (Map k a,Map k a)
 partitionWithKey p Tip = (Tip,Tip)
 partitionWithKey p (Bin _ kx x l r)
@@ -916 +1528 @@
     (l1,l2) = partitionWithKey p l
     (r1,r2) = partitionWithKey p r
 
--- | /O(n)/. Map values and collect the 'Just' results.
+-- | Map values and collect the 'Just' results. /O(n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- > let f x = if x == "a" then Just "new a" else Nothing
+-- > mapMaybe f m
+-- >   {5:="new a"}
+
 mapMaybe :: Ord k => (a -> Maybe b) -> Map k a -> Map k b
 mapMaybe f m
   = mapMaybeWithKey (\k x -> f x) m
 
--- | /O(n)/. Map keys\/values and collect the 'Just' results.
+-- | Map keys\/values and collect the 'Just' results. /O(n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- > let f k _ = if k < 5 then Just ("key : " ++ (show k)) else Nothing
+-- > mapMaybeWithKey f m
+-- >   {3,"key : 3"}
+
 mapMaybeWithKey :: Ord k => (k -> a -> Maybe b) -> Map k a -> Map k b
 mapMaybeWithKey f Tip = Tip
 mapMaybeWithKey f (Bin _ kx x l r) = case f kx x of
   Just y  -> join kx y (mapMaybeWithKey f l) (mapMaybeWithKey f r)
   Nothing -> merge (mapMaybeWithKey f l) (mapMaybeWithKey f r)
 
--- | /O(n)/. Map values and separate the 'Left' and 'Right' results.
+-- | Map values and separate the 'Left' and 'Right' results. /O(n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b"), (1, "x"), (10, "z")]
+-- > m
+-- >   {1:="x",3:="b",5:="a",10:="z"}
+-- > let f a = if a < "c" then Left a else Right a
+-- > mapEither f m
+-- >   ({3:="b",5:="a"},{1:="x",10:="z"})
+-- >
+-- > let f a = Right a
+-- > mapEither f m
+-- >   ({},{1:="x",3:="b",5:="a",10:="z"})
+
 mapEither :: Ord k => (a -> Either b c) -> Map k a -> (Map k b, Map k c)
 mapEither f m
   = mapEitherWithKey (\k x -> f x) m
 
--- | /O(n)/. Map keys\/values and separate the 'Left' and 'Right' results.
+-- | Map keys\/values and separate the 'Left' and 'Right' results. /O(n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b"), (1, "x"), (10, "z")]
+-- > m
+-- >   {1:="x",3:="b",5:="a",10:="z"}
+-- > let f k a = if k < 5 then Left k else Right a
+-- > mapEitherWithKey f m
+-- > ({1:=2,3:=6},{5:="a",10:="z"})
+-- >
+-- > let f _ a = Right a
+-- > mapEitherWithKey f m
+-- >   ({},{1:="x",3:="b",5:="a",10:="z"})
+
 mapEitherWithKey :: Ord k =>
   (k -> a -> Either b c) -> Map k a -> (Map k b, Map k c)
 mapEitherWithKey f Tip = (Tip, Tip)
@@ -947 +1599 @@
 {--------------------------------------------------------------------
   Mapping
 --------------------------------------------------------------------}
--- | /O(n)/. Map a function over all values in the map.
+-- | Map a function over all values in the map. /O(n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- > map (++ "x") m
+-- >   {3:="bx",5:="ax"}
+
 map :: (a -> b) -> Map k a -> Map k b
 map f m
   = mapWithKey (\k x -> f x) m
 
--- | /O(n)/. Map a function over all values in the map.
+-- | Map a function over all values in the map. /O(n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- > let f key x = (show key) ++ ":" ++ x
+-- > mapWithKey f m
+-- >   {3:="3:b",5:="5:a"}
+
 mapWithKey :: (k -> a -> b) -> Map k a -> Map k b
 mapWithKey f Tip = Tip
 mapWithKey f (Bin sx kx x l r) 
   = Bin sx kx (f kx x) (mapWithKey f l) (mapWithKey f r)
 
--- | /O(n)/. The function 'mapAccum' threads an accumulating
--- argument through the map in ascending order of keys.
+-- | The function 'mapAccum' threads an accumulating
+-- argument through the map in ascending order of keys. /O(n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- > let f a b = (a ++ b, b ++ "X")
+-- > mapAccum f "Everything: " m
+-- >   ("Everything: ba",{3:="bX",5:="aX"})
+
 mapAccum :: (a -> b -> (a,c)) -> a -> Map k b -> (a,Map k c)
 mapAccum f a m
   = mapAccumWithKey (\a k x -> f a x) a m
 
--- | /O(n)/. The function 'mapAccumWithKey' threads an accumulating
--- argument through the map in ascending order of keys.
+-- | The function 'mapAccumWithKey' threads an accumulating
+-- argument through the map in ascending order of keys. /O(n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- > let f a k b = (a ++ " " ++ (show k) ++ "-" ++ b, b ++ "X")
+-- > mapAccumWithKey f "Everything:" m
+-- >   ("Everything: 3-b 5-a",{3:="bX",5:="aX"})
+
 mapAccumWithKey :: (a -> k -> b -> (a,c)) -> a -> Map k b -> (a,Map k c)
 mapAccumWithKey f a t
   = mapAccumL f a t
 
--- | /O(n)/. The function 'mapAccumL' threads an accumulating
--- argument throught the map in ascending order of keys.
+-- | The function 'mapAccumL' threads an accumulating
+-- argument throught the map in ascending order of keys. /O(n)/.
 mapAccumL :: (a -> k -> b -> (a,c)) -> a -> Map k b -> (a,Map k c)
 mapAccumL f a t
   = case t of
@@ -982 +1665 @@
                  (a3,r') = mapAccumL f a2 r
              in (a3,Bin sx kx x' l' r')
 
--- | /O(n)/. The function 'mapAccumR' threads an accumulating
--- argument throught the map in descending order of keys.
+-- | The function 'mapAccumR' threads an accumulating
+-- argument throught the map in descending order of keys. /O(n)/.
 mapAccumR :: (a -> k -> b -> (a,c)) -> a -> Map k b -> (a,Map k c)
 mapAccumR f a t
   = case t of
@@ -994 +1677 @@
                  (a3,l') = mapAccumR f a2 l
              in (a3,Bin sx kx x' l' r')
 
--- | /O(n*log n)/. 
--- @'mapKeys' f s@ is the map obtained by applying @f@ to each key of @s@.
+-- | @'mapKeys' f s@ is the map obtained by applying @f@ to each key of @s@.
 -- 
 -- The size of the result may be smaller if @f@ maps two or more distinct
 -- keys to the same new key.  In this case the value at the smallest of
--- these keys is retained.
+-- these keys is retained. /O(n*log n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- > mapKeys (+ 1) m
+-- >   {4:="b",6:="a"}
+-- >
+-- > -- overlapping resulting keys
+-- > let m = fromList [(1,"b"), (2,"a"), (3,"d"), (4,"c")]
+-- > m
+-- >   {1:="b",2:="a",3:="d",4:="c"}
+-- > mapKeys (\ _ -> 1) m
+-- >   {1:="c"}
+-- > mapKeys (\ _ -> 3) m
+-- >   {3:="c"}
 
 mapKeys :: Ord k2 => (k1->k2) -> Map k1 a -> Map k2 a
 mapKeys = mapKeysWith (\x y->x)
 
--- | /O(n*log n)/. 
--- @'mapKeysWith' c f s@ is the map obtained by applying @f@ to each key of @s@.
+-- | @'mapKeysWith' c f s@ is the map obtained by applying @f@ to each key of @s@.
 -- 
 -- The size of the result may be smaller if @f@ maps two or more distinct
 -- keys to the same new key.  In this case the associated values will be
--- combined using @c@.
+-- combined using @c@. /O(n*log n)/.
+--
+-- > let m = fromList [(1,"b"), (2,"a"), (3,"d"), (4,"c")]
+-- > m
+-- >   {1:="b",2:="a",3:="d",4:="c"}
+-- > mapKeysWith (++) (\ _ -> 1) m
+-- >   {1:="cdab"}
+-- > mapKeysWith (++) (\ _ -> 3) m
+-- >   {3:="cdab"}
 
 mapKeysWith :: Ord k2 => (a -> a -> a) -> (k1->k2) -> Map k1 a -> Map k2 a
 mapKeysWith c f = fromListWith c . List.map fFirst . toList
     where fFirst (x,y) = (f x, y)
 
 
--- | /O(n)/.
--- @'mapKeysMonotonic' f s == 'mapKeys' f s@, but works only when @f@
+-- | @'mapKeysMonotonic' f s == 'mapKeys' f s@, but works only when @f@
 -- is strictly monotonic.
+-- That is, for any values @x@ and @y@, if @x@ < @y@ then @f x@ < @f y@.
 -- /The precondition is not checked./
 -- Semi-formally, we have:
 -- 
 -- > and [x < y ==> f x < f y | x <- ls, y <- ls] 
 -- >                     ==> mapKeysMonotonic f s == mapKeys f s
 -- >     where ls = keys s
+--
+-- This means that @f@ maps distinct original keys to distinct resulting keys.
+-- This function has better performance than 'mapKeys'. /O(n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- > let result = mapKeysMonotonic (\ k -> k * 2) m
+-- > result
+-- >   {6:="b",10:="a"}
+-- > valid result
+-- >   True
+-- >
+-- > -- resulting map is invalid if the function is non-monotonic
+-- > let result = mapKeysMonotonic (\ _ -> 1) m
+-- > result
+-- >   {1:="b",1:="a"}
+-- > valid result
+-- >   False
 
 mapKeysMonotonic :: (k1->k2) -> Map k1 a -> Map k2 a
 mapKeysMonotonic f Tip = Tip
@@ -1035 +1758 @@
   Folds  
 --------------------------------------------------------------------}
 
--- | /O(n)/. Fold the values in the map, such that
+-- | Fold the values in the map, such that
 -- @'fold' f z == 'Prelude.foldr' f z . 'elems'@.
 -- For example,
 --
 -- > elems map = fold (:) [] map
 --
+-- /O(n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"bbb")]
+-- > m
+-- >   {3:="bbb",5:="a"}
+-- >
+-- > let f a len = len + (length a)
+-- > -- sum of values lengths
+-- > fold f 0 m
+-- >   4
+
 fold :: (a -> b -> b) -> b -> Map k a -> b
 fold f z m
   = foldWithKey (\k x z -> f x z) z m
 
--- | /O(n)/. Fold the keys and values in the map, such that
+-- | Fold the keys and values in the map, such that
 -- @'foldWithKey' f z == 'Prelude.foldr' ('uncurry' f) z . 'toAscList'@.
 -- For example,
 --
 -- > keys map = foldWithKey (\k x ks -> k:ks) [] map
 --
+-- /O(n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- > let f k a result = result ++ "(" ++ (show k) ++ ":" ++ a ++ ")"
+-- > foldWithKey f "Map: " m
+-- >   "Map: (5:a)(3:b)"
+
 foldWithKey :: (k -> a -> b -> b) -> b -> Map k a -> b
 foldWithKey f z t
   = foldr f z t
 
--- | /O(n)/. In-order fold.
+-- | In-order fold. /O(n)/.
 foldi :: (k -> a -> b -> b -> b) -> b -> Map k a -> b 
 foldi f z Tip               = z
 foldi f z (Bin _ kx x l r)  = f kx x (foldi f z l) (foldi f z r)
 
--- | /O(n)/. Post-order fold.
+-- | Post-order fold. /O(n)/.
 foldr :: (k -> a -> b -> b) -> b -> Map k a -> b
 foldr f z Tip              = z
 foldr f z (Bin _ kx x l r) = foldr f (f kx x (foldr f z r)) l
 
--- | /O(n)/. Pre-order fold.
+-- | Pre-order fold. /O(n)/.
 foldl :: (b -> k -> a -> b) -> b -> Map k a -> b
 foldl f z Tip              = z
 foldl f z (Bin _ kx x l r) = foldl f (f (foldl f z l) kx x) r
@@ -1073 +1816 @@
 {--------------------------------------------------------------------
   List variations 
 --------------------------------------------------------------------}
--- | /O(n)/.
--- Return all elements of the map in the ascending order of their keys.
+-- | Return all elements of the map in the ascending order of their keys.
+-- /O(n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- > elems m
+-- >   ["b","a"]
+-- > elems empty
+-- >   []
+
 elems :: Map k a -> [a]
 elems m
   = [x | (k,x) <- assocs m]
 
--- | /O(n)/. Return all keys of the map in ascending order.
+-- | Return all keys of the map in ascending order. /O(n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- > keys m
+-- >   [3,5]
+-- > keys empty
+-- >   []
+
 keys  :: Map k a -> [k]
 keys m
   = [k | (k,x) <- assocs m]
 
--- | /O(n)/. The set of all keys of the map.
+-- | The set of all keys of the map. /O(n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- > keysSet m
+-- >   {3,5}
+-- > keysSet empty
+-- >   {}
+
 keysSet :: Map k a -> Set.Set k
 keysSet m = Set.fromDistinctAscList (keys m)
 
--- | /O(n)/. Return all key\/value pairs in the map in ascending key order.
+-- | Return all key\/value pairs in the map in ascending key order. /O(n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- > assocs m
+-- >   [(3,"b"),(5,"a")]
+-- > assocs empty
+-- >   []
+
 assocs :: Map k a -> [(k,a)]
 assocs m
   = toList m
@@ -1097 +1876 @@
   Lists 
   use [foldlStrict] to reduce demand on the control-stack
 --------------------------------------------------------------------}
--- | /O(n*log n)/. Build a map from a list of key\/value pairs. See also 'fromAscList'.
+-- | Build a map from a list of key\/value pairs. See also 'fromAscList'.
+-- If the list contains more than one value for the same key, the last value
+-- for the key is retained.
+-- /O(n*log n)/.
+--
+-- > fromList [(5,"a"), (3,"b")]
+-- >   {3:="b",5:="a"}
+-- > fromList []
+-- >   {}
+-- > fromList [(5,"a"), (3,"b"), (5, "b")]
+-- >   {3:="b",5:="b"}
+-- > fromList [(5,"b"), (3,"b"), (5, "a")]
+-- >   {3:="b",5:="a"}
+
 fromList :: Ord k => [(k,a)] -> Map k a 
 fromList xs       
   = foldlStrict ins empty xs
   where
     ins t (k,x) = insert k x t
 
--- | /O(n*log n)/. Build a map from a list of key\/value pairs with a combining function. See also 'fromAscListWith'.
+-- | Build a map from a list of key\/value pairs with a combining function. See also 'fromAscListWith'.
+-- /O(n*log n)/.
+--
+-- > fromListWith (++) [(5,"a"), (5,"b"), (3,"b"), (3,"a"), (5,"a")]
+-- >   {3:="ab",5:="aba"}
+-- > fromListWith (++) []
+-- >   {}
+
 fromListWith :: Ord k => (a -> a -> a) -> [(k,a)] -> Map k a 
 fromListWith f xs
   = fromListWithKey (\k x y -> f x y) xs
 
--- | /O(n*log n)/. Build a map from a list of key\/value pairs with a combining function. See also 'fromAscListWithKey'.
+-- | Build a map from a list of key\/value pairs with a combining function. See also 'fromAscListWithKey'.
+-- /O(n*log n)/.
+--
+-- > let f k a1 a2 = (show k) ++ a1 ++ a2
+-- > fromListWithKey f [(5,"a"), (5,"b"), (3,"b"), (3,"a"), (5,"a")]
+-- >   {3:="3ab",5:="5a5ba"}
+-- > fromListWithKey f []
+-- >   {}
+
 fromListWithKey :: Ord k => (k -> a -> a -> a) -> [(k,a)] -> Map k a 
 fromListWithKey f xs 
   = foldlStrict ins empty xs
   where
     ins t (k,x) = insertWithKey f k x t
 
--- | /O(n)/. Convert to a list of key\/value pairs.
+-- | Convert to a list of key\/value pairs. /O(n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- > toList m
+-- >   [(3,"b"),(5,"a")]
+
 toList :: Map k a -> [(k,a)]
 toList t      = toAscList t
 
--- | /O(n)/. Convert to an ascending list.
+-- | Convert to an ascending list. /O(n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- >
+-- > toAscList m
+-- >   [(3,"b"),(5,"a")]
+
 toAscList :: Map k a -> [(k,a)]
 toAscList t   = foldr (\k x xs -> (k,x):xs) [] t
 
 -- | /O(n)/. 
+
 toDescList :: Map k a -> [(k,a)]
 toDescList t  = foldl (\xs k x -> (k,x):xs) [] t
 
@@ -1136 +1959 @@
     fromAscList xs       == fromList xs
     fromAscListWith f xs == fromListWith f xs
 --------------------------------------------------------------------}
--- | /O(n)/. Build a map from an ascending list in linear time.
--- /The precondition (input list is ascending) is not checked./
+-- | Build a map from an ascending list in linear time.
+-- /The precondition (input list is ascending) is not checked./ /O(n)/.
+--
+-- > fromAscList [(3,"b"), (5,"a")]
+-- >   {3:="b",5:="a"}
+-- >
+-- > let result = fromAscList [(3,"b"), (5,"a")]
+-- > result
+-- >   {3:="b",5:="a"}
+-- > let result = fromAscList [(3,"b"), (5,"a"), (5,"b")]
+-- > result
+-- >   {3:="b",5:="b"}
+-- > valid result
+-- >   True
+-- >
+-- > -- invalid map is generated if the list is not ordered
+-- > let result = fromAscList [(5,"a"), (3,"b"), (5,"b")]
+-- > result
+-- >   {5:="a",3:="b",5:="b"}
+-- > valid result
+-- >   False
+
 fromAscList :: Eq k => [(k,a)] -> Map k a 
 fromAscList xs
   = fromAscListWithKey (\k x y -> x) xs
 
--- | /O(n)/. Build a map from an ascending list in linear time with a combining function for equal keys.
--- /The precondition (input list is ascending) is not checked./
+-- | Build a map from an ascending list in linear time with a combining function for equal keys.
+-- /The precondition (input list is ascending) is not checked./ /O(n)/.
+--
+-- > let result = fromAscListWith (++) [(3,"b"), (5,"a"), (5,"b")]
+-- > result
+-- >   {3:="b",5:="ba"}
+-- > valid result
+-- >   True
+-- >
+-- > -- invalid map is generated if the list is not ordered
+-- > let result = fromAscListWith (++) [(5,"a"), (3,"b"), (5,"b")]
+-- > result
+-- >   {5:="a",3:="b",5:="b"}
+-- > valid result
+-- >   False
+
 fromAscListWith :: Eq k => (a -> a -> a) -> [(k,a)] -> Map k a 
 fromAscListWith f xs
   = fromAscListWithKey (\k x y -> f x y) xs
 
--- | /O(n)/. Build a map from an ascending list in linear time with a
+-- | Build a map from an ascending list in linear time with a
 -- combining function for equal keys.
--- /The precondition (input list is ascending) is not checked./
+-- /The precondition (input list is ascending) is not checked./ /O(n)/.
+--
+-- > let f k a1 a2 = (show k) ++ ":" ++ a1 ++ a2
+-- > let result = fromAscListWithKey f [(3,"b"), (5,"a"), (5,"b"), (5,"b")]
+-- > result
+-- >   {3:="b",5:="5:b5:ba"}
+-- > valid result
+-- >   True
+-- >
+-- > -- invalid map is generated if the list is not ordered
+-- > let result = fromAscListWithKey f [(5,"a"), (3,"b"), (5,"b"), (5,"b")]
+-- > result
+-- >   {5:="a",3:="b",5:="5:bb"}
+-- > valid result
+-- >   False
+
 fromAscListWithKey :: Eq k => (k -> a -> a -> a) -> [(k,a)] -> Map k a 
 fromAscListWithKey f xs
   = fromDistinctAscList (combineEq f xs)
@@ -1168 +2040 @@
     | otherwise = z:combineEq' x xs
 
 
--- | /O(n)/. Build a map from an ascending list of distinct elements in linear time.
--- /The precondition is not checked./
+-- | Build a map from an ascending list of distinct elements in linear time.
+-- /The precondition is not checked./ /O(n)/.
+--
+-- > let result = fromDistinctAscList [(3,"b"), (5,"a")]
+-- > result
+-- >   {3:="b",5:="a"}
+-- > valid result
+-- >   True
+-- >
+-- > -- invalid map is generated if the list had non-distinct elements
+-- > let result = fromDistinctAscList [(3,"b"), (5,"a"), (5,"b")]
+-- > result
+-- >   {3:="b",5:="a",5:="b"}
+-- > valid result
+-- >   False
+
 fromDistinctAscList :: [(k,a)] -> Map k a 
 fromDistinctAscList xs
   = build const (length xs) xs
@@ -1255 +2141 @@
 {--------------------------------------------------------------------
   Split
 --------------------------------------------------------------------}
--- | /O(log n)/. The expression (@'split' k map@) is a pair @(map1,map2)@ where
--- the keys in @map1@ are smaller than @k@ and the keys in @map2@ larger than @k@. Any key equal to @k@ is found in neither @map1@ nor @map2@.
+-- | The expression (@'split' k map@) is a pair @(map1,map2)@ where
+-- the keys in @map1@ are smaller than @k@ and the keys in @map2@ larger than @k@.
+-- Any key equal to @k@ is found in neither @map1@ nor @map2@.
+-- /O(log n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- > split 2 m
+-- >   ({},{3:="b",5:="a"})
+-- > split 3 m
+-- >   ({},{5:="a"})
+-- > split 4 m
+-- >   ({3:="b"},{5:="a"})
+-- > split 5 m
+-- >   ({3:="b"},{})
+-- > split 6 m
+-- >   ({3:="b",5:="a"},{})
+
 split :: Ord k => k -> Map k a -> (Map k a,Map k a)
 split k Tip = (Tip,Tip)
 split k (Bin sx kx x l r)
@@ -1265 +2168 @@
       GT -> let (lt,gt) = split k r in (join kx x l lt,gt)
       EQ -> (l,r)
 
--- | /O(log n)/. The expression (@'splitLookup' k map@) splits a map just
+-- | The expression (@'splitLookup' k map@) splits a map just
 -- like 'split' but also returns @'lookup' k map@.
+-- /O(log n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b")]
+-- > m
+-- >   {3:="b",5:="a"}
+-- > splitLookup 2 m
+-- >   ({},Nothing,{3:="b",5:="a"})
+-- > splitLookup 3 m
+-- >   ({},Just "b",{5:="a"})
+-- > splitLookup 4 m
+-- >   ({3:="b"},Nothing,{5,"a"})
+-- > splitLookup 5 m
+-- >   ({3,"b"},Just "a",{})
+-- > splitLookup 6 m
+-- >   ({3:="b",5:="a"},Nothing,{})
+
 splitLookup :: Ord k => k -> Map k a -> (Map k a,Maybe a,Map k a)
 splitLookup k Tip = (Tip,Nothing,Tip)
 splitLookup k (Bin sx kx x l r)
@@ -1284 +2203 @@
       GT -> let (lt,z,gt) = splitLookupWithKey k r in (join kx x l lt,z,gt)
       EQ -> (l,Just (kx, x),r)
 
--- | /O(log n)/. Performs a 'split' but also returns whether the pivot
+-- | Performs a 'split' but also returns whether the pivot
 -- element was found in the original set.
+-- /O(log n)/.
 splitMember :: Ord k => k -> Map k a -> (Map k a,Bool,Map k a)
 splitMember x t = let (l,m,r) = splitLookup x t in
      (l,maybe False (const True) m,r)
@@ -1369 +2289 @@
   | otherwise       = let ((km,m),r') = deleteFindMin r in balance km m l r'
 
 
--- | /O(log n)/. Delete and find the minimal element.
+-- | Delete and find the minimal element. /O(log n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b"), (10,"c")]
+-- > m
+-- >   {3:="b",5:="a",10:="c"}
+-- > deleteFindMin m
+-- >   ((3,"b"),{5:="a",10:="c"})
+-- > deleteFindMin empty
+-- >   Exception: Map.deleteFindMin: can not return the minimal element of an empty map
+
 deleteFindMin :: Map k a -> ((k,a),Map k a)
 deleteFindMin t 
   = case t of
@@ -1377 +2306 @@
       Bin _ k x l r   -> let (km,l') = deleteFindMin l in (km,balance k x l' r)
       Tip             -> (error "Map.deleteFindMin: can not return the minimal element of an empty map", Tip)
 
--- | /O(log n)/. Delete and find the maximal element.
+-- | Delete and find the maximal element. /O(log n)/.
+--
+-- > let m = fromList [(5,"a"), (3,"b"), (10,"c")]
+-- > m
+-- >   {3:="b",5:="a",10:="c"}
+-- > deleteFindMax m
+-- >   ((10,"c"),{3:="b",5:="a"})
+-- > deleteFindMax empty
+-- >   Exception: Map.deleteFindMax: can not return the maximal element of an empty map
+
 deleteFindMax :: Map k a -> ((k,a),Map k a)
 deleteFindMax t
   = case t of
@@ -1531 +2469 @@
     showElem (k,x)  = shows k . showString " := " . shows x
   
 
--- | /O(n)/. Show the tree that implements the map. The tree is shown
--- in a compressed, hanging format.
+-- | Show the tree that implements the map. The tree is shown
+-- in a compressed, hanging format. See 'showTreeWith'. /O(n)/.
 showTree :: (Show k,Show a) => Map k a -> String
 showTree m
   = showTreeWith showElem True False m
@@ -1540 +2478 @@
     showElem k x  = show k ++ ":=" ++ show x
 
 
-{- | /O(n)/. The expression (@'showTreeWith' showelem hang wide map@) shows
+{- | The expression (@'showTreeWith' showelem hang wide map@) shows
  the tree that implements the map. Elements are shown using the @showElem@ function. If @hang@ is
  'True', a /hanging/ tree is shown otherwise a rotated tree is shown. If
- @wide@ is 'True', an extra wide version is shown.
+ @wide@ is 'True', an extra wide version is shown. /O(n)/.
 
 >  Map> let t = fromDistinctAscList [(x,()) | x <- [1..5]]
 >  Map> putStrLn $ showTreeWith (\k x -> show (k,x)) True False t
@@ -1632 +2570 @@
 {--------------------------------------------------------------------
   Assertions
 --------------------------------------------------------------------}
--- | /O(n)/. Test if the internal map structure is valid.
+-- | Test if the internal map structure is valid. /O(n)/.
+--
+-- > let result = fromAscList [(3,"b"), (5,"a")]
+-- > result
+-- >   {3:="b",5:="a"}
+-- > let result = fromAscList [(3,"b"), (5,"a"), (5,"b")]
+-- > result
+-- >   {3:="b",5:="b"}
+-- > valid result
+-- >   True
+-- >
+-- > -- invalid map is generated if the list is not ordered
+-- > let result = fromAscList [(5,"a"), (3,"b"), (5,"b")]
+-- > result
+-- >   {5:="a",3:="b",5:="b"}
+-- > valid result
+-- >   False
+
 valid :: Ord k => Map k a -> Bool
 valid t
   = balanced t && ordered t && validsize t