From 522fc419d9a79128d040f0dda47938c71a7a48ed Mon Sep 17 00:00:00 2001 From: Matt Renaud Date: Sun, 31 May 2020 19:51:49 -0700 Subject: [PATCH] DO NOT SUBMIT: Some partial conversion to Tutorial module. --- Tutorial.hs | 80 +++++++++++++++++++++++++++++++++ Tutorial/HashSet.hs | 92 ++++++++++++++++++++++++++++++++++++++ unordered-containers.cabal | 2 + 3 files changed, 174 insertions(+) create mode 100644 Tutorial.hs create mode 100644 Tutorial/HashSet.hs diff --git a/Tutorial.hs b/Tutorial.hs new file mode 100644 index 00000000..ae3cfe46 --- /dev/null +++ b/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 +* - ordered containers using trees instead of hashing. +* - 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: + +* , its focused on the ordered + library but provides some useful examples. +* +-} + +{- $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 + 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". + +-} diff --git a/Tutorial/HashSet.hs b/Tutorial/HashSet.hs new file mode 100644 index 00000000..9b8c8f76 --- /dev/null +++ b/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 package. You can find the +introductory documentation for @containers@ at +. + +@ +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 + + 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 + `_ 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. + + +-} diff --git a/unordered-containers.cabal b/unordered-containers.cabal index b00be4ef..8c064d2f 100644 --- a/unordered-containers.cabal +++ b/unordered-containers.cabal @@ -40,6 +40,8 @@ library Data.HashMap.Lazy Data.HashMap.Strict Data.HashSet + Tutorial + Tutorial.HashSet other-modules: Data.HashMap.Array Data.HashMap.Base