# Ticket #1611: Map.diff

File Map.diff, 90.8 KB (added by guest, 6 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
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
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
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
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
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
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
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
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.
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
768-- > findIndex 3 m
769-- >   0
770-- > findIndex 4 m
772-- > findIndex 5 m
773-- >   1
774-- > findIndex 6 m
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

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
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
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