ea4750a5c9901dc42d2b76a1f8e54afc99f55932
[packages/containers.git] / docs / intro.rst
1 ``containers`` Introduction
2 ===========================
3
4 The ``containers`` package provides implementations of various immutable data
5 structures.
6
7 Some of the data structures provided by this package have a very large API
8 surface (for better or worse). The docs here focus on the most common functions
9 which should be more than enough to get you started. Once you know the basics,
10 or if you're looking for a specific function, you can head over to the
11 :haddock:`containers` Haddocks to check out the full API documentation!
12
13 Provided Data Structures
14 ------------------------
15
16 - :doc:`set`: ordered, non-duplicated elements
17 - :doc:`map`: ordered maps from keys to values (aka. dictionaries)
18 - :doc:`sequence`: finite sequence of elements, an efficient alternative to list
19
20 .. NOTE::
21    You'll need ``containers >= 0.5.9`` for a few of the examples. See
22    `Version Requirements`_ for info on how to check which version you have and
23    how to upgrade.
24
25
26 Related Packages
27 ----------------
28
29 - :haddock:`unordered-containers` - containers using hashing instead of
30   ordering.
31
32 - :haddock:`array` - mutable and immutable arrays.
33
34 - :haddock:`vector` - efficient ``Int``-indexed arrays (boxed and unboxed).
35
36 - :haddock:`bytestring` - compact, immutable bytestrings, useful for binary and
37   8-bit character data.
38
39 - :haddock:`dlist` - difference lists with *O(1)* append, useful for efficient
40   logging and pretty printing.
41
42 - :haddock:`hashtables` - mutable hash tables in the ST monad.
43
44
45 Looking for more resources?
46 ---------------------------
47
48 If you've worked your way through the documentation here and you're looking for
49 more examples or tutorials you should check out:
50
51 - `haskell-lang.org's containers tutorial
52   <https://haskell-lang.org/library/containers>`_
53 - `Learn You a Haskell "Modules" chapter <http://learnyouahaskell.com/modules>`_
54
55 .. _installing:
56
57 Installing and using the ``containers`` package
58 -----------------------------------------------
59
60 Version Requirements
61 ^^^^^^^^^^^^^^^^^^^^
62
63 For some of the examples you'll need ``containers >= 0.5.9`` which ships with
64 ``GHC >= 8.2``. You can check to see which version you have installed with:
65
66 ::
67
68     ghc --version
69     > The Glorious Glasgow Haskell Compilation System, version 8.2.2
70
71 If you have an older version, don't worry about it, the majority of the code
72 works with older versions of the package. If you want, you can get a recent
73 version by `from haskell.org <https://www.haskell.org/downloads>`_, or with
74 `Stack <https://www.haskellstack.org>`_ using ``stack --resolver lts-10.2
75 ghci``.
76
77
78 Importing modules
79 ^^^^^^^^^^^^^^^^^
80
81 All of the modules in ``containers`` should be imported ``qualified`` since they
82 use names that conflict with the standard Prelude.
83
84 ::
85
86     import qualified Data.Set as Set
87     import qualified Data.Map.Strict as Map
88     import qualified Data.Sequence as Seq
89
90
91 In GHCi
92 ^^^^^^^
93
94 Start the GHCi `REPL
95 <https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop>`_ with
96 ``ghci`` or ``stack ghci``. Once the REPL is loaded import the modules you want
97 to use and you're good to go!
98
99
100 In a `Cabal <https://cabal.readthedocs.io>`_ or `Stack <https://www.haskellstack.org>`_ project
101 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
102
103 Add ``containers`` to the ``build-depends:`` stanza for your library,
104 executable, or test-suite::
105
106     library
107         build-depends:
108             base >= 4.3 && < 5,
109             containers >= 0.5.7 && < 0.6
110
111 and ``import`` any modules you need in your Haskell source files.