Ticket #1611: Map.diff

File Map.diff, 90.8 KB (added by guest, 8 years ago)

The diff.

  • Data/IntMap.hs

    diff -rN -u old-src/Data/IntMap.hs new-src/Data/IntMap.hs
    old new  
    1 {-# OPTIONS -cpp -fglasgow-exts -fno-bang-patterns #-}  
     1{-TODO - enable # OPTIONS -cpp -fglasgow-exts -fno-bang-patterns #-}  
    22----------------------------------------------------------------------------- 
    33-- | 
    44-- Module      :  Data.IntMap 
     
    3030--      Information Coded In Alphanumeric/\", Journal of the ACM, 15(4), 
    3131--      October 1968, pages 514-534. 
    3232-- 
     33-- Operation comments contain the operation time complexity in 
     34-- the Big-O notation <http://en.wikipedia.org/wiki/Big_O_notation>. 
    3335-- Many operations have a worst-case complexity of /O(min(n,W))/. 
    3436-- This means that the operation can become linear in the number of 
    3537-- elements with a maximum of /W/ -- the number of bits in an 'Int' 
     
    215217  Operators 
    216218--------------------------------------------------------------------} 
    217219 
    218 -- | /O(min(n,W))/. Find the value at a key. 
    219 -- Calls 'error' when the element can not be found. 
     220-- | Find the value at a key. 
     221-- Calls 'error' when the element can not be found. /O(min(n,W))/. 
    220222 
    221223(!) :: IntMap a -> Key -> a 
    222224m ! k    = find' k m 
    223225 
    224 -- | /O(n+m)/. See 'difference'. 
     226-- | See 'difference'. /O(n+m)/. 
    225227(\\) :: IntMap a -> IntMap b -> IntMap a 
    226228m1 \\ m2 = difference m1 m2 
    227229 
     
    268270{-------------------------------------------------------------------- 
    269271  Query 
    270272--------------------------------------------------------------------} 
    271 -- | /O(1)/. Is the map empty? 
     273-- | Is the map empty? /O(1)/. 
    272274null :: IntMap a -> Bool 
    273275null Nil   = True 
    274276null other = False 
    275277 
    276 -- | /O(n)/. Number of elements in the map. 
     278-- | Number of elements in the map. /O(n)/. 
    277279size :: IntMap a -> Int 
    278280size t 
    279281  = case t of 
     
    281283      Tip k x -> 1 
    282284      Nil     -> 0 
    283285 
    284 -- | /O(min(n,W))/. Is the key a member of the map? 
     286-- | Is the key a member of the map? /O(min(n,W))/. 
    285287member :: Key -> IntMap a -> Bool 
    286288member k m 
    287289  = case lookup k m of 
    288290      Nothing -> False 
    289291      Just x  -> True 
    290292     
    291 -- | /O(log n)/. Is the key not a member of the map? 
     293-- | Is the key not a member of the map? /O(log n)/. 
    292294notMember :: Key -> IntMap a -> Bool 
    293295notMember k m = not $ member k m 
    294296 
    295 -- | /O(min(n,W))/. Lookup the value at a key in the map. 
     297-- | Lookup the value at a key in the map. /O(min(n,W))/. 
    296298lookup :: (Monad m) => Key -> IntMap a -> m a 
    297299lookup k t = case lookup' k t of 
    298300    Just x -> return x 
     
    320322      Just x  -> x 
    321323 
    322324 
    323 -- | /O(min(n,W))/. The expression @('findWithDefault' def k map)@ 
     325-- | The expression @('findWithDefault' def k map)@ 
    324326-- returns the value at key @k@ or returns @def@ when the key is not an 
    325 -- element of the map. 
     327-- element of the map. /O(min(n,W))/. 
    326328findWithDefault :: a -> Key -> IntMap a -> a 
    327329findWithDefault def k m 
    328330  = case lookup k m of 
     
    332334{-------------------------------------------------------------------- 
    333335  Construction 
    334336--------------------------------------------------------------------} 
    335 -- | /O(1)/. The empty map. 
     337-- | The empty map. /O(1)/. 
    336338empty :: IntMap a 
    337339empty 
    338340  = Nil 
    339341 
    340 -- | /O(1)/. A map of one element. 
     342-- | A map of one element. /O(1)/. 
    341343singleton :: Key -> a -> IntMap a 
    342344singleton k x 
    343345  = Tip k x 
     
    345347{-------------------------------------------------------------------- 
    346348  Insert 
    347349--------------------------------------------------------------------} 
    348 -- | /O(min(n,W))/. Insert a new key\/value pair in the map. 
     350-- | Insert a new key\/value pair in the map. 
    349351-- If the key is already present in the map, the associated value is 
    350352-- replaced with the supplied value, i.e. 'insert' is equivalent to 
    351 -- @'insertWith' 'const'@. 
     353-- @'insertWith' 'const'@. /O(min(n,W))/. 
    352354insert :: Key -> a -> IntMap a -> IntMap a 
    353355insert k x t 
    354356  = case t of 
     
    362364      Nil -> Tip k x 
    363365 
    364366-- right-biased insertion, used by 'union' 
    365 -- | /O(min(n,W))/. Insert with a combining function. 
     367-- | Insert with a combining function. 
    366368-- @'insertWith' f key value mp@  
    367369-- will insert the pair (key, value) into @mp@ if key does 
    368370-- not exist in the map. If the key does exist, the function will 
    369 -- insert @f new_value old_value@. 
     371-- insert @f new_value old_value@. /O(min(n,W))/. 
    370372insertWith :: (a -> a -> a) -> Key -> a -> IntMap a -> IntMap a 
    371373insertWith f k x t 
    372374  = insertWithKey (\k x y -> f x y) k x t 
    373375 
    374 -- | /O(min(n,W))/. Insert with a combining function. 
     376-- | Insert with a combining function. 
    375377-- @'insertWithKey' f key value mp@  
    376378-- will insert the pair (key, value) into @mp@ if key does 
    377379-- not exist in the map. If the key does exist, the function will 
    378 -- insert @f key new_value old_value@. 
     380-- insert @f key new_value old_value@. /O(min(n,W))/. 
    379381insertWithKey :: (Key -> a -> a -> a) -> Key -> a -> IntMap a -> IntMap a 
    380382insertWithKey f k x t 
    381383  = case t of 
     
    389391      Nil -> Tip k x 
    390392 
    391393 
    392 -- | /O(min(n,W))/. The expression (@'insertLookupWithKey' f k x map@) 
     394-- | The expression (@'insertLookupWithKey' f k x map@) 
    393395-- is a pair where the first element is equal to (@'lookup' k map@) 
    394 -- and the second element equal to (@'insertWithKey' f k x map@). 
     396-- and the second element equal to (@'insertWithKey' f k x map@). /O(min(n,W))/. 
    395397insertLookupWithKey :: (Key -> a -> a -> a) -> Key -> a -> IntMap a -> (Maybe a, IntMap a) 
    396398insertLookupWithKey f k x t 
    397399  = case t of 
     
    409411  Deletion 
    410412  [delete] is the inlined version of [deleteWith (\k x -> Nothing)] 
    411413--------------------------------------------------------------------} 
    412 -- | /O(min(n,W))/. Delete a key and its value from the map. When the key is not 
    413 -- a member of the map, the original map is returned. 
     414-- | Delete a key and its value from the map. When the key is not 
     415-- a member of the map, the original map is returned. /O(min(n,W))/. 
    414416delete :: Key -> IntMap a -> IntMap a 
    415417delete k t 
    416418  = case t of 
     
    423425        | otherwise     -> t 
    424426      Nil -> Nil 
    425427 
    426 -- | /O(min(n,W))/. Adjust a value at a specific key. When the key is not 
    427 -- a member of the map, the original map is returned. 
     428-- | Adjust a value at a specific key. When the key is not 
     429-- a member of the map, the original map is returned. /O(min(n,W))/. 
    428430adjust ::  (a -> a) -> Key -> IntMap a -> IntMap a 
    429431adjust f k m 
    430432  = adjustWithKey (\k x -> f x) k m 
    431433 
    432 -- | /O(min(n,W))/. Adjust a value at a specific key. When the key is not 
    433 -- a member of the map, the original map is returned. 
     434-- | Adjust a value at a specific key. When the key is not 
     435-- a member of the map, the original map is returned. /O(min(n,W))/. 
    434436adjustWithKey ::  (Key -> a -> a) -> Key -> IntMap a -> IntMap a 
    435437adjustWithKey f k m 
    436438  = updateWithKey (\k x -> Just (f k x)) k m 
    437439 
    438 -- | /O(min(n,W))/. The expression (@'update' f k map@) updates the value @x@ 
     440-- | The expression (@'update' f k map@) updates the value @x@ 
    439441-- at @k@ (if it is in the map). If (@f x@) is 'Nothing', the element is 
    440442-- deleted. If it is (@'Just' y@), the key @k@ is bound to the new value @y@. 
     443-- /O(min(n,W))/. 
    441444update ::  (a -> Maybe a) -> Key -> IntMap a -> IntMap a 
    442445update f k m 
    443446  = updateWithKey (\k x -> f x) k m 
    444447 
    445 -- | /O(min(n,W))/. The expression (@'update' f k map@) updates the value @x@ 
     448-- | The expression (@'update' f k map@) updates the value @x@ 
    446449-- at @k@ (if it is in the map). If (@f k x@) is 'Nothing', the element is 
    447450-- deleted. If it is (@'Just' y@), the key @k@ is bound to the new value @y@. 
     451-- /O(min(n,W))/. 
    448452updateWithKey ::  (Key -> a -> Maybe a) -> Key -> IntMap a -> IntMap a 
    449453updateWithKey f k t 
    450454  = case t of 
     
    459463        | otherwise     -> t 
    460464      Nil -> Nil 
    461465 
    462 -- | /O(min(n,W))/. Lookup and update. 
     466-- | Lookup and update. /O(min(n,W))/. 
    463467updateLookupWithKey ::  (Key -> a -> Maybe a) -> Key -> IntMap a -> (Maybe a,IntMap a) 
    464468updateLookupWithKey f k t 
    465469  = case t of 
     
    476480 
    477481 
    478482 
    479 -- | /O(log n)/. The expression (@'alter' f k map@) alters the value @x@ at @k@, or absence thereof. 
     483-- | The expression (@'alter' f k map@) alters the value @x@ at @k@, or absence thereof. 
    480484-- 'alter' can be used to insert, delete, or update a value in a 'Map'. 
    481 -- In short : @'lookup' k ('alter' f k m) = f ('lookup' k m)@ 
     485-- In short : @'lookup' k ('alter' f k m) = f ('lookup' k m)@. /O(log n)/. 
    482486alter f k t 
    483487  = case t of 
    484488      Bin p m l r  
     
    512516unionsWith f ts 
    513517  = foldlStrict (unionWith f) empty ts 
    514518 
    515 -- | /O(n+m)/. The (left-biased) union of two maps.  
     519-- | The (left-biased) union of two maps.  
    516520-- It prefers the first map when duplicate keys are encountered, 
    517 -- i.e. (@'union' == 'unionWith' 'const'@). 
     521-- i.e. (@'union' == 'unionWith' 'const'@). /O(n+m)/. 
    518522union :: IntMap a -> IntMap a -> IntMap a 
    519523union t1@(Bin p1 m1 l1 r1) t2@(Bin p2 m2 l2 r2) 
    520524  | shorter m1 m2  = union1 
     
    535539union Nil t       = t 
    536540union t Nil       = t 
    537541 
    538 -- | /O(n+m)/. The union with a combining function.  
     542-- | The union with a combining function. /O(n+m)/. 
    539543unionWith :: (a -> a -> a) -> IntMap a -> IntMap a -> IntMap a 
    540544unionWith f m1 m2 
    541545  = unionWithKey (\k x y -> f x y) m1 m2 
    542546 
    543 -- | /O(n+m)/. The union with a combining function.  
     547-- | The union with a combining function. /O(n+m)/. 
    544548unionWithKey :: (Key -> a -> a -> a) -> IntMap a -> IntMap a -> IntMap a 
    545549unionWithKey f t1@(Bin p1 m1 l1 r1) t2@(Bin p2 m2 l2 r2) 
    546550  | shorter m1 m2  = union1 
     
    564568{-------------------------------------------------------------------- 
    565569  Difference 
    566570--------------------------------------------------------------------} 
    567 -- | /O(n+m)/. Difference between two maps (based on keys).  
     571-- | Difference between two maps (based on keys). /O(n+m)/. 
    568572difference :: IntMap a -> IntMap b -> IntMap a 
    569573difference t1@(Bin p1 m1 l1 r1) t2@(Bin p2 m2 l2 r2) 
    570574  | shorter m1 m2  = difference1 
     
    588592difference t (Tip k x) = delete k t 
    589593difference t Nil       = t 
    590594 
    591 -- | /O(n+m)/. Difference with a combining function.  
     595-- | Difference with a combining function. /O(n+m)/. 
    592596differenceWith :: (a -> b -> Maybe a) -> IntMap a -> IntMap b -> IntMap a 
    593597differenceWith f m1 m2 
    594598  = differenceWithKey (\k x y -> f x y) m1 m2 
    595599 
    596 -- | /O(n+m)/. Difference with a combining function. When two equal keys are 
     600-- | Difference with a combining function. When two equal keys are 
    597601-- encountered, the combining function is applied to the key and both values. 
    598602-- If it returns 'Nothing', the element is discarded (proper set difference). 
    599603-- If it returns (@'Just' y@), the element is updated with a new value @y@.  
     604-- /O(n+m)/. 
    600605differenceWithKey :: (Key -> a -> b -> Maybe a) -> IntMap a -> IntMap b -> IntMap a 
    601606differenceWithKey f t1@(Bin p1 m1 l1 r1) t2@(Bin p2 m2 l2 r2) 
    602607  | shorter m1 m2  = difference1 
     
    627632{-------------------------------------------------------------------- 
    628633  Intersection 
    629634--------------------------------------------------------------------} 
    630 -- | /O(n+m)/. The (left-biased) intersection of two maps (based on keys).  
     635-- | The (left-biased) intersection of two maps (based on keys). /O(n+m)/. 
    631636intersection :: IntMap a -> IntMap b -> IntMap a 
    632637intersection t1@(Bin p1 m1 l1 r1) t2@(Bin p2 m2 l2 r2) 
    633638  | shorter m1 m2  = intersection1 
     
    653658intersection Nil t = Nil 
    654659intersection t Nil = Nil 
    655660 
    656 -- | /O(n+m)/. The intersection with a combining function.  
     661-- | The intersection with a combining function. /O(n+m)/. 
    657662intersectionWith :: (a -> b -> a) -> IntMap a -> IntMap b -> IntMap a 
    658663intersectionWith f m1 m2 
    659664  = intersectionWithKey (\k x y -> f x y) m1 m2 
    660665 
    661 -- | /O(n+m)/. The intersection with a combining function.  
     666-- | The intersection with a combining function. /O(n+m)/. 
    662667intersectionWithKey :: (Key -> a -> b -> a) -> IntMap a -> IntMap b -> IntMap a 
    663668intersectionWithKey f t1@(Bin p1 m1 l1 r1) t2@(Bin p2 m2 l2 r2) 
    664669  | shorter m1 m2  = intersection1 
     
    690695  Min\/Max 
    691696--------------------------------------------------------------------} 
    692697 
    693 -- | /O(log n)/. Update the value at the minimal key. 
     698-- | Update the value at the minimal key. /O(log n)/. 
    694699updateMinWithKey :: (Key -> a -> a) -> IntMap a -> IntMap a 
    695700updateMinWithKey f t 
    696701    = case t of 
     
    704709        Bin p m l r -> let t' = updateMinWithKeyUnsigned f r in Bin p m l t' 
    705710        Tip k y -> Tip k (f k y) 
    706711 
    707 -- | /O(log n)/. Update the value at the maximal key. 
     712-- | Update the value at the maximal key. /O(log n)/. 
    708713updateMaxWithKey :: (Key -> a -> a) -> IntMap a -> IntMap a 
    709714updateMaxWithKey f t 
    710715    = case t of 
     
    719724        Tip k y -> Tip k (f k y) 
    720725 
    721726 
    722 -- | /O(log n)/. Retrieves the maximal (key,value) couple of the map, and the map stripped from that element. 
    723 -- @fail@s (in the monad) when passed an empty map. 
     727-- | Retrieves the maximal (key,value) couple of the map, and the map stripped from that element. 
     728-- @fail@s (in the monad) when passed an empty map. /O(log n)/. 
    724729maxViewWithKey :: (Monad m) => IntMap a -> m ((Key, a), IntMap a) 
    725730maxViewWithKey t 
    726731    = case t of 
     
    734739        Bin p m l r -> let (result,t') = maxViewUnsigned r in (result,bin p m l t') 
    735740        Tip k y -> ((k,y), Nil) 
    736741 
    737 -- | /O(log n)/. Retrieves the minimal (key,value) couple of the map, and the map stripped from that element. 
    738 -- @fail@s (in the monad) when passed an empty map. 
     742-- | Retrieves the minimal (key,value) couple of the map, and the map stripped from that element. 
     743-- @fail@s (in the monad) when passed an empty map. /O(log n)/. 
    739744minViewWithKey :: (Monad m) => IntMap a -> m ((Key, a), IntMap a) 
    740745minViewWithKey t 
    741746    = case t of 
     
    750755        Tip k y -> ((k,y),Nil) 
    751756 
    752757 
    753 -- | /O(log n)/. Update the value at the maximal key. 
     758-- | Update the value at the maximal key. /O(log n)/. 
    754759updateMax :: (a -> a) -> IntMap a -> IntMap a 
    755760updateMax f = updateMaxWithKey (const f) 
    756761 
    757 -- | /O(log n)/. Update the value at the minimal key. 
     762-- | Update the value at the minimal key. /O(log n)/. 
    758763updateMin :: (a -> a) -> IntMap a -> IntMap a 
    759764updateMin f = updateMinWithKey (const f) 
    760765 
     
    768773first f (x,y) = (f x,y) 
    769774 
    770775 
    771 -- | /O(log n)/. Retrieves the maximal key of the map, and the map stripped from that element. 
    772 -- @fail@s (in the monad) when passed an empty map. 
     776-- | Retrieves the maximal key of the map, and the map stripped from that element. 
     777-- @fail@s (in the monad) when passed an empty map. /O(log n)/. 
    773778maxView t = liftM (first snd) (maxViewWithKey t) 
    774779 
    775 -- | /O(log n)/. Retrieves the minimal key of the map, and the map stripped from that element. 
     780-- | Retrieves the minimal key of the map, and the map stripped from that element. 
    776781-- @fail@s (in the monad) when passed an empty map. 
     782-- /O(log n)/. 
    777783minView t = liftM (first snd) (minViewWithKey t) 
    778784 
    779 -- | /O(log n)/. Delete and find the maximal element. 
     785-- | Delete and find the maximal element. /O(log n)/. 
    780786deleteFindMax = runIdentity . maxView 
    781787 
    782 -- | /O(log n)/. Delete and find the minimal element. 
     788-- | Delete and find the minimal element. /O(log n)/. 
    783789deleteFindMin = runIdentity . minView 
    784790 
    785 -- | /O(log n)/. The minimal key of the map. 
     791-- | The minimal key of the map. /O(log n)/. 
    786792findMin = fst . runIdentity . minView 
    787793 
    788 -- | /O(log n)/. The maximal key of the map. 
     794-- | The maximal key of the map. /O(log n)/. 
    789795findMax = fst . runIdentity . maxView 
    790796 
    791 -- | /O(log n)/. Delete the minimal key. 
     797-- | Delete the minimal key. /O(log n)/. 
    792798deleteMin = snd . runIdentity . minView 
    793799 
    794 -- | /O(log n)/. Delete the maximal key. 
     800-- | Delete the maximal key. /O(log n)/. 
    795801deleteMax = snd . runIdentity . maxView 
    796802 
    797803 
    798804{-------------------------------------------------------------------- 
    799805  Submap 
    800806--------------------------------------------------------------------} 
    801 -- | /O(n+m)/. Is this a proper submap? (ie. a submap but not equal).  
    802 -- Defined as (@'isProperSubmapOf' = 'isProperSubmapOfBy' (==)@). 
     807-- | Is this a proper submap? (ie. a submap but not equal).  
     808-- Defined as (@'isProperSubmapOf' = 'isProperSubmapOfBy' (==)@). /O(n+m)/. 
    803809isProperSubmapOf :: Eq a => IntMap a -> IntMap a -> Bool 
    804810isProperSubmapOf m1 m2 
    805811  = isProperSubmapOfBy (==) m1 m2 
    806812 
    807 {- | /O(n+m)/. Is this a proper submap? (ie. a submap but not equal). 
     813{- | Is this a proper submap? (ie. a submap but not equal). 
    808814 The expression (@'isProperSubmapOfBy' f m1 m2@) returns 'True' when 
    809815 @m1@ and @m2@ are not equal, 
    810816 all keys in @m1@ are in @m2@, and when @f@ returns 'True' when 
     
    819825  > isProperSubmapOfBy (==) (fromList [(1,1),(2,2)]) (fromList [(1,1),(2,2)]) 
    820826  > isProperSubmapOfBy (==) (fromList [(1,1),(2,2)]) (fromList [(1,1)]) 
    821827  > isProperSubmapOfBy (<)  (fromList [(1,1)])       (fromList [(1,1),(2,2)]) 
     828 
     829 /O(n+m)/. 
    822830-} 
    823831isProperSubmapOfBy :: (a -> b -> Bool) -> IntMap a -> IntMap b -> Bool 
    824832isProperSubmapOfBy pred t1 t2 
     
    852860submapCmp pred Nil Nil = EQ 
    853861submapCmp pred Nil t   = LT 
    854862 
    855 -- | /O(n+m)/. Is this a submap? 
    856 -- Defined as (@'isSubmapOf' = 'isSubmapOfBy' (==)@). 
     863-- | Is this a submap? 
     864-- Defined as (@'isSubmapOf' = 'isSubmapOfBy' (==)@). /O(n+m)/. 
    857865isSubmapOf :: Eq a => IntMap a -> IntMap a -> Bool 
    858866isSubmapOf m1 m2 
    859867  = isSubmapOfBy (==) m1 m2 
    860868 
    861 {- | /O(n+m)/.  
    862  The expression (@'isSubmapOfBy' f m1 m2@) returns 'True' if 
     869{- | The expression (@'isSubmapOfBy' f m1 m2@) returns 'True' if 
    863870 all keys in @m1@ are in @m2@, and when @f@ returns 'True' when 
    864871 applied to their respective values. For example, the following  
    865872 expressions are all 'True': 
     
    873880  > isSubmapOfBy (==) (fromList [(1,2)]) (fromList [(1,1),(2,2)]) 
    874881  > isSubmapOfBy (<) (fromList [(1,1)]) (fromList [(1,1),(2,2)]) 
    875882  > isSubmapOfBy (==) (fromList [(1,1),(2,2)]) (fromList [(1,1)]) 
     883 
     884 /O(n+m)/.  
    876885-} 
    877886 
    878887isSubmapOfBy :: (a -> b -> Bool) -> IntMap a -> IntMap b -> Bool 
     
    890899{-------------------------------------------------------------------- 
    891900  Mapping 
    892901--------------------------------------------------------------------} 
    893 -- | /O(n)/. Map a function over all values in the map. 
     902-- | Map a function over all values in the map. /O(n)/. 
    894903map :: (a -> b) -> IntMap a -> IntMap b 
    895904map f m 
    896905  = mapWithKey (\k x -> f x) m 
    897906 
    898 -- | /O(n)/. Map a function over all values in the map. 
     907-- | Map a function over all values in the map. /O(n)/. 
    899908mapWithKey :: (Key -> a -> b) -> IntMap a -> IntMap b 
    900909mapWithKey f t   
    901910  = case t of 
     
    903912      Tip k x     -> Tip k (f k x) 
    904913      Nil         -> Nil 
    905914 
    906 -- | /O(n)/. The function @'mapAccum'@ threads an accumulating 
    907 -- argument through the map in ascending order of keys. 
     915-- | The function @'mapAccum'@ threads an accumulating 
     916-- argument through the map in ascending order of keys. /O(n)/. 
    908917mapAccum :: (a -> b -> (a,c)) -> a -> IntMap b -> (a,IntMap c) 
    909918mapAccum f a m 
    910919  = mapAccumWithKey (\a k x -> f a x) a m 
    911920 
    912 -- | /O(n)/. The function @'mapAccumWithKey'@ threads an accumulating 
    913 -- argument through the map in ascending order of keys. 
     921-- | The function @'mapAccumWithKey'@ threads an accumulating 
     922-- argument through the map in ascending order of keys. /O(n)/. 
    914923mapAccumWithKey :: (a -> Key -> b -> (a,c)) -> a -> IntMap b -> (a,IntMap c) 
    915924mapAccumWithKey f a t 
    916925  = mapAccumL f a t 
    917926 
    918 -- | /O(n)/. The function @'mapAccumL'@ threads an accumulating 
    919 -- argument through the map in ascending order of keys. 
     927-- | The function @'mapAccumL'@ threads an accumulating 
     928-- argument through the map in ascending order of keys. /O(n)/. 
    920929mapAccumL :: (a -> Key -> b -> (a,c)) -> a -> IntMap b -> (a,IntMap c) 
    921930mapAccumL f a t 
    922931  = case t of 
     
    927936      Nil         -> (a,Nil) 
    928937 
    929938 
    930 -- | /O(n)/. The function @'mapAccumR'@ threads an accumulating 
    931 -- argument throught the map in descending order of keys. 
     939-- | The function @'mapAccumR'@ threads an accumulating 
     940-- argument throught the map in descending order of keys. /O(n)/. 
    932941mapAccumR :: (a -> Key -> b -> (a,c)) -> a -> IntMap b -> (a,IntMap c) 
    933942mapAccumR f a t 
    934943  = case t of 
     
    941950{-------------------------------------------------------------------- 
    942951  Filter 
    943952--------------------------------------------------------------------} 
    944 -- | /O(n)/. Filter all values that satisfy some predicate. 
     953-- | Filter all values that satisfy some predicate. /O(n)/. 
    945954filter :: (a -> Bool) -> IntMap a -> IntMap a 
    946955filter p m 
    947956  = filterWithKey (\k x -> p x) m 
    948957 
    949 -- | /O(n)/. Filter all keys\/values that satisfy some predicate. 
     958-- | Filter all keys\/values that satisfy some predicate. /O(n)/. 
    950959filterWithKey :: (Key -> a -> Bool) -> IntMap a -> IntMap a 
    951960filterWithKey pred t 
    952961  = case t of 
     
    957966        | otherwise -> Nil 
    958967      Nil -> Nil 
    959968 
    960 -- | /O(n)/. partition the map according to some predicate. The first 
     969-- | Partition the map according to some predicate. The first 
    961970-- map contains all elements that satisfy the predicate, the second all 
    962 -- elements that fail the predicate. See also 'split'. 
     971-- elements that fail the predicate. See also 'split'. /O(n)/. 
    963972partition :: (a -> Bool) -> IntMap a -> (IntMap a,IntMap a) 
    964973partition p m 
    965974  = partitionWithKey (\k x -> p x) m 
    966975 
    967 -- | /O(n)/. partition the map according to some predicate. The first 
     976-- | Partition the map according to some predicate. The first 
    968977-- map contains all elements that satisfy the predicate, the second all 
    969 -- elements that fail the predicate. See also 'split'. 
     978-- elements that fail the predicate. See also 'split'. /O(n)/. 
    970979partitionWithKey :: (Key -> a -> Bool) -> IntMap a -> (IntMap a,IntMap a) 
    971980partitionWithKey pred t 
    972981  = case t of 
     
    979988        | otherwise -> (Nil,t) 
    980989      Nil -> (Nil,Nil) 
    981990 
    982 -- | /O(n)/. Map values and collect the 'Just' results. 
     991-- | Map values and collect the 'Just' results. /O(n)/. 
    983992mapMaybe :: (a -> Maybe b) -> IntMap a -> IntMap b 
    984993mapMaybe f m 
    985994  = mapMaybeWithKey (\k x -> f x) m 
    986995 
    987 -- | /O(n)/. Map keys\/values and collect the 'Just' results. 
     996-- | Map keys\/values and collect the 'Just' results. /O(n)/. 
    988997mapMaybeWithKey :: (Key -> a -> Maybe b) -> IntMap a -> IntMap b 
    989998mapMaybeWithKey f (Bin p m l r) 
    990999  = bin p m (mapMaybeWithKey f l) (mapMaybeWithKey f r) 
     
    9931002  Nothing -> Nil 
    9941003mapMaybeWithKey f Nil = Nil 
    9951004 
    996 -- | /O(n)/. Map values and separate the 'Left' and 'Right' results. 
     1005-- | Map values and separate the 'Left' and 'Right' results. /O(n)/. 
    9971006mapEither :: (a -> Either b c) -> IntMap a -> (IntMap b, IntMap c) 
    9981007mapEither f m 
    9991008  = mapEitherWithKey (\k x -> f x) m 
    10001009 
    1001 -- | /O(n)/. Map keys\/values and separate the 'Left' and 'Right' results. 
     1010-- | Map keys\/values and separate the 'Left' and 'Right' results. /O(n)/. 
    10021011mapEitherWithKey :: (Key -> a -> Either b c) -> IntMap a -> (IntMap b, IntMap c) 
    10031012mapEitherWithKey f (Bin p m l r) 
    10041013  = (bin p m l1 r1, bin p m l2 r2) 
     
    10101019  Right z -> (Nil, Tip k z) 
    10111020mapEitherWithKey f Nil = (Nil, Nil) 
    10121021 
    1013 -- | /O(log n)/. The expression (@'split' k map@) is a pair @(map1,map2)@ 
     1022-- | The expression (@'split' k map@) is a pair @(map1,map2)@ 
    10141023-- where all keys in @map1@ are lower than @k@ and all keys in 
    10151024-- @map2@ larger than @k@. Any key equal to @k@ is found in neither @map1@ nor @map2@. 
     1025-- /O(log n)/. 
    10161026split :: Key -> IntMap a -> (IntMap a,IntMap a) 
    10171027split k t 
    10181028  = case t of 
     
    10401050        | otherwise -> (Nil,Nil) 
    10411051      Nil -> (Nil,Nil) 
    10421052 
    1043 -- | /O(log n)/. Performs a 'split' but also returns whether the pivot 
    1044 -- key was found in the original map. 
     1053-- | Performs a 'split' but also returns whether the pivot 
     1054-- key was found in the original map. /O(log n)/. 
    10451055splitLookup :: Key -> IntMap a -> (IntMap a,Maybe a,IntMap a) 
    10461056splitLookup k t 
    10471057  = case t of 
     
    10721082{-------------------------------------------------------------------- 
    10731083  Fold 
    10741084--------------------------------------------------------------------} 
    1075 -- | /O(n)/. Fold the values in the map, such that 
     1085-- | Fold the values in the map, such that 
    10761086-- @'fold' f z == 'Prelude.foldr' f z . 'elems'@. 
    10771087-- For example, 
    10781088-- 
    10791089-- > elems map = fold (:) [] map 
    10801090-- 
     1091-- /O(n)/. 
    10811092fold :: (a -> b -> b) -> b -> IntMap a -> b 
    10821093fold f z t 
    10831094  = foldWithKey (\k x y -> f x y) z t 
    10841095 
    1085 -- | /O(n)/. Fold the keys and values in the map, such that 
     1096-- | Fold the keys and values in the map, such that 
    10861097-- @'foldWithKey' f z == 'Prelude.foldr' ('uncurry' f) z . 'toAscList'@. 
    10871098-- For example, 
    10881099-- 
    10891100-- > keys map = foldWithKey (\k x ks -> k:ks) [] map 
    10901101-- 
     1102-- /O(n)/. 
    10911103foldWithKey :: (Key -> a -> b -> b) -> b -> IntMap a -> b 
    10921104foldWithKey f z t 
    10931105  = foldr f z t 
     
    11121124{-------------------------------------------------------------------- 
    11131125  List variations  
    11141126--------------------------------------------------------------------} 
    1115 -- | /O(n)/. 
    1116 -- Return all elements of the map in the ascending order of their keys. 
     1127-- | Return all elements of the map in the ascending order of their keys. 
     1128-- /O(n)/. 
    11171129elems :: IntMap a -> [a] 
    11181130elems m 
    11191131  = foldWithKey (\k x xs -> x:xs) [] m   
    11201132 
    1121 -- | /O(n)/. Return all keys of the map in ascending order. 
     1133-- | Return all keys of the map in ascending order. /O(n)/. 
    11221134keys  :: IntMap a -> [Key] 
    11231135keys m 
    11241136  = foldWithKey (\k x ks -> k:ks) [] m 
    11251137 
    1126 -- | /O(n*min(n,W))/. The set of all keys of the map. 
     1138-- | The set of all keys of the map. /O(n*min(n,W))/. 
    11271139keysSet :: IntMap a -> IntSet.IntSet 
    11281140keysSet m = IntSet.fromDistinctAscList (keys m) 
    11291141 
    11301142 
    1131 -- | /O(n)/. Return all key\/value pairs in the map in ascending key order. 
     1143-- | Return all key\/value pairs in the map in ascending key order. /O(n)/. 
    11321144assocs :: IntMap a -> [(Key,a)] 
    11331145assocs m 
    11341146  = toList m 
     
    11371149{-------------------------------------------------------------------- 
    11381150  Lists  
    11391151--------------------------------------------------------------------} 
    1140 -- | /O(n)/. Convert the map to a list of key\/value pairs. 
     1152-- | Convert the map to a list of key\/value pairs. /O(n)/. 
    11411153toList :: IntMap a -> [(Key,a)] 
    11421154toList t 
    11431155  = foldWithKey (\k x xs -> (k,x):xs) [] t 
    11441156 
    1145 -- | /O(n)/. Convert the map to a list of key\/value pairs where the 
    1146 -- keys are in ascending order. 
     1157-- | Convert the map to a list of key\/value pairs where the 
     1158-- keys are in ascending order. /O(n)/. 
    11471159toAscList :: IntMap a -> [(Key,a)] 
    11481160toAscList t    
    11491161  = -- NOTE: the following algorithm only works for big-endian trees 
    11501162    let (pos,neg) = span (\(k,x) -> k >=0) (foldr (\k x xs -> (k,x):xs) [] t) in neg ++ pos 
    11511163 
    1152 -- | /O(n*min(n,W))/. Create a map from a list of key\/value pairs. 
     1164-- | Create a map from a list of key\/value pairs. /O(n*min(n,W))/. 
    11531165fromList :: [(Key,a)] -> IntMap a 
    11541166fromList xs 
    11551167  = foldlStrict ins empty xs 
    11561168  where 
    11571169    ins t (k,x)  = insert k x t 
    11581170 
    1159 -- | /O(n*min(n,W))/.  Create a map from a list of key\/value pairs with a combining function. See also 'fromAscListWith'. 
     1171-- | Create a map from a list of key\/value pairs with a combining function. See also 'fromAscListWith'. 
     1172-- /O(n*min(n,W))/. 
    11601173fromListWith :: (a -> a -> a) -> [(Key,a)] -> IntMap a  
    11611174fromListWith f xs 
    11621175  = fromListWithKey (\k x y -> f x y) xs 
    11631176 
    1164 -- | /O(n*min(n,W))/.  Build a map from a list of key\/value pairs with a combining function. See also fromAscListWithKey'. 
     1177-- | Build a map from a list of key\/value pairs with a combining function. See also fromAscListWithKey'. 
     1178-- /O(n*min(n,W))/. 
    11651179fromListWithKey :: (Key -> a -> a -> a) -> [(Key,a)] -> IntMap a  
    11661180fromListWithKey f xs  
    11671181  = foldlStrict ins empty xs 
    11681182  where 
    11691183    ins t (k,x) = insertWithKey f k x t 
    11701184 
    1171 -- | /O(n*min(n,W))/. Build a map from a list of key\/value pairs where 
    1172 -- the keys are in ascending order. 
     1185-- | Build a map from a list of key\/value pairs where 
     1186-- the keys are in ascending order. /O(n*min(n,W))/. 
    11731187fromAscList :: [(Key,a)] -> IntMap a 
    11741188fromAscList xs 
    11751189  = fromList xs 
    11761190 
    1177 -- | /O(n*min(n,W))/. Build a map from a list of key\/value pairs where 
     1191-- | Build a map from a list of key\/value pairs where 
    11781192-- the keys are in ascending order, with a combining function on equal keys. 
     1193-- /O(n*min(n,W))/. 
    11791194fromAscListWith :: (a -> a -> a) -> [(Key,a)] -> IntMap a 
    11801195fromAscListWith f xs 
    11811196  = fromListWith f xs 
    11821197 
    1183 -- | /O(n*min(n,W))/. Build a map from a list of key\/value pairs where 
     1198-- | Build a map from a list of key\/value pairs where 
    11841199-- the keys are in ascending order, with a combining function on equal keys. 
     1200-- /O(n*min(n,W))/. 
    11851201fromAscListWithKey :: (Key -> a -> a -> a) -> [(Key,a)] -> IntMap a 
    11861202fromAscListWithKey f xs 
    11871203  = fromListWithKey f xs 
    11881204 
    1189 -- | /O(n*min(n,W))/. Build a map from a list of key\/value pairs where 
    1190 -- the keys are in ascending order and all distinct. 
     1205-- | Build a map from a list of key\/value pairs where 
     1206-- the keys are in ascending order and all distinct. /O(n*min(n,W))/. 
    11911207fromDistinctAscList :: [(Key,a)] -> IntMap a 
    11921208fromDistinctAscList xs 
    11931209  = fromList xs 
     
    12771293{-------------------------------------------------------------------- 
    12781294  Debugging 
    12791295--------------------------------------------------------------------} 
    1280 -- | /O(n)/. Show the tree that implements the map. The tree is shown 
    1281 -- in a compressed, hanging format. 
     1296-- | Show the tree that implements the map. The tree is shown 
     1297-- in a compressed, hanging format. /O(n)/. 
    12821298showTree :: Show a => IntMap a -> String 
    12831299showTree s 
    12841300  = showTreeWith True False s 
    12851301 
    12861302 
    1287 {- | /O(n)/. The expression (@'showTreeWith' hang wide map@) shows 
     1303{- | The expression (@'showTreeWith' hang wide map@) shows 
    12881304 the tree that implements the map. If @hang@ is 
    12891305 'True', a /hanging/ tree is shown otherwise a rotated tree is shown. If 
    1290  @wide@ is 'True', an extra wide version is shown. 
     1306 @wide@ is 'True', an extra wide version is shown. /O(n)/. 
    12911307-} 
    12921308showTreeWith :: Show a => Bool -> Bool -> IntMap a -> String 
    12931309showTreeWith hang wide t 
  • Data/Map.hs

    diff -rN -u old-src/Data/Map.hs new-src/Data/Map.hs
    old new  
    1 {-# OPTIONS_GHC -fno-bang-patterns #-} 
     1{-TODO - enable # OPTIONS_GHC -fno-bang-patterns #-} 
    22 
    33----------------------------------------------------------------------------- 
    44-- | 
    55-- Module      :  Data.Map 
    66-- Copyright   :  (c) Daan Leijen 2002 
     7--                (c) Andriy Palamarchuk 2007 
    78-- License     :  BSD-style 
    89-- Maintainer  :  [email protected] 
    910-- Stability   :  provisional 
     
    3132-- Note that the implementation is /left-biased/ -- the elements of a 
    3233-- first argument are always preferred to the second, for example in 
    3334-- 'union' or 'insert'. 
     35-- 
     36-- Operation comments contain the operation time complexity in 
     37-- the Big-O notation <http://en.wikipedia.org/wiki/Big_O_notation>. 
    3438----------------------------------------------------------------------------- 
    3539 
    3640module Data.Map  (  
     
    194198--------------------------------------------------------------------} 
    195199infixl 9 !,\\ -- 
    196200 
    197 -- | /O(log n)/. Find the value at a key. 
    198 -- Calls 'error' when the element can not be found. 
     201-- | Find the value at a key. 
     202-- Calls 'error' when the element can not be found. /O(log n)/. 
     203-- 
     204-- > let m = fromList [(5,'a'), (3,'b'), (7,'c')] 
     205-- > m 
     206-- >   {3:='b',5:='a',7:='c'} 
     207-- > m!1 
     208-- >   Error: element not in the map 
     209-- > m!5 
     210-- >   'a' 
     211 
    199212(!) :: Ord k => Map k a -> k -> a 
    200213m ! k    = find k m 
    201214 
    202 -- | /O(n+m)/. See 'difference'. 
     215-- | Same as 'difference'. 
    203216(\\) :: Ord k => Map k a -> Map k b -> Map k a 
    204217m1 \\ m2 = difference m1 m2 
    205218 
     
    238251{-------------------------------------------------------------------- 
    239252  Query 
    240253--------------------------------------------------------------------} 
    241 -- | /O(1)/. Is the map empty? 
     254-- | Is the map empty? /O(1)/. 
     255-- 
     256-- > Data.Map.null (fromList([])) 
     257-- >   True 
     258-- > Data.Map.null (fromList([('a',1)])) 
     259-- >   False 
     260-- > Data.Map.null (empty) 
     261-- >   True 
     262-- > Data.Map.null (singleton 'a' 1) 
     263-- >   False 
     264 
    242265null :: Map k a -> Bool 
    243266null t 
    244267  = case t of 
    245268      Tip             -> True 
    246269      Bin sz k x l r  -> False 
    247270 
    248 -- | /O(1)/. The number of elements in the map. 
     271-- | The number of elements in the map. /O(1)/. 
     272-- 
     273-- > size empty 
     274-- >   0 
     275-- > size (singleton 'a' 1) 
     276-- >   1 
     277-- > size (fromList([('a',1), ('c', 2), ('b', 3)])) 
     278-- >   3 
     279 
    249280size :: Map k a -> Int 
    250281size t 
    251282  = case t of 
     
    253284      Bin sz k x l r  -> sz 
    254285 
    255286 
    256 -- | /O(log n)/. Lookup the value at a key in the map.  
     287-- | Lookup the value at a key in the map. 
    257288-- 
    258289-- The function will  
    259290-- @return@ the result in the monad or @fail@ in it the key isn't in the  
    260291-- map. Often, the monad to use is 'Maybe', so you get either  
    261 -- @('Just' result)@ or @'Nothing'@. 
     292-- @('Just' result)@ or @'Nothing'@. /O(log n)/. 
     293-- 
     294-- > let m = fromList [(5,'a'), (3,'b'), (7,'c')] 
     295-- > m 
     296-- >   {3:='b',5:='a',7:='c'} 
     297-- > value1 <- Data.Map.lookup 5 m 
     298-- > value1 
     299-- >   'a' 
     300-- > value2 <- Data.Map.lookup 1 m 
     301-- >   Error: Key not found 
     302-- 
     303-- An example of using @lookup@ with @Maybe@ monad: 
     304-- 
     305-- > import Prelude hiding (lookup) 
     306-- > import Data.Map 
     307-- > 
     308-- > employeeDept = fromList([("John","Sales"), ("Bob","IT")]) 
     309-- > deptCountry = fromList([("IT","USA"), ("Sales","France")]) 
     310-- > countryCurrency = fromList([("USA", "Dollar"), ("France", "Euro")]) 
     311-- > 
     312-- > employeeCurrency :: String -> Maybe String 
     313-- > employeeCurrency name = do 
     314-- >     dept <- lookup name employeeDept 
     315-- >     country <- lookup dept deptCountry 
     316-- >     lookup country countryCurrency 
     317-- > 
     318-- > main = do 
     319-- >     putStrLn $ "John's currency: " ++ (show (employeeCurrency "John")) 
     320-- >     putStrLn $ "Pete's currency: " ++ (show (employeeCurrency "Pete")) 
     321-- 
     322-- The output of this program: 
     323-- 
     324-- >   John's currency: Just "Euro" 
     325-- >   Pete's currency: Nothing 
     326 
    262327lookup :: (Monad m,Ord k) => k -> Map k a -> m a 
    263328lookup k t = case lookup' k t of 
    264329    Just x -> return x 
     
    283348               GT -> lookupAssoc k r 
    284349               EQ -> Just (kx,x) 
    285350 
    286 -- | /O(log n)/. Is the key a member of the map? 
     351-- | Is the key a member of the map? See also 'notMember'. /O(log n)/. 
     352-- 
     353-- > let m = fromList [(5,'a'), (3,'b'), (7,'c')] 
     354-- > m 
     355-- >   {3:='b',5:='a',7:='c'} 
     356-- > member 5 m 
     357-- >   True 
     358-- > member 1 m 
     359-- >   False 
     360 
    287361member :: Ord k => k -> Map k a -> Bool 
    288362member k m 
    289363  = case lookup k m of 
    290364      Nothing -> False 
    291365      Just x  -> True 
    292366 
    293 -- | /O(log n)/. Is the key not a member of the map? 
     367-- | Is the key not a member of the map? See also 'member'. /O(log n)/. 
     368-- 
     369-- > let m = fromList [(5,'a'), (3,'b'), (7,'c')] 
     370-- > m 
     371-- >   {3:='b',5:='a',7:='c'} 
     372-- > notMember 5 m 
     373-- >   False 
     374-- > notMember 1 m 
     375-- >   True 
     376 
    294377notMember :: Ord k => k -> Map k a -> Bool 
    295378notMember k m = not $ member k m 
    296379 
    297 -- | /O(log n)/. Find the value at a key. 
     380-- | Find the value at a key. /O(log n)/. 
    298381-- Calls 'error' when the element can not be found. 
    299382find :: Ord k => k -> Map k a -> a 
    300383find k m 
     
    302385      Nothing -> error "Map.find: element not in the map" 
    303386      Just x  -> x 
    304387 
    305 -- | /O(log n)/. The expression @('findWithDefault' def k map)@ returns 
    306 -- the value at key @k@ or returns @def@ when the key is not in the map. 
     388-- | The expression @('findWithDefault' def k map)@ returns 
     389-- the value at key @k@ or returns default value @def@ 
     390-- when the key is not in the map. 
     391-- /O(log n)/. 
     392-- 
     393-- > let m = fromList [(5,'a'), (3,'b'), (7,'c')] 
     394-- > m 
     395-- >   {3:='b',5:='a',7:='c'} 
     396-- > findWithDefault '?' 1 m 
     397-- >   '?' 
     398-- > findWithDefault '?' 5 m 
     399-- >   'a' 
     400 
    307401findWithDefault :: Ord k => a -> k -> Map k a -> a 
    308402findWithDefault def k m 
    309403  = case lookup k m of 
     
    315409{-------------------------------------------------------------------- 
    316410  Construction 
    317411--------------------------------------------------------------------} 
    318 -- | /O(1)/. The empty map. 
     412-- | The empty map. /O(1)/. 
     413-- 
     414-- > empty 
     415-- >   {} 
     416-- > size empty 
     417-- >   0 
     418 
    319419empty :: Map k a 
    320420empty  
    321421  = Tip 
    322422 
    323 -- | /O(1)/. A map with a single element. 
     423-- | A map with a single element. /O(1)/. 
     424-- 
     425-- > singleton 1 'a' 
     426-- >   {1:='a'} 
     427-- > size (singleton 1 'a') 
     428-- >   1 
     429 
    324430singleton :: k -> a -> Map k a 
    325431singleton k x   
    326432  = Bin 1 k x Tip Tip 
     
    328434{-------------------------------------------------------------------- 
    329435  Insertion 
    330436--------------------------------------------------------------------} 
    331 -- | /O(log n)/. Insert a new key and value in the map. 
     437-- | Insert a new key and value in the map. 
    332438-- If the key is already present in the map, the associated value is 
    333 -- replaced with the supplied value, i.e. 'insert' is equivalent to 
    334 -- @'insertWith' 'const'@. 
     439-- replaced with the supplied value. 'insert' is equivalent to 
     440-- @'insertWith' 'const'@. /O(log n)/. 
     441-- 
     442-- > let m = fromList [(5,'a'), (3,'b')] 
     443-- > m 
     444-- >   {3:='b',5:='a'} 
     445-- > insert 5 'x' m 
     446-- >   {3:='b',5:='x'} 
     447-- > insert 10 'x' m 
     448-- >   {3:='b',5:='a',10:='x'} 
     449-- > insert 5 'x' empty 
     450-- >   {5:='x'} 
     451 
    335452insert :: Ord k => k -> a -> Map k a -> Map k a 
    336453insert kx x t 
    337454  = case t of 
     
    342459               GT -> balance ky y l (insert kx x r) 
    343460               EQ -> Bin sz kx x l r 
    344461 
    345 -- | /O(log n)/. Insert with a combining function. 
     462-- | Insert with a function, combining new value and old value. 
    346463-- @'insertWith' f key value mp@  
    347464-- will insert the pair (key, value) into @mp@ if key does 
    348465-- not exist in the map. If the key does exist, the function will 
    349 -- insert the pair @(key, f new_value old_value)@. 
     466-- insert the pair @(key, f new_value old_value)@. /O(log n)/. 
     467-- 
     468-- > let m = fromList [(5,"a"), (3,"b")] 
     469-- > m 
     470-- >   {3:="b",5:="a"} 
     471-- > insertWith (++) 5 "xxx" m 
     472-- >   {3:="b",5:="xxxa"} 
     473-- > insertWith (++) 10 "xxx" m 
     474-- >   {3:="b",5:="a",10:="xxx"} 
     475-- > insertWith (++) 5 "xxx" empty 
     476-- >   {5:="xxx"} 
     477 
    350478insertWith :: Ord k => (a -> a -> a) -> k -> a -> Map k a -> Map k a 
    351479insertWith f k x m           
    352480  = insertWithKey (\k x y -> f x y) k x m 
     
    357485  = insertWithKey' (\k x y -> f x y) k x m 
    358486 
    359487 
    360 -- | /O(log n)/. Insert with a combining function. 
     488-- | Insert with a function, combining key, new value and old value. 
    361489-- @'insertWithKey' f key value mp@  
    362490-- will insert the pair (key, value) into @mp@ if key does 
    363491-- not exist in the map. If the key does exist, the function will 
    364492-- insert the pair @(key,f key new_value old_value)@. 
    365493-- Note that the key passed to f is the same key passed to 'insertWithKey'. 
     494-- /O(log n)/. 
     495-- 
     496-- > let m = fromList [(5,"a"), (3,"b")] 
     497-- > m 
     498-- >   {3:="b",5:="a"} 
     499-- > let f key new_value old_value = (show key) ++ ":" ++ new_value ++ "|" ++ old_value 
     500-- > insertWithKey f 5 "xxx" m 
     501-- >   {3:="b",5:="5:xxx|a"} 
     502-- > insertWithKey f 10 "xxx" m 
     503-- >   {3:="b",5:="a",10:="xxx"} 
     504-- > insertWithKey f 5 "xxx" empty 
     505-- >   {5:="xxx"} 
     506 
    366507insertWithKey :: Ord k => (k -> a -> a -> a) -> k -> a -> Map k a -> Map k a 
    367508insertWithKey f kx x t 
    368509  = case t of 
     
    385526               EQ -> let x' = f kx x y in seq x' (Bin sy kx x' l r) 
    386527 
    387528 
    388 -- | /O(log n)/. The expression (@'insertLookupWithKey' f k x map@) 
     529-- | Combines insert operation with old value retrieval. 
     530-- The expression (@'insertLookupWithKey' f k x map@) 
    389531-- is a pair where the first element is equal to (@'lookup' k map@) 
    390 -- and the second element equal to (@'insertWithKey' f k x map@). 
     532-- and the second element equal to (@'insertWithKey' f k x map@). /O(log n)/. 
     533-- 
     534-- > let m = fromList [(5,"a"), (3,"b")] 
     535-- > m 
     536-- >   {3:="b",5:="a"} 
     537-- > let f key new_value old_value = (show key) ++ ":" ++ new_value ++ "|" ++ old_value 
     538-- > insertLookupWithKey f 5 "xxx" m 
     539-- >   (Just "a",{3:="b",5:="5:xxx|a"}) 
     540-- > insertLookupWithKey f 10 "xxx" m 
     541-- >   (Nothing,{3:="b",5:="a",10:="xxx"}) 
     542-- > insertLookupWithKey f 5 "xxx" empty 
     543-- >   (Nothing,{5:="xxx"}) 
     544-- 
     545-- This is how to define @insertLookup@ using @insertLookupWithKey@: 
     546-- 
     547-- > let m = fromList [(5,"a"), (3,"b")] 
     548-- > m 
     549-- >   {3:="b",5:="a"} 
     550-- > let insertLookup kx x t = insertLookupWithKey (\_ a _ -> a) kx x t 
     551-- > insertLookup 5 "x" m 
     552-- >   (Just "a",{3:="b",5:="x"}) 
     553-- > insertLookup 10 "x" m 
     554-- >   (Nothing,{3:="b",5:="a",10:="x"}) 
     555 
    391556insertLookupWithKey :: Ord k => (k -> a -> a -> a) -> k -> a -> Map k a -> (Maybe a,Map k a) 
    392557insertLookupWithKey f kx x t 
    393558  = case t of 
     
    402567  Deletion 
    403568  [delete] is the inlined version of [deleteWith (\k x -> Nothing)] 
    404569--------------------------------------------------------------------} 
    405 -- | /O(log n)/. Delete a key and its value from the map. When the key is not 
    406 -- a member of the map, the original map is returned. 
     570-- | Delete a key and its value from the map. When the key is not 
     571-- a member of the map, the original map is returned. /O(log n)/. 
     572-- 
     573-- > let m = fromList [(5,"a"), (3,"b")] 
     574-- > m 
     575-- >   {3:="b",5:="a"} 
     576-- > delete 5 m 
     577-- >   {3:="b"} 
     578-- > delete 10 m 
     579-- >   {3:="b",5:="a"} 
     580-- > delete 5 empty 
     581-- >   {} 
     582 
    407583delete :: Ord k => k -> Map k a -> Map k a 
    408584delete k t 
    409585  = case t of 
     
    414590               GT -> balance kx x l (delete k r) 
    415591               EQ -> glue l r 
    416592 
    417 -- | /O(log n)/. Adjust a value at a specific key. When the key is not 
    418 -- a member of the map, the original map is returned. 
     593-- | Update a value at a specific key with the result of the provided function. 
     594-- When the key is not 
     595-- a member of the map, the original map is returned. /O(log n)/. 
     596-- 
     597-- > let m = fromList [(5,"a"), (3,"b")] 
     598-- > m 
     599-- >   {3:="b",5:="a"} 
     600-- > adjust ("new " ++) 5 m 
     601-- >   {3:="b",5:="new a"} 
     602-- > adjust ("new " ++) 10 m 
     603-- >   {3:="b",5:="a"} 
     604-- > adjust ("new " ++) 10 empty 
     605-- >   {} 
     606 
    419607adjust :: Ord k => (a -> a) -> k -> Map k a -> Map k a 
    420608adjust f k m 
    421609  = adjustWithKey (\k x -> f x) k m 
    422610 
    423 -- | /O(log n)/. Adjust a value at a specific key. When the key is not 
    424 -- a member of the map, the original map is returned. 
     611-- | Adjust a value at a specific key. When the key is not 
     612-- a member of the map, the original map is returned. /O(log n)/. 
     613-- 
     614-- > let m = fromList [(5,"a"), (3,"b")] 
     615-- > m 
     616-- >   {3:="b",5:="a"} 
     617-- > let f key x = (show key) ++ ":new " ++ x 
     618-- > adjustWithKey f 5 m 
     619-- >   {3:="b",5:="5:new a"} 
     620-- > adjustWithKey f 10 m 
     621-- >   {3:="b",5:="a"} 
     622-- > adjustWithKey f 10 empty 
     623-- >   {} 
     624 
    425625adjustWithKey :: Ord k => (k -> a -> a) -> k -> Map k a -> Map k a 
    426626adjustWithKey f k m 
    427627  = updateWithKey (\k x -> Just (f k x)) k m 
    428628 
    429 -- | /O(log n)/. The expression (@'update' f k map@) updates the value @x@ 
     629-- | The expression (@'update' f k map@) updates the value @x@ 
    430630-- at @k@ (if it is in the map). If (@f x@) is 'Nothing', the element is 
    431631-- deleted. If it is (@'Just' y@), the key @k@ is bound to the new value @y@. 
     632-- /O(log n)/. 
     633-- 
     634-- > let m = fromList [(5,"a"), (3,"b")] 
     635-- > m 
     636-- >   {3:="b",5:="a"} 
     637-- > let f x = if x == "a" then Just "new a" else Nothing 
     638-- > 
     639-- > -- f "a" returns Just "new a" 
     640-- > update f 5 m 
     641-- >   {3:="b",5:="new a"} 
     642-- > 
     643-- > -- key does not exist 
     644-- > update f 10 m 
     645-- >   {3:="b",5:="a"} 
     646-- > 
     647-- > -- f "b" returns Nothing 
     648-- > update f 3 m 
     649-- >   {5:="a"} 
     650 
    432651update :: Ord k => (a -> Maybe a) -> k -> Map k a -> Map k a 
    433652update f k m 
    434653  = updateWithKey (\k x -> f x) k m 
    435654 
    436 -- | /O(log n)/. The expression (@'updateWithKey' f k map@) updates the 
     655-- | The expression (@'updateWithKey' f k map@) updates the 
    437656-- value @x@ at @k@ (if it is in the map). If (@f k x@) is 'Nothing', 
    438657-- the element is deleted. If it is (@'Just' y@), the key @k@ is bound 
    439 -- to the new value @y@. 
     658-- to the new value @y@. /O(log n)/. 
     659-- 
     660-- > let m = fromList [(5,"a"), (3,"b")] 
     661-- > m 
     662-- >   {3:="b",5:="a"} 
     663-- > let f k x = if x == "a" then Just ((show k) ++ ":new a") else Nothing 
     664-- > 
     665-- > -- f 5 "a" returns Just "5:new a" 
     666-- > updateWithKey f 5 m 
     667-- >   {3:="b",5:="5:new a"} 
     668-- > 
     669-- > -- key does not exist 
     670-- > updateWithKey f 10 m 
     671-- >   {3:="b",5:="a"} 
     672-- > 
     673-- > -- f 3 "b" returns Nothing 
     674-- > updateWithKey f 3 m 
     675-- >   {5:="a"} 
     676 
    440677updateWithKey :: Ord k => (k -> a -> Maybe a) -> k -> Map k a -> Map k a 
    441678updateWithKey f k t 
    442679  = case t of 
     
    449686                       Just x' -> Bin sx kx x' l r 
    450687                       Nothing -> glue l r 
    451688 
    452 -- | /O(log n)/. Lookup and update. 
     689-- | Lookup and update. See also 'updateWithKey'. /O(log n)/. 
     690-- 
     691-- > let m = fromList [(5,"a"), (3,"b")] 
     692-- > m 
     693-- >   {3:="b",5:="a"} 
     694-- > let f k x = if x == "a" then Just ((show k) ++ ":new a") else Nothing 
     695-- > 
     696-- > -- f 5 "a" returns Just "5:new a" 
     697-- > updateLookupWithKey f 5 m 
     698-- >   (Just "5:new a",{3:="b",5:="5:new a"}) 
     699-- > 
     700-- > -- key does not exist 
     701-- > updateLookupWithKey f 10 m 
     702-- >   (Nothing,{3:="b",5:="a"}) 
     703-- > 
     704-- > -- f 3 "b" returns Nothing 
     705-- > updateLookupWithKey f 3 m 
     706-- >   (Just "b",{5:="a"}) 
     707 
    453708updateLookupWithKey :: Ord k => (k -> a -> Maybe a) -> k -> Map k a -> (Maybe a,Map k a) 
    454709updateLookupWithKey f k t 
    455710  = case t of 
     
    462717                       Just x' -> (Just x',Bin sx kx x' l r) 
    463718                       Nothing -> (Just x,glue l r) 
    464719 
    465 -- | /O(log n)/. The expression (@'alter' f k map@) alters the value @x@ at @k@, or absence thereof. 
     720-- | The expression (@'alter' f k map@) alters the value @x@ at @k@, or absence thereof. 
    466721-- 'alter' can be used to insert, delete, or update a value in a 'Map'. 
    467 -- In short : @'lookup' k ('alter' f k m) = f ('lookup' k m)@ 
     722-- In short : @'lookup' k ('alter' f k m) = f ('lookup' k m)@. /O(log n)/. 
     723-- 
     724-- > let m = fromList [(5,"a"), (3,"b")] 
     725-- > m 
     726-- >   {3:="b",5:="a"} 
     727-- > 
     728-- > -- always returns Nothing 
     729-- > let f _ = Nothing 
     730-- > alter f 10 m 
     731-- >   {3:="b",5:="a"} 
     732-- > alter f 5 m 
     733-- >   {3:="b"} 
     734-- > 
     735-- > -- always returns Just "c" 
     736-- > let f _ = Just "c" 
     737-- > alter f 10 m 
     738-- >   {3:="b",5:="a",10:="c")} 
     739-- > alter f 5 m 
     740-- >   {3:="b",5:="c")} 
     741 
    468742alter :: Ord k => (Maybe a -> Maybe a) -> k -> Map k a -> Map k a 
    469743alter f k t 
    470744  = case t of 
     
    482756{-------------------------------------------------------------------- 
    483757  Indexing 
    484758--------------------------------------------------------------------} 
    485 -- | /O(log n)/. Return the /index/ of a key. The index is a number from 
     759-- | Return the /index/ of a key. The index is a number from 
    486760-- /0/ up to, but not including, the 'size' of the map. Calls 'error' when 
    487 -- the key is not a 'member' of the map. 
     761-- the key is not a 'member' of the map. /O(log n)/. 
     762-- 
     763-- > let m = fromList [(5,"a"), (3,"b")] 
     764-- > m 
     765-- >   {3:="b",5:="a"} 
     766-- > findIndex 2 m 
     767-- >   Exception: Key not found. 
     768-- > findIndex 3 m 
     769-- >   0 
     770-- > findIndex 4 m 
     771-- >   Exception: Key not found. 
     772-- > findIndex 5 m 
     773-- >   1 
     774-- > findIndex 6 m 
     775-- >   Exception: Key not found. 
     776 
    488777findIndex :: Ord k => k -> Map k a -> Int 
    489778findIndex k t 
    490779  = case lookupIndex k t of 
    491780      Nothing  -> error "Map.findIndex: element is not in the map" 
    492781      Just idx -> idx 
    493782 
    494 -- | /O(log n)/. Lookup the /index/ of a key. The index is a number from 
    495 -- /0/ up to, but not including, the 'size' of the map.  
     783-- | Lookup the /index/ of a key. The index is a number from 
     784-- /0/ up to, but not including, the 'size' of the map. /O(log n)/. 
     785-- 
     786-- > let m = fromList [(5,"a"), (3,"b")] 
     787-- > m 
     788-- >   {3:="b",5:="a"} 
     789-- > isJust (lookupIndex 2 m) 
     790-- >   False 
     791-- > isJust (lookupIndex 3 m) 
     792-- >   True 
     793-- > fromJust (lookupIndex 3 m) 
     794-- >   0 
     795-- > isJust (lookupIndex 4 m) 
     796-- >   False 
     797-- > isJust (lookupIndex 5 m) 
     798-- >   True 
     799-- > fromJust (lookupIndex 5 m) 
     800-- >   1 
     801-- > isJust (lookupIndex 6 m) 
     802-- >   False 
     803 
    496804lookupIndex :: (Monad m,Ord k) => k -> Map k a -> m Int 
    497805lookupIndex k t = case lookup 0 t of 
    498806    Nothing -> fail "Data.Map.lookupIndex: Key not found." 
     
    505813          GT -> lookup (idx + size l + 1) r  
    506814          EQ -> Just (idx + size l) 
    507815 
    508 -- | /O(log n)/. Retrieve an element by /index/. Calls 'error' when an 
    509 -- invalid index is used. 
     816-- | Retrieve an element by /index/. Calls 'error' when an 
     817-- invalid index is used. /O(log n)/. 
     818-- 
     819-- > let m = fromList [(5,"a"), (3,"b")] 
     820-- > m 
     821-- >   {3:="b",5:="a"} 
     822-- > elemAt 0 m 
     823-- >   (3,"b") 
     824-- > elemAt 1 m 
     825-- >   (5,"a") 
     826-- > elemAt 2 m 
     827-- >   Exception: Map.elemAt: index out of range 
     828 
    510829elemAt :: Int -> Map k a -> (k,a) 
    511830elemAt i Tip = error "Map.elemAt: index out of range" 
    512831elemAt i (Bin _ kx x l r) 
     
    517836  where 
    518837    sizeL = size l 
    519838 
    520 -- | /O(log n)/. Update the element at /index/. Calls 'error' when an 
    521 -- invalid index is used. 
     839-- | Update the element at /index/. Calls 'error' when an 
     840-- invalid index is used. /O(log n)/. 
     841-- 
     842-- > let m = fromList [(5,"a"), (3,"b")] 
     843-- > m 
     844-- >   {3:="b",5:="a"} 
     845-- > 
     846-- > -- always returns Just "x" 
     847-- > let f _ _ = Just "x" 
     848-- > updateAt f 0 m 
     849-- >   {3:="x",5:="a"} 
     850-- > updateAt f 1 m 
     851-- >   {3:="b",5:="x"} 
     852-- > updateAt f 2 m 
     853-- >   Exception: Map.updateAt: index out of range 
     854-- > updateAt f (-1) m 
     855-- >   Exception: Map.updateAt: index out of range 
     856-- > 
     857-- > -- always returns Nothing 
     858-- > let f _ _ = Nothing 
     859-- > updateAt f 0 m 
     860-- >   {5:="a"} 
     861-- > updateAt f 1 m 
     862-- >   {3:="b"} 
     863-- > updateAt f 2 m 
     864-- >   Exception: Map.updateAt: index out of range 
     865-- > updateAt f (-1) m 
     866-- >   Exception: Map.updateAt: index out of range 
     867 
    522868updateAt :: (k -> a -> Maybe a) -> Int -> Map k a -> Map k a 
    523869updateAt f i Tip  = error "Map.updateAt: index out of range" 
    524870updateAt f i (Bin sx kx x l r) 
     
    531877  where 
    532878    sizeL = size l 
    533879 
    534 -- | /O(log n)/. Delete the element at /index/. 
     880-- | Delete the element at /index/. 
    535881-- Defined as (@'deleteAt' i map = 'updateAt' (\k x -> 'Nothing') i map@). 
     882-- /O(log n)/. 
     883-- 
     884-- > let m = fromList [(5,"a"), (3,"b")] 
     885-- > m 
     886-- >   {3:="b",5:="a"} 
     887-- > deleteAt 0 m 
     888-- >   {5:="a"} 
     889-- > deleteAt 1 m 
     890-- >   {3:="b"} 
     891-- > deleteAt 2 m 
     892-- >   Exception: Map.updateAt: index out of range 
     893-- > deleteAt (-1) m 
     894-- >   Exception: Map.updateAt: index out of range 
     895 
    536896deleteAt :: Int -> Map k a -> Map k a 
    537897deleteAt i map 
    538898  = updateAt (\k x -> Nothing) i map 
     
    541901{-------------------------------------------------------------------- 
    542902  Minimal, Maximal 
    543903--------------------------------------------------------------------} 
    544 -- | /O(log n)/. The minimal key of the map. 
     904-- | The minimal key of the map. /O(log n)/. 
     905-- 
     906-- > let m = fromList [(5,"a"), (3,"b")] 
     907-- > m 
     908-- >   {3:="b",5:="a"} 
     909-- > findMin m 
     910-- >   (3,"b") 
     911-- > findMin empty 
     912-- >   Exception: Map.findMin: empty map has no minimal element 
     913 
    545914findMin :: Map k a -> (k,a) 
    546915findMin (Bin _ kx x Tip r)  = (kx,x) 
    547916findMin (Bin _ kx x l r)    = findMin l 
    548917findMin Tip                 = error "Map.findMin: empty map has no minimal element" 
    549918 
    550 -- | /O(log n)/. The maximal key of the map. 
     919-- | The maximal key of the map. /O(log n)/. 
     920-- 
     921-- > let m = fromList [(5,"a"), (3,"b")] 
     922-- > m 
     923-- >   {3:="b",5:="a"} 
     924-- > findMax m 
     925-- >   (5,"a") 
     926-- > findMax empty 
     927-- >   Exception: Map.findMax: empty map has no maximal element 
     928 
    551929findMax :: Map k a -> (k,a) 
    552930findMax (Bin _ kx x l Tip)  = (kx,x) 
    553931findMax (Bin _ kx x l r)    = findMax r 
    554932findMax Tip                 = error "Map.findMax: empty map has no maximal element" 
    555933 
    556 -- | /O(log n)/. Delete the minimal key. 
     934-- | Delete the minimal key. /O(log n)/. 
     935-- 
     936-- > let m = fromList [(5,"a"), (3,"b"), (10,"c")] 
     937-- > m 
     938-- >   {3:="b",5:="a",10:="c"} 
     939-- > deleteMin m 
     940-- >   {5:="a",10:="c"} 
     941-- > deleteMin empty 
     942-- >   {} 
     943 
    557944deleteMin :: Map k a -> Map k a 
    558945deleteMin (Bin _ kx x Tip r)  = r 
    559946deleteMin (Bin _ kx x l r)    = balance kx x (deleteMin l) r 
    560947deleteMin Tip                 = Tip 
    561948 
    562 -- | /O(log n)/. Delete the maximal key. 
     949-- | Delete the maximal key. /O(log n)/. 
     950-- 
     951-- > let m = fromList [(5,"a"), (3,"b"), (10,"c")] 
     952-- > m 
     953-- >   {3:="b",5:="a",10:="c"} 
     954-- > deleteMax m 
     955-- >   {3:="b",5:="a"} 
     956-- > deleteMax empty 
     957-- >   {} 
     958 
    563959deleteMax :: Map k a -> Map k a 
    564960deleteMax (Bin _ kx x l Tip)  = l 
    565961deleteMax (Bin _ kx x l r)    = balance kx x l (deleteMax r) 
    566962deleteMax Tip                 = Tip 
    567963 
    568 -- | /O(log n)/. Update the value at the minimal key. 
     964-- | Update the value at the minimal key. /O(log n)/. 
     965-- 
     966-- > let m = fromList [(5,"a"), (3,"b"), (10,"c")] 
     967-- > m 
     968-- >   {3:="b",5:="a",10:="c"} 
     969-- > updateMin (\ a -> Just ("X" ++ a)) m 
     970-- >   {3:="Xb",5:="a",10:="c"} 
     971-- > updateMin (\ _ -> Nothing) m 
     972-- >   {5:="a",10:="c"} 
     973 
    569974updateMin :: (a -> Maybe a) -> Map k a -> Map k a 
    570975updateMin f m 
    571976  = updateMinWithKey (\k x -> f x) m 
    572977 
    573 -- | /O(log n)/. Update the value at the maximal key. 
     978-- | Update the value at the maximal key. /O(log n)/. 
     979-- 
     980-- > let m = fromList [(5,"a"), (3,"b"), (10,"c")] 
     981-- > m 
     982-- >   {3:="b",5:="a",10:="c"} 
     983-- > updateMax (\ a -> Just ("X" ++ a)) m 
     984-- >   {3:="b",5:="a",10:="Xc"} 
     985-- > updateMax (\ _ -> Nothing) m 
     986-- >   {3:="b",5,"a"} 
     987 
    574988updateMax :: (a -> Maybe a) -> Map k a -> Map k a 
    575989updateMax f m 
    576990  = updateMaxWithKey (\k x -> f x) m 
    577991 
    578992 
    579 -- | /O(log n)/. Update the value at the minimal key. 
     993-- | Update the value at the minimal key. /O(log n)/. 
     994-- 
     995-- > let m = fromList [(5,"a"), (3,"b"), (10,"c")] 
     996-- > m 
     997-- >   {3:="b",5:="a",10:="c"} 
     998-- > updateMinWithKey (\ k a -> Just ((show k) ++ ":" ++ a)) m 
     999-- >   {3:="3:b",5:="a",10:="c"} 
     1000-- > updateMinWithKey (\ _ _ -> Nothing) m 
     1001-- >   {5:="a",10:="c"} 
     1002 
    5801003updateMinWithKey :: (k -> a -> Maybe a) -> Map k a -> Map k a 
    5811004updateMinWithKey f t 
    5821005  = case t of 
     
    5861009      Bin sx kx x l r    -> balance kx x (updateMinWithKey f l) r 
    5871010      Tip                -> Tip 
    5881011 
    589 -- | /O(log n)/. Update the value at the maximal key. 
     1012-- | Update the value at the maximal key. /O(log n)/. 
     1013-- 
     1014-- > let m = fromList [(5,"a"), (3,"b"), (10,"c")] 
     1015-- > m 
     1016-- >   {3:="b",5:="a",10:="c"} 
     1017-- > updateMaxWithKey (\ k a -> Just ((show k) ++ ":" ++ a)) m 
     1018-- >   {3:="b",5:="a",10:="10:c"} 
     1019-- > updateMaxWithKey (\ _ _ -> Nothing) m 
     1020-- >   {3:="b",5:="a"} 
     1021 
    5901022updateMaxWithKey :: (k -> a -> Maybe a) -> Map k a -> Map k a 
    5911023updateMaxWithKey f t 
    5921024  = case t of 
     
    5961028      Bin sx kx x l r    -> balance kx x l (updateMaxWithKey f r) 
    5971029      Tip                -> Tip 
    5981030 
    599 -- | /O(log n)/. Retrieves the minimal (key,value) pair of the map, and the map stripped from that element 
     1031-- | Retrieves the minimal (key,value) pair of the map, and the map stripped from that element 
    6001032-- @fail@s (in the monad) when passed an empty map. 
     1033-- /O(log n)/. 
     1034-- 
     1035-- > let m = fromList [(5,"a"), (3,"b")] 
     1036-- > m 
     1037-- >   {3:="b",5:="a"} 
     1038-- > minViewWithKey m 
     1039-- >   ((3,"b"), {5:="a"}) 
     1040-- > minViewWithKey empty 
     1041-- >   Exception: user error (Map.minViewWithKey: empty map) 
     1042 
    6011043minViewWithKey :: Monad m => Map k a -> m ((k,a), Map k a) 
    602 minViewWithKey Tip = fail "Map.minView: empty map" 
     1044minViewWithKey Tip = fail "Map.minViewWithKey: empty map" 
    6031045minViewWithKey x = return (deleteFindMin x) 
    6041046 
    605 -- | /O(log n)/. Retrieves the maximal (key,value) pair of the map, and the map stripped from that element 
    606 -- @fail@s (in the monad) when passed an empty map. 
     1047-- | Retrieves the maximal (key,value) pair of the map, and the map stripped from that element 
     1048-- @fail@s (in the monad) when passed an empty map. /O(log n)/. 
     1049-- 
     1050-- > let m = fromList [(5,"a"), (3,"b")] 
     1051-- > m 
     1052-- >   {3:="b",5:="a"} 
     1053-- > maxViewWithKey m 
     1054-- >   ((5,"a"), {3:="b"}) 
     1055-- > maxViewWithKey empty 
     1056-- >   Exception: user error (Map.maxViewWithKey: empty map) 
     1057 
    6071058maxViewWithKey :: Monad m => Map k a -> m ((k,a), Map k a) 
    608 maxViewWithKey Tip = fail "Map.maxView: empty map" 
     1059maxViewWithKey Tip = fail "Map.maxViewWithKey: empty map" 
    6091060maxViewWithKey x = return (deleteFindMax x) 
    6101061 
    611 -- | /O(log n)/. Retrieves the minimal key\'s value of the map, and the map stripped from that element 
    612 -- @fail@s (in the monad) when passed an empty map. 
     1062-- | Retrieves the minimal key\'s value of the map, and the map stripped from that element 
     1063-- @fail@s (in the monad) when passed an empty map. /O(log n)/. 
     1064-- 
     1065-- > let m = fromList [(5,"a"), (3,"b")] 
     1066-- > m 
     1067-- >   {3:="b",5:="a"} 
     1068-- > minView m 
     1069-- >   ("b", {5:="a"}) 
     1070-- > minView empty 
     1071-- >   Exception: user error (Map.minView: empty map) 
     1072 
    6131073minView :: Monad m => Map k a -> m (a, Map k a) 
    6141074minView Tip = fail "Map.minView: empty map" 
    6151075minView x = return (first snd $ deleteFindMin x) 
    6161076 
    617 -- | /O(log n)/. Retrieves the maximal key\'s value of the map, and the map stripped from that element 
    618 -- @fail@s (in the monad) when passed an empty map. 
     1077-- | Retrieves the maximal key\'s value of the map, and the map stripped from that element 
     1078-- @fail@s (in the monad) when passed an empty map. /O(log n)/. 
     1079-- 
     1080-- > let m = fromList [(5,"a"), (3,"b")] 
     1081-- > m 
     1082-- >   {3:="b",5:="a"} 
     1083-- > maxView m 
     1084-- >   ("a", {3:="b"}) 
     1085-- > maxView empty 
     1086-- >   Exception: user error (Map.maxView: empty map) 
     1087 
    6191088maxView :: Monad m => Map k a -> m (a, Map k a) 
    6201089maxView Tip = fail "Map.maxView: empty map" 
    6211090maxView x = return (first snd $ deleteFindMax x) 
     
    6291098--------------------------------------------------------------------} 
    6301099-- | The union of a list of maps: 
    6311100--   (@'unions' == 'Prelude.foldl' 'union' 'empty'@). 
     1101-- 
     1102-- > let map1 = fromList [(5, "a"), (3, "b")] 
     1103-- > let map2 = fromList [(5, "A"), (10, "C")] 
     1104-- > let map3 = fromList [(5, "A3"), (3, "B3")] 
     1105-- > unions [map1, map2, map3] 
     1106-- >   {3:="b",5:="a",10:="C"} 
     1107-- > unions [map3, map2, map1] 
     1108-- >   {3:="B3",5:="A3",10:="C"} 
     1109 
    6321110unions :: Ord k => [Map k a] -> Map k a 
    6331111unions ts 
    6341112  = foldlStrict union empty ts 
    6351113 
    6361114-- | The union of a list of maps, with a combining operation: 
    6371115--   (@'unionsWith' f == 'Prelude.foldl' ('unionWith' f) 'empty'@). 
     1116-- 
     1117-- > let map1 = fromList [(5, "a"), (3, "b")] 
     1118-- > let map2 = fromList [(5, "A"), (10, "C")] 
     1119-- > let map3 = fromList [(5, "A3"), (3, "B3")] 
     1120-- > unionsWith (++) [map1, map2, map3] 
     1121-- >   {3:="bB3",5:="aAA3",10:="C"} 
     1122 
    6381123unionsWith :: Ord k => (a->a->a) -> [Map k a] -> Map k a 
    6391124unionsWith f ts 
    6401125  = foldlStrict (unionWith f) empty ts 
    6411126 
    642 -- | /O(n+m)/. 
    643 -- The expression (@'union' t1 t2@) takes the left-biased union of @t1@ and @t2@.  
     1127-- | The expression (@'union' t1 t2@) takes the left-biased union of @t1@ and @t2@.  
    6441128-- It prefers @t1@ when duplicate keys are encountered, 
    6451129-- i.e. (@'union' == 'unionWith' 'const'@). 
    6461130-- The implementation uses the efficient /hedge-union/ algorithm. 
    647 -- Hedge-union is more efficient on (bigset `union` smallset) 
     1131-- Hedge-union is more efficient on (bigset \``union`\` smallset). /O(n+m)/. 
     1132-- 
     1133-- > let map1 = fromList [(5, "a"), (3, "b")] 
     1134-- > let map2 = fromList [(5, "A"), (10, "C")] 
     1135-- > union map1 map2 
     1136-- >   {3:="b",5:="a",10:="C"} 
     1137 
    6481138union :: Ord k => Map k a -> Map k a -> Map k a 
    6491139union Tip t2  = t2 
    6501140union t1 Tip  = t1 
     
    6801170{-------------------------------------------------------------------- 
    6811171  Union with a combining function 
    6821172--------------------------------------------------------------------} 
    683 -- | /O(n+m)/. Union with a combining function. The implementation uses the efficient /hedge-union/ algorithm. 
     1173-- | Union with a combining function. The implementation uses the efficient /hedge-union/ algorithm. 
     1174-- /O(n+m)/. 
     1175-- 
     1176-- > let map1 = fromList [(5, "a"), (3, "b")] 
     1177-- > let map2 = fromList [(5, "A"), (10, "C")] 
     1178-- > unionWith (++) map1 map2 
     1179-- >   {3:="b",5:="aA",10:="C"} 
     1180 
    6841181unionWith :: Ord k => (a -> a -> a) -> Map k a -> Map k a -> Map k a 
    6851182unionWith f m1 m2 
    6861183  = unionWithKey (\k x y -> f x y) m1 m2 
    6871184 
    688 -- | /O(n+m)/. 
    689 -- Union with a combining function. The implementation uses the efficient /hedge-union/ algorithm. 
    690 -- Hedge-union is more efficient on (bigset `union` smallset). 
     1185-- | Union with a combining function. The implementation uses the efficient /hedge-union/ algorithm. 
     1186-- Hedge-union is more efficient on (bigset \``union`\` smallset). 
     1187-- /O(n+m)/. 
     1188-- 
     1189-- > let map1 = fromList [(5, "a"), (3, "b")] 
     1190-- > let map2 = fromList [(5, "A"), (10, "C")] 
     1191-- > let f key new_value old_value = (show key) ++ ":" ++ new_value ++ "|" ++ old_value 
     1192-- > unionWithKey f map1 map2 
     1193-- >   {3:="b",5:="5:a|A",10:="C"} 
     1194 
    6911195unionWithKey :: Ord k => (k -> a -> a -> a) -> Map k a -> Map k a -> Map k a 
    6921196unionWithKey f Tip t2  = t2 
    6931197unionWithKey f t1 Tip  = t1 
     
    7111215{-------------------------------------------------------------------- 
    7121216  Difference 
    7131217--------------------------------------------------------------------} 
    714 -- | /O(n+m)/. Difference of two maps.  
     1218-- | Difference of two maps.  
     1219-- Return elements of the first map not existing in the second map. 
    7151220-- The implementation uses an efficient /hedge/ algorithm comparable with /hedge-union/. 
     1221-- /O(n+m)/. 
     1222-- 
     1223-- > let map1 = fromList [(5, "a"), (3, "b")] 
     1224-- > let map2 = fromList [(5, "A"), (10, "C")] 
     1225-- > difference map1 map2 
     1226-- >   {3:="b"} 
     1227 
    7161228difference :: Ord k => Map k a -> Map k b -> Map k a 
    7171229difference Tip t2  = Tip 
    7181230difference t1 Tip  = t1 
     
    7281240  where 
    7291241    cmpkx k = compare kx k    
    7301242 
    731 -- | /O(n+m)/. Difference with a combining function.  
     1243-- | Difference with a combining function.  
     1244-- When two equal keys are 
     1245-- encountered, the combining function is applied to the values of these keys. 
     1246-- If it returns 'Nothing', the element is discarded (proper set difference). If 
     1247-- it returns (@'Just' y@), the element is updated with a new value @y@.  
    7321248-- The implementation uses an efficient /hedge/ algorithm comparable with /hedge-union/. 
     1249-- /O(n+m)/. 
     1250-- 
     1251-- > -- 3 and 5 are common keys 
     1252-- > let map1 = fromList [(5, "a"), (3, "b")] 
     1253-- > let map2 = fromList [(5, "A"), (3, "B"), (10, "C")] 
     1254-- > map1 
     1255-- >   {3:="b",5:="a"} 
     1256-- > map2 
     1257-- >   {3:="B",5:="A",10:="C"} 
     1258-- > let f al ar = if al == "b" then Just (al ++ ":" ++ ar) else Nothing 
     1259-- > 
     1260-- > -- f returns Nothing for 5, Just "b:B" for 3 
     1261-- > differenceWith f map1 map2 
     1262-- >   {3:="b:B"} 
     1263 
    7331264differenceWith :: Ord k => (a -> b -> Maybe a) -> Map k a -> Map k b -> Map k a 
    7341265differenceWith f m1 m2 
    7351266  = differenceWithKey (\k x y -> f x y) m1 m2 
    7361267 
    737 -- | /O(n+m)/. Difference with a combining function. When two equal keys are 
     1268-- | Difference with a combining function. When two equal keys are 
    7381269-- encountered, the combining function is applied to the key and both values. 
    7391270-- If it returns 'Nothing', the element is discarded (proper set difference). If 
    7401271-- it returns (@'Just' y@), the element is updated with a new value @y@.  
    7411272-- The implementation uses an efficient /hedge/ algorithm comparable with /hedge-union/. 
     1273-- /O(n+m)/. 
     1274-- 
     1275-- > -- 3 and 5 are common keys 
     1276-- > let map1 = fromList [(5, "a"), (3, "b")] 
     1277-- > let map2 = fromList [(5, "A"), (3, "B"), (10, "C")] 
     1278-- > map1 
     1279-- >   {3:="b",5:="a"} 
     1280-- > map2 
     1281-- >   {3:="B",5:="A",10:="C"} 
     1282-- > let f k al ar = if al == "b" then Just ((show k) ++ ":" ++ al ++ "|" ++ ar) else Nothing 
     1283-- > 
     1284-- > -- f returns Nothing for 5, Just "3:b|B" for 3 
     1285-- > differenceWithKey f map1 map2 
     1286-- >   {3:="3:b|B"} 
     1287 
    7421288differenceWithKey :: Ord k => (k -> a -> b -> Maybe a) -> Map k a -> Map k b -> Map k a 
    7431289differenceWithKey f Tip t2  = Tip 
    7441290differenceWithKey f t1 Tip  = t1 
     
    7671313{-------------------------------------------------------------------- 
    7681314  Intersection 
    7691315--------------------------------------------------------------------} 
    770 -- | /O(n+m)/. Intersection of two maps. The values in the first 
    771 -- map are returned, i.e. (@'intersection' m1 m2 == 'intersectionWith' 'const' m1 m2@). 
     1316-- | Intersection of two maps. 
     1317-- Return data in the first map for the keys existing in both maps. 
     1318-- (@'intersection' m1 m2 == 'intersectionWith' 'const' m1 m2@). 
     1319-- /O(n+m)/. 
     1320-- 
     1321-- > let map1 = fromList [(5, "a"), (3, "b")] 
     1322-- > let map2 = fromList [(5, "A"), (10, "C")] 
     1323-- > intersection map1 map2 
     1324-- >   {5:="a"} 
     1325 
    7721326intersection :: Ord k => Map k a -> Map k b -> Map k a 
    7731327intersection m1 m2 
    7741328  = intersectionWithKey (\k x y -> x) m1 m2 
    7751329 
    776 -- | /O(n+m)/. Intersection with a combining function. 
     1330-- | Intersection with a combining function. 
     1331-- /O(n+m)/. 
     1332-- 
     1333-- > let map1 = fromList [(5, "a"), (3, "b")] 
     1334-- > let map2 = fromList [(5, "A"), (10, "C")] 
     1335-- > intersectionWith (++) map1 map2 
     1336-- >   {5:="aA"} 
     1337 
    7771338intersectionWith :: Ord k => (a -> b -> c) -> Map k a -> Map k b -> Map k c 
    7781339intersectionWith f m1 m2 
    7791340  = intersectionWithKey (\k x y -> f x y) m1 m2 
    7801341 
    781 -- | /O(n+m)/. Intersection with a combining function. 
    782 -- Intersection is more efficient on (bigset `intersection` smallset) 
     1342-- | Intersection with a combining function. 
     1343-- Intersection is more efficient on (bigset \``intersection`\` smallset). /O(n+m)/. 
     1344-- 
     1345-- > let map1 = fromList [(5, "a"), (3, "b")] 
     1346-- > let map2 = fromList [(5, "A"), (10, "C")] 
     1347-- > let f k al ar = (show k) ++ ":" ++ al ++ "|" ++ ar 
     1348-- > intersectionWithKey f map1 map2 
     1349-- >   {5:="5:a|A"} 
     1350 
    7831351--intersectionWithKey :: Ord k => (k -> a -> b -> c) -> Map k a -> Map k b -> Map k c 
    7841352--intersectionWithKey f Tip t = Tip 
    7851353--intersectionWithKey f t Tip = Tip 
     
    7961364--    tl            = intersectWithKey f lt l 
    7971365--    tr            = intersectWithKey f gt r 
    7981366 
    799  
    8001367intersectionWithKey :: Ord k => (k -> a -> b -> c) -> Map k a -> Map k b -> Map k c 
    8011368intersectionWithKey f Tip t = Tip 
    8021369intersectionWithKey f t Tip = Tip 
     
    8201387{-------------------------------------------------------------------- 
    8211388  Submap 
    8221389--------------------------------------------------------------------} 
    823 -- | /O(n+m)/.  
    824 -- This function is defined as (@'isSubmapOf' = 'isSubmapOfBy' (==)@). 
     1390-- | This function is defined as (@'isSubmapOf' = 'isSubmapOfBy' (==)@). 
     1391-- /O(n+m)/. 
    8251392isSubmapOf :: (Ord k,Eq a) => Map k a -> Map k a -> Bool 
    8261393isSubmapOf m1 m2 
    8271394  = isSubmapOfBy (==) m1 m2 
    8281395 
    829 {- | /O(n+m)/.  
    830  The expression (@'isSubmapOfBy' f t1 t2@) returns 'True' if 
     1396{- | The expression (@'isSubmapOfBy' f t1 t2@) returns 'True' if 
    8311397 all keys in @t1@ are in tree @t2@, and when @f@ returns 'True' when 
    8321398 applied to their respective values. For example, the following  
    8331399 expressions are all 'True': 
     
    8411407 > isSubmapOfBy (==) (fromList [('a',2)]) (fromList [('a',1),('b',2)]) 
    8421408 > isSubmapOfBy (<)  (fromList [('a',1)]) (fromList [('a',1),('b',2)]) 
    8431409 > isSubmapOfBy (==) (fromList [('a',1),('b',2)]) (fromList [('a',1)]) 
     1410  
     1411 /O(n+m)/. 
    8441412-} 
    8451413isSubmapOfBy :: Ord k => (a->b->Bool) -> Map k a -> Map k b -> Bool 
    8461414isSubmapOfBy f t1 t2 
     
    8551423  where 
    8561424    (lt,found,gt) = splitLookup kx t 
    8571425 
    858 -- | /O(n+m)/. Is this a proper submap? (ie. a submap but not equal).  
    859 -- Defined as (@'isProperSubmapOf' = 'isProperSubmapOfBy' (==)@). 
     1426-- | Is this a proper submap? (ie. a submap but not equal).  
     1427-- Defined as (@'isProperSubmapOf' = 'isProperSubmapOfBy' (==)@). /O(n+m)/. 
    8601428isProperSubmapOf :: (Ord k,Eq a) => Map k a -> Map k a -> Bool 
    8611429isProperSubmapOf m1 m2 
    8621430  = isProperSubmapOfBy (==) m1 m2 
    8631431 
    864 {- | /O(n+m)/. Is this a proper submap? (ie. a submap but not equal). 
     1432{- | Is this a proper submap? (ie. a submap but not equal). 
    8651433 The expression (@'isProperSubmapOfBy' f m1 m2@) returns 'True' when 
    8661434 @m1@ and @m2@ are not equal, 
    8671435 all keys in @m1@ are in @m2@, and when @f@ returns 'True' when 
     
    8761444  > isProperSubmapOfBy (==) (fromList [(1,1),(2,2)]) (fromList [(1,1),(2,2)]) 
    8771445  > isProperSubmapOfBy (==) (fromList [(1,1),(2,2)]) (fromList [(1,1)]) 
    8781446  > isProperSubmapOfBy (<)  (fromList [(1,1)])       (fromList [(1,1),(2,2)]) 
     1447   
     1448  /O(n+m)/. 
    8791449-} 
    8801450isProperSubmapOfBy :: Ord k => (a -> b -> Bool) -> Map k a -> Map k b -> Bool 
    8811451isProperSubmapOfBy f t1 t2 
     
    8841454{-------------------------------------------------------------------- 
    8851455  Filter and partition 
    8861456--------------------------------------------------------------------} 
    887 -- | /O(n)/. Filter all values that satisfy the predicate. 
     1457-- | Filter all values that satisfy the predicate. /O(n)/. 
     1458-- 
     1459-- > let m = fromList [(5,"a"), (3,"b")] 
     1460-- > m 
     1461-- >   {3:="b",5:="a"} 
     1462-- > filter (> "a") m 
     1463-- >   {3:="b"} 
     1464-- > filter (> "x") m 
     1465-- >   {} 
     1466-- > filter (< "a") m 
     1467-- >   {} 
     1468 
    8881469filter :: Ord k => (a -> Bool) -> Map k a -> Map k a 
    8891470filter p m 
    8901471  = filterWithKey (\k x -> p x) m 
    8911472 
    892 -- | /O(n)/. Filter all keys\/values that satisfy the predicate. 
     1473-- | Filter all keys\/values that satisfy the predicate. /O(n)/. 
     1474-- 
     1475-- > let m = fromList [(5,"a"), (3,"b")] 
     1476-- > m 
     1477-- >   {3:="b",5:="a"} 
     1478-- > let f k a = k > 4 
     1479-- > filterWithKey f m 
     1480-- >   {5:="a"} 
     1481 
    8931482filterWithKey :: Ord k => (k -> a -> Bool) -> Map k a -> Map k a 
    8941483filterWithKey p Tip = Tip 
    8951484filterWithKey p (Bin _ kx x l r) 
     
    8971486  | otherwise = merge (filterWithKey p l) (filterWithKey p r) 
    8981487 
    8991488 
    900 -- | /O(n)/. partition the map according to a predicate. The first 
     1489-- | Partition the map according to a predicate. The first 
    9011490-- map contains all elements that satisfy the predicate, the second all 
    9021491-- elements that fail the predicate. See also 'split'. 
     1492-- /O(n)/. 
     1493-- 
     1494-- > let m = fromList [(5,"a"), (3,"b")] 
     1495-- > m 
     1496-- >   {3:="b",5:="a"} 
     1497-- > partition (> "a") m 
     1498-- >   ({3:="b"},{5:="a"}) 
     1499-- > partition (< "x") m 
     1500-- >   ({3:="b",5:="a"},{}) 
     1501-- > partition (> "x") m 
     1502-- >   ({},{3:="b",5:="a"}) 
     1503 
    9031504partition :: Ord k => (a -> Bool) -> Map k a -> (Map k a,Map k a) 
    9041505partition p m 
    9051506  = partitionWithKey (\k x -> p x) m 
    9061507 
    907 -- | /O(n)/. partition the map according to a predicate. The first 
     1508-- | Partition the map according to a predicate. The first 
    9081509-- map contains all elements that satisfy the predicate, the second all 
    909 -- elements that fail the predicate. See also 'split'. 
     1510-- elements that fail the predicate. See also 'split'. /O(n)/. 
     1511-- 
     1512-- > let m = fromList [(5,"a"), (3,"b")] 
     1513-- > m 
     1514-- >   {3:="b",5:="a"} 
     1515-- > partitionWithKey (\ k _ -> k > 3) m 
     1516-- >   ({5:="a"},{3:="b"}) 
     1517-- > partitionWithKey (\ k _ -> k < 10) m 
     1518-- >   ({3:="b",5:="a"},{}) 
     1519-- > partitionWithKey (\ k _ -> k > 10) m 
     1520-- >   ({},{3:="b",5:="a"}) 
     1521 
    9101522partitionWithKey :: Ord k => (k -> a -> Bool) -> Map k a -> (Map k a,Map k a) 
    9111523partitionWithKey p Tip = (Tip,Tip) 
    9121524partitionWithKey p (Bin _ kx x l r) 
     
    9161528    (l1,l2) = partitionWithKey p l 
    9171529    (r1,r2) = partitionWithKey p r 
    9181530 
    919 -- | /O(n)/. Map values and collect the 'Just' results. 
     1531-- | Map values and collect the 'Just' results. /O(n)/. 
     1532-- 
     1533-- > let m = fromList [(5,"a"), (3,"b")] 
     1534-- > m 
     1535-- >   {3:="b",5:="a"} 
     1536-- > let f x = if x == "a" then Just "new a" else Nothing 
     1537-- > mapMaybe f m 
     1538-- >   {5:="new a"} 
     1539 
    9201540mapMaybe :: Ord k => (a -> Maybe b) -> Map k a -> Map k b 
    9211541mapMaybe f m 
    9221542  = mapMaybeWithKey (\k x -> f x) m 
    9231543 
    924 -- | /O(n)/. Map keys\/values and collect the 'Just' results. 
     1544-- | Map keys\/values and collect the 'Just' results. /O(n)/. 
     1545-- 
     1546-- > let m = fromList [(5,"a"), (3,"b")] 
     1547-- > m 
     1548-- >   {3:="b",5:="a"} 
     1549-- > let f k _ = if k < 5 then Just ("key : " ++ (show k)) else Nothing 
     1550-- > mapMaybeWithKey f m 
     1551-- >   {3,"key : 3"} 
     1552 
    9251553mapMaybeWithKey :: Ord k => (k -> a -> Maybe b) -> Map k a -> Map k b 
    9261554mapMaybeWithKey f Tip = Tip 
    9271555mapMaybeWithKey f (Bin _ kx x l r) = case f kx x of 
    9281556  Just y  -> join kx y (mapMaybeWithKey f l) (mapMaybeWithKey f r) 
    9291557  Nothing -> merge (mapMaybeWithKey f l) (mapMaybeWithKey f r) 
    9301558 
    931 -- | /O(n)/. Map values and separate the 'Left' and 'Right' results. 
     1559-- | Map values and separate the 'Left' and 'Right' results. /O(n)/. 
     1560-- 
     1561-- > let m = fromList [(5,"a"), (3,"b"), (1, "x"), (10, "z")] 
     1562-- > m 
     1563-- >   {1:="x",3:="b",5:="a",10:="z"} 
     1564-- > let f a = if a < "c" then Left a else Right a 
     1565-- > mapEither f m 
     1566-- >   ({3:="b",5:="a"},{1:="x",10:="z"}) 
     1567-- > 
     1568-- > let f a = Right a 
     1569-- > mapEither f m 
     1570-- >   ({},{1:="x",3:="b",5:="a",10:="z"}) 
     1571 
    9321572mapEither :: Ord k => (a -> Either b c) -> Map k a -> (Map k b, Map k c) 
    9331573mapEither f m 
    9341574  = mapEitherWithKey (\k x -> f x) m 
    9351575 
    936 -- | /O(n)/. Map keys\/values and separate the 'Left' and 'Right' results. 
     1576-- | Map keys\/values and separate the 'Left' and 'Right' results. /O(n)/. 
     1577-- 
     1578-- > let m = fromList [(5,"a"), (3,"b"), (1, "x"), (10, "z")] 
     1579-- > m 
     1580-- >   {1:="x",3:="b",5:="a",10:="z"} 
     1581-- > let f k a = if k < 5 then Left k else Right a 
     1582-- > mapEitherWithKey f m 
     1583-- > ({1:=2,3:=6},{5:="a",10:="z"}) 
     1584-- > 
     1585-- > let f _ a = Right a 
     1586-- > mapEitherWithKey f m 
     1587-- >   ({},{1:="x",3:="b",5:="a",10:="z"}) 
     1588 
    9371589mapEitherWithKey :: Ord k => 
    9381590  (k -> a -> Either b c) -> Map k a -> (Map k b, Map k c) 
    9391591mapEitherWithKey f Tip = (Tip, Tip) 
     
    9471599{-------------------------------------------------------------------- 
    9481600  Mapping 
    9491601--------------------------------------------------------------------} 
    950 -- | /O(n)/. Map a function over all values in the map. 
     1602-- | Map a function over all values in the map. /O(n)/. 
     1603-- 
     1604-- > let m = fromList [(5,"a"), (3,"b")] 
     1605-- > m 
     1606-- >   {3:="b",5:="a"} 
     1607-- > map (++ "x") m 
     1608-- >   {3:="bx",5:="ax"} 
     1609 
    9511610map :: (a -> b) -> Map k a -> Map k b 
    9521611map f m 
    9531612  = mapWithKey (\k x -> f x) m 
    9541613 
    955 -- | /O(n)/. Map a function over all values in the map. 
     1614-- | Map a function over all values in the map. /O(n)/. 
     1615-- 
     1616-- > let m = fromList [(5,"a"), (3,"b")] 
     1617-- > m 
     1618-- >   {3:="b",5:="a"} 
     1619-- > let f key x = (show key) ++ ":" ++ x 
     1620-- > mapWithKey f m 
     1621-- >   {3:="3:b",5:="5:a"} 
     1622 
    9561623mapWithKey :: (k -> a -> b) -> Map k a -> Map k b 
    9571624mapWithKey f Tip = Tip 
    9581625mapWithKey f (Bin sx kx x l r)  
    9591626  = Bin sx kx (f kx x) (mapWithKey f l) (mapWithKey f r) 
    9601627 
    961 -- | /O(n)/. The function 'mapAccum' threads an accumulating 
    962 -- argument through the map in ascending order of keys. 
     1628-- | The function 'mapAccum' threads an accumulating 
     1629-- argument through the map in ascending order of keys. /O(n)/. 
     1630-- 
     1631-- > let m = fromList [(5,"a"), (3,"b")] 
     1632-- > m 
     1633-- >   {3:="b",5:="a"} 
     1634-- > let f a b = (a ++ b, b ++ "X") 
     1635-- > mapAccum f "Everything: " m 
     1636-- >   ("Everything: ba",{3:="bX",5:="aX"}) 
     1637 
    9631638mapAccum :: (a -> b -> (a,c)) -> a -> Map k b -> (a,Map k c) 
    9641639mapAccum f a m 
    9651640  = mapAccumWithKey (\a k x -> f a x) a m 
    9661641 
    967 -- | /O(n)/. The function 'mapAccumWithKey' threads an accumulating 
    968 -- argument through the map in ascending order of keys. 
     1642-- | The function 'mapAccumWithKey' threads an accumulating 
     1643-- argument through the map in ascending order of keys. /O(n)/. 
     1644-- 
     1645-- > let m = fromList [(5,"a"), (3,"b")] 
     1646-- > m 
     1647-- >   {3:="b",5:="a"} 
     1648-- > let f a k b = (a ++ " " ++ (show k) ++ "-" ++ b, b ++ "X") 
     1649-- > mapAccumWithKey f "Everything:" m 
     1650-- >   ("Everything: 3-b 5-a",{3:="bX",5:="aX"}) 
     1651 
    9691652mapAccumWithKey :: (a -> k -> b -> (a,c)) -> a -> Map k b -> (a,Map k c) 
    9701653mapAccumWithKey f a t 
    9711654  = mapAccumL f a t 
    9721655 
    973 -- | /O(n)/. The function 'mapAccumL' threads an accumulating 
    974 -- argument throught the map in ascending order of keys. 
     1656-- | The function 'mapAccumL' threads an accumulating 
     1657-- argument throught the map in ascending order of keys. /O(n)/. 
    9751658mapAccumL :: (a -> k -> b -> (a,c)) -> a -> Map k b -> (a,Map k c) 
    9761659mapAccumL f a t 
    9771660  = case t of 
     
    9821665                 (a3,r') = mapAccumL f a2 r 
    9831666             in (a3,Bin sx kx x' l' r') 
    9841667 
    985 -- | /O(n)/. The function 'mapAccumR' threads an accumulating 
    986 -- argument throught the map in descending order of keys. 
     1668-- | The function 'mapAccumR' threads an accumulating 
     1669-- argument throught the map in descending order of keys. /O(n)/. 
    9871670mapAccumR :: (a -> k -> b -> (a,c)) -> a -> Map k b -> (a,Map k c) 
    9881671mapAccumR f a t 
    9891672  = case t of 
     
    9941677                 (a3,l') = mapAccumR f a2 l 
    9951678             in (a3,Bin sx kx x' l' r') 
    9961679 
    997 -- | /O(n*log n)/.  
    998 -- @'mapKeys' f s@ is the map obtained by applying @f@ to each key of @s@. 
     1680-- | @'mapKeys' f s@ is the map obtained by applying @f@ to each key of @s@. 
    9991681--  
    10001682-- The size of the result may be smaller if @f@ maps two or more distinct 
    10011683-- keys to the same new key.  In this case the value at the smallest of 
    1002 -- these keys is retained. 
     1684-- these keys is retained. /O(n*log n)/. 
     1685-- 
     1686-- > let m = fromList [(5,"a"), (3,"b")] 
     1687-- > m 
     1688-- >   {3:="b",5:="a"} 
     1689-- > mapKeys (+ 1) m 
     1690-- >   {4:="b",6:="a"} 
     1691-- > 
     1692-- > -- overlapping resulting keys 
     1693-- > let m = fromList [(1,"b"), (2,"a"), (3,"d"), (4,"c")] 
     1694-- > m 
     1695-- >   {1:="b",2:="a",3:="d",4:="c"} 
     1696-- > mapKeys (\ _ -> 1) m 
     1697-- >   {1:="c"} 
     1698-- > mapKeys (\ _ -> 3) m 
     1699-- >   {3:="c"} 
    10031700 
    10041701mapKeys :: Ord k2 => (k1->k2) -> Map k1 a -> Map k2 a 
    10051702mapKeys = mapKeysWith (\x y->x) 
    10061703 
    1007 -- | /O(n*log n)/.  
    1008 -- @'mapKeysWith' c f s@ is the map obtained by applying @f@ to each key of @s@. 
     1704-- | @'mapKeysWith' c f s@ is the map obtained by applying @f@ to each key of @s@. 
    10091705--  
    10101706-- The size of the result may be smaller if @f@ maps two or more distinct 
    10111707-- keys to the same new key.  In this case the associated values will be 
    1012 -- combined using @c@. 
     1708-- combined using @c@. /O(n*log n)/. 
     1709-- 
     1710-- > let m = fromList [(1,"b"), (2,"a"), (3,"d"), (4,"c")] 
     1711-- > m 
     1712-- >   {1:="b",2:="a",3:="d",4:="c"} 
     1713-- > mapKeysWith (++) (\ _ -> 1) m 
     1714-- >   {1:="cdab"} 
     1715-- > mapKeysWith (++) (\ _ -> 3) m 
     1716-- >   {3:="cdab"} 
    10131717 
    10141718mapKeysWith :: Ord k2 => (a -> a -> a) -> (k1->k2) -> Map k1 a -> Map k2 a 
    10151719mapKeysWith c f = fromListWith c . List.map fFirst . toList 
    10161720    where fFirst (x,y) = (f x, y) 
    10171721 
    10181722 
    1019 -- | /O(n)/. 
    1020 -- @'mapKeysMonotonic' f s == 'mapKeys' f s@, but works only when @f@ 
     1723-- | @'mapKeysMonotonic' f s == 'mapKeys' f s@, but works only when @f@ 
    10211724-- is strictly monotonic. 
     1725-- That is, for any values @x@ and @y@, if @x@ < @y@ then @f x@ < @f y@. 
    10221726-- /The precondition is not checked./ 
    10231727-- Semi-formally, we have: 
    10241728--  
    10251729-- > and [x < y ==> f x < f y | x <- ls, y <- ls]  
    10261730-- >                     ==> mapKeysMonotonic f s == mapKeys f s 
    10271731-- >     where ls = keys s 
     1732-- 
     1733-- This means that @f@ maps distinct original keys to distinct resulting keys. 
     1734-- This function has better performance than 'mapKeys'. /O(n)/. 
     1735-- 
     1736-- > let m = fromList [(5,"a"), (3,"b")] 
     1737-- > m 
     1738-- >   {3:="b",5:="a"} 
     1739-- > let result = mapKeysMonotonic (\ k -> k * 2) m 
     1740-- > result 
     1741-- >   {6:="b",10:="a"} 
     1742-- > valid result 
     1743-- >   True 
     1744-- > 
     1745-- > -- resulting map is invalid if the function is non-monotonic 
     1746-- > let result = mapKeysMonotonic (\ _ -> 1) m 
     1747-- > result 
     1748-- >   {1:="b",1:="a"} 
     1749-- > valid result 
     1750-- >   False 
    10281751 
    10291752mapKeysMonotonic :: (k1->k2) -> Map k1 a -> Map k2 a 
    10301753mapKeysMonotonic f Tip = Tip 
     
    10351758  Folds   
    10361759--------------------------------------------------------------------} 
    10371760 
    1038 -- | /O(n)/. Fold the values in the map, such that 
     1761-- | Fold the values in the map, such that 
    10391762-- @'fold' f z == 'Prelude.foldr' f z . 'elems'@. 
    10401763-- For example, 
    10411764-- 
    10421765-- > elems map = fold (:) [] map 
    10431766-- 
     1767-- /O(n)/. 
     1768-- 
     1769-- > let m = fromList [(5,"a"), (3,"bbb")] 
     1770-- > m 
     1771-- >   {3:="bbb",5:="a"} 
     1772-- > 
     1773-- > let f a len = len + (length a) 
     1774-- > -- sum of values lengths 
     1775-- > fold f 0 m 
     1776-- >   4 
     1777 
    10441778fold :: (a -> b -> b) -> b -> Map k a -> b 
    10451779fold f z m 
    10461780  = foldWithKey (\k x z -> f x z) z m 
    10471781 
    1048 -- | /O(n)/. Fold the keys and values in the map, such that 
     1782-- | Fold the keys and values in the map, such that 
    10491783-- @'foldWithKey' f z == 'Prelude.foldr' ('uncurry' f) z . 'toAscList'@. 
    10501784-- For example, 
    10511785-- 
    10521786-- > keys map = foldWithKey (\k x ks -> k:ks) [] map 
    10531787-- 
     1788-- /O(n)/. 
     1789-- 
     1790-- > let m = fromList [(5,"a"), (3,"b")] 
     1791-- > m 
     1792-- >   {3:="b",5:="a"} 
     1793-- > let f k a result = result ++ "(" ++ (show k) ++ ":" ++ a ++ ")" 
     1794-- > foldWithKey f "Map: " m 
     1795-- >   "Map: (5:a)(3:b)" 
     1796 
    10541797foldWithKey :: (k -> a -> b -> b) -> b -> Map k a -> b 
    10551798foldWithKey f z t 
    10561799  = foldr f z t 
    10571800 
    1058 -- | /O(n)/. In-order fold. 
     1801-- | In-order fold. /O(n)/. 
    10591802foldi :: (k -> a -> b -> b -> b) -> b -> Map k a -> b  
    10601803foldi f z Tip               = z 
    10611804foldi f z (Bin _ kx x l r)  = f kx x (foldi f z l) (foldi f z r) 
    10621805 
    1063 -- | /O(n)/. Post-order fold. 
     1806-- | Post-order fold. /O(n)/. 
    10641807foldr :: (k -> a -> b -> b) -> b -> Map k a -> b 
    10651808foldr f z Tip              = z 
    10661809foldr f z (Bin _ kx x l r) = foldr f (f kx x (foldr f z r)) l 
    10671810 
    1068 -- | /O(n)/. Pre-order fold. 
     1811-- | Pre-order fold. /O(n)/. 
    10691812foldl :: (b -> k -> a -> b) -> b -> Map k a -> b 
    10701813foldl f z Tip              = z 
    10711814foldl f z (Bin _ kx x l r) = foldl f (f (foldl f z l) kx x) r 
     
    10731816{-------------------------------------------------------------------- 
    10741817  List variations  
    10751818--------------------------------------------------------------------} 
    1076 -- | /O(n)/. 
    1077 -- Return all elements of the map in the ascending order of their keys. 
     1819-- | Return all elements of the map in the ascending order of their keys. 
     1820-- /O(n)/. 
     1821-- 
     1822-- > let m = fromList [(5,"a"), (3,"b")] 
     1823-- > m 
     1824-- >   {3:="b",5:="a"} 
     1825-- > elems m 
     1826-- >   ["b","a"] 
     1827-- > elems empty 
     1828-- >   [] 
     1829 
    10781830elems :: Map k a -> [a] 
    10791831elems m 
    10801832  = [x | (k,x) <- assocs m] 
    10811833 
    1082 -- | /O(n)/. Return all keys of the map in ascending order. 
     1834-- | Return all keys of the map in ascending order. /O(n)/. 
     1835-- 
     1836-- > let m = fromList [(5,"a"), (3,"b")] 
     1837-- > m 
     1838-- >   {3:="b",5:="a"} 
     1839-- > keys m 
     1840-- >   [3,5] 
     1841-- > keys empty 
     1842-- >   [] 
     1843 
    10831844keys  :: Map k a -> [k] 
    10841845keys m 
    10851846  = [k | (k,x) <- assocs m] 
    10861847 
    1087 -- | /O(n)/. The set of all keys of the map. 
     1848-- | The set of all keys of the map. /O(n)/. 
     1849-- 
     1850-- > let m = fromList [(5,"a"), (3,"b")] 
     1851-- > m 
     1852-- >   {3:="b",5:="a"} 
     1853-- > keysSet m 
     1854-- >   {3,5} 
     1855-- > keysSet empty 
     1856-- >   {} 
     1857 
    10881858keysSet :: Map k a -> Set.Set k 
    10891859keysSet m = Set.fromDistinctAscList (keys m) 
    10901860 
    1091 -- | /O(n)/. Return all key\/value pairs in the map in ascending key order. 
     1861-- | Return all key\/value pairs in the map in ascending key order. /O(n)/. 
     1862-- 
     1863-- > let m = fromList [(5,"a"), (3,"b")] 
     1864-- > m 
     1865-- >   {3:="b",5:="a"} 
     1866-- > assocs m 
     1867-- >   [(3,"b"),(5,"a")] 
     1868-- > assocs empty 
     1869-- >   [] 
     1870 
    10921871assocs :: Map k a -> [(k,a)] 
    10931872assocs m 
    10941873  = toList m 
     
    10971876  Lists  
    10981877  use [foldlStrict] to reduce demand on the control-stack 
    10991878--------------------------------------------------------------------} 
    1100 -- | /O(n*log n)/. Build a map from a list of key\/value pairs. See also 'fromAscList'. 
     1879-- | Build a map from a list of key\/value pairs. See also 'fromAscList'. 
     1880-- If the list contains more than one value for the same key, the last value 
     1881-- for the key is retained. 
     1882-- /O(n*log n)/. 
     1883-- 
     1884-- > fromList [(5,"a"), (3,"b")] 
     1885-- >   {3:="b",5:="a"} 
     1886-- > fromList [] 
     1887-- >   {} 
     1888-- > fromList [(5,"a"), (3,"b"), (5, "b")] 
     1889-- >   {3:="b",5:="b"} 
     1890-- > fromList [(5,"b"), (3,"b"), (5, "a")] 
     1891-- >   {3:="b",5:="a"} 
     1892 
    11011893fromList :: Ord k => [(k,a)] -> Map k a  
    11021894fromList xs        
    11031895  = foldlStrict ins empty xs 
    11041896  where 
    11051897    ins t (k,x) = insert k x t 
    11061898 
    1107 -- | /O(n*log n)/. Build a map from a list of key\/value pairs with a combining function. See also 'fromAscListWith'. 
     1899-- | Build a map from a list of key\/value pairs with a combining function. See also 'fromAscListWith'. 
     1900-- /O(n*log n)/. 
     1901-- 
     1902-- > fromListWith (++) [(5,"a"), (5,"b"), (3,"b"), (3,"a"), (5,"a")] 
     1903-- >   {3:="ab",5:="aba"} 
     1904-- > fromListWith (++) [] 
     1905-- >   {} 
     1906 
    11081907fromListWith :: Ord k => (a -> a -> a) -> [(k,a)] -> Map k a  
    11091908fromListWith f xs 
    11101909  = fromListWithKey (\k x y -> f x y) xs 
    11111910 
    1112 -- | /O(n*log n)/. Build a map from a list of key\/value pairs with a combining function. See also 'fromAscListWithKey'. 
     1911-- | Build a map from a list of key\/value pairs with a combining function. See also 'fromAscListWithKey'. 
     1912-- /O(n*log n)/. 
     1913-- 
     1914-- > let f k a1 a2 = (show k) ++ a1 ++ a2 
     1915-- > fromListWithKey f [(5,"a"), (5,"b"), (3,"b"), (3,"a"), (5,"a")] 
     1916-- >   {3:="3ab",5:="5a5ba"} 
     1917-- > fromListWithKey f [] 
     1918-- >   {} 
     1919 
    11131920fromListWithKey :: Ord k => (k -> a -> a -> a) -> [(k,a)] -> Map k a  
    11141921fromListWithKey f xs  
    11151922  = foldlStrict ins empty xs 
    11161923  where 
    11171924    ins t (k,x) = insertWithKey f k x t 
    11181925 
    1119 -- | /O(n)/. Convert to a list of key\/value pairs. 
     1926-- | Convert to a list of key\/value pairs. /O(n)/. 
     1927-- 
     1928-- > let m = fromList [(5,"a"), (3,"b")] 
     1929-- > m 
     1930-- >   {3:="b",5:="a"} 
     1931-- > toList m 
     1932-- >   [(3,"b"),(5,"a")] 
     1933 
    11201934toList :: Map k a -> [(k,a)] 
    11211935toList t      = toAscList t 
    11221936 
    1123 -- | /O(n)/. Convert to an ascending list. 
     1937-- | Convert to an ascending list. /O(n)/. 
     1938-- 
     1939-- > let m = fromList [(5,"a"), (3,"b")] 
     1940-- > m 
     1941-- >   {3:="b",5:="a"} 
     1942-- > 
     1943-- > toAscList m 
     1944-- >   [(3,"b"),(5,"a")] 
     1945 
    11241946toAscList :: Map k a -> [(k,a)] 
    11251947toAscList t   = foldr (\k x xs -> (k,x):xs) [] t 
    11261948 
    11271949-- | /O(n)/.  
     1950 
    11281951toDescList :: Map k a -> [(k,a)] 
    11291952toDescList t  = foldl (\xs k x -> (k,x):xs) [] t 
    11301953 
     
    11361959    fromAscList xs       == fromList xs 
    11371960    fromAscListWith f xs == fromListWith f xs 
    11381961--------------------------------------------------------------------} 
    1139 -- | /O(n)/. Build a map from an ascending list in linear time. 
    1140 -- /The precondition (input list is ascending) is not checked./ 
     1962-- | Build a map from an ascending list in linear time. 
     1963-- /The precondition (input list is ascending) is not checked./ /O(n)/. 
     1964-- 
     1965-- > fromAscList [(3,"b"), (5,"a")] 
     1966-- >   {3:="b",5:="a"} 
     1967-- > 
     1968-- > let result = fromAscList [(3,"b"), (5,"a")] 
     1969-- > result 
     1970-- >   {3:="b",5:="a"} 
     1971-- > let result = fromAscList [(3,"b"), (5,"a"), (5,"b")] 
     1972-- > result 
     1973-- >   {3:="b",5:="b"} 
     1974-- > valid result 
     1975-- >   True 
     1976-- > 
     1977-- > -- invalid map is generated if the list is not ordered 
     1978-- > let result = fromAscList [(5,"a"), (3,"b"), (5,"b")] 
     1979-- > result 
     1980-- >   {5:="a",3:="b",5:="b"} 
     1981-- > valid result 
     1982-- >   False 
     1983 
    11411984fromAscList :: Eq k => [(k,a)] -> Map k a  
    11421985fromAscList xs 
    11431986  = fromAscListWithKey (\k x y -> x) xs 
    11441987 
    1145 -- | /O(n)/. Build a map from an ascending list in linear time with a combining function for equal keys. 
    1146 -- /The precondition (input list is ascending) is not checked./ 
     1988-- | Build a map from an ascending list in linear time with a combining function for equal keys. 
     1989-- /The precondition (input list is ascending) is not checked./ /O(n)/. 
     1990-- 
     1991-- > let result = fromAscListWith (++) [(3,"b"), (5,"a"), (5,"b")] 
     1992-- > result 
     1993-- >   {3:="b",5:="ba"} 
     1994-- > valid result 
     1995-- >   True 
     1996-- > 
     1997-- > -- invalid map is generated if the list is not ordered 
     1998-- > let result = fromAscListWith (++) [(5,"a"), (3,"b"), (5,"b")] 
     1999-- > result 
     2000-- >   {5:="a",3:="b",5:="b"} 
     2001-- > valid result 
     2002-- >   False 
     2003 
    11472004fromAscListWith :: Eq k => (a -> a -> a) -> [(k,a)] -> Map k a  
    11482005fromAscListWith f xs 
    11492006  = fromAscListWithKey (\k x y -> f x y) xs 
    11502007 
    1151 -- | /O(n)/. Build a map from an ascending list in linear time with a 
     2008-- | Build a map from an ascending list in linear time with a 
    11522009-- combining function for equal keys. 
    1153 -- /The precondition (input list is ascending) is not checked./ 
     2010-- /The precondition (input list is ascending) is not checked./ /O(n)/. 
     2011-- 
     2012-- > let f k a1 a2 = (show k) ++ ":" ++ a1 ++ a2 
     2013-- > let result = fromAscListWithKey f [(3,"b"), (5,"a"), (5,"b"), (5,"b")] 
     2014-- > result 
     2015-- >   {3:="b",5:="5:b5:ba"} 
     2016-- > valid result 
     2017-- >   True 
     2018-- > 
     2019-- > -- invalid map is generated if the list is not ordered 
     2020-- > let result = fromAscListWithKey f [(5,"a"), (3,"b"), (5,"b"), (5,"b")] 
     2021-- > result 
     2022-- >   {5:="a",3:="b",5:="5:bb"} 
     2023-- > valid result 
     2024-- >   False 
     2025 
    11542026fromAscListWithKey :: Eq k => (k -> a -> a -> a) -> [(k,a)] -> Map k a  
    11552027fromAscListWithKey f xs 
    11562028  = fromDistinctAscList (combineEq f xs) 
     
    11682040    | otherwise = z:combineEq' x xs 
    11692041 
    11702042 
    1171 -- | /O(n)/. Build a map from an ascending list of distinct elements in linear time. 
    1172 -- /The precondition is not checked./ 
     2043-- | Build a map from an ascending list of distinct elements in linear time. 
     2044-- /The precondition is not checked./ /O(n)/. 
     2045-- 
     2046-- > let result = fromDistinctAscList [(3,"b"), (5,"a")] 
     2047-- > result 
     2048-- >   {3:="b",5:="a"} 
     2049-- > valid result 
     2050-- >   True 
     2051-- > 
     2052-- > -- invalid map is generated if the list had non-distinct elements 
     2053-- > let result = fromDistinctAscList [(3,"b"), (5,"a"), (5,"b")] 
     2054-- > result 
     2055-- >   {3:="b",5:="a",5:="b"} 
     2056-- > valid result 
     2057-- >   False 
     2058 
    11732059fromDistinctAscList :: [(k,a)] -> Map k a  
    11742060fromDistinctAscList xs 
    11752061  = build const (length xs) xs 
     
    12552141{-------------------------------------------------------------------- 
    12562142  Split 
    12572143--------------------------------------------------------------------} 
    1258 -- | /O(log n)/. The expression (@'split' k map@) is a pair @(map1,map2)@ where 
    1259 -- 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@. 
     2144-- | The expression (@'split' k map@) is a pair @(map1,map2)@ where 
     2145-- the keys in @map1@ are smaller than @k@ and the keys in @map2@ larger than @k@. 
     2146-- Any key equal to @k@ is found in neither @map1@ nor @map2@. 
     2147-- /O(log n)/. 
     2148-- 
     2149-- > let m = fromList [(5,"a"), (3,"b")] 
     2150-- > m 
     2151-- >   {3:="b",5:="a"} 
     2152-- > split 2 m 
     2153-- >   ({},{3:="b",5:="a"}) 
     2154-- > split 3 m 
     2155-- >   ({},{5:="a"}) 
     2156-- > split 4 m 
     2157-- >   ({3:="b"},{5:="a"}) 
     2158-- > split 5 m 
     2159-- >   ({3:="b"},{}) 
     2160-- > split 6 m 
     2161-- >   ({3:="b",5:="a"},{}) 
     2162 
    12602163split :: Ord k => k -> Map k a -> (Map k a,Map k a) 
    12612164split k Tip = (Tip,Tip) 
    12622165split k (Bin sx kx x l r) 
     
    12652168      GT -> let (lt,gt) = split k r in (join kx x l lt,gt) 
    12662169      EQ -> (l,r) 
    12672170 
    1268 -- | /O(log n)/. The expression (@'splitLookup' k map@) splits a map just 
     2171-- | The expression (@'splitLookup' k map@) splits a map just 
    12692172-- like 'split' but also returns @'lookup' k map@. 
     2173-- /O(log n)/. 
     2174-- 
     2175-- > let m = fromList [(5,"a"), (3,"b")] 
     2176-- > m 
     2177-- >   {3:="b",5:="a"} 
     2178-- > splitLookup 2 m 
     2179-- >   ({},Nothing,{3:="b",5:="a"}) 
     2180-- > splitLookup 3 m 
     2181-- >   ({},Just "b",{5:="a"}) 
     2182-- > splitLookup 4 m 
     2183-- >   ({3:="b"},Nothing,{5,"a"}) 
     2184-- > splitLookup 5 m 
     2185-- >   ({3,"b"},Just "a",{}) 
     2186-- > splitLookup 6 m 
     2187-- >   ({3:="b",5:="a"},Nothing,{}) 
     2188 
    12702189splitLookup :: Ord k => k -> Map k a -> (Map k a,Maybe a,Map k a) 
    12712190splitLookup k Tip = (Tip,Nothing,Tip) 
    12722191splitLookup k (Bin sx kx x l r) 
     
    12842203      GT -> let (lt,z,gt) = splitLookupWithKey k r in (join kx x l lt,z,gt) 
    12852204      EQ -> (l,Just (kx, x),r) 
    12862205 
    1287 -- | /O(log n)/. Performs a 'split' but also returns whether the pivot 
     2206-- | Performs a 'split' but also returns whether the pivot 
    12882207-- element was found in the original set. 
     2208-- /O(log n)/. 
    12892209splitMember :: Ord k => k -> Map k a -> (Map k a,Bool,Map k a) 
    12902210splitMember x t = let (l,m,r) = splitLookup x t in 
    12912211     (l,maybe False (const True) m,r) 
     
    13692289  | otherwise       = let ((km,m),r') = deleteFindMin r in balance km m l r' 
    13702290 
    13712291 
    1372 -- | /O(log n)/. Delete and find the minimal element. 
     2292-- | Delete and find the minimal element. /O(log n)/. 
     2293-- 
     2294-- > let m = fromList [(5,"a"), (3,"b"), (10,"c")] 
     2295-- > m 
     2296-- >   {3:="b",5:="a",10:="c"} 
     2297-- > deleteFindMin m 
     2298-- >   ((3,"b"),{5:="a",10:="c"}) 
     2299-- > deleteFindMin empty 
     2300-- >   Exception: Map.deleteFindMin: can not return the minimal element of an empty map 
     2301 
    13732302deleteFindMin :: Map k a -> ((k,a),Map k a) 
    13742303deleteFindMin t  
    13752304  = case t of 
     
    13772306      Bin _ k x l r   -> let (km,l') = deleteFindMin l in (km,balance k x l' r) 
    13782307      Tip             -> (error "Map.deleteFindMin: can not return the minimal element of an empty map", Tip) 
    13792308 
    1380 -- | /O(log n)/. Delete and find the maximal element. 
     2309-- | Delete and find the maximal element. /O(log n)/. 
     2310-- 
     2311-- > let m = fromList [(5,"a"), (3,"b"), (10,"c")] 
     2312-- > m 
     2313-- >   {3:="b",5:="a",10:="c"} 
     2314-- > deleteFindMax m 
     2315-- >   ((10,"c"),{3:="b",5:="a"}) 
     2316-- > deleteFindMax empty 
     2317-- >   Exception: Map.deleteFindMax: can not return the maximal element of an empty map 
     2318 
    13812319deleteFindMax :: Map k a -> ((k,a),Map k a) 
    13822320deleteFindMax t 
    13832321  = case t of 
     
    15312469    showElem (k,x)  = shows k . showString " := " . shows x 
    15322470   
    15332471 
    1534 -- | /O(n)/. Show the tree that implements the map. The tree is shown 
    1535 -- in a compressed, hanging format. 
     2472-- | Show the tree that implements the map. The tree is shown 
     2473-- in a compressed, hanging format. See 'showTreeWith'. /O(n)/. 
    15362474showTree :: (Show k,Show a) => Map k a -> String 
    15372475showTree m 
    15382476  = showTreeWith showElem True False m 
     
    15402478    showElem k x  = show k ++ ":=" ++ show x 
    15412479 
    15422480 
    1543 {- | /O(n)/. The expression (@'showTreeWith' showelem hang wide map@) shows 
     2481{- | The expression (@'showTreeWith' showelem hang wide map@) shows 
    15442482 the tree that implements the map. Elements are shown using the @showElem@ function. If @hang@ is 
    15452483 'True', a /hanging/ tree is shown otherwise a rotated tree is shown. If 
    1546  @wide@ is 'True', an extra wide version is shown. 
     2484 @wide@ is 'True', an extra wide version is shown. /O(n)/. 
    15472485 
    15482486>  Map> let t = fromDistinctAscList [(x,()) | x <- [1..5]] 
    15492487>  Map> putStrLn $ showTreeWith (\k x -> show (k,x)) True False t 
     
    16322570{-------------------------------------------------------------------- 
    16332571  Assertions 
    16342572--------------------------------------------------------------------} 
    1635 -- | /O(n)/. Test if the internal map structure is valid. 
     2573-- | Test if the internal map structure is valid. /O(n)/. 
     2574-- 
     2575-- > let result = fromAscList [(3,"b"), (5,"a")] 
     2576-- > result 
     2577-- >   {3:="b",5:="a"} 
     2578-- > let result = fromAscList [(3,"b"), (5,"a"), (5,"b")] 
     2579-- > result 
     2580-- >   {3:="b",5:="b"} 
     2581-- > valid result 
     2582-- >   True 
     2583-- > 
     2584-- > -- invalid map is generated if the list is not ordered 
     2585-- > let result = fromAscList [(5,"a"), (3,"b"), (5,"b")] 
     2586-- > result 
     2587-- >   {5:="a",3:="b",5:="b"} 
     2588-- > valid result 
     2589-- >   False 
     2590 
    16362591valid :: Ord k => Map k a -> Bool 
    16372592valid t 
    16382593  = balanced t && ordered t && validsize t