Ticket #1611: Map.diff

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

The diff.

  • Data/IntMap.hs

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

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