Ticket #1611: Map.2.diff

File Map.2.diff, 47.4 KB (added by guest, 7 years ago)
  • 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  (  
     
    9296            , mapWithKey 
    9397            , mapAccum 
    9498            , mapAccumWithKey 
    95             , mapKeys 
    96             , mapKeysWith 
    97             , mapKeysMonotonic 
     99            , mapKeys 
     100            , mapKeysWith 
     101            , mapKeysMonotonic 
    98102 
    99103            -- ** Fold 
    100104            , fold 
     
    103107            -- * Conversion 
    104108            , elems 
    105109            , keys 
    106             , keysSet 
     110            , keysSet 
    107111            , assocs 
    108112             
    109113            -- ** Lists 
     
    196200 
    197201-- | /O(log n)/. Find the value at a key. 
    198202-- Calls 'error' when the element can not be found. 
     203-- 
     204-- > fromList [(5,'a'), (3,'b')] ! 1    Error: element not in the map 
     205-- > fromList [(5,'a'), (3,'b')] ! 5 == 'a' 
     206 
    199207(!) :: Ord k => Map k a -> k -> a 
    200208m ! k    = find k m 
    201209 
    202 -- | /O(n+m)/. See 'difference'. 
     210-- | Same as 'difference'. 
    203211(\\) :: Ord k => Map k a -> Map k b -> Map k a 
    204212m1 \\ m2 = difference m1 m2 
    205213 
     
    239247  Query 
    240248--------------------------------------------------------------------} 
    241249-- | /O(1)/. Is the map empty? 
     250-- 
     251-- > Data.Map.null (empty)               == True 
     252-- > Data.Map.null (singleton 'a' 1)     == False 
     253 
    242254null :: Map k a -> Bool 
    243255null t 
    244256  = case t of 
     
    246258      Bin sz k x l r  -> False 
    247259 
    248260-- | /O(1)/. The number of elements in the map. 
     261-- 
     262-- > size empty                                     == 0 
     263-- > size (singleton 'a' 1)                         == 1 
     264-- > size (fromList([('a',1), ('c', 2), ('b', 3)])) == 3 
     265 
    249266size :: Map k a -> Int 
    250267size t 
    251268  = case t of 
     
    253270      Bin sz k x l r  -> sz 
    254271 
    255272 
    256 -- | /O(log n)/. Lookup the value at a key in the map.  
     273-- | /O(log n)/. Lookup the value at a key in the map. 
    257274-- 
    258275-- The function will  
    259276-- @return@ the result in the monad or @fail@ in it the key isn't in the  
    260277-- map. Often, the monad to use is 'Maybe', so you get either  
    261278-- @('Just' result)@ or @'Nothing'@. 
     279-- 
     280-- > let m = fromList [(5,'a'), (3,'b'), (7,'c')] 
     281-- > value1 <- Data.Map.lookup 5 m 
     282-- > value1 
     283-- >   'a' 
     284-- > value2 <- Data.Map.lookup 1 m 
     285-- >   Error: Key not found 
     286-- 
     287-- An example of using @lookup@ with @Maybe@ monad: 
     288-- 
     289-- > import Prelude hiding (lookup) 
     290-- > import Data.Map 
     291-- > 
     292-- > employeeDept = fromList([("John","Sales"), ("Bob","IT")]) 
     293-- > deptCountry = fromList([("IT","USA"), ("Sales","France")]) 
     294-- > countryCurrency = fromList([("USA", "Dollar"), ("France", "Euro")]) 
     295-- > 
     296-- > employeeCurrency :: String -> Maybe String 
     297-- > employeeCurrency name = do 
     298-- >     dept <- lookup name employeeDept 
     299-- >     country <- lookup dept deptCountry 
     300-- >     lookup country countryCurrency 
     301-- > 
     302-- > main = do 
     303-- >     putStrLn $ "John's currency: " ++ (show (employeeCurrency "John")) 
     304-- >     putStrLn $ "Pete's currency: " ++ (show (employeeCurrency "Pete")) 
     305-- 
     306-- The output of this program: 
     307-- 
     308-- >   John's currency: Just "Euro" 
     309-- >   Pete's currency: Nothing 
     310 
    262311lookup :: (Monad m,Ord k) => k -> Map k a -> m a 
    263312lookup k t = case lookup' k t of 
    264313    Just x -> return x 
     
    283332               GT -> lookupAssoc k r 
    284333               EQ -> Just (kx,x) 
    285334 
    286 -- | /O(log n)/. Is the key a member of the map? 
     335-- | /O(log n)/. Is the key a member of the map? See also 'notMember'. 
     336-- 
     337-- > member 5 (fromList [(5,'a'), (3,'b')]) == True 
     338-- > member 1 (fromList [(5,'a'), (3,'b')]) == False 
     339 
    287340member :: Ord k => k -> Map k a -> Bool 
    288341member k m 
    289342  = case lookup k m of 
    290343      Nothing -> False 
    291344      Just x  -> True 
    292345 
    293 -- | /O(log n)/. Is the key not a member of the map? 
     346-- | /O(log n)/. Is the key not a member of the map? See also 'member'. 
     347-- 
     348-- > notMember 5 (fromList [(5,'a'), (3,'b')]) == False 
     349-- > notMember 1 (fromList [(5,'a'), (3,'b')]) == True 
     350 
    294351notMember :: Ord k => k -> Map k a -> Bool 
    295352notMember k m = not $ member k m 
    296353 
     
    303360      Just x  -> x 
    304361 
    305362-- | /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. 
     363-- the value at key @k@ or returns default value @def@ 
     364-- when the key is not in the map. 
     365-- 
     366-- > findWithDefault 'x' 1 (fromList [(5,'a'), (3,'b')]) == 'x' 
     367-- > findWithDefault 'x' 5 (fromList [(5,'a'), (3,'b')]) == 'a' 
     368 
    307369findWithDefault :: Ord k => a -> k -> Map k a -> a 
    308370findWithDefault def k m 
    309371  = case lookup k m of 
     
    316378  Construction 
    317379--------------------------------------------------------------------} 
    318380-- | /O(1)/. The empty map. 
     381-- 
     382-- > empty      == fromList [] 
     383-- > size empty == 0 
     384 
    319385empty :: Map k a 
    320386empty  
    321387  = Tip 
    322388 
    323389-- | /O(1)/. A map with a single element. 
     390-- 
     391-- > singleton 1 'a'        == fromList [(1, 'a')] 
     392-- > size (singleton 1 'a') == 1 
     393 
    324394singleton :: k -> a -> Map k a 
    325395singleton k x   
    326396  = Bin 1 k x Tip Tip 
     
    330400--------------------------------------------------------------------} 
    331401-- | /O(log n)/. Insert a new key and value in the map. 
    332402-- 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 
     403-- replaced with the supplied value. 'insert' is equivalent to 
    334404-- @'insertWith' 'const'@. 
     405-- 
     406-- > insert 5 'x' (fromList [(5,'a'), (3,'b')]) == fromList [(3, 'b'), (5, 'x')] 
     407-- > insert 7 'x' (fromList [(5,'a'), (3,'b')]) == fromList [(3, 'b'), (5, 'a'), (7, 'x')] 
     408-- > insert 5 'x' empty                         == singleton 5 'x' 
     409 
    335410insert :: Ord k => k -> a -> Map k a -> Map k a 
    336411insert kx x t 
    337412  = case t of 
     
    342417               GT -> balance ky y l (insert kx x r) 
    343418               EQ -> Bin sz kx x l r 
    344419 
    345 -- | /O(log n)/. Insert with a combining function. 
     420-- | /O(log n)/. Insert with a function, combining new value and old value. 
    346421-- @'insertWith' f key value mp@  
    347422-- will insert the pair (key, value) into @mp@ if key does 
    348423-- not exist in the map. If the key does exist, the function will 
    349424-- insert the pair @(key, f new_value old_value)@. 
     425-- 
     426-- > insertWith (++) 5 "xxx" (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "xxxa")] 
     427-- > insertWith (++) 7 "xxx" (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "a"), (7, "xxx")] 
     428-- > insertWith (++) 5 "xxx" empty                         == singleton 5 "xxx" 
     429 
    350430insertWith :: Ord k => (a -> a -> a) -> k -> a -> Map k a -> Map k a 
    351431insertWith f k x m           
    352432  = insertWithKey (\k x y -> f x y) k x m 
     
    357437  = insertWithKey' (\k x y -> f x y) k x m 
    358438 
    359439 
    360 -- | /O(log n)/. Insert with a combining function. 
     440-- | /O(log n)/. Insert with a function, combining key, new value and old value. 
    361441-- @'insertWithKey' f key value mp@  
    362442-- will insert the pair (key, value) into @mp@ if key does 
    363443-- not exist in the map. If the key does exist, the function will 
    364444-- insert the pair @(key,f key new_value old_value)@. 
    365445-- Note that the key passed to f is the same key passed to 'insertWithKey'. 
     446-- 
     447-- 
     448-- > let f key new_value old_value = (show key) ++ ":" ++ new_value ++ "|" ++ old_value 
     449-- > insertWithKey f 5 "xxx" (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "5:xxx|a")] 
     450-- > insertWithKey f 7 "xxx" (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "a"), (7, "xxx")] 
     451-- > insertWithKey f 5 "xxx" empty                         == singleton 5 "xxx" 
     452 
    366453insertWithKey :: Ord k => (k -> a -> a -> a) -> k -> a -> Map k a -> Map k a 
    367454insertWithKey f kx x t 
    368455  = case t of 
     
    385472               EQ -> let x' = f kx x y in seq x' (Bin sy kx x' l r) 
    386473 
    387474 
    388 -- | /O(log n)/. The expression (@'insertLookupWithKey' f k x map@) 
     475-- | /O(log n)/. Combines insert operation with old value retrieval. 
     476-- The expression (@'insertLookupWithKey' f k x map@) 
    389477-- is a pair where the first element is equal to (@'lookup' k map@) 
    390478-- and the second element equal to (@'insertWithKey' f k x map@). 
     479-- 
     480-- > let f key new_value old_value = (show key) ++ ":" ++ new_value ++ "|" ++ old_value 
     481-- > insertLookupWithKey f 5 "xxx" (fromList [(5,"a"), (3,"b")]) == (Just "a", fromList [(3, "b"), (5, "5:xxx|a")]) 
     482-- > insertLookupWithKey f 7 "xxx" (fromList [(5,"a"), (3,"b")]) == (Nothing,  fromList [(3, "b"), (5, "a"), (7, "xxx")]) 
     483-- > insertLookupWithKey f 5 "xxx" empty                         == (Nothing,  singleton 5 "xxx") 
     484-- 
     485-- This is how to define @insertLookup@ using @insertLookupWithKey@: 
     486-- 
     487-- > let insertLookup kx x t = insertLookupWithKey (\_ a _ -> a) kx x t 
     488-- > insertLookup 5 "x" (fromList [(5,"a"), (3,"b")]) == (Just "a", fromList [(3, "b"), (5, "x")]) 
     489-- > insertLookup 7 "x" (fromList [(5,"a"), (3,"b")]) == (Nothing,  fromList [(3, "b"), (5, "a"), (7, "x")]) 
     490 
    391491insertLookupWithKey :: Ord k => (k -> a -> a -> a) -> k -> a -> Map k a -> (Maybe a,Map k a) 
    392492insertLookupWithKey f kx x t 
    393493  = case t of 
     
    404504--------------------------------------------------------------------} 
    405505-- | /O(log n)/. Delete a key and its value from the map. When the key is not 
    406506-- a member of the map, the original map is returned. 
     507-- 
     508-- > delete 5 (fromList [(5,"a"), (3,"b")]) == singleton 3 "b" 
     509-- > delete 7 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "a")] 
     510-- > delete 5 empty                         == empty 
     511 
    407512delete :: Ord k => k -> Map k a -> Map k a 
    408513delete k t 
    409514  = case t of 
     
    414519               GT -> balance kx x l (delete k r) 
    415520               EQ -> glue l r 
    416521 
    417 -- | /O(log n)/. Adjust a value at a specific key. When the key is not 
     522-- | /O(log n)/. Update a value at a specific key with the result of the provided function. 
     523-- When the key is not 
    418524-- a member of the map, the original map is returned. 
     525-- 
     526-- > adjust ("new " ++) 5 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "new a")] 
     527-- > adjust ("new " ++) 7 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "a")] 
     528-- > adjust ("new " ++) 7 empty                         == empty 
     529 
    419530adjust :: Ord k => (a -> a) -> k -> Map k a -> Map k a 
    420531adjust f k m 
    421532  = adjustWithKey (\k x -> f x) k m 
    422533 
    423534-- | /O(log n)/. Adjust a value at a specific key. When the key is not 
    424535-- a member of the map, the original map is returned. 
     536-- 
     537-- > let f key x = (show key) ++ ":new " ++ x 
     538-- > adjustWithKey f 5 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "5:new a")] 
     539-- > adjustWithKey f 7 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "a")] 
     540-- > adjustWithKey f 7 empty                         == empty 
     541 
    425542adjustWithKey :: Ord k => (k -> a -> a) -> k -> Map k a -> Map k a 
    426543adjustWithKey f k m 
    427544  = updateWithKey (\k x -> Just (f k x)) k m 
     
    429546-- | /O(log n)/. The expression (@'update' f k map@) updates the value @x@ 
    430547-- at @k@ (if it is in the map). If (@f x@) is 'Nothing', the element is 
    431548-- deleted. If it is (@'Just' y@), the key @k@ is bound to the new value @y@. 
     549-- 
     550-- > let f x = if x == "a" then Just "new a" else Nothing 
     551-- > update f 5 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "new a")] 
     552-- > update f 7 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "a")] 
     553-- > update f 3 (fromList [(5,"a"), (3,"b")]) == singleton 5 "a" 
     554 
    432555update :: Ord k => (a -> Maybe a) -> k -> Map k a -> Map k a 
    433556update f k m 
    434557  = updateWithKey (\k x -> f x) k m 
     
    437560-- value @x@ at @k@ (if it is in the map). If (@f k x@) is 'Nothing', 
    438561-- the element is deleted. If it is (@'Just' y@), the key @k@ is bound 
    439562-- to the new value @y@. 
     563-- 
     564-- > let f k x = if x == "a" then Just ((show k) ++ ":new a") else Nothing 
     565-- > updateWithKey f 5 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "5:new a")] 
     566-- > updateWithKey f 7 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "a")] 
     567-- > updateWithKey f 3 (fromList [(5,"a"), (3,"b")]) == singleton 5 "a" 
     568 
    440569updateWithKey :: Ord k => (k -> a -> Maybe a) -> k -> Map k a -> Map k a 
    441570updateWithKey f k t 
    442571  = case t of 
     
    449578                       Just x' -> Bin sx kx x' l r 
    450579                       Nothing -> glue l r 
    451580 
    452 -- | /O(log n)/. Lookup and update. 
     581-- | /O(log n)/. Lookup and update. See also 'updateWithKey'. 
     582-- The function returns changed value, if it is updated. 
     583-- Returns the original key value if the map entry is deleted.  
     584-- 
     585-- > let f k x = if x == "a" then Just ((show k) ++ ":new a") else Nothing 
     586-- > updateLookupWithKey f 5 (fromList [(5,"a"), (3,"b")]) == (Just "5:new a", fromList [(3, "b"), (5, "5:new a")]) 
     587-- > updateLookupWithKey f 7 (fromList [(5,"a"), (3,"b")]) == (Nothing,  fromList [(3, "b"), (5, "a")]) 
     588-- > updateLookupWithKey f 3 (fromList [(5,"a"), (3,"b")]) == (Just "b", singleton 5 "a") 
     589 
    453590updateLookupWithKey :: Ord k => (k -> a -> Maybe a) -> k -> Map k a -> (Maybe a,Map k a) 
    454591updateLookupWithKey f k t 
    455592  = case t of 
     
    464601 
    465602-- | /O(log n)/. The expression (@'alter' f k map@) alters the value @x@ at @k@, or absence thereof. 
    466603-- '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)@ 
     604-- In short : @'lookup' k ('alter' f k m) = f ('lookup' k m)@. 
     605-- 
     606-- > let f _ = Nothing 
     607-- > alter f 7 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "a")] 
     608-- > alter f 5 (fromList [(5,"a"), (3,"b")]) == singleton 3 "b" 
     609-- > 
     610-- > let f _ = Just "c" 
     611-- > alter f 7 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "a"), (7, "c")] 
     612-- > alter f 5 (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "c")] 
     613 
    468614alter :: Ord k => (Maybe a -> Maybe a) -> k -> Map k a -> Map k a 
    469615alter f k t 
    470616  = case t of 
     
    485631-- | /O(log n)/. Return the /index/ of a key. The index is a number from 
    486632-- /0/ up to, but not including, the 'size' of the map. Calls 'error' when 
    487633-- the key is not a 'member' of the map. 
     634-- 
     635-- > findIndex 2 (fromList [(5,"a"), (3,"b")])    Error: element is not in the map 
     636-- > findIndex 3 (fromList [(5,"a"), (3,"b")]) == 0 
     637-- > findIndex 5 (fromList [(5,"a"), (3,"b")]) == 1 
     638-- > findIndex 6 (fromList [(5,"a"), (3,"b")])    Error: element is not in the map 
     639 
    488640findIndex :: Ord k => k -> Map k a -> Int 
    489641findIndex k t 
    490642  = case lookupIndex k t of 
     
    492644      Just idx -> idx 
    493645 
    494646-- | /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.  
     647-- /0/ up to, but not including, the 'size' of the map. 
     648-- 
     649-- > isJust (lookupIndex 2 (fromList [(5,"a"), (3,"b")]))   == False 
     650-- > fromJust (lookupIndex 3 (fromList [(5,"a"), (3,"b")])) == 0 
     651-- > fromJust (lookupIndex 5 (fromList [(5,"a"), (3,"b")])) == 1 
     652-- > isJust (lookupIndex 6 (fromList [(5,"a"), (3,"b")]))   == False 
     653 
    496654lookupIndex :: (Monad m,Ord k) => k -> Map k a -> m Int 
    497655lookupIndex k t = case lookup 0 t of 
    498656    Nothing -> fail "Data.Map.lookupIndex: Key not found." 
     
    507665 
    508666-- | /O(log n)/. Retrieve an element by /index/. Calls 'error' when an 
    509667-- invalid index is used. 
     668-- 
     669-- > elemAt 0 (fromList [(5,"a"), (3,"b")]) == (3,"b") 
     670-- > elemAt 1 (fromList [(5,"a"), (3,"b")]) == (5, "a") 
     671-- > elemAt 2 (fromList [(5,"a"), (3,"b")])    Error: index out of range 
     672 
    510673elemAt :: Int -> Map k a -> (k,a) 
    511674elemAt i Tip = error "Map.elemAt: index out of range" 
    512675elemAt i (Bin _ kx x l r) 
     
    519682 
    520683-- | /O(log n)/. Update the element at /index/. Calls 'error' when an 
    521684-- invalid index is used. 
     685-- 
     686-- > updateAt (\ _ _ -> Just "x") 0    (fromList [(5,"a"), (3,"b")]) == fromList [(3, "x"), (5, "a")] 
     687-- > updateAt (\ _ _ -> Just "x") 1    (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "x")] 
     688-- > updateAt (\ _ _ -> Just "x") 2    (fromList [(5,"a"), (3,"b")])    Error: index out of range 
     689-- > updateAt (\ _ _ -> Just "x") (-1) (fromList [(5,"a"), (3,"b")])    Error: index out of range 
     690-- > updateAt (\_ _  -> Nothing)  0    (fromList [(5,"a"), (3,"b")]) == singleton 5 "a" 
     691-- > updateAt (\_ _  -> Nothing)  1    (fromList [(5,"a"), (3,"b")]) == singleton 3 "b" 
     692-- > updateAt (\_ _  -> Nothing)  2    (fromList [(5,"a"), (3,"b")])    Error: index out of range 
     693-- > updateAt (\_ _  -> Nothing)  (-1) (fromList [(5,"a"), (3,"b")])    Error: index out of range 
     694 
    522695updateAt :: (k -> a -> Maybe a) -> Int -> Map k a -> Map k a 
    523696updateAt f i Tip  = error "Map.updateAt: index out of range" 
    524697updateAt f i (Bin sx kx x l r) 
     
    533706 
    534707-- | /O(log n)/. Delete the element at /index/. 
    535708-- Defined as (@'deleteAt' i map = 'updateAt' (\k x -> 'Nothing') i map@). 
     709-- 
     710-- > deleteAt 0  (fromList [(5,"a"), (3,"b")]) == singleton 5 "a" 
     711-- > deleteAt 1  (fromList [(5,"a"), (3,"b")]) == singleton 3 "b" 
     712-- > deleteAt 2 (fromList [(5,"a"), (3,"b")])     Error: index out of range 
     713-- > deleteAt (-1) (fromList [(5,"a"), (3,"b")])  Error: index out of range 
     714 
    536715deleteAt :: Int -> Map k a -> Map k a 
    537716deleteAt i map 
    538717  = updateAt (\k x -> Nothing) i map 
     
    541720{-------------------------------------------------------------------- 
    542721  Minimal, Maximal 
    543722--------------------------------------------------------------------} 
    544 -- | /O(log n)/. The minimal key of the map. 
     723-- | /O(log n)/. The minimal key of the map. Calls 'error' is the map is empty. 
     724-- 
     725-- > findMin (fromList [(5,"a"), (3,"b")]) == (3,"b") 
     726-- > findMin empty                            Error: empty map has no minimal element 
     727 
    545728findMin :: Map k a -> (k,a) 
    546729findMin (Bin _ kx x Tip r)  = (kx,x) 
    547730findMin (Bin _ kx x l r)    = findMin l 
    548731findMin Tip                 = error "Map.findMin: empty map has no minimal element" 
    549732 
    550 -- | /O(log n)/. The maximal key of the map. 
     733-- | /O(log n)/. The maximal key of the map. Calls 'error' is the map is empty. 
     734-- 
     735-- > findMax (fromList [(5,"a"), (3,"b")]) == (5,"a") 
     736-- > findMax empty                            Error: empty map has no maximal element 
     737 
    551738findMax :: Map k a -> (k,a) 
    552739findMax (Bin _ kx x l Tip)  = (kx,x) 
    553740findMax (Bin _ kx x l r)    = findMax r 
    554741findMax Tip                 = error "Map.findMax: empty map has no maximal element" 
    555742 
    556 -- | /O(log n)/. Delete the minimal key. 
     743-- | /O(log n)/. Delete the minimal key. Returns an empty map if the map is empty. 
     744-- 
     745-- > deleteMin (fromList [(5,"a"), (3,"b"), (7,"c")]) == fromList [(5,"a"), (7,"c")] 
     746-- > deleteMin empty == empty 
     747 
    557748deleteMin :: Map k a -> Map k a 
    558749deleteMin (Bin _ kx x Tip r)  = r 
    559750deleteMin (Bin _ kx x l r)    = balance kx x (deleteMin l) r 
    560751deleteMin Tip                 = Tip 
    561752 
    562 -- | /O(log n)/. Delete the maximal key. 
     753-- | /O(log n)/. Delete the maximal key. Returns an empty map if the map is empty. 
     754-- 
     755-- > deleteMax (fromList [(5,"a"), (3,"b"), (7,"c")]) == fromList [(3,"b"), (5,"a")] 
     756-- > deleteMax empty == empty 
     757 
    563758deleteMax :: Map k a -> Map k a 
    564759deleteMax (Bin _ kx x l Tip)  = l 
    565760deleteMax (Bin _ kx x l r)    = balance kx x l (deleteMax r) 
    566761deleteMax Tip                 = Tip 
    567762 
    568763-- | /O(log n)/. Update the value at the minimal key. 
     764-- 
     765-- > updateMin (\ a -> Just ("X" ++ a)) (fromList [(5,"a"), (3,"b")]) == fromList [(3, "Xb"), (5, "a")] 
     766-- > updateMin (\ _ -> Nothing)         (fromList [(5,"a"), (3,"b")]) == singleton 5 "a" 
     767 
    569768updateMin :: (a -> Maybe a) -> Map k a -> Map k a 
    570769updateMin f m 
    571770  = updateMinWithKey (\k x -> f x) m 
    572771 
    573772-- | /O(log n)/. Update the value at the maximal key. 
     773-- 
     774-- > updateMax (\ a -> Just ("X" ++ a)) (fromList [(5,"a"), (3,"b")]) == fromList [(3, "b"), (5, "Xa")] 
     775-- > updateMax (\ _ -> Nothing)         (fromList [(5,"a"), (3,"b")]) == singleton 3 "b" 
     776 
    574777updateMax :: (a -> Maybe a) -> Map k a -> Map k a 
    575778updateMax f m 
    576779  = updateMaxWithKey (\k x -> f x) m 
    577780 
    578781 
    579782-- | /O(log n)/. Update the value at the minimal key. 
     783-- 
     784-- > updateMinWithKey (\ k a -> Just ((show k) ++ ":" ++ a)) (fromList [(5,"a"), (3,"b")]) == fromList [(3,"3:b"), (5,"a")] 
     785-- > updateMinWithKey (\ _ _ -> Nothing)                     (fromList [(5,"a"), (3,"b")]) == singleton 5 "a" 
     786 
    580787updateMinWithKey :: (k -> a -> Maybe a) -> Map k a -> Map k a 
    581788updateMinWithKey f t 
    582789  = case t of 
     
    587794      Tip                -> Tip 
    588795 
    589796-- | /O(log n)/. Update the value at the maximal key. 
     797-- 
     798-- > updateMaxWithKey (\ k a -> Just ((show k) ++ ":" ++ a)) (fromList [(5,"a"), (3,"b")]) == fromList [(3,"b"), (5,"5:a")] 
     799-- > updateMaxWithKey (\ _ _ -> Nothing)                     (fromList [(5,"a"), (3,"b")]) == singleton 3 "b" 
     800 
    590801updateMaxWithKey :: (k -> a -> Maybe a) -> Map k a -> Map k a 
    591802updateMaxWithKey f t 
    592803  = case t of 
     
    598809 
    599810-- | /O(log n)/. Retrieves the minimal (key,value) pair of the map, and the map stripped from that element 
    600811-- @fail@s (in the monad) when passed an empty map. 
     812-- 
     813-- > v <- minViewWithKey (fromList [(5,"a"), (3,"b")]) 
     814-- > v ==  ((3,"b"), singleton 5 "a") 
     815-- > minViewWithKey empty              Error: empty map 
     816 
    601817minViewWithKey :: Monad m => Map k a -> m ((k,a), Map k a) 
    602 minViewWithKey Tip = fail "Map.minView: empty map" 
     818minViewWithKey Tip = fail "Map.minViewWithKey: empty map" 
    603819minViewWithKey x = return (deleteFindMin x) 
    604820 
    605821-- | /O(log n)/. Retrieves the maximal (key,value) pair of the map, and the map stripped from that element 
    606822-- @fail@s (in the monad) when passed an empty map. 
     823-- 
     824-- > v <- maxViewWithKey (fromList [(5,"a"), (3,"b")]) 
     825-- > v == ((5,"a"), singleton 3 "b") 
     826-- > maxViewWithKey empty              Error: empty map 
     827 
    607828maxViewWithKey :: Monad m => Map k a -> m ((k,a), Map k a) 
    608 maxViewWithKey Tip = fail "Map.maxView: empty map" 
     829maxViewWithKey Tip = fail "Map.maxViewWithKey: empty map" 
    609830maxViewWithKey x = return (deleteFindMax x) 
    610831 
    611832-- | /O(log n)/. Retrieves the minimal key\'s value of the map, and the map stripped from that element 
    612833-- @fail@s (in the monad) when passed an empty map. 
     834-- 
     835-- > v <- minView (fromList [(5,"a"), (3,"b")]) 
     836-- > v == ("b", singleton 5 "a") 
     837-- > minView empty                     Error: empty map 
     838 
    613839minView :: Monad m => Map k a -> m (a, Map k a) 
    614840minView Tip = fail "Map.minView: empty map" 
    615841minView x = return (first snd $ deleteFindMin x) 
    616842 
    617843-- | /O(log n)/. Retrieves the maximal key\'s value of the map, and the map stripped from that element 
    618844-- @fail@s (in the monad) when passed an empty map. 
     845-- 
     846-- > v <- maxView (fromList [(5,"a"), (3,"b")])  
     847-- > v == ("a", singleton 3 "b") 
     848-- > maxView empty                     Error: empty map 
     849 
    619850maxView :: Monad m => Map k a -> m (a, Map k a) 
    620851maxView Tip = fail "Map.maxView: empty map" 
    621852maxView x = return (first snd $ deleteFindMax x) 
     
    629860--------------------------------------------------------------------} 
    630861-- | The union of a list of maps: 
    631862--   (@'unions' == 'Prelude.foldl' 'union' 'empty'@). 
     863-- 
     864-- > unions [(fromList [(5, "a"), (3, "b")]), (fromList [(5, "A"), (7, "C")]), (fromList [(5, "A3"), (3, "B3")])] 
     865-- >     == fromList [(3, "b"), (5, "a"), (7, "C")] 
     866-- > unions [(fromList [(5, "A3"), (3, "B3")]), (fromList [(5, "A"), (7, "C")]), (fromList [(5, "a"), (3, "b")])] 
     867-- >     == fromList [(3, "B3"), (5, "A3"), (7, "C")] 
     868 
    632869unions :: Ord k => [Map k a] -> Map k a 
    633870unions ts 
    634871  = foldlStrict union empty ts 
    635872 
    636873-- | The union of a list of maps, with a combining operation: 
    637874--   (@'unionsWith' f == 'Prelude.foldl' ('unionWith' f) 'empty'@). 
     875-- 
     876-- > unionsWith (++) [(fromList [(5, "a"), (3, "b")]), (fromList [(5, "A"), (7, "C")]), (fromList [(5, "A3"), (3, "B3")])] 
     877-- >     == fromList [(3, "bB3"), (5, "aAA3"), (7, "C")] 
     878 
    638879unionsWith :: Ord k => (a->a->a) -> [Map k a] -> Map k a 
    639880unionsWith f ts 
    640881  = foldlStrict (unionWith f) empty ts 
     
    644885-- It prefers @t1@ when duplicate keys are encountered, 
    645886-- i.e. (@'union' == 'unionWith' 'const'@). 
    646887-- The implementation uses the efficient /hedge-union/ algorithm. 
    647 -- Hedge-union is more efficient on (bigset `union` smallset) 
     888-- Hedge-union is more efficient on (bigset \``union`\` smallset). 
     889-- 
     890-- > union (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == fromList [(3, "b"), (5, "a"), (7, "C")] 
     891 
    648892union :: Ord k => Map k a -> Map k a -> Map k a 
    649893union Tip t2  = t2 
    650894union t1 Tip  = t1 
     
    681925  Union with a combining function 
    682926--------------------------------------------------------------------} 
    683927-- | /O(n+m)/. Union with a combining function. The implementation uses the efficient /hedge-union/ algorithm. 
     928-- 
     929-- > unionWith (++) (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == fromList [(3, "b"), (5, "aA"), (7, "C")] 
     930 
    684931unionWith :: Ord k => (a -> a -> a) -> Map k a -> Map k a -> Map k a 
    685932unionWith f m1 m2 
    686933  = unionWithKey (\k x y -> f x y) m1 m2 
    687934 
    688935-- | /O(n+m)/. 
    689936-- Union with a combining function. The implementation uses the efficient /hedge-union/ algorithm. 
    690 -- Hedge-union is more efficient on (bigset `union` smallset). 
     937-- Hedge-union is more efficient on (bigset \``union`\` smallset). 
     938-- 
     939-- > let f key new_value old_value = (show key) ++ ":" ++ new_value ++ "|" ++ old_value 
     940-- > unionWithKey f (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == fromList [(3, "b"), (5, "5:a|A"), (7, "C")] 
     941 
    691942unionWithKey :: Ord k => (k -> a -> a -> a) -> Map k a -> Map k a -> Map k a 
    692943unionWithKey f Tip t2  = t2 
    693944unionWithKey f t1 Tip  = t1 
     
    712963  Difference 
    713964--------------------------------------------------------------------} 
    714965-- | /O(n+m)/. Difference of two maps.  
     966-- Return elements of the first map not existing in the second map. 
    715967-- The implementation uses an efficient /hedge/ algorithm comparable with /hedge-union/. 
     968-- 
     969-- > difference (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == singleton 3 "b" 
     970 
    716971difference :: Ord k => Map k a -> Map k b -> Map k a 
    717972difference Tip t2  = Tip 
    718973difference t1 Tip  = t1 
     
    729984    cmpkx k = compare kx k    
    730985 
    731986-- | /O(n+m)/. Difference with a combining function.  
     987-- When two equal keys are 
     988-- encountered, the combining function is applied to the values of these keys. 
     989-- If it returns 'Nothing', the element is discarded (proper set difference). If 
     990-- it returns (@'Just' y@), the element is updated with a new value @y@.  
    732991-- The implementation uses an efficient /hedge/ algorithm comparable with /hedge-union/. 
     992-- 
     993-- > let f al ar = if al == "b" then Just (al ++ ":" ++ ar) else Nothing 
     994-- > differenceWith f (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (3, "B"), (7, "C")]) 
     995-- >     == singleton 3 "b:B" 
     996 
    733997differenceWith :: Ord k => (a -> b -> Maybe a) -> Map k a -> Map k b -> Map k a 
    734998differenceWith f m1 m2 
    735999  = differenceWithKey (\k x y -> f x y) m1 m2 
     
    7391003-- If it returns 'Nothing', the element is discarded (proper set difference). If 
    7401004-- it returns (@'Just' y@), the element is updated with a new value @y@.  
    7411005-- The implementation uses an efficient /hedge/ algorithm comparable with /hedge-union/. 
     1006-- 
     1007-- > let f k al ar = if al == "b" then Just ((show k) ++ ":" ++ al ++ "|" ++ ar) else Nothing 
     1008-- > differenceWithKey f (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (3, "B"), (10, "C")]) 
     1009-- >     == singleton 3 "3:b|B" 
     1010 
    7421011differenceWithKey :: Ord k => (k -> a -> b -> Maybe a) -> Map k a -> Map k b -> Map k a 
    7431012differenceWithKey f Tip t2  = Tip 
    7441013differenceWithKey f t1 Tip  = t1 
     
    7671036{-------------------------------------------------------------------- 
    7681037  Intersection 
    7691038--------------------------------------------------------------------} 
    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@). 
     1039-- | /O(n+m)/. Intersection of two maps. 
     1040-- Return data in the first map for the keys existing in both maps. 
     1041-- (@'intersection' m1 m2 == 'intersectionWith' 'const' m1 m2@). 
     1042-- 
     1043-- > intersection (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == singleton 5 "a" 
     1044 
    7721045intersection :: Ord k => Map k a -> Map k b -> Map k a 
    7731046intersection m1 m2 
    7741047  = intersectionWithKey (\k x y -> x) m1 m2 
    7751048 
    7761049-- | /O(n+m)/. Intersection with a combining function. 
     1050-- 
     1051-- > intersectionWith (++) (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == singleton 5 "aA" 
     1052 
    7771053intersectionWith :: Ord k => (a -> b -> c) -> Map k a -> Map k b -> Map k c 
    7781054intersectionWith f m1 m2 
    7791055  = intersectionWithKey (\k x y -> f x y) m1 m2 
    7801056 
    7811057-- | /O(n+m)/. Intersection with a combining function. 
    782 -- Intersection is more efficient on (bigset `intersection` smallset) 
     1058-- Intersection is more efficient on (bigset \``intersection`\` smallset). 
     1059-- 
     1060-- > let f k al ar = (show k) ++ ":" ++ al ++ "|" ++ ar 
     1061-- > intersectionWithKey f (fromList [(5, "a"), (3, "b")]) (fromList [(5, "A"), (7, "C")]) == singleton 5 "5:a|A" 
     1062 
    7831063--intersectionWithKey :: Ord k => (k -> a -> b -> c) -> Map k a -> Map k b -> Map k c 
    7841064--intersectionWithKey f Tip t = Tip 
    7851065--intersectionWithKey f t Tip = Tip 
     
    7961076--    tl            = intersectWithKey f lt l 
    7971077--    tr            = intersectWithKey f gt r 
    7981078 
    799  
    8001079intersectionWithKey :: Ord k => (k -> a -> b -> c) -> Map k a -> Map k b -> Map k c 
    8011080intersectionWithKey f Tip t = Tip 
    8021081intersectionWithKey f t Tip = Tip 
     
    8201099{-------------------------------------------------------------------- 
    8211100  Submap 
    8221101--------------------------------------------------------------------} 
    823 -- | /O(n+m)/.  
     1102-- | /O(n+m)/. 
    8241103-- This function is defined as (@'isSubmapOf' = 'isSubmapOfBy' (==)@). 
     1104-- 
    8251105isSubmapOf :: (Ord k,Eq a) => Map k a -> Map k a -> Bool 
    8261106isSubmapOf m1 m2 
    8271107  = isSubmapOfBy (==) m1 m2 
    8281108 
    829 {- | /O(n+m)/.  
     1109{- | /O(n+m)/. 
    8301110 The expression (@'isSubmapOfBy' f t1 t2@) returns 'True' if 
    8311111 all keys in @t1@ are in tree @t2@, and when @f@ returns 'True' when 
    8321112 applied to their respective values. For example, the following  
     
    8411121 > isSubmapOfBy (==) (fromList [('a',2)]) (fromList [('a',1),('b',2)]) 
    8421122 > isSubmapOfBy (<)  (fromList [('a',1)]) (fromList [('a',1),('b',2)]) 
    8431123 > isSubmapOfBy (==) (fromList [('a',1),('b',2)]) (fromList [('a',1)]) 
     1124  
     1125 
    8441126-} 
    8451127isSubmapOfBy :: Ord k => (a->b->Bool) -> Map k a -> Map k b -> Bool 
    8461128isSubmapOfBy f t1 t2 
     
    8761158  > isProperSubmapOfBy (==) (fromList [(1,1),(2,2)]) (fromList [(1,1),(2,2)]) 
    8771159  > isProperSubmapOfBy (==) (fromList [(1,1),(2,2)]) (fromList [(1,1)]) 
    8781160  > isProperSubmapOfBy (<)  (fromList [(1,1)])       (fromList [(1,1),(2,2)]) 
     1161   
     1162  
    8791163-} 
    8801164isProperSubmapOfBy :: Ord k => (a -> b -> Bool) -> Map k a -> Map k b -> Bool 
    8811165isProperSubmapOfBy f t1 t2 
     
    8851169  Filter and partition 
    8861170--------------------------------------------------------------------} 
    8871171-- | /O(n)/. Filter all values that satisfy the predicate. 
     1172-- 
     1173-- > filter (> "a") (fromList [(5,"a"), (3,"b")]) == singleton 3 "b" 
     1174-- > filter (> "x") (fromList [(5,"a"), (3,"b")]) == empty 
     1175-- > filter (< "a") (fromList [(5,"a"), (3,"b")]) == empty 
     1176 
    8881177filter :: Ord k => (a -> Bool) -> Map k a -> Map k a 
    8891178filter p m 
    8901179  = filterWithKey (\k x -> p x) m 
    8911180 
    8921181-- | /O(n)/. Filter all keys\/values that satisfy the predicate. 
     1182-- 
     1183-- > filterWithKey (\k _ -> k > 4) (fromList [(5,"a"), (3,"b")]) == singleton 5 "a" 
     1184 
    8931185filterWithKey :: Ord k => (k -> a -> Bool) -> Map k a -> Map k a 
    8941186filterWithKey p Tip = Tip 
    8951187filterWithKey p (Bin _ kx x l r) 
     
    8971189  | otherwise = merge (filterWithKey p l) (filterWithKey p r) 
    8981190 
    8991191 
    900 -- | /O(n)/. partition the map according to a predicate. The first 
     1192-- | /O(n)/. Partition the map according to a predicate. The first 
    9011193-- map contains all elements that satisfy the predicate, the second all 
    9021194-- elements that fail the predicate. See also 'split'. 
     1195-- 
     1196-- > partition (> "a") (fromList [(5,"a"), (3,"b")]) == (singleton 3 "b", singleton 5 "a") 
     1197-- > partition (< "x") (fromList [(5,"a"), (3,"b")]) == (fromList [(3, "b"), (5, "a")], empty) 
     1198-- > partition (> "x") (fromList [(5,"a"), (3,"b")]) == (empty, fromList [(3, "b"), (5, "a")]) 
     1199 
    9031200partition :: Ord k => (a -> Bool) -> Map k a -> (Map k a,Map k a) 
    9041201partition p m 
    9051202  = partitionWithKey (\k x -> p x) m 
    9061203 
    907 -- | /O(n)/. partition the map according to a predicate. The first 
     1204-- | /O(n)/. Partition the map according to a predicate. The first 
    9081205-- map contains all elements that satisfy the predicate, the second all 
    9091206-- elements that fail the predicate. See also 'split'. 
     1207-- 
     1208-- > partitionWithKey (\ k _ -> k > 3) (fromList [(5,"a"), (3,"b")]) == (singleton 5 "a", singleton 3 "b") 
     1209-- > partitionWithKey (\ k _ -> k < 7) (fromList [(5,"a"), (3,"b")]) == (fromList [(3, "b"), (5, "a")], empty) 
     1210-- > partitionWithKey (\ k _ -> k > 7) (fromList [(5,"a"), (3,"b")]) == (empty, fromList [(3, "b"), (5, "a")]) 
     1211 
    9101212partitionWithKey :: Ord k => (k -> a -> Bool) -> Map k a -> (Map k a,Map k a) 
    9111213partitionWithKey p Tip = (Tip,Tip) 
    9121214partitionWithKey p (Bin _ kx x l r) 
     
    9171219    (r1,r2) = partitionWithKey p r 
    9181220 
    9191221-- | /O(n)/. Map values and collect the 'Just' results. 
     1222-- 
     1223-- > let f x = if x == "a" then Just "new a" else Nothing 
     1224-- > mapMaybe f (fromList [(5,"a"), (3,"b")]) == singleton 5 "new a" 
     1225 
    9201226mapMaybe :: Ord k => (a -> Maybe b) -> Map k a -> Map k b 
    9211227mapMaybe f m 
    9221228  = mapMaybeWithKey (\k x -> f x) m 
    9231229 
    9241230-- | /O(n)/. Map keys\/values and collect the 'Just' results. 
     1231-- 
     1232-- > let f k _ = if k < 5 then Just ("key : " ++ (show k)) else Nothing 
     1233-- > mapMaybeWithKey f (fromList [(5,"a"), (3,"b")]) == singleton 3 "key : 3" 
     1234 
    9251235mapMaybeWithKey :: Ord k => (k -> a -> Maybe b) -> Map k a -> Map k b 
    9261236mapMaybeWithKey f Tip = Tip 
    9271237mapMaybeWithKey f (Bin _ kx x l r) = case f kx x of 
     
    9291239  Nothing -> merge (mapMaybeWithKey f l) (mapMaybeWithKey f r) 
    9301240 
    9311241-- | /O(n)/. Map values and separate the 'Left' and 'Right' results. 
     1242-- 
     1243-- > let f a = if a < "c" then Left a else Right a 
     1244-- > mapEither f (fromList [(5,"a"), (3,"b"), (1,"x"), (7,"z")]) 
     1245-- >     == (fromList [(3,"b"), (5,"a")], fromList [(1,"x"), (7,"z")]) 
     1246-- > 
     1247-- > mapEither (\ a -> Right a) (fromList [(5,"a"), (3,"b"), (1,"x"), (7,"z")]) 
     1248-- >     == (empty, fromList [(5,"a"), (3,"b"), (1,"x"), (7,"z")]) 
     1249 
    9321250mapEither :: Ord k => (a -> Either b c) -> Map k a -> (Map k b, Map k c) 
    9331251mapEither f m 
    9341252  = mapEitherWithKey (\k x -> f x) m 
    9351253 
    9361254-- | /O(n)/. Map keys\/values and separate the 'Left' and 'Right' results. 
     1255-- 
     1256-- > let f k a = if k < 5 then Left (k * 2) else Right (a ++ a) 
     1257-- > mapEitherWithKey f (fromList [(5,"a"), (3,"b"), (1,"x"), (7,"z")]) 
     1258-- >     == (fromList [(1,2), (3,6)], fromList [(5,"aa"), (7,"zz")]) 
     1259-- > 
     1260-- > mapEitherWithKey (\_ a -> Right a) (fromList [(5,"a"), (3,"b"), (1,"x"), (7,"z")]) 
     1261-- >     == (empty, fromList [(1,"x"), (3,"b"), (5,"a"), (7,"z")]) 
     1262 
    9371263mapEitherWithKey :: Ord k => 
    9381264  (k -> a -> Either b c) -> Map k a -> (Map k b, Map k c) 
    9391265mapEitherWithKey f Tip = (Tip, Tip) 
     
    9481274  Mapping 
    9491275--------------------------------------------------------------------} 
    9501276-- | /O(n)/. Map a function over all values in the map. 
     1277-- 
     1278-- > map (++ "x") (fromList [(5,"a"), (3,"b")]) == fromList [(3, "bx"), (5, "ax")] 
     1279 
    9511280map :: (a -> b) -> Map k a -> Map k b 
    9521281map f m 
    9531282  = mapWithKey (\k x -> f x) m 
    9541283 
    9551284-- | /O(n)/. Map a function over all values in the map. 
     1285-- 
     1286-- > let f key x = (show key) ++ ":" ++ x 
     1287-- > mapWithKey f (fromList [(5,"a"), (3,"b")]) == fromList [(3, "3:b"), (5, "5:a")] 
     1288 
    9561289mapWithKey :: (k -> a -> b) -> Map k a -> Map k b 
    9571290mapWithKey f Tip = Tip 
    9581291mapWithKey f (Bin sx kx x l r)  
     
    9601293 
    9611294-- | /O(n)/. The function 'mapAccum' threads an accumulating 
    9621295-- argument through the map in ascending order of keys. 
     1296-- 
     1297-- > let f a b = (a ++ b, b ++ "X") 
     1298-- > mapAccum f "Everything: " (fromList [(5,"a"), (3,"b")]) == ("Everything: ba", fromList [(3, "bX"), (5, "aX")]) 
     1299 
    9631300mapAccum :: (a -> b -> (a,c)) -> a -> Map k b -> (a,Map k c) 
    9641301mapAccum f a m 
    9651302  = mapAccumWithKey (\a k x -> f a x) a m 
    9661303 
    9671304-- | /O(n)/. The function 'mapAccumWithKey' threads an accumulating 
    9681305-- argument through the map in ascending order of keys. 
     1306-- 
     1307-- > let f a k b = (a ++ " " ++ (show k) ++ "-" ++ b, b ++ "X") 
     1308-- > mapAccumWithKey f "Everything:" (fromList [(5,"a"), (3,"b")]) == ("Everything: 3-b 5-a", fromList [(3, "bX"), (5, "aX")]) 
     1309 
    9691310mapAccumWithKey :: (a -> k -> b -> (a,c)) -> a -> Map k b -> (a,Map k c) 
    9701311mapAccumWithKey f a t 
    9711312  = mapAccumL f a t 
     
    9941335                 (a3,l') = mapAccumR f a2 l 
    9951336             in (a3,Bin sx kx x' l' r') 
    9961337 
    997 -- | /O(n*log n)/.  
     1338-- | /O(n*log n)/. 
    9981339-- @'mapKeys' f s@ is the map obtained by applying @f@ to each key of @s@. 
    9991340--  
    10001341-- The size of the result may be smaller if @f@ maps two or more distinct 
    10011342-- keys to the same new key.  In this case the value at the smallest of 
    10021343-- these keys is retained. 
     1344-- 
     1345-- > mapKeys (+ 1) (fromList [(5,"a"), (3,"b")])                        == fromList [(4, "b"), (6, "a")] 
     1346-- > mapKeys (\ _ -> 1) (fromList [(1,"b"), (2,"a"), (3,"d"), (4,"c")]) == singleton 1 "c" 
     1347-- > mapKeys (\ _ -> 3) (fromList [(1,"b"), (2,"a"), (3,"d"), (4,"c")]) == singleton 3 "c" 
    10031348 
    10041349mapKeys :: Ord k2 => (k1->k2) -> Map k1 a -> Map k2 a 
    10051350mapKeys = mapKeysWith (\x y->x) 
    10061351 
    1007 -- | /O(n*log n)/.  
     1352-- | /O(n*log n)/. 
    10081353-- @'mapKeysWith' c f s@ is the map obtained by applying @f@ to each key of @s@. 
    10091354--  
    10101355-- The size of the result may be smaller if @f@ maps two or more distinct 
    10111356-- keys to the same new key.  In this case the associated values will be 
    10121357-- combined using @c@. 
     1358-- 
     1359-- > mapKeysWith (++) (\ _ -> 1) (fromList [(1,"b"), (2,"a"), (3,"d"), (4,"c")]) == singleton 1 "cdab" 
     1360-- > mapKeysWith (++) (\ _ -> 3) (fromList [(1,"b"), (2,"a"), (3,"d"), (4,"c")]) == singleton 3 "cdab" 
    10131361 
    10141362mapKeysWith :: Ord k2 => (a -> a -> a) -> (k1->k2) -> Map k1 a -> Map k2 a 
    10151363mapKeysWith c f = fromListWith c . List.map fFirst . toList 
     
    10191367-- | /O(n)/. 
    10201368-- @'mapKeysMonotonic' f s == 'mapKeys' f s@, but works only when @f@ 
    10211369-- is strictly monotonic. 
     1370-- That is, for any values @x@ and @y@, if @x@ < @y@ then @f x@ < @f y@. 
    10221371-- /The precondition is not checked./ 
    10231372-- Semi-formally, we have: 
    10241373--  
    10251374-- > and [x < y ==> f x < f y | x <- ls, y <- ls]  
    10261375-- >                     ==> mapKeysMonotonic f s == mapKeys f s 
    10271376-- >     where ls = keys s 
     1377-- 
     1378-- This means that @f@ maps distinct original keys to distinct resulting keys. 
     1379-- This function has better performance than 'mapKeys'. 
     1380-- 
     1381-- > mapKeysMonotonic (\ k -> k * 2) (fromList [(5,"a"), (3,"b")]) == fromList [(6, "b"), (10, "a")] 
     1382-- > valid (mapKeysMonotonic (\ k -> k * 2) (fromList [(5,"a"), (3,"b")])) == True 
     1383-- > valid (mapKeysMonotonic (\ _ -> 1)     (fromList [(5,"a"), (3,"b")])) == False 
    10281384 
    10291385mapKeysMonotonic :: (k1->k2) -> Map k1 a -> Map k2 a 
    10301386mapKeysMonotonic f Tip = Tip 
     
    10411397-- 
    10421398-- > elems map = fold (:) [] map 
    10431399-- 
     1400-- > let f a len = len + (length a) 
     1401-- > fold f 0 (fromList [(5,"a"), (3,"bbb")]) == 4 
     1402 
    10441403fold :: (a -> b -> b) -> b -> Map k a -> b 
    10451404fold f z m 
    10461405  = foldWithKey (\k x z -> f x z) z m 
     
    10511410-- 
    10521411-- > keys map = foldWithKey (\k x ks -> k:ks) [] map 
    10531412-- 
     1413-- > let f k a result = result ++ "(" ++ (show k) ++ ":" ++ a ++ ")" 
     1414-- > foldWithKey f "Map: " (fromList [(5,"a"), (3,"b")]) == "Map: (5:a)(3:b)" 
     1415 
    10541416foldWithKey :: (k -> a -> b -> b) -> b -> Map k a -> b 
    10551417foldWithKey f z t 
    10561418  = foldr f z t 
     
    10751437--------------------------------------------------------------------} 
    10761438-- | /O(n)/. 
    10771439-- Return all elements of the map in the ascending order of their keys. 
     1440-- 
     1441-- > elems (fromList [(5,"a"), (3,"b")]) == ["b","a"] 
     1442-- > elems empty == [] 
     1443 
    10781444elems :: Map k a -> [a] 
    10791445elems m 
    10801446  = [x | (k,x) <- assocs m] 
    10811447 
    10821448-- | /O(n)/. Return all keys of the map in ascending order. 
     1449-- 
     1450-- > keys (fromList [(5,"a"), (3,"b")]) == [3,5] 
     1451-- > keys empty == [] 
     1452 
    10831453keys  :: Map k a -> [k] 
    10841454keys m 
    10851455  = [k | (k,x) <- assocs m] 
    10861456 
    10871457-- | /O(n)/. The set of all keys of the map. 
     1458-- 
     1459-- > keysSet (fromList [(5,"a"), (3,"b")]) == Data.Set.fromList [3,5] 
     1460-- > keysSet empty == Data.Set.empty 
     1461 
    10881462keysSet :: Map k a -> Set.Set k 
    10891463keysSet m = Set.fromDistinctAscList (keys m) 
    10901464 
    10911465-- | /O(n)/. Return all key\/value pairs in the map in ascending key order. 
     1466-- 
     1467-- > assocs (fromList [(5,"a"), (3,"b")]) == [(3,"b"), (5,"a")] 
     1468-- > assocs empty == [] 
     1469 
    10921470assocs :: Map k a -> [(k,a)] 
    10931471assocs m 
    10941472  = toList m 
     
    10981476  use [foldlStrict] to reduce demand on the control-stack 
    10991477--------------------------------------------------------------------} 
    11001478-- | /O(n*log n)/. Build a map from a list of key\/value pairs. See also 'fromAscList'. 
     1479-- If the list contains more than one value for the same key, the last value 
     1480-- for the key is retained. 
     1481-- 
     1482-- > fromList [] == empty 
     1483-- > fromList [(5,"a"), (3,"b"), (5, "c")] == fromList [(5,"c"), (3,"b")] 
     1484-- > fromList [(5,"c"), (3,"b"), (5, "a")] == fromList [(5,"a"), (3,"b")] 
     1485 
    11011486fromList :: Ord k => [(k,a)] -> Map k a  
    11021487fromList xs        
    11031488  = foldlStrict ins empty xs 
     
    11051490    ins t (k,x) = insert k x t 
    11061491 
    11071492-- | /O(n*log n)/. Build a map from a list of key\/value pairs with a combining function. See also 'fromAscListWith'. 
     1493-- 
     1494-- > fromListWith (++) [(5,"a"), (5,"b"), (3,"b"), (3,"a"), (5,"a")] == fromList [(3, "ab"), (5, "aba")] 
     1495-- > fromListWith (++) [] == empty 
     1496 
    11081497fromListWith :: Ord k => (a -> a -> a) -> [(k,a)] -> Map k a  
    11091498fromListWith f xs 
    11101499  = fromListWithKey (\k x y -> f x y) xs 
    11111500 
    11121501-- | /O(n*log n)/. Build a map from a list of key\/value pairs with a combining function. See also 'fromAscListWithKey'. 
     1502-- 
     1503-- > let f k a1 a2 = (show k) ++ a1 ++ a2 
     1504-- > fromListWithKey f [(5,"a"), (5,"b"), (3,"b"), (3,"a"), (5,"a")] == fromList [(3, "3ab"), (5, "5a5ba")] 
     1505-- > fromListWithKey f [] == empty 
     1506 
    11131507fromListWithKey :: Ord k => (k -> a -> a -> a) -> [(k,a)] -> Map k a  
    11141508fromListWithKey f xs  
    11151509  = foldlStrict ins empty xs 
     
    11171511    ins t (k,x) = insertWithKey f k x t 
    11181512 
    11191513-- | /O(n)/. Convert to a list of key\/value pairs. 
     1514-- 
     1515-- > toList (fromList [(5,"a"), (3,"b")]) == [(3,"b"), (5,"a")] 
     1516-- > toList empty == [] 
     1517 
    11201518toList :: Map k a -> [(k,a)] 
    11211519toList t      = toAscList t 
    11221520 
    11231521-- | /O(n)/. Convert to an ascending list. 
     1522-- 
     1523-- > toAscList (fromList [(5,"a"), (3,"b")]) == [(3,"b"), (5,"a")] 
     1524 
    11241525toAscList :: Map k a -> [(k,a)] 
    11251526toAscList t   = foldr (\k x xs -> (k,x):xs) [] t 
    11261527 
    1127 -- | /O(n)/.  
     1528-- | /O(n)/. 
    11281529toDescList :: Map k a -> [(k,a)] 
    11291530toDescList t  = foldl (\xs k x -> (k,x):xs) [] t 
    11301531 
     
    11381539--------------------------------------------------------------------} 
    11391540-- | /O(n)/. Build a map from an ascending list in linear time. 
    11401541-- /The precondition (input list is ascending) is not checked./ 
     1542-- 
     1543-- > fromAscList [(3,"b"), (5,"a")]          == fromList [(3, "b"), (5, "a")] 
     1544-- > fromAscList [(3,"b"), (5,"a"), (5,"b")] == fromList [(3, "b"), (5, "b")] 
     1545-- > valid (fromAscList [(3,"b"), (5,"a"), (5,"b")]) == True 
     1546-- > valid (fromAscList [(5,"a"), (3,"b"), (5,"b")]) == False 
     1547 
    11411548fromAscList :: Eq k => [(k,a)] -> Map k a  
    11421549fromAscList xs 
    11431550  = fromAscListWithKey (\k x y -> x) xs 
    11441551 
    11451552-- | /O(n)/. Build a map from an ascending list in linear time with a combining function for equal keys. 
    11461553-- /The precondition (input list is ascending) is not checked./ 
     1554-- 
     1555-- > fromAscListWith (++) [(3,"b"), (5,"a"), (5,"b")] == fromList [(3, "b"), (5, "ba")] 
     1556-- > valid (fromAscListWith (++) [(3,"b"), (5,"a"), (5,"b")]) == True 
     1557-- > valid (fromAscListWith (++) [(5,"a"), (3,"b"), (5,"b")]) == False 
     1558 
    11471559fromAscListWith :: Eq k => (a -> a -> a) -> [(k,a)] -> Map k a  
    11481560fromAscListWith f xs 
    11491561  = fromAscListWithKey (\k x y -> f x y) xs 
     
    11511563-- | /O(n)/. Build a map from an ascending list in linear time with a 
    11521564-- combining function for equal keys. 
    11531565-- /The precondition (input list is ascending) is not checked./ 
     1566-- 
     1567-- > let f k a1 a2 = (show k) ++ ":" ++ a1 ++ a2 
     1568-- > fromAscListWithKey f [(3,"b"), (5,"a"), (5,"b"), (5,"b")] == fromList [(3, "b"), (5, "5:b5:ba")] 
     1569-- > valid (fromAscListWithKey f [(3,"b"), (5,"a"), (5,"b"), (5,"b")]) == True 
     1570-- > valid (fromAscListWithKey f [(5,"a"), (3,"b"), (5,"b"), (5,"b")]) == False 
     1571 
    11541572fromAscListWithKey :: Eq k => (k -> a -> a -> a) -> [(k,a)] -> Map k a  
    11551573fromAscListWithKey f xs 
    11561574  = fromDistinctAscList (combineEq f xs) 
     
    11701588 
    11711589-- | /O(n)/. Build a map from an ascending list of distinct elements in linear time. 
    11721590-- /The precondition is not checked./ 
     1591-- 
     1592-- > fromDistinctAscList [(3,"b"), (5,"a")] == fromList [(3, "b"), (5, "a")] 
     1593-- > valid (fromDistinctAscList [(3,"b"), (5,"a")])          == True 
     1594-- > valid (fromDistinctAscList [(3,"b"), (5,"a"), (5,"b")]) == False 
     1595 
    11731596fromDistinctAscList :: [(k,a)] -> Map k a  
    11741597fromDistinctAscList xs 
    11751598  = build const (length xs) xs 
     
    12561679  Split 
    12571680--------------------------------------------------------------------} 
    12581681-- | /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@. 
     1682-- the keys in @map1@ are smaller than @k@ and the keys in @map2@ larger than @k@. 
     1683-- Any key equal to @k@ is found in neither @map1@ nor @map2@. 
     1684-- 
     1685-- > split 2 (fromList [(5,"a"), (3,"b")]) == (empty, fromList [(3,"b"), (5,"a")]) 
     1686-- > split 3 (fromList [(5,"a"), (3,"b")]) == (empty, singleton 5 "a") 
     1687-- > split 4 (fromList [(5,"a"), (3,"b")]) == (singleton 3 "b", singleton 5 "a") 
     1688-- > split 5 (fromList [(5,"a"), (3,"b")]) == (singleton 3 "b", empty) 
     1689-- > split 6 (fromList [(5,"a"), (3,"b")]) == (fromList [(3,"b"), (5,"a")], empty) 
     1690 
    12601691split :: Ord k => k -> Map k a -> (Map k a,Map k a) 
    12611692split k Tip = (Tip,Tip) 
    12621693split k (Bin sx kx x l r) 
     
    12671698 
    12681699-- | /O(log n)/. The expression (@'splitLookup' k map@) splits a map just 
    12691700-- like 'split' but also returns @'lookup' k map@. 
     1701-- 
     1702-- > splitLookup 2 (fromList [(5,"a"), (3,"b")]) == (empty, Nothing, fromList [(3,"b"), (5,"a")]) 
     1703-- > splitLookup 3 (fromList [(5,"a"), (3,"b")]) == (empty, Just "b", singleton 5 "a") 
     1704-- > splitLookup 4 (fromList [(5,"a"), (3,"b")]) == (singleton 3 "b", Nothing, singleton 5 "a") 
     1705-- > splitLookup 5 (fromList [(5,"a"), (3,"b")]) == (singleton 3 "b", Just "a", empty) 
     1706-- > splitLookup 6 (fromList [(5,"a"), (3,"b")]) == (fromList [(3,"b"), (5,"a")], Nothing, empty) 
     1707 
    12701708splitLookup :: Ord k => k -> Map k a -> (Map k a,Maybe a,Map k a) 
    12711709splitLookup k Tip = (Tip,Nothing,Tip) 
    12721710splitLookup k (Bin sx kx x l r) 
     
    13701808 
    13711809 
    13721810-- | /O(log n)/. Delete and find the minimal element. 
     1811-- 
     1812-- > deleteFindMin (fromList [(5,"a"), (3,"b"), (10,"c")]) == ((3,"b"), fromList[(5,"a"), (10,"c")])  
     1813-- > deleteFindMin                                            Error: can not return the minimal element of an empty map 
     1814 
    13731815deleteFindMin :: Map k a -> ((k,a),Map k a) 
    13741816deleteFindMin t  
    13751817  = case t of 
     
    13781820      Tip             -> (error "Map.deleteFindMin: can not return the minimal element of an empty map", Tip) 
    13791821 
    13801822-- | /O(log n)/. Delete and find the maximal element. 
     1823-- 
     1824-- > deleteFindMax (fromList [(5,"a"), (3,"b"), (10,"c")]) == ((10,"c"), fromList [(3,"b"), (5,"a")]) 
     1825-- > deleteFindMax empty                                      Error: can not return the maximal element of an empty map 
     1826 
    13811827deleteFindMax :: Map k a -> ((k,a),Map k a) 
    13821828deleteFindMax t 
    13831829  = case t of 
     
    15321978   
    15331979 
    15341980-- | /O(n)/. Show the tree that implements the map. The tree is shown 
    1535 -- in a compressed, hanging format. 
     1981-- in a compressed, hanging format. See 'showTreeWith'. 
    15361982showTree :: (Show k,Show a) => Map k a -> String 
    15371983showTree m 
    15381984  = showTreeWith showElem True False m 
     
    16332079  Assertions 
    16342080--------------------------------------------------------------------} 
    16352081-- | /O(n)/. Test if the internal map structure is valid. 
     2082-- 
     2083-- > valid (fromAscList [(3,"b"), (5,"a")]) == True 
     2084-- > valid (fromAscList [(5,"a"), (3,"b")]) == False 
     2085 
    16362086valid :: Ord k => Map k a -> Bool 
    16372087valid t 
    16382088  = balanced t && ordered t && validsize t