===========
pure-stllib
===========

.. default-domain:: pure

Version 0.6, |today|

| Peter Summerland <p.summerland@gmail.com>

:doc:`pure-stllib` is an "umbrella" package that contains a pair of Pure
addons, :doc:`pure-stlvec` and :doc:`pure-stlmap`. These addons provide
`Pure`_ interfaces to a selection of containers provided by the `C++ Standard
Library`_, specialized to hold pointers to arbitrary Pure
expressions. :doc:`pure-stlvec` is a Pure interface to C++'s vector and the
STL algorithms that act on them. :doc:`pure-stlmap` is an interface to six (of
the eight) of C++'s associative containers: map, set, multimap, multiset,
unordered_map and unordered_set.

.. _Pure: http://purelang.bitbucket.org

.. _C++ Standard Library: http://en.cppreference.com/w/cpp

.. only:: html

   .. contents:: :local:


Copying
=======

| Copyright (c) 2011-2012 by Peter Summerland <p.summerland@gmail.com>.

All rights reserved. 

:doc:`pure-stllib` is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.

:doc:`pure-stllib` is distributed under a BSD-style license, see the COPYING
file for details.

Installation
============

pure-stllib-0.6 requires at least Pure 0.50. The latest version of
Pure is available at https://bitbucket.org/purelang/pure-lang/downloads.

The latest version of the source code for :doc:`pure-stllib` can be downloaded
from https://bitbucket.org/purelang/pure-lang/downloads/pure-stllib-0.6.tar.gz.
 
To install pure-stllib-0.6 (on Linux), extract the source code (e.g.,
tar -xzf pure-stllib-0.6.tar.gz), cd to the pure-stllib-0.6
directory, and run ``make``. After this you can (and should) also run ``make
check`` to run a few unit tests to make sure that :doc:`pure-stlvec` and
:doc:`pure-stlmap` work properly on your system. If ``make check`` works, run
``sudo make install`` to install :doc:`pure-stlvec` and
:doc:`pure-stlmap`. Run ``sudo make uninstall`` to remove them.

``make`` tries to guess your Pure installation directory and platform-specific
setup. If it gets this wrong, you can set some variables manually. In
particular, ``make install prefix=/usr`` sets the installation prefix. Please
see the Makefile for details.

Usage
=====

:doc:`pure-stlvec` provides functions that act on a single mutable container,
stlvec, which is a wrapper around C++'s vector, specialized to hold Pure
expressions. It also provides functions that correspond to C++'s STL
algorithms specialized to act on stlvecs.

:doc:`pure-stlmap` provides functions that act on six mutable containers,
"stlmap", "stlset", "stlmmap", "stlmset", "stlhmap" and "stlhset", that are
thin wrappers around the corresponding associative containers provided by C++,
map, set, multimap, multiset, unordered_map and unordered_set, specialized to
hold Pure expressions.

The functions provided by :doc:`pure-stlvec` and :doc:`pure-stlmap` are made
available by importing one or more of the following modules.

  :mod:`stlvec` - support for stlvecs

  :mod:`stlvec::algorithms` - STL algorithms specialized to act on stlvecs

  :mod:`stlmap` - support for stlmap and stlset

  :mod:`stlmmap` - support for stlmmap and stlmset

  :mod:`stlhmap` - support for stlhmap and stlhset


Documentation
=============

Please see the documentation for :doc:`pure-stlvec` and :doc:`pure-stlmap`.

For the impatient, the functions that act on containers provided by the
:mod:`stlmap`, :mod:`stlmmap`, :mod:`stlhmap` and :mod:`stlvec` modules are
summarized in a rudimentary cheatsheet, pure-stllib-cheatsheet.pdf, which can
be found in the pure-stllib/doc directory.

Changes
=======

Version 0.1 - Bundle pure-stlvec-0.3 and pure-stlmap-0.1.

Version 0.2 - Bundle pure-stlvec-0.3 and pure-stlmap-0.2.

Version 0.3 - Bundle pure-stlvec-0.4 and pure-stlmap-0.3.