Ticket #1611: Map.2.diff

File Map.2.diff, 47.4 KB (added by guest, 8 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