Improve HashSet API docs.

Author: m-renaud

Data/HashSet.hs

@@ -4,25 +4,68 @@
 #endif
 
 ------------------------------------------------------------------------
--- |
--- Module      :  Data.HashSet
--- Copyright   :  2011 Bryan O'Sullivan
--- License     :  BSD-style
--- Maintainer  :  johan.tibell@gmail.com
--- Stability   :  provisional
--- Portability :  portable
---
--- 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
--- 'HashSet' is often faster than other tree-based set types,
--- especially when value comparison is expensive, as in the case of
--- strings.
---
--- Many operations have a average-case complexity of /O(log n)/.  The
--- implementation uses a large base (i.e. 16) so in practice these
--- operations are constant time.
+{-|
+Module      :  Data.HashSet
+Copyright   :  2011 Bryan O'Sullivan
+License     :  BSD-style
+Maintainer  :  johan.tibell@gmail.com
+Stability   :  provisional
+Portability :  portable
+
+= Introduction
+
+'HashSet' allows you to store /unique/ elements, providing efficient
+insertion, lookups, and deletion. If you are storing sets of @Int@s consider
+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.
+
+== Example
+
+@
+import qualified Data.HashSet as HashSet
+
+-- Create an empty HashSet.
+let s = HashSet.'HashSet.empty'
+
+-- Create a HashSet from a list of elements.
+let s1 = HashSet.'HashSet.fromList' ["a", "b"]
+
+-- Remove an entry from the HashSet @s1@, storing the new set in @s2@.
+let s2 = HashSet.'HashSet.delete' "a" s1
+
+-- Print the @HashSet@ @s1@, notice it still contains the deleted @"a"@.
+print s1
+> HashSet.'HashSet.fromList' ["a","b"]
+
+-- Print the modified @HashSet@, notice that it does not contain the deleted @"a"@.
+print s2
+> HashSet.'HashSet.fromList' ["b"]
+@
+
+__IMPORTANT:__ @HashSet@ relies on the @element@ type having instances of the
+@Eq@ and @Hashable@ typeclasses for its internal representation. These are
+already defined for builtin types, and if you are using your own data type you
+can use the <https://en.wikibooks.org/wiki/Haskell/Classes_and_types#Deriving deriving>
+mechanism.
+
+== Performance
+
+The implementation is based on /hash array mapped trie/.  A
+'HashSet' is often faster than other tree-based set types,
+especially when value comparison is expensive, as in the case of
+strings.
+
+Many operations have a average-case complexity of /O(log n)/.  The
+implementation uses a large base (i.e. 16) so in practice these
+operations are constant time.
+-}
 
 module Data.HashSet
     (

Data/HashSet/Base.hs

@@ -36,10 +36,6 @@ module Data.HashSet.Base
     , empty
     , singleton
 
-    -- * Combine
-    , union
-    , unions
-
     -- * Basic interface
     , null
     , size
@@ -50,6 +46,10 @@ module Data.HashSet.Base
     -- * Transformations
     , map
 
+    -- * Combine
+    , union
+    , unions
+
       -- * Difference and intersection
     , difference
     , intersection
@@ -259,38 +259,63 @@ fromListConstr = mkConstr hashSetDataType "fromList" [] Prefix
 hashSetDataType :: DataType
 hashSetDataType = mkDataType "Data.HashSet.Base.HashSet" [fromListConstr]
 
--- | /O(1)/ Construct an empty set.
+-- | Construct an empty set.
+--
+-- >>> HashSet.empty
+-- fromList []
+--
+-- __Complexity:__ /O(1)/
 empty :: HashSet a
 empty = HashSet H.empty
 
--- | /O(1)/ Construct a set with a single element.
+-- | 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 #-}
 
--- | /O(1)/ Convert to the equivalent 'HashMap'.
+-- | 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
 
--- | /O(1)/ Convert from the equivalent 'HashMap'.
+-- | Convert from the equivalent 'HashMap' with @()@ values.
+--
+-- >>> HashSet.fromMap (HashMap.singleton 1 ())
+-- fromList [1]
+--
+-- __Complexity:__ /O(1)/
 fromMap :: HashMap a () -> HashSet a
 fromMap = HashSet
 
--- | /O(n)/ Produce a 'HashSet' of all the keys in the given 'HashMap'.
+-- | 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)
 
--- | /O(n+m)/ Construct a set containing all elements from both sets.
+-- | Construct a set containing all elements from both sets.
 --
 -- To obtain good performance, the smaller set must be presented as
 -- the first argument.
 --
--- ==== __Examples__
---
 -- >>> 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 #-}
@@ -302,103 +327,164 @@ unions :: (Eq a, Hashable a) => [HashSet a] -> HashSet a
 unions = List.foldl' union empty
 {-# INLINE unions #-}
 
--- | /O(1)/ Return 'True' if this set is empty, 'False' otherwise.
+-- | 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 #-}
 
--- | /O(n)/ Return the number of elements in this set.
+-- | Return the number of elements in this set.
+--
+-- >>> HashSet.size HashSet.empty
+-- 0
+-- >>> HashSet.size (HashSet.fromList [1,2,3])
+-- 3
+--
+-- __Complexity:__ /O(n)/
 size :: HashSet a -> Int
 size = H.size . asMap
 {-# INLINE size #-}
 
--- | /O(log n)/ Return 'True' if the given value is present in this
+-- | 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 #-}
 
--- | /O(log n)/ Add the specified value to this set.
+-- | 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 #-}
 
--- | /O(log n)/ Remove the specified value from this set if
--- present.
+-- | 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 #-}
 
--- | /O(n)/ Transform this set by applying a function to every value.
+-- | 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 #-}
 
--- | /O(n)/ Difference of two sets. Return elements of the first set
+-- | 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 #-}
 
--- | /O(n)/ Intersection of two sets. Return elements present in both
+-- | 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 #-}
 
--- | /O(n)/ Reduce this set by applying a binary operator to all
+-- | 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' #-}
 
--- | /O(n)/ Reduce this set by applying a binary operator to all
+-- | 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' #-}
 
--- | /O(n)/ Reduce this set by applying a binary operator to all
+-- | 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 #-}
 
--- | /O(n)/ Reduce this set by applying a binary operator to all
+-- | 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 #-}
 
--- | /O(n)/ Filter this set by retaining only elements satisfying a
+-- | 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 #-}
 
--- | /O(n)/ Return a list of this set's elements.  The list is
+-- | 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 #-}
 
--- | /O(n*min(W, n))/ Construct a set from a list of elements.
+-- | Construct a set from a list of elements.
+--
+-- __Complexity:__ /O(n*min(W, n))/
 fromList :: (Eq a, Hashable a) => [a] -> HashSet a
 fromList = HashSet . List.foldl' (\ m k -> H.insert k () m) H.empty
 {-# INLINE fromList #-}