containers Introduction

The containers package provides implementations of various 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 containers Haddocks to check out the full API documentation!

Provided Data Structures

• Sets: ordered, non-duplicated elements

• Maps: ordered maps from keys to values (aka. dictionaries)

• Sequences: finite sequence of elements, an efficient alternative to list

Note

You’ll need containers >= 0.5.9 for a few of the examples. See Version Requirements for info on how to check which version you have and how to upgrade.

Related Packages

• unordered-containers - containers using hashing instead of ordering.

• array - mutable and immutable arrays.

• vector - efficient Int-indexed arrays (boxed and unboxed).

• bytestring - compact, immutable bytestrings, useful for binary and 8-bit character data.

• dlist - difference lists with O(1) append, useful for efficient logging and pretty printing.

• hashtables - mutable hash tables in the ST monad.

Looking for more resources?

If you’ve worked your way through the documentation here and you’re looking for more examples or tutorials you should check out:

• haskell-lang.org’s containers tutorial

• Learn You a Haskell “Modules” chapter

Installing and using the containers package

Version Requirements

For some of the examples you’ll need containers >= 0.5.9 which ships with GHC >= 8.2. You can check to see which version you have installed with:

ghc --version
> The Glorious Glasgow Haskell Compilation System, version 8.2.2

If you have an older version, don’t worry about it, the majority of the code works with older versions of the package. If you want, you can get a recent version by from haskell.org, or with Stack using something like stack --resolver lts-20.14 ghci (see Stackage for the latest long-term support (LTS) or nightly resolver version).

Importing modules

All of the modules in containers should be imported qualified since they use names that conflict with the standard Prelude.

import qualified Data.Set as Set
import qualified Data.Map.Strict as Map
import qualified Data.Sequence as Seq

In GHCi

Start the GHCi REPL with ghci or stack ghci. Once the REPL is loaded import the modules you want to use and you’re good to go!

In a Cabal or Stack project

Add containers to the build-depends: stanza for your library, executable, or test-suite:

library
    build-depends:
        base >= 4.3 && < 5,
        containers >= 0.5.7 && < 0.6

and import any modules you need in your Haskell source files.