Merged from 1.33.0 release

[SVN r30540]
2026-07-21 13:33:33 +00:00 · 2005-08-12 13:02:37 +00:00
14 changed files with 234 additions and 198 deletions
@@ -3,7 +3,7 @@
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.3.7: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.3.9: http://docutils.sourceforge.net/" />
 <title>Boost Pointer Container Library</title>
 <link rel="stylesheet" href="default.css" type="text/css" />
 </head>
@@ -26,6 +26,7 @@ and provides almost the same interface.  The new conventions are:</p>
 <li><a class="reference" href="#ownership-can-be-transferred-from-a-container-on-a-per-pointer-basis" id="id10" name="id10">Ownership can be transferred from a container on a per pointer basis</a></li>
 <li><a class="reference" href="#ownership-can-be-transferred-from-a-container-to-another-container-on-a-per-iterator-range-basis" id="id11" name="id11">Ownership can be transferred from a container to another container on a per iterator range basis</a></li>
 <li><a class="reference" href="#a-container-can-be-cheaply-returned-from-functions-either-by-making-a-clone-or-by-giving-up-ownership-of-the-container" id="id12" name="id12">A container can be cheaply returned from functions either by making a clone or by giving up ownership of the container</a></li>
+<li><a class="reference" href="#iterators-are-invalidated-as-in-the-corresponding-standard-container" id="id13" name="id13">Iterators are invalidated as in the corresponding standard container</a></li>
 </ul>
 </div>
 <div class="section" id="null-pointers-are-not-allowed-by-default">
@@ -71,7 +72,7 @@ needed anyway, every container has a <tt class="docutils literal"><span class="p
 (see <a class="reference" href="examples.html">Example 3</a>).</p>
 </div>
 <div class="section" id="stored-elements-are-required-to-be-clonable-for-a-subset-of-the-operations">
-<h1><a class="toc-backref" href="#id7" name="stored-elements-are-required-to-be-clonable-for-a-subset-of-the-operations">Stored elements are required to be <a class="reference" href="reference.html#the-clonable-concept">Clonable</a> for a subset of the operations</a></h1>
+<h1><a name="stored-elements-are-required-to-be-clonable-for-a-subset-of-the-operations">Stored elements are required to be <a class="reference" href="reference.html#the-clonable-concept">Clonable</a> for a subset of the operations</a></h1>
 <p>This is because most polymorphic objects cannot be copied directly, but 
 they can often be so by a use of a member function (see <a class="reference" href="examples.html">Example 4</a>).  Often 
 it does not even make sense to clone an object in which case a large 
@@ -104,6 +105,16 @@ containers without cloning the objects again (see <a class="reference" href="exa
 <tt class="docutils literal"><span class="pre">auto_ptr&lt;SmartContainer&gt;</span></tt> which can be assigned to another pointer container.  This 
 effectively reduces the cost of returning a container to one 
 heap-allocation plus a call to <tt class="docutils literal"><span class="pre">swap()</span></tt> (see <a class="reference" href="examples.html">Example 3</a>).</p>
+</div>
+<div class="section" id="iterators-are-invalidated-as-in-the-corresponding-standard-container">
+<h1><a class="toc-backref" href="#id13" name="iterators-are-invalidated-as-in-the-corresponding-standard-container">Iterators are invalidated as in the corresponding standard container</a></h1>
+<p>Because the containers in this library wrap standard containers, the
+rules for invalidation of iterators are the same as the rules
+of the corresponding standard container.</p>
+<p>For example, for both <tt class="docutils literal"><span class="pre">boost::ptr_vector&lt;T&gt;</span></tt> and <tt class="docutils literal"><span class="pre">std::vector&lt;U&gt;</span></tt>
+insertion and deletion only invalidates the deleted
+element and elements following it; all elements before the inserted/deleted
+element remain valid.</p>
 <p><strong>Navigate:</strong></p>
 <ul class="simple">
 <li><a class="reference" href="ptr_container.html">home</a></li>
@@ -99,7 +99,20 @@ A container can be cheaply returned from functions either by making a clone or b
 Two special member functions, ``clone()`` and ``release()``, both return an 
 ``auto_ptr<SmartContainer>`` which can be assigned to another pointer container.  This 
 effectively reduces the cost of returning a container to one 
-heap-allocation plus a call to ``swap()`` (see `Example 3 <examples.html>`_).  
+heap-allocation plus a call to ``swap()`` (see `Example 3 <examples.html>`_).
+
+Iterators are invalidated as in the corresponding standard container
+--------------------------------------------------------------------
+
+Because the containers in this library wrap standard containers, the
+rules for invalidation of iterators are the same as the rules
+of the corresponding standard container.
+
+For example, for both ``boost::ptr_vector<T>`` and ``std::vector<U>``
+insertion and deletion only invalidates the deleted
+element and elements following it; all elements before the inserted/deleted
+element remain valid.
+

 **Navigate:**

@@ -26,7 +26,7 @@
 </div>
 <div class="section" id="since-a-pointer-container-is-not-copy-constructible-and-assignable-i-cannot-put-them-into-standard-containers-what-do-i-do">
 <h1><a class="toc-backref" href="#id4" name="since-a-pointer-container-is-not-copy-constructible-and-assignable-i-cannot-put-them-into-standard-containers-what-do-i-do">Since a pointer container is not Copy Constructible and Assignable, I cannot put them into standard containers; what do I do?</a></h1>
-<p>Since they are <a class="reference" href="ptr_container.html#the-clonable-concept">Clonable</a>, you simply put them in a pointer container.</p>
+<p>Since they are <a class="reference" href="reference.html#the-clonable-concept">Clonable</a>, you simply put them in a pointer container.</p>
 </div>
 <div class="section" id="calling-assign-is-very-costly-and-i-do-not-really-need-to-store-cloned-objects-i-merely-need-to-overwrite-the-existing-ones-what-do-i-do">
 <h1><a class="toc-backref" href="#id5" name="calling-assign-is-very-costly-and-i-do-not-really-need-to-store-cloned-objects-i-merely-need-to-overwrite-the-existing-ones-what-do-i-do">Calling <tt class="docutils literal"><span class="pre">assign()</span></tt> is very costly and I do not really need to store cloned objects; I merely need to overwrite the existing ones; what do I do?</a></h1>
@@ -3,7 +3,7 @@
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.3.7: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.3.9: http://docutils.sourceforge.net/" />
 <title>Boost Pointer Container Library</title>
 <link rel="stylesheet" href="default.css" type="text/css" />
 </head>
@@ -36,25 +36,19 @@ and functions <tt class="docutils literal"><span class="pre">new_clone()</span><
 <tr><td><tt class="docutils literal"><span class="pre">&lt;boost/ptr_container/ptr_array.hpp&gt;</span></tt></td>
 <td>class <a class="reference" href="ptr_array.html">ptr_array</a> (and <tt class="docutils literal"><span class="pre">boost::array</span></tt>)</td>
 </tr>
-<tr><td><tt class="docutils literal"><span class="pre">&lt;boost/ptr_container/ptr_set&gt;</span></tt></td>
-<td><dl class="first last docutils">
-<dt>classes <a class="reference" href="ptr_set.html">ptr_set</a> and <a class="reference" href="ptr_multiset.html">ptr_multiset</a></dt>
-<dd>(and <tt class="docutils literal"><span class="pre">std::set</span></tt> and <tt class="docutils literal"><span class="pre">std::multiset</span></tt>)</dd>
-</dl>
-</td>
+<tr><td><tt class="docutils literal"><span class="pre">&lt;boost/ptr_container/ptr_set.hpp&gt;</span></tt></td>
+<td>classes <a class="reference" href="ptr_set.html">ptr_set</a> and <a class="reference" href="ptr_multiset.html">ptr_multiset</a>
+(and <tt class="docutils literal"><span class="pre">std::set</span></tt> and <tt class="docutils literal"><span class="pre">std::multiset</span></tt>)</td>
 </tr>
-<tr><td><tt class="docutils literal"><span class="pre">&lt;boost/ptr_container/ptr_map&gt;</span></tt></td>
-<td><dl class="first last docutils">
-<dt>classes <a class="reference" href="ptr_map.html">ptr_map</a> and <a class="reference" href="ptr_multimap.html">ptr_multimap</a></dt>
-<dd>(and <tt class="docutils literal"><span class="pre">std::map</span></tt> and <tt class="docutils literal"><span class="pre">std::multimap</span></tt>)</dd>
-</dl>
-</td>
+<tr><td><tt class="docutils literal"><span class="pre">&lt;boost/ptr_container/ptr_map.hpp&gt;</span></tt></td>
+<td>classes <a class="reference" href="ptr_map.html">ptr_map</a> and <a class="reference" href="ptr_multimap.html">ptr_multimap</a>
+(and <tt class="docutils literal"><span class="pre">std::map</span></tt> and <tt class="docutils literal"><span class="pre">std::multimap</span></tt>)</td>
 </tr>
 <tr><td><tt class="docutils literal"><span class="pre">&lt;boost/ptr_container/ptr_sequence_adapter.hpp&gt;</span></tt></td>
 <td>class <a class="reference" href="ptr_sequence_adapter.html">ptr_sequence_adapter</a></td>
 </tr>
 <tr><td><tt class="docutils literal"><span class="pre">&lt;boost/ptr_container/ptr_set_adapter.hpp&gt;</span></tt></td>
-<td>classes <a class="reference" href="ptr_set_adapter.html">ptr_set_adapter</a> and <a class="reference" href="ptr_multiset_adapter.html">ptr_multiset_adapter</a></td>
+<td>classes <a class="reference" href="ptr_set_adapter.html">ptr_set_adapter</a> and <a class="reference" href="ptr_multiset_sdapter.html">ptr_multiset_adapter</a></td>
 </tr>
 <tr><td><tt class="docutils literal"><span class="pre">&lt;boost/ptr_container/ptr_map_adapter.hpp&gt;</span></tt></td>
 <td>classes <a class="reference" href="ptr_map_adapter.html">ptr_map_adapter</a> and <a class="reference" href="ptr_multimap_adapter.html">ptr_multimap_adapter</a></td>
@@ -1,7 +1,7 @@
 ++++++++++++++++++++++++++++++++++
 |Boost| Pointer Container Library
 ++++++++++++++++++++++++++++++++++
- 
+
 .. |Boost| image:: cboost.gif

 ===============
@@ -11,9 +11,9 @@ Library headers
 ======================================================= =============================================================
             **Header**                                    **Includes**

-``<boost/ptr_container/clone_allocator.hpp>``            classes heap_clone_allocator_  and view_clone_allocator_ 
-                                                         and functions ``new_clone()`` and ``delete_clone()`` 
-                                                         
+``<boost/ptr_container/clone_allocator.hpp>``            classes heap_clone_allocator_  and view_clone_allocator_
+                                                         and functions ``new_clone()`` and ``delete_clone()``
+
 ``<boost/ptr_container/ptr_deque.hpp>``                  class `ptr_deque <ptr_deque.html>`_ (and ``std::deque``)

 ``<boost/ptr_container/ptr_list.hpp>``                   class `ptr_list <ptr_list.html>`_  (and ``std::list``)
@@ -22,10 +22,10 @@ Library headers

 ``<boost/ptr_container/ptr_array.hpp>``                  class `ptr_array <ptr_array.html>`_ (and ``boost::array``)

-``<boost/ptr_container/ptr_set>``                        classes `ptr_set <ptr_set.html>`_ and `ptr_multiset <ptr_multiset.html>`_
-                                                           (and ``std::set`` and ``std::multiset``)  
+``<boost/ptr_container/ptr_set.hpp>``                      classes `ptr_set <ptr_set.html>`_ and `ptr_multiset <ptr_multiset.html>`_
+                                                           (and ``std::set`` and ``std::multiset``)

-``<boost/ptr_container/ptr_map>``                        classes `ptr_map <ptr_map.html>`_ and `ptr_multimap <ptr_multimap.html>`_
+``<boost/ptr_container/ptr_map.hpp>``                      classes `ptr_map <ptr_map.html>`_ and `ptr_multimap <ptr_multimap.html>`_
                                                           (and ``std::map`` and ``std::multimap``)

 ``<boost/ptr_container/ptr_sequence_adapter.hpp>``       class `ptr_sequence_adapter <ptr_sequence_adapter.html>`_
@@ -34,7 +34,7 @@ Library headers

 ``<boost/ptr_container/ptr_map_adapter.hpp>``            classes `ptr_map_adapter <ptr_map_adapter.html>`_ and `ptr_multimap_adapter <ptr_multimap_adapter.html>`_

-``<boost/ptr_container/exception.hpp>``                  classes ``bad_ptr_container_operation``, ``bad_index`` 
+``<boost/ptr_container/exception.hpp>``                  classes ``bad_ptr_container_operation``, ``bad_index``
                                                           and ``bad_pointer``
 ``<boost/ptr_container/indirect_fun.hpp>``               class ``indirect_fun``

@@ -50,5 +50,5 @@ Library headers
 - `reference <reference.html>`_


-:copyright:     Thorsten Ottosen 2004-2005. 
+:copyright:     Thorsten Ottosen 2004-2005.

@@ -3,7 +3,7 @@
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.3.7: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.3.9: http://docutils.sourceforge.net/" />
 <title>Boost Pointer Container Library</title>
 <meta name="author" content="Thorsten Ottosen" />
 <meta name="date" content="3rd of May 2005" />
@@ -32,15 +32,15 @@
 <div class="section" id="overview">
 <h1><a name="overview">Overview</a></h1>
 <p>Boost.Pointer Container provides containers for holding heap-allocated
-objects in an exception-safe manner and with minimal overhead. 
+objects in an exception-safe manner and with minimal overhead.
 The aim of the library is in particular to make OO programming
-easier in C++ by establishing a standard set of classes, methods 
+easier in C++ by establishing a standard set of classes, methods
 and designs for dealing with OO specific problems</p>
 <ul class="simple">
 <li><a class="reference" href="#motivation">Motivation</a></li>
 <li><a class="reference" href="tutorial.html">Tutorial</a></li>
 <li><a class="reference" href="reference.html">Reference</a><ul>
-<li><a class="reference" href="reference.html#conventions">Conventions</a></li>
+<li><a class="reference" href="conventions.html">Conventions</a></li>
 <li><a class="reference" href="reference.html#the-clonable-concept">The Clonable Concept</a></li>
 <li><a class="reference" href="reference.html#the-clone-allocator-concept">The Clone Allocator Concept</a></li>
 <li><a class="reference" href="reference.html#pointer-container-adapters">Pointer container adapters</a></li>
@@ -73,7 +73,7 @@ and designs for dealing with OO specific problems</p>
 </div>
 <div class="section" id="motivation">
 <h1><a name="motivation">Motivation</a></h1>
-<p>Whenever a programmer wants to have a container of pointers to 
+<p>Whenever a programmer wants to have a container of pointers to
 heap-allocated objects, there is usually only one exception-safe way:
 to make a container of pointer pointers like <tt class="docutils literal"><span class="pre">boost::shared_ptr</span></tt>.
 This approach is suboptimal if</p>
@@ -81,12 +81,12 @@ This approach is suboptimal if</p>
 <li>the stored objects are not shared, but owned exclusively, or</li>
 <li>the overhead implied by pointer pointers is inappropriate</li>
 </ol>
-<p>This library therefore provides standard-like containers that are for storing 
-heap-allocated or <a class="reference" href="reference.html#the-clonable-concept">cloned</a> objects (or in case of a map, the mapped object must be 
-a heap-allocated or cloned object). For each of the standard 
-containers there is a pointer container equivalent that takes ownership of 
-the objects in an exception safe manner.  In this respect the library is intended 
-to solve the so-called 
+<p>This library therefore provides standard-like containers that are for storing
+heap-allocated or <a class="reference" href="reference.html#the-clonable-concept">cloned</a> objects (or in case of a map, the mapped object must be
+a heap-allocated or cloned object). For each of the standard
+containers there is a pointer container equivalent that takes ownership of
+the objects in an exception safe manner.  In this respect the library is intended
+to solve the so-called
 <a class="reference" href="faq.html#what-is-the-polymorphic-class-problem">polymorphic class problem</a>.</p>
 <p>The advantages of pointer containers are</p>
 <ol class="arabic simple">
@@ -95,32 +95,32 @@ to solve the so-called
 <li>Can be used for types that are neither Assignable nor Copy Constructible.</li>
 <li>No memory-overhead as containers of pointer pointers can have (see <a class="footnote-reference" href="#id21" id="id2" name="id2">[11]</a> and <a class="footnote-reference" href="#id23" id="id3" name="id3">[12]</a>).</li>
 <li>Usually faster than using containers of pointer pointers (see <a class="footnote-reference" href="#id21" id="id4" name="id4">[11]</a> and <a class="footnote-reference" href="#id23" id="id5" name="id5">[12]</a>).</li>
-<li>The interface is slightly changed towards the domain of pointers  
+<li>The interface is slightly changed towards the domain of pointers
 instead of relying on the normal value-based interface. For example,
 now it is possible for <tt class="docutils literal"><span class="pre">pop_back()</span></tt> to return the removed element.</li>
 <li>Propagates constness s.t. one cannot modify the objects via a <tt class="docutils literal"><span class="pre">const_iterator</span></tt></li>
 </ol>
 <p>The disadvantages are</p>
 <ol class="arabic simple">
-<li>Less flexible than containers of pointer pointers</li>
+<li>Less flexible than containers of smart pointers like <a class="reference" href="../../smart_ptr/shared_ptr.htm">boost::shared_ptr</a></li>
 </ol>
 </div>
 <div class="section" id="acknowledgements">
 <h1><a name="acknowledgements">Acknowledgements</a></h1>
 <p>The following people have been very helpful:</p>
 <ul class="simple">
-<li>Bjørn D. Rasmussen for showing me his cr**** code that motivated me to start this library</li>
+<li>Bjørn D. Rasmussen for unintentionally motivating me to start this library</li>
 <li>Pavel Vozenilek for asking me to make the adapters</li>
 <li>David Abrahams for the <tt class="docutils literal"><span class="pre">indirect_fun</span></tt> design</li>
 <li>Pavol Droba for being review manager</li>
 <li>Ross Boylan for trying out a prototype for real</li>
 <li>Felipe Magno de Almeida for giving fedback based on using the
 library in production code even before the library was part of boost</li>
-<li>Jonathan Turkanis for supplying his <tt class="docutils literal"><span class="pre">move_ptr</span></tt> framework 
+<li>Jonathan Turkanis for supplying his <tt class="docutils literal"><span class="pre">move_ptr</span></tt> framework
 which is used internally</li>
 <li>Stefan Slapeta and Howard Hinnant for Metrowerks support</li>
 <li>Russell Hind for help with Borland compatibility</li>
-<li>Jonathan Wakely for help with GCC compatibility</li>
+<li>Jonathan Wakely for his great help with GCC compatibility and bug fixes</li>
 <li>Pavel Chikulaev for comments and bug-fixes</li>
 </ul>
 </div>
@@ -2,9 +2,9 @@
 ++++++++++++++++++++++++++++++++++
 |Boost| Pointer Container Library
 ++++++++++++++++++++++++++++++++++
- 
+
 .. |Boost| image:: cboost.gif
-   
+


 :Authors:       Thorsten Ottosen
@@ -14,7 +14,7 @@
 :copyright:     Thorsten Ottosen 2004-2005. Use, modification and distribution is subject to the Boost Software License, Version 1.0 (see LICENSE_1_0.txt__).

 __ http://www.boost.org/LICENSE_1_0.txt
- 
+
 .. _`Department of Computer Science`: http://www.cs.aau.dk
 .. _`Dezide Aps`: http://www.dezide.com

@@ -23,19 +23,19 @@ Overview
 ========

 Boost.Pointer Container provides containers for holding heap-allocated
-objects in an exception-safe manner and with minimal overhead. 
+objects in an exception-safe manner and with minimal overhead.
 The aim of the library is in particular to make OO programming
-easier in C++ by establishing a standard set of classes, methods 
+easier in C++ by establishing a standard set of classes, methods
 and designs for dealing with OO specific problems

 * Motivation_
 * Tutorial_
 * Reference_

-  - `Conventions <reference.html#conventions>`_
-  - `The Clonable Concept <reference.html#the-clonable-concept>`_ 
-  - `The Clone Allocator Concept <reference.html#the-clone-allocator-concept>`_ 
-  - `Pointer container adapters <reference.html#pointer-container-adapters>`_ 
+  - `Conventions <conventions.html>`_
+  - `The Clonable Concept <reference.html#the-clonable-concept>`_
+  - `The Clone Allocator Concept <reference.html#the-clone-allocator-concept>`_
+  - `Pointer container adapters <reference.html#pointer-container-adapters>`_
  - `Sequence container classes <reference.html#sequence-containers>`_

    - `ptr_vector <ptr_vector.html>`_
@@ -47,16 +47,16 @@ and designs for dealing with OO specific problems
    - `ptr_set <ptr_set.html>`_
    - `ptr_multiset <ptr_multiset.html>`_
    - `ptr_map <ptr_map.html>`_
-    - `ptr_multimap <ptr_multimap.html>`_   
-  - `Indirected functions <indirect_fun.html>`_ 
+    - `ptr_multimap <ptr_multimap.html>`_
+  - `Indirected functions <indirect_fun.html>`_
  - `Class nullable <reference.html#class-nullable>`_
-  - `Exception classes <reference.html#exception-classes>`_         
+  - `Exception classes <reference.html#exception-classes>`_
 * `Usage guidelines`_
 * Examples_
 * `Library headers`_
 * FAQ_
-* Acknowledgements_ 
-* References_ 
+* Acknowledgements_
+* References_


 .. _Tutorial: tutorial.html
@@ -70,14 +70,14 @@ and designs for dealing with OO specific problems

 .. _`Library headers`: headers.html

-.. _FAQ: faq.html 
+.. _FAQ: faq.html


 ==========
 Motivation
 ==========

-Whenever a programmer wants to have a container of pointers to 
+Whenever a programmer wants to have a container of pointers to
 heap-allocated objects, there is usually only one exception-safe way:
 to make a container of pointer pointers like ``boost::shared_ptr``.
 This approach is suboptimal if
@@ -85,49 +85,49 @@ This approach is suboptimal if
 1. the stored objects are not shared, but owned exclusively, or
 2. the overhead implied by pointer pointers is inappropriate

-This library therefore provides standard-like containers that are for storing 
-heap-allocated or `cloned <reference.html#the-clonable-concept>`_ objects (or in case of a map, the mapped object must be 
-a heap-allocated or cloned object). For each of the standard 
-containers there is a pointer container equivalent that takes ownership of 
-the objects in an exception safe manner.  In this respect the library is intended 
-to solve the so-called 
-`polymorphic class problem <faq.html#what-is-the-polymorphic-class-problem>`_. 
+This library therefore provides standard-like containers that are for storing
+heap-allocated or `cloned <reference.html#the-clonable-concept>`_ objects (or in case of a map, the mapped object must be
+a heap-allocated or cloned object). For each of the standard
+containers there is a pointer container equivalent that takes ownership of
+the objects in an exception safe manner.  In this respect the library is intended
+to solve the so-called
+`polymorphic class problem <faq.html#what-is-the-polymorphic-class-problem>`_.


 The advantages of pointer containers are

 1. Exception-safe pointer storage and manipulation.
 2. Notational convenience compared to the use of containers of pointers.
-3. Can be used for types that are neither Assignable nor Copy Constructible. 
+3. Can be used for types that are neither Assignable nor Copy Constructible.
 4. No memory-overhead as containers of pointer pointers can have (see [11]_ and [12]_).
-5. Usually faster than using containers of pointer pointers (see [11]_ and [12]_). 
-6. The interface is slightly changed towards the domain of pointers  
+5. Usually faster than using containers of pointer pointers (see [11]_ and [12]_).
+6. The interface is slightly changed towards the domain of pointers
   instead of relying on the normal value-based interface. For example,
-   now it is possible for ``pop_back()`` to return the removed element. 
+   now it is possible for ``pop_back()`` to return the removed element.
 7. Propagates constness s.t. one cannot modify the objects via a ``const_iterator``

 The disadvantages are

-1. Less flexible than containers of pointer pointers
-  
+1. Less flexible than containers of smart pointers like `boost::shared_ptr <../../smart_ptr/shared_ptr.htm>`_
+
 ================
 Acknowledgements
 ================

 The following people have been very helpful:

- Bjørn D. Rasmussen for showing me his cr**** code that motivated me to start this library
+- Bjørn D. Rasmussen for unintentionally motivating me to start this library
 - Pavel Vozenilek for asking me to make the adapters
 - David Abrahams for the ``indirect_fun`` design
 - Pavol Droba for being review manager
 - Ross Boylan for trying out a prototype for real
 - Felipe Magno de Almeida for giving fedback based on using the
-  library in production code even before the library was part of boost  
- Jonathan Turkanis for supplying his ``move_ptr`` framework 
+  library in production code even before the library was part of boost
+- Jonathan Turkanis for supplying his ``move_ptr`` framework
  which is used internally
 - Stefan Slapeta and Howard Hinnant for Metrowerks support
 - Russell Hind for help with Borland compatibility
- Jonathan Wakely for help with GCC compatibility
+- Jonathan Wakely for his great help with GCC compatibility and bug fixes
 - Pavel Chikulaev for comments and bug-fixes

 ==========
@@ -20,7 +20,7 @@ of the interface from <tt class="docutils literal"><span class="pre">associative
 <li><a class="reference" href="reversible_ptr_container.html">reversible_ptr_container</a></li>
 <li><a class="reference" href="associative_ptr_container.html">associative_ptr_container</a></li>
 <li><a class="reference" href="ptr_multimap.html">ptr_multimap</a></li>
-<li><a class="reference" href="ptr_container.html#map-iterator-operations">new map iterators</a></li>
+<li><a class="reference" href="reference.html#map-iterator-operations">new map iterators</a></li>
 </ul>
 <p><strong>Navigate:</strong></p>
 <ul class="simple">
@@ -3,7 +3,7 @@
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.3.7: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.3.9: http://docutils.sourceforge.net/" />
 <title>Boost Pointer Container Library</title>
 <link rel="stylesheet" href="default.css" type="text/css" />
 </head>
@@ -33,48 +33,48 @@ containers from.</p>
 <p><strong>Synopsis:</strong></p>
 <pre class="literal-block">
 namespace boost
-{      
+{

    template
-    &lt; 
-        class T, 
+    &lt;
+        class T,
        class VoidPtrSeq,
        class CloneAllocator = heap_clone_allocator
    &gt;
-    class ptr_sequence_adapter 
+    class ptr_sequence_adapter
    {
    public: // <a class="reference" href="#construct-copy-destroy">construct/copy/destroy</a>
        template&lt; class InputIterator &gt;
        assign( InputIterator first, InputIterator last );
        template&lt; class InputRange &gt;
        assign( const InputRange&amp; e );
-    
+
    public: // <a class="reference" href="#element-access">element access</a>
        T&amp;        front();
        const T&amp;  front() const;
        T&amp;        back();
        const T&amp;  back() const;
-    
+
    public: // <a class="reference" href="#modifiers">modifiers</a>
        void      push_back( T* x );
        auto_type pop_back();
        iterator  insert( iterator position, T* x );
        template&lt; class InputIterator &gt;
-        void      insert( iterator position, InputIterator first, InputIterator last ); 
+        void      insert( iterator position, InputIterator first, InputIterator last );
        template&lt; class InputRange &gt;
        void      insert( iterator position, const InputRange&amp; r );
        iterator  erase( iterator position );
        iterator  erase( iterator first, iterator last );
        template&lt; class Range &gt;
        iterator  erase( const Range&amp; r );
-    
+
    public: // <a class="reference" href="#pointer-container-requirements">pointer container requirements</a>

-        void  transfer( iterator before, iterator object, 
+        void  transfer( iterator before, iterator object,
                        ptr_sequence_adapter&amp; from );
        void  transfer( iterator before, iterator first, iterator last,
                        ptr_sequence_adapter&amp; from );
-        void template&lt; class Range&gt; 
+        void template&lt; class Range&gt;
        void transfer( iterator before, const Range&amp; r, ptr_sequence_adapter&amp; from );
        void transfer( iterator before, ptr_sequence_adapter&amp; from );

@@ -105,21 +105,21 @@ namespace boost
        void merge( iterator first, iterator last, ptr_sequence_adapter&amp; from );
        template&lt; class Compare &gt;
        void merge( iterator first, iterator last, ptr_sequence_adapter&amp; from, Compare comp );
-        
+
    public: // <a class="reference" href="ptr_list.html">ptr_list interface</a>
-     
+
    public: // <a class="reference" href="ptr_vector.html">ptr_vector interface</a>

-    public: // <a class="reference" href="ptr_deque.html">ptr_deque interface</a> 
-     
+    public: // <a class="reference" href="ptr_deque.html">ptr_deque interface</a>
+
    }; //  class 'ptr_sequence_adapter'

-} // namespace 'boost'  
+} // namespace 'boost'
 </pre>
 </div>
 <div class="section" id="semantics">
 <h1><a name="semantics">Semantics</a></h1>
-<a class="target" id="construct-copy-destroy" name="construct-copy-destroy"></a><div class="section" id="semantics-construct-copy-destroy">
+<span id="construct-copy-destroy"></span><div class="section" id="semantics-construct-copy-destroy">
 <h2><a name="semantics-construct-copy-destroy">Semantics: construct/copy/destroy</a></h2>
 <ul>
 <li><p class="first"><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">InputIterator</span> <span class="pre">&gt;</span>
@@ -150,20 +150,20 @@ namespace boost

 - Exception safety: Strong guarantee -->
 <!-- void resize( size_type sz, const T& x );
-Effects: 
+Effects:

 if ( sz > size() )
    insert( end(), sz-size(), x );
    else if ( sz < size() )
    erase( begin()+sz, end() );
    else
-    ; //do nothing 
+    ; //do nothing

 Postconditions: size() == sz

 Exception safety: Strong guarantee -->
-<a class="target" id="element-access" name="element-access"></a></div>
-<div class="section" id="semantics-element-access">
+</div>
+<span id="element-access"></span><div class="section" id="semantics-element-access">
 <h2><a name="semantics-element-access">Semantics: element access</a></h2>
 <ul>
 <li><p class="first"><tt class="docutils literal"><span class="pre">T&amp;</span> <span class="pre">front();</span></tt></p>
@@ -203,8 +203,8 @@ Exception safety: Strong guarantee -->
 </blockquote>
 </li>
 </ul>
-<a class="target" id="modifiers" name="modifiers"></a></div>
-<div class="section" id="semantics-modifiers">
+</div>
+<span id="modifiers"></span><div class="section" id="semantics-modifiers">
 <h2><a name="semantics-modifiers">Semantics: modifiers</a></h2>
 <ul>
 <li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">push_back(</span> <span class="pre">T*</span> <span class="pre">x</span> <span class="pre">);</span></tt></p>
@@ -238,9 +238,9 @@ Exception safety: Strong guarantee -->
 <li><p class="first"><tt class="docutils literal"><span class="pre">iterator</span> <span class="pre">insert(</span> <span class="pre">iterator</span> <span class="pre">position,</span> <span class="pre">T*</span> <span class="pre">x</span> <span class="pre">);</span></tt></p>
 <blockquote>
 <ul class="simple">
-<li>Requirements: position is a valid iterator from the container and 
+<li>Requirements: <tt class="docutils literal"><span class="pre">position</span></tt> is a valid iterator from the container and
 <tt class="docutils literal"><span class="pre">x</span> <span class="pre">!=</span> <span class="pre">0</span></tt></li>
-<li>Effects: Inserts <tt class="docutils literal"><span class="pre">x</span></tt> before position and returns an iterator pointing to it</li>
+<li>Effects: Inserts <tt class="docutils literal"><span class="pre">x</span></tt> before <tt class="docutils literal"><span class="pre">position</span></tt> and returns an iterator pointing to it</li>
 <li>Throws: <tt class="docutils literal"><span class="pre">bad_pointer</span></tt> if <tt class="docutils literal"><span class="pre">x</span> <span class="pre">==</span> <span class="pre">0</span></tt></li>
 <li>Exception safety: Strong guarantee</li>
 </ul>
@@ -259,7 +259,7 @@ Exception safety: Strong guarantee -->

 - Requirements: ``position`` is a valid iterator from the container

- Effects: Inserts ``n`` clones of ``x`` before position into the container 
+- Effects: Inserts ``n`` clones of ``x`` before position into the container

 - Exception safety: Strong guarantee -->
 <ul>
@@ -308,15 +308,20 @@ Exception safety: Strong guarantee -->
 </blockquote>
 </li>
 </ul>
-<a class="target" id="pointer-container-requirements" name="pointer-container-requirements"></a></div>
-<div class="section" id="semantics-pointer-container-requirements">
+</div>
+<span id="pointer-container-requirements"></span><div class="section" id="semantics-pointer-container-requirements">
 <h2><a name="semantics-pointer-container-requirements">Semantics: pointer container requirements</a></h2>
+<p>You cannot use <tt class="docutils literal"><span class="pre">transfer()</span></tt> to move elements between two
+different types of containers. This is to avoid
+problems with different allocators. The requirement might be
+weakened in the future.</p>
 <ul>
 <li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">transfer(</span> <span class="pre">iterator</span> <span class="pre">before,</span> <span class="pre">iterator</span> <span class="pre">object,</span> <span class="pre">ptr_sequence_adapter&amp;</span> <span class="pre">from</span> <span class="pre">);</span></tt></p>
 <blockquote>
 <ul class="simple">
 <li>Requirements: <tt class="docutils literal"><span class="pre">not</span> <span class="pre">from.empty()</span></tt></li>
-<li>Effects: Inserts the object defined by <tt class="docutils literal"><span class="pre">object</span></tt> into the container and remove it from <tt class="docutils literal"><span class="pre">from</span></tt>.</li>
+<li>Effects: Inserts the object defined by <tt class="docutils literal"><span class="pre">object</span></tt> into the container and remove it from <tt class="docutils literal"><span class="pre">from</span></tt>.
+Insertion takes place before <tt class="docutils literal"><span class="pre">before</span></tt>.</li>
 <li>Postconditions: <tt class="docutils literal"><span class="pre">size()</span></tt> is one more, <tt class="docutils literal"><span class="pre">from.size()</span></tt> is one less.</li>
 <li>Exception safety: Strong guarantee</li>
 </ul>
@@ -326,7 +331,8 @@ Exception safety: Strong guarantee -->
 <blockquote>
 <ul class="simple">
 <li>Requirements: <tt class="docutils literal"><span class="pre">not</span> <span class="pre">from.empty()</span></tt></li>
-<li>Effects: Inserts the objects defined by the range <tt class="docutils literal"><span class="pre">[first,last)</span></tt> into the container and remove it from <tt class="docutils literal"><span class="pre">from</span></tt>.</li>
+<li>Effects: Inserts the objects defined by the range <tt class="docutils literal"><span class="pre">[first,last)</span></tt> into the container and remove it from <tt class="docutils literal"><span class="pre">from</span></tt>.
+Insertion takes place before <tt class="docutils literal"><span class="pre">before</span></tt>.</li>
 <li>Postconditions: Let <tt class="docutils literal"><span class="pre">N</span> <span class="pre">==</span> <span class="pre">std::distance(first,last);</span></tt> then <tt class="docutils literal"><span class="pre">size()</span></tt> is <tt class="docutils literal"><span class="pre">N</span></tt> more, <tt class="docutils literal"><span class="pre">from.size()</span></tt> is <tt class="docutils literal"><span class="pre">N</span></tt> less.</li>
 <li>Exception safety: Strong guarantee</li>
 </ul>
@@ -350,8 +356,8 @@ takes place before <tt class="docutils literal"><span class="pre">before</span><
 </blockquote>
 </li>
 </ul>
-<a class="target" id="algorithms" name="algorithms"></a></div>
-<div class="section" id="semantics-algorithms">
+</div>
+<span id="algorithms"></span><div class="section" id="semantics-algorithms">
 <h2><a name="semantics-algorithms">Semantics: algorithms</a></h2>
 <p>The general requirement for these algorithms is that the container <em>does not
 contain any nulls</em>.</p>
@@ -1,7 +1,7 @@
 ++++++++++++++++++++++++++++++++++
 |Boost| Pointer Container Library
 ++++++++++++++++++++++++++++++++++
- 
+
 .. |Boost| image:: cboost.gif

 Class ``ptr_sequence_adapter``
@@ -14,9 +14,9 @@ sequences:
 - ptr_list_,
 - ptr_deque_,

-.. _ptr_vector : ptr_vector.html 
-.. _ptr_list : ptr_list.html 
-.. _ptr_deque : ptr_deque.html 
+.. _ptr_vector : ptr_vector.html
+.. _ptr_list : ptr_list.html
+.. _ptr_deque : ptr_deque.html


 The ``ptr_sequence_adapter`` is also a concrete class that you can use to create custom pointer
@@ -26,7 +26,7 @@ containers from.

 - reversible_ptr_container__

-__ reversible_ptr_container.html  
+__ reversible_ptr_container.html

 **Navigate:**

@@ -36,51 +36,51 @@ __ reversible_ptr_container.html

 **Synopsis:**

-.. parsed-literal::  
-           
+.. parsed-literal::
+
        namespace boost
-        {      
-        
+        {
+
            template
-            < 
-                class T, 
+            <
+                class T,
                class VoidPtrSeq,
                class CloneAllocator = heap_clone_allocator
            >
-            class ptr_sequence_adapter 
+            class ptr_sequence_adapter
            {
            public: // `construct/copy/destroy`_
                template< class InputIterator >
                assign( InputIterator first, InputIterator last );
                template< class InputRange >
                assign( const InputRange& e );
-            
+
            public: // `element access`_
                T&        front();
                const T&  front() const;
                T&        back();
                const T&  back() const;
-            
+
            public: // `modifiers`_
                void      push_back( T* x );
                auto_type pop_back();
                iterator  insert( iterator position, T* x );
                template< class InputIterator >
-                void      insert( iterator position, InputIterator first, InputIterator last ); 
+                void      insert( iterator position, InputIterator first, InputIterator last );
                template< class InputRange >
                void      insert( iterator position, const InputRange& r );
                iterator  erase( iterator position );
                iterator  erase( iterator first, iterator last );
                template< class Range >
                iterator  erase( const Range& r );
-            
+
            public: // `pointer container requirements`_
-   
-                void  transfer( iterator before, iterator object, 
+
+                void  transfer( iterator before, iterator object,
                                ptr_sequence_adapter& from );
                void  transfer( iterator before, iterator first, iterator last,
                                ptr_sequence_adapter& from );
-                void template< class Range> 
+                void template< class Range>
                void transfer( iterator before, const Range& r, ptr_sequence_adapter& from );
                void transfer( iterator before, ptr_sequence_adapter& from );

@@ -111,16 +111,16 @@ __ reversible_ptr_container.html
                void merge( iterator first, iterator last, ptr_sequence_adapter& from );
                template< class Compare >
                void merge( iterator first, iterator last, ptr_sequence_adapter& from, Compare comp );
-                
+
            public: // `ptr_list interface`_
-             
+
            public: // `ptr_vector interface`_

-            public: // `ptr_deque interface`_ 
-             
+            public: // `ptr_deque interface`_
+
            }; //  class 'ptr_sequence_adapter'
-        
-        } // namespace 'boost'  
+
+        } // namespace 'boost'

 .. _`ptr_list interface`: ptr_list.html
 .. _`ptr_vector interface`: ptr_vector.html
@@ -153,27 +153,27 @@ Semantics: construct/copy/destroy

 ..
        - ``assign( size_type n, const T& u )``
-    
+
        - Effects: ``clear(); insert( begin(), n, u );``
-    
+
        - Postconditions: ``size() == n``
-    
+
        - Exception safety: Strong guarantee


-.. 
+..
        void resize( size_type sz, const T& x );
-        Effects: 
-        
+        Effects:
+
        if ( sz > size() )
            insert( end(), sz-size(), x );
            else if ( sz < size() )
            erase( begin()+sz, end() );
            else
-            ; //do nothing 
-        
+            ; //do nothing
+
        Postconditions: size() == sz
-        
+
        Exception safety: Strong guarantee


@@ -232,9 +232,9 @@ Semantics: modifiers

 ..
        - ``void push_back( const T& x );``
-    
+
        - Effects: ``push_back( CloneAllocator::clone( x ) );``
-    
+
        - Exception safety: Strong guarantee

 - ``auto_type pop_back();``
@@ -246,16 +246,16 @@ Semantics: modifiers
    - Postconditions: ``size()`` is one less

    - Throws: ``bad_ptr_container_operation`` if ``empty() == true``
-    
+
    - Exception safety: Strong guarantee


 - ``iterator insert( iterator position, T* x );``

-    - Requirements: position is a valid iterator from the container and 
+    - Requirements: ``position`` is a valid iterator from the container and
      ``x != 0``

-    - Effects: Inserts ``x`` before position and returns an iterator pointing to it
+    - Effects: Inserts ``x`` before ``position`` and returns an iterator pointing to it

    - Throws: ``bad_pointer`` if ``x == 0``

@@ -263,19 +263,19 @@ Semantics: modifiers

 ..
        - ``iterator insert( iterator position, const T& x );``
-    
+
        - Requirements: ``position`` is a valid iterator from the container
-    
+
        - Effects: ``return insert( position, CloneAllocator::clone( x ) );``
-    
+
        - Exception safety: Strong guarantee

        - ``void insert( iterator position, size_type n, const T& x );``
-    
+
        - Requirements: ``position`` is a valid iterator from the container
-    
-        - Effects: Inserts ``n`` clones of ``x`` before position into the container 
-    
+
+        - Effects: Inserts ``n`` clones of ``x`` before position into the container
+
        - Exception safety: Strong guarantee

 - ``template< class InputIterator >
@@ -318,21 +318,30 @@ Semantics: modifiers
 Semantics: pointer container requirements
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

+You cannot use ``transfer()`` to move elements between two
+different types of containers. This is to avoid
+problems with different allocators. The requirement might be
+weakened in the future.
+
+
 - ``void transfer( iterator before, iterator object, ptr_sequence_adapter& from );``

    - Requirements: ``not from.empty()``

    - Effects: Inserts the object defined by ``object`` into the container and remove it from ``from``.
+      Insertion takes place before ``before``.

    - Postconditions: ``size()`` is one more, ``from.size()`` is one less.

    - Exception safety: Strong guarantee

+
 - ``void transfer( iterator before, iterator first, iterator last, ptr_sequence_adapter& from );``

    - Requirements: ``not from.empty()``

    - Effects: Inserts the objects defined by the range ``[first,last)`` into the container and remove it from ``from``.
+      Insertion takes place before ``before``.

    - Postconditions: Let ``N == std::distance(first,last);`` then ``size()`` is ``N`` more, ``from.size()`` is ``N`` less.

@@ -341,7 +350,7 @@ Semantics: pointer container requirements
 - ``template< class Range> void transfer( iterator before, const Range& r, ptr_sequence_adapter& from );``

    - Effects: ``transfer(before, boost::begin(r), boost::end(r), from);``
-    
+
 - ``void transfer( iterator before, ptr_sequence_adapter& from );``

    - Effects: Transfers all objects from ``from`` into the container. Insertion
@@ -369,7 +378,7 @@ contain any nulls*.
    - Effects: sorts the entire container or the specified range
    - Exception safety: nothrow guarantee (the behavior is undefined if the comparison operator throws)
    - Remarks: The versions of ``sort()`` that take two iterators are not available for ``ptr_list``
-    
+
 - ``void unique();``
 - ``void unique( iterator first, iterator last );``
 - ``template< class Compare > void unique( Compare comp );``
@@ -3,7 +3,7 @@
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.3.7: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.3.9: http://docutils.sourceforge.net/" />
 <title>Boost Pointer Container Library</title>
 <link rel="stylesheet" href="default.css" type="text/css" />
 </head>
@@ -50,7 +50,7 @@ the <a class="reference" href="reference.html#the-clone-allocator-concept">Clone
 <li><a class="reference" href="#class-nullable">Class nullable</a></li>
 <li><a class="reference" href="#exception-classes">Exception classes</a></li>
 </ul>
-<div class="section" id="the-clonable-concept">
+<div class="section" id="the-clonable-concept_">
 <h1><a name="the-clonable-concept">The Clonable concept</a></h1>
 <p><strong>Refinement of</strong></p>
 <ul class="simple">
@@ -3,7 +3,7 @@
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.3.7: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.3.9: http://docutils.sourceforge.net/" />
 <title>Boost Pointer Container Library</title>
 <link rel="stylesheet" href="default.css" type="text/css" />
 </head>
@@ -105,26 +105,26 @@ namespace boost
    template &lt; class T,  class CA, class VPC &gt;
    bool operator&lt;=( const reversible_ptr_container&lt;T,CA,VPC&gt;&amp; x,
                     const reversible_ptr_container&lt;T,CA,VPC&gt;&amp; y);
-    
+
    template&lt; class T,  class CA, class VPC  &gt;
-    void swap( reversible_ptr_container&lt;T,CA,VPC&gt;&amp; x, 
+    void swap( reversible_ptr_container&lt;T,CA,VPC&gt;&amp; x,
               reversible_ptr_container&lt;T,CA,VPC&gt;&amp; y );

    // <a class="reference" href="#clonability">clonability</a>
    template&lt; class T,  class CA, class VPC &gt;
-    reversible_ptr_container&lt;T,CA,VPC&gt;* 
+    reversible_ptr_container&lt;T,CA,VPC&gt;*
    new_clone( const reversible_ptr_container&lt;T,CA,VPC&gt;&amp; r );

    // <a class="reference" href="#null-predicate">null predicate</a>
    template&lt; class Iterator &gt;
    bool is_null( Iterator i );

-} // namespace 'boost'  
+} // namespace 'boost'
 </pre>
 </div>
 <div class="section" id="semantics">
 <h1><a name="semantics">Semantics</a></h1>
-<a class="target" id="typedefs" name="typedefs"></a><div class="section" id="semantics-typedefs">
+<span id="typedefs"></span><div class="section" id="semantics-typedefs">
 <h2><a name="semantics-typedefs">Semantics: typedefs</a></h2>
 <p>Notice how these two types differ:</p>
 <ul>
@@ -159,7 +159,7 @@ iterator i = ...;
 i.base();
 </pre>
 <p>returns an iterator that allows one to iterate over <tt class="docutils literal"><span class="pre">void*</span></tt>
-elements (<em>this is very rarely needed and you should not use that
+elements (<em>this is very rarely needed and you should not use the
 functionality unless you know what you are doing</em>).</p>
 <ul class="simple">
 <li><tt class="docutils literal"><span class="pre">typedef</span> <span class="pre">...</span> <span class="pre">auto_type</span></tt></li>
@@ -170,12 +170,12 @@ operations:</p>
 T* operator-&gt;() const;
 T&amp; operator*() const;
 T* release();
-~auto_type();    
+~auto_type();
 </pre>
 <p>The destructor will delete the stored object. It might help to
 think it is just an <tt class="docutils literal"><span class="pre">std::auto_ptr&lt;T&gt;</span></tt>.</p>
-<a class="target" id="construct-copy-destroy" name="construct-copy-destroy"></a></div>
-<div class="section" id="semantics-construct-copy-destroy">
+</div>
+<span id="construct-copy-destroy"></span><div class="section" id="semantics-construct-copy-destroy">
 <h2><a name="semantics-construct-copy-destroy">Semantics: construct/copy/destroy</a></h2>
 <ul>
 <li><p class="first"><tt class="docutils literal"><span class="pre">reversible_ptr_container();</span></tt></p>
@@ -234,9 +234,10 @@ think it is just an <tt class="docutils literal"><span class="pre">std::auto_ptr
 </blockquote>
 </li>
 </ul>
-<a class="target" id="iterators" name="iterators"></a></div>
-<div class="section" id="semantics-iterators">
+</div>
+<span id="iterators"></span><div class="section" id="semantics-iterators">
 <h2><a name="semantics-iterators">Semantics: iterators</a></h2>
+<p><strong>See also:</strong> <a class="reference" href="conventions.html#iterators-are-invalidated-as-in-the-corresponding-standard-container">iterator invalidation</a></p>
 <ul>
 <li><p class="first"><tt class="docutils literal"><span class="pre">iterator</span> <span class="pre">begin();</span></tt></p>
 </li>
@@ -279,8 +280,8 @@ think it is just an <tt class="docutils literal"><span class="pre">std::auto_ptr
 </blockquote>
 </li>
 </ul>
-<a class="target" id="capacity" name="capacity"></a></div>
-<div class="section" id="semantics-capacity">
+</div>
+<span id="capacity"></span><div class="section" id="semantics-capacity">
 <h2><a name="semantics-capacity">Semantics: capacity</a></h2>
 <ul>
 <li><p class="first"><tt class="docutils literal"><span class="pre">size_type</span> <span class="pre">size()</span> <span class="pre">const;</span></tt></p>
@@ -308,8 +309,8 @@ think it is just an <tt class="docutils literal"><span class="pre">std::auto_ptr
 </blockquote>
 </li>
 </ul>
-<a class="target" id="modifiers" name="modifiers"></a></div>
-<div class="section" id="semantics-modifiers">
+</div>
+<span id="modifiers"></span><div class="section" id="semantics-modifiers">
 <h2><a name="semantics-modifiers">Semantics: modifiers</a></h2>
 <ul>
 <li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">swap(</span> <span class="pre">reversible_ptr_container&amp;</span> <span class="pre">r</span> <span class="pre">);</span></tt></p>
@@ -330,8 +331,8 @@ think it is just an <tt class="docutils literal"><span class="pre">std::auto_ptr
 </blockquote>
 </li>
 </ul>
-<a class="target" id="pointer-container-requirements" name="pointer-container-requirements"></a></div>
-<div class="section" id="semantics-pointer-container-requirements">
+</div>
+<span id="pointer-container-requirements"></span><div class="section" id="semantics-pointer-container-requirements">
 <h2><a name="semantics-pointer-container-requirements">Semantics: pointer container requirements</a></h2>
 <ul>
 <li><p class="first"><tt class="docutils literal"><span class="pre">auto_type</span> <span class="pre">replace(</span> <span class="pre">iterator</span> <span class="pre">position,</span> <span class="pre">T*</span> <span class="pre">x</span> <span class="pre">);</span></tt></p>
@@ -375,8 +376,8 @@ think it is just an <tt class="docutils literal"><span class="pre">std::auto_ptr
 </blockquote>
 </li>
 </ul>
-<a class="target" id="comparison" name="comparison"></a></div>
-<div class="section" id="semantics-comparison">
+</div>
+<span id="comparison"></span><div class="section" id="semantics-comparison">
 <h2><a name="semantics-comparison">Semantics: comparison</a></h2>
 <p>These functions compare the underlying range of objects. 
 So</p>
@@ -385,8 +386,8 @@ operation( const ptr_container&amp; l, const ptr_container&amp; r );
 </pre>
 <p>has the effect one would expect of normal standard containers. Hence
 objects are compared and not the pointers to objects.</p>
-<a class="target" id="clonability" name="clonability"></a></div>
-<div class="section" id="semantics-clonability">
+</div>
+<span id="clonability"></span><div class="section" id="semantics-clonability">
 <h2><a name="semantics-clonability">Semantics: clonability</a></h2>
 <ul>
 <li><p class="first"><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">T,</span> <span class="pre">class</span> <span class="pre">CloneAllocator</span> <span class="pre">&gt;</span>
@@ -395,14 +396,14 @@ objects are compared and not the pointers to objects.</p>
 <blockquote>
 <ul class="simple">
 <li>Effects: <tt class="docutils literal"><span class="pre">return</span> <span class="pre">r.clone().release();</span></tt></li>
-<li>Remarks: This function is only defined for concrete <a class="reference" href="ptr_container.html#smart-containers">pointer containers</a>, but not for 
-<a class="reference" href="ptr_container.html#smart-container-adapters">pointer container adapters</a>.</li>
+<li>Remarks: This function is only defined for concrete <a class="reference" href="reference.html#pointer-containers">pointer containers</a>, but not for 
+<a class="reference" href="reference.html#pointer-container-adapters">pointer container adapters</a>.</li>
 </ul>
 </blockquote>
 </li>
 </ul>
-<a class="target" id="null-predicate" name="null-predicate"></a></div>
-<div class="section" id="semantics-null-predicate">
+</div>
+<span id="null-predicate"></span><div class="section" id="semantics-null-predicate">
 <h2><a name="semantics-null-predicate">Semantics: null predicate</a></h2>
 <ul>
 <li><p class="first"><tt class="docutils literal"><span class="pre">template&lt;</span> <span class="pre">class</span> <span class="pre">Iterator</span> <span class="pre">&gt;</span> <span class="pre">bool</span> <span class="pre">is_null(</span> <span class="pre">Iterator</span> <span class="pre">i</span> <span class="pre">);</span></tt></p>
@@ -103,21 +103,21 @@ Its purpose is to present the general interface of all the pointer containers.
            template < class T,  class CA, class VPC >
            bool operator<=( const reversible_ptr_container<T,CA,VPC>& x,
                             const reversible_ptr_container<T,CA,VPC>& y);
-            
+
            template< class T,  class CA, class VPC  >
-            void swap( reversible_ptr_container<T,CA,VPC>& x, 
+            void swap( reversible_ptr_container<T,CA,VPC>& x,
                       reversible_ptr_container<T,CA,VPC>& y );

            // clonability_
            template< class T,  class CA, class VPC >
-            reversible_ptr_container<T,CA,VPC>* 
+            reversible_ptr_container<T,CA,VPC>*
            new_clone( const reversible_ptr_container<T,CA,VPC>& r );

            // `null predicate`_
            template< class Iterator >
            bool is_null( Iterator i );
-     
-        } // namespace 'boost'  
+
+        } // namespace 'boost'



@@ -132,7 +132,7 @@ Semantics: typedefs
 Notice how these two types differ:


- ``typedef T* value_type;`` 
+- ``typedef T* value_type;``

    - notice this has pointer type

@@ -143,7 +143,7 @@ Notice how these two types differ:
 This is done to be able to add pointers directly
 to the container, but to hide the pointers externally.

-.. 
+..
        - ``typedef *implementation defined* object_type;``
        - this is ``T`` for sequences and sets
        - this is ``std::pair<const Key, void*>`` for maps
@@ -160,7 +160,7 @@ Note that::

 returns an iterator that allows one to iterate over ``void*``
 elements (*this is very rarely needed and you should not use the
-functionality unless you know what you are doing*).    
+functionality unless you know what you are doing*).

 - ``typedef ... auto_type``

@@ -170,7 +170,7 @@ operations::
    T* operator->() const;
    T& operator*() const;
    T* release();
-    ~auto_type();    
+    ~auto_type();

 The destructor will delete the stored object. It might help to
 think it is just an ``std::auto_ptr<T>``.
@@ -188,16 +188,16 @@ Semantics: construct/copy/destroy

 ..
        - ``reversible_ptr_container( size_type n, const T& x );``
-    
+
        - Effects: Constructs a container with ``n`` clones of ``x``
-    
+
        - Postconditions: ``size() == n``

 - ``explicit reversible_ptr_container( std::auto_ptr< reversible_ptr_container > r );``

    - Effects: Constructs a container by taking ownership of the supplied pointers

- 
+
 - ``template< class InputIterator >``
  ``reversible_ptr_container( InputIterator first, InputIterator last );``

@@ -229,6 +229,8 @@ Semantics: construct/copy/destroy
 Semantics: iterators
 ^^^^^^^^^^^^^^^^^^^^

+**See also:** `iterator invalidation <conventions.html#iterators-are-invalidated-as-in-the-corresponding-standard-container>`_
+
 - ``iterator begin();``
 - ``const_iterator begin() const;``

@@ -248,7 +250,7 @@ Semantics: iterators
 - ``const_reverse_iterator rbegin() const;``

    - Effects: Returns a mutable/non-mutable reverse iterator with ``value_type T``
- 
+
    - Throws: Nothing

 - ``reverse_iterator rend();``