Document the Semigroup for Map
authorChris Martin <ch.martin@gmail.com>
Thu, 7 Feb 2019 19:53:37 +0000 (12:53 -0700)
committerDavid Feuer <David.Feuer@gmail.com>
Mon, 15 Apr 2019 05:07:32 +0000 (01:07 -0400)
The Map type has many possible semigroup implementations,
so the documentation needs to explain which one was chosen.

Data/Map/Internal.hs

index 883f50c..f8b18a3 100644 (file)
@@ -463,6 +463,11 @@ m1 \\ m2 = difference m1 m2
   Size balanced trees.
 --------------------------------------------------------------------}
 -- | A Map from keys @k@ to values @a@.
   Size balanced trees.
 --------------------------------------------------------------------}
 -- | A Map from keys @k@ to values @a@.
+--
+-- The 'Semigroup' operation for 'Map' is 'union', which prefers
+-- values from the left operand. If @m1@ maps a key @k@ to a value
+-- @a1@, and @m2@ maps the same key to a different value @a2@, then
+-- their union @m1 <> m2@ maps @k@ to @a1@.
 
 -- See Note: Order of constructors
 data Map k a  = Bin {-# UNPACK #-} !Size !k a !(Map k a) !(Map k a)
 
 -- See Note: Order of constructors
 data Map k a  = Bin {-# UNPACK #-} !Size !k a !(Map k a) !(Map k a)