Document general behavior on equal keys (#1168)

Author: meooow25

containers/src/Data/Map.hs

@@ -20,7 +20,8 @@
 -- This module re-exports the value lazy "Data.Map.Lazy" API.
 --
 -- The @'Map' k v@ type represents a finite map (sometimes called a dictionary)
--- from keys of type @k@ to values of type @v@. A 'Map' is strict in its keys but lazy
+-- from keys of type @k@ to values of type @v@. Most operations require that @k@
+-- have an instance of the 'Ord' class. A 'Map' is strict in its keys but lazy
 -- in its values.
 --
 -- The functions in "Data.Map.Strict" are careful to force values before
@@ -45,9 +46,11 @@
 -- > import Data.Map (Map)
 -- > import qualified Data.Map as Map
 --
--- Note that the implementation is generally /left-biased/. Functions that take
--- two maps as arguments and combine them, such as `union` and `intersection`,
--- prefer the values in the first argument to those in the second.
+-- The @'Ord' k@ instance is expected to be lawful and define a total order.
+-- Unless otherwise specified, operations expect equality on keys to be
+-- extensional: if keys @k1@ and @k2@ satisfy @k1 == k2@, they are considered
+-- identical. For instance, if only one key must be retained by an operation, it
+-- is free to select either.
 --
 --
 -- == Warning

containers/src/Data/Map/Lazy.hs

@@ -18,7 +18,8 @@
 -- = Finite Maps (lazy interface)
 --
 -- The @'Map' k v@ type represents a finite map (sometimes called a dictionary)
--- from keys of type @k@ to values of type @v@. A 'Map' is strict in its keys but lazy
+-- from keys of type @k@ to values of type @v@. Most operations require that @k@
+-- have an instance of the 'Ord' class. A 'Map' is strict in its keys but lazy
 -- in its values.
 --
 -- The functions in "Data.Map.Strict" are careful to force values before
@@ -43,9 +44,11 @@
 -- > import Data.Map.Lazy (Map)
 -- > import qualified Data.Map.Lazy as Map
 --
--- Note that the implementation is generally /left-biased/. Functions that take
--- two maps as arguments and combine them, such as `union` and `intersection`,
--- prefer the values in the first argument to those in the second.
+-- The @'Ord' k@ instance is expected to be lawful and define a total order.
+-- Unless otherwise specified, operations expect equality on keys to be
+-- extensional: if keys @k1@ and @k2@ satisfy @k1 == k2@, they are considered
+-- identical. For instance, if only one key must be retained by an operation, it
+-- is free to select either.
 --
 --
 -- == Warning

containers/src/Data/Map/Strict.hs

@@ -18,7 +18,8 @@
 -- = Finite Maps (strict interface)
 --
 -- The @'Map' k v@ type represents a finite map (sometimes called a dictionary)
--- from keys of type @k@ to values of type @v@.
+-- from keys of type @k@ to values of type @v@. Most operations require that @k@
+-- have an instance of the 'Ord' class.
 --
 -- Each function in this module is careful to force values before installing
 -- them in a 'Map'. This is usually more efficient when laziness is not
@@ -48,9 +49,11 @@
 -- > import Data.Map.Strict (Map)
 -- > import qualified Data.Map.Strict as Map
 --
--- Note that the implementation is generally /left-biased/. Functions that take
--- two maps as arguments and combine them, such as `union` and `intersection`,
--- prefer the values in the first argument to those in the second.
+-- The @'Ord' k@ instance is expected to be lawful and define a total order.
+-- Unless otherwise specified, operations expect equality on keys to be
+-- extensional: if keys @k1@ and @k2@ satisfy @k1 == k2@, they are considered
+-- identical. For instance, if only one key must be retained by an operation, it
+-- is free to select either.
 --
 --
 -- == Warning

containers/src/Data/Set.hs

@@ -17,8 +17,8 @@
 -- = Finite Sets
 --
 -- The @'Set' e@ type represents a set of elements of type @e@. Most operations
--- require that @e@ be an instance of the 'Ord' class. A 'Set' is strict in its
--- elements.
+-- require that @e@ have an instance of the 'Ord' class. A 'Set' is strict in
+-- its elements.
 --
 -- For a walkthrough of the most commonly used functions see the
 -- <https://haskell-containers.readthedocs.io/en/latest/set.html sets introduction>.
@@ -29,11 +29,11 @@
 -- >  import Data.Set (Set)
 -- >  import qualified Data.Set as Set
 --
--- Note that the implementation is generally /left-biased/. Functions that take
--- two sets as arguments and combine them, such as `union` and `intersection`,
--- prefer the entries in the first argument to those in the second. Of course,
--- this bias can only be observed when equality is an equivalence relation
--- instead of structural equality.
+-- The @'Ord' e@ instance is expected to be lawful and define a total order.
+-- Unless otherwise specified, operations expect equality to be extensional: if
+-- elements @x1@ and @x2@ satisfy @x1 == x2@, they are considered identical. For
+-- instance, if only one element must be retained by an operation, it is free to
+-- select either.
 --
 --
 -- == Warning

containers/src/Data/Set/Internal.hs

@@ -1022,9 +1022,6 @@ mapMaybe f t = finishB (foldl' go emptyB t)
 --
 -- It's worth noting that the size of the result may be smaller if,
 -- for some @(x,y)@, @x \/= y && f x == f y@
---
--- If the function produces duplicate values, only one will be retained. No
--- guarantee is made as to which.
 
 map :: Ord b => (a->b) -> Set a -> Set b
 map f t = finishB (foldl' (\b x -> insertB (f x) b) emptyB t)
@@ -1173,9 +1170,6 @@ foldlFB = foldl
 --
 -- If the elements are in non-decreasing order, this function takes \(O(n)\)
 -- time.
---
--- If the list contains duplicate elements, only one will be retained. No
--- guarantee is made as to which.
 fromList :: Ord a => [a] -> Set a
 fromList xs = finishB (Foldable.foldl' (flip insertB) emptyB xs)
 {-# INLINE fromList #-}  -- INLINE for fusion
@@ -1188,9 +1182,6 @@ fromList xs = finishB (Foldable.foldl' (flip insertB) emptyB xs)
 --------------------------------------------------------------------}
 -- | \(O(n)\). Build a set from an ascending list in linear time.
 --
--- If the list contains duplicate elements, only one will be retained. No
--- guarantee is made as to which.
---
 -- __Warning__: This function should be used only if the elements are in
 -- non-decreasing order. This precondition is not checked. Use 'fromList' if the
 -- precondition may not hold.
@@ -1207,9 +1198,6 @@ fromAscList xs = ascLinkAll (Foldable.foldl' next Nada xs)
 
 -- | \(O(n)\). Build a set from a descending list in linear time.
 --
--- If the list contains duplicate elements, only one will be retained. No
--- guarantee is made as to which.
---
 -- __Warning__: This function should be used only if the elements are in
 -- non-increasing order. This precondition is not checked. Use 'fromList' if the
 -- precondition may not hold.