diff rN u oldsrc/Data/IntMap.hs newsrc/Data/IntMap.hs
 oldsrc/Data/IntMap.hs 20070810 13:59:45.580678603 0400
+++ newsrc/Data/IntMap.hs 20070810 13:59:46.980758391 0400
@@ 1,4 +1,4 @@
{# OPTIONS cpp fglasgowexts fnobangpatterns #}
+{TODO  enable # OPTIONS cpp fglasgowexts fnobangpatterns #}

 
 Module : Data.IntMap
@@ 30,6 +30,8 @@
 Information Coded In Alphanumeric/\", Journal of the ACM, 15(4),
 October 1968, pages 514534.

+ Operation comments contain the operation time complexity in
+ the BigO notation .
 Many operations have a worstcase complexity of /O(min(n,W))/.
 This means that the operation can become linear in the number of
 elements with a maximum of /W/  the number of bits in an 'Int'
@@ 215,13 +217,13 @@
Operators
}
  /O(min(n,W))/. Find the value at a key.
 Calls 'error' when the element can not be found.
+  Find the value at a key.
+ Calls 'error' when the element can not be found. /O(min(n,W))/.
(!) :: IntMap a > Key > a
m ! k = find' k m
  /O(n+m)/. See 'difference'.
+  See 'difference'. /O(n+m)/.
(\\) :: IntMap a > IntMap b > IntMap a
m1 \\ m2 = difference m1 m2
@@ 268,12 +270,12 @@
{
Query
}
  /O(1)/. Is the map empty?
+  Is the map empty? /O(1)/.
null :: IntMap a > Bool
null Nil = True
null other = False
  /O(n)/. Number of elements in the map.
+  Number of elements in the map. /O(n)/.
size :: IntMap a > Int
size t
= case t of
@@ 281,18 +283,18 @@
Tip k x > 1
Nil > 0
  /O(min(n,W))/. Is the key a member of the map?
+  Is the key a member of the map? /O(min(n,W))/.
member :: Key > IntMap a > Bool
member k m
= case lookup k m of
Nothing > False
Just x > True
  /O(log n)/. Is the key not a member of the map?
+  Is the key not a member of the map? /O(log n)/.
notMember :: Key > IntMap a > Bool
notMember k m = not $ member k m
  /O(min(n,W))/. Lookup the value at a key in the map.
+  Lookup the value at a key in the map. /O(min(n,W))/.
lookup :: (Monad m) => Key > IntMap a > m a
lookup k t = case lookup' k t of
Just x > return x
@@ 320,9 +322,9 @@
Just x > x
  /O(min(n,W))/. The expression @('findWithDefault' def k map)@
+  The expression @('findWithDefault' def k map)@
 returns the value at key @k@ or returns @def@ when the key is not an
 element of the map.
+ element of the map. /O(min(n,W))/.
findWithDefault :: a > Key > IntMap a > a
findWithDefault def k m
= case lookup k m of
@@ 332,12 +334,12 @@
{
Construction
}
  /O(1)/. The empty map.
+  The empty map. /O(1)/.
empty :: IntMap a
empty
= Nil
  /O(1)/. A map of one element.
+  A map of one element. /O(1)/.
singleton :: Key > a > IntMap a
singleton k x
= Tip k x
@@ 345,10 +347,10 @@
{
Insert
}
  /O(min(n,W))/. Insert a new key\/value pair in the map.
+  Insert a new key\/value pair in the map.
 If the key is already present in the map, the associated value is
 replaced with the supplied value, i.e. 'insert' is equivalent to
 @'insertWith' 'const'@.
+ @'insertWith' 'const'@. /O(min(n,W))/.
insert :: Key > a > IntMap a > IntMap a
insert k x t
= case t of
@@ 362,20 +364,20 @@
Nil > Tip k x
 rightbiased insertion, used by 'union'
  /O(min(n,W))/. Insert with a combining function.
+  Insert with a combining function.
 @'insertWith' f key value mp@
 will insert the pair (key, value) into @mp@ if key does
 not exist in the map. If the key does exist, the function will
 insert @f new_value old_value@.
+ insert @f new_value old_value@. /O(min(n,W))/.
insertWith :: (a > a > a) > Key > a > IntMap a > IntMap a
insertWith f k x t
= insertWithKey (\k x y > f x y) k x t
  /O(min(n,W))/. Insert with a combining function.
+  Insert with a combining function.
 @'insertWithKey' f key value mp@
 will insert the pair (key, value) into @mp@ if key does
 not exist in the map. If the key does exist, the function will
 insert @f key new_value old_value@.
+ insert @f key new_value old_value@. /O(min(n,W))/.
insertWithKey :: (Key > a > a > a) > Key > a > IntMap a > IntMap a
insertWithKey f k x t
= case t of
@@ 389,9 +391,9 @@
Nil > Tip k x
  /O(min(n,W))/. The expression (@'insertLookupWithKey' f k x map@)
+  The expression (@'insertLookupWithKey' f k x map@)
 is a pair where the first element is equal to (@'lookup' k map@)
 and the second element equal to (@'insertWithKey' f k x map@).
+ and the second element equal to (@'insertWithKey' f k x map@). /O(min(n,W))/.
insertLookupWithKey :: (Key > a > a > a) > Key > a > IntMap a > (Maybe a, IntMap a)
insertLookupWithKey f k x t
= case t of
@@ 409,8 +411,8 @@
Deletion
[delete] is the inlined version of [deleteWith (\k x > Nothing)]
}
  /O(min(n,W))/. Delete a key and its value from the map. When the key is not
 a member of the map, the original map is returned.
+  Delete a key and its value from the map. When the key is not
+ a member of the map, the original map is returned. /O(min(n,W))/.
delete :: Key > IntMap a > IntMap a
delete k t
= case t of
@@ 423,28 +425,30 @@
 otherwise > t
Nil > Nil
  /O(min(n,W))/. Adjust a value at a specific key. When the key is not
 a member of the map, the original map is returned.
+  Adjust a value at a specific key. When the key is not
+ a member of the map, the original map is returned. /O(min(n,W))/.
adjust :: (a > a) > Key > IntMap a > IntMap a
adjust f k m
= adjustWithKey (\k x > f x) k m
  /O(min(n,W))/. Adjust a value at a specific key. When the key is not
 a member of the map, the original map is returned.
+  Adjust a value at a specific key. When the key is not
+ a member of the map, the original map is returned. /O(min(n,W))/.
adjustWithKey :: (Key > a > a) > Key > IntMap a > IntMap a
adjustWithKey f k m
= updateWithKey (\k x > Just (f k x)) k m
  /O(min(n,W))/. The expression (@'update' f k map@) updates the value @x@
+  The expression (@'update' f k map@) updates the value @x@
 at @k@ (if it is in the map). If (@f x@) is 'Nothing', the element is
 deleted. If it is (@'Just' y@), the key @k@ is bound to the new value @y@.
+ /O(min(n,W))/.
update :: (a > Maybe a) > Key > IntMap a > IntMap a
update f k m
= updateWithKey (\k x > f x) k m
  /O(min(n,W))/. The expression (@'update' f k map@) updates the value @x@
+  The expression (@'update' f k map@) updates the value @x@
 at @k@ (if it is in the map). If (@f k x@) is 'Nothing', the element is
 deleted. If it is (@'Just' y@), the key @k@ is bound to the new value @y@.
+ /O(min(n,W))/.
updateWithKey :: (Key > a > Maybe a) > Key > IntMap a > IntMap a
updateWithKey f k t
= case t of
@@ 459,7 +463,7 @@
 otherwise > t
Nil > Nil
  /O(min(n,W))/. Lookup and update.
+  Lookup and update. /O(min(n,W))/.
updateLookupWithKey :: (Key > a > Maybe a) > Key > IntMap a > (Maybe a,IntMap a)
updateLookupWithKey f k t
= case t of
@@ 476,9 +480,9 @@
  /O(log n)/. The expression (@'alter' f k map@) alters the value @x@ at @k@, or absence thereof.
+  The expression (@'alter' f k map@) alters the value @x@ at @k@, or absence thereof.
 'alter' can be used to insert, delete, or update a value in a 'Map'.
 In short : @'lookup' k ('alter' f k m) = f ('lookup' k m)@
+ In short : @'lookup' k ('alter' f k m) = f ('lookup' k m)@. /O(log n)/.
alter f k t
= case t of
Bin p m l r
@@ 512,9 +516,9 @@
unionsWith f ts
= foldlStrict (unionWith f) empty ts
  /O(n+m)/. The (leftbiased) union of two maps.
+  The (leftbiased) union of two maps.
 It prefers the first map when duplicate keys are encountered,
 i.e. (@'union' == 'unionWith' 'const'@).
+ i.e. (@'union' == 'unionWith' 'const'@). /O(n+m)/.
union :: IntMap a > IntMap a > IntMap a
union t1@(Bin p1 m1 l1 r1) t2@(Bin p2 m2 l2 r2)
 shorter m1 m2 = union1
@@ 535,12 +539,12 @@
union Nil t = t
union t Nil = t
  /O(n+m)/. The union with a combining function.
+  The union with a combining function. /O(n+m)/.
unionWith :: (a > a > a) > IntMap a > IntMap a > IntMap a
unionWith f m1 m2
= unionWithKey (\k x y > f x y) m1 m2
  /O(n+m)/. The union with a combining function.
+  The union with a combining function. /O(n+m)/.
unionWithKey :: (Key > a > a > a) > IntMap a > IntMap a > IntMap a
unionWithKey f t1@(Bin p1 m1 l1 r1) t2@(Bin p2 m2 l2 r2)
 shorter m1 m2 = union1
@@ 564,7 +568,7 @@
{
Difference
}
  /O(n+m)/. Difference between two maps (based on keys).
+  Difference between two maps (based on keys). /O(n+m)/.
difference :: IntMap a > IntMap b > IntMap a
difference t1@(Bin p1 m1 l1 r1) t2@(Bin p2 m2 l2 r2)
 shorter m1 m2 = difference1
@@ 588,15 +592,16 @@
difference t (Tip k x) = delete k t
difference t Nil = t
  /O(n+m)/. Difference with a combining function.
+  Difference with a combining function. /O(n+m)/.
differenceWith :: (a > b > Maybe a) > IntMap a > IntMap b > IntMap a
differenceWith f m1 m2
= differenceWithKey (\k x y > f x y) m1 m2
  /O(n+m)/. Difference with a combining function. When two equal keys are
+  Difference with a combining function. When two equal keys are
 encountered, the combining function is applied to the key and both values.
 If it returns 'Nothing', the element is discarded (proper set difference).
 If it returns (@'Just' y@), the element is updated with a new value @y@.
+ /O(n+m)/.
differenceWithKey :: (Key > a > b > Maybe a) > IntMap a > IntMap b > IntMap a
differenceWithKey f t1@(Bin p1 m1 l1 r1) t2@(Bin p2 m2 l2 r2)
 shorter m1 m2 = difference1
@@ 627,7 +632,7 @@
{
Intersection
}
  /O(n+m)/. The (leftbiased) intersection of two maps (based on keys).
+  The (leftbiased) intersection of two maps (based on keys). /O(n+m)/.
intersection :: IntMap a > IntMap b > IntMap a
intersection t1@(Bin p1 m1 l1 r1) t2@(Bin p2 m2 l2 r2)
 shorter m1 m2 = intersection1
@@ 653,12 +658,12 @@
intersection Nil t = Nil
intersection t Nil = Nil
  /O(n+m)/. The intersection with a combining function.
+  The intersection with a combining function. /O(n+m)/.
intersectionWith :: (a > b > a) > IntMap a > IntMap b > IntMap a
intersectionWith f m1 m2
= intersectionWithKey (\k x y > f x y) m1 m2
  /O(n+m)/. The intersection with a combining function.
+  The intersection with a combining function. /O(n+m)/.
intersectionWithKey :: (Key > a > b > a) > IntMap a > IntMap b > IntMap a
intersectionWithKey f t1@(Bin p1 m1 l1 r1) t2@(Bin p2 m2 l2 r2)
 shorter m1 m2 = intersection1
@@ 690,7 +695,7 @@
Min\/Max
}
  /O(log n)/. Update the value at the minimal key.
+  Update the value at the minimal key. /O(log n)/.
updateMinWithKey :: (Key > a > a) > IntMap a > IntMap a
updateMinWithKey f t
= case t of
@@ 704,7 +709,7 @@
Bin p m l r > let t' = updateMinWithKeyUnsigned f r in Bin p m l t'
Tip k y > Tip k (f k y)
  /O(log n)/. Update the value at the maximal key.
+  Update the value at the maximal key. /O(log n)/.
updateMaxWithKey :: (Key > a > a) > IntMap a > IntMap a
updateMaxWithKey f t
= case t of
@@ 719,8 +724,8 @@
Tip k y > Tip k (f k y)
  /O(log n)/. Retrieves the maximal (key,value) couple of the map, and the map stripped from that element.
 @fail@s (in the monad) when passed an empty map.
+  Retrieves the maximal (key,value) couple of the map, and the map stripped from that element.
+ @fail@s (in the monad) when passed an empty map. /O(log n)/.
maxViewWithKey :: (Monad m) => IntMap a > m ((Key, a), IntMap a)
maxViewWithKey t
= case t of
@@ 734,8 +739,8 @@
Bin p m l r > let (result,t') = maxViewUnsigned r in (result,bin p m l t')
Tip k y > ((k,y), Nil)
  /O(log n)/. Retrieves the minimal (key,value) couple of the map, and the map stripped from that element.
 @fail@s (in the monad) when passed an empty map.
+  Retrieves the minimal (key,value) couple of the map, and the map stripped from that element.
+ @fail@s (in the monad) when passed an empty map. /O(log n)/.
minViewWithKey :: (Monad m) => IntMap a > m ((Key, a), IntMap a)
minViewWithKey t
= case t of
@@ 750,11 +755,11 @@
Tip k y > ((k,y),Nil)
  /O(log n)/. Update the value at the maximal key.
+  Update the value at the maximal key. /O(log n)/.
updateMax :: (a > a) > IntMap a > IntMap a
updateMax f = updateMaxWithKey (const f)
  /O(log n)/. Update the value at the minimal key.
+  Update the value at the minimal key. /O(log n)/.
updateMin :: (a > a) > IntMap a > IntMap a
updateMin f = updateMinWithKey (const f)
@@ 768,43 +773,44 @@
first f (x,y) = (f x,y)
  /O(log n)/. Retrieves the maximal key of the map, and the map stripped from that element.
 @fail@s (in the monad) when passed an empty map.
+  Retrieves the maximal key of the map, and the map stripped from that element.
+ @fail@s (in the monad) when passed an empty map. /O(log n)/.
maxView t = liftM (first snd) (maxViewWithKey t)
  /O(log n)/. Retrieves the minimal key of the map, and the map stripped from that element.
+  Retrieves the minimal key of the map, and the map stripped from that element.
 @fail@s (in the monad) when passed an empty map.
+ /O(log n)/.
minView t = liftM (first snd) (minViewWithKey t)
  /O(log n)/. Delete and find the maximal element.
+  Delete and find the maximal element. /O(log n)/.
deleteFindMax = runIdentity . maxView
  /O(log n)/. Delete and find the minimal element.
+  Delete and find the minimal element. /O(log n)/.
deleteFindMin = runIdentity . minView
  /O(log n)/. The minimal key of the map.
+  The minimal key of the map. /O(log n)/.
findMin = fst . runIdentity . minView
  /O(log n)/. The maximal key of the map.
+  The maximal key of the map. /O(log n)/.
findMax = fst . runIdentity . maxView
  /O(log n)/. Delete the minimal key.
+  Delete the minimal key. /O(log n)/.
deleteMin = snd . runIdentity . minView
  /O(log n)/. Delete the maximal key.
+  Delete the maximal key. /O(log n)/.
deleteMax = snd . runIdentity . maxView
{
Submap
}
  /O(n+m)/. Is this a proper submap? (ie. a submap but not equal).
 Defined as (@'isProperSubmapOf' = 'isProperSubmapOfBy' (==)@).
+  Is this a proper submap? (ie. a submap but not equal).
+ Defined as (@'isProperSubmapOf' = 'isProperSubmapOfBy' (==)@). /O(n+m)/.
isProperSubmapOf :: Eq a => IntMap a > IntMap a > Bool
isProperSubmapOf m1 m2
= isProperSubmapOfBy (==) m1 m2
{  /O(n+m)/. Is this a proper submap? (ie. a submap but not equal).
+{  Is this a proper submap? (ie. a submap but not equal).
The expression (@'isProperSubmapOfBy' f m1 m2@) returns 'True' when
@m1@ and @m2@ are not equal,
all keys in @m1@ are in @m2@, and when @f@ returns 'True' when
@@ 819,6 +825,8 @@
> isProperSubmapOfBy (==) (fromList [(1,1),(2,2)]) (fromList [(1,1),(2,2)])
> isProperSubmapOfBy (==) (fromList [(1,1),(2,2)]) (fromList [(1,1)])
> isProperSubmapOfBy (<) (fromList [(1,1)]) (fromList [(1,1),(2,2)])
+
+ /O(n+m)/.
}
isProperSubmapOfBy :: (a > b > Bool) > IntMap a > IntMap b > Bool
isProperSubmapOfBy pred t1 t2
@@ 852,14 +860,13 @@
submapCmp pred Nil Nil = EQ
submapCmp pred Nil t = LT
  /O(n+m)/. Is this a submap?
 Defined as (@'isSubmapOf' = 'isSubmapOfBy' (==)@).
+  Is this a submap?
+ Defined as (@'isSubmapOf' = 'isSubmapOfBy' (==)@). /O(n+m)/.
isSubmapOf :: Eq a => IntMap a > IntMap a > Bool
isSubmapOf m1 m2
= isSubmapOfBy (==) m1 m2
{  /O(n+m)/.
 The expression (@'isSubmapOfBy' f m1 m2@) returns 'True' if
+{  The expression (@'isSubmapOfBy' f m1 m2@) returns 'True' if
all keys in @m1@ are in @m2@, and when @f@ returns 'True' when
applied to their respective values. For example, the following
expressions are all 'True':
@@ 873,6 +880,8 @@
> isSubmapOfBy (==) (fromList [(1,2)]) (fromList [(1,1),(2,2)])
> isSubmapOfBy (<) (fromList [(1,1)]) (fromList [(1,1),(2,2)])
> isSubmapOfBy (==) (fromList [(1,1),(2,2)]) (fromList [(1,1)])
+
+ /O(n+m)/.
}
isSubmapOfBy :: (a > b > Bool) > IntMap a > IntMap b > Bool
@@ 890,12 +899,12 @@
{
Mapping
}
  /O(n)/. Map a function over all values in the map.
+  Map a function over all values in the map. /O(n)/.
map :: (a > b) > IntMap a > IntMap b
map f m
= mapWithKey (\k x > f x) m
  /O(n)/. Map a function over all values in the map.
+  Map a function over all values in the map. /O(n)/.
mapWithKey :: (Key > a > b) > IntMap a > IntMap b
mapWithKey f t
= case t of
@@ 903,20 +912,20 @@
Tip k x > Tip k (f k x)
Nil > Nil
  /O(n)/. The function @'mapAccum'@ threads an accumulating
 argument through the map in ascending order of keys.
+  The function @'mapAccum'@ threads an accumulating
+ argument through the map in ascending order of keys. /O(n)/.
mapAccum :: (a > b > (a,c)) > a > IntMap b > (a,IntMap c)
mapAccum f a m
= mapAccumWithKey (\a k x > f a x) a m
  /O(n)/. The function @'mapAccumWithKey'@ threads an accumulating
 argument through the map in ascending order of keys.
+  The function @'mapAccumWithKey'@ threads an accumulating
+ argument through the map in ascending order of keys. /O(n)/.
mapAccumWithKey :: (a > Key > b > (a,c)) > a > IntMap b > (a,IntMap c)
mapAccumWithKey f a t
= mapAccumL f a t
  /O(n)/. The function @'mapAccumL'@ threads an accumulating
 argument through the map in ascending order of keys.
+  The function @'mapAccumL'@ threads an accumulating
+ argument through the map in ascending order of keys. /O(n)/.
mapAccumL :: (a > Key > b > (a,c)) > a > IntMap b > (a,IntMap c)
mapAccumL f a t
= case t of
@@ 927,8 +936,8 @@
Nil > (a,Nil)
  /O(n)/. The function @'mapAccumR'@ threads an accumulating
 argument throught the map in descending order of keys.
+  The function @'mapAccumR'@ threads an accumulating
+ argument throught the map in descending order of keys. /O(n)/.
mapAccumR :: (a > Key > b > (a,c)) > a > IntMap b > (a,IntMap c)
mapAccumR f a t
= case t of
@@ 941,12 +950,12 @@
{
Filter
}
  /O(n)/. Filter all values that satisfy some predicate.
+  Filter all values that satisfy some predicate. /O(n)/.
filter :: (a > Bool) > IntMap a > IntMap a
filter p m
= filterWithKey (\k x > p x) m
  /O(n)/. Filter all keys\/values that satisfy some predicate.
+  Filter all keys\/values that satisfy some predicate. /O(n)/.
filterWithKey :: (Key > a > Bool) > IntMap a > IntMap a
filterWithKey pred t
= case t of
@@ 957,16 +966,16 @@
 otherwise > Nil
Nil > Nil
  /O(n)/. partition the map according to some predicate. The first
+  Partition the map according to some predicate. The first
 map contains all elements that satisfy the predicate, the second all
 elements that fail the predicate. See also 'split'.
+ elements that fail the predicate. See also 'split'. /O(n)/.
partition :: (a > Bool) > IntMap a > (IntMap a,IntMap a)
partition p m
= partitionWithKey (\k x > p x) m
  /O(n)/. partition the map according to some predicate. The first
+  Partition the map according to some predicate. The first
 map contains all elements that satisfy the predicate, the second all
 elements that fail the predicate. See also 'split'.
+ elements that fail the predicate. See also 'split'. /O(n)/.
partitionWithKey :: (Key > a > Bool) > IntMap a > (IntMap a,IntMap a)
partitionWithKey pred t
= case t of
@@ 979,12 +988,12 @@
 otherwise > (Nil,t)
Nil > (Nil,Nil)
  /O(n)/. Map values and collect the 'Just' results.
+  Map values and collect the 'Just' results. /O(n)/.
mapMaybe :: (a > Maybe b) > IntMap a > IntMap b
mapMaybe f m
= mapMaybeWithKey (\k x > f x) m
  /O(n)/. Map keys\/values and collect the 'Just' results.
+  Map keys\/values and collect the 'Just' results. /O(n)/.
mapMaybeWithKey :: (Key > a > Maybe b) > IntMap a > IntMap b
mapMaybeWithKey f (Bin p m l r)
= bin p m (mapMaybeWithKey f l) (mapMaybeWithKey f r)
@@ 993,12 +1002,12 @@
Nothing > Nil
mapMaybeWithKey f Nil = Nil
  /O(n)/. Map values and separate the 'Left' and 'Right' results.
+  Map values and separate the 'Left' and 'Right' results. /O(n)/.
mapEither :: (a > Either b c) > IntMap a > (IntMap b, IntMap c)
mapEither f m
= mapEitherWithKey (\k x > f x) m
  /O(n)/. Map keys\/values and separate the 'Left' and 'Right' results.
+  Map keys\/values and separate the 'Left' and 'Right' results. /O(n)/.
mapEitherWithKey :: (Key > a > Either b c) > IntMap a > (IntMap b, IntMap c)
mapEitherWithKey f (Bin p m l r)
= (bin p m l1 r1, bin p m l2 r2)
@@ 1010,9 +1019,10 @@
Right z > (Nil, Tip k z)
mapEitherWithKey f Nil = (Nil, Nil)
  /O(log n)/. The expression (@'split' k map@) is a pair @(map1,map2)@
+  The expression (@'split' k map@) is a pair @(map1,map2)@
 where all keys in @map1@ are lower than @k@ and all keys in
 @map2@ larger than @k@. Any key equal to @k@ is found in neither @map1@ nor @map2@.
+ /O(log n)/.
split :: Key > IntMap a > (IntMap a,IntMap a)
split k t
= case t of
@@ 1040,8 +1050,8 @@
 otherwise > (Nil,Nil)
Nil > (Nil,Nil)
  /O(log n)/. Performs a 'split' but also returns whether the pivot
 key was found in the original map.
+  Performs a 'split' but also returns whether the pivot
+ key was found in the original map. /O(log n)/.
splitLookup :: Key > IntMap a > (IntMap a,Maybe a,IntMap a)
splitLookup k t
= case t of
@@ 1072,22 +1082,24 @@
{
Fold
}
  /O(n)/. Fold the values in the map, such that
+  Fold the values in the map, such that
 @'fold' f z == 'Prelude.foldr' f z . 'elems'@.
 For example,

 > elems map = fold (:) [] map

+ /O(n)/.
fold :: (a > b > b) > b > IntMap a > b
fold f z t
= foldWithKey (\k x y > f x y) z t
  /O(n)/. Fold the keys and values in the map, such that
+  Fold the keys and values in the map, such that
 @'foldWithKey' f z == 'Prelude.foldr' ('uncurry' f) z . 'toAscList'@.
 For example,

 > keys map = foldWithKey (\k x ks > k:ks) [] map

+ /O(n)/.
foldWithKey :: (Key > a > b > b) > b > IntMap a > b
foldWithKey f z t
= foldr f z t
@@ 1112,23 +1124,23 @@
{
List variations
}
  /O(n)/.
 Return all elements of the map in the ascending order of their keys.
+  Return all elements of the map in the ascending order of their keys.
+ /O(n)/.
elems :: IntMap a > [a]
elems m
= foldWithKey (\k x xs > x:xs) [] m
  /O(n)/. Return all keys of the map in ascending order.
+  Return all keys of the map in ascending order. /O(n)/.
keys :: IntMap a > [Key]
keys m
= foldWithKey (\k x ks > k:ks) [] m
  /O(n*min(n,W))/. The set of all keys of the map.
+  The set of all keys of the map. /O(n*min(n,W))/.
keysSet :: IntMap a > IntSet.IntSet
keysSet m = IntSet.fromDistinctAscList (keys m)
  /O(n)/. Return all key\/value pairs in the map in ascending key order.
+  Return all key\/value pairs in the map in ascending key order. /O(n)/.
assocs :: IntMap a > [(Key,a)]
assocs m
= toList m
@@ 1137,57 +1149,61 @@
{
Lists
}
  /O(n)/. Convert the map to a list of key\/value pairs.
+  Convert the map to a list of key\/value pairs. /O(n)/.
toList :: IntMap a > [(Key,a)]
toList t
= foldWithKey (\k x xs > (k,x):xs) [] t
  /O(n)/. Convert the map to a list of key\/value pairs where the
 keys are in ascending order.
+  Convert the map to a list of key\/value pairs where the
+ keys are in ascending order. /O(n)/.
toAscList :: IntMap a > [(Key,a)]
toAscList t
=  NOTE: the following algorithm only works for bigendian trees
let (pos,neg) = span (\(k,x) > k >=0) (foldr (\k x xs > (k,x):xs) [] t) in neg ++ pos
  /O(n*min(n,W))/. Create a map from a list of key\/value pairs.
+  Create a map from a list of key\/value pairs. /O(n*min(n,W))/.
fromList :: [(Key,a)] > IntMap a
fromList xs
= foldlStrict ins empty xs
where
ins t (k,x) = insert k x t
  /O(n*min(n,W))/. Create a map from a list of key\/value pairs with a combining function. See also 'fromAscListWith'.
+  Create a map from a list of key\/value pairs with a combining function. See also 'fromAscListWith'.
+ /O(n*min(n,W))/.
fromListWith :: (a > a > a) > [(Key,a)] > IntMap a
fromListWith f xs
= fromListWithKey (\k x y > f x y) xs
  /O(n*min(n,W))/. Build a map from a list of key\/value pairs with a combining function. See also fromAscListWithKey'.
+  Build a map from a list of key\/value pairs with a combining function. See also fromAscListWithKey'.
+ /O(n*min(n,W))/.
fromListWithKey :: (Key > a > a > a) > [(Key,a)] > IntMap a
fromListWithKey f xs
= foldlStrict ins empty xs
where
ins t (k,x) = insertWithKey f k x t
  /O(n*min(n,W))/. Build a map from a list of key\/value pairs where
 the keys are in ascending order.
+  Build a map from a list of key\/value pairs where
+ the keys are in ascending order. /O(n*min(n,W))/.
fromAscList :: [(Key,a)] > IntMap a
fromAscList xs
= fromList xs
  /O(n*min(n,W))/. Build a map from a list of key\/value pairs where
+  Build a map from a list of key\/value pairs where
 the keys are in ascending order, with a combining function on equal keys.
+ /O(n*min(n,W))/.
fromAscListWith :: (a > a > a) > [(Key,a)] > IntMap a
fromAscListWith f xs
= fromListWith f xs
  /O(n*min(n,W))/. Build a map from a list of key\/value pairs where
+  Build a map from a list of key\/value pairs where
 the keys are in ascending order, with a combining function on equal keys.
+ /O(n*min(n,W))/.
fromAscListWithKey :: (Key > a > a > a) > [(Key,a)] > IntMap a
fromAscListWithKey f xs
= fromListWithKey f xs
  /O(n*min(n,W))/. Build a map from a list of key\/value pairs where
 the keys are in ascending order and all distinct.
+  Build a map from a list of key\/value pairs where
+ the keys are in ascending order and all distinct. /O(n*min(n,W))/.
fromDistinctAscList :: [(Key,a)] > IntMap a
fromDistinctAscList xs
= fromList xs
@@ 1277,17 +1293,17 @@
{
Debugging
}
  /O(n)/. Show the tree that implements the map. The tree is shown
 in a compressed, hanging format.
+  Show the tree that implements the map. The tree is shown
+ in a compressed, hanging format. /O(n)/.
showTree :: Show a => IntMap a > String
showTree s
= showTreeWith True False s
{  /O(n)/. The expression (@'showTreeWith' hang wide map@) shows
+{  The expression (@'showTreeWith' hang wide map@) shows
the tree that implements the map. If @hang@ is
'True', a /hanging/ tree is shown otherwise a rotated tree is shown. If
 @wide@ is 'True', an extra wide version is shown.
+ @wide@ is 'True', an extra wide version is shown. /O(n)/.
}
showTreeWith :: Show a => Bool > Bool > IntMap a > String
showTreeWith hang wide t
diff rN u oldsrc/Data/Map.hs newsrc/Data/Map.hs
 oldsrc/Data/Map.hs 20070810 13:59:45.588679058 0400
+++ newsrc/Data/Map.hs 20070810 13:59:46.984758618 0400
@@ 1,9 +1,10 @@
{# OPTIONS_GHC fnobangpatterns #}
+{TODO  enable # OPTIONS_GHC fnobangpatterns #}

 
 Module : Data.Map
 Copyright : (c) Daan Leijen 2002
+ (c) Andriy Palamarchuk 2007
 License : BSDstyle
 Maintainer : libraries@haskell.org
 Stability : provisional
@@ 31,6 +32,9 @@
 Note that the implementation is /leftbiased/  the elements of a
 first argument are always preferred to the second, for example in
 'union' or 'insert'.
+
+ Operation comments contain the operation time complexity in
+ the BigO notation .

module Data.Map (
@@ 194,12 +198,21 @@
}
infixl 9 !,\\ 
  /O(log n)/. Find the value at a key.
 Calls 'error' when the element can not be found.
+  Find the value at a key.
+ Calls 'error' when the element can not be found. /O(log n)/.
+
+ > let m = fromList [(5,'a'), (3,'b'), (7,'c')]
+ > m
+ > {3:='b',5:='a',7:='c'}
+ > m!1
+ > Error: element not in the map
+ > m!5
+ > 'a'
+
(!) :: Ord k => Map k a > k > a
m ! k = find k m
  /O(n+m)/. See 'difference'.
+  Same as 'difference'.
(\\) :: Ord k => Map k a > Map k b > Map k a
m1 \\ m2 = difference m1 m2
@@ 238,14 +251,32 @@
{
Query
}
  /O(1)/. Is the map empty?
+  Is the map empty? /O(1)/.
+
+ > Data.Map.null (fromList([]))
+ > True
+ > Data.Map.null (fromList([('a',1)]))
+ > False
+ > Data.Map.null (empty)
+ > True
+ > Data.Map.null (singleton 'a' 1)
+ > False
+
null :: Map k a > Bool
null t
= case t of
Tip > True
Bin sz k x l r > False
  /O(1)/. The number of elements in the map.
+  The number of elements in the map. /O(1)/.
+
+ > size empty
+ > 0
+ > size (singleton 'a' 1)
+ > 1
+ > size (fromList([('a',1), ('c', 2), ('b', 3)]))
+ > 3
+
size :: Map k a > Int
size t
= case t of
@@ 253,12 +284,46 @@
Bin sz k x l r > sz
  /O(log n)/. Lookup the value at a key in the map.
+  Lookup the value at a key in the map.

 The function will
 @return@ the result in the monad or @fail@ in it the key isn't in the
 map. Often, the monad to use is 'Maybe', so you get either
 @('Just' result)@ or @'Nothing'@.
+ @('Just' result)@ or @'Nothing'@. /O(log n)/.
+
+ > let m = fromList [(5,'a'), (3,'b'), (7,'c')]
+ > m
+ > {3:='b',5:='a',7:='c'}
+ > value1 < Data.Map.lookup 5 m
+ > value1
+ > 'a'
+ > value2 < Data.Map.lookup 1 m
+ > Error: Key not found
+
+ An example of using @lookup@ with @Maybe@ monad:
+
+ > import Prelude hiding (lookup)
+ > import Data.Map
+ >
+ > employeeDept = fromList([("John","Sales"), ("Bob","IT")])
+ > deptCountry = fromList([("IT","USA"), ("Sales","France")])
+ > countryCurrency = fromList([("USA", "Dollar"), ("France", "Euro")])
+ >
+ > employeeCurrency :: String > Maybe String
+ > employeeCurrency name = do
+ > dept < lookup name employeeDept
+ > country < lookup dept deptCountry
+ > lookup country countryCurrency
+ >
+ > main = do
+ > putStrLn $ "John's currency: " ++ (show (employeeCurrency "John"))
+ > putStrLn $ "Pete's currency: " ++ (show (employeeCurrency "Pete"))
+
+ The output of this program:
+
+ > John's currency: Just "Euro"
+ > Pete's currency: Nothing
+
lookup :: (Monad m,Ord k) => k > Map k a > m a
lookup k t = case lookup' k t of
Just x > return x
@@ 283,18 +348,36 @@
GT > lookupAssoc k r
EQ > Just (kx,x)
  /O(log n)/. Is the key a member of the map?
+  Is the key a member of the map? See also 'notMember'. /O(log n)/.
+
+ > let m = fromList [(5,'a'), (3,'b'), (7,'c')]
+ > m
+ > {3:='b',5:='a',7:='c'}
+ > member 5 m
+ > True
+ > member 1 m
+ > False
+
member :: Ord k => k > Map k a > Bool
member k m
= case lookup k m of
Nothing > False
Just x > True
  /O(log n)/. Is the key not a member of the map?
+  Is the key not a member of the map? See also 'member'. /O(log n)/.
+
+ > let m = fromList [(5,'a'), (3,'b'), (7,'c')]
+ > m
+ > {3:='b',5:='a',7:='c'}
+ > notMember 5 m
+ > False
+ > notMember 1 m
+ > True
+
notMember :: Ord k => k > Map k a > Bool
notMember k m = not $ member k m
  /O(log n)/. Find the value at a key.
+  Find the value at a key. /O(log n)/.
 Calls 'error' when the element can not be found.
find :: Ord k => k > Map k a > a
find k m
@@ 302,8 +385,19 @@
Nothing > error "Map.find: element not in the map"
Just x > x
  /O(log n)/. The expression @('findWithDefault' def k map)@ returns
 the value at key @k@ or returns @def@ when the key is not in the map.
+  The expression @('findWithDefault' def k map)@ returns
+ the value at key @k@ or returns default value @def@
+ when the key is not in the map.
+ /O(log n)/.
+
+ > let m = fromList [(5,'a'), (3,'b'), (7,'c')]
+ > m
+ > {3:='b',5:='a',7:='c'}
+ > findWithDefault '?' 1 m
+ > '?'
+ > findWithDefault '?' 5 m
+ > 'a'
+
findWithDefault :: Ord k => a > k > Map k a > a
findWithDefault def k m
= case lookup k m of
@@ 315,12 +409,24 @@
{
Construction
}
  /O(1)/. The empty map.
+  The empty map. /O(1)/.
+
+ > empty
+ > {}
+ > size empty
+ > 0
+
empty :: Map k a
empty
= Tip
  /O(1)/. A map with a single element.
+  A map with a single element. /O(1)/.
+
+ > singleton 1 'a'
+ > {1:='a'}
+ > size (singleton 1 'a')
+ > 1
+
singleton :: k > a > Map k a
singleton k x
= Bin 1 k x Tip Tip
@@ 328,10 +434,21 @@
{
Insertion
}
  /O(log n)/. Insert a new key and value in the map.
+  Insert a new key and value in the map.
 If the key is already present in the map, the associated value is
 replaced with the supplied value, i.e. 'insert' is equivalent to
 @'insertWith' 'const'@.
+ replaced with the supplied value. 'insert' is equivalent to
+ @'insertWith' 'const'@. /O(log n)/.
+
+ > let m = fromList [(5,'a'), (3,'b')]
+ > m
+ > {3:='b',5:='a'}
+ > insert 5 'x' m
+ > {3:='b',5:='x'}
+ > insert 10 'x' m
+ > {3:='b',5:='a',10:='x'}
+ > insert 5 'x' empty
+ > {5:='x'}
+
insert :: Ord k => k > a > Map k a > Map k a
insert kx x t
= case t of
@@ 342,11 +459,22 @@
GT > balance ky y l (insert kx x r)
EQ > Bin sz kx x l r
  /O(log n)/. Insert with a combining function.
+  Insert with a function, combining new value and old value.
 @'insertWith' f key value mp@
 will insert the pair (key, value) into @mp@ if key does
 not exist in the map. If the key does exist, the function will
 insert the pair @(key, f new_value old_value)@.
+ insert the pair @(key, f new_value old_value)@. /O(log n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ > insertWith (++) 5 "xxx" m
+ > {3:="b",5:="xxxa"}
+ > insertWith (++) 10 "xxx" m
+ > {3:="b",5:="a",10:="xxx"}
+ > insertWith (++) 5 "xxx" empty
+ > {5:="xxx"}
+
insertWith :: Ord k => (a > a > a) > k > a > Map k a > Map k a
insertWith f k x m
= insertWithKey (\k x y > f x y) k x m
@@ 357,12 +485,25 @@
= insertWithKey' (\k x y > f x y) k x m
  /O(log n)/. Insert with a combining function.
+  Insert with a function, combining key, new value and old value.
 @'insertWithKey' f key value mp@
 will insert the pair (key, value) into @mp@ if key does
 not exist in the map. If the key does exist, the function will
 insert the pair @(key,f key new_value old_value)@.
 Note that the key passed to f is the same key passed to 'insertWithKey'.
+ /O(log n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ > let f key new_value old_value = (show key) ++ ":" ++ new_value ++ "" ++ old_value
+ > insertWithKey f 5 "xxx" m
+ > {3:="b",5:="5:xxxa"}
+ > insertWithKey f 10 "xxx" m
+ > {3:="b",5:="a",10:="xxx"}
+ > insertWithKey f 5 "xxx" empty
+ > {5:="xxx"}
+
insertWithKey :: Ord k => (k > a > a > a) > k > a > Map k a > Map k a
insertWithKey f kx x t
= case t of
@@ 385,9 +526,33 @@
EQ > let x' = f kx x y in seq x' (Bin sy kx x' l r)
  /O(log n)/. The expression (@'insertLookupWithKey' f k x map@)
+  Combines insert operation with old value retrieval.
+ The expression (@'insertLookupWithKey' f k x map@)
 is a pair where the first element is equal to (@'lookup' k map@)
 and the second element equal to (@'insertWithKey' f k x map@).
+ and the second element equal to (@'insertWithKey' f k x map@). /O(log n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ > let f key new_value old_value = (show key) ++ ":" ++ new_value ++ "" ++ old_value
+ > insertLookupWithKey f 5 "xxx" m
+ > (Just "a",{3:="b",5:="5:xxxa"})
+ > insertLookupWithKey f 10 "xxx" m
+ > (Nothing,{3:="b",5:="a",10:="xxx"})
+ > insertLookupWithKey f 5 "xxx" empty
+ > (Nothing,{5:="xxx"})
+
+ This is how to define @insertLookup@ using @insertLookupWithKey@:
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ > let insertLookup kx x t = insertLookupWithKey (\_ a _ > a) kx x t
+ > insertLookup 5 "x" m
+ > (Just "a",{3:="b",5:="x"})
+ > insertLookup 10 "x" m
+ > (Nothing,{3:="b",5:="a",10:="x"})
+
insertLookupWithKey :: Ord k => (k > a > a > a) > k > a > Map k a > (Maybe a,Map k a)
insertLookupWithKey f kx x t
= case t of
@@ 402,8 +567,19 @@
Deletion
[delete] is the inlined version of [deleteWith (\k x > Nothing)]
}
  /O(log n)/. Delete a key and its value from the map. When the key is not
 a member of the map, the original map is returned.
+  Delete a key and its value from the map. When the key is not
+ a member of the map, the original map is returned. /O(log n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ > delete 5 m
+ > {3:="b"}
+ > delete 10 m
+ > {3:="b",5:="a"}
+ > delete 5 empty
+ > {}
+
delete :: Ord k => k > Map k a > Map k a
delete k t
= case t of
@@ 414,29 +590,90 @@
GT > balance kx x l (delete k r)
EQ > glue l r
  /O(log n)/. Adjust a value at a specific key. When the key is not
 a member of the map, the original map is returned.
+  Update a value at a specific key with the result of the provided function.
+ When the key is not
+ a member of the map, the original map is returned. /O(log n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ > adjust ("new " ++) 5 m
+ > {3:="b",5:="new a"}
+ > adjust ("new " ++) 10 m
+ > {3:="b",5:="a"}
+ > adjust ("new " ++) 10 empty
+ > {}
+
adjust :: Ord k => (a > a) > k > Map k a > Map k a
adjust f k m
= adjustWithKey (\k x > f x) k m
  /O(log n)/. Adjust a value at a specific key. When the key is not
 a member of the map, the original map is returned.
+  Adjust a value at a specific key. When the key is not
+ a member of the map, the original map is returned. /O(log n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ > let f key x = (show key) ++ ":new " ++ x
+ > adjustWithKey f 5 m
+ > {3:="b",5:="5:new a"}
+ > adjustWithKey f 10 m
+ > {3:="b",5:="a"}
+ > adjustWithKey f 10 empty
+ > {}
+
adjustWithKey :: Ord k => (k > a > a) > k > Map k a > Map k a
adjustWithKey f k m
= updateWithKey (\k x > Just (f k x)) k m
  /O(log n)/. The expression (@'update' f k map@) updates the value @x@
+  The expression (@'update' f k map@) updates the value @x@
 at @k@ (if it is in the map). If (@f x@) is 'Nothing', the element is
 deleted. If it is (@'Just' y@), the key @k@ is bound to the new value @y@.
+ /O(log n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ > let f x = if x == "a" then Just "new a" else Nothing
+ >
+ >  f "a" returns Just "new a"
+ > update f 5 m
+ > {3:="b",5:="new a"}
+ >
+ >  key does not exist
+ > update f 10 m
+ > {3:="b",5:="a"}
+ >
+ >  f "b" returns Nothing
+ > update f 3 m
+ > {5:="a"}
+
update :: Ord k => (a > Maybe a) > k > Map k a > Map k a
update f k m
= updateWithKey (\k x > f x) k m
  /O(log n)/. The expression (@'updateWithKey' f k map@) updates the
+  The expression (@'updateWithKey' f k map@) updates the
 value @x@ at @k@ (if it is in the map). If (@f k x@) is 'Nothing',
 the element is deleted. If it is (@'Just' y@), the key @k@ is bound
 to the new value @y@.
+ to the new value @y@. /O(log n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ > let f k x = if x == "a" then Just ((show k) ++ ":new a") else Nothing
+ >
+ >  f 5 "a" returns Just "5:new a"
+ > updateWithKey f 5 m
+ > {3:="b",5:="5:new a"}
+ >
+ >  key does not exist
+ > updateWithKey f 10 m
+ > {3:="b",5:="a"}
+ >
+ >  f 3 "b" returns Nothing
+ > updateWithKey f 3 m
+ > {5:="a"}
+
updateWithKey :: Ord k => (k > a > Maybe a) > k > Map k a > Map k a
updateWithKey f k t
= case t of
@@ 449,7 +686,25 @@
Just x' > Bin sx kx x' l r
Nothing > glue l r
  /O(log n)/. Lookup and update.
+  Lookup and update. See also 'updateWithKey'. /O(log n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ > let f k x = if x == "a" then Just ((show k) ++ ":new a") else Nothing
+ >
+ >  f 5 "a" returns Just "5:new a"
+ > updateLookupWithKey f 5 m
+ > (Just "5:new a",{3:="b",5:="5:new a"})
+ >
+ >  key does not exist
+ > updateLookupWithKey f 10 m
+ > (Nothing,{3:="b",5:="a"})
+ >
+ >  f 3 "b" returns Nothing
+ > updateLookupWithKey f 3 m
+ > (Just "b",{5:="a"})
+
updateLookupWithKey :: Ord k => (k > a > Maybe a) > k > Map k a > (Maybe a,Map k a)
updateLookupWithKey f k t
= case t of
@@ 462,9 +717,28 @@
Just x' > (Just x',Bin sx kx x' l r)
Nothing > (Just x,glue l r)
  /O(log n)/. The expression (@'alter' f k map@) alters the value @x@ at @k@, or absence thereof.
+  The expression (@'alter' f k map@) alters the value @x@ at @k@, or absence thereof.
 'alter' can be used to insert, delete, or update a value in a 'Map'.
 In short : @'lookup' k ('alter' f k m) = f ('lookup' k m)@
+ In short : @'lookup' k ('alter' f k m) = f ('lookup' k m)@. /O(log n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ >
+ >  always returns Nothing
+ > let f _ = Nothing
+ > alter f 10 m
+ > {3:="b",5:="a"}
+ > alter f 5 m
+ > {3:="b"}
+ >
+ >  always returns Just "c"
+ > let f _ = Just "c"
+ > alter f 10 m
+ > {3:="b",5:="a",10:="c")}
+ > alter f 5 m
+ > {3:="b",5:="c")}
+
alter :: Ord k => (Maybe a > Maybe a) > k > Map k a > Map k a
alter f k t
= case t of
@@ 482,17 +756,51 @@
{
Indexing
}
  /O(log n)/. Return the /index/ of a key. The index is a number from
+  Return the /index/ of a key. The index is a number from
 /0/ up to, but not including, the 'size' of the map. Calls 'error' when
 the key is not a 'member' of the map.
+ the key is not a 'member' of the map. /O(log n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ > findIndex 2 m
+ > Exception: Key not found.
+ > findIndex 3 m
+ > 0
+ > findIndex 4 m
+ > Exception: Key not found.
+ > findIndex 5 m
+ > 1
+ > findIndex 6 m
+ > Exception: Key not found.
+
findIndex :: Ord k => k > Map k a > Int
findIndex k t
= case lookupIndex k t of
Nothing > error "Map.findIndex: element is not in the map"
Just idx > idx
  /O(log n)/. Lookup the /index/ of a key. The index is a number from
 /0/ up to, but not including, the 'size' of the map.
+  Lookup the /index/ of a key. The index is a number from
+ /0/ up to, but not including, the 'size' of the map. /O(log n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ > isJust (lookupIndex 2 m)
+ > False
+ > isJust (lookupIndex 3 m)
+ > True
+ > fromJust (lookupIndex 3 m)
+ > 0
+ > isJust (lookupIndex 4 m)
+ > False
+ > isJust (lookupIndex 5 m)
+ > True
+ > fromJust (lookupIndex 5 m)
+ > 1
+ > isJust (lookupIndex 6 m)
+ > False
+
lookupIndex :: (Monad m,Ord k) => k > Map k a > m Int
lookupIndex k t = case lookup 0 t of
Nothing > fail "Data.Map.lookupIndex: Key not found."
@@ 505,8 +813,19 @@
GT > lookup (idx + size l + 1) r
EQ > Just (idx + size l)
  /O(log n)/. Retrieve an element by /index/. Calls 'error' when an
 invalid index is used.
+  Retrieve an element by /index/. Calls 'error' when an
+ invalid index is used. /O(log n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ > elemAt 0 m
+ > (3,"b")
+ > elemAt 1 m
+ > (5,"a")
+ > elemAt 2 m
+ > Exception: Map.elemAt: index out of range
+
elemAt :: Int > Map k a > (k,a)
elemAt i Tip = error "Map.elemAt: index out of range"
elemAt i (Bin _ kx x l r)
@@ 517,8 +836,35 @@
where
sizeL = size l
  /O(log n)/. Update the element at /index/. Calls 'error' when an
 invalid index is used.
+  Update the element at /index/. Calls 'error' when an
+ invalid index is used. /O(log n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ >
+ >  always returns Just "x"
+ > let f _ _ = Just "x"
+ > updateAt f 0 m
+ > {3:="x",5:="a"}
+ > updateAt f 1 m
+ > {3:="b",5:="x"}
+ > updateAt f 2 m
+ > Exception: Map.updateAt: index out of range
+ > updateAt f (1) m
+ > Exception: Map.updateAt: index out of range
+ >
+ >  always returns Nothing
+ > let f _ _ = Nothing
+ > updateAt f 0 m
+ > {5:="a"}
+ > updateAt f 1 m
+ > {3:="b"}
+ > updateAt f 2 m
+ > Exception: Map.updateAt: index out of range
+ > updateAt f (1) m
+ > Exception: Map.updateAt: index out of range
+
updateAt :: (k > a > Maybe a) > Int > Map k a > Map k a
updateAt f i Tip = error "Map.updateAt: index out of range"
updateAt f i (Bin sx kx x l r)
@@ 531,8 +877,22 @@
where
sizeL = size l
  /O(log n)/. Delete the element at /index/.
+  Delete the element at /index/.
 Defined as (@'deleteAt' i map = 'updateAt' (\k x > 'Nothing') i map@).
+ /O(log n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ > deleteAt 0 m
+ > {5:="a"}
+ > deleteAt 1 m
+ > {3:="b"}
+ > deleteAt 2 m
+ > Exception: Map.updateAt: index out of range
+ > deleteAt (1) m
+ > Exception: Map.updateAt: index out of range
+
deleteAt :: Int > Map k a > Map k a
deleteAt i map
= updateAt (\k x > Nothing) i map
@@ 541,42 +901,105 @@
{
Minimal, Maximal
}
  /O(log n)/. The minimal key of the map.
+  The minimal key of the map. /O(log n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ > findMin m
+ > (3,"b")
+ > findMin empty
+ > Exception: Map.findMin: empty map has no minimal element
+
findMin :: Map k a > (k,a)
findMin (Bin _ kx x Tip r) = (kx,x)
findMin (Bin _ kx x l r) = findMin l
findMin Tip = error "Map.findMin: empty map has no minimal element"
  /O(log n)/. The maximal key of the map.
+  The maximal key of the map. /O(log n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ > findMax m
+ > (5,"a")
+ > findMax empty
+ > Exception: Map.findMax: empty map has no maximal element
+
findMax :: Map k a > (k,a)
findMax (Bin _ kx x l Tip) = (kx,x)
findMax (Bin _ kx x l r) = findMax r
findMax Tip = error "Map.findMax: empty map has no maximal element"
  /O(log n)/. Delete the minimal key.
+  Delete the minimal key. /O(log n)/.
+
+ > let m = fromList [(5,"a"), (3,"b"), (10,"c")]
+ > m
+ > {3:="b",5:="a",10:="c"}
+ > deleteMin m
+ > {5:="a",10:="c"}
+ > deleteMin empty
+ > {}
+
deleteMin :: Map k a > Map k a
deleteMin (Bin _ kx x Tip r) = r
deleteMin (Bin _ kx x l r) = balance kx x (deleteMin l) r
deleteMin Tip = Tip
  /O(log n)/. Delete the maximal key.
+  Delete the maximal key. /O(log n)/.
+
+ > let m = fromList [(5,"a"), (3,"b"), (10,"c")]
+ > m
+ > {3:="b",5:="a",10:="c"}
+ > deleteMax m
+ > {3:="b",5:="a"}
+ > deleteMax empty
+ > {}
+
deleteMax :: Map k a > Map k a
deleteMax (Bin _ kx x l Tip) = l
deleteMax (Bin _ kx x l r) = balance kx x l (deleteMax r)
deleteMax Tip = Tip
  /O(log n)/. Update the value at the minimal key.
+  Update the value at the minimal key. /O(log n)/.
+
+ > let m = fromList [(5,"a"), (3,"b"), (10,"c")]
+ > m
+ > {3:="b",5:="a",10:="c"}
+ > updateMin (\ a > Just ("X" ++ a)) m
+ > {3:="Xb",5:="a",10:="c"}
+ > updateMin (\ _ > Nothing) m
+ > {5:="a",10:="c"}
+
updateMin :: (a > Maybe a) > Map k a > Map k a
updateMin f m
= updateMinWithKey (\k x > f x) m
  /O(log n)/. Update the value at the maximal key.
+  Update the value at the maximal key. /O(log n)/.
+
+ > let m = fromList [(5,"a"), (3,"b"), (10,"c")]
+ > m
+ > {3:="b",5:="a",10:="c"}
+ > updateMax (\ a > Just ("X" ++ a)) m
+ > {3:="b",5:="a",10:="Xc"}
+ > updateMax (\ _ > Nothing) m
+ > {3:="b",5,"a"}
+
updateMax :: (a > Maybe a) > Map k a > Map k a
updateMax f m
= updateMaxWithKey (\k x > f x) m
  /O(log n)/. Update the value at the minimal key.
+  Update the value at the minimal key. /O(log n)/.
+
+ > let m = fromList [(5,"a"), (3,"b"), (10,"c")]
+ > m
+ > {3:="b",5:="a",10:="c"}
+ > updateMinWithKey (\ k a > Just ((show k) ++ ":" ++ a)) m
+ > {3:="3:b",5:="a",10:="c"}
+ > updateMinWithKey (\ _ _ > Nothing) m
+ > {5:="a",10:="c"}
+
updateMinWithKey :: (k > a > Maybe a) > Map k a > Map k a
updateMinWithKey f t
= case t of
@@ 586,7 +1009,16 @@
Bin sx kx x l r > balance kx x (updateMinWithKey f l) r
Tip > Tip
  /O(log n)/. Update the value at the maximal key.
+  Update the value at the maximal key. /O(log n)/.
+
+ > let m = fromList [(5,"a"), (3,"b"), (10,"c")]
+ > m
+ > {3:="b",5:="a",10:="c"}
+ > updateMaxWithKey (\ k a > Just ((show k) ++ ":" ++ a)) m
+ > {3:="b",5:="a",10:="10:c"}
+ > updateMaxWithKey (\ _ _ > Nothing) m
+ > {3:="b",5:="a"}
+
updateMaxWithKey :: (k > a > Maybe a) > Map k a > Map k a
updateMaxWithKey f t
= case t of
@@ 596,26 +1028,63 @@
Bin sx kx x l r > balance kx x l (updateMaxWithKey f r)
Tip > Tip
  /O(log n)/. Retrieves the minimal (key,value) pair of the map, and the map stripped from that element
+  Retrieves the minimal (key,value) pair of the map, and the map stripped from that element
 @fail@s (in the monad) when passed an empty map.
+ /O(log n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ > minViewWithKey m
+ > ((3,"b"), {5:="a"})
+ > minViewWithKey empty
+ > Exception: user error (Map.minViewWithKey: empty map)
+
minViewWithKey :: Monad m => Map k a > m ((k,a), Map k a)
minViewWithKey Tip = fail "Map.minView: empty map"
+minViewWithKey Tip = fail "Map.minViewWithKey: empty map"
minViewWithKey x = return (deleteFindMin x)
  /O(log n)/. Retrieves the maximal (key,value) pair of the map, and the map stripped from that element
 @fail@s (in the monad) when passed an empty map.
+  Retrieves the maximal (key,value) pair of the map, and the map stripped from that element
+ @fail@s (in the monad) when passed an empty map. /O(log n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ > maxViewWithKey m
+ > ((5,"a"), {3:="b"})
+ > maxViewWithKey empty
+ > Exception: user error (Map.maxViewWithKey: empty map)
+
maxViewWithKey :: Monad m => Map k a > m ((k,a), Map k a)
maxViewWithKey Tip = fail "Map.maxView: empty map"
+maxViewWithKey Tip = fail "Map.maxViewWithKey: empty map"
maxViewWithKey x = return (deleteFindMax x)
  /O(log n)/. Retrieves the minimal key\'s value of the map, and the map stripped from that element
 @fail@s (in the monad) when passed an empty map.
+  Retrieves the minimal key\'s value of the map, and the map stripped from that element
+ @fail@s (in the monad) when passed an empty map. /O(log n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ > minView m
+ > ("b", {5:="a"})
+ > minView empty
+ > Exception: user error (Map.minView: empty map)
+
minView :: Monad m => Map k a > m (a, Map k a)
minView Tip = fail "Map.minView: empty map"
minView x = return (first snd $ deleteFindMin x)
  /O(log n)/. Retrieves the maximal key\'s value of the map, and the map stripped from that element
 @fail@s (in the monad) when passed an empty map.
+  Retrieves the maximal key\'s value of the map, and the map stripped from that element
+ @fail@s (in the monad) when passed an empty map. /O(log n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ > maxView m
+ > ("a", {3:="b"})
+ > maxView empty
+ > Exception: user error (Map.maxView: empty map)
+
maxView :: Monad m => Map k a > m (a, Map k a)
maxView Tip = fail "Map.maxView: empty map"
maxView x = return (first snd $ deleteFindMax x)
@@ 629,22 +1098,43 @@
}
  The union of a list of maps:
 (@'unions' == 'Prelude.foldl' 'union' 'empty'@).
+
+ > let map1 = fromList [(5, "a"), (3, "b")]
+ > let map2 = fromList [(5, "A"), (10, "C")]
+ > let map3 = fromList [(5, "A3"), (3, "B3")]
+ > unions [map1, map2, map3]
+ > {3:="b",5:="a",10:="C"}
+ > unions [map3, map2, map1]
+ > {3:="B3",5:="A3",10:="C"}
+
unions :: Ord k => [Map k a] > Map k a
unions ts
= foldlStrict union empty ts
  The union of a list of maps, with a combining operation:
 (@'unionsWith' f == 'Prelude.foldl' ('unionWith' f) 'empty'@).
+
+ > let map1 = fromList [(5, "a"), (3, "b")]
+ > let map2 = fromList [(5, "A"), (10, "C")]
+ > let map3 = fromList [(5, "A3"), (3, "B3")]
+ > unionsWith (++) [map1, map2, map3]
+ > {3:="bB3",5:="aAA3",10:="C"}
+
unionsWith :: Ord k => (a>a>a) > [Map k a] > Map k a
unionsWith f ts
= foldlStrict (unionWith f) empty ts
  /O(n+m)/.
 The expression (@'union' t1 t2@) takes the leftbiased union of @t1@ and @t2@.
+  The expression (@'union' t1 t2@) takes the leftbiased union of @t1@ and @t2@.
 It prefers @t1@ when duplicate keys are encountered,
 i.e. (@'union' == 'unionWith' 'const'@).
 The implementation uses the efficient /hedgeunion/ algorithm.
 Hedgeunion is more efficient on (bigset `union` smallset)
+ Hedgeunion is more efficient on (bigset \``union`\` smallset). /O(n+m)/.
+
+ > let map1 = fromList [(5, "a"), (3, "b")]
+ > let map2 = fromList [(5, "A"), (10, "C")]
+ > union map1 map2
+ > {3:="b",5:="a",10:="C"}
+
union :: Ord k => Map k a > Map k a > Map k a
union Tip t2 = t2
union t1 Tip = t1
@@ 680,14 +1170,28 @@
{
Union with a combining function
}
  /O(n+m)/. Union with a combining function. The implementation uses the efficient /hedgeunion/ algorithm.
+  Union with a combining function. The implementation uses the efficient /hedgeunion/ algorithm.
+ /O(n+m)/.
+
+ > let map1 = fromList [(5, "a"), (3, "b")]
+ > let map2 = fromList [(5, "A"), (10, "C")]
+ > unionWith (++) map1 map2
+ > {3:="b",5:="aA",10:="C"}
+
unionWith :: Ord k => (a > a > a) > Map k a > Map k a > Map k a
unionWith f m1 m2
= unionWithKey (\k x y > f x y) m1 m2
  /O(n+m)/.
 Union with a combining function. The implementation uses the efficient /hedgeunion/ algorithm.
 Hedgeunion is more efficient on (bigset `union` smallset).
+  Union with a combining function. The implementation uses the efficient /hedgeunion/ algorithm.
+ Hedgeunion is more efficient on (bigset \``union`\` smallset).
+ /O(n+m)/.
+
+ > let map1 = fromList [(5, "a"), (3, "b")]
+ > let map2 = fromList [(5, "A"), (10, "C")]
+ > let f key new_value old_value = (show key) ++ ":" ++ new_value ++ "" ++ old_value
+ > unionWithKey f map1 map2
+ > {3:="b",5:="5:aA",10:="C"}
+
unionWithKey :: Ord k => (k > a > a > a) > Map k a > Map k a > Map k a
unionWithKey f Tip t2 = t2
unionWithKey f t1 Tip = t1
@@ 711,8 +1215,16 @@
{
Difference
}
  /O(n+m)/. Difference of two maps.
+  Difference of two maps.
+ Return elements of the first map not existing in the second map.
 The implementation uses an efficient /hedge/ algorithm comparable with /hedgeunion/.
+ /O(n+m)/.
+
+ > let map1 = fromList [(5, "a"), (3, "b")]
+ > let map2 = fromList [(5, "A"), (10, "C")]
+ > difference map1 map2
+ > {3:="b"}
+
difference :: Ord k => Map k a > Map k b > Map k a
difference Tip t2 = Tip
difference t1 Tip = t1
@@ 728,17 +1240,51 @@
where
cmpkx k = compare kx k
  /O(n+m)/. Difference with a combining function.
+  Difference with a combining function.
+ When two equal keys are
+ encountered, the combining function is applied to the values of these keys.
+ If it returns 'Nothing', the element is discarded (proper set difference). If
+ it returns (@'Just' y@), the element is updated with a new value @y@.
 The implementation uses an efficient /hedge/ algorithm comparable with /hedgeunion/.
+ /O(n+m)/.
+
+ >  3 and 5 are common keys
+ > let map1 = fromList [(5, "a"), (3, "b")]
+ > let map2 = fromList [(5, "A"), (3, "B"), (10, "C")]
+ > map1
+ > {3:="b",5:="a"}
+ > map2
+ > {3:="B",5:="A",10:="C"}
+ > let f al ar = if al == "b" then Just (al ++ ":" ++ ar) else Nothing
+ >
+ >  f returns Nothing for 5, Just "b:B" for 3
+ > differenceWith f map1 map2
+ > {3:="b:B"}
+
differenceWith :: Ord k => (a > b > Maybe a) > Map k a > Map k b > Map k a
differenceWith f m1 m2
= differenceWithKey (\k x y > f x y) m1 m2
  /O(n+m)/. Difference with a combining function. When two equal keys are
+  Difference with a combining function. When two equal keys are
 encountered, the combining function is applied to the key and both values.
 If it returns 'Nothing', the element is discarded (proper set difference). If
 it returns (@'Just' y@), the element is updated with a new value @y@.
 The implementation uses an efficient /hedge/ algorithm comparable with /hedgeunion/.
+ /O(n+m)/.
+
+ >  3 and 5 are common keys
+ > let map1 = fromList [(5, "a"), (3, "b")]
+ > let map2 = fromList [(5, "A"), (3, "B"), (10, "C")]
+ > map1
+ > {3:="b",5:="a"}
+ > map2
+ > {3:="B",5:="A",10:="C"}
+ > let f k al ar = if al == "b" then Just ((show k) ++ ":" ++ al ++ "" ++ ar) else Nothing
+ >
+ >  f returns Nothing for 5, Just "3:bB" for 3
+ > differenceWithKey f map1 map2
+ > {3:="3:bB"}
+
differenceWithKey :: Ord k => (k > a > b > Maybe a) > Map k a > Map k b > Map k a
differenceWithKey f Tip t2 = Tip
differenceWithKey f t1 Tip = t1
@@ 767,19 +1313,41 @@
{
Intersection
}
  /O(n+m)/. Intersection of two maps. The values in the first
 map are returned, i.e. (@'intersection' m1 m2 == 'intersectionWith' 'const' m1 m2@).
+  Intersection of two maps.
+ Return data in the first map for the keys existing in both maps.
+ (@'intersection' m1 m2 == 'intersectionWith' 'const' m1 m2@).
+ /O(n+m)/.
+
+ > let map1 = fromList [(5, "a"), (3, "b")]
+ > let map2 = fromList [(5, "A"), (10, "C")]
+ > intersection map1 map2
+ > {5:="a"}
+
intersection :: Ord k => Map k a > Map k b > Map k a
intersection m1 m2
= intersectionWithKey (\k x y > x) m1 m2
  /O(n+m)/. Intersection with a combining function.
+  Intersection with a combining function.
+ /O(n+m)/.
+
+ > let map1 = fromList [(5, "a"), (3, "b")]
+ > let map2 = fromList [(5, "A"), (10, "C")]
+ > intersectionWith (++) map1 map2
+ > {5:="aA"}
+
intersectionWith :: Ord k => (a > b > c) > Map k a > Map k b > Map k c
intersectionWith f m1 m2
= intersectionWithKey (\k x y > f x y) m1 m2
  /O(n+m)/. Intersection with a combining function.
 Intersection is more efficient on (bigset `intersection` smallset)
+  Intersection with a combining function.
+ Intersection is more efficient on (bigset \``intersection`\` smallset). /O(n+m)/.
+
+ > let map1 = fromList [(5, "a"), (3, "b")]
+ > let map2 = fromList [(5, "A"), (10, "C")]
+ > let f k al ar = (show k) ++ ":" ++ al ++ "" ++ ar
+ > intersectionWithKey f map1 map2
+ > {5:="5:aA"}
+
intersectionWithKey :: Ord k => (k > a > b > c) > Map k a > Map k b > Map k c
intersectionWithKey f Tip t = Tip
intersectionWithKey f t Tip = Tip
@@ 796,7 +1364,6 @@
 tl = intersectWithKey f lt l
 tr = intersectWithKey f gt r

intersectionWithKey :: Ord k => (k > a > b > c) > Map k a > Map k b > Map k c
intersectionWithKey f Tip t = Tip
intersectionWithKey f t Tip = Tip
@@ 820,14 +1387,13 @@
{
Submap
}
  /O(n+m)/.
 This function is defined as (@'isSubmapOf' = 'isSubmapOfBy' (==)@).
+  This function is defined as (@'isSubmapOf' = 'isSubmapOfBy' (==)@).
+ /O(n+m)/.
isSubmapOf :: (Ord k,Eq a) => Map k a > Map k a > Bool
isSubmapOf m1 m2
= isSubmapOfBy (==) m1 m2
{  /O(n+m)/.
 The expression (@'isSubmapOfBy' f t1 t2@) returns 'True' if
+{  The expression (@'isSubmapOfBy' f t1 t2@) returns 'True' if
all keys in @t1@ are in tree @t2@, and when @f@ returns 'True' when
applied to their respective values. For example, the following
expressions are all 'True':
@@ 841,6 +1407,8 @@
> isSubmapOfBy (==) (fromList [('a',2)]) (fromList [('a',1),('b',2)])
> isSubmapOfBy (<) (fromList [('a',1)]) (fromList [('a',1),('b',2)])
> isSubmapOfBy (==) (fromList [('a',1),('b',2)]) (fromList [('a',1)])
+
+ /O(n+m)/.
}
isSubmapOfBy :: Ord k => (a>b>Bool) > Map k a > Map k b > Bool
isSubmapOfBy f t1 t2
@@ 855,13 +1423,13 @@
where
(lt,found,gt) = splitLookup kx t
  /O(n+m)/. Is this a proper submap? (ie. a submap but not equal).
 Defined as (@'isProperSubmapOf' = 'isProperSubmapOfBy' (==)@).
+  Is this a proper submap? (ie. a submap but not equal).
+ Defined as (@'isProperSubmapOf' = 'isProperSubmapOfBy' (==)@). /O(n+m)/.
isProperSubmapOf :: (Ord k,Eq a) => Map k a > Map k a > Bool
isProperSubmapOf m1 m2
= isProperSubmapOfBy (==) m1 m2
{  /O(n+m)/. Is this a proper submap? (ie. a submap but not equal).
+{  Is this a proper submap? (ie. a submap but not equal).
The expression (@'isProperSubmapOfBy' f m1 m2@) returns 'True' when
@m1@ and @m2@ are not equal,
all keys in @m1@ are in @m2@, and when @f@ returns 'True' when
@@ 876,6 +1444,8 @@
> isProperSubmapOfBy (==) (fromList [(1,1),(2,2)]) (fromList [(1,1),(2,2)])
> isProperSubmapOfBy (==) (fromList [(1,1),(2,2)]) (fromList [(1,1)])
> isProperSubmapOfBy (<) (fromList [(1,1)]) (fromList [(1,1),(2,2)])
+
+ /O(n+m)/.
}
isProperSubmapOfBy :: Ord k => (a > b > Bool) > Map k a > Map k b > Bool
isProperSubmapOfBy f t1 t2
@@ 884,12 +1454,31 @@
{
Filter and partition
}
  /O(n)/. Filter all values that satisfy the predicate.
+  Filter all values that satisfy the predicate. /O(n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ > filter (> "a") m
+ > {3:="b"}
+ > filter (> "x") m
+ > {}
+ > filter (< "a") m
+ > {}
+
filter :: Ord k => (a > Bool) > Map k a > Map k a
filter p m
= filterWithKey (\k x > p x) m
  /O(n)/. Filter all keys\/values that satisfy the predicate.
+  Filter all keys\/values that satisfy the predicate. /O(n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ > let f k a = k > 4
+ > filterWithKey f m
+ > {5:="a"}
+
filterWithKey :: Ord k => (k > a > Bool) > Map k a > Map k a
filterWithKey p Tip = Tip
filterWithKey p (Bin _ kx x l r)
@@ 897,16 +1486,39 @@
 otherwise = merge (filterWithKey p l) (filterWithKey p r)
  /O(n)/. partition the map according to a predicate. The first
+  Partition the map according to a predicate. The first
 map contains all elements that satisfy the predicate, the second all
 elements that fail the predicate. See also 'split'.
+ /O(n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ > partition (> "a") m
+ > ({3:="b"},{5:="a"})
+ > partition (< "x") m
+ > ({3:="b",5:="a"},{})
+ > partition (> "x") m
+ > ({},{3:="b",5:="a"})
+
partition :: Ord k => (a > Bool) > Map k a > (Map k a,Map k a)
partition p m
= partitionWithKey (\k x > p x) m
  /O(n)/. partition the map according to a predicate. The first
+  Partition the map according to a predicate. The first
 map contains all elements that satisfy the predicate, the second all
 elements that fail the predicate. See also 'split'.
+ elements that fail the predicate. See also 'split'. /O(n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ > partitionWithKey (\ k _ > k > 3) m
+ > ({5:="a"},{3:="b"})
+ > partitionWithKey (\ k _ > k < 10) m
+ > ({3:="b",5:="a"},{})
+ > partitionWithKey (\ k _ > k > 10) m
+ > ({},{3:="b",5:="a"})
+
partitionWithKey :: Ord k => (k > a > Bool) > Map k a > (Map k a,Map k a)
partitionWithKey p Tip = (Tip,Tip)
partitionWithKey p (Bin _ kx x l r)
@@ 916,24 +1528,64 @@
(l1,l2) = partitionWithKey p l
(r1,r2) = partitionWithKey p r
  /O(n)/. Map values and collect the 'Just' results.
+  Map values and collect the 'Just' results. /O(n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ > let f x = if x == "a" then Just "new a" else Nothing
+ > mapMaybe f m
+ > {5:="new a"}
+
mapMaybe :: Ord k => (a > Maybe b) > Map k a > Map k b
mapMaybe f m
= mapMaybeWithKey (\k x > f x) m
  /O(n)/. Map keys\/values and collect the 'Just' results.
+  Map keys\/values and collect the 'Just' results. /O(n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ > let f k _ = if k < 5 then Just ("key : " ++ (show k)) else Nothing
+ > mapMaybeWithKey f m
+ > {3,"key : 3"}
+
mapMaybeWithKey :: Ord k => (k > a > Maybe b) > Map k a > Map k b
mapMaybeWithKey f Tip = Tip
mapMaybeWithKey f (Bin _ kx x l r) = case f kx x of
Just y > join kx y (mapMaybeWithKey f l) (mapMaybeWithKey f r)
Nothing > merge (mapMaybeWithKey f l) (mapMaybeWithKey f r)
  /O(n)/. Map values and separate the 'Left' and 'Right' results.
+  Map values and separate the 'Left' and 'Right' results. /O(n)/.
+
+ > let m = fromList [(5,"a"), (3,"b"), (1, "x"), (10, "z")]
+ > m
+ > {1:="x",3:="b",5:="a",10:="z"}
+ > let f a = if a < "c" then Left a else Right a
+ > mapEither f m
+ > ({3:="b",5:="a"},{1:="x",10:="z"})
+ >
+ > let f a = Right a
+ > mapEither f m
+ > ({},{1:="x",3:="b",5:="a",10:="z"})
+
mapEither :: Ord k => (a > Either b c) > Map k a > (Map k b, Map k c)
mapEither f m
= mapEitherWithKey (\k x > f x) m
  /O(n)/. Map keys\/values and separate the 'Left' and 'Right' results.
+  Map keys\/values and separate the 'Left' and 'Right' results. /O(n)/.
+
+ > let m = fromList [(5,"a"), (3,"b"), (1, "x"), (10, "z")]
+ > m
+ > {1:="x",3:="b",5:="a",10:="z"}
+ > let f k a = if k < 5 then Left k else Right a
+ > mapEitherWithKey f m
+ > ({1:=2,3:=6},{5:="a",10:="z"})
+ >
+ > let f _ a = Right a
+ > mapEitherWithKey f m
+ > ({},{1:="x",3:="b",5:="a",10:="z"})
+
mapEitherWithKey :: Ord k =>
(k > a > Either b c) > Map k a > (Map k b, Map k c)
mapEitherWithKey f Tip = (Tip, Tip)
@@ 947,31 +1599,62 @@
{
Mapping
}
  /O(n)/. Map a function over all values in the map.
+  Map a function over all values in the map. /O(n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ > map (++ "x") m
+ > {3:="bx",5:="ax"}
+
map :: (a > b) > Map k a > Map k b
map f m
= mapWithKey (\k x > f x) m
  /O(n)/. Map a function over all values in the map.
+  Map a function over all values in the map. /O(n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ > let f key x = (show key) ++ ":" ++ x
+ > mapWithKey f m
+ > {3:="3:b",5:="5:a"}
+
mapWithKey :: (k > a > b) > Map k a > Map k b
mapWithKey f Tip = Tip
mapWithKey f (Bin sx kx x l r)
= Bin sx kx (f kx x) (mapWithKey f l) (mapWithKey f r)
  /O(n)/. The function 'mapAccum' threads an accumulating
 argument through the map in ascending order of keys.
+  The function 'mapAccum' threads an accumulating
+ argument through the map in ascending order of keys. /O(n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ > let f a b = (a ++ b, b ++ "X")
+ > mapAccum f "Everything: " m
+ > ("Everything: ba",{3:="bX",5:="aX"})
+
mapAccum :: (a > b > (a,c)) > a > Map k b > (a,Map k c)
mapAccum f a m
= mapAccumWithKey (\a k x > f a x) a m
  /O(n)/. The function 'mapAccumWithKey' threads an accumulating
 argument through the map in ascending order of keys.
+  The function 'mapAccumWithKey' threads an accumulating
+ argument through the map in ascending order of keys. /O(n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ > let f a k b = (a ++ " " ++ (show k) ++ "" ++ b, b ++ "X")
+ > mapAccumWithKey f "Everything:" m
+ > ("Everything: 3b 5a",{3:="bX",5:="aX"})
+
mapAccumWithKey :: (a > k > b > (a,c)) > a > Map k b > (a,Map k c)
mapAccumWithKey f a t
= mapAccumL f a t
  /O(n)/. The function 'mapAccumL' threads an accumulating
 argument throught the map in ascending order of keys.
+  The function 'mapAccumL' threads an accumulating
+ argument throught the map in ascending order of keys. /O(n)/.
mapAccumL :: (a > k > b > (a,c)) > a > Map k b > (a,Map k c)
mapAccumL f a t
= case t of
@@ 982,8 +1665,8 @@
(a3,r') = mapAccumL f a2 r
in (a3,Bin sx kx x' l' r')
  /O(n)/. The function 'mapAccumR' threads an accumulating
 argument throught the map in descending order of keys.
+  The function 'mapAccumR' threads an accumulating
+ argument throught the map in descending order of keys. /O(n)/.
mapAccumR :: (a > k > b > (a,c)) > a > Map k b > (a,Map k c)
mapAccumR f a t
= case t of
@@ 994,37 +1677,77 @@
(a3,l') = mapAccumR f a2 l
in (a3,Bin sx kx x' l' r')
  /O(n*log n)/.
 @'mapKeys' f s@ is the map obtained by applying @f@ to each key of @s@.
+  @'mapKeys' f s@ is the map obtained by applying @f@ to each key of @s@.

 The size of the result may be smaller if @f@ maps two or more distinct
 keys to the same new key. In this case the value at the smallest of
 these keys is retained.
+ these keys is retained. /O(n*log n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ > mapKeys (+ 1) m
+ > {4:="b",6:="a"}
+ >
+ >  overlapping resulting keys
+ > let m = fromList [(1,"b"), (2,"a"), (3,"d"), (4,"c")]
+ > m
+ > {1:="b",2:="a",3:="d",4:="c"}
+ > mapKeys (\ _ > 1) m
+ > {1:="c"}
+ > mapKeys (\ _ > 3) m
+ > {3:="c"}
mapKeys :: Ord k2 => (k1>k2) > Map k1 a > Map k2 a
mapKeys = mapKeysWith (\x y>x)
  /O(n*log n)/.
 @'mapKeysWith' c f s@ is the map obtained by applying @f@ to each key of @s@.
+  @'mapKeysWith' c f s@ is the map obtained by applying @f@ to each key of @s@.

 The size of the result may be smaller if @f@ maps two or more distinct
 keys to the same new key. In this case the associated values will be
 combined using @c@.
+ combined using @c@. /O(n*log n)/.
+
+ > let m = fromList [(1,"b"), (2,"a"), (3,"d"), (4,"c")]
+ > m
+ > {1:="b",2:="a",3:="d",4:="c"}
+ > mapKeysWith (++) (\ _ > 1) m
+ > {1:="cdab"}
+ > mapKeysWith (++) (\ _ > 3) m
+ > {3:="cdab"}
mapKeysWith :: Ord k2 => (a > a > a) > (k1>k2) > Map k1 a > Map k2 a
mapKeysWith c f = fromListWith c . List.map fFirst . toList
where fFirst (x,y) = (f x, y)
  /O(n)/.
 @'mapKeysMonotonic' f s == 'mapKeys' f s@, but works only when @f@
+  @'mapKeysMonotonic' f s == 'mapKeys' f s@, but works only when @f@
 is strictly monotonic.
+ That is, for any values @x@ and @y@, if @x@ < @y@ then @f x@ < @f y@.
 /The precondition is not checked./
 Semiformally, we have:

 > and [x < y ==> f x < f y  x < ls, y < ls]
 > ==> mapKeysMonotonic f s == mapKeys f s
 > where ls = keys s
+
+ This means that @f@ maps distinct original keys to distinct resulting keys.
+ This function has better performance than 'mapKeys'. /O(n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ > let result = mapKeysMonotonic (\ k > k * 2) m
+ > result
+ > {6:="b",10:="a"}
+ > valid result
+ > True
+ >
+ >  resulting map is invalid if the function is nonmonotonic
+ > let result = mapKeysMonotonic (\ _ > 1) m
+ > result
+ > {1:="b",1:="a"}
+ > valid result
+ > False
mapKeysMonotonic :: (k1>k2) > Map k1 a > Map k2 a
mapKeysMonotonic f Tip = Tip
@@ 1035,37 +1758,57 @@
Folds
}
  /O(n)/. Fold the values in the map, such that
+  Fold the values in the map, such that
 @'fold' f z == 'Prelude.foldr' f z . 'elems'@.
 For example,

 > elems map = fold (:) [] map

+ /O(n)/.
+
+ > let m = fromList [(5,"a"), (3,"bbb")]
+ > m
+ > {3:="bbb",5:="a"}
+ >
+ > let f a len = len + (length a)
+ >  sum of values lengths
+ > fold f 0 m
+ > 4
+
fold :: (a > b > b) > b > Map k a > b
fold f z m
= foldWithKey (\k x z > f x z) z m
  /O(n)/. Fold the keys and values in the map, such that
+  Fold the keys and values in the map, such that
 @'foldWithKey' f z == 'Prelude.foldr' ('uncurry' f) z . 'toAscList'@.
 For example,

 > keys map = foldWithKey (\k x ks > k:ks) [] map

+ /O(n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ > let f k a result = result ++ "(" ++ (show k) ++ ":" ++ a ++ ")"
+ > foldWithKey f "Map: " m
+ > "Map: (5:a)(3:b)"
+
foldWithKey :: (k > a > b > b) > b > Map k a > b
foldWithKey f z t
= foldr f z t
  /O(n)/. Inorder fold.
+  Inorder fold. /O(n)/.
foldi :: (k > a > b > b > b) > b > Map k a > b
foldi f z Tip = z
foldi f z (Bin _ kx x l r) = f kx x (foldi f z l) (foldi f z r)
  /O(n)/. Postorder fold.
+  Postorder fold. /O(n)/.
foldr :: (k > a > b > b) > b > Map k a > b
foldr f z Tip = z
foldr f z (Bin _ kx x l r) = foldr f (f kx x (foldr f z r)) l
  /O(n)/. Preorder fold.
+  Preorder fold. /O(n)/.
foldl :: (b > k > a > b) > b > Map k a > b
foldl f z Tip = z
foldl f z (Bin _ kx x l r) = foldl f (f (foldl f z l) kx x) r
@@ 1073,22 +1816,58 @@
{
List variations
}
  /O(n)/.
 Return all elements of the map in the ascending order of their keys.
+  Return all elements of the map in the ascending order of their keys.
+ /O(n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ > elems m
+ > ["b","a"]
+ > elems empty
+ > []
+
elems :: Map k a > [a]
elems m
= [x  (k,x) < assocs m]
  /O(n)/. Return all keys of the map in ascending order.
+  Return all keys of the map in ascending order. /O(n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ > keys m
+ > [3,5]
+ > keys empty
+ > []
+
keys :: Map k a > [k]
keys m
= [k  (k,x) < assocs m]
  /O(n)/. The set of all keys of the map.
+  The set of all keys of the map. /O(n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ > keysSet m
+ > {3,5}
+ > keysSet empty
+ > {}
+
keysSet :: Map k a > Set.Set k
keysSet m = Set.fromDistinctAscList (keys m)
  /O(n)/. Return all key\/value pairs in the map in ascending key order.
+  Return all key\/value pairs in the map in ascending key order. /O(n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ > assocs m
+ > [(3,"b"),(5,"a")]
+ > assocs empty
+ > []
+
assocs :: Map k a > [(k,a)]
assocs m
= toList m
@@ 1097,34 +1876,78 @@
Lists
use [foldlStrict] to reduce demand on the controlstack
}
  /O(n*log n)/. Build a map from a list of key\/value pairs. See also 'fromAscList'.
+  Build a map from a list of key\/value pairs. See also 'fromAscList'.
+ If the list contains more than one value for the same key, the last value
+ for the key is retained.
+ /O(n*log n)/.
+
+ > fromList [(5,"a"), (3,"b")]
+ > {3:="b",5:="a"}
+ > fromList []
+ > {}
+ > fromList [(5,"a"), (3,"b"), (5, "b")]
+ > {3:="b",5:="b"}
+ > fromList [(5,"b"), (3,"b"), (5, "a")]
+ > {3:="b",5:="a"}
+
fromList :: Ord k => [(k,a)] > Map k a
fromList xs
= foldlStrict ins empty xs
where
ins t (k,x) = insert k x t
  /O(n*log n)/. Build a map from a list of key\/value pairs with a combining function. See also 'fromAscListWith'.
+  Build a map from a list of key\/value pairs with a combining function. See also 'fromAscListWith'.
+ /O(n*log n)/.
+
+ > fromListWith (++) [(5,"a"), (5,"b"), (3,"b"), (3,"a"), (5,"a")]
+ > {3:="ab",5:="aba"}
+ > fromListWith (++) []
+ > {}
+
fromListWith :: Ord k => (a > a > a) > [(k,a)] > Map k a
fromListWith f xs
= fromListWithKey (\k x y > f x y) xs
  /O(n*log n)/. Build a map from a list of key\/value pairs with a combining function. See also 'fromAscListWithKey'.
+  Build a map from a list of key\/value pairs with a combining function. See also 'fromAscListWithKey'.
+ /O(n*log n)/.
+
+ > let f k a1 a2 = (show k) ++ a1 ++ a2
+ > fromListWithKey f [(5,"a"), (5,"b"), (3,"b"), (3,"a"), (5,"a")]
+ > {3:="3ab",5:="5a5ba"}
+ > fromListWithKey f []
+ > {}
+
fromListWithKey :: Ord k => (k > a > a > a) > [(k,a)] > Map k a
fromListWithKey f xs
= foldlStrict ins empty xs
where
ins t (k,x) = insertWithKey f k x t
  /O(n)/. Convert to a list of key\/value pairs.
+  Convert to a list of key\/value pairs. /O(n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ > toList m
+ > [(3,"b"),(5,"a")]
+
toList :: Map k a > [(k,a)]
toList t = toAscList t
  /O(n)/. Convert to an ascending list.
+  Convert to an ascending list. /O(n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ >
+ > toAscList m
+ > [(3,"b"),(5,"a")]
+
toAscList :: Map k a > [(k,a)]
toAscList t = foldr (\k x xs > (k,x):xs) [] t
  /O(n)/.
+
toDescList :: Map k a > [(k,a)]
toDescList t = foldl (\xs k x > (k,x):xs) [] t
@@ 1136,21 +1959,70 @@
fromAscList xs == fromList xs
fromAscListWith f xs == fromListWith f xs
}
  /O(n)/. Build a map from an ascending list in linear time.
 /The precondition (input list is ascending) is not checked./
+  Build a map from an ascending list in linear time.
+ /The precondition (input list is ascending) is not checked./ /O(n)/.
+
+ > fromAscList [(3,"b"), (5,"a")]
+ > {3:="b",5:="a"}
+ >
+ > let result = fromAscList [(3,"b"), (5,"a")]
+ > result
+ > {3:="b",5:="a"}
+ > let result = fromAscList [(3,"b"), (5,"a"), (5,"b")]
+ > result
+ > {3:="b",5:="b"}
+ > valid result
+ > True
+ >
+ >  invalid map is generated if the list is not ordered
+ > let result = fromAscList [(5,"a"), (3,"b"), (5,"b")]
+ > result
+ > {5:="a",3:="b",5:="b"}
+ > valid result
+ > False
+
fromAscList :: Eq k => [(k,a)] > Map k a
fromAscList xs
= fromAscListWithKey (\k x y > x) xs
  /O(n)/. Build a map from an ascending list in linear time with a combining function for equal keys.
 /The precondition (input list is ascending) is not checked./
+  Build a map from an ascending list in linear time with a combining function for equal keys.
+ /The precondition (input list is ascending) is not checked./ /O(n)/.
+
+ > let result = fromAscListWith (++) [(3,"b"), (5,"a"), (5,"b")]
+ > result
+ > {3:="b",5:="ba"}
+ > valid result
+ > True
+ >
+ >  invalid map is generated if the list is not ordered
+ > let result = fromAscListWith (++) [(5,"a"), (3,"b"), (5,"b")]
+ > result
+ > {5:="a",3:="b",5:="b"}
+ > valid result
+ > False
+
fromAscListWith :: Eq k => (a > a > a) > [(k,a)] > Map k a
fromAscListWith f xs
= fromAscListWithKey (\k x y > f x y) xs
  /O(n)/. Build a map from an ascending list in linear time with a
+  Build a map from an ascending list in linear time with a
 combining function for equal keys.
 /The precondition (input list is ascending) is not checked./
+ /The precondition (input list is ascending) is not checked./ /O(n)/.
+
+ > let f k a1 a2 = (show k) ++ ":" ++ a1 ++ a2
+ > let result = fromAscListWithKey f [(3,"b"), (5,"a"), (5,"b"), (5,"b")]
+ > result
+ > {3:="b",5:="5:b5:ba"}
+ > valid result
+ > True
+ >
+ >  invalid map is generated if the list is not ordered
+ > let result = fromAscListWithKey f [(5,"a"), (3,"b"), (5,"b"), (5,"b")]
+ > result
+ > {5:="a",3:="b",5:="5:bb"}
+ > valid result
+ > False
+
fromAscListWithKey :: Eq k => (k > a > a > a) > [(k,a)] > Map k a
fromAscListWithKey f xs
= fromDistinctAscList (combineEq f xs)
@@ 1168,8 +2040,22 @@
 otherwise = z:combineEq' x xs
  /O(n)/. Build a map from an ascending list of distinct elements in linear time.
 /The precondition is not checked./
+  Build a map from an ascending list of distinct elements in linear time.
+ /The precondition is not checked./ /O(n)/.
+
+ > let result = fromDistinctAscList [(3,"b"), (5,"a")]
+ > result
+ > {3:="b",5:="a"}
+ > valid result
+ > True
+ >
+ >  invalid map is generated if the list had nondistinct elements
+ > let result = fromDistinctAscList [(3,"b"), (5,"a"), (5,"b")]
+ > result
+ > {3:="b",5:="a",5:="b"}
+ > valid result
+ > False
+
fromDistinctAscList :: [(k,a)] > Map k a
fromDistinctAscList xs
= build const (length xs) xs
@@ 1255,8 +2141,25 @@
{
Split
}
  /O(log n)/. The expression (@'split' k map@) is a pair @(map1,map2)@ where
 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@.
+  The expression (@'split' k map@) is a pair @(map1,map2)@ where
+ 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@.
+ /O(log n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ > split 2 m
+ > ({},{3:="b",5:="a"})
+ > split 3 m
+ > ({},{5:="a"})
+ > split 4 m
+ > ({3:="b"},{5:="a"})
+ > split 5 m
+ > ({3:="b"},{})
+ > split 6 m
+ > ({3:="b",5:="a"},{})
+
split :: Ord k => k > Map k a > (Map k a,Map k a)
split k Tip = (Tip,Tip)
split k (Bin sx kx x l r)
@@ 1265,8 +2168,24 @@
GT > let (lt,gt) = split k r in (join kx x l lt,gt)
EQ > (l,r)
  /O(log n)/. The expression (@'splitLookup' k map@) splits a map just
+  The expression (@'splitLookup' k map@) splits a map just
 like 'split' but also returns @'lookup' k map@.
+ /O(log n)/.
+
+ > let m = fromList [(5,"a"), (3,"b")]
+ > m
+ > {3:="b",5:="a"}
+ > splitLookup 2 m
+ > ({},Nothing,{3:="b",5:="a"})
+ > splitLookup 3 m
+ > ({},Just "b",{5:="a"})
+ > splitLookup 4 m
+ > ({3:="b"},Nothing,{5,"a"})
+ > splitLookup 5 m
+ > ({3,"b"},Just "a",{})
+ > splitLookup 6 m
+ > ({3:="b",5:="a"},Nothing,{})
+
splitLookup :: Ord k => k > Map k a > (Map k a,Maybe a,Map k a)
splitLookup k Tip = (Tip,Nothing,Tip)
splitLookup k (Bin sx kx x l r)
@@ 1284,8 +2203,9 @@
GT > let (lt,z,gt) = splitLookupWithKey k r in (join kx x l lt,z,gt)
EQ > (l,Just (kx, x),r)
  /O(log n)/. Performs a 'split' but also returns whether the pivot
+  Performs a 'split' but also returns whether the pivot
 element was found in the original set.
+ /O(log n)/.
splitMember :: Ord k => k > Map k a > (Map k a,Bool,Map k a)
splitMember x t = let (l,m,r) = splitLookup x t in
(l,maybe False (const True) m,r)
@@ 1369,7 +2289,16 @@
 otherwise = let ((km,m),r') = deleteFindMin r in balance km m l r'
  /O(log n)/. Delete and find the minimal element.
+  Delete and find the minimal element. /O(log n)/.
+
+ > let m = fromList [(5,"a"), (3,"b"), (10,"c")]
+ > m
+ > {3:="b",5:="a",10:="c"}
+ > deleteFindMin m
+ > ((3,"b"),{5:="a",10:="c"})
+ > deleteFindMin empty
+ > Exception: Map.deleteFindMin: can not return the minimal element of an empty map
+
deleteFindMin :: Map k a > ((k,a),Map k a)
deleteFindMin t
= case t of
@@ 1377,7 +2306,16 @@
Bin _ k x l r > let (km,l') = deleteFindMin l in (km,balance k x l' r)
Tip > (error "Map.deleteFindMin: can not return the minimal element of an empty map", Tip)
  /O(log n)/. Delete and find the maximal element.
+  Delete and find the maximal element. /O(log n)/.
+
+ > let m = fromList [(5,"a"), (3,"b"), (10,"c")]
+ > m
+ > {3:="b",5:="a",10:="c"}
+ > deleteFindMax m
+ > ((10,"c"),{3:="b",5:="a"})
+ > deleteFindMax empty
+ > Exception: Map.deleteFindMax: can not return the maximal element of an empty map
+
deleteFindMax :: Map k a > ((k,a),Map k a)
deleteFindMax t
= case t of
@@ 1531,8 +2469,8 @@
showElem (k,x) = shows k . showString " := " . shows x
  /O(n)/. Show the tree that implements the map. The tree is shown
 in a compressed, hanging format.
+  Show the tree that implements the map. The tree is shown
+ in a compressed, hanging format. See 'showTreeWith'. /O(n)/.
showTree :: (Show k,Show a) => Map k a > String
showTree m
= showTreeWith showElem True False m
@@ 1540,10 +2478,10 @@
showElem k x = show k ++ ":=" ++ show x
{  /O(n)/. The expression (@'showTreeWith' showelem hang wide map@) shows
+{  The expression (@'showTreeWith' showelem hang wide map@) shows
the tree that implements the map. Elements are shown using the @showElem@ function. If @hang@ is
'True', a /hanging/ tree is shown otherwise a rotated tree is shown. If
 @wide@ is 'True', an extra wide version is shown.
+ @wide@ is 'True', an extra wide version is shown. /O(n)/.
> Map> let t = fromDistinctAscList [(x,())  x < [1..5]]
> Map> putStrLn $ showTreeWith (\k x > show (k,x)) True False t
@@ 1632,7 +2570,24 @@
{
Assertions
}
  /O(n)/. Test if the internal map structure is valid.
+  Test if the internal map structure is valid. /O(n)/.
+
+ > let result = fromAscList [(3,"b"), (5,"a")]
+ > result
+ > {3:="b",5:="a"}
+ > let result = fromAscList [(3,"b"), (5,"a"), (5,"b")]
+ > result
+ > {3:="b",5:="b"}
+ > valid result
+ > True
+ >
+ >  invalid map is generated if the list is not ordered
+ > let result = fromAscList [(5,"a"), (3,"b"), (5,"b")]
+ > result
+ > {5:="a",3:="b",5:="b"}
+ > valid result
+ > False
+
valid :: Ord k => Map k a > Bool
valid t
= balanced t && ordered t && validsize t