clarify insertion behavior in docs and tests

Make it clear to library users that the insert function replaces the
value assigned to an existing key.

Author: matthewleon

src/Data/Map.purs

@@ -246,7 +246,7 @@ fromZipper (Cons x ctx) tree =
 
 data KickUp k v = KickUp (Map k v) k v (Map k v)
 
--- | Insert a key/value pair into a map
+-- | Insert or replace a key/value pair in a map
 insert :: forall k v. Ord k => k -> v -> Map k v -> Map k v
 insert = down Nil
   where

src/Data/StrMap.purs

@@ -164,7 +164,7 @@ lookup = runFn4 _lookup Nothing Just
 member :: forall a. String -> StrMap a -> Boolean
 member = runFn4 _lookup false (const true)
 
--- | Insert a key and value into a map
+-- | Insert or replace a key/value pair in a map
 insert :: forall a. String -> a -> StrMap a -> StrMap a
 insert k v = mutate (\s -> SM.poke s k v)
 

test/Test/Data/Map.purs

@@ -121,6 +121,10 @@ mapTests = do
   quickCheck $ \k v -> M.lookup (smallKey k) (M.insert k v M.empty) == Just (number v)
     <?> ("k: " <> show k <> ", v: " <> show v)
 
+  log "Test inserting two values with same key"
+  quickCheck $ \k v1 v2 ->
+    M.lookup (smallKey k) (M.insert k v2 (M.insert k v1 M.empty)) == Just (number v2)
+
   log "Test delete after inserting"
   quickCheck $ \k v -> M.isEmpty (M.delete (smallKey k) (M.insert k (number v) M.empty))
     <?> ("k: " <> show k <> ", v: " <> show v)

test/Test/Data/StrMap.purs

@@ -59,6 +59,9 @@ strMapTests = do
   quickCheck $ \k v -> M.lookup k (M.insert k v M.empty) == Just (number v)
     <?> ("k: " <> show k <> ", v: " <> show v)
 
+  quickCheck $ \k v1 v2 ->
+    M.lookup (smallKey k) (M.insert k v2 (M.insert k v1 M.empty)) == Just (number v2)
+
   log "Test delete after inserting"
   quickCheck $ \k v -> M.isEmpty (M.delete k (M.insert k (number v) M.empty))
     <?> ("k: " <> show k <> ", v: " <> show v)