DO NOT SUBMIT: Some partial conversion to Tutorial module.

Author: m-renaud

Tutorial.hs

@@ -0,0 +1,80 @@
+{-# OPTIONS_GHC -fno-warn-unused-imports #-}
+
+{-|
+    The @unordered-containers@ package provides implementations of various
+    hash-based immutable data structures.
+
+    Some of the data structures provided by this package have a very large API
+    surface (for better or worse). The docs here focus on the most common functions
+    which should be more than enough to get you started. Once you know the basics,
+    or if you're looking for a specific function, you can head over to the
+    full API documentation!
+-}
+
+
+module Tutorial (
+    -- * Provided Data Structures
+    -- $provideddatastructures
+
+    -- * Related Packages
+    -- $relatedpackages
+
+    -- * Looking for more resources?
+    -- $moreresources
+
+    -- * Installing and using the @unordered-containers@ packages
+    -- $installing
+
+    -- * HashSet and HashMap tutorial
+    -- $tutorials
+
+                ) where
+
+{- $provideddatastructures
+* 'Data.HashSet' - unordered, non-duplicated elements
+* 'Data.HashMap' - unordered map from keys to values (aka. dictionaries)
+-}
+
+{- $relatedpackages
+* <https://hackage.haskell.org/packages/containers containers> - ordered containers using trees instead of hashing.
+* <https://hackage.haskell.org/packages/hashable containers> - types that can be converted to a hash value.
+-}
+
+{- $moreresources
+If you've worked your way through the documentation here and you're looking for
+more examples or tutorials you should check out:
+
+* <https://haskell-lang.org/library/containers haskell-lang.org's containers tutorial>, its focused on the ordered
+  <https://hackage.haskell.org/packages/containers containers> library but provides some useful examples.
+* <http://learnyouahaskell.com/modules Learn You a Haskell "Modules" chapter>
+-}
+
+{- $installing
+__Version Requirements__
+
+All of the examples here should work for all recent versions of the package.
+
+__Importing modules__
+
+All of the modules in @unordered-containers@@ should be imported @qualified@
+since they use names that conflict with the standard Prelude.
+
+@
+import qualified Data.HashSet as HashSet
+import qualified Data.HashMap.Strict as HashMap
+@
+
+__In GHCi__
+
+Start the GHCi
+<https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop REPL> with
+@ghci@, @cabal repl@, or @stack ghci@. Once the REPL is loaded, import the
+modules you want using the @import@ statements above and you're good to go!
+-}
+
+
+{- $tutorials
+
+See "Tutorial.HashSet" and "Tutorial.HashMap".
+
+-}

Tutorial/HashSet.hs

@@ -0,0 +1,92 @@
+{-# OPTIONS_GHC -fno-warn-unused-imports #-}
+
+{-|
+Sets allow you to store *unique* elements, providing efficient insertion,
+lookups, and deletions. If you are storing sets of @Int@ s consider using
+'Data.IntSet' from the <https://hackage.haskell.org/packages/containers containers> package. You can find the
+introductory documentation for @containers@ at
+<https://haskell-containers.readthedocs.io>.
+
+@
+data HashSet element = ...
+@
+
+
+All of these implementations are *immutable* which means that any update
+functions do not modify the set that you passed in, they creates a new set. In
+order to keep the changes you need to assign it to a new variable. For example:
+
+@
+let s1 = HashSet.fromList ["a", "b"]
+let s2 = HashSet.delete "a" s1
+print s1
+> fromList ["a","b"]
+print s2
+> 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.
+
+
+-}
+
+module Tutorial.HashSet (
+    -- * Short Example
+    -- $shortexample
+
+                        ) where
+
+
+{- $shortexample
+
+The following GHCi session shows some of the basic set functionality:
+
+@
+import qualified Data.HashSet as HashSet
+
+let dataStructures = HashSet.fromList ["HashSet", "HashMap", "Graph"]
+
+-- Check if "HashMap" and "Trie" are in the set of data structures.
+HashSet.member "HashMap" dataStructures
+> True
+
+HashSet.member "Trie" dataStructures
+> False
+
+
+-- Add "Trie" to our original set of data structures.
+let moreDataStructures = HashSet.insert "Trie" dataStructures
+
+HashSet.member "Trie" moreDataStructures
+> True
+
+
+-- Remove "Graph" from our original set of data structures.
+let fewerDataStructures = HashSet.delete "Graph" dataStructures
+
+HashSet.toList fewerDataStructures
+> ["HashSet", "HashMap"]
+
+
+-- Create a new set and combine it with our original set.
+let orderedDataStructures = HashSet.fromList ["Set", "Map"]
+
+HashSet.union dataStructures orderedDataStructures
+> fromList ["Map", "HashSet", "Graph", "HashMap", "Set"]
+@
+
+
+__TIP__: You can use the `OverloadedLists
+	 <https://ghc.haskell.org/trac/ghc/wiki/OverloadedLists>`_ extension so
+	 you don't need to write ``fromList [1, 2, 3]`` everywhere. Instead you
+	 can just write ``[1, 2, 3]`` and if the function is expecting a set it
+	 will be converted automatically! The code here will continue to use
+	 ``fromList`` for clarity though.
+
+
+-}

unordered-containers.cabal

@@ -31,6 +31,8 @@ library
     Data.HashMap.Lazy
     Data.HashMap.Strict
     Data.HashSet
+    Tutorial
+    Tutorial.HashSet
   other-modules:
     Data.HashMap.Array
     Data.HashMap.Base