Hi Haskell hackers! The library documentation I sit with for Data.Map misses some explanation: insertWith :: Ord k => (a -> a -> a) -> k -> a -> Map k a -> Map k a O(log n). Insert with a combining function. Ok, we now have to guess about the exact semantics of this function. We expect that if k is not existing in the Map, the (k,a) pair is going to be inserted. If k is existing, the combining function will be called. When the combining function is being called, we only have 50% chance of guessing the semantics. You could, with some correctness, postulate the documentation was 50% correct. The following test is from hugs-2005Mar: Data.Map> let a = insert 0 1 empty in insertWith (curry fst) 0 2 a {0:=2} Data.Map> let a = insert 0 1 empty in insertWith (curry snd) 0 2 a {0:=1} Aha!, so now we are able to make the documentation for the function better:

-- | /O(log n)/. 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 the value from the function call `f new_value old_value`.

Feel free to make my crude english better and to supply the same documentation for insertWithKey. If this has already been done, ignore my message ;)