From 7659d3c9c7c6dc87d3d2be1391f123c15553a1a4 Mon Sep 17 00:00:00 2001
From: ross <unknown>
Date: Tue, 12 Apr 2005 12:57:49 +0000
Subject: [PATCH] [project @ 2005-04-12 12:57:49 by ross] clarify docs of
 insert and union.

(for STABLE)
---
 Data/IntMap.hs |   12 +++++++-----
 Data/Map.hs    |    4 +++-
 Data/Set.hs    |    6 +++++-
 3 files changed, 15 insertions(+), 7 deletions(-)

diff --git a/Data/IntMap.hs b/Data/IntMap.hs
index fd648cb..972c2e7 100644
--- a/Data/IntMap.hs
+++ b/Data/IntMap.hs
@@ -296,11 +296,11 @@ singleton k x
 
 {--------------------------------------------------------------------
   Insert
-  'insert' is the inlined version of 'insertWith (\k x y -> x)'
 --------------------------------------------------------------------}
--- | /O(min(n,W))/. Insert a new key\/value pair in the map. When the key 
--- is already an element of the set, its value is replaced by the new value, 
--- ie. 'insert' is left-biased.
+-- | /O(min(n,W))/. 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'@.
 insert :: Key -> a -> IntMap a -> IntMap a
 insert k x t
   = case t of
@@ -432,7 +432,9 @@ unionsWith :: (a->a->a) -> [IntMap a] -> IntMap a
 unionsWith f ts
   = foldlStrict (unionWith f) empty ts
 
--- | /O(n+m)/. The (left-biased) union of two sets. 
+-- | /O(n+m)/. The (left-biased) union of two maps. 
+-- It prefers the first map when duplicate keys are encountered,
+-- i.e. (@'union' == 'unionWith' 'const'@).
 union :: IntMap a -> IntMap a -> IntMap a
 union t1@(Bin p1 m1 l1 r1) t2@(Bin p2 m2 l2 r2)
   | shorter m1 m2  = union1
diff --git a/Data/Map.hs b/Data/Map.hs
index d89ab6a..f916606 100644
--- a/Data/Map.hs
+++ b/Data/Map.hs
@@ -278,9 +278,11 @@ singleton k x
 
 {--------------------------------------------------------------------
   Insertion
-  [insert] is the inlined version of [insertWith (\k x y -> x)]
 --------------------------------------------------------------------}
 -- | /O(log n)/. 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'@.
 insert :: Ord k => k -> a -> Map k a -> Map k a
 insert kx x t
   = case t of
diff --git a/Data/Set.hs b/Data/Set.hs
index f321abf..eb41f94 100644
--- a/Data/Set.hs
+++ b/Data/Set.hs
@@ -207,6 +207,8 @@ singleton x
   Insertion, Deletion
 --------------------------------------------------------------------}
 -- | /O(log n)/. Insert an element in a set.
+-- If the set already contains an element equal to the given value,
+-- it is replaced with the new value.
 insert :: Ord a => a -> Set a -> Set a
 insert x t
   = case t of
@@ -289,7 +291,9 @@ unions ts
   = foldlStrict union empty ts
 
 
--- | /O(n+m)/. The union of two sets. Uses the efficient /hedge-union/ algorithm.
+-- | /O(n+m)/. The union of two sets, preferring the first set when
+-- equal elements are encountered.
+-- The implementation uses the efficient /hedge-union/ algorithm.
 -- Hedge-union is more efficient on (bigset `union` smallset).
 union :: Ord a => Set a -> Set a -> Set a
 union Tip t2  = t2
-- 
1.7.10.4