X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=Data%2FMap.hs;h=a76b62bea5425c6ab93aa8ed1ff606f79eec0c49;hb=e9e2a5412bb7cda8d13a063ac403d9f18ac97380;hp=74a57c01e5f3bc0d27b7600f3d188b06df4131a7;hpb=42459d4ce473c881242c8c24c0cd570c3288393e;p=ghc-base.git

diff --git a/Data/Map.hs b/Data/Map.hs
index 74a57c0..a76b62b 100644
--- a/Data/Map.hs
+++ b/Data/Map.hs
@@ -171,7 +171,8 @@ import Data.Generics.Instances
 --------------------------------------------------------------------}
 infixl 9 !,\\ --
 
--- | /O(log n)/. Find the value of a key. Calls 'error' when the element can not be found.
+-- | /O(log n)/. Find the value at a key.
+-- Calls 'error' when the element can not be found.
 (!) :: Ord k => Map k a -> k -> a
 m ! k    = find k m
 
@@ -223,15 +224,19 @@ size t
       Bin sz k x l r  -> sz
 
 
--- | /O(log n)/. Lookup the value of key in the map.
-lookup :: Ord k => k -> Map k a -> Maybe a
-lookup k t
+-- | /O(log n)/. Lookup the value at a key in the map.
+lookup :: (Monad m,Ord k) => k -> Map k a -> m a
+lookup k t = case lookup' k t of
+    Just x -> return x
+    Nothing -> fail "Data.Map.lookup: Key not found"
+lookup' :: Ord k => k -> Map k a -> Maybe a
+lookup' k t
   = case t of
       Tip -> Nothing
       Bin sz kx x l r
           -> case compare k kx of
-               LT -> lookup k l
-               GT -> lookup k r
+               LT -> lookup' k l
+               GT -> lookup' k r
                EQ -> Just x       
 
 -- | /O(log n)/. Is the key a member of the map?
@@ -241,7 +246,8 @@ member k m
       Nothing -> False
       Just x  -> True
 
--- | /O(log n)/. Find the value of a key. Calls 'error' when the element can not be found.
+-- | /O(log n)/. Find the value at a key.
+-- Calls 'error' when the element can not be found.
 find :: Ord k => k -> Map k a -> a
 find k m
   = case lookup k m of
@@ -249,7 +255,7 @@ find k m
       Just x  -> x
 
 -- | /O(log n)/. The expression @('findWithDefault' def k map)@ returns
--- the value of key @k@ or returns @def@ when the key is not in the map.
+-- the value at key @k@ or returns @def@ when the key is not in the map.
 findWithDefault :: Ord k => a -> k -> Map k a -> a
 findWithDefault def k m
   = case lookup k m of
@@ -266,7 +272,7 @@ empty :: Map k a
 empty 
   = Tip
 
--- | /O(1)/. Create a map with a single element.
+-- | /O(1)/. A map with a single element.
 singleton :: k -> a -> Map k a
 singleton k x  
   = Bin 1 k x Tip Tip
@@ -393,9 +399,10 @@ findIndex k t
 
 -- | /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. 
-lookupIndex :: Ord k => k -> Map k a -> Maybe Int
-lookupIndex k t
-  = lookup 0 t
+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."
+    Just x -> return x
   where
     lookup idx Tip  = Nothing
     lookup idx (Bin _ kx x l r)
@@ -464,18 +471,18 @@ 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 minimal key.
+-- | /O(log n)/. Update the value at the minimal key.
 updateMin :: (a -> Maybe a) -> Map k a -> Map k a
 updateMin f m
   = updateMinWithKey (\k x -> f x) m
 
--- | /O(log n)/. Update the maximal key.
+-- | /O(log n)/. Update the value at the maximal key.
 updateMax :: (a -> Maybe a) -> Map k a -> Map k a
 updateMax f m
   = updateMaxWithKey (\k x -> f x) m
 
 
--- | /O(log n)/. Update the minimal key.
+-- | /O(log n)/. Update the value at the minimal key.
 updateMinWithKey :: (k -> a -> Maybe a) -> Map k a -> Map k a
 updateMinWithKey f t
   = case t of
@@ -485,7 +492,7 @@ updateMinWithKey f t
       Bin sx kx x l r    -> balance kx x (updateMinWithKey f l) r
       Tip                -> Tip
 
--- | /O(log n)/. Update the maximal key.
+-- | /O(log n)/. Update the value at the maximal key.
 updateMaxWithKey :: (k -> a -> Maybe a) -> Map k a -> Map k a
 updateMaxWithKey f t
   = case t of
@@ -673,7 +680,7 @@ intersectWithKey f t (Bin _ kx x l r)
       Nothing -> merge tl tr
       Just y  -> join kx (f kx y x) tl tr
   where
-    (found,lt,gt) = splitLookup kx t
+    (lt,found,gt) = splitLookup kx t
     tl            = intersectWithKey f lt l
     tr            = intersectWithKey f gt r
 
@@ -715,7 +722,7 @@ submap' f (Bin _ kx x l r) t
       Nothing -> False
       Just y  -> f x y && submap' f l lt && submap' f r gt
   where
-    (found,lt,gt) = splitLookup kx t
+    (lt,found,gt) = splitLookup kx t
 
 -- | /O(n+m)/. Is this a proper submap? (ie. a submap but not equal). 
 -- Defined as (@'isProperSubmapOf' = 'isProperSubmapOfBy' (==)@).
@@ -794,19 +801,19 @@ 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 an unspecified order.
+-- argument through the map in ascending order of keys.
 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 unspecified order. (= ascending pre-order)
+-- argument through the map in ascending order of keys.
 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) pre-order.
+-- argument throught the map in ascending order of keys.
 mapAccumL :: (a -> k -> b -> (a,c)) -> a -> Map k b -> (a,Map k c)
 mapAccumL f a t
   = case t of
@@ -818,7 +825,7 @@ mapAccumL f a t
              in (a3,Bin sx kx x' l' r')
 
 -- | /O(n)/. The function 'mapAccumR' threads an accumulating
--- argument throught the map in (descending) post-order.
+-- argument throught the map in descending order of keys.
 mapAccumR :: (a -> k -> b -> (a,c)) -> a -> Map k b -> (a,Map k c)
 mapAccumR f a t
   = case t of
@@ -832,8 +839,9 @@ mapAccumR f a t
 -- | /O(n*log n)/. 
 -- @'mapKeys' f s@ is the map obtained by applying @f@ to each key of @s@.
 -- 
--- It's worth noting that the size of the result may be smaller if,
--- for some @(x,y)@, @x \/= y && f x == f y@
+-- 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.
 
 mapKeys :: Ord k2 => (k1->k2) -> Map k1 a -> Map k2 a
 mapKeys = mapKeysWith (\x y->x)
@@ -841,9 +849,9 @@ 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@.
 -- 
--- It's worth noting that the size of the result may be smaller if,
--- for some @(x,y)@, @x \/= y && f x == f y@
--- In such a case, the values will be combined using @c@
+-- 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@.
 
 mapKeysWith :: Ord k2 => (a -> a -> a) -> (k1->k2) -> Map k1 a -> Map k2 a
 mapKeysWith c f = fromListWith c . List.map fFirst . toList
@@ -851,7 +859,8 @@ mapKeysWith c f = fromListWith c . List.map fFirst . toList
 
 
 -- | /O(n)/.
--- @'mapKeysMonotonic' f s == 'mapKeys' f s@, but works only when @f@ is monotonic.
+-- @'mapKeysMonotonic' f s == 'mapKeys' f s@, but works only when @f@
+-- is strictly monotonic.
 -- /The precondition is not checked./
 -- Semi-formally, we have:
 -- 
@@ -867,12 +876,23 @@ mapKeysMonotonic f (Bin sz k x l r) =
 {--------------------------------------------------------------------
   Folds  
 --------------------------------------------------------------------}
--- | /O(n)/. Fold the map in an unspecified order. (= descending post-order).
+
+-- | /O(n)/. Fold the values in the map, such that
+-- @'fold' f z == 'Prelude.foldr' f z . 'elems'@.
+-- For example,
+--
+-- > elems map = fold (:) [] map
+--
 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 map in an unspecified order. (= descending post-order).
+-- | /O(n)/. 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
+--
 foldWithKey :: (k -> a -> b -> b) -> b -> Map k a -> b
 foldWithKey f z t
   = foldr f z t
@@ -895,12 +915,13 @@ foldl f z (Bin _ kx x l r) = foldl f (f (foldl f z l) kx x) r
 {--------------------------------------------------------------------
   List variations 
 --------------------------------------------------------------------}
--- | /O(n)/. Return all elements of the map.
+-- | /O(n)/.
+-- Return all elements of the map in the ascending order of their keys.
 elems :: Map k a -> [a]
 elems m
   = [x | (k,x) <- assocs m]
 
--- | /O(n)/. Return all keys of the map.
+-- | /O(n)/. Return all keys of the map in ascending order.
 keys  :: Map k a -> [k]
 keys m
   = [k | (k,x) <- assocs m]
@@ -909,7 +930,7 @@ keys m
 keysSet :: Map k a -> Set.Set k
 keysSet m = Set.fromDistinctAscList (keys m)
 
--- | /O(n)/. Return all key\/value pairs in the map.
+-- | /O(n)/. Return all key\/value pairs in the map in ascending key order.
 assocs :: Map k a -> [(k,a)]
 assocs m
   = toList m
@@ -1088,13 +1109,13 @@ split k (Bin sx kx x l r)
 
 -- | /O(log n)/. The expression (@'splitLookup' k map@) splits a map just
 -- like 'split' but also returns @'lookup' k map@.
-splitLookup :: Ord k => k -> Map k a -> (Maybe a,Map k a,Map k a)
-splitLookup k Tip = (Nothing,Tip,Tip)
+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)
   = case compare k kx of
-      LT -> let (z,lt,gt) = splitLookup k l in (z,lt,join kx x gt r)
-      GT -> let (z,lt,gt) = splitLookup k r in (z,join kx x l lt,gt)
-      EQ -> (Just x,l,r)
+      LT -> let (lt,z,gt) = splitLookup k l in (lt,z,join kx x gt r)
+      GT -> let (lt,z,gt) = splitLookup k r in (join kx x l lt,z,gt)
+      EQ -> (l,Just x,r)
 
 {--------------------------------------------------------------------
   Utility functions that maintain the balance properties of the tree.