Resolve review comments.

Author: m-renaud

Data/HashSet.hs

@@ -20,12 +20,6 @@ using the @Data.IntSet@ from the
 <https://hackage.haskell.org/packages/containers containers> package.
 A 'HashSet' makes no guarantees as to the order of its elements.
 
-== Immutability
-
-@HashSet@s are /immutable/ which means that any update functions do not modify
-the set you passed in, they create a new set. In order to keep the changes
-you need to assign it to a new variable.
-
 == Examples
 
 All the examples below assume @HashSet@ is imported qualified, and uses the following @dataStructures@ set.
@@ -64,16 +58,18 @@ fromList ["Map","HashSet","Graph","HashMap","Set","Sequence"]
 
 === Using custom data with HashSet
 
-To create a @HashSet@ of your custom type, you must derive @Eq@ and
-@Hashable@. The @Hashable@ typeclass is defined in the
+To create a @HashSet@ of your custom type, the type must have instances for 'Eq' and
+'Hashable'. The 'Hashable' typeclass is defined in the
 <https://hackage.haskell.org/packages/hashable hashable> package and the
 recommended way to define the instance is using generics, for which you'll need
 the @DeriveGeneric@ GHC extension.
 
+Note: You'll need to enable the @DeviceGeneric@ language extension, either via
+@:set -XDeriveGeneric@ in GHCi or @\{\-\# DeriveGeneric \#\-\}@ in your Haskell source
+code.
+
 We'll start by setting up our custom data type:
 
->>> :set -XDeriveGeneric
->>> -- or {-# DeriveGeneric #-} if writing a Haskell source file.
 >>> import GHC.Generics (Generic)
 >>> import Data.Hashable
 >>> data Person = Person { name :: String, likesDogs :: Bool } deriving (Show, Eq, Generic)
@@ -88,7 +84,7 @@ fromList [Person {name = "Simon", likesDogs = True},Person {name = "Lana", likes
 
 == Performance
 
-The implementation is based on /hash array mapped trie/.  A
+The implementation is based on /hash array mapped tries/.  A
 'HashSet' is often faster than other 'Ord'-based set types,
 especially when value comparisons are expensive, as in the case of
 strings.

Data/HashSet/Base.hs

@@ -19,7 +19,7 @@
 -- A set of /hashable/ values.  A set cannot contain duplicate items.
 -- A 'HashSet' makes no guarantees as to the order of its elements.
 --
--- The implementation is based on /hash array mapped trie/.  A
+-- The implementation is based on /hash array mapped tries/.  A
 -- 'HashSet' is often faster than other tree-based set types,
 -- especially when value comparison is expensive, as in the case of
 -- strings.
@@ -259,63 +259,51 @@ fromListConstr = mkConstr hashSetDataType "fromList" [] Prefix
 hashSetDataType :: DataType
 hashSetDataType = mkDataType "Data.HashSet.Base.HashSet" [fromListConstr]
 
--- | Construct an empty set.
+-- | /O(1)/ Construct an empty set.
 --
 -- >>> HashSet.empty
 -- fromList []
---
--- __Complexity:__ /O(1)/
 empty :: HashSet a
 empty = HashSet H.empty
 
--- | Construct a set with a single element.
+-- | /O(1)/ Construct a set with a single element.
 --
 -- >>> HashSet.singleton 1
 -- fromList [1]
---
--- __Complexity:__ /O(1)/
 singleton :: Hashable a => a -> HashSet a
 singleton a = HashSet (H.singleton a ())
 {-# INLINABLE singleton #-}
 
--- | Convert to set to the equivalent 'HashMap' with @()@ values.
+-- | /O(1)/ Convert to set to the equivalent 'HashMap' with @()@ values.
 --
 -- >>> HashSet.toMap (HashSet.singleton 1)
 -- fromList [(1,())]
---
--- /Complexity:/ /O(1)/
 toMap :: HashSet a -> HashMap a ()
 toMap = asMap
 
--- | Convert from the equivalent 'HashMap' with @()@ values.
+-- | /O(1)/ Convert from the equivalent 'HashMap' with @()@ values.
 --
 -- >>> HashSet.fromMap (HashMap.singleton 1 ())
 -- fromList [1]
---
--- /Complexity:/ /O(1)/
 fromMap :: HashMap a () -> HashSet a
 fromMap = HashSet
 
--- | Produce a 'HashSet' of all the keys in the given 'HashMap'.
+-- | /O(n)/ Produce a 'HashSet' of all the keys in the given 'HashMap'.
 --
 -- >>> HashSet.keysSet (HashMap.fromList [(1, "a"), (2, "b")]
 -- fromList [1,2]
 --
--- /Complexity:/ /O(n)/
---
 -- @since 0.2.10.0
 keysSet :: HashMap k a -> HashSet k
 keysSet m = fromMap (() <$ m)
 
--- | Construct a set containing all elements from both sets.
+-- | /O(n+m)/ Construct a set containing all elements from both sets.
 --
 -- To obtain good performance, the smaller set must be presented as
 -- the first argument.
 --
 -- >>> union (fromList [1,2]) (fromList [2,3])
 -- fromList [1,2,3]
---
--- __Complexity:__ /O(n+m)/
 union :: (Eq a, Hashable a) => HashSet a -> HashSet a -> HashSet a
 union s1 s2 = HashSet $ H.union (asMap s1) (asMap s2)
 {-# INLINE union #-}
@@ -327,165 +315,134 @@ unions :: (Eq a, Hashable a) => [HashSet a] -> HashSet a
 unions = List.foldl' union empty
 {-# INLINE unions #-}
 
--- | Return 'True' if this set is empty, 'False' otherwise.
+-- | /O(1)/ Return 'True' if this set is empty, 'False' otherwise.
 --
 -- >>> HashSet.null HashSet.empty
 -- True
 -- >>> HashSet.null (HashSet.singleton 1)
 -- False
---
--- __Complexity:__ /O(1)/
 null :: HashSet a -> Bool
 null = H.null . asMap
 {-# INLINE null #-}
 
--- | Return the number of elements in this set.
+-- | /O(n)/ Return the number of elements in this set.
 --
 -- >>> HashSet.size HashSet.empty
 -- 0
 -- >>> HashSet.size (HashSet.fromList [1,2,3])
 -- 3
---
--- __Complexity:__ /O(n)/ - The implementation of @HashSet@ does not save the
--- size in a field so must traverse the entire data structure on each call.
 size :: HashSet a -> Int
 size = H.size . asMap
 {-# INLINE size #-}
 
--- | Return 'True' if the given value is present in this
+-- | /O(log n)/ Return 'True' if the given value is present in this
 -- set, 'False' otherwise.
 --
 -- >>> HashSet.member 1 (Hashset.fromList [1,2,3])
 -- True
 -- >>> HashSet.member 1 (Hashset.fromList [4,5,6])
 -- False
---
--- __Complexity:__ /O(log n)/
 member :: (Eq a, Hashable a) => a -> HashSet a -> Bool
 member a s = case H.lookup a (asMap s) of
                Just _ -> True
                _      -> False
 {-# INLINABLE member #-}
 
--- | Add the specified value to this set.
+-- | /O(log n)/ Add the specified value to this set.
 --
 -- >>> HashSet.insert 1 HashSet.empty
 -- fromList [1]
---
--- __Complexity:__ /O(log n)/
 insert :: (Eq a, Hashable a) => a -> HashSet a -> HashSet a
 insert a = HashSet . H.insert a () . asMap
 {-# INLINABLE insert #-}
 
--- | Remove the specified value from this set if present.
+-- | /O(log n)/ Remove the specified value from this set if present.
 --
 -- >>> HashSet.delete 1 (HashSet.fromList [1,2,3])
 -- fromList [2,3]
 -- >>> HashSet.delete 1 (HashSet.fromList [4,5,6])
 -- fromList [4,5,6]
---
--- __Complexity:__ /O(log n)/
 delete :: (Eq a, Hashable a) => a -> HashSet a -> HashSet a
 delete a = HashSet . H.delete a . asMap
 {-# INLINABLE delete #-}
 
--- | Transform this set by applying a function to every value.
+-- | /O(n)/ Transform this set by applying a function to every value.
 -- The resulting set may be smaller than the source.
 --
 -- >>> HashSet.map show (HashSet.fromList [1,2,3])
 -- HashSet.fromList ["1","2","3"]
---
--- __Complexity:__ /O(n)/
 map :: (Hashable b, Eq b) => (a -> b) -> HashSet a -> HashSet b
 map f = fromList . List.map f . toList
 {-# INLINE map #-}
 
--- | Difference of two sets. Return elements of the first set
+-- | /O(n)/ Difference of two sets. Return elements of the first set
 -- not existing in the second.
 --
 -- >>> HashSet.difference (HashSet.fromList [1,2,3]) (HashSet.fromList [2,3,4])
 -- fromList [1]
---
--- __Complexity:__ /O(n)/
 difference :: (Eq a, Hashable a) => HashSet a -> HashSet a -> HashSet a
 difference (HashSet a) (HashSet b) = HashSet (H.difference a b)
 {-# INLINABLE difference #-}
 
--- | Intersection of two sets. Return elements present in both
+-- | /O(n)/ Intersection of two sets. Return elements present in both
 -- the first set and the second.
 --
 -- >>> HashSet.intersection (HashSet.fromList [1,2,3]) (HashSet.fromList [2,3,4])
 -- fromList [2,3]
---
--- __Complexity:__ /O(n)/
 intersection :: (Eq a, Hashable a) => HashSet a -> HashSet a -> HashSet a
 intersection (HashSet a) (HashSet b) = HashSet (H.intersection a b)
 {-# INLINABLE intersection #-}
 
--- | Reduce this set by applying a binary operator to all
+-- | /O(n)/ Reduce this set by applying a binary operator to all
 -- elements, using the given starting value (typically the
 -- left-identity of the operator).  Each application of the operator
 -- is evaluated before before using the result in the next
 -- application.  This function is strict in the starting value.
---
--- __Complexity:__ /O(n)/
 foldl' :: (a -> b -> a) -> a -> HashSet b -> a
 foldl' f z0 = H.foldlWithKey' g z0 . asMap
   where g z k _ = f z k
 {-# INLINE foldl' #-}
 
--- | Reduce this set by applying a binary operator to all
+-- | /O(n)/ Reduce this set by applying a binary operator to all
 -- elements, using the given starting value (typically the
 -- right-identity of the operator). Each application of the operator
 -- is evaluated before before using the result in the next
 -- application. This function is strict in the starting value.
---
--- __Complexity:__ /O(n)/
 foldr' :: (b -> a -> a) -> a -> HashSet b -> a
 foldr' f z0 = H.foldrWithKey' g z0 . asMap
   where g k _ z = f k z
 {-# INLINE foldr' #-}
 
--- | Reduce this set by applying a binary operator to all
+-- | /O(n)/ Reduce this set by applying a binary operator to all
 -- elements, using the given starting value (typically the
 -- right-identity of the operator).
---
--- __Complexity:__ /O(n)/
 foldr :: (b -> a -> a) -> a -> HashSet b -> a
 foldr f z0 = foldrWithKey g z0 . asMap
   where g k _ z = f k z
 {-# INLINE foldr #-}
 
--- | Reduce this set by applying a binary operator to all
+-- | /O(n)/ Reduce this set by applying a binary operator to all
 -- elements, using the given starting value (typically the
 -- left-identity of the operator).
---
--- __Complexity:__ /O(n)/
 foldl :: (a -> b -> a) -> a -> HashSet b -> a
 foldl f z0 = foldlWithKey g z0 . asMap
   where g z k _ = f z k
 {-# INLINE foldl #-}
 
--- | Filter this set by retaining only elements satisfying a
+-- | /O(n)/ Filter this set by retaining only elements satisfying a
 -- predicate.
---
--- /Complexity:/ /O(n)/
 filter :: (a -> Bool) -> HashSet a -> HashSet a
 filter p = HashSet . H.filterWithKey q . asMap
   where q k _ = p k
 {-# INLINE filter #-}
 
--- | Return a list of this set's elements.  The list is
+-- | /O(n)/ Return a list of this set's elements.  The list is
 -- produced lazily.
---
--- /Complexity:/ /O(n)/
 toList :: HashSet a -> [a]
 toList t = build (\ c z -> foldrWithKey ((const .) c) z (asMap t))
 {-# INLINE toList #-}
 
--- | Construct a set from a list of elements.
---
--- /Complexity:/ /O(n*min(W, n))/
+-- | /O(n*min(W, n))/ Construct a set from a list of elements.
 fromList :: (Eq a, Hashable a) => [a] -> HashSet a
 fromList = HashSet . List.foldl' (\ m k -> H.insert k () m) H.empty
 {-# INLINE fromList #-}