Merge branch 'develop'

# Conflicts:
#	include/boost/iterator/reverse_iterator.hpp

.travis.yml

@@ -0,0 +1,40 @@
+# Copyright 2016 Peter Dimov
+# Distributed under the Boost Software License, Version 1.0.
+# (See accompanying file LICENSE_1_0.txt or copy at http://boost.org/LICENSE_1_0.txt)
+
+language: cpp
+
+sudo: false
+
+python: "2.7"
+
+os:
+  - linux
+  - osx
+
+branches:
+  only:
+    - master
+    - develop
+
+install:
+  - cd ..
+  - git clone -b $TRAVIS_BRANCH --depth 1 https://github.com/boostorg/boost.git boost-root
+  - cd boost-root
+  - git submodule update --init --depth 1 tools/build
+  - git submodule update --init --depth 1 libs/config
+  - git submodule update --init --depth 1 tools/boostdep
+  - cp -r $TRAVIS_BUILD_DIR/* libs/iterator
+  - python tools/boostdep/depinst/depinst.py iterator
+  - ./bootstrap.sh
+  - ./b2 headers
+
+script:
+  - TOOLSET=gcc,clang
+  - if [ $TRAVIS_OS_NAME == osx ]; then TOOLSET=clang; fi
+  - ./b2 --verbose-test libs/config/test//config_info toolset=$TOOLSET || true
+  - ./b2 libs/iterator/test toolset=$TOOLSET
+
+notifications:
+  email:
+    on_success: always

development/boost/iterator_categories.hpp

@@ -1,159 +0,0 @@
-#ifndef BOOST_ITERATOR_CATEGORIES_HPP
-#define BOOST_ITERATOR_CATEGORIES_HPP
-
-#include <boost/config.hpp>
-#include <boost/type_traits/conversion_traits.hpp>
-#include <boost/type_traits/cv_traits.hpp>
-#include <boost/pending/ct_if.hpp>
-#include <boost/detail/iterator.hpp>
-
-namespace boost {
-
-  // Return Type Categories
-  struct readable_iterator_tag { };
-  struct writable_iterator_tag { };
-  struct swappable_iterator_tag { };
-  struct mutable_lvalue_iterator_tag : 
-    virtual public writable_iterator_tag,
-    virtual public readable_iterator_tag { };
-  struct constant_lvalue_iterator_tag : 
-    virtual public readable_iterator_tag { };
-
-  // Traversal Categories
-  struct forward_traversal_tag { };
-  struct bidirectional_traversal_tag : public forward_traversal_tag { };
-  struct random_access_traversal_tag : public bidirectional_traversal_tag { };
-
-  struct error_iterator_tag { };
-
-  // Inherit from iterator_base if your iterator defines its own
-  // return_category and traversal_category. Otherwise, the "old style"
-  // iterator category will be mapped to the return_category and
-  // traversal_category.
-  struct new_iterator_base { };
-
-  namespace detail {
-
-    struct return_category_from_nested_type {
-      template <typename Iterator> struct bind {
-        typedef typename Iterator::return_category type;
-      };
-    };
-
-    struct traversal_category_from_nested_type {
-      template <typename Iterator> struct bind {
-        typedef typename Iterator::traversal_category type;
-      };
-    };
-
-    template <typename ValueType>
-    struct choose_lvalue_return {
-      typedef typename ct_if<is_const<ValueType>::value,
-                             boost::constant_lvalue_iterator_tag,
-                             boost::mutable_lvalue_iterator_tag>::type type;
-    };
-    
-    
-    template <typename Category, typename ValueType>
-    struct iter_category_to_return {
-      typedef typename ct_if<
-        is_convertible<Category*, std::forward_iterator_tag*>::value,
-        typename choose_lvalue_return<ValueType>::type,
-        typename ct_if<
-          is_convertible<Category*, std::input_iterator_tag*>::value,
-          boost::readable_iterator_tag,
-          typename ct_if<
-            is_convertible<Category*, std::output_iterator_tag*>::value,
-            boost::writable_iterator_tag,
-            boost::error_iterator_tag
-          >::type
-       >::type
-      >::type type;
-    };
-
-    template <typename Category>
-    struct iter_category_to_traversal {
-      typedef typename ct_if<
-        is_convertible<Category*, std::random_access_iterator_tag*>::value,
-        random_access_traversal_tag,
-        typename ct_if<
-          is_convertible<Category*, std::bidirectional_iterator_tag*>::value,
-          bidirectional_traversal_tag,
-          forward_traversal_tag
-          >::type
-        >::type type;
-    };
-
-    struct return_category_from_old_traits {
-      template <typename Iterator> class bind {
-        typedef boost::detail::iterator_traits<Iterator> OldTraits;
-        typedef typename OldTraits::iterator_category Cat;
-        typedef typename OldTraits::value_type value_type;
-      public:
-        typedef iter_category_to_return<Cat, value_type>::type type;
-      };      
-    };
-
-    struct traversal_category_from_old_traits {
-      template <typename Iterator> class bind {
-        typedef boost::detail::iterator_traits<Iterator> OldTraits;
-        typedef typename OldTraits::iterator_category Cat;
-      public:
-        typedef iter_category_to_traversal<Cat>::type type;
-      };      
-    };
-
-    template <typename Iterator>
-    class choose_return_category {
-      typedef typename ct_if<is_convertible<Iterator*,
-                                            new_iterator_base*>::value,
-                             return_category_from_nested_type,
-                             return_category_from_old_traits>::type Choice;
-    public:
-      typedef typename Choice:: template bind<Iterator>::type type;
-    };
-
-    template <typename Iterator>
-    class choose_traversal_category {
-      typedef typename ct_if<is_convertible<Iterator*,
-                                            new_iterator_base*>::value,
-                             traversal_category_from_nested_type,
-                             traversal_category_from_old_traits>::type Choice;
-    public:
-      typedef typename Choice:: template bind<Iterator>::type type;
-    };
-    
-  } // namespace detail
-  
-  template <class Iterator>
-  struct return_category {
-    typedef typename detail::choose_return_category<Iterator>::type type;
-  };
-
-
-  template <class Iterator>
-  struct traversal_category {
-    typedef typename detail::choose_traversal_category<Iterator>::type type;
-  };
-
-#if !defined(BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION)
-
-  template <typename T>
-  struct return_category<T*>
-  {
-    typedef typename ct_if<is_const<T>::value,
-      constant_lvalue_iterator_tag,
-      mutable_lvalue_iterator_tag>::type type;
-  };
-
-  template <typename T>
-  struct traversal_category<T*>
-  {
-    typedef random_access_traversal_tag type;
-  };
-
-#endif
-
-} // namespace boost
-
-#endif // BOOST_ITERATOR_CATEGORIES_HPP

development/boost/iterator_concepts.hpp

@@ -1,172 +0,0 @@
-#ifndef BOOST_ITERATOR_CONCEPTS_HPP
-#define BOOST_ITERATOR_CONCEPTS_HPP
-
-#include <boost/concept_check.hpp>
-#include <boost/iterator_categories.hpp>
-#include <boost/type_traits/conversion_traits.hpp>
-#include <boost/static_assert.hpp>
-
-namespace boost_concepts {
-  // Used a different namespace here (instead of "boost") so that the
-  // concept descriptions do not take for granted the names in
-  // namespace boost.
-
-
-  //===========================================================================
-  // Iterator Access Concepts
-
-  template <typename Iterator>
-  class ReadableIteratorConcept {
-  public:
-    typedef typename std::iterator_traits<Iterator>::value_type value_type;
-    typedef typename std::iterator_traits<Iterator>::reference reference;
-    typedef typename boost::return_category<Iterator>::type return_category;
-
-    void constraints() {
-      boost::function_requires< boost::SGIAssignableConcept<Iterator> >();
-      boost::function_requires< boost::EqualityComparableConcept<Iterator> >();
-      boost::function_requires< 
-        boost::DefaultConstructibleConcept<Iterator> >();
-      
-      BOOST_STATIC_ASSERT((boost::is_convertible<return_category*,
-                           boost::readable_iterator_tag*>::value));
-                          
-      reference r = *i; // or perhaps read(x)
-      value_type v(r);
-      boost::ignore_unused_variable_warning(v);
-    }
-    Iterator i;
-  };
-  
-  template <typename Iterator, typename ValueType>
-  class WritableIteratorConcept {
-  public:
-    typedef typename boost::return_category<Iterator>::type return_category;
-
-    void constraints() {
-      boost::function_requires< boost::SGIAssignableConcept<Iterator> >();
-      boost::function_requires< boost::EqualityComparableConcept<Iterator> >();
-      boost::function_requires< 
-        boost::DefaultConstructibleConcept<Iterator> >();
-      
-      BOOST_STATIC_ASSERT((boost::is_convertible<return_category*,
-                           boost::writable_iterator_tag*>::value));
-
-      *i = v; // a good alternative could be something like write(x, v)
-    }
-    ValueType v;
-    Iterator i;
-  };
-  
-  template <typename Iterator>
-  class ConstantLvalueIteratorConcept {
-  public:
-    typedef typename std::iterator_traits<Iterator>::value_type value_type;
-    typedef typename std::iterator_traits<Iterator>::reference reference;
-    typedef typename boost::return_category<Iterator>::type return_category;
-
-    void constraints() {
-      boost::function_requires< ReadableIteratorConcept<Iterator> >();
-
-      BOOST_STATIC_ASSERT((boost::is_convertible<return_category*, 
-                           boost::constant_lvalue_iterator_tag*>::value));
-
-      BOOST_STATIC_ASSERT((boost::is_same<reference, 
-                           const value_type&>::value));
-
-      reference v = *i;
-      boost::ignore_unused_variable_warning(v);
-    }
-    Iterator i;
-  };
-
-  template <typename Iterator>
-  class MutableLvalueIteratorConcept {
-  public:
-    typedef typename std::iterator_traits<Iterator>::value_type value_type;
-    typedef typename std::iterator_traits<Iterator>::reference reference;
-    typedef typename boost::return_category<Iterator>::type return_category;
-
-    void constraints() {
-      boost::function_requires< ReadableIteratorConcept<Iterator> >();
-      boost::function_requires< 
-        WritableIteratorConcept<Iterator, value_type> >();
-      
-      BOOST_STATIC_ASSERT((boost::is_convertible<return_category*, 
-                           boost::mutable_lvalue_iterator_tag*>::value));
-
-      BOOST_STATIC_ASSERT((boost::is_same<reference, value_type&>::value));
-
-      reference v = *i;
-      boost::ignore_unused_variable_warning(v);
-    }
-    Iterator i;
-  };
-  
-  //===========================================================================
-  // Iterator Traversal Concepts
-
-  template <typename Iterator>
-  class ForwardIteratorConcept {
-  public:
-    typedef typename boost::traversal_category<Iterator>::type traversal_category;
-
-    void constraints() {
-      boost::function_requires< boost::SGIAssignableConcept<Iterator> >();
-      boost::function_requires< boost::EqualityComparableConcept<Iterator> >();
-      boost::function_requires< 
-        boost::DefaultConstructibleConcept<Iterator> >();
-
-      BOOST_STATIC_ASSERT((boost::is_convertible<traversal_category*, 
-                           boost::forward_traversal_tag*>::value));
-      ++i;
-      (void)i++;
-    }
-    Iterator i;
-  };
-  
-  template <typename Iterator>
-  class BidirectionalIteratorConcept {
-  public:
-    typedef typename boost::traversal_category<Iterator>::type traversal_category;
-
-    void constraints() {
-      boost::function_requires< ForwardIteratorConcept<Iterator> >();
-      
-      BOOST_STATIC_ASSERT((boost::is_convertible<traversal_category*, 
-                           boost::bidirectional_traversal_tag*>::value));
-
-      --i;
-      (void)i--;
-    }
-    Iterator i;
-  };
-
-  template <typename Iterator>
-  class RandomAccessIteratorConcept {
-  public:
-    typedef typename boost::traversal_category<Iterator>::type traversal_category;
-    typedef typename std::iterator_traits<Iterator>::difference_type
-      difference_type;
-
-    void constraints() {
-      boost::function_requires< BidirectionalIteratorConcept<Iterator> >();
-
-      BOOST_STATIC_ASSERT((boost::is_convertible<traversal_category*, 
-                           boost::random_access_traversal_tag*>::value));
-      
-      i += n;
-      i = i + n;
-      i = n + i;
-      i -= n;
-      i = i - n;
-      n = i - j;
-    }
-    difference_type n;
-    Iterator i, j;
-  };
-
-} // namespace boost_concepts
-
-
-#endif // BOOST_ITERATOR_CONCEPTS_HPP

development/libs/iterator/concept_tests.cpp

@@ -1,73 +0,0 @@
-#include <boost/iterator_concepts.hpp>
-#include <boost/operators.hpp>
-
-struct new_iterator
-  : public boost::iterator<std::random_access_iterator_tag, int>,
-    public boost::new_iterator_base
-{
-  typedef boost::random_access_traversal_tag traversal_category;
-  typedef boost::mutable_lvalue_iterator_tag return_category;
-
-  int& operator*() const { return *m_x; }
-  new_iterator& operator++() { return *this; }
-  new_iterator operator++(int) { return *this; }
-  new_iterator& operator--() { return *this; }
-  new_iterator operator--(int) { return *this; }
-  new_iterator& operator+=(std::ptrdiff_t) { return *this; }
-  new_iterator operator+(std::ptrdiff_t) { return *this; }
-  new_iterator& operator-=(std::ptrdiff_t) { return *this; }
-  std::ptrdiff_t operator-(const new_iterator&) const { return 0; }
-  new_iterator operator-(std::ptrdiff_t) const { return *this; }
-  bool operator==(const new_iterator&) const { return false; }
-  bool operator!=(const new_iterator&) const { return false; }
-  bool operator<(const new_iterator&) const { return false; }
-  int* m_x;
-};
-new_iterator operator+(std::ptrdiff_t, new_iterator x) { return x; }
-
-struct old_iterator
-  : public boost::iterator<std::random_access_iterator_tag, int>
-{
-  int& operator*() const { return *m_x; }
-  old_iterator& operator++() { return *this; }
-  old_iterator operator++(int) { return *this; }
-  old_iterator& operator--() { return *this; }
-  old_iterator operator--(int) { return *this; }
-  old_iterator& operator+=(std::ptrdiff_t) { return *this; }
-  old_iterator operator+(std::ptrdiff_t) { return *this; }
-  old_iterator& operator-=(std::ptrdiff_t) { return *this; }
-  old_iterator operator-(std::ptrdiff_t) const { return *this; }
-  std::ptrdiff_t operator-(const old_iterator&) const { return 0; }
-  bool operator==(const old_iterator&) const { return false; }
-  bool operator!=(const old_iterator&) const { return false; }
-  bool operator<(const old_iterator&) const { return false; }
-  int* m_x;
-};
-old_iterator operator+(std::ptrdiff_t, old_iterator x) { return x; }
-
-int
-main()
-{
-#if !defined(BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION)
-  boost::function_requires<
-    boost_concepts::MutableLvalueIteratorConcept<int*> >();
-  boost::function_requires<
-    boost_concepts::RandomAccessIteratorConcept<int*> >();
-
-  boost::function_requires<
-    boost_concepts::ConstantLvalueIteratorConcept<const int*> >();
-  boost::function_requires<
-    boost_concepts::RandomAccessIteratorConcept<const int*> >();
-#endif
-
-  boost::function_requires<
-    boost_concepts::MutableLvalueIteratorConcept<new_iterator> >();
-  boost::function_requires<
-    boost_concepts::RandomAccessIteratorConcept<new_iterator> >();
-
-  boost::function_requires<
-    boost_concepts::MutableLvalueIteratorConcept<old_iterator> >();
-  boost::function_requires<
-    boost_concepts::RandomAccessIteratorConcept<old_iterator> >();
-  return 0;
-}

development/libs/iterator/iterator_categories.htm

@@ -1,160 +0,0 @@
-<html>
-<!--
-  -- Copyright (c) Jeremy Siek 2000,2001
-  --
-  -- Permission to use, copy, modify, distribute and sell this software
-  -- and its documentation for any purpose is hereby granted without fee,
-  -- provided that the above copyright notice appears in all copies and
-  -- that both that copyright notice and this permission notice appear
-  -- in supporting documentation.  I make no representations about the
-  -- suitability of this software for any purpose.  It is provided "as is"
-  -- without express or implied warranty.
-  -->
-  <head>
-    <title>Boost Iterator Traits</title>
-  </head>
-
-<BODY BGCOLOR="#ffffff" LINK="#0000ee" TEXT="#000000" VLINK="#551a8b" 
-	ALINK="#ff0000"> 
-<IMG SRC="../../../../c++boost.gif" 
-     ALT="C++ Boost" width="277" height="86"> 
-<BR Clear>
-
-    <h1>Boost Iterator Category Traits</h1>
-Header <tt><a href="../../boost/iterator_categories.hpp">boost/iterator_categories.hpp</a></tt>
-
-<p>
-The <tt>boost::traversal_category</tt> and
-<tt>boost::return_category</tt> traits classes provides access to the
-category tags for iterators that model the Boost <a
-href="./iterator_concepts.htm">Iterator Concepts</a>, which are a
-replacement for the iterator requirements in the C++ standard.  The
-other associated types of the Boost iterator concepts are accessed
-through the <tt>std::iterator_traits</tt> class.
-
-<ul>
-  <li><tt>traversal_category&lt;Iter&gt;::type</tt>&nbsp;&nbsp; Can the iterator go forward, backward, etc.?
-  <li><tt>return_category&lt;Iter&gt;::type</tt>&nbsp;&nbsp; Is the iterator read or write only?
-    Is the dereferenced type an lvalue?
-</ul>
-
-<p>
-An important feature of the <tt>boost::traversal_category</tt> and
-<tt>boost::return_category</tt> classes is that they are <b>backwards
-compatible</b>, i.e., they automatically work for iterators for which
-there are valid definitions of <tt>std::iterator_traits</tt>. The old
-<tt>iterator_category</tt> is mapped to the appropriate traversal and
-return categories.
-
-<p>
-When creating a new iterator type that is meant to work with
-<tt>boost::traversal_category</tt> and
-<tt>boost::return_category</tt>, you can either create a
-specialization of these classes for your iterator type, or you can
-provide all the necessary associated types as nested typedefs.  In
-this case, your iterator class will need to inherit from
-<tt>new_iterator_base</tt> to let the category traits know
-that it will be able to find typedefs for <tt>traversal_category</tt>
-and <tt>return_category</tt> in you iterator class.
-
-
-Each of the new iterator requirements will need a category tag.
-
-<pre>
-namespace boost {
-
-  // Return Type Categories
-  struct readable_iterator_tag { };
-  struct writable_iterator_tag { };
-  struct swappable_iterator_tag { };
-  struct mutable_lvalue_iterator_tag : virtual public writable_iterator_tag,
-    virtual public readable_iterator_tag { };
-  struct constant_lvalue_iterator_tag : public readable_iterator_tag { };
-
-  // Traversal Categories
-  struct forward_traversal_tag { };
-  struct bidirectional_traversal_tag : public forward_traversal_tag { };
-  struct random_access_traversal_tag : public bidirectional_traversal_tag { };
-
-}
-</pre>  
-
-<p>
-The following is pseudo-code for the iterator category traits classes.
-
-<pre>
-namespace boost {
-
-  <i>// Inherit from iterator_base if your iterator defines its own
-  // return_category and traversal_category. Otherwise, the "old style"
-  // iterator category will be mapped to the return_category and
-  // traversal_category.</i>
-  struct new_iterator_base { };
-
-  template &lt;typename Iterator&gt;
-  struct return_category
-  {
-    <b><i>// Pseudo-code</i></b>
-    if (Iterator inherits from new_iterator_base) {
-      typedef typename Iterator::return_category type;
-    } else {
-      typedef std::iterator_traits&lt;Iterator&gt; OldTraits;
-      typedef typename OldTraits::iterator_category Cat;
-      if (Cat inherits from std::forward_iterator_tag)
-	if (is-const(T))
-	  typedef boost::constant_lvalue_iterator_tag type;
-	else
-	  typedef boost::mutable_lvalue_iterator_tag type;
-      else if (Cat inherits from std::input_iterator_tag)
-	typedef boost::readable_iterator_tag type;
-      else if (Cat inherits from std::output_iterator_tag)
-	typedef boost::writable_iterator_tag type;
-    }
-  };
-
-  template &lt;typename T&gt;
-  struct return_category&lt;T*&gt;
-  {
-    <b><i>// Pseudo-code</i></b>
-    if (is-const(T))
-      typedef boost::constant_lvalue_iterator_tag type;
-    else
-      typedef boost::mutable_lvalue_iterator_tag type;
-  };
-
-  template &lt;typename Iterator&gt;
-  struct traversal_category
-  {
-    <b><i>// Pseudo-code</i></b>
-    if (Iterator inherits from new_iterator_base) {
-      typedef typename Iterator::traversal_category type;
-    } else {
-      typedef std::iterator_traits&lt;Iterator&gt; OldTraits;
-      typedef typename OldTraits::iterator_category Cat;
-
-      if (Cat inherits from std::random_access_iterator_tag)
-	typedef boost::random_access_traversal_tag type;
-      else if (Cat inherits from std::bidirectional_iterator_tag)
-	typedef boost::bidirectional_traversal_tag type;
-      else if (Cat inherits from std::forward_iterator_tag)
-	typedef boost::forward_traversal_tag type;
-    }
-  };
-
-  template &lt;typename T&gt;
-  struct traversal_category&lt;T*&gt;
-  {
-    typedef boost::random_access_traversal_tag type;
-  };
-
-}
-</pre>
-
-    <hr>
-    <address><a href="mailto:jsiek@lsc.nd.edu">jeremy siek</a></address>
-<!-- Created: Sun Mar 18 14:06:57 EST 2001 -->
-<!-- hhmts start -->
-Last modified: Mon Mar 19 12:59:30 EST 2001
-<!-- hhmts end -->
-  </body>
-</html>

development/libs/iterator/iterator_concepts.fig

@@ -1,37 +0,0 @@
-#FIG 3.2
-Landscape
-Center
-Inches
-Letter  
-100.00
-Single
--2
-1200 2
-6 150 2325 4275 4350
-2 1 0 1 0 7 100 0 -1 4.000 0 0 -1 1 0 2
-	1 1 1.00 60.00 120.00
-	 1725 4050 1725 3450
-2 1 0 1 0 7 100 0 -1 4.000 0 0 -1 1 0 2
-	1 1 1.00 60.00 120.00
-	 1725 3150 1725 2550
-4 0 0 100 0 19 18 0.0000 4 210 3180 375 2550 ForwardTraversalIterator\001
-4 0 0 100 0 19 18 0.0000 4 210 3765 225 3450 BidirectionalTraversalIterator\001
-4 0 0 100 0 19 18 0.0000 4 210 4125 150 4350 RandomAccessTraversalIterator\001
--6
-2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2
-	1 1 1.00 60.00 120.00
-	 4800 3600 4800 2400
-2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2
-	1 1 1.00 60.00 120.00
-	 6900 3000 5400 2400
-2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2
-	1 1 1.00 60.00 120.00
-	 6900 3000 7500 2400
-2 1 0 1 0 7 50 0 -1 0.000 0 0 -1 1 0 2
-	1 1 1.00 60.00 120.00
-	 6900 3000 9075 2475
-4 0 0 100 0 19 18 0.0000 4 210 2040 6600 2400 WritableIterator\001
-4 0 0 100 0 19 18 0.0000 4 210 2145 3900 2400 ReadableIterator\001
-4 0 0 50 0 19 18 0.0000 4 210 2835 5700 3300 MutableLvalueIterator\001
-4 0 0 50 0 19 18 0.0000 4 270 2355 9075 2400 SwappableIterator\001
-4 0 0 50 0 19 18 0.0000 4 210 2970 3825 3900 ConstantLvalueIterator\001

development/libs/iterator/iterator_concepts.htm

@@ -1,663 +0,0 @@
-<HTML>
-<!--
-  -- Copyright (c) Jeremy Siek 2000
-  --
-  -- Permission to use, copy, modify, distribute and sell this software
-  -- and its documentation for any purpose is hereby granted without fee,
-  -- provided that the above copyright notice appears in all copies and
-  -- that both that copyright notice and this permission notice appear
-  -- in supporting documentation.  I make no representations about the
-  -- suitability of this software for any purpose.  It is provided "as is"
-  -- without express or implied warranty.
-  -->
-<!--
-  -- Copyright (c) 1996-1999
-  -- Silicon Graphics Computer Systems, Inc.
-  --
-  -- Permission to use, copy, modify, distribute and sell this software
-  -- and its documentation for any purpose is hereby granted without fee,
-  -- provided that the above copyright notice appears in all copies and
-  -- that both that copyright notice and this permission notice appear
-  -- in supporting documentation.  Silicon Graphics makes no
-  -- representations about the suitability of this software for any
-  -- purpose.  It is provided "as is" without express or implied warranty.
-  --
-  -- Copyright (c) 1994
-  -- Hewlett-Packard Company
-  --
-  -- Permission to use, copy, modify, distribute and sell this software
-  -- and its documentation for any purpose is hereby granted without fee,
-  -- provided that the above copyright notice appears in all copies and
-  -- that both that copyright notice and this permission notice appear
-  -- in supporting documentation.  Hewlett-Packard Company makes no
-  -- representations about the suitability of this software for any
-  -- purpose.  It is provided "as is" without express or implied warranty.
-  --
-  -->
-<Head>
-<Title>Iterator Concepts</Title>
-<BODY BGCOLOR="#ffffff" LINK="#0000ee" TEXT="#000000" VLINK="#551a8b" 
-	ALINK="#ff0000"> 
-<IMG SRC="../../../../c++boost.gif" 
-     ALT="C++ Boost" width="277" height="86"> 
-
-<BR Clear>
-
-
-<h1>Iterator Concepts</h1>
-
-<p>The standard iterator categories and requirements are flawed because
-they use a single hierarchy of requirements to address two orthogonal
-issues: <b><i>iterator traversal</i></b> and <b><i>dereference return
-type</i></b>. The current iterator requirement hierarchy is mainly
-geared towards iterator traversal (hence the category names), while
-requirements that address dereference return type sneak in at various
-places. 
-
-<p>
-The iterator requirements should be separated into two hierarchies.
-One set of concepts handles the return type semantics: 
-<ul>
-  <li><a href="#concept:ReadableIterator">Readable Iterator</a></li>
-  <li><a href="#concept:WritableIterator">Writable Iterator</a></li>
-  <li><a href="#concept:SwappableIterator">Swappable Iterator</a></li>
-  <li><a href="#concept:ConstantLvalueIterator">Constant Lvalue Iterator</a></li>
-  <li><a href="#concept:MutableLvalueIterator">Mutable Lvalue Iterator</a></li>
-</ul>
-
-The other set of concepts handles iterator traversal: 
-
-<ul>
-  <li><a href="#concept:ForwardTraversalIterator">Forward Traversal Iterator</a></li>
-  <li><a href="#concept:BidirectionalTraversalIterator">Bidirectional Traversal Iterator</a></li>
-  <li><a href="#concept:RandomAccessTraversalIterator">Random Access Traversal Iterator</a></li>
-</ul>
-
-The current Input Iterator and Output Iterator requirements will
-continue to be used as is. Note that Input Iterator implies Readable
-Iterator and Output Iterator implies Writable Iterator.
-
-<p>
-Note: we considered defining a Single-Pass Iterator, which could be
-combined with Readable or Writable Iterator to replace the Input and
-Output Iterator requirements. We rejected this idea because there are
-some differences between Input and Output Iterators that make it hard
-to merge them: for example Input Iterator requires Equality Comparable
-while Output Iterator does not.
-
-
-<p></p>
-<DIV ALIGN="CENTER"><A NAME="fig:graph-concepts"></A></A>
-<TABLE>
-<CAPTION ALIGN="TOP"><STRONG>Figure 1:</STRONG>
-The iterator concepts and refinement relationships.
-</CAPTION>
-<TR><TD><IMG SRC="./iterator_concepts.gif" ></TD></TR>
-</TABLE>
-</DIV>
-<p></p>
-
-
-<h2>Relationship with the standard iterator concepts</h2>
-
-<p>
-std::Input Iterator implies boost::ReadableIterator.
-
-<p>
-std::Output Iterator implies boost::Writable Iterator.
-
-<p>
-std::Forward Iterator refines boost::Forward Iterator and
-boost::Constant Lvalue Iterator or boost::Mutable Lvalue Iterator.
-
-<p>
-std::Bidirectional Iterator refines boost::Bidirectional Iterator and
-boost::Constant Lvalue Iterator or boost::Mutable Lvalue Iterator.
-
-<p>
-std::Random Access Iterator refines boost::Random Access Iterator and
-boost::Constant Lvalue Iterator or boost::Mutable Lvalue Iterator.
-
-
-<h3>Notation</h3>
-<Table>
-  <tr>
-    <td><tt>X</tt></td>
-    <td>The iterator type.</td>
-  </tr>
-  <tr>
-    <td><tt>T</tt></td>
-    <td>The value type of <tt>X</tt>, i.e., <tt>std::iterator_traits&lt;X&gt;::value_type</tt>.</td>
-  </tr>
-  <tr>
-    <td><tt>x</tt>, <tt>y</tt></td>
-    <td>An object of type <tt>X</tt>.</td>
-  </tr>
-  <tr>
-    <td><tt>t</tt></td>
-    <td>An object of type <tt>T</tt>.</td>
-  </tr>
-</table>
-
-<p>
-
-<hr>
-<!--------------------------------------------------------------------------->
-
-<H3><A NAME="concept:ReadableIterator"></A>
-Readable Iterator
-</H3>
-
-A Readable Iterator is an iterator that dereferences to produce an
-rvalue that is convertible to the <tt>value_type</tt> of the
-iterator. 
-
-<h3>Associated Types</h3>
-
-<Table border>
-
-  <tr>
-    <td>Value type</td>
-    <td><tt>std::iterator_traits&lt;X&gt;::value_type</tt></td>
-    <td>The type of the objects pointed to by the iterator.</td>
-  </tr>
-
-  <tr>
-    <td>Reference type</td>
-    <td><tt>std::iterator_traits&lt;X&gt;::reference</tt></td>
-    <td>
-    The return type of dereferencing the iterator. This
-    type must be convertible to <tt>T</tt>.
-    </td>
-  </tr>
-
-  <tr>
-    <td>Return Category</td>
-    <td><tt>std::return_category&lt;X&gt;::type</tt></td>
-    <td>
-    A type convertible to <tt>std::readable_iterator_tag</tt>
-    </td>
-  </tr>
-
-</Table>
-
-<h3>Refinement of</h3>
-
-<A href="http://www.boost.org/libs/utility/CopyConstructible.html">Copy Constructible</A>
-
-<h3>Valid expressions</h3>
-
-<Table border>
-<tr><TH>Name</TH><TH>Expression</TH><TH>Type requirements</TH><TH>Return type</TH></tr>
-<tr>
- <td>Dereference</td>
- <td><tt>*x</tt></td>
- <td>&nbsp;</td>
- <td><tt>std::iterator_traits&lt;X&gt;::reference</tt></td>
-</tr>
-<tr>
- <td>Member access</td>
- <td><tt>x-&gt;m</tt></td>
- <td><tt>T</tt> is a type with a member named <tt>m</tt>.</td>
- <td>
-If <tt>m</tt> is a data member, the type of <tt>m</tt>.
-If <tt>m</tt> is a member function, the return type of <tt>m</tt>.
- </td>
-</tr>
-</table>
-
-<p>
-
-<hr>
-<!--------------------------------------------------------------------------->
-
-<H3><A NAME="concept:WritableIterator"></A>
-Writable Iterator
-</H3>
-
-A Writable Iterator is an iterator that can be used to store a value
-using the dereference-assignment expression.
-
-<h3>Definitions</h3>
-
-If <tt>x</tt> is an Writable Iterator of type <tt>X</tt>, then the
-expression <tt>*x = a;</tt> stores the value <tt>a</tt> into
-<tt>x</tt>.  Note that <tt>operator=</tt>, like other C++ functions,
-may be overloaded; it may, in fact, even be a template function.  In
-general, then, <tt>a</tt> may be any of several different types.  A
-type <tt>A</tt> belongs to the <i>set of value types</i> of <tt>X</tt>
-if, for an object <tt>a</tt> of type <tt>A</tt>, <tt>*x = a;</tt> is
-well-defined and does not require performing any non-trivial
-conversions on <tt>a</tt>.
-
-<h3>Associated Types</h3>
-
-<Table border>
-
-  <tr>
-    <td>Return Category</td>
-    <td><tt>std::return_category&lt;X&gt;::type</tt></td>
-    <td>
-    A type convertible to <tt>std::writable_iterator_tag</tt>
-    </td>
-  </tr>
-
-</Table>
-
-
-
-<h3>Refinement of</h3>
-
-<A href="http://www.boost.org/libs/utility/CopyConstructible.html">Copy Constructible</A>
-
-<h3>Valid expressions</h3>
-
-<Table border>
-  <tr>
-    <TH>Name</TH><TH>Expression</TH><TH>Return type</TH>
-  </tr>
-  <tr>
-    <td>Dereference assignment</td>
-    <td><tt>*x = a</tt></td>
-    <td>unspecified</td>
-  </tr>
-</table>
-
-<p>
-
-
-<hr>
-<!--------------------------------------------------------------------------->
-
-<H3><A NAME="concept:SwappableIterator"></A>
-Swappable Iterator
-</H3>
-
-A Swappable Iterator is an iterator whose dereferenced values can be
-swapped.
-
-<p>
-Note: the requirements for Swappable Iterator are dependent on the
-issues surrounding <tt>std::swap()</tt> being resolved. Here we assume
-that the issue will be resolved by allowing the overload of
-<tt>std::swap()</tt> for user-defined types.
-
-<p>
-Note: Readable Iterator and Writable Iterator combined implies
-Swappable Iterator because of the fully templated
-<tt>std::swap()</tt>.  However, Swappable Iterator does not imply
-Readable Iterator nor Writable Iterator.
-
-<h3>Associated Types</h3>
-
-<Table border>
-
-  <tr>
-    <td>Return Category</td>
-    <td><tt>std::return_category&lt;X&gt;::type</tt></td>
-    <td>
-    A type convertible to <tt>std::swappable_iterator_tag</tt>
-    </td>
-  </tr>
-
-</Table>
-
-
-<h3>Valid expressions</h3>
-
-Of the two valid expressions listed below, only one <b>OR</b> the
-other is required. If <tt>std::iter_swap()</tt> is overloaded for
-<tt>X</tt> then <tt>std::swap()</tt> is not required. If
-<tt>std::iter_swap()</tt> is not overloaded for <tt>X</tt> then the
-default (fully templated) version is used, which will call
-<tt>std::swap()</tt> (this means changing the current requirements for
-<tt>std::iter_swap()</tt>).
-
-<p>
-<Table border>
-  <tr>
-    <TH>Name</TH><TH>Expression</TH><TH>Return type</TH>
-  </tr>
-
-  <tr>
-    <td>Iterator Swap</td>
-    <td><tt>std::iter_swap(x, y)</tt></td>
-    <td>void</td>
-  </tr>
-
-  <tr>
-    <td>Dereference and Swap</td>
-    <td><tt>std::swap(*x, *y)</tt></td>
-    <td>void</td>
-  </tr>
-
-</table>
-
-<p>
-
-
-<hr>
-<!--------------------------------------------------------------------------->
-
-<H3><A NAME="concept:ConstantLvalueIterator"></A>
-Constant Lvalue Iterator
-</H3>
-
-A Constant Lvalue Iterator is an iterator that dereferences to produce a
-const reference to the pointed-to object, i.e., the associated
-<tt>reference</tt> type is <tt>const T&amp;</tt>. Changing the value
-of or destroying an iterator that models Constant Lvalue Iterator does
-not invalidate pointers and references previously obtained from that
-iterator.
-
- 
-<h3>Refinement of</h3>
-
-<a href="#concept:ReadableIterator">Readable Iterator</a> 
-
-<h3>Associated Types</h3>
-
-<Table border>
-
-  <tr>
-    <td>Reference type</td>
-    <td><tt>std::iterator_traits&lt;X&gt;::reference</tt></td>
-    <td>
-     The return type of dereferencing the iterator, which must be
-     <tt>const T&amp;</tt>.
-    </td>
-  </tr>
-
-<!--  I don't think this is needed
-  <tr>
-    <td>Pointer type</td>
-    <td><tt>std::iterator_traits&lt;X&gt;::pointer</tt></td>
-    <td>
-     The pointer to the value type, which must be <tt>const T*</tt>.
-    </td>
-  </tr>
--->
-
-  <tr>
-    <td>Return Category</td>
-    <td><tt>std::return_category&lt;X&gt;::type</tt></td>
-    <td>
-    A type convertible to <tt>std::constant_lvalue_iterator_tag</tt>
-    </td>
-  </tr>
-
-</table>
-
-<!-- these are not necessary now that we use reference as operator* return type
-<h3>Valid expressions</h3>
-
-<Table border>
-<tr><TH>Name</TH><TH>Expression</TH><TH>Type requirements</TH><TH>Return type</TH></tr>
-<tr>
- <td>Dereference</td>
- <td><tt>*x</tt></td>
- <td>&nbsp;</td>
- <td><tt>std::iterator_traits&lt;X&gt;::reference</tt></td>
-</tr>
-<tr>
- <td>Member access</td>
- <td><tt>x-&gt;m</tt></td>
- <td><tt>T</tt> is a type with a member named <tt>m</tt>.</td>
- <td>
- &nbsp;
- </td>
-</tr>
-</table>
-
--->
-
-<p>
-
-<hr>
-<!--------------------------------------------------------------------------->
-
-<H3><A NAME="concept:MutableLvalueIterator"></A>
-Mutable Lvalue Iterator
-</H3>
-
-A Mutable Lvalue Iterator is an iterator that dereferences to produce a
-reference to the pointed-to object. The associated <tt>reference</tt>
-type is <tt>T&amp;</tt>.  Changing the value of or destroying an
-iterator that models Mutable Lvalue Iterator does not invalidate
-pointers and references previously obtained from that iterator.
- 
-<h3>Refinement of</h3>
-
-<a href="#concept:ReadableIterator">Readable Iterator</a>,
-<a href="#concept:WritableIterator">Writable Iterator</a>,
-and <a href="#concept:SwappableIterator">Swappable Iterator</a>.
-
-
-
-<h3>Associated Types</h3>
-
-<Table border>
-
-  <tr>
-    <td>Reference type</td>
-    <td><tt>std::iterator_traits&lt;X&gt;::reference</tt></td>
-    <td>The return type of dereferencing the iterator, which must be
-     <tt>T&amp;</tt>.</td>
-  </tr>
-
-<!-- I don't think this is necessary
-  <tr>
-    <td>Pointer type</td>
-    <td><tt>std::iterator_traits&lt;X&gt;::pointer</tt></td>
-    <td>
-     The pointer to the value type, which is <tt>T*</tt>.
-    </td>
-  </tr>
--->
-
-  <tr>
-    <td>Return Category</td>
-    <td><tt>std::return_category&lt;X&gt;::type</tt></td>
-    <td>
-    A type convertible to <tt>std::mutable_lvalue_iterator_tag</tt>
-    </td>
-  </tr>
-
-</table>
-
-<!-- no longer needed since the return type is specified as reference in the readable iterator
-<h3>Valid expressions</h3>
-
-<Table border>
-<tr><TH>Name</TH><TH>Expression</TH><TH>Type requirements</TH><TH>Return type</TH></tr>
-<tr>
- <td>Dereference</td>
- <td><tt>*x</tt></td>
- <td>&nbsp;</td>
- <td><tt>std::iterator_traits&lt;X&gt;::reference</tt></td>
-</tr>
-<tr>
- <td>Member access</td>
- <td><tt>x-&gt;m</tt></td>
- <td><tt>T</tt> is a type with a member named <tt>m</tt>.</td>
- <td>
- &nbsp;
- </td>
-</tr>
-</table>
-
--->
-
-<p>
-<hr>
-<!--------------------------------------------------------------------------->
-
-<H3><A NAME="concept:ForwardTraversalIterator"></A>
-Forward Traversal Iterator
-</H3>
-
-The Forward Iterator is an iterator that can be incremented. Also, it
-is permissible to make multiple passes through the iterator's range.
-
-<h3>Refinement of</h3>
-
-<A href="http://www.boost.org/libs/utility/CopyConstructible.html">Copy Constructible</A>,
-<A href="http://www.boost.org/libs/utility/Assignable.html">Assignable</A>,
-<A href="http://www.sgi.com/tech/stl/DefaultConstructible.html">Default Constructible</A>, and 
-<A href="http://www.sgi.com/tech/stl/EqualityComparable.html">Equality Comparable</A>
-
-
-<h3>Associated types</h3>
-
-<Table border>
-
-  <tr>
-    <td>Difference Type</td>
-    <td><tt>std::iterator_traits&lt;X&gt;::difference_type</tt></td>
-    <td>
-    A signed integral type used for representing distances
-    between iterators that point into the same range.
-    </td>
-  </tr>
-
-  <tr>
-    <td>Traversal Category</td>
-    <td><tt>std::traversal_category&lt;X&gt;::type</tt></td>
-    <td>
-    A type convertible to <tt>std::forward_traversal_tag</tt>
-    </td>
-  </tr>
-</Table>
-
-<h3>Valid expressions</h3>
-
-<Table border>
-  <tr>
-    <TH>Name</TH><TH>Expression</TH><TH>Type requirements</TH>
-      <TH>Return type</TH>
-  </tr>
-  <tr>
-    <td>Preincrement</td>
-    <td><tt>++i</tt></td><td>&nbsp;</td><td><tt>X&amp;</tt></td>
-  </tr>
-  <tr>
-    <td>Postincrement</td>
-    <td><tt>i++</tt></td><td>&nbsp;</td><td>convertible to <tt>const X&amp;</tt></td>
-  </tr>
-</Table>
-
-<p>
-<hr>
-<!--------------------------------------------------------------------------->
-
-<H3><A NAME="concept:BidirectionalTraversalIterator"></A>
-Bidirectional Traversal Iterator
-</H3>
-
-An iterator that can be incremented and decremented.
-
-<h3>Refinement of</h3>
-
-<a href="#concept:ForwardTraversalIterator">Forward Traversal Iterator</a>
-
-<h3>Associated types</h3>
-
-<Table border>
-  <tr>
-    <td>Traversal Category</td>
-    <td><tt>std::traversal_category&lt;X&gt;::type</tt></td>
-    <td>
-    A type convertible to <tt>std::bidirectional_traversal_tag</tt>
-    </td>
-  </tr>
-</Table>
-
-<h3>Valid expressions</h3>
-
-<Table border>
-  <tr>
-  <TH>Name</TH><TH>Expression</TH><TH>Type requirements</TH>
-      <TH>Return type</TH>
-  </tr>
-  <tr><td>Predecrement</td>
-      <td><tt>--i</tt></td><td>&nbsp;</td><td><tt>X&amp;</tt></td>
-  </tr>
-  <tr><td>Postdecrement</td>
-      <td><tt>i--</tt></td><td>&nbsp;</td><td>convertible to <tt>const X&amp;</tt></td>
-  </tr>
-</table>
-
-<p>
-<hr>
-<!--------------------------------------------------------------------------->
-
-<H3><A NAME="concept:RandomAccessTraversalIterator"></A>
-Random Access Traversal Iterator
-</H3>
-
-An iterator that provides constant-time methods for moving forward and
-backward in arbitrary-sized steps.
-
-<h3>Refinement of</h3>
-
-<a href="#concept:BidirectionalTraversalIterator">Bidirectional Traversal Iterator</a> and
-<A href="http://www.sgi.com/tech/stl/LessThanComparable.html">Less Than Comparable</A> where <tt>&lt;</tt> is a total ordering
-
-<h3>Associated types</h3>
-
-<Table border>
-  <tr>
-    <td>Traversal Category</td>
-    <td><tt>std::traversal_category&lt;X&gt;::type</tt></td>
-    <td>
-    A type convertible to <tt>std::random_access_traversal_tag</tt>
-    </td>
-  </tr>
-</Table>
-
-<h3>Valid expressions</h3>
-
-<Table border>
-<tr><TH>Name</TH><TH>Expression</TH><TH>Type requirements</TH>
-    <TH>Return type</TH>
-</tr>
-<tr><td>Iterator addition</td>
-    <td><tt>i += n</tt></td><td>&nbsp;</td><td><tt>X&amp;</tt></td>
-</tr>
-<tr><td>Iterator addition</td>
-    <td><tt>i + n</tt> or <tt>n + i</tt></td><td>&nbsp;</td><td><tt>X</tt></td>
-</tr>
-<tr><td>Iterator subtraction</td>
-   <td><tt>i -= n</tt></td><td>&nbsp;</td><td><tt>X&amp;</tt></td>
-</tr>
-<tr><td>Iterator subtraction</td>
-    <td><tt>i - n</tt></td><td>&nbsp;</td><td><tt>X</tt></td>
-</tr>
-<tr><td>Difference</td>
-    <td><tt>i - j</tt></td><td>&nbsp;</td><td><tt>std::iterator_traits&lt;X&gt;::difference_type</tt></td>
-</tr>
-<tr><td>Element operator</td>
-    <td><tt>i[n]</tt></td>
-    <td><tt>X</tt> must also be a model of
-     <a href="#concept:ReadableIterator">Readable Iterator</a>. </td>
-    <td><tt>std::iterator_traits&lt;X&gt;::reference</tt></td>
-</tr>
-<tr><td>Element assignment</td>
-    <td><tt>i[n] = t</tt></td>
-    <td><tt>X</tt> must also be a model of
-      <a href="#concept:WritableIterator">Writable Iterator</a>.</td>
-    <td>unspecified</td>
-</tr>
-</table>
-
-<p>
-
-<HR>
-<TABLE>
-<TR valign=top>
-<TD nowrap>Copyright &copy 2000</TD><TD>
-<A HREF="../../../../people/jeremy_siek.htm">Jeremy Siek</A>, Univ.of Notre Dame (<A HREF="mailto:jsiek@lsc.nd.edu">jsiek@lsc.nd.edu</A>)
-</TD></TR></TABLE>
-
-</body>
-</html>

doc/BidirectionalTraversal.html

@@ -0,0 +1,76 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<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.5: http://docutils.sourceforge.net/" />
+<title>Bidirectional Traversal Concept</title>
+<link rel="stylesheet" href="../../../rst.css" type="text/css" />
+</head>
+<body>
+<div class="document" id="bidirectional-traversal-concept">
+<h1 class="title">Bidirectional Traversal Concept</h1>
+
+<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
+<!-- Software License, Version 1.0. (See accompanying -->
+<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
+<p>A class or built-in type <tt class="docutils literal"><span class="pre">X</span></tt> models the <em>Bidirectional Traversal</em>
+concept if, in addition to <tt class="docutils literal"><span class="pre">X</span></tt> meeting the requirements of Forward
+Traversal Iterator, the following expressions are valid and respect
+the stated semantics.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="38%" />
+<col width="37%" />
+<col width="25%" />
+</colgroup>
+<thead valign="bottom">
+<tr><th class="head" colspan="3">Bidirectional Traversal Iterator Requirements (in addition to Forward Traversal
+Iterator)</th>
+</tr>
+<tr><th class="head">Expression</th>
+<th class="head">Return Type</th>
+<th class="head">Assertion/Semantics /
+Pre-/Post-condition</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr><td><tt class="docutils literal"><span class="pre">--r</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">X&amp;</span></tt></td>
+<td>pre: there exists
+<tt class="docutils literal"><span class="pre">s</span></tt> such that <tt class="docutils literal"><span class="pre">r</span>
+<span class="pre">==</span> <span class="pre">++s</span></tt>.  post:
+<tt class="docutils literal"><span class="pre">s</span></tt> is
+dereferenceable.
+<tt class="docutils literal"><span class="pre">--(++r)</span> <span class="pre">==</span> <span class="pre">r</span></tt>.
+<tt class="docutils literal"><span class="pre">--r</span> <span class="pre">==</span> <span class="pre">--s</span></tt>
+implies <tt class="docutils literal"><span class="pre">r</span> <span class="pre">==</span>
+<span class="pre">s</span></tt>. <tt class="docutils literal"><span class="pre">&amp;r</span> <span class="pre">==</span> <span class="pre">&amp;--r</span></tt>.</td>
+</tr>
+<tr><td><tt class="docutils literal"><span class="pre">r--</span></tt></td>
+<td>convertible to <tt class="docutils literal"><span class="pre">const</span> <span class="pre">X&amp;</span></tt></td>
+<td><pre class="first last literal-block">
+{
+  X tmp = r;
+  --r;
+  return tmp;
+}
+</pre>
+</td>
+</tr>
+<tr><td><tt class="docutils literal"><span class="pre">iterator_traversal&lt;X&gt;::type</span></tt></td>
+<td>Convertible to
+<tt class="docutils literal"><span class="pre">bidirectional_traversal_tag</span></tt></td>
+<td>&nbsp;</td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="footer">
+<hr class="footer" />
+<a class="reference external" href="BidirectionalTraversal.rst">View document source</a>.
+Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
+
+</div>
+</body>
+</html>

doc/BidirectionalTraversal.rst

@@ -0,0 +1,41 @@
+.. Copyright David Abrahams 2006. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+Bidirectional Traversal Concept
+...............................
+
+A class or built-in type ``X`` models the *Bidirectional Traversal*
+concept if, in addition to ``X`` meeting the requirements of Forward
+Traversal Iterator, the following expressions are valid and respect
+the stated semantics.
+
++--------------------------------------------------------------------------------------+
+|Bidirectional Traversal Iterator Requirements (in addition to Forward Traversal       |
+|Iterator)                                                                             |
++--------------------------------+-------------------------------+---------------------+
+|Expression                      |Return Type                    |Assertion/Semantics /|
+|                                |                               |Pre-/Post-condition  |
++================================+===============================+=====================+
+|``--r``                         |``X&``                         |pre: there exists    |
+|                                |                               |``s`` such that ``r  |
+|                                |                               |== ++s``.  post:     |
+|                                |                               |``s`` is             |
+|                                |                               |dereferenceable.     |
+|                                |                               |``--(++r) == r``.    |
+|                                |                               |``--r == --s``       |
+|                                |                               |implies ``r ==       |
+|                                |                               |s``. ``&r == &--r``. |
++--------------------------------+-------------------------------+---------------------+
+|``r--``                         |convertible to ``const X&``    |::                   |
+|                                |                               |                     |
+|                                |                               | {                   |
+|                                |                               |   X tmp = r;        |
+|                                |                               |   --r;              |
+|                                |                               |   return tmp;       |
+|                                |                               | }                   |
++--------------------------------+-------------------------------+---------------------+
+|``iterator_traversal<X>::type`` |Convertible to                 |                     |
+|                                |``bidirectional_traversal_tag``|                     |
+|                                |                               |                     |
++--------------------------------+-------------------------------+---------------------+

doc/ForwardTraversal.html

@@ -0,0 +1,67 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<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.5: http://docutils.sourceforge.net/" />
+<title>Forward Traversal Concept</title>
+<link rel="stylesheet" href="../../../rst.css" type="text/css" />
+</head>
+<body>
+<div class="document" id="forward-traversal-concept">
+<h1 class="title">Forward Traversal Concept</h1>
+
+<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
+<!-- Software License, Version 1.0. (See accompanying -->
+<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
+<p>A class or built-in type <tt class="docutils literal"><span class="pre">X</span></tt> models the <em>Forward Traversal</em>
+concept if, in addition to <tt class="docutils literal"><span class="pre">X</span></tt> meeting the requirements of Default
+Constructible and Single Pass Iterator, the following expressions are
+valid and respect the stated semantics.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="38%" />
+<col width="34%" />
+<col width="27%" />
+</colgroup>
+<thead valign="bottom">
+<tr><th class="head" colspan="3">Forward Traversal Iterator Requirements (in addition to Default Constructible and Single Pass Iterator)</th>
+</tr>
+<tr><th class="head">Expression</th>
+<th class="head">Return Type</th>
+<th class="head">Assertion/Note</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr><td><tt class="docutils literal"><span class="pre">X</span> <span class="pre">u;</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">X&amp;</span></tt></td>
+<td>note: <tt class="docutils literal"><span class="pre">u</span></tt> may have a
+singular value.</td>
+</tr>
+<tr><td><tt class="docutils literal"><span class="pre">++r</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">X&amp;</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">r</span> <span class="pre">==</span> <span class="pre">s</span></tt> and <tt class="docutils literal"><span class="pre">r</span></tt> is
+dereferenceable implies
+<tt class="docutils literal"><span class="pre">++r</span> <span class="pre">==</span> <span class="pre">++s.</span></tt></td>
+</tr>
+<tr><td><tt class="docutils literal"><span class="pre">iterator_traits&lt;X&gt;::difference_type</span></tt></td>
+<td>A signed integral type representing
+the distance between iterators</td>
+<td>&nbsp;</td>
+</tr>
+<tr><td><tt class="docutils literal"><span class="pre">iterator_traversal&lt;X&gt;::type</span></tt></td>
+<td>Convertible to
+<tt class="docutils literal"><span class="pre">forward_traversal_tag</span></tt></td>
+<td>&nbsp;</td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="footer">
+<hr class="footer" />
+<a class="reference external" href="ForwardTraversal.rst">View document source</a>.
+Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
+
+</div>
+</body>
+</html>

doc/ForwardTraversal.rst

@@ -0,0 +1,31 @@
+.. Copyright David Abrahams 2006. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+Forward Traversal Concept
+.........................
+
+A class or built-in type ``X`` models the *Forward Traversal*
+concept if, in addition to ``X`` meeting the requirements of Default
+Constructible and Single Pass Iterator, the following expressions are
+valid and respect the stated semantics.
+
++--------------------------------------------------------------------------------------------------------+
+|Forward Traversal Iterator Requirements (in addition to Default Constructible and Single Pass Iterator) |
++---------------------------------------+-----------------------------------+----------------------------+
+|Expression                             |Return Type                        |Assertion/Note              |
++=======================================+===================================+============================+
+|``X u;``                               |``X&``                             |note: ``u`` may have a      |
+|                                       |                                   |singular value.             |
++---------------------------------------+-----------------------------------+----------------------------+
+|``++r``                                |``X&``                             |``r == s`` and ``r`` is     |
+|                                       |                                   |dereferenceable implies     |
+|                                       |                                   |``++r == ++s.``             |
++---------------------------------------+-----------------------------------+----------------------------+
+|``iterator_traits<X>::difference_type``|A signed integral type representing|                            |
+|                                       |the distance between iterators     |                            |
+|                                       |                                   |                            |
++---------------------------------------+-----------------------------------+----------------------------+
+|``iterator_traversal<X>::type``        |Convertible to                     |                            |
+|                                       |``forward_traversal_tag``          |                            |
++---------------------------------------+-----------------------------------+----------------------------+

doc/GNUmakefile

@@ -1,232 +1,15 @@
-# GNUmakefile for postprocessing PDF files
-#
-# © 2000 IBM Corporation.
-# Licensed under the GNU GPL.
+# Copyright David Abrahams 2004. Distributed under the Boost
+# Software License, Version 1.0. (See accompanying
+# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 
-########################################################################
-# Make sure that the following macros are correct for your setup
-########################################################################
-# ... System utilities
-RMRF	= /bin/rm -rf
-MV	= /bin/mv
-EGREP	= /bin/egrep
 ECHO	= /bin/echo
-PERL	= /usr/bin/perl
-CAT	= /bin/cat
-TOUCH 	= /bin/touch
-ZIP	= /usr/bin/zip
 
-# ... TeX & postprocessors
-PPOWER4	      = ppower4
-PDFLATEX      = pdflatex
-METAPOST      = mpost
-FIG2DEV	      = fig2dev
-BIBTEX	      = bibtex
-FOLIAGECUTTER = foliageCutter --verbose
-RST2LATEX	  = rst2latex --documentclass book --documentoptions 10pt,twoside,pdftex # --use-latex-toc
-RST2HTML	  = rst2html
+all: 
+	@${ECHO} "<boost-root>/libs/iterator/doc/GNUmakefile should be replaced by"
+	@${ECHO}
+	@${ECHO} "    http://www.boost-consulting.com/writing/GNUmakefile,"
+	@${ECHO}
+	@${ECHO} "before proceeding.  That file is not included in the Boost"
+	@${ECHO} "distribution because it is licensed under the GPL, which violates"
+	@${ECHO} "Boost license requirements."
 
-TEX = latex
-export TEX
-########################################################################
-# End of user servicable parts; don't fiddle with the remainder of this
-# makefile unless you know what you do.
-#
-# You have been warned ;=)
-########################################################################
-
-# ... Variables
-TEXFILES = $(strip $(wildcard *.tex))
-RSTFILES = $(strip $(wildcard *.rst))
--include GNUmakefile.local
-TEXSTEMS = $(strip $(patsubst %.tex,%,${TEXFILES}))
-RSTSTEMS = $(strip $(patsubst %.rst,%,${RSTFILES}))
-CUTFOILS = $(strip $(patsubst %,%---toc.tex,${TEXSTEMS}))
-PDFFILES = $(strip $(patsubst %.tex,%.pdf,${TEXFILES}))
-PRINTS = $(patsubst %.pdf,%-print.pdf,${PDFFILES})
-PRINTZIP = prints.zip
-SLIDEZIP = slides.zip
-
-# ... Depend
-DEPENDFILE = .depend
-GENFILE	   = .generated
-
-# ... List of extensions and files generated
-texcrap = *.mpx *.log *.aux *.blg *-print.brf *-print.tex *.out
-
-mpxcrap = mpxerr.tex mpxerr.pdf
-
-generated = *.out *.[0-9] *.[0-9][0-9] *.bbl *.brf \
-	    *.mp *.mmp *.pdf .depend *.ps TMP-*.pdf *.ftoc\
-	    ${PRINTZIP} ${SLIDEZIP} ${GENFILE} ${DEPENDFILE} \
-	    ${texcrap} ${mpxcrap} ${CUTFOILS} $(strip $(wildcard *---*.tex))
-
-
-# ... canned command to run PDFLaTeX
-define run-pdflatex
-@${ECHO} ""
-@${ECHO} "---- Running PDFLaTeX on $<" && ${PDFLATEX} $<
-@${ECHO} "---- Running PDFLaTeX on $< again" && ${PDFLATEX} $<
--@(${EGREP} -qi 'Rerun to get' $*.log && \
-		${ECHO} "---- Rerunning PDFLaTeX on $* to get cross-refs right" && \
-		${PDFLATEX} $<) || \
-		${ECHO} "---- No cross-refs correcting PDFLaTeX rerun required for $*"
--@(${EGREP} -qi $*.ftoc $*.log && \
-		${ECHO} "---- Rerunning PDFLaTeX on $* for FTOC" && \
-		${PDFLATEX} $<) || \
-		${ECHO} "---- No FTOC PDFLaTeX run required for $*"
--@(${EGREP} -qi 'Warning: Citation' $*.log && \
-		${ECHO} "---- Running BIBTeX on $*" && \
-		${BIBTEX} $* && \
-		${ECHO} "---- Running PDFLaTeX on $<" && \
-		${PDFLATEX} $<) || \
-		${ECHO} "---- No BIBTeX run required for $*"
--@(${EGREP} -qi 'Warning: .+undefined references' $*.log && \
-		${ECHO} "---- Running PDFLaTeX on $<" && \
-		${PDFLATEX} $<) || \
-		${ECHO} "---- No further PDFLaTex run required for $<"
-@${ECHO} "Generated:     $@ {$<}" >> ${GENFILE}
-@${RMRF} ${texcrap}
-endef
-
-# ... canned command to run PDFLaTeX for printable versions
-define run-pdflatex-for-print
-@${ECHO} ""
-@${ECHO} "---- Running PDFLaTeX on $*-print.tex" && ${PDFLATEX} $*-print.tex
-@${ECHO} "---- Running PDFLaTeX on $< again" && ${PDFLATEX} $<
--@(${EGREP} -qi 'Warning: Citation' $*-print.log && \
-		${ECHO} "---- Running BIBTeX on $*-print" && \
-		${BIBTEX} $*-print && \
-		${ECHO} "---- Running PDFLaTeX on $*-print.tex" && \
-		${PDFLATEX} $*-print.tex) || \
-		${ECHO} "---- No BIBTeX run required for $*"
--@(${EGREP} -qi 'Warning: .+undefined references' $*-print.log && \
-		${ECHO} "---- Running PDFLaTeX on $*-print" && \
-		${PDFLATEX} $*-print.tex) || \
-		${ECHO} "---- No further PDFLaTex run required for $*-print"
-@${ECHO} "Generated:     $@ {$<}" >> ${GENFILE}
-@${RMRF} ${texcrap}
-endef
-
-# DWA begin modifications
-# ... Rule: How to generate TeX from ReST
-%.tex: %.txt
-	@${ECHO} "---- Running rst2latex on $<"
-	${RST2LATEX} $< $@
-	@${ECHO} "Generated: $@ {$<}" >> ${GENFILE}
-
-# ... Rule: How to generate TeX from ReST
-%.tex: %.rst
-	@${ECHO} "---- Running rst2latex on $<"
-	${RST2LATEX} $< $@
-	@${ECHO} "Generated: $@ {$<}" >> ${GENFILE}
-
-# ... Rule: How to generate HTML from ReST
-%.html: %.txt
-	@${ECHO} "---- Running rst2html on $<"
-	${RST2HTML} $< $@
-	@${ECHO} "Generated: $@ {$<}" >> ${GENFILE}
-
-# ... Rule: How to generate HTML from ReST
-%.html: %.rst
-	@${ECHO} "---- Running rst2html on $<"
-	${RST2HTML} $< $@
-	@${ECHO} "Generated: $@ {$<}" >> ${GENFILE}
-# DWA end modifications
-
-# ... Rule: How to generate PDF from TeX
-%.pdf: %.tex
-	$(run-pdflatex)
-	@${MV} $@ TMP-$@
-	@${ECHO} "---- Running PPower4 on $*"
-	${PPOWER4} -v TMP-$@ $@
-	@${RMRF} TMP-$@
-	@${ECHO} "Postprocessed: $*.pdf {$*.pdf}" >> ${GENFILE}
-
-# ... Rule: How to generate printable PDF from TeX
-%-print.pdf: %.tex
-	${PERL} -pe 's/^\\documentclass\[(.*?)\]/\\documentclass\[$$1,prints\]/;' < $< > $*-print.tex
-	$(run-pdflatex-for-print)
-	@${ECHO} "Generated:     $*-print.pdf {$*.pdf}" >> ${GENFILE}
-
-# ... Rule: How to generate cut foils from TeX master
-%---toc.tex: %.tex
-	${FOLIAGECUTTER} --prefix=$* $<
-
-# ... Rule: How to generate MetaPost from FIG
-%.mp: %.fig
-	@${ECHO} "---- Running Fig2Dev (mp) on $<"
-	${FIG2DEV} -L mp $< $@
-	@${ECHO} "Generated:     $@ {$<}" >> ${GENFILE}
-
-# ... Rule: How to generate MultiMetaPost from FIG
-%.mmp: %.fig
-	@${ECHO} "---- Running Fig2Dev (mmp) on $<"
-	${FIG2DEV} -L mmp $< $@
-	@${ECHO} "Generated:     $@ {$<}" >> ${GENFILE}
-
-# ... Rule: How to generate includable PS from FIG via MetaPost
-%.mps: %.fig
-	@${ECHO} "---- Running Fig2Dev (mps) on $<"
-	${FIG2DEV} -L mp $< $*.mps.mp
-	@${RMRF} $*.mps.[0-9]
-	${METAPOST} $*.mps.mp
-	@${MV} $*.mps.0 $@
-	@${ECHO} "Generated:     $@ {$<}" >> ${GENFILE}
-
-# ... Rule: How to generate includable PS files from MultiMetaPost
-%.0: %.mmp
-	@${ECHO} "---- Running MetaPost on $<"
-	@${RMRF} $*.[0-9] $*.[0-9][0-9]
-	${METAPOST} $<
-	@${ECHO} "Generated:     $*.0{...} {$<}" >> ${GENFILE}
-
-cleanup-crap:
-	@${RMRF} ${mpxcrap}
-
-# ... Target: all
-all: cleanup-crap .depend ${PDFFILES} ${PRINTS} ${PRINTZIP} ${SLIDEZIP}
-	@${ECHO} ""
-	@${TOUCH} ${GENFILE}
-	@${CAT} ${GENFILE}
-	@${RMRF} ${GENFILE}
-
-# ... Target: ZIP files
-zip zips: ${PRINTZIP} ${SLIDEZIP}
-
-# ... Target: ZIP file containing printable versions of slides
-${PRINTZIP}: .depend ${PDFFILES}
-	@${RMRF} ${PRINTZIP}
-	${ZIP} -r ${PRINTZIP} ${PRINTS}
-	@${ECHO} "Generated:     ${PRINTZIP}" >> ${GENFILE}
-
-# ... Target: ZIP file containing screen versions of slides
- ${SLIDEZIP}: .depend ${PDFFILES}
-	@${RMRF} ${SLIDEZIP}
-	${ZIP} -r ${SLIDEZIP} ${PDFFILES}
-	@${ECHO} "Generated:     ${SLIDEZIP}" >> ${GENFILE}
-
-# ... Target: clean up
-clean:
-	${RMRF} ${generated}
-
-# ... Target: create dependencies
-depend: .depend
-
-# ... Target: dependency file (parse TEXFILES for multiinclude and includegraphics)
-.depend: GNUmakefile ${TEXFILES}
-	${RMRF} $@
-	@for t in ${TEXSTEMS} ; do \
-		${ECHO} "Scanning $$t.tex"; \
-		${PERL} -e 'my $$target = shift @ARGV;' -e 'while (<>) { /\\multiinclude(\[.*?\])?{(.*?)}/ && print "$$target: $$2.0\n";}' $$t.pdf < $$t.tex >> $@; \
-		${PERL} -e 'my $$target = shift @ARGV;' -e 'while (<>) { /\\includegraphics(\[.*?\])?{(.*?)\.(.*?)}/ && print "$$target: $$2.$$3\n";}' $$t.pdf < $$t.tex >> $@; \
-	done
-	@for t in ${RSTSTEMS} ; do \
-		${ECHO} "Scanning $$t.rst"; \
-		${PERL} -e 'my $$target = shift @ARGV;' -e 'while (<>) { /^\.\. include::\s+(.*)/ && print "$$target: $$1\n";}' $$t.html < $$t.rst >> $@; \
-		${PERL} -e 'my $$target = shift @ARGV;' -e 'while (<>) { /^\.\. include::\s+(.*)/ && print "$$target: $$1\n";}' $$t.tex < $$t.rst >> $@; \
-	done
-
-
-# ... include dependency file
--include .depend

doc/IncrementableIterator.html

@@ -0,0 +1,66 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<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.5: http://docutils.sourceforge.net/" />
+<title>Incrementable Iterator Concept</title>
+<link rel="stylesheet" href="../../../rst.css" type="text/css" />
+</head>
+<body>
+<div class="document" id="incrementable-iterator-concept">
+<h1 class="title">Incrementable Iterator Concept</h1>
+
+<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
+<!-- Software License, Version 1.0. (See accompanying -->
+<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
+<p>A class or built-in type <tt class="docutils literal"><span class="pre">X</span></tt> models the <em>Incrementable Iterator</em>
+concept if, in addition to <tt class="docutils literal"><span class="pre">X</span></tt> being Assignable and Copy
+Constructible, the following expressions are valid and respect the
+stated semantics.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="39%" />
+<col width="37%" />
+<col width="24%" />
+</colgroup>
+<thead valign="bottom">
+<tr><th class="head" colspan="3">Incrementable Iterator Requirements (in addition to Assignable, Copy Constructible)</th>
+</tr>
+<tr><th class="head">Expression</th>
+<th class="head">Return Type</th>
+<th class="head">Assertion/Semantics</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr><td><tt class="docutils literal"><span class="pre">++r</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">X&amp;</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">&amp;r</span> <span class="pre">==</span> <span class="pre">&amp;++r</span></tt></td>
+</tr>
+<tr><td><tt class="docutils literal"><span class="pre">r++</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">X</span></tt></td>
+<td><pre class="first last literal-block">
+{
+   X tmp = r;
+   ++r;
+   return tmp;
+}
+</pre>
+</td>
+</tr>
+<tr><td><tt class="docutils literal"><span class="pre">iterator_traversal&lt;X&gt;::type</span></tt></td>
+<td>Convertible to
+<tt class="docutils literal"><span class="pre">incrementable_traversal_tag</span></tt></td>
+<td>&nbsp;</td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="footer">
+<hr class="footer" />
+<a class="reference external" href="IncrementableIterator.rst">View document source</a>.
+Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
+
+</div>
+</body>
+</html>

doc/IncrementableIterator.rst

@@ -0,0 +1,32 @@
+.. Copyright David Abrahams 2006. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+Incrementable Iterator Concept
+..............................
+
+A class or built-in type ``X`` models the *Incrementable Iterator*
+concept if, in addition to ``X`` being Assignable and Copy
+Constructible, the following expressions are valid and respect the
+stated semantics.
+
+
++-------------------------------------------------------------------------------------+
+|Incrementable Iterator Requirements (in addition to Assignable, Copy Constructible)  |
+|                                                                                     |
++--------------------------------+-------------------------------+--------------------+
+|Expression                      |Return Type                    |Assertion/Semantics |
++================================+===============================+====================+
+|``++r``                         |``X&``                         |``&r == &++r``      |
++--------------------------------+-------------------------------+--------------------+
+|``r++``                         |``X``                          |::                  |
+|                                |                               |                    |
+|                                |                               | {                  |
+|                                |                               |    X tmp = r;      |
+|                                |                               |    ++r;            |
+|                                |                               |    return tmp;     |
+|                                |                               | }                  |
++--------------------------------+-------------------------------+--------------------+
+|``iterator_traversal<X>::type`` |Convertible to                 |                    |
+|                                |``incrementable_traversal_tag``|                    |
++--------------------------------+-------------------------------+--------------------+

doc/InteroperableIterator.rst

@@ -0,0 +1,61 @@
+.. Copyright David Abrahams 2006. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+Interoperable Iterator Concept
+..............................
+
+A class or built-in type ``X`` that models Single Pass Iterator is
+*interoperable with* a class or built-in type ``Y`` that also models
+Single Pass Iterator if the following expressions are valid and
+respect the stated semantics. In the tables below, ``x`` is an object
+of type ``X``, ``y`` is an object of type ``Y``, ``Distance`` is
+``iterator_traits<Y>::difference_type``, and ``n`` represents a
+constant object of type ``Distance``.
+
++-----------+-----------------------+---------------------------------------------------+
+|Expression |Return Type            |Assertion/Precondition/Postcondition               |
++===========+=======================+===================================================+
+|``y = x``  |``Y``                  |post: ``y == x``                                   |
++-----------+-----------------------+---------------------------------------------------+
+|``Y(x)``   |``Y``                  |post: ``Y(x) == x``                                |
++-----------+-----------------------+---------------------------------------------------+
+|``x == y`` |convertible to ``bool``|``==`` is an equivalence relation over its domain. |
++-----------+-----------------------+---------------------------------------------------+
+|``y == x`` |convertible to ``bool``|``==`` is an equivalence relation over its domain. |
++-----------+-----------------------+---------------------------------------------------+
+|``x != y`` |convertible to ``bool``|``bool(a==b) != bool(a!=b)`` over its domain.      |
++-----------+-----------------------+---------------------------------------------------+
+|``y != x`` |convertible to ``bool``|``bool(a==b) != bool(a!=b)`` over its domain.      |
++-----------+-----------------------+---------------------------------------------------+
+
+If ``X`` and ``Y`` both model Random Access Traversal Iterator then
+the following additional requirements must be met.
+
++-----------+-----------------------+---------------------+--------------------------------------+
+|Expression |Return Type            |Operational Semantics|Assertion/ Precondition               |
++===========+=======================+=====================+======================================+
+|``x < y``  |convertible to ``bool``|``y - x > 0``        |``<`` is a total ordering relation    |
++-----------+-----------------------+---------------------+--------------------------------------+
+|``y < x``  |convertible to ``bool``|``x - y > 0``        |``<`` is a total ordering relation    |
++-----------+-----------------------+---------------------+--------------------------------------+
+|``x > y``  |convertible to ``bool``|``y < x``            |``>`` is a total ordering relation    |
++-----------+-----------------------+---------------------+--------------------------------------+
+|``y > x``  |convertible to ``bool``|``x < y``            |``>`` is a total ordering relation    |
++-----------+-----------------------+---------------------+--------------------------------------+
+|``x >= y`` |convertible to ``bool``|``!(x < y)``         |                                      |
++-----------+-----------------------+---------------------+--------------------------------------+
+|``y >= x`` |convertible to ``bool``|``!(y < x)``         |                                      |
++-----------+-----------------------+---------------------+--------------------------------------+
+|``x <= y`` |convertible to ``bool``|``!(x > y)``         |                                      |
++-----------+-----------------------+---------------------+--------------------------------------+
+|``y <= x`` |convertible to ``bool``|``!(y > x)``         |                                      |
++-----------+-----------------------+---------------------+--------------------------------------+
+|``y - x``  |``Distance``           |``distance(Y(x),y)`` |pre: there exists a value ``n`` of    |
+|           |                       |                     |``Distance`` such that ``x + n == y``.|
+|           |                       |                     |``y == x + (y - x)``.                 |
++-----------+-----------------------+---------------------+--------------------------------------+ 
+|``x - y``  |``Distance``           |``distance(y,Y(x))`` |pre: there exists a value ``n`` of    |
+|           |                       |                     |``Distance`` such that ``y + n == x``.|
+|           |                       |                     |``x == y + (x - y)``.                 |
++-----------+-----------------------+---------------------+--------------------------------------+

doc/Jamfile.v2

@@ -0,0 +1,27 @@
+# Copyright Thomas Witt 2005. Use, modification, and distribution are
+# subject to the Boost Software License, Version 1.0. (See accompanying
+# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+using quickbook ;
+
+xml iterator 
+  : 
+    quickbook/iterator.qbk 
+  ;
+
+boostbook standalone 
+  : 
+    iterator 
+  :
+    <xsl:param>boost.root=../../../..
+    <xsl:param>toc.max.depth=3
+    <xsl:param>toc.section.depth=3
+    <xsl:param>chunk.section.depth=4
+    <format>pdf:<xsl:param>boost.url.prefix=http://www.boost.org/doc/libs/release/libs/iterator/doc
+  ;
+
+###############################################################################
+alias boostdoc ;
+explicit boostdoc ;
+alias boostrelease : standalone ;
+explicit boostrelease ;

doc/LvalueIterator.html

@@ -0,0 +1,56 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<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.5: http://docutils.sourceforge.net/" />
+<title>Lvalue Iterator Concept</title>
+<link rel="stylesheet" href="../../../rst.css" type="text/css" />
+</head>
+<body>
+<div class="document" id="lvalue-iterator-concept">
+<h1 class="title">Lvalue Iterator Concept</h1>
+
+<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
+<!-- Software License, Version 1.0. (See accompanying -->
+<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
+<p>The <em>Lvalue Iterator</em> concept adds the requirement that the return
+type of <tt class="docutils literal"><span class="pre">operator*</span></tt> type be a reference to the value type of the
+iterator.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="22%" />
+<col width="19%" />
+<col width="59%" />
+</colgroup>
+<thead valign="bottom">
+<tr><th class="head" colspan="3">Lvalue Iterator Requirements</th>
+</tr>
+<tr><th class="head">Expression</th>
+<th class="head">Return Type</th>
+<th class="head">Note/Assertion</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr><td><tt class="docutils literal"><span class="pre">*a</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">T&amp;</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">T</span></tt> is <em>cv</em>
+<tt class="docutils literal"><span class="pre">iterator_traits&lt;X&gt;::value_type</span></tt>
+where <em>cv</em> is an optional
+cv-qualification.
+pre: <tt class="docutils literal"><span class="pre">a</span></tt> is
+dereferenceable. If <tt class="docutils literal"><span class="pre">a</span>
+<span class="pre">==</span> <span class="pre">b</span></tt> then <tt class="docutils literal"><span class="pre">*a</span></tt> is
+equivalent to <tt class="docutils literal"><span class="pre">*b</span></tt>.</td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="footer">
+<hr class="footer" />
+<a class="reference external" href="LvalueIterator.rst">View document source</a>.
+Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
+
+</div>
+</body>
+</html>

doc/LvalueIterator.rst

@@ -0,0 +1,25 @@
+.. Copyright David Abrahams 2006. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+Lvalue Iterator Concept
+.......................
+
+The *Lvalue Iterator* concept adds the requirement that the return
+type of ``operator*`` type be a reference to the value type of the
+iterator.
+
++-------------------------------------------------------------+
+| Lvalue Iterator Requirements                                |
++-------------+-----------+-----------------------------------+
+|Expression   |Return Type|Note/Assertion                     |
++=============+===========+===================================+
+|``*a``       | ``T&``    |``T`` is *cv*                      |
+|             |           |``iterator_traits<X>::value_type`` |
+|             |           |where *cv* is an optional          |
+|             |           |cv-qualification.                  |
+|             |           |pre: ``a`` is                      |
+|             |           |dereferenceable. If ``a            |
+|             |           |== b`` then ``*a`` is              |
+|             |           |equivalent to ``*b``.              |
++-------------+-----------+-----------------------------------+

doc/RandomAccessTraversal.html

@@ -0,0 +1,134 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<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.5: http://docutils.sourceforge.net/" />
+<title>Random Access Traversal Concept</title>
+<link rel="stylesheet" href="../../../rst.css" type="text/css" />
+</head>
+<body>
+<div class="document" id="random-access-traversal-concept">
+<h1 class="title">Random Access Traversal Concept</h1>
+
+<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
+<!-- Software License, Version 1.0. (See accompanying -->
+<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
+<p>A class or built-in type <tt class="docutils literal"><span class="pre">X</span></tt> models the <em>Random Access Traversal</em>
+concept if the following expressions are valid and respect the stated
+semantics.  In the table below, <tt class="docutils literal"><span class="pre">Distance</span></tt> is
+<tt class="docutils literal"><span class="pre">iterator_traits&lt;X&gt;::difference_type</span></tt> and <tt class="docutils literal"><span class="pre">n</span></tt> represents a
+constant object of type <tt class="docutils literal"><span class="pre">Distance</span></tt>.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="28%" />
+<col width="30%" />
+<col width="23%" />
+<col width="20%" />
+</colgroup>
+<thead valign="bottom">
+<tr><th class="head" colspan="4">Random Access Traversal Iterator Requirements (in addition to Bidirectional Traversal)</th>
+</tr>
+<tr><th class="head">Expression</th>
+<th class="head">Return Type</th>
+<th class="head">Operational Semantics</th>
+<th class="head">Assertion/
+Precondition</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr><td><tt class="docutils literal"><span class="pre">r</span> <span class="pre">+=</span> <span class="pre">n</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">X&amp;</span></tt></td>
+<td><pre class="first last literal-block">
+{
+  Distance m = n;
+  if (m &gt;= 0)
+    while (m--)
+      ++r;
+  else
+    while (m++)
+      --r;
+  return r;
+}
+</pre>
+</td>
+<td>&nbsp;</td>
+</tr>
+<tr><td><tt class="docutils literal"><span class="pre">a</span> <span class="pre">+</span> <span class="pre">n</span></tt>, <tt class="docutils literal"><span class="pre">n</span> <span class="pre">+</span> <span class="pre">a</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">X</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">{</span> <span class="pre">X</span> <span class="pre">tmp</span> <span class="pre">=</span> <span class="pre">a;</span> <span class="pre">return</span> <span class="pre">tmp</span>
+<span class="pre">+=</span> <span class="pre">n;</span> <span class="pre">}</span></tt></td>
+<td>&nbsp;</td>
+</tr>
+<tr><td><tt class="docutils literal"><span class="pre">r</span> <span class="pre">-=</span> <span class="pre">n</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">X&amp;</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">return</span> <span class="pre">r</span> <span class="pre">+=</span> <span class="pre">-n</span></tt></td>
+<td>&nbsp;</td>
+</tr>
+<tr><td><tt class="docutils literal"><span class="pre">a</span> <span class="pre">-</span> <span class="pre">n</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">X</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">{</span> <span class="pre">X</span> <span class="pre">tmp</span> <span class="pre">=</span> <span class="pre">a;</span> <span class="pre">return</span> <span class="pre">tmp</span>
+<span class="pre">-=</span> <span class="pre">n;</span> <span class="pre">}</span></tt></td>
+<td>&nbsp;</td>
+</tr>
+<tr><td><tt class="docutils literal"><span class="pre">b</span> <span class="pre">-</span> <span class="pre">a</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">Distance</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">a</span> <span class="pre">&lt;</span> <span class="pre">b</span> <span class="pre">?</span>&nbsp; <span class="pre">distance(a,b)</span>
+<span class="pre">:</span> <span class="pre">-distance(b,a)</span></tt></td>
+<td>pre: there exists a
+value <tt class="docutils literal"><span class="pre">n</span></tt> of
+<tt class="docutils literal"><span class="pre">Distance</span></tt> such that
+<tt class="docutils literal"><span class="pre">a</span> <span class="pre">+</span> <span class="pre">n</span> <span class="pre">==</span> <span class="pre">b</span></tt>.  <tt class="docutils literal"><span class="pre">b</span>
+<span class="pre">==</span> <span class="pre">a</span> <span class="pre">+</span> <span class="pre">(b</span> <span class="pre">-</span> <span class="pre">a)</span></tt>.</td>
+</tr>
+<tr><td><tt class="docutils literal"><span class="pre">a[n]</span></tt></td>
+<td>convertible to T</td>
+<td><tt class="docutils literal"><span class="pre">*(a</span> <span class="pre">+</span> <span class="pre">n)</span></tt></td>
+<td>pre: a is a <em>Readable
+Iterator</em></td>
+</tr>
+<tr><td><tt class="docutils literal"><span class="pre">a[n]</span> <span class="pre">=</span> <span class="pre">v</span></tt></td>
+<td>convertible to T</td>
+<td><tt class="docutils literal"><span class="pre">*(a</span> <span class="pre">+</span> <span class="pre">n)</span> <span class="pre">=</span> <span class="pre">v</span></tt></td>
+<td>pre: a is a <em>Writable
+iterator</em></td>
+</tr>
+<tr><td><tt class="docutils literal"><span class="pre">a</span> <span class="pre">&lt;</span> <span class="pre">b</span></tt></td>
+<td>convertible to <tt class="docutils literal"><span class="pre">bool</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">b</span> <span class="pre">-</span> <span class="pre">a</span> <span class="pre">&gt;</span> <span class="pre">0</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">&lt;</span></tt> is a total
+ordering relation</td>
+</tr>
+<tr><td><tt class="docutils literal"><span class="pre">a</span> <span class="pre">&gt;</span> <span class="pre">b</span></tt></td>
+<td>convertible to <tt class="docutils literal"><span class="pre">bool</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">b</span> <span class="pre">&lt;</span> <span class="pre">a</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">&gt;</span></tt> is a total
+ordering relation</td>
+</tr>
+<tr><td><tt class="docutils literal"><span class="pre">a</span> <span class="pre">&gt;=</span> <span class="pre">b</span></tt></td>
+<td>convertible to <tt class="docutils literal"><span class="pre">bool</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">!(a</span> <span class="pre">&lt;</span> <span class="pre">b)</span></tt></td>
+<td>&nbsp;</td>
+</tr>
+<tr><td><tt class="docutils literal"><span class="pre">a</span> <span class="pre">&lt;=</span> <span class="pre">b</span></tt></td>
+<td>convertible to <tt class="docutils literal"><span class="pre">bool</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">!(a</span> <span class="pre">&gt;</span> <span class="pre">b)</span></tt></td>
+<td>&nbsp;</td>
+</tr>
+<tr><td><tt class="docutils literal"><span class="pre">iterator_traversal&lt;X&gt;::type</span></tt></td>
+<td>Convertible to
+<tt class="docutils literal"><span class="pre">random_access_traversal_tag</span></tt></td>
+<td>&nbsp;</td>
+<td>&nbsp;</td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="footer">
+<hr class="footer" />
+<a class="reference external" href="RandomAccessTraversal.rst">View document source</a>.
+Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
+
+</div>
+</body>
+</html>

doc/RandomAccessTraversal.rst

@@ -0,0 +1,67 @@
+.. Copyright David Abrahams 2006. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+Random Access Traversal Concept
+...............................
+
+A class or built-in type ``X`` models the *Random Access Traversal*
+concept if the following expressions are valid and respect the stated
+semantics.  In the table below, ``Distance`` is
+``iterator_traits<X>::difference_type`` and ``n`` represents a
+constant object of type ``Distance``.
+
++------------------------------------------------------------------------------------------------------------------+
+|Random Access Traversal Iterator Requirements (in addition to Bidirectional Traversal)                            |
++-------------------------------+---------------------------------+-------------------------+----------------------+
+|Expression                     |Return Type                      |Operational Semantics    |Assertion/            |
+|                               |                                 |                         |Precondition          |
++===============================+=================================+=========================+======================+
+|``r += n``                     |``X&``                           |::                       |                      |
+|                               |                                 |                         |                      |
+|                               |                                 | {                       |                      |
+|                               |                                 |   Distance m = n;       |                      |
+|                               |                                 |   if (m >= 0)           |                      |
+|                               |                                 |     while (m--)         |                      |
+|                               |                                 |       ++r;              |                      |
+|                               |                                 |   else                  |                      |
+|                               |                                 |     while (m++)         |                      |
+|                               |                                 |       --r;              |                      |
+|                               |                                 |   return r;             |                      |
+|                               |                                 | }                       |                      |
++-------------------------------+---------------------------------+-------------------------+----------------------+
+|``a + n``, ``n + a``           |``X``                            |``{ X tmp = a; return tmp|                      |
+|                               |                                 |+= n; }``                |                      |
+|                               |                                 |                         |                      |
++-------------------------------+---------------------------------+-------------------------+----------------------+
+|``r -= n``                     |``X&``                           |``return r += -n``       |                      |
++-------------------------------+---------------------------------+-------------------------+----------------------+
+|``a - n``                      |``X``                            |``{ X tmp = a; return tmp|                      |
+|                               |                                 |-= n; }``                |                      |
+|                               |                                 |                         |                      |
++-------------------------------+---------------------------------+-------------------------+----------------------+
+|``b - a``                      |``Distance``                     |``a < b ?  distance(a,b) |pre: there exists a   |
+|                               |                                 |: -distance(b,a)``       |value ``n`` of        |
+|                               |                                 |                         |``Distance`` such that|
+|                               |                                 |                         |``a + n == b``.  ``b  |
+|                               |                                 |                         |== a + (b - a)``.     |
++-------------------------------+---------------------------------+-------------------------+----------------------+
+|``a[n]``                       |convertible to T                 |``*(a + n)``             |pre: a is a *Readable |
+|                               |                                 |                         |Iterator*             |
++-------------------------------+---------------------------------+-------------------------+----------------------+
+|``a[n] = v``                   |convertible to T                 |``*(a + n) = v``         |pre: a is a *Writable |
+|                               |                                 |                         |iterator*             |
++-------------------------------+---------------------------------+-------------------------+----------------------+
+|``a < b``                      |convertible to ``bool``          |``b - a > 0``            |``<`` is a total      |
+|                               |                                 |                         |ordering relation     |
++-------------------------------+---------------------------------+-------------------------+----------------------+
+|``a > b``                      |convertible to ``bool``          |``b < a``                |``>`` is a total      |
+|                               |                                 |                         |ordering relation     |
++-------------------------------+---------------------------------+-------------------------+----------------------+
+|``a >= b``                     |convertible to ``bool``          |``!(a < b)``             |                      |
++-------------------------------+---------------------------------+-------------------------+----------------------+
+|``a <= b``                     |convertible to ``bool``          |``!(a > b)``             |                      |
++-------------------------------+---------------------------------+-------------------------+----------------------+
+|``iterator_traversal<X>::type``|Convertible to                   |                         |                      |
+|                               |``random_access_traversal_tag``  |                         |                      |
++-------------------------------+---------------------------------+-------------------------+----------------------+

doc/ReadableIterator.html

@@ -0,0 +1,64 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<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.5: http://docutils.sourceforge.net/" />
+<title>Readable Iterator Concept</title>
+<link rel="stylesheet" href="../../../rst.css" type="text/css" />
+</head>
+<body>
+<div class="document" id="readable-iterator-concept">
+<h1 class="title">Readable Iterator Concept</h1>
+
+<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
+<!-- Software License, Version 1.0. (See accompanying -->
+<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
+<p>A class or built-in type <tt class="docutils literal"><span class="pre">X</span></tt> models the <em>Readable Iterator</em> concept
+for value type <tt class="docutils literal"><span class="pre">T</span></tt> if, in addition to <tt class="docutils literal"><span class="pre">X</span></tt> being Assignable and
+Copy Constructible, the following expressions are valid and respect
+the stated semantics. <tt class="docutils literal"><span class="pre">U</span></tt> is the type of any specified member of
+type <tt class="docutils literal"><span class="pre">T</span></tt>.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="28%" />
+<col width="20%" />
+<col width="52%" />
+</colgroup>
+<thead valign="bottom">
+<tr><th class="head" colspan="3">Readable Iterator Requirements (in addition to Assignable and Copy Constructible)</th>
+</tr>
+<tr><th class="head">Expression</th>
+<th class="head">Return Type</th>
+<th class="head">Note/Precondition</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr><td><tt class="docutils literal"><span class="pre">iterator_traits&lt;X&gt;::value_type</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">T</span></tt></td>
+<td>Any non-reference,
+non-cv-qualified type</td>
+</tr>
+<tr><td><tt class="docutils literal"><span class="pre">*a</span></tt></td>
+<td>Convertible to <tt class="docutils literal"><span class="pre">T</span></tt></td>
+<td><dl class="first last docutils">
+<dt>pre: <tt class="docutils literal"><span class="pre">a</span></tt> is dereferenceable. If <tt class="docutils literal"><span class="pre">a</span> <span class="pre">==</span> <span class="pre">b</span></tt> then <tt class="docutils literal"><span class="pre">*a</span></tt></dt>
+<dd>is equivalent to <tt class="docutils literal"><span class="pre">*b</span></tt>.</dd>
+</dl>
+</td>
+</tr>
+<tr><td><tt class="docutils literal"><span class="pre">a-&gt;m</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">U&amp;</span></tt></td>
+<td>pre: <tt class="docutils literal"><span class="pre">pre:</span> <span class="pre">(*a).m</span></tt> is well-defined. Equivalent to <tt class="docutils literal"><span class="pre">(*a).m</span></tt>.</td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="footer">
+<hr class="footer" />
+<a class="reference external" href="ReadableIterator.rst">View document source</a>.
+Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
+
+</div>
+</body>
+</html>

doc/ReadableIterator.rst

@@ -0,0 +1,26 @@
+.. Copyright David Abrahams 2006. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+Readable Iterator Concept
+.........................
+
+A class or built-in type ``X`` models the *Readable Iterator* concept
+for value type ``T`` if, in addition to ``X`` being Assignable and
+Copy Constructible, the following expressions are valid and respect
+the stated semantics. ``U`` is the type of any specified member of
+type ``T``.
+
++-----------------------------------------------------------------------------------------------------------------------------+
+|Readable Iterator Requirements (in addition to Assignable and Copy Constructible)                                            |
++-----------------------------------+------------------------+----------------------------------------------------------------+
+|Expression                         |Return Type             |Note/Precondition                                               |
++===================================+========================+================================================================+
+|``iterator_traits<X>::value_type`` |``T``                   |Any non-reference,                                              |
+|                                   |                        |non-cv-qualified type                                           |
++-----------------------------------+------------------------+----------------------------------------------------------------+
+|``*a``                             | Convertible to ``T``   |pre: ``a`` is dereferenceable. If ``a == b`` then ``*a``        |
+|                                   |                        | is equivalent to ``*b``.                                       |
++-----------------------------------+------------------------+----------------------------------------------------------------+
+|``a->m``                           |``U&``                  |pre: ``pre: (*a).m`` is well-defined. Equivalent to ``(*a).m``. |
++-----------------------------------+------------------------+----------------------------------------------------------------+

doc/SinglePassIterator.html

@@ -0,0 +1,68 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<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.5: http://docutils.sourceforge.net/" />
+<title>Single Pass Iterator Concept</title>
+<link rel="stylesheet" href="../../../rst.css" type="text/css" />
+</head>
+<body>
+<div class="document" id="single-pass-iterator-concept">
+<h1 class="title">Single Pass Iterator Concept</h1>
+
+<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
+<!-- Software License, Version 1.0. (See accompanying -->
+<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
+<p>A class or built-in type <tt class="docutils literal"><span class="pre">X</span></tt> models the <em>Single Pass Iterator</em>
+concept if the following expressions are valid and respect the stated
+semantics.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="36%" />
+<col width="33%" />
+<col width="31%" />
+</colgroup>
+<thead valign="bottom">
+<tr><th class="head" colspan="3">Single Pass Iterator Requirements (in addition to Incrementable Iterator and Equality
+Comparable)</th>
+</tr>
+<tr><th class="head">Expression</th>
+<th class="head">Return Type</th>
+<th class="head">Assertion/Semantics /
+Pre-/Post-condition</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr><td><tt class="docutils literal"><span class="pre">++r</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">X&amp;</span></tt></td>
+<td>pre: <tt class="docutils literal"><span class="pre">r</span></tt> is
+dereferenceable; post:
+<tt class="docutils literal"><span class="pre">r</span></tt> is dereferenceable or
+<tt class="docutils literal"><span class="pre">r</span></tt> is past-the-end</td>
+</tr>
+<tr><td><tt class="docutils literal"><span class="pre">a</span> <span class="pre">==</span> <span class="pre">b</span></tt></td>
+<td>convertible to <tt class="docutils literal"><span class="pre">bool</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">==</span></tt> is an equivalence
+relation over its domain</td>
+</tr>
+<tr><td><tt class="docutils literal"><span class="pre">a</span> <span class="pre">!=</span> <span class="pre">b</span></tt></td>
+<td>convertible to <tt class="docutils literal"><span class="pre">bool</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">!(a</span> <span class="pre">==</span> <span class="pre">b)</span></tt></td>
+</tr>
+<tr><td><tt class="docutils literal"><span class="pre">iterator_traversal&lt;X&gt;::type</span></tt></td>
+<td>Convertible to
+<tt class="docutils literal"><span class="pre">single_pass_traversal_tag</span></tt></td>
+<td>&nbsp;</td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="footer">
+<hr class="footer" />
+<a class="reference external" href="SinglePassIterator.rst">View document source</a>.
+Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
+
+</div>
+</body>
+</html>

doc/SinglePassIterator.rst

@@ -0,0 +1,32 @@
+.. Copyright David Abrahams 2006. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+Single Pass Iterator Concept
+............................
+
+A class or built-in type ``X`` models the *Single Pass Iterator*
+concept if the following expressions are valid and respect the stated
+semantics.
+
+
++------------------------------------------------------------------------------------------+
+|Single Pass Iterator Requirements (in addition to Incrementable Iterator and Equality     |
+|Comparable)                                                                               |
++--------------------------------+-----------------------------+---------------------------+
+|Expression                      |Return Type                  |Assertion/Semantics /      | 
+|                                |                             |Pre-/Post-condition        |
++================================+=============================+===========================+
+|``++r``                         |``X&``                       |pre: ``r`` is              |
+|                                |                             |dereferenceable; post:     |
+|                                |                             |``r`` is dereferenceable or|
+|                                |                             |``r`` is past-the-end      |
++--------------------------------+-----------------------------+---------------------------+
+|``a == b``                      |convertible to ``bool``      |``==`` is an equivalence   |
+|                                |                             |relation over its domain   |
++--------------------------------+-----------------------------+---------------------------+
+|``a != b``                      |convertible to ``bool``      |``!(a == b)``              |
++--------------------------------+-----------------------------+---------------------------+
+|``iterator_traversal<X>::type`` |Convertible to               |                           |
+|                                |``single_pass_traversal_tag``|                           |
++--------------------------------+-----------------------------+---------------------------+

doc/SwappableIterator.html

@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<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.5: http://docutils.sourceforge.net/" />
+<title>Swappable Iterator Concept</title>
+<link rel="stylesheet" href="../../../rst.css" type="text/css" />
+</head>
+<body>
+<div class="document" id="swappable-iterator-concept">
+<h1 class="title">Swappable Iterator Concept</h1>
+
+<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
+<!-- Software License, Version 1.0. (See accompanying -->
+<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
+<p>A class or built-in type <tt class="docutils literal"><span class="pre">X</span></tt> models the <em>Swappable Iterator</em> concept
+if, in addition to <tt class="docutils literal"><span class="pre">X</span></tt> being Copy Constructible, the following
+expressions are valid and respect the stated semantics.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="37%" />
+<col width="19%" />
+<col width="43%" />
+</colgroup>
+<thead valign="bottom">
+<tr><th class="head" colspan="3">Swappable Iterator Requirements (in addition to Copy Constructible)</th>
+</tr>
+<tr><th class="head">Expression</th>
+<th class="head">Return Type</th>
+<th class="head">Postcondition</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr><td><tt class="docutils literal"><span class="pre">iter_swap(a,</span> <span class="pre">b)</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">void</span></tt></td>
+<td>the pointed to values are
+exchanged</td>
+</tr>
+</tbody>
+</table>
+<dl class="docutils">
+<dt>[<em>Note:</em> An iterator that is a model of the <em>Readable</em> and <em>Writable Iterator</em> concepts</dt>
+<dd>is also a model of <em>Swappable Iterator</em>.  <em>--end note</em>]</dd>
+</dl>
+</div>
+<div class="footer">
+<hr class="footer" />
+<a class="reference external" href="SwappableIterator.rst">View document source</a>.
+Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
+
+</div>
+</body>
+</html>

doc/SwappableIterator.rst

@@ -0,0 +1,23 @@
+.. Copyright David Abrahams 2006. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+Swappable Iterator Concept
+..........................
+
+A class or built-in type ``X`` models the *Swappable Iterator* concept
+if, in addition to ``X`` being Copy Constructible, the following
+expressions are valid and respect the stated semantics.
+
++---------------------------------------------------------------------+
+|Swappable Iterator Requirements (in addition to Copy Constructible)  |
++-------------------------+-------------+-----------------------------+
+|Expression               |Return Type  |Postcondition                |
++=========================+=============+=============================+
+|``iter_swap(a, b)``      |``void``     |the pointed to values are    |
+|                         |             |exchanged                    |
++-------------------------+-------------+-----------------------------+
+
+[*Note:* An iterator that is a model of the *Readable* and *Writable Iterator* concepts
+  is also a model of *Swappable Iterator*.  *--end note*]
+

doc/WritableIterator.html

@@ -0,0 +1,52 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<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.5: http://docutils.sourceforge.net/" />
+<title>Writable Iterator Concept</title>
+<link rel="stylesheet" href="../../../rst.css" type="text/css" />
+</head>
+<body>
+<div class="document" id="writable-iterator-concept">
+<h1 class="title">Writable Iterator Concept</h1>
+
+<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
+<!-- Software License, Version 1.0. (See accompanying -->
+<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
+<p>A class or built-in type <tt class="docutils literal"><span class="pre">X</span></tt> models the <em>Writable Iterator</em> concept
+if, in addition to <tt class="docutils literal"><span class="pre">X</span></tt> being Copy Constructible, the following
+expressions are valid and respect the stated semantics.  Writable
+Iterators have an associated <em>set of value types</em>.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="37%" />
+<col width="21%" />
+<col width="42%" />
+</colgroup>
+<thead valign="bottom">
+<tr><th class="head" colspan="3">Writable Iterator Requirements (in addition to Copy Constructible)</th>
+</tr>
+<tr><th class="head">Expression</th>
+<th class="head">Return Type</th>
+<th class="head">Precondition</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr><td><tt class="docutils literal"><span class="pre">*a</span> <span class="pre">=</span> <span class="pre">o</span></tt></td>
+<td>&nbsp;</td>
+<td>pre: The type of <tt class="docutils literal"><span class="pre">o</span></tt>
+is in the set of
+value types of <tt class="docutils literal"><span class="pre">X</span></tt></td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="footer">
+<hr class="footer" />
+<a class="reference external" href="WritableIterator.rst">View document source</a>.
+Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
+
+</div>
+</body>
+</html>

doc/WritableIterator.rst

@@ -0,0 +1,21 @@
+.. Copyright David Abrahams 2006. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+Writable Iterator Concept
+.........................
+
+A class or built-in type ``X`` models the *Writable Iterator* concept
+if, in addition to ``X`` being Copy Constructible, the following
+expressions are valid and respect the stated semantics.  Writable
+Iterators have an associated *set of value types*.
+
++---------------------------------------------------------------------+
+|Writable Iterator Requirements (in addition to Copy Constructible)   |
++-------------------------+--------------+----------------------------+
+|Expression               |Return Type   |Precondition                |
++=========================+==============+============================+
+|``*a = o``               |              | pre: The type of ``o``     |
+|                         |              | is in the set of           |
+|                         |              | value types of ``X``       |
++-------------------------+--------------+----------------------------+

doc/counting_iterator.html

@@ -3,204 +3,13 @@
 <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.1: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
 <title>Counting Iterator</title>
 <meta name="author" content="David Abrahams, Jeremy Siek, Thomas Witt" />
 <meta name="organization" content="Boost Consulting, Indiana University Open Systems Lab, University of Hanover Institute for Transport Railway Operation and Construction" />
-<meta name="date" content="2003-09-14" />
-<meta name="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved" />
-<style type="text/css"><!--
-
-/*
-:Author: David Goodger
-:Contact: goodger@users.sourceforge.net
-:date: $Date$
-:version: $Revision$
-:copyright: This stylesheet has been placed in the public domain.
-
-Default cascading style sheet for the HTML output of Docutils.
-*/
-
-.first {
-  margin-top: 0 }
-
-.last {
-  margin-bottom: 0 }
-
-a.toc-backref {
-  text-decoration: none ;
-  color: black }
-
-dd {
-  margin-bottom: 0.5em }
-
-div.abstract {
-  margin: 2em 5em }
-
-div.abstract p.topic-title {
-  font-weight: bold ;
-  text-align: center }
-
-div.attention, div.caution, div.danger, div.error, div.hint,
-div.important, div.note, div.tip, div.warning {
-  margin: 2em ;
-  border: medium outset ;
-  padding: 1em }
-
-div.attention p.admonition-title, div.caution p.admonition-title,
-div.danger p.admonition-title, div.error p.admonition-title,
-div.warning p.admonition-title {
-  color: red ;
-  font-weight: bold ;
-  font-family: sans-serif }
-
-div.hint p.admonition-title, div.important p.admonition-title,
-div.note p.admonition-title, div.tip p.admonition-title {
-  font-weight: bold ;
-  font-family: sans-serif }
-
-div.dedication {
-  margin: 2em 5em ;
-  text-align: center ;
-  font-style: italic }
-
-div.dedication p.topic-title {
-  font-weight: bold ;
-  font-style: normal }
-
-div.figure {
-  margin-left: 2em }
-
-div.footer, div.header {
-  font-size: smaller }
-
-div.system-messages {
-  margin: 5em }
-
-div.system-messages h1 {
-  color: red }
-
-div.system-message {
-  border: medium outset ;
-  padding: 1em }
-
-div.system-message p.system-message-title {
-  color: red ;
-  font-weight: bold }
-
-div.topic {
-  margin: 2em }
-
-h1.title {
-  text-align: center }
-
-h2.subtitle {
-  text-align: center }
-
-hr {
-  width: 75% }
-
-ol.simple, ul.simple {
-  margin-bottom: 1em }
-
-ol.arabic {
-  list-style: decimal }
-
-ol.loweralpha {
-  list-style: lower-alpha }
-
-ol.upperalpha {
-  list-style: upper-alpha }
-
-ol.lowerroman {
-  list-style: lower-roman }
-
-ol.upperroman {
-  list-style: upper-roman }
-
-p.caption {
-  font-style: italic }
-
-p.credits {
-  font-style: italic ;
-  font-size: smaller }
-
-p.label {
-  white-space: nowrap }
-
-p.topic-title {
-  font-weight: bold }
-
-pre.address {
-  margin-bottom: 0 ;
-  margin-top: 0 ;
-  font-family: serif ;
-  font-size: 100% }
-
-pre.line-block {
-  font-family: serif ;
-  font-size: 100% }
-
-pre.literal-block, pre.doctest-block {
-  margin-left: 2em ;
-  margin-right: 2em ;
-  background-color: #eeeeee }
-
-span.classifier {
-  font-family: sans-serif ;
-  font-style: oblique }
-
-span.classifier-delimiter {
-  font-family: sans-serif ;
-  font-weight: bold }
-
-span.interpreted {
-  font-family: sans-serif }
-
-span.option-argument {
-  font-style: italic }
-
-span.pre {
-  white-space: pre }
-
-span.problematic {
-  color: red }
-
-table {
-  margin-top: 0.5em ;
-  margin-bottom: 0.5em }
-
-table.citation {
-  border-left: solid thin gray ;
-  padding-left: 0.5ex }
-
-table.docinfo {
-  margin: 2em 4em }
-
-table.footnote {
-  border-left: solid thin black ;
-  padding-left: 0.5ex }
-
-td, th {
-  padding-left: 0.5em ;
-  padding-right: 0.5em ;
-  vertical-align: top }
-
-th.docinfo-name, th.field-name {
-  font-weight: bold ;
-  text-align: left ;
-  white-space: nowrap }
-
-h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
-  font-size: 100% }
-
-tt {
-  background-color: #eeeeee }
-
-ul.auto-toc {
-  list-style-type: none }
-
---></style>
+<meta name="date" content="2006-09-11" />
+<meta name="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003." />
+<link rel="stylesheet" href="../../../rst.css" type="text/css" />
 </head>
 <body>
 <div class="document" id="counting-iterator">
@@ -212,136 +21,281 @@ ul.auto-toc {
 <tr><th class="docinfo-name">Author:</th>
 <td>David Abrahams, Jeremy Siek, Thomas Witt</td></tr>
 <tr><th class="docinfo-name">Contact:</th>
-<td><a class="first reference" href="mailto:dave&#64;boost-consulting.com">dave&#64;boost-consulting.com</a>, <a class="reference" href="mailto:jsiek&#64;osl.iu.edu">jsiek&#64;osl.iu.edu</a>, <a class="last reference" href="mailto:witt&#64;ive.uni-hannover.de">witt&#64;ive.uni-hannover.de</a></td></tr>
+<td><a class="first reference external" href="mailto:dave&#64;boost-consulting.com">dave&#64;boost-consulting.com</a>, <a class="reference external" href="mailto:jsiek&#64;osl.iu.edu">jsiek&#64;osl.iu.edu</a>, <a class="last reference external" href="mailto:witt&#64;ive.uni-hannover.de">witt&#64;ive.uni-hannover.de</a></td></tr>
 <tr><th class="docinfo-name">Organization:</th>
-<td><a class="first reference" href="http://www.boost-consulting.com">Boost Consulting</a>, Indiana University <a class="reference" href="http://www.osl.iu.edu">Open Systems
-Lab</a>, University of Hanover <a class="last reference" href="http://www.ive.uni-hannover.de">Institute for Transport
+<td><a class="first reference external" href="http://www.boost-consulting.com">Boost Consulting</a>, Indiana University <a class="reference external" href="http://www.osl.iu.edu">Open Systems
+Lab</a>, University of Hanover <a class="last reference external" href="http://www.ive.uni-hannover.de">Institute for Transport
 Railway Operation and Construction</a></td></tr>
 <tr><th class="docinfo-name">Date:</th>
-<td>2003-09-14</td></tr>
+<td>2006-09-11</td></tr>
 <tr><th class="docinfo-name">Copyright:</th>
-<td>Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved</td></tr>
+<td>Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003.</td></tr>
 </tbody>
 </table>
-<table class="field-list" frame="void" rules="none">
+<!-- Distributed under the Boost -->
+<!-- Software License, Version 1.0. (See accompanying -->
+<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
+<table class="docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
-<tr class="field"><th class="field-name">abstract:</th><td class="field-body"></td>
+<tr class="field"><th class="field-name">abstract:</th><td class="field-body"><p class="first">How would you fill up a vector with the numbers zero
+through one hundred using <tt class="docutils literal"><span class="pre">std::copy()</span></tt>?  The only iterator
+operation missing from builtin integer types is an
+<tt class="docutils literal"><span class="pre">operator*()</span></tt> that returns the current value of the integer.
+The counting iterator adaptor adds this crucial piece of
+functionality to whatever type it wraps.  One can use the
+counting iterator adaptor not only with integer types, but with
+any incrementable type.</p>
+<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
+<!-- Software License, Version 1.0. (See accompanying -->
+<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
+<p class="last"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> adapts an object by adding an <tt class="docutils literal"><span class="pre">operator*</span></tt> that
+returns the current value of the object. All other iterator operations
+are forwarded to the adapted object.</p>
+</td>
 </tr>
 </tbody>
 </table>
-<p>The counting iterator adaptor implements dereference by returning a
-reference to the base object. The other operations are implemented by
-the base <tt class="literal"><span class="pre">m_iterator</span></tt>, as per the inheritance from
-<tt class="literal"><span class="pre">iterator_adaptor</span></tt>.</p>
 <div class="contents topic" id="table-of-contents">
-<p class="topic-title"><a name="table-of-contents">Table of Contents</a></p>
+<p class="topic-title first">Table of Contents</p>
 <ul class="simple">
-<li><a class="reference" href="#counting-iterator-requirements" id="id1" name="id1"><tt class="literal"><span class="pre">counting_iterator</span></tt> requirements</a></li>
-<li><a class="reference" href="#counting-iterator-operations" id="id2" name="id2"><tt class="literal"><span class="pre">counting_iterator</span></tt> operations</a></li>
+<li><a class="reference internal" href="#counting-iterator-synopsis" id="id2"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> synopsis</a></li>
+<li><a class="reference internal" href="#counting-iterator-requirements" id="id3"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> requirements</a></li>
+<li><a class="reference internal" href="#counting-iterator-models" id="id4"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> models</a></li>
+<li><a class="reference internal" href="#counting-iterator-operations" id="id5"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> operations</a></li>
+<li><a class="reference internal" href="#example" id="id6">Example</a></li>
 </ul>
 </div>
+<div class="section" id="counting-iterator-synopsis">
+<h1><a class="toc-backref" href="#id2"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> synopsis</a></h1>
+<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
+<!-- Software License, Version 1.0. (See accompanying -->
+<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
 <pre class="literal-block">
 template &lt;
     class Incrementable
-  , unsigned Access = use_default_access
-  , class Traversal = use_default
+  , class CategoryOrTraversal = use_default
   , class Difference = use_default
 &gt;
 class counting_iterator
-  : public iterator_adaptor&lt;
-        counting_iterator&lt;Incrementable, Access, Traversal, Difference&gt;
-      , Incrementable
-      , Incrementable
-      , Access
-      , /* see details for traversal category */
-      , Incrementable const&amp;
-      , Incrementable const*
-      , /* distance = Difference or a signed integral type */&gt;
 {
-    friend class iterator_core_access;
- public:
+public:
+    typedef Incrementable value_type;
+    typedef const Incrementable&amp; reference;
+    typedef const Incrementable* pointer;
+    typedef /* see below */ difference_type;
+    typedef /* see below */ iterator_category;
+
     counting_iterator();
     counting_iterator(counting_iterator const&amp; rhs);
-    counting_iterator(Incrementable x);
- private:
-    typename counting_iterator::reference dereference() const
-    {
-        return this-&gt;base_reference();
-    }
-  };
+    explicit counting_iterator(Incrementable x);
+    Incrementable const&amp; base() const;
+    reference operator*() const;
+    counting_iterator&amp; operator++();
+    counting_iterator&amp; operator--();
+private:
+    Incrementable m_inc; // exposition
+};
 </pre>
-<dl>
+<p>If the <tt class="docutils literal"><span class="pre">Difference</span></tt> argument is <tt class="docutils literal"><span class="pre">use_default</span></tt> then
+<tt class="docutils literal"><span class="pre">difference_type</span></tt> is an unspecified signed integral
+type. Otherwise <tt class="docutils literal"><span class="pre">difference_type</span></tt> is <tt class="docutils literal"><span class="pre">Difference</span></tt>.</p>
+<p><tt class="docutils literal"><span class="pre">iterator_category</span></tt> is determined according to the following
+algorithm:</p>
+<pre class="literal-block">
+if (CategoryOrTraversal is not use_default)
+    return CategoryOrTraversal
+else if (numeric_limits&lt;Incrementable&gt;::is_specialized)
+    return <a class="reference external" href="iterator_facade.html#iterator-category"><em>iterator-category</em></a>(
+        random_access_traversal_tag, Incrementable, const Incrementable&amp;)
+else
+    return <a class="reference external" href="iterator_facade.html#iterator-category"><em>iterator-category</em></a>(
+         iterator_traversal&lt;Incrementable&gt;::type,
+         Incrementable, const Incrementable&amp;)
+</pre>
+<dl class="docutils">
 <dt>[<em>Note:</em> implementers are encouraged to provide an implementation of</dt>
-<dd><tt class="literal"><span class="pre">distance_to</span></tt> and a <tt class="literal"><span class="pre">difference_type</span></tt> that avoids overflows in
-the cases when the <tt class="literal"><span class="pre">Incrementable</span></tt> type is a numeric type.]</dd>
+<dd><tt class="docutils literal"><span class="pre">operator-</span></tt> and a <tt class="docutils literal"><span class="pre">difference_type</span></tt> that avoids overflows in
+the cases where <tt class="docutils literal"><span class="pre">std::numeric_limits&lt;Incrementable&gt;::is_specialized</span></tt>
+is true.]</dd>
 </dl>
+</div>
 <div class="section" id="counting-iterator-requirements">
-<h1><a class="toc-backref" href="#id1" name="counting-iterator-requirements"><tt class="literal"><span class="pre">counting_iterator</span></tt> requirements</a></h1>
-<p>The <tt class="literal"><span class="pre">Incrementable</span></tt> type must be Default Constructible, Copy
-Constructible, and Assignable.  The default distance is
-an implementation defined signed integegral type.</p>
-<p>The resulting <tt class="literal"><span class="pre">counting_iterator</span></tt> models Readable Lvalue Iterator.</p>
-<p>Furthermore, if you wish to create a counting iterator that is a Forward
-Traversal Iterator, then the following expressions must be valid:</p>
+<h1><a class="toc-backref" href="#id3"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> requirements</a></h1>
+<p>The <tt class="docutils literal"><span class="pre">Incrementable</span></tt> argument shall be Copy Constructible and Assignable.</p>
+<p>If <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is convertible to <tt class="docutils literal"><span class="pre">forward_iterator_tag</span></tt>
+or <tt class="docutils literal"><span class="pre">forward_traversal_tag</span></tt>, the following must be well-formed:</p>
 <pre class="literal-block">
 Incrementable i, j;
-++i         // pre-increment
-i == j      // operator equal
+++i;         // pre-increment
+i == j;      // operator equal
 </pre>
-<p>If you wish to create a counting iterator that is a 
-Bidirectional Traversal Iterator, then pre-decrement is also required:</p>
+<p>If <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is convertible to
+<tt class="docutils literal"><span class="pre">bidirectional_iterator_tag</span></tt> or <tt class="docutils literal"><span class="pre">bidirectional_traversal_tag</span></tt>,
+the following expression must also be well-formed:</p>
 <pre class="literal-block">
 --i
 </pre>
-<p>If you wish to create a counting iterator that is a Random Access
-Traversal Iterator, then these additional expressions are also
-required:</p>
+<p>If <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is convertible to
+<tt class="docutils literal"><span class="pre">random_access_iterator_tag</span></tt> or <tt class="docutils literal"><span class="pre">random_access_traversal_tag</span></tt>,
+the following must must also be valid:</p>
 <pre class="literal-block">
 counting_iterator::difference_type n;
-i += n
-n = i - j
-i &lt; j
+i += n;
+n = i - j;
+i &lt; j;
 </pre>
 </div>
+<div class="section" id="counting-iterator-models">
+<h1><a class="toc-backref" href="#id4"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> models</a></h1>
+<p>Specializations of <tt class="docutils literal"><span class="pre">counting_iterator</span></tt> model Readable Lvalue
+Iterator. In addition, they model the concepts corresponding to the
+iterator tags to which their <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is convertible.
+Also, if <tt class="docutils literal"><span class="pre">CategoryOrTraversal</span></tt> is not <tt class="docutils literal"><span class="pre">use_default</span></tt> then
+<tt class="docutils literal"><span class="pre">counting_iterator</span></tt> models the concept corresponding to the iterator
+tag <tt class="docutils literal"><span class="pre">CategoryOrTraversal</span></tt>.  Otherwise, if
+<tt class="docutils literal"><span class="pre">numeric_limits&lt;Incrementable&gt;::is_specialized</span></tt>, then
+<tt class="docutils literal"><span class="pre">counting_iterator</span></tt> models Random Access Traversal Iterator.
+Otherwise, <tt class="docutils literal"><span class="pre">counting_iterator</span></tt> models the same iterator traversal
+concepts modeled by <tt class="docutils literal"><span class="pre">Incrementable</span></tt>.</p>
+<p><tt class="docutils literal"><span class="pre">counting_iterator&lt;X,C1,D1&gt;</span></tt> is interoperable with
+<tt class="docutils literal"><span class="pre">counting_iterator&lt;Y,C2,D2&gt;</span></tt> if and only if <tt class="docutils literal"><span class="pre">X</span></tt> is
+interoperable with <tt class="docutils literal"><span class="pre">Y</span></tt>.</p>
+</div>
 <div class="section" id="counting-iterator-operations">
-<h1><a class="toc-backref" href="#id2" name="counting-iterator-operations"><tt class="literal"><span class="pre">counting_iterator</span></tt> operations</a></h1>
-<p><tt class="literal"><span class="pre">counting_iterator();</span></tt></p>
-<table class="field-list" frame="void" rules="none">
+<h1><a class="toc-backref" href="#id5"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt> operations</a></h1>
+<p>In addition to the operations required by the concepts modeled by
+<tt class="docutils literal"><span class="pre">counting_iterator</span></tt>, <tt class="docutils literal"><span class="pre">counting_iterator</span></tt> provides the following
+operations.</p>
+<p><tt class="docutils literal"><span class="pre">counting_iterator();</span></tt></p>
+<table class="docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
-<tr class="field"><th class="field-name">Returns:</th><td class="field-body">A default constructed instance of <tt class="literal"><span class="pre">counting_iterator</span></tt>.</td>
+<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="docutils literal"><span class="pre">Incrementable</span></tt> is Default Constructible.</td>
+</tr>
+<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Default construct the member <tt class="docutils literal"><span class="pre">m_inc</span></tt>.</td>
 </tr>
 </tbody>
 </table>
-<p><tt class="literal"><span class="pre">counting_iterator(counting_iterator</span> <span class="pre">const&amp;</span> <span class="pre">rhs);</span></tt></p>
-<table class="field-list" frame="void" rules="none">
+<p><tt class="docutils literal"><span class="pre">counting_iterator(counting_iterator</span> <span class="pre">const&amp;</span> <span class="pre">rhs);</span></tt></p>
+<table class="docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
-<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="literal"><span class="pre">counting_iterator</span></tt> that is a copy of <tt class="literal"><span class="pre">rhs</span></tt>.</td>
+<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Construct member <tt class="docutils literal"><span class="pre">m_inc</span></tt> from <tt class="docutils literal"><span class="pre">rhs.m_inc</span></tt>.</td>
 </tr>
 </tbody>
 </table>
-<p><tt class="literal"><span class="pre">counting_iterator(Incrementable</span> <span class="pre">x);</span></tt></p>
-<table class="field-list" frame="void" rules="none">
+<p><tt class="docutils literal"><span class="pre">explicit</span> <span class="pre">counting_iterator(Incrementable</span> <span class="pre">x);</span></tt></p>
+<table class="docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
-<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="literal"><span class="pre">counting_iterator</span></tt> with its base
-object copy constructed from <tt class="literal"><span class="pre">x</span></tt>.</td>
+<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Construct member <tt class="docutils literal"><span class="pre">m_inc</span></tt> from <tt class="docutils literal"><span class="pre">x</span></tt>.</td>
 </tr>
 </tbody>
 </table>
+<p><tt class="docutils literal"><span class="pre">reference</span> <span class="pre">operator*()</span> <span class="pre">const;</span></tt></p>
+<table class="docutils field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">m_inc</span></tt></td>
+</tr>
+</tbody>
+</table>
+<p><tt class="docutils literal"><span class="pre">counting_iterator&amp;</span> <span class="pre">operator++();</span></tt></p>
+<table class="docutils field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><tt class="docutils literal"><span class="pre">++m_inc</span></tt></td>
+</tr>
+<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">*this</span></tt></td>
+</tr>
+</tbody>
+</table>
+<p><tt class="docutils literal"><span class="pre">counting_iterator&amp;</span> <span class="pre">operator--();</span></tt></p>
+<table class="docutils field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><tt class="docutils literal"><span class="pre">--m_inc</span></tt></td>
+</tr>
+<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">*this</span></tt></td>
+</tr>
+</tbody>
+</table>
+<p><tt class="docutils literal"><span class="pre">Incrementable</span> <span class="pre">const&amp;</span> <span class="pre">base()</span> <span class="pre">const;</span></tt></p>
+<table class="docutils field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">m_inc</span></tt></td>
+</tr>
+</tbody>
+</table>
+<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
+<!-- Software License, Version 1.0. (See accompanying -->
+<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
+<pre class="literal-block">
+template &lt;class Incrementable&gt;
+counting_iterator&lt;Incrementable&gt; make_counting_iterator(Incrementable x);
+</pre>
+<table class="docutils field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="docutils literal"><span class="pre">counting_iterator&lt;Incrementable&gt;</span></tt>
+with <tt class="docutils literal"><span class="pre">current</span></tt> constructed from <tt class="docutils literal"><span class="pre">x</span></tt>.</td>
+</tr>
+</tbody>
+</table>
+<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
+<!-- Software License, Version 1.0. (See accompanying -->
+<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
+</div>
+<div class="section" id="example">
+<h1><a class="toc-backref" href="#id6">Example</a></h1>
+<p>This example fills an array with numbers and a second array with
+pointers into the first array, using <tt class="docutils literal"><span class="pre">counting_iterator</span></tt> for both
+tasks. Finally <tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> is used to print out the numbers
+into the first array via indirection through the second array.</p>
+<pre class="literal-block">
+int N = 7;
+std::vector&lt;int&gt; numbers;
+typedef std::vector&lt;int&gt;::iterator n_iter;
+std::copy(boost::counting_iterator&lt;int&gt;(0),
+         boost::counting_iterator&lt;int&gt;(N),
+         std::back_inserter(numbers));
+
+std::vector&lt;std::vector&lt;int&gt;::iterator&gt; pointers;
+std::copy(boost::make_counting_iterator(numbers.begin()),
+          boost::make_counting_iterator(numbers.end()),
+          std::back_inserter(pointers));
+
+std::cout &lt;&lt; &quot;indirectly printing out the numbers from 0 to &quot;
+          &lt;&lt; N &lt;&lt; std::endl;
+std::copy(boost::make_indirect_iterator(pointers.begin()),
+          boost::make_indirect_iterator(pointers.end()),
+          std::ostream_iterator&lt;int&gt;(std::cout, &quot; &quot;));
+std::cout &lt;&lt; std::endl;
+</pre>
+<p>The output is:</p>
+<pre class="literal-block">
+indirectly printing out the numbers from 0 to 7
+0 1 2 3 4 5 6
+</pre>
+<p>The source code for this example can be found <a class="reference external" href="../example/counting_iterator_example.cpp">here</a>.</p>
 </div>
 </div>
-<hr class="footer" />
 <div class="footer">
-<a class="reference" href="counting_iterator.rst">View document source</a>.
-Generated on: 2003-11-24 05:00 UTC.
-Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
+<hr class="footer" />
+<a class="reference external" href="counting_iterator.rst">View document source</a>.
+Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
+
 </div>
 </body>
 </html>

doc/counting_iterator.rst

@@ -1,3 +1,7 @@
+.. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
 +++++++++++++++++++
  Counting Iterator
 +++++++++++++++++++
@@ -8,16 +12,32 @@
                Lab`_, University of Hanover `Institute for Transport
                Railway Operation and Construction`_
 :date: $Date$
-:copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved
+:copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. 
 
 .. _`Boost Consulting`: http://www.boost-consulting.com
 .. _`Open Systems Lab`: http://www.osl.iu.edu
 .. _`Institute for Transport Railway Operation and Construction`: http://www.ive.uni-hannover.de
 
-:abstract:
+:abstract: How would you fill up a vector with the numbers zero
+  through one hundred using ``std::copy()``?  The only iterator
+  operation missing from builtin integer types is an
+  ``operator*()`` that returns the current value of the integer.
+  The counting iterator adaptor adds this crucial piece of
+  functionality to whatever type it wraps.  One can use the
+  counting iterator adaptor not only with integer types, but with
+  any incrementable type.
 
-.. include:: counting_iterator_abstract.rst
+  .. include:: counting_iterator_abstract.rst
 
 .. contents:: Table of Contents
 
+``counting_iterator`` synopsis
+..............................
+
 .. include:: counting_iterator_ref.rst
+.. include:: make_counting_iterator.rst
+
+.. include:: counting_iterator_eg.rst
+
+.. _iterator-category: iterator_facade.html#iterator-category
+.. |iterator-category| replace:: *iterator-category*

doc/counting_iterator_abstract.rst

@@ -1,5 +1,8 @@
-The counting iterator adaptor implements dereference by returning a
-reference to the base object. The other operations are implemented by
-the base ``m_iterator``, as per the inheritance from
-``iterator_adaptor``.
+.. Copyright David Abrahams 2006. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+``counting_iterator`` adapts an object by adding an ``operator*`` that
+returns the current value of the object. All other iterator operations
+are forwarded to the adapted object.
 

doc/counting_iterator_eg.rst

@@ -0,0 +1,43 @@
+.. Copyright David Abrahams 2006. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+Example
+.......
+
+This example fills an array with numbers and a second array with
+pointers into the first array, using ``counting_iterator`` for both
+tasks. Finally ``indirect_iterator`` is used to print out the numbers
+into the first array via indirection through the second array.
+
+::
+
+    int N = 7;
+    std::vector<int> numbers;
+    typedef std::vector<int>::iterator n_iter;
+    std::copy(boost::counting_iterator<int>(0),
+             boost::counting_iterator<int>(N),
+             std::back_inserter(numbers));
+
+    std::vector<std::vector<int>::iterator> pointers;
+    std::copy(boost::make_counting_iterator(numbers.begin()),
+	      boost::make_counting_iterator(numbers.end()),
+	      std::back_inserter(pointers));
+
+    std::cout << "indirectly printing out the numbers from 0 to " 
+	      << N << std::endl;
+    std::copy(boost::make_indirect_iterator(pointers.begin()),
+	      boost::make_indirect_iterator(pointers.end()),
+	      std::ostream_iterator<int>(std::cout, " "));
+    std::cout << std::endl;
+
+
+The output is::
+
+    indirectly printing out the numbers from 0 to 7
+    0 1 2 3 4 5 6 
+
+The source code for this example can be found `here`__.
+
+__ ../example/counting_iterator_example.cpp
+

doc/counting_iterator_ref.rst

@@ -1,91 +1,149 @@
+.. Copyright David Abrahams 2006. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
 ::
 
   template <
       class Incrementable
-    , unsigned Access = use_default_access
-    , class Traversal = use_default
+    , class CategoryOrTraversal = use_default
     , class Difference = use_default
   >
   class counting_iterator
-    : public iterator_adaptor<
-          counting_iterator<Incrementable, Access, Traversal, Difference>
-        , Incrementable
-        , Incrementable
-        , Access
-        , /* see details for traversal category */
-        , Incrementable const&
-        , Incrementable const*
-        , /* distance = Difference or a signed integral type */>
   {
-      friend class iterator_core_access;
-   public:
+  public:
+      typedef Incrementable value_type;
+      typedef const Incrementable& reference;
+      typedef const Incrementable* pointer;
+      typedef /* see below */ difference_type;
+      typedef /* see below */ iterator_category;
+
       counting_iterator();
       counting_iterator(counting_iterator const& rhs);
-      counting_iterator(Incrementable x);
-   private:
-      typename counting_iterator::reference dereference() const
-      {
-          return this->base_reference();
-      }
-    };
+      explicit counting_iterator(Incrementable x);
+      Incrementable const& base() const;
+      reference operator*() const;
+      counting_iterator& operator++();
+      counting_iterator& operator--();
+  private:
+      Incrementable m_inc; // exposition
+  };
 
 
+If the ``Difference`` argument is ``use_default`` then
+``difference_type`` is an unspecified signed integral
+type. Otherwise ``difference_type`` is ``Difference``.
+
+``iterator_category`` is determined according to the following
+algorithm:
+
+.. parsed-literal::
+
+   if (CategoryOrTraversal is not use_default)
+       return CategoryOrTraversal
+   else if (numeric_limits<Incrementable>::is_specialized)
+       return |iterator-category|_\ (
+           random_access_traversal_tag, Incrementable, const Incrementable&)
+   else
+       return |iterator-category|_\ (
+            iterator_traversal<Incrementable>::type, 
+            Incrementable, const Incrementable&)
+        
 [*Note:* implementers are encouraged to provide an implementation of
-  ``distance_to`` and a ``difference_type`` that avoids overflows in
-  the cases when the ``Incrementable`` type is a numeric type.]
+  ``operator-`` and a ``difference_type`` that avoids overflows in
+  the cases where ``std::numeric_limits<Incrementable>::is_specialized``
+  is true.]
 
 ``counting_iterator`` requirements
-----------------------------------
+..................................
 
-The ``Incrementable`` type must be Default Constructible, Copy
-Constructible, and Assignable.  The default distance is
-an implementation defined signed integegral type.
+The ``Incrementable`` argument shall be Copy Constructible and Assignable.
 
-The resulting ``counting_iterator`` models Readable Lvalue Iterator.
-
-Furthermore, if you wish to create a counting iterator that is a Forward
-Traversal Iterator, then the following expressions must be valid:
-::
+If ``iterator_category`` is convertible to ``forward_iterator_tag``
+or ``forward_traversal_tag``, the following must be well-formed::
 
     Incrementable i, j;
-    ++i         // pre-increment
-    i == j      // operator equal
+    ++i;         // pre-increment
+    i == j;      // operator equal
 
-If you wish to create a counting iterator that is a 
-Bidirectional Traversal Iterator, then pre-decrement is also required:
-::
+
+If ``iterator_category`` is convertible to
+``bidirectional_iterator_tag`` or ``bidirectional_traversal_tag``,
+the following expression must also be well-formed::
 
     --i
 
-If you wish to create a counting iterator that is a Random Access
-Traversal Iterator, then these additional expressions are also
-required:
-::
+If ``iterator_category`` is convertible to
+``random_access_iterator_tag`` or ``random_access_traversal_tag``,
+the following must must also be valid::
 
     counting_iterator::difference_type n;
-    i += n
-    n = i - j
-    i < j
+    i += n;
+    n = i - j;
+    i < j;
 
+``counting_iterator`` models
+............................
+
+Specializations of ``counting_iterator`` model Readable Lvalue
+Iterator. In addition, they model the concepts corresponding to the
+iterator tags to which their ``iterator_category`` is convertible.
+Also, if ``CategoryOrTraversal`` is not ``use_default`` then
+``counting_iterator`` models the concept corresponding to the iterator
+tag ``CategoryOrTraversal``.  Otherwise, if
+``numeric_limits<Incrementable>::is_specialized``, then
+``counting_iterator`` models Random Access Traversal Iterator.
+Otherwise, ``counting_iterator`` models the same iterator traversal
+concepts modeled by ``Incrementable``.
+
+``counting_iterator<X,C1,D1>`` is interoperable with
+``counting_iterator<Y,C2,D2>`` if and only if ``X`` is
+interoperable with ``Y``.
 
 
 
 ``counting_iterator`` operations
---------------------------------
+................................
+
+In addition to the operations required by the concepts modeled by
+``counting_iterator``, ``counting_iterator`` provides the following
+operations.
+
 
 ``counting_iterator();``
 
-:Returns: A default constructed instance of ``counting_iterator``.
+:Requires: ``Incrementable`` is Default Constructible.
+:Effects: Default construct the member ``m_inc``.
 
 
 ``counting_iterator(counting_iterator const& rhs);``
 
-:Returns: An instance of ``counting_iterator`` that is a copy of ``rhs``.
+:Effects: Construct member ``m_inc`` from ``rhs.m_inc``.
 
 
 
-``counting_iterator(Incrementable x);``
+``explicit counting_iterator(Incrementable x);``
 
-:Returns: An instance of ``counting_iterator`` with its base
-    object copy constructed from ``x``.
+:Effects: Construct member ``m_inc`` from ``x``.
 
+
+``reference operator*() const;``
+
+:Returns: ``m_inc``
+
+
+``counting_iterator& operator++();``
+
+:Effects: ``++m_inc``
+:Returns: ``*this``
+
+
+``counting_iterator& operator--();``
+
+:Effects: ``--m_inc``
+:Returns: ``*this``  
+
+
+``Incrementable const& base() const;``
+
+:Returns: ``m_inc``

doc/default.css

@@ -5,6 +5,8 @@
 :version: $Revision$
 :copyright: This stylesheet has been placed in the public domain.
 
+boostinspect:nolicense
+
 Default cascading style sheet for the HTML output of Docutils.
 */
 
@@ -29,7 +31,7 @@ div.abstract p.topic-title {
   text-align: center }
 
 div.attention, div.caution, div.danger, div.error, div.hint,
-div.important, div.note, div.tip, div.warning {
+div.important, div.note, div.tip, div.warning, div.admonition {
   margin: 2em ;
   border: medium outset ;
   padding: 1em }
@@ -42,7 +44,8 @@ div.warning p.admonition-title {
   font-family: sans-serif }
 
 div.hint p.admonition-title, div.important p.admonition-title,
-div.note p.admonition-title, div.tip p.admonition-title {
+div.note p.admonition-title, div.tip p.admonition-title,
+div.admonition p.admonition-title {
   font-weight: bold ;
   font-family: sans-serif }
 
@@ -61,6 +64,19 @@ div.figure {
 div.footer, div.header {
   font-size: smaller }
 
+div.sidebar {
+  margin-left: 1em ;
+  border: medium outset ;
+  padding: 0em 1em ;
+  background-color: #ffffee ;
+  width: 40% ;
+  float: right ;
+  clear: right }
+
+div.sidebar p.rubric {
+  font-family: sans-serif ;
+  font-size: medium }
+
 div.system-messages {
   margin: 5em }
 
@@ -105,6 +121,10 @@ ol.lowerroman {
 ol.upperroman {
   list-style: upper-roman }
 
+p.attribution {
+  text-align: right ;
+  margin-left: 50% }
+
 p.caption {
   font-style: italic }
 
@@ -115,6 +135,21 @@ p.credits {
 p.label {
   white-space: nowrap }
 
+p.rubric {
+  font-weight: bold ;
+  font-size: larger ;
+  color: maroon ;
+  text-align: center }
+
+p.sidebar-title {
+  font-family: sans-serif ;
+  font-weight: bold ;
+  font-size: larger }
+
+p.sidebar-subtitle {
+  font-family: sans-serif ;
+  font-weight: bold }
+
 p.topic-title {
   font-weight: bold }
 
@@ -144,6 +179,9 @@ span.classifier-delimiter {
 span.interpreted {
   font-family: sans-serif }
 
+span.option {
+  white-space: nowrap }
+
 span.option-argument {
   font-style: italic }
 

doc/docutils.sty

@@ -0,0 +1,54 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%%%%%%%%%%%%% docutils.sty: A style for docutils latex output %%%%%%%%%%%%%%%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%%
+%% o author: Alexander Schmolck (a.schmolck@gmx.net)
+%% o created: 2002-07-07 10:50:31+00:40
+%% o last modified: $Date: 2004/01/29 05:55:26 $
+%% o keywords: 
+%% o license: 
+%XXX titlesec
+%% XXX geometry
+\usepackage{graphicx}
+\usepackage{latexsym} % extra symbols
+\usepackage{url} % !!!: pay attention when using in other commands!!!
+\usepackage{verbatim} % normal verbatim has lenght-limit
+\usepackage{enumerate} % easy style choice with e.g: ``\begin{enumerate}[Ex i.]``
+\usepackage{hyperref} %href, htarget and hlink XXX: pdfauthor, pdfcreator etc.
+\usepackage{xr} %XXX do we need this?
+% need this to have ``fboxes`` in ``enviroments``, as well as ``verbatim``s
+\usepackage{fancybox} 
+\usepackage{mdwtab} % better tables and arrays (fixes spacing and adds
+                    % vertical align and multirows (m))
+\usepackage{ltxtable} % long and autoscaling tables (use X for autoscaled
+                      % columns)
+\newcommand{\transition}{\vspace{2em}\par\hrule{}\par\vspace{2em}}
+\newcommand{\classifier}[1]{(\textit{#1})}
+\newenvironment{topic}[1]%
+{\begin{Sbox}%
+    \begin{minipage}{.8\textwidth}%
+      \protect{\large{\textbf{#1}}}\par\vspace{.5em}}%
+{\end{minipage}\end{Sbox}\fbox{\TheSbox}\par\vspace{.5em}}
+%XXX shadow box for warnings?
+\newenvironment{admonition}[1]%
+{\begin{center}%
+  \begin{Sbox}%
+    \begin{minipage}{.9\textwidth}%
+      \protect{\textsc{#1}}\par\vspace{.2em}}%
+{\end{minipage}\end{Sbox}\fbox{\TheSbox}\par\vspace{.5em}\end{center}}
+
+\newenvironment{doctest}%
+{\VerbatimEnvironment
+ \begin{Verbatim}}%
+{\end{Verbatim}}
+% {%
+%     \begin{Sbox}%
+%     \begin{minipage}{.8\textwidth}%
+%       \protect{\large{\textsc{#1}}\par\vspace{.5em}}}%
+% {\end{minipage}\end{Sbox}\fbox{\TheSbox}\par\vspace{.5em}}
+%{\end{minipage}\end{Sbox}\fbox{\TheSbox}}
+
+
+%% just a piece of example code
+% \newcommand{\vitem}%
+% {\SaveVerb[{\item[\UseVerb{\MyTemp}]}]{\MyTemp}}

doc/facade-and-adaptor.rst

@@ -1,12 +1,15 @@
+.. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
 +++++++++++++++++++++++++++++
  Iterator Facade and Adaptor
 +++++++++++++++++++++++++++++
 
 :Author: David Abrahams, Jeremy Siek, Thomas Witt
-:Contact: dave@boost-consulting.com, jsiek@osl.iu.edu, witt@acm.org
+:Contact: dave@boost-consulting.com, jsiek@osl.iu.edu, witt@styleadvisor.com
 :organization: `Boost Consulting`_, Indiana University `Open Systems
-               Lab`_, University of Hanover `Institute for Transport
-               Railway Operation and Construction`_
+               Lab`_, `Zephyr Associates, Inc.`_
 :date: $Date$
 
 :Number: This is a revised version of N1530_\ =03-0113, which was
@@ -16,13 +19,13 @@
 .. Version 1.9 of this ReStructuredText document corresponds to
    n1530_, the paper accepted by the LWG.
 
-.. _n1530: http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2003/n1530.html
+.. _n1530: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2003/n1530.html
 
-:copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved
+:copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. 
 
 .. _`Boost Consulting`: http://www.boost-consulting.com
 .. _`Open Systems Lab`: http://www.osl.iu.edu
-.. _`Institute for Transport Railway Operation and Construction`: http://www.ive.uni-hannover.de
+.. _`Zephyr Associates, Inc.`: http://www.styleadvisor.com
 
 :abstract: We propose a set of class templates that help programmers
            build standard-conforming iterators, both from scratch and
@@ -137,7 +140,7 @@ as proposed in n1550_, since user-defined and especially adapted
 iterators suffer from the well known categorization problems that are
 inherent to the current iterator categories.
 
-.. _n1550: http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/papers/2003/n1550.html
+.. _n1550: http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2003/n1550.htm
 
 This proposal does not strictly depend on proposal n1550_, as there
 is a direct mapping between new and old categories. This proposal
@@ -166,8 +169,8 @@ reverse iterator types. The proposed new reverse_iterator template
 fixes the issues raised in 280. It provides the desired
 interoperability without introducing unwanted overloads.
 
-.. _179: http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/lwg-defects.html#179
-.. _280: http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/lwg-active.html#280
+.. _179: http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#179
+.. _280: http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-active.html#280
 
 
 Iterator Facade
@@ -197,10 +200,6 @@ which were easily implemented using ``iterator_adaptor``:
 * ``transform_iterator``, which applies a user-defined function object
   to the underlying values when dereferenced.
 
-* ``projection_iterator``, which is similar to ``transform_iterator``
-  except that when dereferenced it returns a reference instead of
-  a value.
-
 * ``filter_iterator``, which provides a view of an iterator range in
   which some elements of the underlying range are skipped.
 
@@ -266,6 +265,12 @@ Header ``<iterator_helper>`` synopsis    [lib.iterator.helper.synopsis]
   >
   class indirect_iterator;
   
+  template <class Dereferenceable>
+  struct pointee;
+
+  template <class Dereferenceable>
+  struct indirect_reference;
+
   template <class Iterator>
   class reverse_iterator;
 
@@ -285,7 +290,7 @@ Header ``<iterator_helper>`` synopsis    [lib.iterator.helper.synopsis]
     , class CategoryOrTraversal  = use_default
     , class Difference = use_default
   >
-  class counting_iterator
+  class counting_iterator;
 
   template <class UnaryFunction>
   class function_output_iterator;
@@ -352,6 +357,16 @@ Indirect iterator
 
 .. include:: indirect_iterator_abstract.rst
 
+Class template ``pointee``
+....................................
+
+.. include:: pointee_ref.rst
+
+Class template ``indirect_reference``
+.....................................
+
+.. include:: indirect_reference_ref.rst
+
 Class template ``indirect_iterator``
 ....................................
 
@@ -405,12 +420,12 @@ Class template ``counting_iterator``
 Function output iterator
 ------------------------
 
-.. include:: function_output_iterator_abstract.rst
+.. include:: func_output_iter_abstract.rst
 
 Class template ``function_output_iterator``
 ...........................................
 
-.. include:: function_output_iterator_ref.rst
+.. include:: func_output_iter_ref.rst
 
 
 

doc/facade_iterator_category.rst

@@ -0,0 +1,53 @@
+.. |iterator-category| replace:: *iterator-category*
+.. _iterator-category:
+
+.. parsed-literal::
+  
+  *iterator-category*\ (C,R,V) :=
+     if (C is convertible to std::input_iterator_tag
+         || C is convertible to std::output_iterator_tag
+     )
+         return C
+
+     else if (C is not convertible to incrementable_traversal_tag)
+         *the program is ill-formed*
+
+     else return a type X satisfying the following two constraints:
+
+        1. X is convertible to X1, and not to any more-derived
+           type, where X1 is defined by:
+
+             if (R is a reference type
+                 && C is convertible to forward_traversal_tag)
+             {
+                 if (C is convertible to random_access_traversal_tag)
+                     X1 = random_access_iterator_tag
+                 else if (C is convertible to bidirectional_traversal_tag)
+                     X1 = bidirectional_iterator_tag
+                 else
+                     X1 = forward_iterator_tag
+             }
+             else
+             {
+                 if (C is convertible to single_pass_traversal_tag
+                     && R is convertible to V)
+                     X1 = input_iterator_tag
+                 else
+                     X1 = C
+             }
+
+        2. |category-to-traversal|_\ (X) is convertible to the most
+           derived traversal tag type to which X is also
+           convertible, and not to any more-derived traversal tag
+           type.
+
+.. |category-to-traversal| replace:: *category-to-traversal*
+.. _`category-to-traversal`: new-iter-concepts.html#category-to-traversal
+
+[Note: the intention is to allow ``iterator_category`` to be one of
+the five original category tags when convertibility to one of the
+traversal tags would add no information]
+
+.. Copyright David Abrahams 2004. Use, modification and distribution is
+.. subject to the Boost Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

doc/filter_iterator.html

@@ -3,204 +3,13 @@
 <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.1: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
 <title>Filter Iterator</title>
 <meta name="author" content="David Abrahams, Jeremy Siek, Thomas Witt" />
 <meta name="organization" content="Boost Consulting, Indiana University Open Systems Lab, University of Hanover Institute for Transport Railway Operation and Construction" />
-<meta name="date" content="2003-09-14" />
-<meta name="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved" />
-<style type="text/css"><!--
-
-/*
-:Author: David Goodger
-:Contact: goodger@users.sourceforge.net
-:date: $Date$
-:version: $Revision$
-:copyright: This stylesheet has been placed in the public domain.
-
-Default cascading style sheet for the HTML output of Docutils.
-*/
-
-.first {
-  margin-top: 0 }
-
-.last {
-  margin-bottom: 0 }
-
-a.toc-backref {
-  text-decoration: none ;
-  color: black }
-
-dd {
-  margin-bottom: 0.5em }
-
-div.abstract {
-  margin: 2em 5em }
-
-div.abstract p.topic-title {
-  font-weight: bold ;
-  text-align: center }
-
-div.attention, div.caution, div.danger, div.error, div.hint,
-div.important, div.note, div.tip, div.warning {
-  margin: 2em ;
-  border: medium outset ;
-  padding: 1em }
-
-div.attention p.admonition-title, div.caution p.admonition-title,
-div.danger p.admonition-title, div.error p.admonition-title,
-div.warning p.admonition-title {
-  color: red ;
-  font-weight: bold ;
-  font-family: sans-serif }
-
-div.hint p.admonition-title, div.important p.admonition-title,
-div.note p.admonition-title, div.tip p.admonition-title {
-  font-weight: bold ;
-  font-family: sans-serif }
-
-div.dedication {
-  margin: 2em 5em ;
-  text-align: center ;
-  font-style: italic }
-
-div.dedication p.topic-title {
-  font-weight: bold ;
-  font-style: normal }
-
-div.figure {
-  margin-left: 2em }
-
-div.footer, div.header {
-  font-size: smaller }
-
-div.system-messages {
-  margin: 5em }
-
-div.system-messages h1 {
-  color: red }
-
-div.system-message {
-  border: medium outset ;
-  padding: 1em }
-
-div.system-message p.system-message-title {
-  color: red ;
-  font-weight: bold }
-
-div.topic {
-  margin: 2em }
-
-h1.title {
-  text-align: center }
-
-h2.subtitle {
-  text-align: center }
-
-hr {
-  width: 75% }
-
-ol.simple, ul.simple {
-  margin-bottom: 1em }
-
-ol.arabic {
-  list-style: decimal }
-
-ol.loweralpha {
-  list-style: lower-alpha }
-
-ol.upperalpha {
-  list-style: upper-alpha }
-
-ol.lowerroman {
-  list-style: lower-roman }
-
-ol.upperroman {
-  list-style: upper-roman }
-
-p.caption {
-  font-style: italic }
-
-p.credits {
-  font-style: italic ;
-  font-size: smaller }
-
-p.label {
-  white-space: nowrap }
-
-p.topic-title {
-  font-weight: bold }
-
-pre.address {
-  margin-bottom: 0 ;
-  margin-top: 0 ;
-  font-family: serif ;
-  font-size: 100% }
-
-pre.line-block {
-  font-family: serif ;
-  font-size: 100% }
-
-pre.literal-block, pre.doctest-block {
-  margin-left: 2em ;
-  margin-right: 2em ;
-  background-color: #eeeeee }
-
-span.classifier {
-  font-family: sans-serif ;
-  font-style: oblique }
-
-span.classifier-delimiter {
-  font-family: sans-serif ;
-  font-weight: bold }
-
-span.interpreted {
-  font-family: sans-serif }
-
-span.option-argument {
-  font-style: italic }
-
-span.pre {
-  white-space: pre }
-
-span.problematic {
-  color: red }
-
-table {
-  margin-top: 0.5em ;
-  margin-bottom: 0.5em }
-
-table.citation {
-  border-left: solid thin gray ;
-  padding-left: 0.5ex }
-
-table.docinfo {
-  margin: 2em 4em }
-
-table.footnote {
-  border-left: solid thin black ;
-  padding-left: 0.5ex }
-
-td, th {
-  padding-left: 0.5em ;
-  padding-right: 0.5em ;
-  vertical-align: top }
-
-th.docinfo-name, th.field-name {
-  font-weight: bold ;
-  text-align: left ;
-  white-space: nowrap }
-
-h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
-  font-size: 100% }
-
-tt {
-  background-color: #eeeeee }
-
-ul.auto-toc {
-  list-style-type: none }
-
---></style>
+<meta name="date" content="2006-09-11" />
+<meta name="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003." />
+<link rel="stylesheet" href="../../../rst.css" type="text/css" />
 </head>
 <body>
 <div class="document" id="filter-iterator">
@@ -212,52 +21,67 @@ ul.auto-toc {
 <tr><th class="docinfo-name">Author:</th>
 <td>David Abrahams, Jeremy Siek, Thomas Witt</td></tr>
 <tr><th class="docinfo-name">Contact:</th>
-<td><a class="first reference" href="mailto:dave&#64;boost-consulting.com">dave&#64;boost-consulting.com</a>, <a class="reference" href="mailto:jsiek&#64;osl.iu.edu">jsiek&#64;osl.iu.edu</a>, <a class="last reference" href="mailto:witt&#64;ive.uni-hannover.de">witt&#64;ive.uni-hannover.de</a></td></tr>
+<td><a class="first reference external" href="mailto:dave&#64;boost-consulting.com">dave&#64;boost-consulting.com</a>, <a class="reference external" href="mailto:jsiek&#64;osl.iu.edu">jsiek&#64;osl.iu.edu</a>, <a class="last reference external" href="mailto:witt&#64;ive.uni-hannover.de">witt&#64;ive.uni-hannover.de</a></td></tr>
 <tr><th class="docinfo-name">Organization:</th>
-<td><a class="first reference" href="http://www.boost-consulting.com">Boost Consulting</a>, Indiana University <a class="reference" href="http://www.osl.iu.edu">Open Systems
-Lab</a>, University of Hanover <a class="last reference" href="http://www.ive.uni-hannover.de">Institute for Transport
+<td><a class="first reference external" href="http://www.boost-consulting.com">Boost Consulting</a>, Indiana University <a class="reference external" href="http://www.osl.iu.edu">Open Systems
+Lab</a>, University of Hanover <a class="last reference external" href="http://www.ive.uni-hannover.de">Institute for Transport
 Railway Operation and Construction</a></td></tr>
 <tr><th class="docinfo-name">Date:</th>
-<td>2003-09-14</td></tr>
+<td>2006-09-11</td></tr>
 <tr><th class="docinfo-name">Copyright:</th>
-<td>Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved</td></tr>
+<td>Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003.</td></tr>
 </tbody>
 </table>
-<table class="field-list" frame="void" rules="none">
+<!-- Distributed under the Boost -->
+<!-- Software License, Version 1.0. (See accompanying -->
+<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
+<table class="docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
-<tr class="field"><th class="field-name">abstract:</th><td class="field-body"></td>
+<tr class="field"><th class="field-name">abstract:</th><td class="field-body"><!-- Copyright David Abrahams 2006. Distributed under the Boost -->
+<!-- Software License, Version 1.0. (See accompanying -->
+<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
+The filter iterator adaptor creates a view of an iterator range in
+which some elements of the range are skipped. A predicate function
+object controls which elements are skipped. When the predicate is
+applied to an element, if it returns <tt class="docutils literal"><span class="pre">true</span></tt> then the element is
+retained and if it returns <tt class="docutils literal"><span class="pre">false</span></tt> then the element is skipped
+over. When skipping over elements, it is necessary for the filter
+adaptor to know when to stop so as to avoid going past the end of the
+underlying range. A filter iterator is therefore constructed with pair
+of iterators indicating the range of elements in the unfiltered
+sequence to be traversed.</td>
 </tr>
 </tbody>
 </table>
-<p>The filter iterator adaptor creates a view of an iterator range in
-which some elements of the range are skipped over. A predicate
-function object controls which elements are skipped. When the
-predicate is applied to an element, if it returns <tt class="literal"><span class="pre">true</span></tt> then the
-element is retained and if it returns <tt class="literal"><span class="pre">false</span></tt> then the element is
-skipped over. When skipping over elements, it is necessary for the
-filter adaptor to know when to stop so as to avoid going past the end
-of the underlying range. Therefore the constructor of the filter
-iterator takes two iterator parameters: the position for the filtered
-iterator and the end of the range.</p>
 <div class="contents topic" id="table-of-contents">
-<p class="topic-title"><a name="table-of-contents">Table of Contents</a></p>
+<p class="topic-title first">Table of Contents</p>
 <ul class="simple">
-<li><a class="reference" href="#filter-iterator-requirements" id="id1" name="id1"><tt class="literal"><span class="pre">filter_iterator</span></tt> requirements</a></li>
-<li><a class="reference" href="#filter-iterator-operations" id="id2" name="id2"><tt class="literal"><span class="pre">filter_iterator</span></tt> operations</a></li>
+<li><a class="reference internal" href="#filter-iterator-synopsis" id="id2"><tt class="docutils literal"><span class="pre">filter_iterator</span></tt> synopsis</a></li>
+<li><a class="reference internal" href="#filter-iterator-requirements" id="id3"><tt class="docutils literal"><span class="pre">filter_iterator</span></tt> requirements</a></li>
+<li><a class="reference internal" href="#filter-iterator-models" id="id4"><tt class="docutils literal"><span class="pre">filter_iterator</span></tt> models</a></li>
+<li><a class="reference internal" href="#filter-iterator-operations" id="id5"><tt class="docutils literal"><span class="pre">filter_iterator</span></tt> operations</a></li>
+<li><a class="reference internal" href="#example" id="id6">Example</a></li>
 </ul>
 </div>
+<div class="section" id="filter-iterator-synopsis">
+<h1><a class="toc-backref" href="#id2"><tt class="docutils literal"><span class="pre">filter_iterator</span></tt> synopsis</a></h1>
+<!-- Copyright David Abrahams, Jeremy Siek, and Thomas Witt -->
+<!-- 2004. Use, modification and distribution is subject to the Boost -->
+<!-- Software License, Version 1.0. (See accompanying  file -->
+<!-- LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
 <pre class="literal-block">
 template &lt;class Predicate, class Iterator&gt;
 class filter_iterator
-    : public iterator_adaptor&lt;
-          filter_iterator&lt;Predicate, Iterator&gt;, Iterator
-        , use_default
-        , /* see details */
-      &gt;
 {
  public:
+    typedef iterator_traits&lt;Iterator&gt;::value_type value_type;
+    typedef iterator_traits&lt;Iterator&gt;::reference reference;
+    typedef iterator_traits&lt;Iterator&gt;::pointer pointer;
+    typedef iterator_traits&lt;Iterator&gt;::difference_type difference_type;
+    typedef /* see below */ iterator_category;
+
     filter_iterator();
     filter_iterator(Predicate f, Iterator x, Iterator end = Iterator());
     filter_iterator(Iterator x, Iterator end = Iterator());
@@ -268,76 +92,152 @@ class filter_iterator
         );
     Predicate predicate() const;
     Iterator end() const;
-
- private: // as-if specification
-    void increment()
-    {
-        ++(this-&gt;base_reference());
-        satisfy_predicate();
-    }
-
-    void satisfy_predicate()
-    {
-        while (this-&gt;base() != this-&gt;m_end &amp;&amp; !this-&gt;m_predicate(*this-&gt;base()))
-            ++(this-&gt;base_reference());
-    }
-
-    Predicate m_predicate;
-    Iterator m_end;
+    Iterator const&amp; base() const;
+    reference operator*() const;
+    filter_iterator&amp; operator++();
+private:
+    Predicate m_pred; // exposition only
+    Iterator m_iter;  // exposition only
+    Iterator m_end;   // exposition only
 };
 </pre>
+<p>If <tt class="docutils literal"><span class="pre">Iterator</span></tt> models Readable Lvalue Iterator and Bidirectional Traversal
+Iterator then <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is convertible to
+<tt class="docutils literal"><span class="pre">std::bidirectional_iterator_tag</span></tt>.
+Otherwise, if <tt class="docutils literal"><span class="pre">Iterator</span></tt> models Readable Lvalue Iterator and Forward Traversal
+Iterator then <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is convertible to
+<tt class="docutils literal"><span class="pre">std::forward_iterator_tag</span></tt>.
+Otherwise <tt class="docutils literal"><span class="pre">iterator_category</span></tt> is
+convertible to <tt class="docutils literal"><span class="pre">std::input_iterator_tag</span></tt>.</p>
+</div>
 <div class="section" id="filter-iterator-requirements">
-<h1><a class="toc-backref" href="#id1" name="filter-iterator-requirements"><tt class="literal"><span class="pre">filter_iterator</span></tt> requirements</a></h1>
-<p>The base <tt class="literal"><span class="pre">Iterator</span></tt> parameter must be a model of Readable
-Iterator and Single Pass Iterator. The resulting
-<tt class="literal"><span class="pre">filter_iterator</span></tt> will be a model of Forward Traversal Iterator
-if <tt class="literal"><span class="pre">Iterator</span></tt> is, otherwise the <tt class="literal"><span class="pre">filter_iterator</span></tt> will be a
-model of Single Pass Iterator. The access category of the
-<tt class="literal"><span class="pre">filter_iterator</span></tt> will be the same as the access category of
-<tt class="literal"><span class="pre">Iterator</span></tt>.</p>
-<!-- Thomas is going to try implementing filter_iterator so that
-it will be bidirectional if the underlying iterator is. -JGS -->
-<p>The <tt class="literal"><span class="pre">Predicate</span></tt> must be Assignable, Copy Constructible, and the
-expression <tt class="literal"><span class="pre">p(x)</span></tt> must be valid where <tt class="literal"><span class="pre">p</span></tt> is an object of type
-<tt class="literal"><span class="pre">Predicate</span></tt>, <tt class="literal"><span class="pre">x</span></tt> is an object of type
-<tt class="literal"><span class="pre">iterator_traits&lt;Iterator&gt;::value_type</span></tt>, and where the type of
-<tt class="literal"><span class="pre">p(x)</span></tt> must be convertible to <tt class="literal"><span class="pre">bool</span></tt>.</p>
+<h1><a class="toc-backref" href="#id3"><tt class="docutils literal"><span class="pre">filter_iterator</span></tt> requirements</a></h1>
+<p>The <tt class="docutils literal"><span class="pre">Iterator</span></tt> argument shall meet the requirements of Readable
+Iterator and Single Pass Iterator or it shall meet the requirements of
+Input Iterator.</p>
+<p>The <tt class="docutils literal"><span class="pre">Predicate</span></tt> argument must be Assignable, Copy Constructible, and
+the expression <tt class="docutils literal"><span class="pre">p(x)</span></tt> must be valid where <tt class="docutils literal"><span class="pre">p</span></tt> is an object of type
+<tt class="docutils literal"><span class="pre">Predicate</span></tt>, <tt class="docutils literal"><span class="pre">x</span></tt> is an object of type
+<tt class="docutils literal"><span class="pre">iterator_traits&lt;Iterator&gt;::value_type</span></tt>, and where the type of
+<tt class="docutils literal"><span class="pre">p(x)</span></tt> must be convertible to <tt class="docutils literal"><span class="pre">bool</span></tt>.</p>
+</div>
+<div class="section" id="filter-iterator-models">
+<h1><a class="toc-backref" href="#id4"><tt class="docutils literal"><span class="pre">filter_iterator</span></tt> models</a></h1>
+<p>The concepts that <tt class="docutils literal"><span class="pre">filter_iterator</span></tt> models are dependent on which
+concepts the <tt class="docutils literal"><span class="pre">Iterator</span></tt> argument models, as specified in the
+following tables.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="44%" />
+<col width="56%" />
+</colgroup>
+<thead valign="bottom">
+<tr><th class="head">If <tt class="docutils literal"><span class="pre">Iterator</span></tt> models</th>
+<th class="head">then <tt class="docutils literal"><span class="pre">filter_iterator</span></tt> models</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr><td>Single Pass Iterator</td>
+<td>Single Pass Iterator</td>
+</tr>
+<tr><td>Forward Traversal Iterator</td>
+<td>Forward Traversal Iterator</td>
+</tr>
+<tr><td>Bidirectional Traversal Iterator</td>
+<td>Bidirectional Traversal Iterator</td>
+</tr>
+</tbody>
+</table>
+<table border="1" class="docutils">
+<colgroup>
+<col width="41%" />
+<col width="59%" />
+</colgroup>
+<thead valign="bottom">
+<tr><th class="head">If <tt class="docutils literal"><span class="pre">Iterator</span></tt> models</th>
+<th class="head">then <tt class="docutils literal"><span class="pre">filter_iterator</span></tt> models</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr><td>Readable Iterator</td>
+<td>Readable Iterator</td>
+</tr>
+<tr><td>Writable Iterator</td>
+<td>Writable Iterator</td>
+</tr>
+<tr><td>Lvalue Iterator</td>
+<td>Lvalue Iterator</td>
+</tr>
+</tbody>
+</table>
+<table border="1" class="docutils">
+<colgroup>
+<col width="63%" />
+<col width="38%" />
+</colgroup>
+<thead valign="bottom">
+<tr><th class="head">If <tt class="docutils literal"><span class="pre">Iterator</span></tt> models</th>
+<th class="head">then <tt class="docutils literal"><span class="pre">filter_iterator</span></tt> models</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr><td>Readable Iterator, Single Pass Iterator</td>
+<td>Input Iterator</td>
+</tr>
+<tr><td>Readable Lvalue Iterator, Forward Traversal Iterator</td>
+<td>Forward Iterator</td>
+</tr>
+<tr><td>Writable Lvalue Iterator, Forward Traversal Iterator</td>
+<td>Mutable Forward Iterator</td>
+</tr>
+<tr><td>Writable Lvalue Iterator, Bidirectional Iterator</td>
+<td>Mutable Bidirectional Iterator</td>
+</tr>
+</tbody>
+</table>
+<p><tt class="docutils literal"><span class="pre">filter_iterator&lt;P1,</span> <span class="pre">X&gt;</span></tt> is interoperable with <tt class="docutils literal"><span class="pre">filter_iterator&lt;P2,</span> <span class="pre">Y&gt;</span></tt>
+if and only if <tt class="docutils literal"><span class="pre">X</span></tt> is interoperable with <tt class="docutils literal"><span class="pre">Y</span></tt>.</p>
 </div>
 <div class="section" id="filter-iterator-operations">
-<h1><a class="toc-backref" href="#id2" name="filter-iterator-operations"><tt class="literal"><span class="pre">filter_iterator</span></tt> operations</a></h1>
-<p><tt class="literal"><span class="pre">filter_iterator();</span></tt></p>
-<table class="field-list" frame="void" rules="none">
+<h1><a class="toc-backref" href="#id5"><tt class="docutils literal"><span class="pre">filter_iterator</span></tt> operations</a></h1>
+<p>In addition to those operations required by the concepts that
+<tt class="docutils literal"><span class="pre">filter_iterator</span></tt> models, <tt class="docutils literal"><span class="pre">filter_iterator</span></tt> provides the following
+operations.</p>
+<p><tt class="docutils literal"><span class="pre">filter_iterator();</span></tt></p>
+<table class="docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
-<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="literal"><span class="pre">Predicate</span></tt> and <tt class="literal"><span class="pre">Iterator</span></tt> must be Default Constructible.</td>
+<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="docutils literal"><span class="pre">Predicate</span></tt> and <tt class="docutils literal"><span class="pre">Iterator</span></tt> must be Default Constructible.</td>
 </tr>
-<tr class="field"><th class="field-name">Returns:</th><td class="field-body">a <tt class="literal"><span class="pre">filter_iterator</span></tt> whose
-predicate is a default constructed <tt class="literal"><span class="pre">Predicate</span></tt> and
-whose <tt class="literal"><span class="pre">end</span></tt> is a default constructed <tt class="literal"><span class="pre">Iterator</span></tt>.</td>
+<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Constructs a <tt class="docutils literal"><span class="pre">filter_iterator</span></tt> whose``m_pred``,  <tt class="docutils literal"><span class="pre">m_iter</span></tt>, and <tt class="docutils literal"><span class="pre">m_end</span></tt>
+members are a default constructed.</td>
 </tr>
 </tbody>
 </table>
-<p><tt class="literal"><span class="pre">filter_iterator(Predicate</span> <span class="pre">f,</span> <span class="pre">Iterator</span> <span class="pre">x,</span> <span class="pre">Iterator</span> <span class="pre">end</span> <span class="pre">=</span> <span class="pre">Iterator());</span></tt></p>
-<table class="field-list" frame="void" rules="none">
+<p><tt class="docutils literal"><span class="pre">filter_iterator(Predicate</span> <span class="pre">f,</span> <span class="pre">Iterator</span> <span class="pre">x,</span> <span class="pre">Iterator</span> <span class="pre">end</span> <span class="pre">=</span> <span class="pre">Iterator());</span></tt></p>
+<table class="docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
-<tr class="field"><th class="field-name">Returns:</th><td class="field-body">A <tt class="literal"><span class="pre">filter_iterator</span></tt> at position <tt class="literal"><span class="pre">x</span></tt> that filters according
-to predicate <tt class="literal"><span class="pre">f</span></tt> and that will not increment past <tt class="literal"><span class="pre">end</span></tt>.</td>
+<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Constructs a <tt class="docutils literal"><span class="pre">filter_iterator</span></tt> where <tt class="docutils literal"><span class="pre">m_iter</span></tt> is either
+the first position in the range <tt class="docutils literal"><span class="pre">[x,end)</span></tt> such that <tt class="docutils literal"><span class="pre">f(*m_iter)</span> <span class="pre">==</span> <span class="pre">true</span></tt>
+or else``m_iter == end``. The member <tt class="docutils literal"><span class="pre">m_pred</span></tt> is constructed from
+<tt class="docutils literal"><span class="pre">f</span></tt> and <tt class="docutils literal"><span class="pre">m_end</span></tt> from <tt class="docutils literal"><span class="pre">end</span></tt>.</td>
 </tr>
 </tbody>
 </table>
-<p><tt class="literal"><span class="pre">filter_iterator(Iterator</span> <span class="pre">x,</span> <span class="pre">Iterator</span> <span class="pre">end</span> <span class="pre">=</span> <span class="pre">Iterator());</span></tt></p>
-<table class="field-list" frame="void" rules="none">
+<p><tt class="docutils literal"><span class="pre">filter_iterator(Iterator</span> <span class="pre">x,</span> <span class="pre">Iterator</span> <span class="pre">end</span> <span class="pre">=</span> <span class="pre">Iterator());</span></tt></p>
+<table class="docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
-<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="literal"><span class="pre">Predicate</span></tt> must be Default Constructible.</td>
+<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="docutils literal"><span class="pre">Predicate</span></tt> must be Default Constructible and
+<tt class="docutils literal"><span class="pre">Predicate</span></tt> is a class type (not a function pointer).</td>
 </tr>
-<tr class="field"><th class="field-name">Returns:</th><td class="field-body">A <tt class="literal"><span class="pre">filter_iterator</span></tt> at position <tt class="literal"><span class="pre">x</span></tt> that filters 
-according to a default constructed <tt class="literal"><span class="pre">Predicate</span></tt>
-and that will not increment past <tt class="literal"><span class="pre">end</span></tt>.</td>
+<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Constructs a <tt class="docutils literal"><span class="pre">filter_iterator</span></tt> where <tt class="docutils literal"><span class="pre">m_iter</span></tt> is either
+the first position in the range <tt class="docutils literal"><span class="pre">[x,end)</span></tt> such that <tt class="docutils literal"><span class="pre">m_pred(*m_iter)</span> <span class="pre">==</span> <span class="pre">true</span></tt>
+or else``m_iter == end``. The member <tt class="docutils literal"><span class="pre">m_pred</span></tt> is default constructed.</td>
 </tr>
 </tbody>
 </table>
@@ -348,41 +248,166 @@ filter_iterator(
     , typename enable_if_convertible&lt;OtherIterator, Iterator&gt;::type* = 0 // exposition
     );``
 </pre>
-<table class="field-list" frame="void" rules="none">
+<table class="docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
-<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="literal"><span class="pre">OtherIterator</span></tt> is implicitly convertible to <tt class="literal"><span class="pre">Iterator</span></tt>.</td>
+<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="docutils literal"><span class="pre">OtherIterator</span></tt> is implicitly convertible to <tt class="docutils literal"><span class="pre">Iterator</span></tt>.</td>
 </tr>
-<tr class="field"><th class="field-name">Returns:</th><td class="field-body">A copy of iterator <tt class="literal"><span class="pre">t</span></tt>.</td>
+<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Constructs a filter iterator whose members are copied from <tt class="docutils literal"><span class="pre">t</span></tt>.</td>
 </tr>
 </tbody>
 </table>
-<p><tt class="literal"><span class="pre">Predicate</span> <span class="pre">predicate()</span> <span class="pre">const;</span></tt></p>
-<table class="field-list" frame="void" rules="none">
+<p><tt class="docutils literal"><span class="pre">Predicate</span> <span class="pre">predicate()</span> <span class="pre">const;</span></tt></p>
+<table class="docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
-<tr class="field"><th class="field-name">Returns:</th><td class="field-body">A copy of the predicate object used to construct <tt class="literal"><span class="pre">*this</span></tt>.</td>
+<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">m_pred</span></tt></td>
 </tr>
 </tbody>
 </table>
-<p><tt class="literal"><span class="pre">Iterator</span> <span class="pre">end()</span> <span class="pre">const;</span></tt></p>
-<table class="field-list" frame="void" rules="none">
+<p><tt class="docutils literal"><span class="pre">Iterator</span> <span class="pre">end()</span> <span class="pre">const;</span></tt></p>
+<table class="docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
-<tr class="field"><th class="field-name">Returns:</th><td class="field-body">The object <tt class="literal"><span class="pre">end</span></tt> used to construct <tt class="literal"><span class="pre">*this</span></tt>.</td>
+<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">m_end</span></tt></td>
 </tr>
 </tbody>
 </table>
+<p><tt class="docutils literal"><span class="pre">Iterator</span> <span class="pre">const&amp;</span> <span class="pre">base()</span> <span class="pre">const;</span></tt></p>
+<table class="docutils field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">m_iterator</span></tt></td>
+</tr>
+</tbody>
+</table>
+<p><tt class="docutils literal"><span class="pre">reference</span> <span class="pre">operator*()</span> <span class="pre">const;</span></tt></p>
+<table class="docutils field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">*m_iter</span></tt></td>
+</tr>
+</tbody>
+</table>
+<p><tt class="docutils literal"><span class="pre">filter_iterator&amp;</span> <span class="pre">operator++();</span></tt></p>
+<table class="docutils field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Increments <tt class="docutils literal"><span class="pre">m_iter</span></tt> and then continues to
+increment <tt class="docutils literal"><span class="pre">m_iter</span></tt> until either <tt class="docutils literal"><span class="pre">m_iter</span> <span class="pre">==</span> <span class="pre">m_end</span></tt>
+or <tt class="docutils literal"><span class="pre">m_pred(*m_iter)</span> <span class="pre">==</span> <span class="pre">true</span></tt>.</td>
+</tr>
+<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">*this</span></tt></td>
+</tr>
+</tbody>
+</table>
+<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
+<!-- Software License, Version 1.0. (See accompanying -->
+<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
+<pre class="literal-block">
+template &lt;class Predicate, class Iterator&gt;
+filter_iterator&lt;Predicate,Iterator&gt;
+make_filter_iterator(Predicate f, Iterator x, Iterator end = Iterator());
+</pre>
+<table class="docutils field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field"><th class="field-name">Returns:</th><td class="field-body">filter_iterator&lt;Predicate,Iterator&gt;(f, x, end)</td>
+</tr>
+</tbody>
+</table>
+<pre class="literal-block">
+template &lt;class Predicate, class Iterator&gt;
+filter_iterator&lt;Predicate,Iterator&gt;
+make_filter_iterator(Iterator x, Iterator end = Iterator());
+</pre>
+<table class="docutils field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field"><th class="field-name">Returns:</th><td class="field-body">filter_iterator&lt;Predicate,Iterator&gt;(x, end)</td>
+</tr>
+</tbody>
+</table>
+<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
+<!-- Software License, Version 1.0. (See accompanying -->
+<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
+</div>
+<div class="section" id="example">
+<h1><a class="toc-backref" href="#id6">Example</a></h1>
+<p>This example uses <tt class="docutils literal"><span class="pre">filter_iterator</span></tt> and then
+<tt class="docutils literal"><span class="pre">make_filter_iterator</span></tt> to output only the positive integers from an
+array of integers. Then <tt class="docutils literal"><span class="pre">make_filter_iterator</span></tt> is is used to output
+the integers greater than <tt class="docutils literal"><span class="pre">-2</span></tt>.</p>
+<pre class="literal-block">
+struct is_positive_number {
+  bool operator()(int x) { return 0 &lt; x; }
+};
+
+int main()
+{
+  int numbers_[] = { 0, -1, 4, -3, 5, 8, -2 };
+  const int N = sizeof(numbers_)/sizeof(int);
+
+  typedef int* base_iterator;
+  base_iterator numbers(numbers_);
+
+  // Example using filter_iterator
+  typedef boost::filter_iterator&lt;is_positive_number, base_iterator&gt;
+    FilterIter;
+
+  is_positive_number predicate;
+  FilterIter filter_iter_first(predicate, numbers, numbers + N);
+  FilterIter filter_iter_last(predicate, numbers + N, numbers + N);
+
+  std::copy(filter_iter_first, filter_iter_last, std::ostream_iterator&lt;int&gt;(std::cout, &quot; &quot;));
+  std::cout &lt;&lt; std::endl;
+
+  // Example using make_filter_iterator()
+  std::copy(boost::make_filter_iterator&lt;is_positive_number&gt;(numbers, numbers + N),
+            boost::make_filter_iterator&lt;is_positive_number&gt;(numbers + N, numbers + N),
+            std::ostream_iterator&lt;int&gt;(std::cout, &quot; &quot;));
+  std::cout &lt;&lt; std::endl;
+
+  // Another example using make_filter_iterator()
+  std::copy(
+      boost::make_filter_iterator(
+          std::bind2nd(std::greater&lt;int&gt;(), -2)
+        , numbers, numbers + N)
+
+    , boost::make_filter_iterator(
+          std::bind2nd(std::greater&lt;int&gt;(), -2)
+        , numbers + N, numbers + N)
+
+    , std::ostream_iterator&lt;int&gt;(std::cout, &quot; &quot;)
+  );
+
+  std::cout &lt;&lt; std::endl;
+
+  return boost::exit_success;
+}
+</pre>
+<p>The output is:</p>
+<pre class="literal-block">
+4 5 8
+4 5 8
+0 -1 4 5 8
+</pre>
+<p>The source code for this example can be found <a class="reference external" href="../example/filter_iterator_example.cpp">here</a>.</p>
 </div>
 </div>
-<hr class="footer" />
 <div class="footer">
-<a class="reference" href="filter_iterator.rst">View document source</a>.
-Generated on: 2003-11-24 05:00 UTC.
-Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
+<hr class="footer" />
+<a class="reference external" href="filter_iterator.rst">View document source</a>.
+Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
+
 </div>
 </body>
 </html>

doc/filter_iterator.rst

@@ -1,3 +1,7 @@
+.. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
 +++++++++++++++++
  Filter Iterator
 +++++++++++++++++
@@ -8,7 +12,7 @@
                Lab`_, University of Hanover `Institute for Transport
                Railway Operation and Construction`_
 :date: $Date$
-:copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved
+:copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. 
 
 .. _`Boost Consulting`: http://www.boost-consulting.com
 .. _`Open Systems Lab`: http://www.osl.iu.edu
@@ -16,8 +20,14 @@
 
 :abstract:
 
-.. include:: filter_iterator_abstract.rst
+  .. include:: filter_iterator_abstract.rst
 
 .. contents:: Table of Contents
 
+``filter_iterator`` synopsis
+............................
+
 .. include:: filter_iterator_ref.rst
+.. include:: make_filter_iterator.rst
+
+.. include:: filter_iterator_eg.rst

doc/filter_iterator_abstract.rst

@@ -1,10 +1,15 @@
+.. Copyright David Abrahams 2006. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
 The filter iterator adaptor creates a view of an iterator range in
-which some elements of the range are skipped over. A predicate
-function object controls which elements are skipped. When the
-predicate is applied to an element, if it returns ``true`` then the
-element is retained and if it returns ``false`` then the element is
-skipped over. When skipping over elements, it is necessary for the
-filter adaptor to know when to stop so as to avoid going past the end
-of the underlying range. Therefore the constructor of the filter
-iterator takes two iterator parameters: the position for the filtered
-iterator and the end of the range.
+which some elements of the range are skipped. A predicate function
+object controls which elements are skipped. When the predicate is
+applied to an element, if it returns ``true`` then the element is
+retained and if it returns ``false`` then the element is skipped
+over. When skipping over elements, it is necessary for the filter
+adaptor to know when to stop so as to avoid going past the end of the
+underlying range. A filter iterator is therefore constructed with pair
+of iterators indicating the range of elements in the unfiltered
+sequence to be traversed.
+

doc/filter_iterator_eg.rst

@@ -0,0 +1,72 @@
+.. Copyright David Abrahams 2006. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+Example
+.......
+
+This example uses ``filter_iterator`` and then
+``make_filter_iterator`` to output only the positive integers from an
+array of integers. Then ``make_filter_iterator`` is is used to output
+the integers greater than ``-2``.
+
+::
+
+    struct is_positive_number {
+      bool operator()(int x) { return 0 < x; }
+    };
+
+    int main()
+    {
+      int numbers_[] = { 0, -1, 4, -3, 5, 8, -2 };
+      const int N = sizeof(numbers_)/sizeof(int);
+
+      typedef int* base_iterator;
+      base_iterator numbers(numbers_);
+
+      // Example using filter_iterator
+      typedef boost::filter_iterator<is_positive_number, base_iterator>
+	FilterIter;
+
+      is_positive_number predicate;
+      FilterIter filter_iter_first(predicate, numbers, numbers + N);
+      FilterIter filter_iter_last(predicate, numbers + N, numbers + N);
+
+      std::copy(filter_iter_first, filter_iter_last, std::ostream_iterator<int>(std::cout, " "));
+      std::cout << std::endl;
+
+      // Example using make_filter_iterator()
+      std::copy(boost::make_filter_iterator<is_positive_number>(numbers, numbers + N),
+		boost::make_filter_iterator<is_positive_number>(numbers + N, numbers + N),
+		std::ostream_iterator<int>(std::cout, " "));
+      std::cout << std::endl;
+
+      // Another example using make_filter_iterator()
+      std::copy(
+	  boost::make_filter_iterator(
+	      std::bind2nd(std::greater<int>(), -2)
+	    , numbers, numbers + N)
+
+	, boost::make_filter_iterator(
+	      std::bind2nd(std::greater<int>(), -2)
+	    , numbers + N, numbers + N)
+
+	, std::ostream_iterator<int>(std::cout, " ")
+      );
+
+      std::cout << std::endl;
+
+      return boost::exit_success;
+    }
+
+
+The output is::
+
+    4 5 8 
+    4 5 8 
+    0 -1 4 5 8 
+
+
+The source code for this example can be found `here`__.
+
+__ ../example/filter_iterator_example.cpp

doc/filter_iterator_ref.rst

@@ -1,14 +1,20 @@
+.. Copyright David Abrahams, Jeremy Siek, and Thomas Witt
+.. 2004. Use, modification and distribution is subject to the Boost
+.. Software License, Version 1.0. (See accompanying  file
+.. LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 
+
 ::
 
   template <class Predicate, class Iterator>
   class filter_iterator
-      : public iterator_adaptor<
-            filter_iterator<Predicate, Iterator>, Iterator
-          , use_default
-          , /* see details */
-        >
   {
    public:
+      typedef iterator_traits<Iterator>::value_type value_type;
+      typedef iterator_traits<Iterator>::reference reference;
+      typedef iterator_traits<Iterator>::pointer pointer;
+      typedef iterator_traits<Iterator>::difference_type difference_type;
+      typedef /* see below */ iterator_category;
+
       filter_iterator();
       filter_iterator(Predicate f, Iterator x, Iterator end = Iterator());
       filter_iterator(Iterator x, Iterator end = Iterator());
@@ -19,71 +25,115 @@
           );
       Predicate predicate() const;
       Iterator end() const;
-
-   private: // as-if specification
-      void increment()
-      {
-          ++(this->base_reference());
-          satisfy_predicate();
-      }
-
-      void satisfy_predicate()
-      {
-          while (this->base() != this->m_end && !this->m_predicate(*this->base()))
-              ++(this->base_reference());
-      }
-
-      Predicate m_predicate;
-      Iterator m_end;
+      Iterator const& base() const;
+      reference operator*() const;
+      filter_iterator& operator++();
+  private:
+      Predicate m_pred; // exposition only
+      Iterator m_iter;  // exposition only
+      Iterator m_end;   // exposition only
   };
 
 
+If ``Iterator`` models Readable Lvalue Iterator and Bidirectional Traversal
+Iterator then ``iterator_category`` is convertible to
+``std::bidirectional_iterator_tag``. 
+Otherwise, if ``Iterator`` models Readable Lvalue Iterator and Forward Traversal
+Iterator then ``iterator_category`` is convertible to
+``std::forward_iterator_tag``. 
+Otherwise ``iterator_category`` is
+convertible to ``std::input_iterator_tag``.
+
+
 ``filter_iterator`` requirements
---------------------------------
+................................
 
-The base ``Iterator`` parameter must be a model of Readable
-Iterator and Single Pass Iterator. The resulting
-``filter_iterator`` will be a model of Forward Traversal Iterator
-if ``Iterator`` is, otherwise the ``filter_iterator`` will be a
-model of Single Pass Iterator. The access category of the
-``filter_iterator`` will be the same as the access category of
-``Iterator``.
+The ``Iterator`` argument shall meet the requirements of Readable
+Iterator and Single Pass Iterator or it shall meet the requirements of
+Input Iterator.
 
-.. Thomas is going to try implementing filter_iterator so that
-   it will be bidirectional if the underlying iterator is. -JGS
-
-
-The ``Predicate`` must be Assignable, Copy Constructible, and the
-expression ``p(x)`` must be valid where ``p`` is an object of type
+The ``Predicate`` argument must be Assignable, Copy Constructible, and
+the expression ``p(x)`` must be valid where ``p`` is an object of type
 ``Predicate``, ``x`` is an object of type
 ``iterator_traits<Iterator>::value_type``, and where the type of
 ``p(x)`` must be convertible to ``bool``.
 
 
+``filter_iterator`` models
+..........................
+
+The concepts that ``filter_iterator`` models are dependent on which
+concepts the ``Iterator`` argument models, as specified in the
+following tables.
+
++---------------------------------+------------------------------------------+
+|If ``Iterator`` models           |then ``filter_iterator`` models           |
++=================================+==========================================+
+|Single Pass Iterator             |Single Pass Iterator                      |
++---------------------------------+------------------------------------------+
+|Forward Traversal Iterator       |Forward Traversal Iterator                |
++---------------------------------+------------------------------------------+
+|Bidirectional Traversal Iterator |Bidirectional Traversal Iterator          |
++---------------------------------+------------------------------------------+
+
++--------------------------------+----------------------------------------------+
+| If ``Iterator`` models         | then ``filter_iterator`` models              |
++================================+==============================================+
+| Readable Iterator              | Readable Iterator                            |
++--------------------------------+----------------------------------------------+
+| Writable Iterator              | Writable Iterator                            |
++--------------------------------+----------------------------------------------+
+| Lvalue Iterator                | Lvalue Iterator                              |
++--------------------------------+----------------------------------------------+
+
++-------------------------------------------------------+---------------------------------+
+|If ``Iterator`` models                                 | then ``filter_iterator`` models |
++=======================================================+=================================+
+|Readable Iterator, Single Pass Iterator                | Input Iterator                  |
++-------------------------------------------------------+---------------------------------+
+|Readable Lvalue Iterator, Forward Traversal Iterator   | Forward Iterator                |
++-------------------------------------------------------+---------------------------------+
+|Writable Lvalue Iterator, Forward Traversal Iterator   | Mutable Forward Iterator        |
++-------------------------------------------------------+---------------------------------+
+|Writable Lvalue Iterator, Bidirectional Iterator       | Mutable Bidirectional Iterator  |
++-------------------------------------------------------+---------------------------------+
+
+
+``filter_iterator<P1, X>`` is interoperable with ``filter_iterator<P2, Y>`` 
+if and only if ``X`` is interoperable with ``Y``.
+
 
 ``filter_iterator`` operations
-------------------------------
+..............................
+
+In addition to those operations required by the concepts that
+``filter_iterator`` models, ``filter_iterator`` provides the following
+operations.
+
 
 ``filter_iterator();``
 
 :Requires: ``Predicate`` and ``Iterator`` must be Default Constructible.
-:Returns: a ``filter_iterator`` whose
-    predicate is a default constructed ``Predicate`` and
-    whose ``end`` is a default constructed ``Iterator``.
+:Effects: Constructs a ``filter_iterator`` whose``m_pred``,  ``m_iter``, and ``m_end`` 
+  members are a default constructed.
 
 
 ``filter_iterator(Predicate f, Iterator x, Iterator end = Iterator());``
 
-:Returns: A ``filter_iterator`` at position ``x`` that filters according
-    to predicate ``f`` and that will not increment past ``end``.
+:Effects: Constructs a ``filter_iterator`` where ``m_iter`` is either
+    the first position in the range ``[x,end)`` such that ``f(*m_iter) == true`` 
+    or else``m_iter == end``. The member ``m_pred`` is constructed from
+    ``f`` and ``m_end`` from ``end``.
+
 
 
 ``filter_iterator(Iterator x, Iterator end = Iterator());``
 
-:Requires: ``Predicate`` must be Default Constructible.
-:Returns: A ``filter_iterator`` at position ``x`` that filters 
-    according to a default constructed ``Predicate``
-    and that will not increment past ``end``.
+:Requires: ``Predicate`` must be Default Constructible and
+  ``Predicate`` is a class type (not a function pointer).
+:Effects: Constructs a ``filter_iterator`` where ``m_iter`` is either
+    the first position in the range ``[x,end)`` such that ``m_pred(*m_iter) == true`` 
+    or else``m_iter == end``. The member ``m_pred`` is default constructed.
 
 
 ::
@@ -95,15 +145,33 @@ expression ``p(x)`` must be valid where ``p`` is an object of type
         );``
 
 :Requires: ``OtherIterator`` is implicitly convertible to ``Iterator``.
-:Returns: A copy of iterator ``t``. 
+:Effects: Constructs a filter iterator whose members are copied from ``t``.
 
 
 ``Predicate predicate() const;``
 
-:Returns: A copy of the predicate object used to construct ``*this``.
+:Returns: ``m_pred``
 
 
 ``Iterator end() const;``
 
-:Returns: The object ``end`` used to construct ``*this``.
+:Returns: ``m_end``
 
+
+``Iterator const& base() const;``
+
+:Returns: ``m_iterator``
+
+
+
+``reference operator*() const;``
+
+:Returns: ``*m_iter``
+
+
+``filter_iterator& operator++();``
+
+:Effects: Increments ``m_iter`` and then continues to
+  increment ``m_iter`` until either ``m_iter == m_end``
+  or ``m_pred(*m_iter) == true``.
+:Returns: ``*this``  

doc/func_output_iter_abstract.rst

@@ -1,3 +1,7 @@
+.. Copyright David Abrahams 2006. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
 The function output iterator adaptor makes it easier to create custom
 output iterators. The adaptor takes a unary function and creates a
 model of Output Iterator. Each item assigned to the output iterator is

doc/func_output_iter_ref.rst

@@ -0,0 +1,73 @@
+.. Copyright David Abrahams 2006. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+Header
+......
+
+::
+  
+  #include <boost/function_output_iterator.hpp>
+
+::
+
+  template <class UnaryFunction>
+  class function_output_iterator {
+  public:
+    typedef std::output_iterator_tag iterator_category;
+    typedef void                     value_type;
+    typedef void                     difference_type;
+    typedef void                     pointer;
+    typedef void                     reference;
+
+    explicit function_output_iterator();
+
+    explicit function_output_iterator(const UnaryFunction& f);
+
+    /* see below */ operator*();
+    function_output_iterator& operator++();
+    function_output_iterator& operator++(int);
+  private:
+    UnaryFunction m_f;     // exposition only
+  };
+
+
+
+``function_output_iterator`` requirements
+.........................................
+
+``UnaryFunction`` must be Assignable and Copy Constructible.  
+
+
+
+``function_output_iterator`` models
+...................................
+
+``function_output_iterator`` is a model of the Writable and
+Incrementable Iterator concepts.
+
+
+
+``function_output_iterator`` operations
+.......................................
+
+``explicit function_output_iterator(const UnaryFunction& f = UnaryFunction());``
+
+:Effects: Constructs an instance of ``function_output_iterator`` 
+  with ``m_f`` constructed from ``f``.
+
+
+``operator*();``
+
+:Returns: An object ``r`` of unspecified type such that ``r = t``
+  is equivalent to ``m_f(t)`` for all ``t``.
+  
+
+``function_output_iterator& operator++();``
+
+:Returns: ``*this``
+
+
+``function_output_iterator& operator++(int);``
+
+:Returns: ``*this``

doc/function_input_iterator.html

@@ -0,0 +1,142 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<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.6: http://docutils.sourceforge.net/" />
+<title></title>
+<meta name="author" content="Dean Michael Berris" />
+<link rel="stylesheet" href="../../../rst.css" type="text/css" />
+</head>
+<body>
+<div class="document">
+
+<table class="docinfo" frame="void" rules="none">
+<col class="docinfo-name" />
+<col class="docinfo-content" />
+<tbody valign="top">
+<tr><th class="docinfo-name">Author:</th>
+<td><a class="first reference external" href="mailto:mikhailberis&#64;gmail.com">Dean Michael Berris</a></td></tr>
+<tr class="field"><th class="docinfo-name">License:</th><td class="field-body">Distributed under the Boost Software License, Version 1.0
+(See accompanying file LICENSE_1_0.txt or copy at <a class="reference external" href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</td>
+</tr>
+</tbody>
+</table>
+<div class="section" id="function-input-iterator">
+<h1>Function Input Iterator</h1>
+<p>The Function Input Iterator allows for creating iterators that encapsulate
+a nullary function object and a state object which tracks the number of times
+the iterator has been incremented. A Function Input Iterator models the
+<a class="reference external" href="http://www.sgi.com/tech/stl/InputIterator.html">InputIterator</a> concept and is useful for creating bounded input iterators.</p>
+<p>Like the Generator Iterator, the Function Input Iterator takes a function
+that models the <a class="reference external" href="http://www.sgi.com/tech/stl/Generator.html">Generator</a> concept (which is basically a nullary or 0-arity
+function object). Each increment of the function Function Input Iterator
+invokes the generator function and stores the value in the iterator. When
+the iterator is dereferenced the stored value is returned.</p>
+<p>The Function Input Iterator encapsulates a state object which models the
+<a class="reference internal" href="#incrementable-concept">Incrementable Concept</a> and the <a class="reference external" href="http://www.sgi.com/tech/stl/EqualityComparable.html">EqualityComparable</a> Concept. These concepts are
+described below as:</p>
+<div class="section" id="incrementable-concept">
+<h2>Incrementable Concept</h2>
+<p>A type models the Incrementable Concept when it supports the pre- and post-
+increment operators. For a given object <tt class="docutils literal"><span class="pre">i</span></tt> with type <tt class="docutils literal"><span class="pre">I</span></tt>, the following
+constructs should be valid:</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="24%" />
+<col width="46%" />
+<col width="30%" />
+</colgroup>
+<tbody valign="top">
+<tr><td colspan="3">Construct  Description        Return Type</td>
+</tr>
+<tr><td>i++</td>
+<td>Post-increment i.</td>
+<td>I</td>
+</tr>
+<tr><td>++i</td>
+<td>Pre-increment i.</td>
+<td>I&amp;</td>
+</tr>
+</tbody>
+</table>
+<p>NOTE: An Incrementable type should also be <a class="reference external" href="http://www.sgi.com/tech/stl/DefaultConstructible.html">DefaultConstructible</a>.</p>
+</div>
+<div class="section" id="synopsis">
+<h2>Synopsis</h2>
+<pre class="literal-block">
+namespace {
+    template &lt;class Function, class State&gt;
+    class function_input_iterator;
+
+    template &lt;class Function, class State&gt;
+    typename function_input_iterator&lt;Function, State&gt;
+    make_function_input_iterator(Function &amp; f);
+
+    struct infinite;
+}
+</pre>
+</div>
+<div class="section" id="function-input-iterator-class">
+<h2>Function Input Iterator Class</h2>
+<p>The class Function Input Iterator class takes two template parameters
+<tt class="docutils literal"><span class="pre">Function</span></tt> and <tt class="docutils literal"><span class="pre">State</span></tt>. These two template parameters tell the
+Function Input Iterator the type of the function to encapsulate and
+the type of the internal state value to hold.</p>
+<p>The <tt class="docutils literal"><span class="pre">State</span></tt> parameter is important in cases where you want to
+control the type of the counter which determines whether two iterators
+are at the same state. This allows for creating a pair of iterators which
+bound the range of the invocations of the encapsulated functions.</p>
+</div>
+<div class="section" id="examples">
+<h2>Examples</h2>
+<p>The following example shows how we use the function input iterator class
+in cases where we want to create bounded (lazy) generated ranges.</p>
+<pre class="literal-block">
+struct generator {
+    typedef int result_type;
+    generator() { srand(time(0)); }
+    result_type operator() () const {
+        return rand();
+    }
+};
+
+int main(int argc, char * argv[]) {
+    generator f;
+    copy(
+            make_function_input_iterator(f, 0),
+            make_function_input_iterator(f, 10),
+            ostream_iterator&lt;int&gt;(cout, &quot; &quot;)
+        );
+    return 0;
+}
+</pre>
+<p>Here we can see that we've bounded the number of invocations using an <tt class="docutils literal"><span class="pre">int</span></tt>
+that counts from <tt class="docutils literal"><span class="pre">0</span></tt> to <tt class="docutils literal"><span class="pre">10</span></tt>. Say we want to create an endless stream
+of random numbers and encapsulate that in a pair of integers, we can do
+it with the <tt class="docutils literal"><span class="pre">boost::infinite</span></tt> helper class.</p>
+<pre class="literal-block">
+copy(
+        make_function_input_iterator(f,infinite()),
+        make_function_input_iterator(f,infinite()),
+        ostream_iterator&lt;int&gt;(count, &quot; &quot;)
+    );
+</pre>
+<p>Above, instead of creating a huge vector we rely on the STL copy algorithm
+to traverse the function input iterator and call the function object f
+as it increments the iterator. The special property of <tt class="docutils literal"><span class="pre">boost::infinite</span></tt>
+is that equating two instances always yield false -- and that incrementing
+an instance of <tt class="docutils literal"><span class="pre">boost::infinite</span></tt> doesn't do anything. This is an efficient
+way of stating that the iterator range provided by two iterators with an
+encapsulated infinite state will definitely be infinite.</p>
+</div>
+</div>
+</div>
+<div class="footer">
+<hr class="footer" />
+<a class="reference external" href="function_input_iterator.rst">View document source</a>.
+Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
+
+</div>
+</body>
+</html>

doc/function_input_iterator.rst

@@ -0,0 +1,132 @@
+:Author:
+    `Dean Michael Berris <mailto:me@deanberris.com>`_
+
+:License:
+    Distributed under the Boost Software License, Version 1.0
+    (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+:Copyright:
+    Copyright 2012 Google, Inc.
+
+Function Input Iterator
+=======================
+
+The Function Input Iterator allows for creating iterators that encapsulate
+a nullary function object and a state object which tracks the number of times
+the iterator has been incremented. A Function Input Iterator models the
+`InputIterator`_ concept and is useful for creating bounded input iterators.
+
+.. _InputIterator: http://www.sgi.com/tech/stl/InputIterator.html
+
+The Function Input Iterator takes a function that models the Generator_ concept
+(which is basically a nullary or 0-arity function object). The first dereference
+of the iterator at a given position invokes the generator function and stores
+and returns the result; subsequent dereferences at the same position simply
+return the same stored result. Incrementing the iterator places it at a new
+position, hence a subsequent dereference will generate a new value via another
+invokation of the generator function. This ensures the generator function is
+invoked precisely when the iterator is requested to return a (new) value.
+
+.. _Generator: http://www.sgi.com/tech/stl/Generator.html
+
+The Function Input Iterator encapsulates a state object which models the
+`Incrementable Concept`_ and the EqualityComparable_ Concept. These concepts are
+described below as:
+
+.. _EqualityComparable: http://www.sgi.com/tech/stl/EqualityComparable.html
+
+Incrementable Concept
+---------------------
+
+A type models the Incrementable Concept when it supports the pre- and post-
+increment operators. For a given object ``i`` with type ``I``, the following 
+constructs should be valid:
+
+=========  =================  ===========
+Construct  Description        Return Type
+-----------------------------------------
+i++        Post-increment i.  I
+++i        Pre-increment i.   I&
+=========  =================  ===========
+
+NOTE: An Incrementable type should also be DefaultConstructible_.
+
+.. _DefaultConstructible: http://www.sgi.com/tech/stl/DefaultConstructible.html
+
+Synopsis
+--------
+
+::
+
+    namespace {
+        template <class Function, class State>
+        class function_input_iterator;
+
+        template <class Function, class State>
+        typename function_input_iterator<Function, State>
+        make_function_input_iterator(Function & f, State s);
+
+        struct infinite;
+    }
+
+Function Input Iterator Class
+-----------------------------
+
+The class Function Input Iterator class takes two template parameters
+``Function`` and ``State``. These two template parameters tell the
+Function Input Iterator the type of the function to encapsulate and
+the type of the internal state value to hold.
+
+The ``State`` parameter is important in cases where you want to
+control the type of the counter which determines whether two iterators 
+are at the same state. This allows for creating a pair of iterators which 
+bound the range of the invocations of the encapsulated functions.
+
+Examples
+--------
+
+The following example shows how we use the function input iterator class
+in cases where we want to create bounded (lazy) generated ranges.
+
+::
+
+    struct generator {
+        typedef int result_type;
+        generator() { srand(time(0)); }
+        result_type operator() () const {
+            return rand();
+        }
+    };
+
+    int main(int argc, char * argv[]) {
+        generator f;
+        copy(
+                make_function_input_iterator(f, 0),
+                make_function_input_iterator(f, 10),
+                ostream_iterator<int>(cout, " ")
+            );
+        return 0;
+    }
+
+Here we can see that we've bounded the number of invocations using an ``int``
+that counts from ``0`` to ``10``. Say we want to create an endless stream
+of random numbers and encapsulate that in a pair of integers, we can do
+it with the ``boost::infinite`` helper class.
+
+::
+
+    copy(
+            make_function_input_iterator(f,infinite()),
+            make_function_input_iterator(f,infinite()),
+            ostream_iterator<int>(cout, " ")
+        );
+   
+Above, instead of creating a huge vector we rely on the STL copy algorithm
+to traverse the function input iterator and call the function object f
+as it increments the iterator. The special property of ``boost::infinite``
+is that equating two instances always yield false -- and that incrementing
+an instance of ``boost::infinite`` doesn't do anything. This is an efficient
+way of stating that the iterator range provided by two iterators with an
+encapsulated infinite state will definitely be infinite.
+
+

doc/function_output_iterator.html

@@ -3,204 +3,13 @@
 <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.1: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
 <title>Function Output Iterator</title>
 <meta name="author" content="David Abrahams, Jeremy Siek, Thomas Witt" />
 <meta name="organization" content="Boost Consulting, Indiana University Open Systems Lab, University of Hanover Institute for Transport Railway Operation and Construction" />
-<meta name="date" content="2003-09-14" />
-<meta name="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved" />
-<style type="text/css"><!--
-
-/*
-:Author: David Goodger
-:Contact: goodger@users.sourceforge.net
-:date: $Date$
-:version: $Revision$
-:copyright: This stylesheet has been placed in the public domain.
-
-Default cascading style sheet for the HTML output of Docutils.
-*/
-
-.first {
-  margin-top: 0 }
-
-.last {
-  margin-bottom: 0 }
-
-a.toc-backref {
-  text-decoration: none ;
-  color: black }
-
-dd {
-  margin-bottom: 0.5em }
-
-div.abstract {
-  margin: 2em 5em }
-
-div.abstract p.topic-title {
-  font-weight: bold ;
-  text-align: center }
-
-div.attention, div.caution, div.danger, div.error, div.hint,
-div.important, div.note, div.tip, div.warning {
-  margin: 2em ;
-  border: medium outset ;
-  padding: 1em }
-
-div.attention p.admonition-title, div.caution p.admonition-title,
-div.danger p.admonition-title, div.error p.admonition-title,
-div.warning p.admonition-title {
-  color: red ;
-  font-weight: bold ;
-  font-family: sans-serif }
-
-div.hint p.admonition-title, div.important p.admonition-title,
-div.note p.admonition-title, div.tip p.admonition-title {
-  font-weight: bold ;
-  font-family: sans-serif }
-
-div.dedication {
-  margin: 2em 5em ;
-  text-align: center ;
-  font-style: italic }
-
-div.dedication p.topic-title {
-  font-weight: bold ;
-  font-style: normal }
-
-div.figure {
-  margin-left: 2em }
-
-div.footer, div.header {
-  font-size: smaller }
-
-div.system-messages {
-  margin: 5em }
-
-div.system-messages h1 {
-  color: red }
-
-div.system-message {
-  border: medium outset ;
-  padding: 1em }
-
-div.system-message p.system-message-title {
-  color: red ;
-  font-weight: bold }
-
-div.topic {
-  margin: 2em }
-
-h1.title {
-  text-align: center }
-
-h2.subtitle {
-  text-align: center }
-
-hr {
-  width: 75% }
-
-ol.simple, ul.simple {
-  margin-bottom: 1em }
-
-ol.arabic {
-  list-style: decimal }
-
-ol.loweralpha {
-  list-style: lower-alpha }
-
-ol.upperalpha {
-  list-style: upper-alpha }
-
-ol.lowerroman {
-  list-style: lower-roman }
-
-ol.upperroman {
-  list-style: upper-roman }
-
-p.caption {
-  font-style: italic }
-
-p.credits {
-  font-style: italic ;
-  font-size: smaller }
-
-p.label {
-  white-space: nowrap }
-
-p.topic-title {
-  font-weight: bold }
-
-pre.address {
-  margin-bottom: 0 ;
-  margin-top: 0 ;
-  font-family: serif ;
-  font-size: 100% }
-
-pre.line-block {
-  font-family: serif ;
-  font-size: 100% }
-
-pre.literal-block, pre.doctest-block {
-  margin-left: 2em ;
-  margin-right: 2em ;
-  background-color: #eeeeee }
-
-span.classifier {
-  font-family: sans-serif ;
-  font-style: oblique }
-
-span.classifier-delimiter {
-  font-family: sans-serif ;
-  font-weight: bold }
-
-span.interpreted {
-  font-family: sans-serif }
-
-span.option-argument {
-  font-style: italic }
-
-span.pre {
-  white-space: pre }
-
-span.problematic {
-  color: red }
-
-table {
-  margin-top: 0.5em ;
-  margin-bottom: 0.5em }
-
-table.citation {
-  border-left: solid thin gray ;
-  padding-left: 0.5ex }
-
-table.docinfo {
-  margin: 2em 4em }
-
-table.footnote {
-  border-left: solid thin black ;
-  padding-left: 0.5ex }
-
-td, th {
-  padding-left: 0.5em ;
-  padding-right: 0.5em ;
-  vertical-align: top }
-
-th.docinfo-name, th.field-name {
-  font-weight: bold ;
-  text-align: left ;
-  white-space: nowrap }
-
-h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
-  font-size: 100% }
-
-tt {
-  background-color: #eeeeee }
-
-ul.auto-toc {
-  list-style-type: none }
-
---></style>
+<meta name="date" content="2006-09-11" />
+<meta name="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003." />
+<link rel="stylesheet" href="../../../rst.css" type="text/css" />
 </head>
 <body>
 <div class="document" id="function-output-iterator">
@@ -212,145 +21,171 @@ ul.auto-toc {
 <tr><th class="docinfo-name">Author:</th>
 <td>David Abrahams, Jeremy Siek, Thomas Witt</td></tr>
 <tr><th class="docinfo-name">Contact:</th>
-<td><a class="first reference" href="mailto:dave&#64;boost-consulting.com">dave&#64;boost-consulting.com</a>, <a class="reference" href="mailto:jsiek&#64;osl.iu.edu">jsiek&#64;osl.iu.edu</a>, <a class="last reference" href="mailto:witt&#64;ive.uni-hannover.de">witt&#64;ive.uni-hannover.de</a></td></tr>
+<td><a class="first reference external" href="mailto:dave&#64;boost-consulting.com">dave&#64;boost-consulting.com</a>, <a class="reference external" href="mailto:jsiek&#64;osl.iu.edu">jsiek&#64;osl.iu.edu</a>, <a class="last reference external" href="mailto:witt&#64;ive.uni-hannover.de">witt&#64;ive.uni-hannover.de</a></td></tr>
 <tr><th class="docinfo-name">Organization:</th>
-<td><a class="first reference" href="http://www.boost-consulting.com">Boost Consulting</a>, Indiana University <a class="reference" href="http://www.osl.iu.edu">Open Systems
-Lab</a>, University of Hanover <a class="last reference" href="http://www.ive.uni-hannover.de">Institute for Transport
+<td><a class="first reference external" href="http://www.boost-consulting.com">Boost Consulting</a>, Indiana University <a class="reference external" href="http://www.osl.iu.edu">Open Systems
+Lab</a>, University of Hanover <a class="last reference external" href="http://www.ive.uni-hannover.de">Institute for Transport
 Railway Operation and Construction</a></td></tr>
 <tr><th class="docinfo-name">Date:</th>
-<td>2003-09-14</td></tr>
+<td>2006-09-11</td></tr>
 <tr><th class="docinfo-name">Copyright:</th>
-<td>Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved</td></tr>
+<td>Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003.</td></tr>
 </tbody>
 </table>
-<table class="field-list" frame="void" rules="none">
+<!-- Distributed under the Boost -->
+<!-- Software License, Version 1.0. (See accompanying -->
+<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
+<table class="docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
-<tr class="field"><th class="field-name">abstract:</th><td class="field-body"></td>
-</tr>
-</tbody>
-</table>
-<p>The function output iterator adaptor makes it easier to create custom
+<tr class="field"><th class="field-name">abstract:</th><td class="field-body"><!-- Copyright David Abrahams 2006. Distributed under the Boost -->
+<!-- Software License, Version 1.0. (See accompanying -->
+<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
+The function output iterator adaptor makes it easier to create custom
 output iterators. The adaptor takes a unary function and creates a
 model of Output Iterator. Each item assigned to the output iterator is
 passed as an argument to the unary function.  The motivation for this
 iterator is that creating a conforming output iterator is non-trivial,
 particularly because the proper implementation usually requires a
-proxy object.</p>
+proxy object.</td>
+</tr>
+</tbody>
+</table>
 <div class="contents topic" id="table-of-contents">
-<p class="topic-title"><a name="table-of-contents">Table of Contents</a></p>
+<p class="topic-title first">Table of Contents</p>
 <ul class="simple">
-<li><a class="reference" href="#function-output-iterator-requirements" id="id1" name="id1"><tt class="literal"><span class="pre">function_output_iterator</span></tt> requirements</a></li>
-<li><a class="reference" href="#function-output-iterator-operations" id="id2" name="id2"><tt class="literal"><span class="pre">function_output_iterator</span></tt> operations</a></li>
-<li><a class="reference" href="#function-output-iterator-output-proxy-operations" id="id3" name="id3"><tt class="literal"><span class="pre">function_output_iterator::output_proxy</span></tt> operations</a></li>
+<li><a class="reference internal" href="#header" id="id1">Header</a></li>
+<li><a class="reference internal" href="#function-output-iterator-requirements" id="id2"><tt class="docutils literal"><span class="pre">function_output_iterator</span></tt> requirements</a></li>
+<li><a class="reference internal" href="#function-output-iterator-models" id="id3"><tt class="docutils literal"><span class="pre">function_output_iterator</span></tt> models</a></li>
+<li><a class="reference internal" href="#function-output-iterator-operations" id="id4"><tt class="docutils literal"><span class="pre">function_output_iterator</span></tt> operations</a></li>
+<li><a class="reference internal" href="#example" id="id5">Example</a></li>
 </ul>
 </div>
+<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
+<!-- Software License, Version 1.0. (See accompanying -->
+<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
+<div class="section" id="header">
+<h1><a class="toc-backref" href="#id1">Header</a></h1>
+<pre class="literal-block">
+#include &lt;boost/function_output_iterator.hpp&gt;
+</pre>
 <pre class="literal-block">
 template &lt;class UnaryFunction&gt;
 class function_output_iterator {
 public:
-  typedef iterator_tag&lt;
-        writable_iterator
-      , incrementable_traversal_tag
-  &gt; iterator_category;
-  typedef void                value_type;
-  typedef void                difference_type;
-  typedef void                pointer;
-  typedef void                reference;
+  typedef std::output_iterator_tag iterator_category;
+  typedef void                     value_type;
+  typedef void                     difference_type;
+  typedef void                     pointer;
+  typedef void                     reference;
 
-  explicit function_output_iterator(const UnaryFunction&amp; f = UnaryFunction());
+  explicit function_output_iterator();
 
-  struct output_proxy {
-    output_proxy(UnaryFunction&amp; f);
-    template &lt;class T&gt; output_proxy&amp; operator=(const T&amp; value);
-  };
-  output_proxy operator*();
+  explicit function_output_iterator(const UnaryFunction&amp; f);
+
+  /* see below */ operator*();
   function_output_iterator&amp; operator++();
   function_output_iterator&amp; operator++(int);
+private:
+  UnaryFunction m_f;     // exposition only
 };
 </pre>
+</div>
 <div class="section" id="function-output-iterator-requirements">
-<h1><a class="toc-backref" href="#id1" name="function-output-iterator-requirements"><tt class="literal"><span class="pre">function_output_iterator</span></tt> requirements</a></h1>
-<p>The <tt class="literal"><span class="pre">UnaryFunction</span></tt> must be Assignable, Copy Constructible, and the
-expression <tt class="literal"><span class="pre">f(x)</span></tt> must be valid, where <tt class="literal"><span class="pre">f</span></tt> is an object of type
-<tt class="literal"><span class="pre">UnaryFunction</span></tt> and <tt class="literal"><span class="pre">x</span></tt> is an object of a type accepted by <tt class="literal"><span class="pre">f</span></tt>.
-The resulting <tt class="literal"><span class="pre">function_output_iterator</span></tt> is a model of the Writable
-and Incrementable Iterator concepts.</p>
+<h1><a class="toc-backref" href="#id2"><tt class="docutils literal"><span class="pre">function_output_iterator</span></tt> requirements</a></h1>
+<p><tt class="docutils literal"><span class="pre">UnaryFunction</span></tt> must be Assignable and Copy Constructible.</p>
+</div>
+<div class="section" id="function-output-iterator-models">
+<h1><a class="toc-backref" href="#id3"><tt class="docutils literal"><span class="pre">function_output_iterator</span></tt> models</a></h1>
+<p><tt class="docutils literal"><span class="pre">function_output_iterator</span></tt> is a model of the Writable and
+Incrementable Iterator concepts.</p>
 </div>
 <div class="section" id="function-output-iterator-operations">
-<h1><a class="toc-backref" href="#id2" name="function-output-iterator-operations"><tt class="literal"><span class="pre">function_output_iterator</span></tt> operations</a></h1>
-<p><tt class="literal"><span class="pre">explicit</span> <span class="pre">function_output_iterator(const</span> <span class="pre">UnaryFunction&amp;</span> <span class="pre">f</span> <span class="pre">=</span> <span class="pre">UnaryFunction());</span></tt></p>
-<table class="field-list" frame="void" rules="none">
+<h1><a class="toc-backref" href="#id4"><tt class="docutils literal"><span class="pre">function_output_iterator</span></tt> operations</a></h1>
+<p><tt class="docutils literal"><span class="pre">explicit</span> <span class="pre">function_output_iterator(const</span> <span class="pre">UnaryFunction&amp;</span> <span class="pre">f</span> <span class="pre">=</span> <span class="pre">UnaryFunction());</span></tt></p>
+<table class="docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
-<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="literal"><span class="pre">function_output_iterator</span></tt> with
-<tt class="literal"><span class="pre">f</span></tt> stored as a data member.</td>
+<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Constructs an instance of <tt class="docutils literal"><span class="pre">function_output_iterator</span></tt>
+with <tt class="docutils literal"><span class="pre">m_f</span></tt> constructed from <tt class="docutils literal"><span class="pre">f</span></tt>.</td>
 </tr>
 </tbody>
 </table>
-<p><tt class="literal"><span class="pre">output_proxy</span> <span class="pre">operator*();</span></tt></p>
-<table class="field-list" frame="void" rules="none">
+<p><tt class="docutils literal"><span class="pre">operator*();</span></tt></p>
+<table class="docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
-<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="literal"><span class="pre">output_proxy</span></tt> constructed with
-a copy of the unary function <tt class="literal"><span class="pre">f</span></tt>.</td>
+<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An object <tt class="docutils literal"><span class="pre">r</span></tt> of unspecified type such that <tt class="docutils literal"><span class="pre">r</span> <span class="pre">=</span> <span class="pre">t</span></tt>
+is equivalent to <tt class="docutils literal"><span class="pre">m_f(t)</span></tt> for all <tt class="docutils literal"><span class="pre">t</span></tt>.</td>
 </tr>
 </tbody>
 </table>
-<p><tt class="literal"><span class="pre">function_output_iterator&amp;</span> <span class="pre">operator++();</span></tt></p>
-<table class="field-list" frame="void" rules="none">
+<p><tt class="docutils literal"><span class="pre">function_output_iterator&amp;</span> <span class="pre">operator++();</span></tt></p>
+<table class="docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
-<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">*this</span></tt></td>
+<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">*this</span></tt></td>
 </tr>
 </tbody>
 </table>
-<p><tt class="literal"><span class="pre">function_output_iterator&amp;</span> <span class="pre">operator++(int);</span></tt></p>
-<table class="field-list" frame="void" rules="none">
+<p><tt class="docutils literal"><span class="pre">function_output_iterator&amp;</span> <span class="pre">operator++(int);</span></tt></p>
+<table class="docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
-<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">*this</span></tt></td>
+<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">*this</span></tt></td>
 </tr>
 </tbody>
 </table>
+<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
+<!-- Software License, Version 1.0. (See accompanying -->
+<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
 </div>
-<div class="section" id="function-output-iterator-output-proxy-operations">
-<h1><a class="toc-backref" href="#id3" name="function-output-iterator-output-proxy-operations"><tt class="literal"><span class="pre">function_output_iterator::output_proxy</span></tt> operations</a></h1>
-<p><tt class="literal"><span class="pre">output_proxy(UnaryFunction&amp;</span> <span class="pre">f);</span></tt></p>
-<table class="field-list" frame="void" rules="none">
-<col class="field-name" />
-<col class="field-body" />
-<tbody valign="top">
-<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="literal"><span class="pre">output_proxy</span></tt> with <tt class="literal"><span class="pre">f</span></tt> stored as
-a data member.</td>
-</tr>
-</tbody>
-</table>
-<p><tt class="literal"><span class="pre">template</span> <span class="pre">&lt;class</span> <span class="pre">T&gt;</span> <span class="pre">output_proxy&amp;</span> <span class="pre">operator=(const</span> <span class="pre">T&amp;</span> <span class="pre">value);</span></tt></p>
-<table class="field-list" frame="void" rules="none">
-<col class="field-name" />
-<col class="field-body" />
-<tbody valign="top">
-<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><pre class="first last literal-block">
-m_f(value); 
-return *this; 
+<div class="section" id="example">
+<h1><a class="toc-backref" href="#id5">Example</a></h1>
+<pre class="literal-block">
+struct string_appender
+{
+    string_appender(std::string&amp; s)
+        : m_str(&amp;s)
+    {}
+
+    void operator()(const std::string&amp; x) const
+    {
+        *m_str += x;
+    }
+
+    std::string* m_str;
+};
+
+int main(int, char*[])
+{
+  std::vector&lt;std::string&gt; x;
+  x.push_back(&quot;hello&quot;);
+  x.push_back(&quot; &quot;);
+  x.push_back(&quot;world&quot;);
+  x.push_back(&quot;!&quot;);
+
+  std::string s = &quot;&quot;;
+  std::copy(x.begin(), x.end(),
+            boost::make_function_output_iterator(string_appender(s)));
+
+  std::cout &lt;&lt; s &lt;&lt; std::endl;
+
+  return 0;
+}
 </pre>
-</td>
-</tr>
-</tbody>
-</table>
 </div>
 </div>
-<hr class="footer" />
 <div class="footer">
-<a class="reference" href="function_output_iterator.rst">View document source</a>.
-Generated on: 2003-11-24 05:00 UTC.
-Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
+<hr class="footer" />
+<a class="reference external" href="function_output_iterator.rst">View document source</a>.
+Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
+
 </div>
 </body>
 </html>

doc/function_output_iterator.rst

@@ -1,3 +1,7 @@
+.. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
 ++++++++++++++++++++++++++
  Function Output Iterator
 ++++++++++++++++++++++++++
@@ -8,7 +12,7 @@
                Lab`_, University of Hanover `Institute for Transport
                Railway Operation and Construction`_
 :date: $Date$
-:copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved
+:copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. 
 
 .. _`Boost Consulting`: http://www.boost-consulting.com
 .. _`Open Systems Lab`: http://www.osl.iu.edu
@@ -16,8 +20,9 @@
 
 :abstract:
 
-.. include:: function_output_iterator_abstract.rst
+  .. include:: func_output_iter_abstract.rst
 
 .. contents:: Table of Contents
 
-.. include:: function_output_iterator_ref.rst
+.. include:: func_output_iter_ref.rst
+.. include:: function_output_iterator_eg.rst

doc/function_output_iterator_eg.rst

@@ -0,0 +1,39 @@
+.. Copyright David Abrahams 2006. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+Example
+.......
+
+::
+
+    struct string_appender
+    {
+	string_appender(std::string& s)
+	    : m_str(&s)
+	{}
+
+	void operator()(const std::string& x) const
+	{
+	    *m_str += x;
+	}
+
+	std::string* m_str;
+    };
+
+    int main(int, char*[])
+    {
+      std::vector<std::string> x;
+      x.push_back("hello");
+      x.push_back(" ");
+      x.push_back("world");
+      x.push_back("!");
+
+      std::string s = "";
+      std::copy(x.begin(), x.end(), 
+		boost::make_function_output_iterator(string_appender(s)));
+
+      std::cout << s << std::endl;
+
+      return 0;
+    }

doc/function_output_iterator_ref.rst

@@ -1,77 +0,0 @@
-::
-
-  template <class UnaryFunction>
-  class function_output_iterator {
-  public:
-    typedef iterator_tag<
-          writable_iterator
-        , incrementable_traversal_tag
-    > iterator_category;
-    typedef void                value_type;
-    typedef void                difference_type;
-    typedef void                pointer;
-    typedef void                reference;
-
-    explicit function_output_iterator(const UnaryFunction& f = UnaryFunction());
-
-    struct output_proxy {
-      output_proxy(UnaryFunction& f);
-      template <class T> output_proxy& operator=(const T& value);
-    };
-    output_proxy operator*();
-    function_output_iterator& operator++();
-    function_output_iterator& operator++(int);
-  };
-
-
-``function_output_iterator`` requirements
------------------------------------------
-
-The ``UnaryFunction`` must be Assignable, Copy Constructible, and the
-expression ``f(x)`` must be valid, where ``f`` is an object of type
-``UnaryFunction`` and ``x`` is an object of a type accepted by ``f``.
-The resulting ``function_output_iterator`` is a model of the Writable
-and Incrementable Iterator concepts.
-
-
-``function_output_iterator`` operations
----------------------------------------
-
-``explicit function_output_iterator(const UnaryFunction& f = UnaryFunction());``
-
-:Returns: An instance of ``function_output_iterator`` with
-  ``f`` stored as a data member.
-
-
-``output_proxy operator*();``
-
-:Returns: An instance of ``output_proxy`` constructed with
-  a copy of the unary function ``f``.
-  
-
-``function_output_iterator& operator++();``
-
-:Returns: ``*this``
-
-
-``function_output_iterator& operator++(int);``
-
-:Returns: ``*this``
-
-
-``function_output_iterator::output_proxy`` operations
------------------------------------------------------
-
-``output_proxy(UnaryFunction& f);``
-
-:Returns: An instance of ``output_proxy`` with ``f`` stored as
-    a data member.
-
-
-``template <class T> output_proxy& operator=(const T& value);``
-
-:Effects: 
-  ::
-
-      m_f(value); 
-      return *this; 

doc/generate.py

@@ -1,4 +1,7 @@
 #!/usr/bin/python
+# Copyright David Abrahams 2004. Use, modification and distribution is
+# subject to the Boost Software License, Version 1.0. (See accompanying
+# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 
 #
 # Generate html, TeX, and PDF versions of all the source files
@@ -13,7 +16,7 @@ if 0:
     for s in sources:
         syscmd('boosthtml %s' % s)
 else:        
-    extensions = ('html', 'tex', 'pdf')
+    extensions = ('html', 'pdf')
 
     if len(sys.argv) > 1:
         extensions = sys.argv[1:]

doc/generator_iterator.htm

@@ -0,0 +1,163 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+
+<html>
+<head>
+  <meta http-equiv="Content-Language" content="en-us">
+  <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
+
+  <title>Generator Iterator Adaptor Documentation</title>
+</head>
+
+<body bgcolor="#FFFFFF" text="#000000">
+  <img src="../../boost.png" alt="boost.png (6897 bytes)" align="middle"
+  width="277" height="86">
+
+  <h1>Generator Iterator Adaptor</h1>
+
+  <p>Defined in header <a href=
+  "../../boost/generator_iterator.hpp">boost/generator_iterator.hpp</a></p>
+
+  <p>The generator iterator adaptor makes it easier to create custom input
+  iterators from 0-ary functions and function objects. The adaptor takes a
+  <a href="http://www.sgi.com/tech/stl/Generator.html">Generator</a> and
+  creates a model of <a href=
+  "http://www.sgi.com/tech/stl/InputIterator.html">Input Iterator</a>. Each
+  increment retrieves an item from the generator and makes it available to be
+  retrieved by dereferencing. The motivation for this iterator is that some
+  concepts can be more naturally expressed as a generator, while most STL
+  algorithms expect an iterator. An example is the <a href=
+  "../random/index.html">Random Number</a> library.</p>
+
+  <h2>Synopsis</h2>
+
+  <blockquote>
+    <pre>
+namespace boost {
+  template &lt;class Generator&gt;
+  class generator_iterator_policies;
+
+  template &lt;class Generator&gt;
+  class generator_iterator_generator;
+
+  template &lt;class Generator&gt;
+  typename generator_iterator_generator&lt;Generator&gt;::type
+  make_generator_iterator(Generator &amp; gen);
+}
+</pre>
+  </blockquote>
+  <hr>
+
+  <h2>The Generator Iterator Generator Class</h2>
+
+  <p>The class generator_iterator_generator is a helper class whose purpose
+  is to construct a generator iterator type. The template parameter for this
+  class is the Generator function object type that is being wrapped. The
+  generator iterator adaptor only holds a reference (or pointer) to the
+  function object, therefore the function object must outlive the generator
+  iterator adaptor constructed from it.</p>
+  <pre>
+template &lt;class Generator&gt;
+class generator_iterator_generator
+{
+public:
+  typedef <i>unspecified</i> type; // the resulting generator iterator type 
+}
+</pre>
+
+  <h3>Template Parameters</h3>
+
+  <table border summary="">
+    <tr>
+      <th>Parameter</th>
+
+      <th>Description</th>
+    </tr>
+
+    <tr>
+      <td><tt><a href=
+      "http://www.sgi.com/tech/stl/Generator.html">Generator</a></tt></td>
+
+      <td>The generator (0-ary function object) type being wrapped. The
+      return type of the function must be defined as
+      <tt>Generator::result_type</tt>. The function object must be a model of
+      <a href=
+      "http://www.sgi.com/tech/stl/Generator.html">Generator</a>.</td>
+    </tr>
+  </table>
+
+  <h3>Concept Model</h3>
+
+  <p>The generator iterator class is a model of <a href=
+  "http://www.sgi.com/tech/stl/InputIterator.html">Input Iterator</a>.</p>
+
+  <h3>Members</h3>
+
+  <p>The generator iterator implements the member functions and operators
+  required of the <a href=
+  "http://www.sgi.com/tech/stl/InputIterator.html">Input Iterator</a>
+  concept.<br></p>
+  <hr>
+
+  <h2><a name="make_generator_iterator" id="make_generator_iterator">The
+  Generator Iterator Object Generator</a></h2>
+
+  <p>The <tt>make_generator_iterator()</tt> function provides a convenient
+  way to create generator iterator objects. The function saves the user the
+  trouble of explicitly writing out the iterator types.</p>
+
+  <blockquote>
+    <pre>
+template &lt;class Generator&gt;
+typename generator_iterator_generator&lt;Generator&gt;::type
+make_generator_iterator(Generator &amp; gen);
+</pre>
+  </blockquote>
+  <hr>
+
+  <h3>Example</h3>
+
+  <p>The following program shows how <code>generator_iterator</code>
+  transforms a generator into an input iterator.</p>
+
+  <blockquote>
+    <pre>
+#include &lt;iostream&gt;
+#include &lt;boost/generator_iterator.hpp&gt;
+
+class my_generator
+{
+public:
+  typedef int result_type;
+  my_generator() : state(0) { }
+  int operator()() { return ++state; }
+private:
+  int state;
+};
+
+int main()
+{
+  my_generator gen;
+  boost::generator_iterator_generator&lt;my_generator&gt;::type it = boost::make_generator_iterator(gen);
+  for(int i = 0; i &lt; 10; ++i, ++it)
+    std::cout &lt;&lt; *it &lt;&lt; std::endl;
+}
+</pre>
+  </blockquote>
+  <hr>
+
+  <p><a href="http://validator.w3.org/check?uri=referer"><img border="0" src=
+  "../../doc/images/valid-html401.png" alt="Valid HTML 4.01 Transitional"
+  height="31" width="88"></a></p>
+
+  <p>Revised 
+  <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->05 December, 2006<!--webbot bot="Timestamp" endspan i-checksum="38516" --></p>
+
+  <p><i>Copyright &copy; 2001 <a href=
+  "http://www.boost.org/people/jens_maurer.htm">Jens Maurer</a></i></p>
+
+  <p><i>Distributed under the Boost Software License, Version 1.0. (See
+  accompanying file <a href="../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
+  copy at <a href=
+  "http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
+</body>
+</html>

doc/index.html

@@ -3,234 +3,46 @@
 <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.1: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
 <title>The Boost.Iterator Library Boost</title>
-<style type="text/css"><!--
-
-/*
-:Author: David Goodger
-:Contact: goodger@users.sourceforge.net
-:date: $Date$
-:version: $Revision$
-:copyright: This stylesheet has been placed in the public domain.
-
-Default cascading style sheet for the HTML output of Docutils.
-*/
-
-.first {
-  margin-top: 0 }
-
-.last {
-  margin-bottom: 0 }
-
-a.toc-backref {
-  text-decoration: none ;
-  color: black }
-
-dd {
-  margin-bottom: 0.5em }
-
-div.abstract {
-  margin: 2em 5em }
-
-div.abstract p.topic-title {
-  font-weight: bold ;
-  text-align: center }
-
-div.attention, div.caution, div.danger, div.error, div.hint,
-div.important, div.note, div.tip, div.warning {
-  margin: 2em ;
-  border: medium outset ;
-  padding: 1em }
-
-div.attention p.admonition-title, div.caution p.admonition-title,
-div.danger p.admonition-title, div.error p.admonition-title,
-div.warning p.admonition-title {
-  color: red ;
-  font-weight: bold ;
-  font-family: sans-serif }
-
-div.hint p.admonition-title, div.important p.admonition-title,
-div.note p.admonition-title, div.tip p.admonition-title {
-  font-weight: bold ;
-  font-family: sans-serif }
-
-div.dedication {
-  margin: 2em 5em ;
-  text-align: center ;
-  font-style: italic }
-
-div.dedication p.topic-title {
-  font-weight: bold ;
-  font-style: normal }
-
-div.figure {
-  margin-left: 2em }
-
-div.footer, div.header {
-  font-size: smaller }
-
-div.system-messages {
-  margin: 5em }
-
-div.system-messages h1 {
-  color: red }
-
-div.system-message {
-  border: medium outset ;
-  padding: 1em }
-
-div.system-message p.system-message-title {
-  color: red ;
-  font-weight: bold }
-
-div.topic {
-  margin: 2em }
-
-h1.title {
-  text-align: center }
-
-h2.subtitle {
-  text-align: center }
-
-hr {
-  width: 75% }
-
-ol.simple, ul.simple {
-  margin-bottom: 1em }
-
-ol.arabic {
-  list-style: decimal }
-
-ol.loweralpha {
-  list-style: lower-alpha }
-
-ol.upperalpha {
-  list-style: upper-alpha }
-
-ol.lowerroman {
-  list-style: lower-roman }
-
-ol.upperroman {
-  list-style: upper-roman }
-
-p.caption {
-  font-style: italic }
-
-p.credits {
-  font-style: italic ;
-  font-size: smaller }
-
-p.label {
-  white-space: nowrap }
-
-p.topic-title {
-  font-weight: bold }
-
-pre.address {
-  margin-bottom: 0 ;
-  margin-top: 0 ;
-  font-family: serif ;
-  font-size: 100% }
-
-pre.line-block {
-  font-family: serif ;
-  font-size: 100% }
-
-pre.literal-block, pre.doctest-block {
-  margin-left: 2em ;
-  margin-right: 2em ;
-  background-color: #eeeeee }
-
-span.classifier {
-  font-family: sans-serif ;
-  font-style: oblique }
-
-span.classifier-delimiter {
-  font-family: sans-serif ;
-  font-weight: bold }
-
-span.interpreted {
-  font-family: sans-serif }
-
-span.option-argument {
-  font-style: italic }
-
-span.pre {
-  white-space: pre }
-
-span.problematic {
-  color: red }
-
-table {
-  margin-top: 0.5em ;
-  margin-bottom: 0.5em }
-
-table.citation {
-  border-left: solid thin gray ;
-  padding-left: 0.5ex }
-
-table.docinfo {
-  margin: 2em 4em }
-
-table.footnote {
-  border-left: solid thin black ;
-  padding-left: 0.5ex }
-
-td, th {
-  padding-left: 0.5em ;
-  padding-right: 0.5em ;
-  vertical-align: top }
-
-th.docinfo-name, th.field-name {
-  font-weight: bold ;
-  text-align: left ;
-  white-space: nowrap }
-
-h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
-  font-size: 100% }
-
-tt {
-  background-color: #eeeeee }
-
-ul.auto-toc {
-  list-style-type: none }
-
---></style>
+<link rel="stylesheet" href="../../../rst.css" type="text/css" />
 </head>
 <body>
 <div class="document" id="the-boost-iterator-library-logo">
-<h1 class="title">The Boost.Iterator Library <a class="reference" href="../../../index.htm"><img alt="Boost" src="../../../c++boost.gif" /></a></h1>
-<hr />
-<table class="field-list" frame="void" rules="none">
+<h1 class="title">The Boost.Iterator Library <a class="reference external" href="../../../index.htm"><img alt="Boost" src="../../../boost.png" /></a></h1>
+
+<!-- Distributed under the Boost -->
+<!-- Software License, Version 1.0. (See accompanying -->
+<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
+<hr class="docutils" />
+<table class="docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">Authors:</th><td class="field-body">David Abrahams, Jeremy Siek, Thomas Witt</td>
 </tr>
-<tr class="field"><th class="field-name">Contact:</th><td class="field-body"><a class="reference" href="mailto:dave&#64;boost-consulting.com">dave&#64;boost-consulting.com</a>, <a class="reference" href="mailto:jsiek&#64;osl.iu.edu">jsiek&#64;osl.iu.edu</a>, <a class="reference" href="mailto:witt&#64;ive.uni-hannover.de">witt&#64;ive.uni-hannover.de</a></td>
+<tr class="field"><th class="field-name">Contact:</th><td class="field-body"><a class="reference external" href="mailto:dave&#64;boost-consulting.com">dave&#64;boost-consulting.com</a>, <a class="reference external" href="mailto:jsiek&#64;osl.iu.edu">jsiek&#64;osl.iu.edu</a>, <a class="reference external" href="mailto:witt&#64;styleadvisor.com">witt&#64;styleadvisor.com</a></td>
 </tr>
-<tr class="field"><th class="field-name">organizations:</th><td class="field-body"><a class="reference" href="http://www.boost-consulting.com">Boost Consulting</a>, Indiana University <a class="reference" href="http://www.osl.iu.edu">Open Systems
-Lab</a>, University of Hanover <a class="reference" href="http://www.ive.uni-hannover.de">Institute for Transport
-Railway Operation and Construction</a></td>
+<tr class="field"><th class="field-name">organizations:</th><td class="field-body"><a class="reference external" href="http://www.boost-consulting.com">Boost Consulting</a>, Indiana University <a class="reference external" href="http://www.osl.iu.edu">Open Systems
+Lab</a>, <a class="reference external" href="http://www.styleadvisor.com">Zephyr Associates, Inc.</a></td>
 </tr>
 <tr class="field"><th class="field-name">date:</th><td class="field-body">$Date$</td>
 </tr>
-<tr class="field"><th class="field-name">copyright:</th><td class="field-body">Copyright David Abrahams, Jeremy Siek, Thomas Witt 2003. All rights reserved</td>
+<tr class="field"><th class="field-name">copyright:</th><td class="field-body">Copyright David Abrahams, Jeremy Siek, Thomas Witt 2003.</td>
 </tr>
 </tbody>
 </table>
-<table class="field-list" frame="void" rules="none">
+<table class="docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
 <tr class="field"><th class="field-name">Abstract:</th><td class="field-body">The Boost Iterator Library contains two parts. The first
-is a system of <a class="reference" href="../../../more/generic_programming.html#concept">concepts</a> which extend the C++ standard
+is a system of <a class="reference external" href="http://www.boost.org/more/generic_programming.html#concept">concepts</a> which extend the C++ standard
 iterator requirements. The second is a framework of
 components for building iterators based on these
 extended concepts and includes several useful iterator
 adaptors. The extended iterator concepts have been
-carefully designed so that so that old-style iterators
+carefully designed so that old-style iterators
 can fit in the new concepts and so that new-style
 iterators will be compatible with old-style algorithms,
 though algorithms may need to be updated if they want to
@@ -243,128 +55,150 @@ older Boost Iterator Adaptor Library.</td>
 </tbody>
 </table>
 <div class="contents topic" id="table-of-contents">
-<p class="topic-title"><a name="table-of-contents"><strong>Table of Contents</strong></a></p>
+<p class="topic-title first"><strong>Table of Contents</strong></p>
 <ul class="simple">
-<li><a class="reference" href="#new-style-iterators" id="id6" name="id6">New-Style Iterators</a></li>
-<li><a class="reference" href="#iterator-facade-and-adaptor" id="id7" name="id7">Iterator Facade and Adaptor</a></li>
-<li><a class="reference" href="#specialized-adaptors" id="id8" name="id8">Specialized Adaptors</a></li>
-<li><a class="reference" href="#iterator-utilities" id="id9" name="id9">Iterator Utilities</a><ul>
-<li><a class="reference" href="#traits" id="id10" name="id10">Traits</a></li>
-<li><a class="reference" href="#testing-and-concept-checking" id="id11" name="id11">Testing and Concept Checking</a></li>
+<li><a class="reference internal" href="#new-style-iterators" id="id23">New-Style Iterators</a></li>
+<li><a class="reference internal" href="#iterator-facade-and-adaptor" id="id24">Iterator Facade and Adaptor</a></li>
+<li><a class="reference internal" href="#specialized-adaptors" id="id25">Specialized Adaptors</a></li>
+<li><a class="reference internal" href="#iterator-utilities" id="id26">Iterator Utilities</a><ul>
+<li><a class="reference internal" href="#traits" id="id27">Traits</a></li>
+<li><a class="reference internal" href="#testing-and-concept-checking" id="id28">Testing and Concept Checking</a></li>
 </ul>
 </li>
-<li><a class="reference" href="#upgrading-from-the-old-boost-iterator-adaptor-library" id="id12" name="id12">Upgrading from the old Boost Iterator Adaptor Library</a></li>
-<li><a class="reference" href="#history" id="id13" name="id13">History</a></li>
+<li><a class="reference internal" href="#upgrading-from-the-old-boost-iterator-adaptor-library" id="id29">Upgrading from the old Boost Iterator Adaptor Library</a></li>
+<li><a class="reference internal" href="#history" id="id30">History</a></li>
 </ul>
 </div>
-<hr />
+<hr class="docutils" />
 <div class="section" id="new-style-iterators">
-<h1><a class="toc-backref" href="#id6" name="new-style-iterators">New-Style Iterators</a></h1>
+<h1><a class="toc-backref" href="#id23">New-Style Iterators</a></h1>
 <p>The iterator categories defined in C++98 are extremely limiting
 because they bind together two orthogonal concepts: traversal and
 element access.  For example, because a random access iterator is
 required to return a reference (and not a proxy) when dereferenced,
 it is impossible to capture the capabilities of
-<tt class="literal"><span class="pre">vector&lt;bool&gt;::iterator</span></tt> using the C++98 categories.  This is the
-infamous &quot;<tt class="literal"><span class="pre">vector&lt;bool&gt;</span></tt> is not a container, and its iterators
+<tt class="docutils literal"><span class="pre">vector&lt;bool&gt;::iterator</span></tt> using the C++98 categories.  This is the
+infamous &quot;<tt class="docutils literal"><span class="pre">vector&lt;bool&gt;</span></tt> is not a container, and its iterators
 aren't random access iterators&quot;, debacle about which Herb Sutter
-wrote two papers for the standards comittee (<a class="reference" href="http://www.gotw.ca/publications/N1185.pdf">n1185</a> and <a class="reference" href="http://www.gotw.ca/publications/N1211.pdf">n1211</a>),
-and a <a class="reference" href="http://www.gotw.ca/gotw/050.htm">Guru of the Week</a>.  New-style iterators go well beyond
-patching up <tt class="literal"><span class="pre">vector&lt;bool&gt;</span></tt>, though: there are lots of other
+wrote two papers for the standards comittee (<a class="reference external" href="http://www.gotw.ca/publications/N1185.pdf">n1185</a> and <a class="reference external" href="http://www.gotw.ca/publications/N1211.pdf">n1211</a>),
+and a <a class="reference external" href="http://www.gotw.ca/gotw/050.htm">Guru of the Week</a>.  New-style iterators go well beyond
+patching up <tt class="docutils literal"><span class="pre">vector&lt;bool&gt;</span></tt>, though: there are lots of other
 iterators already in use which can't be adequately represented by
 the existing concepts.  For details about the new iterator
 concepts, see our</p>
 <blockquote>
-<a class="reference" href="new-iter-concepts.html">Standard Proposal For New-Style Iterators</a></blockquote>
+<a class="reference external" href="new-iter-concepts.html">Standard Proposal For New-Style Iterators</a> (<a class="reference external" href="new-iter-concepts.pdf">PDF</a>)</blockquote>
 </div>
 <div class="section" id="iterator-facade-and-adaptor">
-<h1><a class="toc-backref" href="#id7" name="iterator-facade-and-adaptor">Iterator Facade and Adaptor</a></h1>
+<h1><a class="toc-backref" href="#id24">Iterator Facade and Adaptor</a></h1>
 <p>Writing standard-conforming iterators is tricky, but the need comes
 up often.  In order to ease the implementation of new iterators,
-the Boost.Iterator library provides the <a class="reference" href="iterator_facade.html"><tt class="literal"><span class="pre">iterator_facade</span></tt></a> class template,
+the Boost.Iterator library provides the <tt class="docutils literal"><span class="pre">iterator_facade</span></tt> class template,
 which implements many useful defaults and compile-time checks
-designed to help the author iterator ensure that his iterator is
-correct.  It is common to define a new iterator which behaves like
-another iterator, but which modifies some aspect of its behavior.
-For that purpose, the library supplies the <a class="reference" href="iterator_adaptor.html"><tt class="literal"><span class="pre">iterator_adaptor</span></tt></a> class
-template, which is specially designed to take advantage of as much
-of the underlying iterator's behavior as possible.</p>
-<p>Both <a class="reference" href="iterator_facade.html"><tt class="literal"><span class="pre">iterator_facade</span></tt></a> and <a class="reference" href="iterator_adaptor.html"><tt class="literal"><span class="pre">iterator_adaptor</span></tt></a> as well as many of the <a class="reference" href="#specialized-adaptors">specialized
+designed to help the iterator author ensure that his iterator is
+correct.</p>
+<p>It is also common to define a new iterator that is similar to some
+underlying iterator or iterator-like type, but that modifies some
+aspect of the underlying type's behavior.  For that purpose, the
+library supplies the <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> class template, which is specially
+designed to take advantage of as much of the underlying type's
+behavior as possible.</p>
+<p>The documentation for these two classes can be found at the following
+web pages:</p>
+<ul class="simple">
+<li><a class="reference external" href="iterator_facade.html"><tt class="docutils literal"><span class="pre">iterator_facade</span></tt></a> (<a class="reference external" href="iterator_facade.pdf">PDF</a>)</li>
+<li><a class="reference external" href="iterator_adaptor.html"><tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt></a> (<a class="reference external" href="iterator_adaptor.pdf">PDF</a>)</li>
+</ul>
+<p>Both <tt class="docutils literal"><span class="pre">iterator_facade</span></tt> and <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> as well as many of the <a class="reference internal" href="#specialized-adaptors">specialized
 adaptors</a> mentioned below have been proposed for standardization,
 and accepted into the first C++ technical report; see our</p>
 <blockquote>
-<a class="reference" href="facade-and-adaptor.html">Standard Proposal For Iterator Facade and Adaptor</a></blockquote>
+<a class="reference external" href="facade-and-adaptor.html">Standard Proposal For Iterator Facade and Adaptor</a> (<a class="reference external" href="facade-and-adaptor.pdf">PDF</a>)</blockquote>
 <p>for more details.</p>
 </div>
 <div class="section" id="specialized-adaptors">
-<h1><a class="toc-backref" href="#id8" name="specialized-adaptors">Specialized Adaptors</a></h1>
+<h1><a class="toc-backref" href="#id25">Specialized Adaptors</a></h1>
 <p>The iterator library supplies a useful suite of standard-conforming
-iterator templates based on the Boost <a class="reference" href="#iterator-facade-and-adaptor">iterator facade and adaptor</a>.</p>
+iterator templates based on the Boost <a class="reference internal" href="#iterator-facade-and-adaptor">iterator facade and adaptor</a>.</p>
 <ul class="simple">
-<li><a class="reference" href="counting_iterator.html"><tt class="literal"><span class="pre">counting_iterator</span></tt></a>: an iterator over a sequence of consecutive values.
+<li><a class="reference external" href="counting_iterator.html"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt></a> (<a class="reference external" href="counting_iterator.pdf">PDF</a>): an iterator over a sequence of consecutive values.
 Implements a &quot;lazy sequence&quot;</li>
-<li><a class="reference" href="filter_iterator.html"><tt class="literal"><span class="pre">filter_iterator</span></tt></a>: an iterator over the subset of elements of some
+<li><a class="reference external" href="filter_iterator.html"><tt class="docutils literal"><span class="pre">filter_iterator</span></tt></a> (<a class="reference external" href="filter_iterator.pdf">PDF</a>): an iterator over the subset of elements of some
 sequence which satisfy a given predicate</li>
-<li><a class="reference" href="indirect_iterator.html"><tt class="literal"><span class="pre">indirect_iterator</span></tt></a>: an iterator over the objects <em>pointed-to</em> by the
+<li><a class="reference external" href="function_input_iterator.html"><tt class="docutils literal"><span class="pre">function_input_iterator</span></tt></a> (<a class="reference external" href="function_input_iterator.pdf">PDF</a>): an input iterator wrapping a generator (nullary
+function object); each time the iterator is dereferenced, the function object
+is called to get the value to return.</li>
+<li><a class="reference external" href="function_output_iterator.html"><tt class="docutils literal"><span class="pre">function_output_iterator</span></tt></a> (<a class="reference external" href="function_output_iterator.pdf">PDF</a>): an output iterator wrapping a unary function
+object; each time an element is written into the dereferenced
+iterator, it is passed as a parameter to the function object.</li>
+<li><a class="reference external" href="indirect_iterator.html"><tt class="docutils literal"><span class="pre">indirect_iterator</span></tt></a> (<a class="reference external" href="indirect_iterator.pdf">PDF</a>): an iterator over the objects <em>pointed-to</em> by the
 elements of some sequence.</li>
-<li><a class="reference" href="permutation_iterator.html"><tt class="literal"><span class="pre">permutation_iterator</span></tt></a>: an iterator over the elements of some random-access
+<li><a class="reference external" href="permutation_iterator.html"><tt class="docutils literal"><span class="pre">permutation_iterator</span></tt></a> (<a class="reference external" href="permutation_iterator.pdf">PDF</a>): an iterator over the elements of some random-access
 sequence, rearranged according to some sequence of integer indices.</li>
-<li><a class="reference" href="reverse_iterator.html"><tt class="literal"><span class="pre">reverse_iterator</span></tt></a>: an iterator which traverses the elements of some
+<li><a class="reference external" href="reverse_iterator.html"><tt class="docutils literal"><span class="pre">reverse_iterator</span></tt></a> (<a class="reference external" href="reverse_iterator.pdf">PDF</a>): an iterator which traverses the elements of some
 bidirectional sequence in reverse.  Corrects many of the
-shortcomings of C++98's <tt class="literal"><span class="pre">std::reverse_iterator</span></tt>.</li>
-<li><a class="reference" href="transform_iterator.html"><tt class="literal"><span class="pre">transform_iterator</span></tt></a>: an iterator over elements which are the result of
+shortcomings of C++98's <tt class="docutils literal"><span class="pre">std::reverse_iterator</span></tt>.</li>
+<li><a class="reference external" href="../../utility/shared_container_iterator.html"><tt class="docutils literal"><span class="pre">shared_container_iterator</span></tt></a>: an iterator over elements of a container whose
+lifetime is maintained by a <a class="reference external" href="../../smart_ptr/shared_ptr.htm"><tt class="docutils literal"><span class="pre">shared_ptr</span></tt></a> stored in the iterator.</li>
+<li><a class="reference external" href="transform_iterator.html"><tt class="docutils literal"><span class="pre">transform_iterator</span></tt></a> (<a class="reference external" href="transform_iterator.pdf">PDF</a>): an iterator over elements which are the result of
 applying some functional transformation to the elements of an
 underlying sequence.  This component also replaces the old
-<tt class="literal"><span class="pre">projection_iterator_adaptor</span></tt>.</li>
+<tt class="docutils literal"><span class="pre">projection_iterator_adaptor</span></tt>.</li>
+<li><a class="reference external" href="zip_iterator.html"><tt class="docutils literal"><span class="pre">zip_iterator</span></tt></a> (<a class="reference external" href="zip_iterator.pdf">PDF</a>): an iterator over tuples of the elements at corresponding
+positions of heterogeneous underlying iterators.</li>
 </ul>
 </div>
 <div class="section" id="iterator-utilities">
-<h1><a class="toc-backref" href="#id9" name="iterator-utilities">Iterator Utilities</a></h1>
+<h1><a class="toc-backref" href="#id26">Iterator Utilities</a></h1>
 <div class="section" id="traits">
-<h2><a class="toc-backref" href="#id10" name="traits">Traits</a></h2>
+<h2><a class="toc-backref" href="#id27">Traits</a></h2>
 <ul class="simple">
-<li><a class="reference" href="iterator_traits.html"><tt class="literal"><span class="pre">iterator_traits.hpp</span></tt></a>: Provides <a class="reference" href="../../mpl/doc/index.html">MPL</a>-compatible metafunctions which
+<li><a class="reference external" href="pointee.html"><tt class="docutils literal"><span class="pre">pointee.hpp</span></tt></a> (<a class="reference external" href="pointee.pdf">PDF</a>): Provides the capability to deduce the referent types
+of pointers, smart pointers and iterators in generic code.  Used
+in <tt class="docutils literal"><span class="pre">indirect_iterator</span></tt>.</li>
+<li><a class="reference external" href="iterator_traits.html"><tt class="docutils literal"><span class="pre">iterator_traits.hpp</span></tt></a> (<a class="reference external" href="iterator_traits.pdf">PDF</a>): Provides <a class="reference external" href="../../mpl/doc/index.html">MPL</a>-compatible metafunctions which
 retrieve an iterator's traits.  Also corrects for the deficiencies
-of broken implementations of <tt class="literal"><span class="pre">std::iterator_traits</span></tt>.</li>
-<li><a class="reference" href="interoperable.html"><tt class="literal"><span class="pre">interoperable.hpp</span></tt></a>: Provides an <a class="reference" href="../../mpl/doc/index.html">MPL</a>-compatible metafunction for
-testing iterator interoperability</li>
+of broken implementations of <tt class="docutils literal"><span class="pre">std::iterator_traits</span></tt>.</li>
 </ul>
+<!-- * |interoperable|_ (PDF__): Provides an MPL_\ -compatible metafunction for
+testing iterator interoperability -->
+<!-- comment! __ interoperable.pdf -->
 </div>
 <div class="section" id="testing-and-concept-checking">
-<h2><a class="toc-backref" href="#id11" name="testing-and-concept-checking">Testing and Concept Checking</a></h2>
+<h2><a class="toc-backref" href="#id28">Testing and Concept Checking</a></h2>
 <ul class="simple">
-<li><a class="reference" href="iterator_archetypes.html"><tt class="literal"><span class="pre">iterator_archetypes.hpp</span></tt></a>: Add summary here</li>
-<li><a class="reference" href="iterator_concepts.html"><tt class="literal"><span class="pre">iterator_concepts.hpp</span></tt></a>: Add summary</li>
+<li><a class="reference external" href="iterator_concepts.html"><tt class="docutils literal"><span class="pre">iterator_concepts.hpp</span></tt></a> (<a class="reference external" href="iterator_concepts.pdf">PDF</a>): Concept checking classes for the new iterator concepts.</li>
+<li><a class="reference external" href="iterator_archetypes.html"><tt class="docutils literal"><span class="pre">iterator_archetypes.hpp</span></tt></a> (<a class="reference external" href="iterator_archetypes.pdf">PDF</a>): Concept archetype classes for the new iterators concepts.</li>
 </ul>
 </div>
 </div>
 <div class="section" id="upgrading-from-the-old-boost-iterator-adaptor-library">
-<h1><a class="toc-backref" href="#id12" name="upgrading-from-the-old-boost-iterator-adaptor-library">Upgrading from the old Boost Iterator Adaptor Library</a></h1>
-<a class="target" id="upgrading" name="upgrading"></a><p>If you have been using the old Boost Iterator Adaptor library to
-implement iterators, you probably wrote a <tt class="literal"><span class="pre">Policies</span></tt> class which
+<h1><a class="toc-backref" href="#id29">Upgrading from the old Boost Iterator Adaptor Library</a></h1>
+<p id="upgrading">If you have been using the old Boost Iterator Adaptor library to
+implement iterators, you probably wrote a <tt class="docutils literal"><span class="pre">Policies</span></tt> class which
 captures the core operations of your iterator.  In the new library
 design, you'll move those same core operations into the body of the
 iterator class itself.  If you were writing a family of iterators,
-you probably wrote a <a class="reference" href="../../../more/generic_programming.html#type_generator">type generator</a> to build the
-<tt class="literal"><span class="pre">iterator_adaptor</span></tt> specialization you needed; in the new library
+you probably wrote a <a class="reference external" href="http://www.boost.org/more/generic_programming.html#type_generator">type generator</a> to build the
+<tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> specialization you needed; in the new library
 design you don't need a type generator (though may want to keep it
 around as a compatibility aid for older code) because, due to the
-use of the Curiously Recurring Template Pattern (CRTP) <a class="citation-reference" href="#cop95" id="id5" name="id5">[Cop95]</a>,
+use of the Curiously Recurring Template Pattern (CRTP) <a class="citation-reference" href="#cop95" id="id22">[Cop95]</a>,
 you can now define the iterator class yourself and acquire
-functionality through inheritance from <tt class="literal"><span class="pre">iterator_facade</span></tt> or
-<tt class="literal"><span class="pre">iterator_adaptor</span></tt>.  As a result, you also get much finer control
+functionality through inheritance from <tt class="docutils literal"><span class="pre">iterator_facade</span></tt> or
+<tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt>.  As a result, you also get much finer control
 over how your iterator works: you can add additional constructors,
 or even override the iterator functionality provided by the
 library.</p>
-<p>If you're looking for the old <tt class="literal"><span class="pre">projection_iterator</span></tt> component,
-its functionality has been merged into <tt class="literal"><span class="pre">transform_iterator</span></tt>: as
-long as the function object's <tt class="literal"><span class="pre">result_type</span></tt> (or the <tt class="literal"><span class="pre">Reference</span></tt>
+<p>If you're looking for the old <tt class="docutils literal"><span class="pre">projection_iterator</span></tt> component,
+its functionality has been merged into <tt class="docutils literal"><span class="pre">transform_iterator</span></tt>: as
+long as the function object's <tt class="docutils literal"><span class="pre">result_type</span></tt> (or the <tt class="docutils literal"><span class="pre">Reference</span></tt>
 template argument, if explicitly specified) is a true reference
-type, <tt class="literal"><span class="pre">transform_iterator</span></tt> will behave like
-<tt class="literal"><span class="pre">projection_iterator</span></tt> used to.</p>
+type, <tt class="docutils literal"><span class="pre">transform_iterator</span></tt> will behave like
+<tt class="docutils literal"><span class="pre">projection_iterator</span></tt> used to.</p>
 </div>
 <div class="section" id="history">
-<h1><a class="toc-backref" href="#id13" name="history">History</a></h1>
+<h1><a class="toc-backref" href="#id30">History</a></h1>
 <p>In 2000 Dave Abrahams was writing an iterator for a container of
 pointers, which would access the pointed-to elements when
 dereferenced.  Naturally, being a library writer, he decided to
@@ -385,15 +219,14 @@ policies into the iterator class itself.  Thomas Witt expressed
 interest and became the voice of strict compile-time checking for
 the project, adding uses of the SFINAE technique to eliminate false
 converting constructors and operators from the overload set.  He
-also recognized the need for a separate <tt class="literal"><span class="pre">iterator_facade</span></tt>, and
-factored it out of <tt class="literal"><span class="pre">iterator_adaptor</span></tt>.  Finally, after a
+also recognized the need for a separate <tt class="docutils literal"><span class="pre">iterator_facade</span></tt>, and
+factored it out of <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt>.  Finally, after a
 near-complete rewrite of the prototype, they came up with the
 library you see today.</p>
-<table class="citation" frame="void" id="cop95" rules="none">
+<table class="docutils citation" frame="void" id="cop95" rules="none">
 <colgroup><col class="label" /><col /></colgroup>
-<col />
 <tbody valign="top">
-<tr><td class="label"><a class="fn-backref" href="#id5" name="cop95">[Cop95]</a></td><td>[Coplien, 1995] Coplien, J., Curiously Recurring Template
+<tr><td class="label"><a class="fn-backref" href="#id22">[Cop95]</a></td><td>[Coplien, 1995] Coplien, J., Curiously Recurring Template
 Patterns, C++ Report, February 1995, pp. 24-27.</td></tr>
 </tbody>
 </table>
@@ -406,11 +239,11 @@ LocalWords:  incrementable xxx min prev inplace png oldeqnew AccessTag struct
 LocalWords:  TraversalTag typename lvalues DWA Hmm JGS -->
 </div>
 </div>
-<hr class="footer" />
 <div class="footer">
-<a class="reference" href="index.rst">View document source</a>.
-Generated on: 2003-11-24 04:21 UTC.
-Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
+<hr class="footer" />
+<a class="reference external" href="index.rst">View document source</a>.
+Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
+
 </div>
 </body>
 </html>

doc/index.rst

@@ -1,8 +1,12 @@
+.. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
 +++++++++++++++++++++++++++++++++++++++++++++++++
  The Boost.Iterator Library |(logo)|__
 +++++++++++++++++++++++++++++++++++++++++++++++++
 
-.. |(logo)| image:: ../../../c++boost.gif
+.. |(logo)| image:: ../../../boost.png
    :alt: Boost
 
 __ ../../../index.htm
@@ -12,16 +16,16 @@ __ ../../../index.htm
 
 
 :Authors:       David Abrahams, Jeremy Siek, Thomas Witt
-:Contact:       dave@boost-consulting.com, jsiek@osl.iu.edu, witt@ive.uni-hannover.de
+:Contact:       dave@boost-consulting.com, jsiek@osl.iu.edu, witt@styleadvisor.com
 :organizations: `Boost Consulting`_, Indiana University `Open Systems
-                Lab`_, University of Hanover `Institute for Transport
-                Railway Operation and Construction`_
+                Lab`_, `Zephyr Associates, Inc.`_
 :date:          $Date$
-:copyright:     Copyright David Abrahams, Jeremy Siek, Thomas Witt 2003. All rights reserved
+
+:copyright:     Copyright David Abrahams, Jeremy Siek, Thomas Witt 2003.
 
 .. _`Boost Consulting`: http://www.boost-consulting.com
 .. _`Open Systems Lab`: http://www.osl.iu.edu
-.. _`Institute for Transport Railway Operation and Construction`: http://www.ive.uni-hannover.de
+.. _`Zephyr Associates, Inc.`: http://www.styleadvisor.com
 
 :Abstract: The Boost Iterator Library contains two parts. The first
            is a system of concepts_ which extend the C++ standard
@@ -29,7 +33,7 @@ __ ../../../index.htm
            components for building iterators based on these
            extended concepts and includes several useful iterator
            adaptors. The extended iterator concepts have been
-           carefully designed so that so that old-style iterators
+           carefully designed so that old-style iterators
            can fit in the new concepts and so that new-style
            iterators will be compatible with old-style algorithms,
            though algorithms may need to be updated if they want to
@@ -39,7 +43,7 @@ __ ../../../index.htm
            The components of the Boost Iterator Library replace the
            older Boost Iterator Adaptor Library.
 
-.. _concepts: ../../../more/generic_programming.html#concept
+.. _concepts: http://www.boost.org/more/generic_programming.html#concept
 
 .. contents:: **Table of Contents**
 
@@ -71,9 +75,10 @@ concepts, see our
 __ http://www.gotw.ca/gotw/050.htm
 
 
-   `Standard Proposal For New-Style Iterators`__
+   `Standard Proposal For New-Style Iterators`__ (PDF__)
 
 __ new-iter-concepts.html
+__ new-iter-concepts.pdf
 
 =============================
  Iterator Facade and Adaptor
@@ -81,29 +86,44 @@ __ new-iter-concepts.html
 
 Writing standard-conforming iterators is tricky, but the need comes
 up often.  In order to ease the implementation of new iterators,
-the Boost.Iterator library provides the |facade|_ class template,
+the Boost.Iterator library provides the |facade| class template,
 which implements many useful defaults and compile-time checks
-designed to help the author iterator ensure that his iterator is
-correct.  It is common to define a new iterator which behaves like
-another iterator, but which modifies some aspect of its behavior.
-For that purpose, the library supplies the |adaptor|_ class
-template, which is specially designed to take advantage of as much
-of the underlying iterator's behavior as possible.
+designed to help the iterator author ensure that his iterator is
+correct.  
+
+It is also common to define a new iterator that is similar to some
+underlying iterator or iterator-like type, but that modifies some
+aspect of the underlying type's behavior.  For that purpose, the
+library supplies the |adaptor| class template, which is specially
+designed to take advantage of as much of the underlying type's
+behavior as possible.
+
+The documentation for these two classes can be found at the following
+web pages:
+
+* |facade|_ (PDF__)
+
+* |adaptor|_ (PDF__)
+
 
 .. |facade| replace:: ``iterator_facade``
 .. _facade: iterator_facade.html
+__ iterator_facade.pdf
+
 .. |adaptor| replace:: ``iterator_adaptor``
 .. _adaptor: iterator_adaptor.html
+__ iterator_adaptor.pdf
 
-Both |facade|_ and |adaptor|_ as well as many of the `specialized
-adaptors`_ mentioned below have been proposed for standardization,
-and accepted into the first C++ technical report; see our
+Both |facade| and |adaptor| as well as many of the `specialized
+adaptors`_ mentioned below have been proposed for standardization;
+see our
 
-   `Standard Proposal For Iterator Facade and Adaptor`__
+   `Standard Proposal For Iterator Facade and Adaptor`__ (PDF__)
 
 for more details.
 
 __ facade-and-adaptor.html
+__ facade-and-adaptor.pdf
 
 ======================
  Specialized Adaptors
@@ -112,44 +132,82 @@ __ facade-and-adaptor.html
 The iterator library supplies a useful suite of standard-conforming
 iterator templates based on the Boost `iterator facade and adaptor`_.
 
-* |counting|_: an iterator over a sequence of consecutive values.
+* |counting|_ (PDF__): an iterator over a sequence of consecutive values.
   Implements a "lazy sequence"
 
-* |filter|_: an iterator over the subset of elements of some
+* |filter|_ (PDF__): an iterator over the subset of elements of some
   sequence which satisfy a given predicate
 
-* |indirect|_: an iterator over the objects *pointed-to* by the
+* |function_input|_ (PDF__): an input iterator wrapping a generator (nullary
+  function object); each time the iterator is dereferenced, the function object
+  is called to get the value to return.
+
+* |function_output|_ (PDF__): an output iterator wrapping a unary function
+  object; each time an element is written into the dereferenced
+  iterator, it is passed as a parameter to the function object.
+
+* |indirect|_ (PDF__): an iterator over the objects *pointed-to* by the
   elements of some sequence.
 
-* |permutation|_: an iterator over the elements of some random-access
+* |permutation|_ (PDF__): an iterator over the elements of some random-access
   sequence, rearranged according to some sequence of integer indices.
 
-* |reverse|_: an iterator which traverses the elements of some
+* |reverse|_ (PDF__): an iterator which traverses the elements of some
   bidirectional sequence in reverse.  Corrects many of the
   shortcomings of C++98's ``std::reverse_iterator``.
 
-* |transform|_: an iterator over elements which are the result of
+* |shared|_: an iterator over elements of a container whose
+  lifetime is maintained by a |shared_ptr|_ stored in the iterator.
+
+* |transform|_ (PDF__): an iterator over elements which are the result of
   applying some functional transformation to the elements of an
   underlying sequence.  This component also replaces the old
   ``projection_iterator_adaptor``.
 
+* |zip|_ (PDF__): an iterator over tuples of the elements at corresponding
+  positions of heterogeneous underlying iterators.
+
 .. |counting| replace:: ``counting_iterator``
 .. _counting: counting_iterator.html
+__ counting_iterator.pdf
 
 .. |filter| replace:: ``filter_iterator``
 .. _filter: filter_iterator.html
+__ filter_iterator.pdf
+
+.. |function_input| replace:: ``function_input_iterator``
+.. _function_input: function_input_iterator.html
+__ function_input_iterator.pdf
+
+.. |function_output| replace:: ``function_output_iterator``
+.. _function_output: function_output_iterator.html
+__ function_output_iterator.pdf
 
 .. |indirect| replace:: ``indirect_iterator``
 .. _indirect: indirect_iterator.html
+__ indirect_iterator.pdf
 
 .. |permutation| replace:: ``permutation_iterator``
 .. _permutation: permutation_iterator.html
+__ permutation_iterator.pdf
 
 .. |reverse| replace:: ``reverse_iterator``
 .. _reverse: reverse_iterator.html
+__ reverse_iterator.pdf
+
+.. |shared| replace:: ``shared_container_iterator``
+.. _shared: ../../utility/shared_container_iterator.html
 
 .. |transform| replace:: ``transform_iterator``
 .. _transform: transform_iterator.html
+__ transform_iterator.pdf
+
+.. |zip| replace:: ``zip_iterator``
+.. _zip: zip_iterator.html
+__ zip_iterator.pdf
+
+.. |shared_ptr| replace:: ``shared_ptr``
+.. _shared_ptr: ../../smart_ptr/shared_ptr.htm
 
 ====================
  Iterator Utilities
@@ -158,34 +216,45 @@ iterator templates based on the Boost `iterator facade and adaptor`_.
 Traits
 ------
 
-* |iterator_traits|_: Provides MPL_\ -compatible metafunctions which
+* |pointee|_ (PDF__): Provides the capability to deduce the referent types
+  of pointers, smart pointers and iterators in generic code.  Used
+  in |indirect|.
+
+* |iterator_traits|_ (PDF__): Provides MPL_\ -compatible metafunctions which
   retrieve an iterator's traits.  Also corrects for the deficiencies
   of broken implementations of ``std::iterator_traits``.
 
-* |interoperable|_: Provides an MPL_\ -compatible metafunction for
-  testing iterator interoperability
+.. * |interoperable|_ (PDF__): Provides an MPL_\ -compatible metafunction for
+     testing iterator interoperability
+
+.. |pointee| replace:: ``pointee.hpp``
+.. _pointee: pointee.html
+__ pointee.pdf
 
 .. |iterator_traits| replace:: ``iterator_traits.hpp``
 .. _iterator_traits: iterator_traits.html
+__ iterator_traits.pdf
 
 .. |interoperable| replace:: ``interoperable.hpp``
 .. _interoperable: interoperable.html
+.. comment! __ interoperable.pdf
 
 .. _MPL: ../../mpl/doc/index.html
 
 Testing and Concept Checking
 ----------------------------
 
-* |iterator_archetypes|_: Add summary here
+* |iterator_concepts|_ (PDF__): Concept checking classes for the new iterator concepts.
 
-* |iterator_concepts|_: Add summary
-
-.. |iterator_archetypes| replace:: ``iterator_archetypes.hpp``
-.. _iterator_archetypes: iterator_archetypes.html
+* |iterator_archetypes|_ (PDF__): Concept archetype classes for the new iterators concepts.
 
 .. |iterator_concepts| replace:: ``iterator_concepts.hpp``
 .. _iterator_concepts: iterator_concepts.html
+__ iterator_concepts.pdf
 
+.. |iterator_archetypes| replace:: ``iterator_archetypes.hpp``
+.. _iterator_archetypes: iterator_archetypes.html
+__ iterator_archetypes.pdf
 
 =======================================================
  Upgrading from the old Boost Iterator Adaptor Library
@@ -210,7 +279,7 @@ over how your iterator works: you can add additional constructors,
 or even override the iterator functionality provided by the
 library.
 
-.. _`type generator`: ../../../more/generic_programming.html#type_generator
+.. _`type generator`: http://www.boost.org/more/generic_programming.html#type_generator
 
 If you're looking for the old ``projection_iterator`` component,
 its functionality has been merged into ``transform_iterator``: as

doc/indirect_iterator.html

@@ -3,204 +3,13 @@
 <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.1: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
 <title>Indirect Iterator</title>
 <meta name="author" content="David Abrahams, Jeremy Siek, Thomas Witt" />
 <meta name="organization" content="Boost Consulting, Indiana University Open Systems Lab, University of Hanover Institute for Transport Railway Operation and Construction" />
-<meta name="date" content="2003-09-14" />
-<meta name="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved" />
-<style type="text/css"><!--
-
-/*
-:Author: David Goodger
-:Contact: goodger@users.sourceforge.net
-:date: $Date$
-:version: $Revision$
-:copyright: This stylesheet has been placed in the public domain.
-
-Default cascading style sheet for the HTML output of Docutils.
-*/
-
-.first {
-  margin-top: 0 }
-
-.last {
-  margin-bottom: 0 }
-
-a.toc-backref {
-  text-decoration: none ;
-  color: black }
-
-dd {
-  margin-bottom: 0.5em }
-
-div.abstract {
-  margin: 2em 5em }
-
-div.abstract p.topic-title {
-  font-weight: bold ;
-  text-align: center }
-
-div.attention, div.caution, div.danger, div.error, div.hint,
-div.important, div.note, div.tip, div.warning {
-  margin: 2em ;
-  border: medium outset ;
-  padding: 1em }
-
-div.attention p.admonition-title, div.caution p.admonition-title,
-div.danger p.admonition-title, div.error p.admonition-title,
-div.warning p.admonition-title {
-  color: red ;
-  font-weight: bold ;
-  font-family: sans-serif }
-
-div.hint p.admonition-title, div.important p.admonition-title,
-div.note p.admonition-title, div.tip p.admonition-title {
-  font-weight: bold ;
-  font-family: sans-serif }
-
-div.dedication {
-  margin: 2em 5em ;
-  text-align: center ;
-  font-style: italic }
-
-div.dedication p.topic-title {
-  font-weight: bold ;
-  font-style: normal }
-
-div.figure {
-  margin-left: 2em }
-
-div.footer, div.header {
-  font-size: smaller }
-
-div.system-messages {
-  margin: 5em }
-
-div.system-messages h1 {
-  color: red }
-
-div.system-message {
-  border: medium outset ;
-  padding: 1em }
-
-div.system-message p.system-message-title {
-  color: red ;
-  font-weight: bold }
-
-div.topic {
-  margin: 2em }
-
-h1.title {
-  text-align: center }
-
-h2.subtitle {
-  text-align: center }
-
-hr {
-  width: 75% }
-
-ol.simple, ul.simple {
-  margin-bottom: 1em }
-
-ol.arabic {
-  list-style: decimal }
-
-ol.loweralpha {
-  list-style: lower-alpha }
-
-ol.upperalpha {
-  list-style: upper-alpha }
-
-ol.lowerroman {
-  list-style: lower-roman }
-
-ol.upperroman {
-  list-style: upper-roman }
-
-p.caption {
-  font-style: italic }
-
-p.credits {
-  font-style: italic ;
-  font-size: smaller }
-
-p.label {
-  white-space: nowrap }
-
-p.topic-title {
-  font-weight: bold }
-
-pre.address {
-  margin-bottom: 0 ;
-  margin-top: 0 ;
-  font-family: serif ;
-  font-size: 100% }
-
-pre.line-block {
-  font-family: serif ;
-  font-size: 100% }
-
-pre.literal-block, pre.doctest-block {
-  margin-left: 2em ;
-  margin-right: 2em ;
-  background-color: #eeeeee }
-
-span.classifier {
-  font-family: sans-serif ;
-  font-style: oblique }
-
-span.classifier-delimiter {
-  font-family: sans-serif ;
-  font-weight: bold }
-
-span.interpreted {
-  font-family: sans-serif }
-
-span.option-argument {
-  font-style: italic }
-
-span.pre {
-  white-space: pre }
-
-span.problematic {
-  color: red }
-
-table {
-  margin-top: 0.5em ;
-  margin-bottom: 0.5em }
-
-table.citation {
-  border-left: solid thin gray ;
-  padding-left: 0.5ex }
-
-table.docinfo {
-  margin: 2em 4em }
-
-table.footnote {
-  border-left: solid thin black ;
-  padding-left: 0.5ex }
-
-td, th {
-  padding-left: 0.5em ;
-  padding-right: 0.5em ;
-  vertical-align: top }
-
-th.docinfo-name, th.field-name {
-  font-weight: bold ;
-  text-align: left ;
-  white-space: nowrap }
-
-h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
-  font-size: 100% }
-
-tt {
-  background-color: #eeeeee }
-
-ul.auto-toc {
-  list-style-type: none }
-
---></style>
+<meta name="date" content="2006-09-11" />
+<meta name="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003." />
+<link rel="stylesheet" href="../../../rst.css" type="text/css" />
 </head>
 <body>
 <div class="document" id="indirect-iterator">
@@ -212,119 +21,188 @@ ul.auto-toc {
 <tr><th class="docinfo-name">Author:</th>
 <td>David Abrahams, Jeremy Siek, Thomas Witt</td></tr>
 <tr><th class="docinfo-name">Contact:</th>
-<td><a class="first reference" href="mailto:dave&#64;boost-consulting.com">dave&#64;boost-consulting.com</a>, <a class="reference" href="mailto:jsiek&#64;osl.iu.edu">jsiek&#64;osl.iu.edu</a>, <a class="last reference" href="mailto:witt&#64;ive.uni-hannover.de">witt&#64;ive.uni-hannover.de</a></td></tr>
+<td><a class="first reference external" href="mailto:dave&#64;boost-consulting.com">dave&#64;boost-consulting.com</a>, <a class="reference external" href="mailto:jsiek&#64;osl.iu.edu">jsiek&#64;osl.iu.edu</a>, <a class="last reference external" href="mailto:witt&#64;ive.uni-hannover.de">witt&#64;ive.uni-hannover.de</a></td></tr>
 <tr><th class="docinfo-name">Organization:</th>
-<td><a class="first reference" href="http://www.boost-consulting.com">Boost Consulting</a>, Indiana University <a class="reference" href="http://www.osl.iu.edu">Open Systems
-Lab</a>, University of Hanover <a class="last reference" href="http://www.ive.uni-hannover.de">Institute for Transport
+<td><a class="first reference external" href="http://www.boost-consulting.com">Boost Consulting</a>, Indiana University <a class="reference external" href="http://www.osl.iu.edu">Open Systems
+Lab</a>, University of Hanover <a class="last reference external" href="http://www.ive.uni-hannover.de">Institute for Transport
 Railway Operation and Construction</a></td></tr>
 <tr><th class="docinfo-name">Date:</th>
-<td>2003-09-14</td></tr>
+<td>2006-09-11</td></tr>
 <tr><th class="docinfo-name">Copyright:</th>
-<td>Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved</td></tr>
+<td>Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003.</td></tr>
 </tbody>
 </table>
-<table class="field-list" frame="void" rules="none">
+<!-- Distributed under the Boost -->
+<!-- Software License, Version 1.0. (See accompanying -->
+<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
+<table class="docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
-<tr class="field"><th class="field-name">abstract:</th><td class="field-body"></td>
+<tr class="field"><th class="field-name">abstract:</th><td class="field-body"><!-- Copyright David Abrahams 2006. Distributed under the Boost -->
+<!-- Software License, Version 1.0. (See accompanying -->
+<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
+<tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> adapts an iterator by applying an
+<em>extra</em> dereference inside of <tt class="docutils literal"><span class="pre">operator*()</span></tt>. For example, this
+iterator adaptor makes it possible to view a container of pointers
+(e.g. <tt class="docutils literal"><span class="pre">list&lt;foo*&gt;</span></tt>) as if it were a container of the pointed-to type
+(e.g. <tt class="docutils literal"><span class="pre">list&lt;foo&gt;</span></tt>).  <tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> depends on two
+auxiliary traits, <tt class="docutils literal"><span class="pre">pointee</span></tt> and <tt class="docutils literal"><span class="pre">indirect_reference</span></tt>, to
+provide support for underlying iterators whose <tt class="docutils literal"><span class="pre">value_type</span></tt> is
+not an iterator.</td>
 </tr>
 </tbody>
 </table>
-<p>The indirect iterator adapts an iterator by applying an <em>extra</em>
-dereference inside of <tt class="literal"><span class="pre">operator*()</span></tt>. For example, this iterator
-adaptor makes it possible to view a container of pointers
-(e.g. <tt class="literal"><span class="pre">list&lt;foo*&gt;</span></tt>) as if it were a container of the pointed-to type
-(e.g. <tt class="literal"><span class="pre">list&lt;foo&gt;</span></tt>) .</p>
-<!-- At some point we should add the capability to handle
-iterators over smart pointers, which the impl handles. -JGS -->
 <div class="contents topic" id="table-of-contents">
-<p class="topic-title"><a name="table-of-contents">Table of Contents</a></p>
+<p class="topic-title first">Table of Contents</p>
 <ul class="simple">
-<li><a class="reference" href="#indirect-iterator-requirements" id="id1" name="id1"><tt class="literal"><span class="pre">indirect_iterator</span></tt> requirements</a></li>
-<li><a class="reference" href="#indirect-iterator-operations" id="id2" name="id2"><tt class="literal"><span class="pre">indirect_iterator</span></tt> operations</a></li>
+<li><a class="reference internal" href="#indirect-iterator-synopsis" id="id2"><tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> synopsis</a></li>
+<li><a class="reference internal" href="#indirect-iterator-requirements" id="id3"><tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> requirements</a></li>
+<li><a class="reference internal" href="#indirect-iterator-models" id="id4"><tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> models</a></li>
+<li><a class="reference internal" href="#indirect-iterator-operations" id="id5"><tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> operations</a></li>
+<li><a class="reference internal" href="#example" id="id6">Example</a></li>
 </ul>
 </div>
+<div class="section" id="indirect-iterator-synopsis">
+<h1><a class="toc-backref" href="#id2"><tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> synopsis</a></h1>
+<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
+<!-- Software License, Version 1.0. (See accompanying -->
+<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
 <pre class="literal-block">
 template &lt;
     class Iterator
   , class Value = use_default
-  , unsigned Access  = use_default_access
-  , class Traversal  = use_default
+  , class CategoryOrTraversal = use_default
   , class Reference = use_default
   , class Difference = use_default
 &gt;
 class indirect_iterator
-  : public iterator_adaptor&lt;/* see discussion */&gt;
 {
-    friend class iterator_core_access;
  public:
+    typedef /* see below */ value_type;
+    typedef /* see below */ reference;
+    typedef /* see below */ pointer;
+    typedef /* see below */ difference_type;
+    typedef /* see below */ iterator_category;
+
     indirect_iterator();
     indirect_iterator(Iterator x);
+
     template &lt;
-        class Iterator2, class Value2, unsigned Access2, class Traversal2
+        class Iterator2, class Value2, class Category2
       , class Reference2, class Difference2
     &gt;
     indirect_iterator(
         indirect_iterator&lt;
-             Iterator2, Value2, Access2, Traversal2, Reference2, Difference2
+             Iterator2, Value2, Category2, Reference2, Difference2
         &gt; const&amp; y
       , typename enable_if_convertible&lt;Iterator2, Iterator&gt;::type* = 0 // exposition
     );
-private: // as-if specification
-    typename indirect_iterator::reference dereference() const
-    {
-        return **this-&gt;base();
-    }
+
+    Iterator const&amp; base() const;
+    reference operator*() const;
+    indirect_iterator&amp; operator++();
+    indirect_iterator&amp; operator--();
+private:
+   Iterator m_iterator; // exposition
 };
 </pre>
-<div class="section" id="indirect-iterator-requirements">
-<h1><a class="toc-backref" href="#id1" name="indirect-iterator-requirements"><tt class="literal"><span class="pre">indirect_iterator</span></tt> requirements</a></h1>
-<p>The <tt class="literal"><span class="pre">value_type</span></tt> of the <tt class="literal"><span class="pre">Iterator</span></tt> template parameter should
-itself be dereferenceable. The return type of the <tt class="literal"><span class="pre">operator*</span></tt> for
-the <tt class="literal"><span class="pre">value_type</span></tt> must be the same type as the <tt class="literal"><span class="pre">Reference</span></tt> template
-parameter. The <tt class="literal"><span class="pre">Value</span></tt> template parameter will be the <tt class="literal"><span class="pre">value_type</span></tt>
-for the <tt class="literal"><span class="pre">indirect_iterator</span></tt>, unless <tt class="literal"><span class="pre">Value</span></tt> is const. If <tt class="literal"><span class="pre">Value</span></tt>
-is <tt class="literal"><span class="pre">const</span> <span class="pre">X</span></tt>, then <tt class="literal"><span class="pre">value_type</span></tt> will be <em>non-</em> <tt class="literal"><span class="pre">const</span> <span class="pre">X</span></tt>.  The
-default for <tt class="literal"><span class="pre">Value</span></tt> is</p>
+<p>The member types of <tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> are defined according to
+the following pseudo-code, where <tt class="docutils literal"><span class="pre">V</span></tt> is
+<tt class="docutils literal"><span class="pre">iterator_traits&lt;Iterator&gt;::value_type</span></tt></p>
 <pre class="literal-block">
-iterator_traits&lt; iterator_traits&lt;Iterator&gt;::value_type &gt;::value_type
+if (Value is use_default) then
+    typedef remove_const&lt;pointee&lt;V&gt;::type&gt;::type value_type;
+else
+    typedef remove_const&lt;Value&gt;::type value_type;
+
+if (Reference is use_default) then
+    if (Value is use_default) then
+        typedef indirect_reference&lt;V&gt;::type reference;
+    else
+        typedef Value&amp; reference;
+else
+    typedef Reference reference;
+
+if (Value is use_default) then
+    typedef pointee&lt;V&gt;::type* pointer;
+else
+    typedef Value* pointer;
+
+if (Difference is use_default)
+    typedef iterator_traits&lt;Iterator&gt;::difference_type difference_type;
+else
+    typedef Difference difference_type;
+
+if (CategoryOrTraversal is use_default)
+    typedef <em>iterator-category</em> (
+        iterator_traversal&lt;Iterator&gt;::type,``reference``,``value_type``
+    ) iterator_category;
+else
+    typedef <em>iterator-category</em> (
+        CategoryOrTraversal,``reference``,``value_type``
+    ) iterator_category;
 </pre>
-<p>If the default is used for <tt class="literal"><span class="pre">Value</span></tt>, then there must be a valid
-specialization of <tt class="literal"><span class="pre">iterator_traits</span></tt> for the value type of the base
-iterator.</p>
-<p>The <tt class="literal"><span class="pre">Reference</span></tt> parameter will be the <tt class="literal"><span class="pre">reference</span></tt> type of the
-<tt class="literal"><span class="pre">indirect_iterator</span></tt>. The default is <tt class="literal"><span class="pre">Value&amp;</span></tt>.</p>
-<p>The <tt class="literal"><span class="pre">Access</span></tt> and <tt class="literal"><span class="pre">Traversal</span></tt> parameters are passed unchanged to
-the corresponding parameters of the <tt class="literal"><span class="pre">iterator_adaptor</span></tt> base
-class, and  the <tt class="literal"><span class="pre">Iterator</span></tt> parameter is passed unchanged as the
-<tt class="literal"><span class="pre">Base</span></tt> parameter to the <tt class="literal"><span class="pre">iterator_adaptor</span></tt> base class.</p>
-<p>The indirect iterator will model the most refined standard traversal
-concept that is modeled by the <tt class="literal"><span class="pre">Iterator</span></tt> type.  The indirect
-iterator will model the most refined standard access concept that is
-modeled by the value type of <tt class="literal"><span class="pre">Iterator</span></tt>.</p>
+</div>
+<div class="section" id="indirect-iterator-requirements">
+<h1><a class="toc-backref" href="#id3"><tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> requirements</a></h1>
+<p>The expression <tt class="docutils literal"><span class="pre">*v</span></tt>, where <tt class="docutils literal"><span class="pre">v</span></tt> is an object of
+<tt class="docutils literal"><span class="pre">iterator_traits&lt;Iterator&gt;::value_type</span></tt>, shall be valid
+expression and convertible to <tt class="docutils literal"><span class="pre">reference</span></tt>.  <tt class="docutils literal"><span class="pre">Iterator</span></tt> shall
+model the traversal concept indicated by <tt class="docutils literal"><span class="pre">iterator_category</span></tt>.
+<tt class="docutils literal"><span class="pre">Value</span></tt>, <tt class="docutils literal"><span class="pre">Reference</span></tt>, and <tt class="docutils literal"><span class="pre">Difference</span></tt> shall be chosen so
+that <tt class="docutils literal"><span class="pre">value_type</span></tt>, <tt class="docutils literal"><span class="pre">reference</span></tt>, and <tt class="docutils literal"><span class="pre">difference_type</span></tt> meet
+the requirements indicated by <tt class="docutils literal"><span class="pre">iterator_category</span></tt>.</p>
+<p>[Note: there are further requirements on the
+<tt class="docutils literal"><span class="pre">iterator_traits&lt;Iterator&gt;::value_type</span></tt> if the <tt class="docutils literal"><span class="pre">Value</span></tt>
+parameter is not <tt class="docutils literal"><span class="pre">use_default</span></tt>, as implied by the algorithm for
+deducing the default for the <tt class="docutils literal"><span class="pre">value_type</span></tt> member.]</p>
+</div>
+<div class="section" id="indirect-iterator-models">
+<h1><a class="toc-backref" href="#id4"><tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> models</a></h1>
+<p>In addition to the concepts indicated by <tt class="docutils literal"><span class="pre">iterator_category</span></tt>
+and by <tt class="docutils literal"><span class="pre">iterator_traversal&lt;indirect_iterator&gt;::type</span></tt>, a
+specialization of <tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> models the following
+concepts, Where <tt class="docutils literal"><span class="pre">v</span></tt> is an object of
+<tt class="docutils literal"><span class="pre">iterator_traits&lt;Iterator&gt;::value_type</span></tt>:</p>
+<blockquote>
+<ul class="simple">
+<li>Readable Iterator if <tt class="docutils literal"><span class="pre">reference(*v)</span></tt> is convertible to
+<tt class="docutils literal"><span class="pre">value_type</span></tt>.</li>
+<li>Writable Iterator if <tt class="docutils literal"><span class="pre">reference(*v)</span> <span class="pre">=</span> <span class="pre">t</span></tt> is a valid
+expression (where <tt class="docutils literal"><span class="pre">t</span></tt> is an object of type
+<tt class="docutils literal"><span class="pre">indirect_iterator::value_type</span></tt>)</li>
+<li>Lvalue Iterator if <tt class="docutils literal"><span class="pre">reference</span></tt> is a reference type.</li>
+</ul>
+</blockquote>
+<p><tt class="docutils literal"><span class="pre">indirect_iterator&lt;X,V1,C1,R1,D1&gt;</span></tt> is interoperable with
+<tt class="docutils literal"><span class="pre">indirect_iterator&lt;Y,V2,C2,R2,D2&gt;</span></tt> if and only if <tt class="docutils literal"><span class="pre">X</span></tt> is
+interoperable with <tt class="docutils literal"><span class="pre">Y</span></tt>.</p>
 </div>
 <div class="section" id="indirect-iterator-operations">
-<h1><a class="toc-backref" href="#id2" name="indirect-iterator-operations"><tt class="literal"><span class="pre">indirect_iterator</span></tt> operations</a></h1>
-<p><tt class="literal"><span class="pre">indirect_iterator();</span></tt></p>
-<table class="field-list" frame="void" rules="none">
+<h1><a class="toc-backref" href="#id5"><tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> operations</a></h1>
+<p>In addition to the operations required by the concepts described
+above, specializations of <tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> provide the
+following operations.</p>
+<p><tt class="docutils literal"><span class="pre">indirect_iterator();</span></tt></p>
+<table class="docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
-<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="literal"><span class="pre">Iterator</span></tt> must be Default Constructible.</td>
+<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="docutils literal"><span class="pre">Iterator</span></tt> must be Default Constructible.</td>
 </tr>
-<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="literal"><span class="pre">indirect_iterator</span></tt> with
-a default constructed base object.</td>
+<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Constructs an instance of <tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> with
+a default-constructed <tt class="docutils literal"><span class="pre">m_iterator</span></tt>.</td>
 </tr>
 </tbody>
 </table>
-<p><tt class="literal"><span class="pre">indirect_iterator(Iterator</span> <span class="pre">x);</span></tt></p>
-<table class="field-list" frame="void" rules="none">
+<p><tt class="docutils literal"><span class="pre">indirect_iterator(Iterator</span> <span class="pre">x);</span></tt></p>
+<table class="docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
-<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="literal"><span class="pre">indirect_iterator</span></tt> with
-the <tt class="literal"><span class="pre">iterator_adaptor</span></tt> subobject copy constructed from <tt class="literal"><span class="pre">x</span></tt>.</td>
+<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Constructs an instance of <tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> with
+<tt class="docutils literal"><span class="pre">m_iterator</span></tt> copy constructed from <tt class="docutils literal"><span class="pre">x</span></tt>.</td>
 </tr>
 </tbody>
 </table>
@@ -340,23 +218,128 @@ indirect_iterator(
   , typename enable_if_convertible&lt;Iterator2, Iterator&gt;::type* = 0 // exposition
 );
 </pre>
-<table class="field-list" frame="void" rules="none">
+<table class="docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
-<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="literal"><span class="pre">Iterator2</span></tt> is implicitly convertible to <tt class="literal"><span class="pre">Iterator</span></tt>.</td>
+<tr class="field"><th class="field-name">Requires:</th><td class="field-body"><tt class="docutils literal"><span class="pre">Iterator2</span></tt> is implicitly convertible to <tt class="docutils literal"><span class="pre">Iterator</span></tt>.</td>
 </tr>
-<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="literal"><span class="pre">indirect_iterator</span></tt> that is a copy of <tt class="literal"><span class="pre">y</span></tt>.</td>
+<tr class="field"><th class="field-name">Effects:</th><td class="field-body">Constructs an instance of <tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> whose
+<tt class="docutils literal"><span class="pre">m_iterator</span></tt> subobject is constructed from <tt class="docutils literal"><span class="pre">y.base()</span></tt>.</td>
 </tr>
 </tbody>
 </table>
+<p><tt class="docutils literal"><span class="pre">Iterator</span> <span class="pre">const&amp;</span> <span class="pre">base()</span> <span class="pre">const;</span></tt></p>
+<table class="docutils field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">m_iterator</span></tt></td>
+</tr>
+</tbody>
+</table>
+<p><tt class="docutils literal"><span class="pre">reference</span> <span class="pre">operator*()</span> <span class="pre">const;</span></tt></p>
+<table class="docutils field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">**m_iterator</span></tt></td>
+</tr>
+</tbody>
+</table>
+<p><tt class="docutils literal"><span class="pre">indirect_iterator&amp;</span> <span class="pre">operator++();</span></tt></p>
+<table class="docutils field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><tt class="docutils literal"><span class="pre">++m_iterator</span></tt></td>
+</tr>
+<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">*this</span></tt></td>
+</tr>
+</tbody>
+</table>
+<p><tt class="docutils literal"><span class="pre">indirect_iterator&amp;</span> <span class="pre">operator--();</span></tt></p>
+<table class="docutils field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><tt class="docutils literal"><span class="pre">--m_iterator</span></tt></td>
+</tr>
+<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">*this</span></tt></td>
+</tr>
+</tbody>
+</table>
+<!-- Copyright David Abrahams 2006. Distributed under the Boost -->
+<!-- Software License, Version 1.0. (See accompanying -->
+<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
+</div>
+<div class="section" id="example">
+<h1><a class="toc-backref" href="#id6">Example</a></h1>
+<p>This example prints an array of characters, using
+<tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> to access the array of characters through an
+array of pointers. Next <tt class="docutils literal"><span class="pre">indirect_iterator</span></tt> is used with the
+<tt class="docutils literal"><span class="pre">transform</span></tt> algorithm to copy the characters (incremented by one) to
+another array. A constant indirect iterator is used for the source and
+a mutable indirect iterator is used for the destination. The last part
+of the example prints the original array of characters, but this time
+using the <tt class="docutils literal"><span class="pre">make_indirect_iterator</span></tt> helper function.</p>
+<pre class="literal-block">
+char characters[] = &quot;abcdefg&quot;;
+const int N = sizeof(characters)/sizeof(char) - 1; // -1 since characters has a null char
+char* pointers_to_chars[N];                        // at the end.
+for (int i = 0; i &lt; N; ++i)
+  pointers_to_chars[i] = &amp;characters[i];
+
+// Example of using indirect_iterator
+
+boost::indirect_iterator&lt;char**, char&gt;
+  indirect_first(pointers_to_chars), indirect_last(pointers_to_chars + N);
+
+std::copy(indirect_first, indirect_last, std::ostream_iterator&lt;char&gt;(std::cout, &quot;,&quot;));
+std::cout &lt;&lt; std::endl;
+
+
+// Example of making mutable and constant indirect iterators
+
+char mutable_characters[N];
+char* pointers_to_mutable_chars[N];
+for (int j = 0; j &lt; N; ++j)
+  pointers_to_mutable_chars[j] = &amp;mutable_characters[j];
+
+boost::indirect_iterator&lt;char* const*&gt; mutable_indirect_first(pointers_to_mutable_chars),
+  mutable_indirect_last(pointers_to_mutable_chars + N);
+boost::indirect_iterator&lt;char* const*, char const&gt; const_indirect_first(pointers_to_chars),
+  const_indirect_last(pointers_to_chars + N);
+
+std::transform(const_indirect_first, const_indirect_last,
+               mutable_indirect_first, std::bind1st(std::plus&lt;char&gt;(), 1));
+
+std::copy(mutable_indirect_first, mutable_indirect_last,
+          std::ostream_iterator&lt;char&gt;(std::cout, &quot;,&quot;));
+std::cout &lt;&lt; std::endl;
+
+
+// Example of using make_indirect_iterator()
+
+std::copy(boost::make_indirect_iterator(pointers_to_chars),
+          boost::make_indirect_iterator(pointers_to_chars + N),
+          std::ostream_iterator&lt;char&gt;(std::cout, &quot;,&quot;));
+std::cout &lt;&lt; std::endl;
+</pre>
+<p>The output is:</p>
+<pre class="literal-block">
+a,b,c,d,e,f,g,
+b,c,d,e,f,g,h,
+a,b,c,d,e,f,g,
+</pre>
+<p>The source code for this example can be found <a class="reference external" href="../example/indirect_iterator_example.cpp">here</a>.</p>
 </div>
 </div>
-<hr class="footer" />
 <div class="footer">
-<a class="reference" href="indirect_iterator.rst">View document source</a>.
-Generated on: 2003-11-24 05:00 UTC.
-Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
+<hr class="footer" />
+<a class="reference external" href="indirect_iterator.rst">View document source</a>.
+Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
+
 </div>
 </body>
 </html>

doc/indirect_iterator.rst

@@ -1,3 +1,7 @@
+.. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
 +++++++++++++++++++
  Indirect Iterator
 +++++++++++++++++++
@@ -8,7 +12,7 @@
                Lab`_, University of Hanover `Institute for Transport
                Railway Operation and Construction`_
 :date: $Date$
-:copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved
+:copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. 
 
 .. _`Boost Consulting`: http://www.boost-consulting.com
 .. _`Open Systems Lab`: http://www.osl.iu.edu
@@ -16,8 +20,15 @@
 
 :abstract:
 
-.. include:: indirect_iterator_abstract.rst
+  .. include:: indirect_iterator_abstract.rst
 
 .. contents:: Table of Contents
 
+``indirect_iterator`` synopsis
+..............................
+
 .. include:: indirect_iterator_ref.rst
+.. include:: indirect_iterator_eg.rst
+
+.. _iterator-category: iterator_facade.html#iterator-category
+.. |iterator-category| replace:: *iterator-category*

doc/indirect_iterator_abstract.rst

@@ -1,8 +1,15 @@
-The indirect iterator adapts an iterator by applying an *extra*
-dereference inside of ``operator*()``. For example, this iterator
-adaptor makes it possible to view a container of pointers
-(e.g. ``list<foo*>``) as if it were a container of the pointed-to type
-(e.g. ``list<foo>``) .
+.. Copyright David Abrahams 2006. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+``indirect_iterator`` adapts an iterator by applying an
+*extra* dereference inside of ``operator*()``. For example, this
+iterator adaptor makes it possible to view a container of pointers
+(e.g. ``list<foo*>``) as if it were a container of the pointed-to type
+(e.g. ``list<foo>``).  ``indirect_iterator`` depends on two
+auxiliary traits, ``pointee`` and ``indirect_reference``, to
+provide support for underlying iterators whose ``value_type`` is
+not an iterator.
+
+
 
-.. At some point we should add the capability to handle
-   iterators over smart pointers, which the impl handles. -JGS

doc/indirect_iterator_eg.rst

@@ -0,0 +1,73 @@
+.. Copyright David Abrahams 2006. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+Example
+.......
+
+This example prints an array of characters, using
+``indirect_iterator`` to access the array of characters through an
+array of pointers. Next ``indirect_iterator`` is used with the
+``transform`` algorithm to copy the characters (incremented by one) to
+another array. A constant indirect iterator is used for the source and
+a mutable indirect iterator is used for the destination. The last part
+of the example prints the original array of characters, but this time
+using the ``make_indirect_iterator`` helper function.
+
+
+::
+
+    char characters[] = "abcdefg";
+    const int N = sizeof(characters)/sizeof(char) - 1; // -1 since characters has a null char
+    char* pointers_to_chars[N];                        // at the end.
+    for (int i = 0; i < N; ++i)
+      pointers_to_chars[i] = &characters[i];
+
+    // Example of using indirect_iterator
+
+    boost::indirect_iterator<char**, char>
+      indirect_first(pointers_to_chars), indirect_last(pointers_to_chars + N);
+
+    std::copy(indirect_first, indirect_last, std::ostream_iterator<char>(std::cout, ","));
+    std::cout << std::endl;
+
+
+    // Example of making mutable and constant indirect iterators
+
+    char mutable_characters[N];
+    char* pointers_to_mutable_chars[N];
+    for (int j = 0; j < N; ++j)
+      pointers_to_mutable_chars[j] = &mutable_characters[j];
+
+    boost::indirect_iterator<char* const*> mutable_indirect_first(pointers_to_mutable_chars),
+      mutable_indirect_last(pointers_to_mutable_chars + N);
+    boost::indirect_iterator<char* const*, char const> const_indirect_first(pointers_to_chars),
+      const_indirect_last(pointers_to_chars + N);
+
+    std::transform(const_indirect_first, const_indirect_last,
+		   mutable_indirect_first, std::bind1st(std::plus<char>(), 1));
+
+    std::copy(mutable_indirect_first, mutable_indirect_last,
+	      std::ostream_iterator<char>(std::cout, ","));
+    std::cout << std::endl;
+
+
+    // Example of using make_indirect_iterator()
+
+    std::copy(boost::make_indirect_iterator(pointers_to_chars), 
+	      boost::make_indirect_iterator(pointers_to_chars + N),
+	      std::ostream_iterator<char>(std::cout, ","));
+    std::cout << std::endl;
+
+
+The output is::
+
+    a,b,c,d,e,f,g,
+    b,c,d,e,f,g,h,
+    a,b,c,d,e,f,g,
+
+
+The source code for this example can be found `here`__.
+
+__ ../example/indirect_iterator_example.cpp
+

doc/indirect_iterator_ref.rst

@@ -1,3 +1,7 @@
+.. Copyright David Abrahams 2006. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
 ::
 
   template <
@@ -8,17 +12,14 @@
     , class Difference = use_default
   >
   class indirect_iterator
-    : public iterator_adaptor<
-                 indirect_iterator<Iterator, Value, Access, Traversal, 
-                                   Reference, Difference>,
-                 Iterator,
-                 /* Value = see below */,
-                 CategoryOrTraversal,
-                 Reference,
-                 Difference>
   {
-      friend class iterator_core_access;
    public:
+      typedef /* see below */ value_type;
+      typedef /* see below */ reference;
+      typedef /* see below */ pointer;
+      typedef /* see below */ difference_type;
+      typedef /* see below */ iterator_category;
+
       indirect_iterator();
       indirect_iterator(Iterator x);
 
@@ -32,80 +33,113 @@
           > const& y
         , typename enable_if_convertible<Iterator2, Iterator>::type* = 0 // exposition
       );
-  private: // as-if specification
-      typename indirect_iterator::reference dereference() const
-      {
-          return **this->base();
-      }
-  };
 
-  template <class Dereferenceable>
-  struct referent {
-    typedef /* see below */ type;
+      Iterator const& base() const;
+      reference operator*() const;
+      indirect_iterator& operator++();
+      indirect_iterator& operator--();
+  private:
+     Iterator m_iterator; // exposition
   };
 
 
-If ``Value`` is not ``use_default`` then the the argument for the
-``iterator_adaptor`` base class' ``Value`` parameter is ``Value`` with
-cv-qualifiers removed. If ``Value`` is ``use_default``, then the
-argument for the ``iterator_adaptor`` base class' ``Value`` parameter
-is computed as follows. We use the abbreviation
-``V=iterator_traits<Iterator>::value_type`` and ``v`` is an object of
-type ``V``.::
+The member types of ``indirect_iterator`` are defined according to
+the following pseudo-code, where ``V`` is
+``iterator_traits<Iterator>::value_type``
 
-    if (*v returns a constant lvalue or an rvalue) then
-        referent<V>::type
-    else
-        add_const<referent<V>::type>::type
+.. parsed-literal::
 
-The algorithm for the ``type`` member of ``referent`` traits class is
-as follows::
+  if (Value is use_default) then
+      typedef remove_const<pointee<V>::type>::type value_type;
+  else
+      typedef remove_const<Value>::type value_type;
 
-    if (Dereferenceable is a class and has member element_type)
-        Dereferenceable::element_type
-    else
-        iterator_traits<Dereferenceable>::value_type
+  if (Reference is use_default) then
+      if (Value is use_default) then
+          typedef indirect_reference<V>::type reference;
+      else
+          typedef Value& reference;
+  else
+      typedef Reference reference;
+
+  if (Value is use_default) then 
+      typedef pointee<V>::type\* pointer;
+  else 
+      typedef Value\* pointer;
+
+  if (Difference is use_default)
+      typedef iterator_traits<Iterator>::difference_type difference_type;
+  else
+      typedef Difference difference_type;
+
+  if (CategoryOrTraversal is use_default)
+      typedef *iterator-category* (
+          iterator_traversal<Iterator>::type,``reference``,``value_type``
+      ) iterator_category;
+  else
+      typedef *iterator-category* (
+          CategoryOrTraversal,``reference``,``value_type``
+      ) iterator_category;
 
 
 ``indirect_iterator`` requirements
 ..................................
 
-The ``CategoryOrTraversal`` argument shall be one of the standard
-iterator tags or ``use_default``. If ``CategoryOrTraversal`` is an
-iterator tag, ``indirect_iterator`` satisfies the requirements
-corresponding to the iterator tag.  The template parameter
-``Iterator`` argument shall meet the traversal requirements
-corresponding to the iterator tag and the requirements of Readable
-Iterator.  If ``CategoryOrTraversal`` is ``use_default`` then
-``indirect_iterator`` satisfies the requirements of the most refined
-standard traversal concept that is satisfied by the ``Iterator``
-argument. In this case the ``Iterator`` argument shall meet the
-requirements of Readable Iterator.
+The expression ``*v``, where ``v`` is an object of
+``iterator_traits<Iterator>::value_type``, shall be valid
+expression and convertible to ``reference``.  ``Iterator`` shall
+model the traversal concept indicated by ``iterator_category``.
+``Value``, ``Reference``, and ``Difference`` shall be chosen so
+that ``value_type``, ``reference``, and ``difference_type`` meet
+the requirements indicated by ``iterator_category``.
 
-The expression ``*v``, where ``v`` is an object of type
-``iterator_traits<Iterator>::value_type``, must be a valid expression
-and must be convertible to ``iterator_adaptor::reference`` Also, there
-are further requirements on the
-``iterator_traits<Iterator>::value_type`` if the ``Value`` parameter
-is not ``use_default``, as implied by the algorithm for deducing the
-default.
+[Note: there are further requirements on the
+``iterator_traits<Iterator>::value_type`` if the ``Value``
+parameter is not ``use_default``, as implied by the algorithm for
+deducing the default for the ``value_type`` member.]
 
+``indirect_iterator`` models
+............................
+
+In addition to the concepts indicated by ``iterator_category``
+and by ``iterator_traversal<indirect_iterator>::type``, a
+specialization of ``indirect_iterator`` models the following
+concepts, Where ``v`` is an object of
+``iterator_traits<Iterator>::value_type``:
+
+  * Readable Iterator if ``reference(*v)`` is convertible to
+    ``value_type``.
+   
+  * Writable Iterator if ``reference(*v) = t`` is a valid
+    expression (where ``t`` is an object of type
+    ``indirect_iterator::value_type``)
+
+  * Lvalue Iterator if ``reference`` is a reference type.
+
+``indirect_iterator<X,V1,C1,R1,D1>`` is interoperable with
+``indirect_iterator<Y,V2,C2,R2,D2>`` if and only if ``X`` is
+interoperable with ``Y``.
 
 
 ``indirect_iterator`` operations
 ................................
 
+In addition to the operations required by the concepts described
+above, specializations of ``indirect_iterator`` provide the
+following operations.
+
+
 ``indirect_iterator();``
 
 :Requires: ``Iterator`` must be Default Constructible.
-:Returns: An instance of ``indirect_iterator`` with 
-   a default-constructed ``iterator_adaptor`` subobject.
+:Effects: Constructs an instance of ``indirect_iterator`` with 
+   a default-constructed ``m_iterator``.
 
 
 ``indirect_iterator(Iterator x);``
 
-:Returns: An instance of ``indirect_iterator`` with
-    the ``iterator_adaptor`` subobject copy constructed from ``x``.
+:Effects: Constructs an instance of ``indirect_iterator`` with
+    ``m_iterator`` copy constructed from ``x``.
 
 ::
 
@@ -121,7 +155,27 @@ default.
   );
 
 :Requires: ``Iterator2`` is implicitly convertible to ``Iterator``.
-:Returns: An instance of ``indirect_iterator`` whose 
-    ``iterator_adaptor`` subobject is constructed from ``y.base()``.
+:Effects: Constructs an instance of ``indirect_iterator`` whose 
+    ``m_iterator`` subobject is constructed from ``y.base()``.
 
 
+``Iterator const& base() const;``
+
+:Returns: ``m_iterator``
+
+
+``reference operator*() const;``
+
+:Returns:  ``**m_iterator``
+
+
+``indirect_iterator& operator++();``
+
+:Effects: ``++m_iterator``
+:Returns: ``*this``
+
+
+``indirect_iterator& operator--();``
+
+:Effects: ``--m_iterator``
+:Returns: ``*this``

doc/indirect_reference_ref.rst

@@ -0,0 +1,29 @@
+.. Copyright David Abrahams 2004. Use, modification and distribution is
+.. subject to the Boost Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+::
+
+  template <class Dereferenceable>
+  struct indirect_reference
+  {
+      typedef /* see below */ type;
+  };
+
+:Requires: For an object ``x`` of type ``Dereferenceable``, ``*x``
+  is well-formed.  If ``++x`` is ill-formed it shall neither be
+  ambiguous nor shall it violate access control, and
+  ``pointee<Dereferenceable>::type&`` shall be well-formed.
+  Otherwise ``iterator_traits<Dereferenceable>::reference`` shall
+  be well formed.  [Note: These requirements need not apply to
+  explicit or partial specializations of ``indirect_reference``]
+
+``type`` is determined according to the following algorithm, where
+``x`` is an object of type ``Dereferenceable``::
+
+  if ( ++x is ill-formed )
+      return ``pointee<Dereferenceable>::type&``
+  else
+      std::iterator_traits<Dereferenceable>::reference
+
+  

doc/interoperability-revisited.rst

@@ -0,0 +1,238 @@
+++++++++++++++++++++++++++++
+ Interoperability Revisited 
+++++++++++++++++++++++++++++
+
+:date: $Date$
+:copyright: Copyright Thomas Witt 2004.
+
+.. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+Problem
+=======
+
+The current iterator_facade specification makes it unneccessarily tedious to
+implement interoperable iterators.
+
+In the following text a simplified example of the current iterator_facade specification is used to
+illustrate the problem.
+
+In the current specification binary operators are implemented in the following way::
+
+  template <class Derived>
+  struct Facade
+  {
+  };
+
+  template <class T1, T2>
+  struct is_interoperable :
+    or_< 
+         is_convertible<T1, T2>
+       , is_convertible<T2, T1>
+    > 
+  {};
+
+  template<
+      class Derived1
+    , class Derived2
+  >
+  enable_if<is_interoperable<Derived1, Derived2>, bool> operator==(
+      Derived1 const& lhs
+    , Derived2 const& rhs
+  )
+  {
+    return static_cast<Derived1 const&>(lhs).equal_to(static_cast<Derived2 const&(rhs));
+  } 
+
+The problem with this is that operator== always forwards to Derived1::equal_to. The net effect is that the
+following "obvious" implementation of to interoperable types does
+not quite work. ::
+
+  struct Mutable : Facade<Mutable>
+  {
+    bool equal_to(Mutable const&);  
+  };
+
+  struct Constant : Facade<Constant>
+  {
+    Constant();
+    Constant(Constant const&);
+    Constant(Mutable const&);
+
+    ...
+
+    bool equal_to(Constant const&);  
+  };
+
+  Constant c;
+  Mutable  m;
+
+  c == m; // ok, dispatched to Constant::equal_to
+  m == c; // !! error, dispatched to Mutable::equal_to
+
+  Instead the following "slightly" more complicated implementation is necessary
+
+  struct Mutable : Facade<Mutable>
+  {
+    template <class T>
+    enable_if<is_convertible<Mutable, T> || is_convertible<T, Mutable>, bool>::type equal_to(T const&);  
+  };
+
+  struct Constant : Tag<Constant>
+  {
+    Constant();
+    Constant(Constant const&);
+    Constant(Mutable const&);
+
+    template <class T>
+    enable_if<is_convertible<Constant, T> || is_convertible<T, Constant>, bool>::type equal_to(T const&);  
+  };
+
+Beside the fact that the code is significantly more complex to understand and to teach there is
+a major design problem lurking here. Note that in both types equal_to is a function template with 
+an unconstrained argument T. This is necessary so that further types can be made interoperable with
+Mutable or Constant. Would Mutable be defined as   ::
+
+  struct Mutable : Facade<Mutable>
+  {
+    bool equal_to(Mutable const&);  
+    bool equal_to(Constant const&);  
+  };
+
+Constant and Mutable would still be interoperable but no further interoperable could be added 
+without changing Mutable. Even if this would be considered acceptable the current specification forces
+a two way dependency between interoperable types. Note in the templated equal_to case this dependency 
+is implicitly created when specializing equal_to.
+
+Solution
+========
+
+The two way dependency can be avoided by enabling type conversion in the binary operator
+implementation. Note that this is the usual way interoperability betwween types is achieved
+for binary operators and one reason why binary operators are usually implemented as non-members.
+
+A simple implementation of this strategy would look like this ::
+
+  template<
+      class T1
+    , class T2
+  >
+  struct interoperable_base :
+      if_< 
+          is_convertible<
+              T2
+            , T1
+          >
+        , T1
+        , T2>
+  {};
+
+
+  template<
+      class Derived1
+    , class Derived2
+  >
+  enable_if<is_interoperable<Derived1, Derived2>, bool> operator==(
+      Derived1 const& lhs
+    , Derived2 const& rhs
+  )
+  {
+    typedef interoperable_base<
+                Derived1
+              , Derived2
+            >::type Base;
+
+    return static_cast<Base const&>(lhs).equal_to(static_cast<Derived2 const&(rhs));
+  } 
+
+This way our original simple and "obvious" implementation would
+work again. ::
+
+  c == m; // ok, dispatched to Constant::equal_to
+  m == c; // ok, dispatched to Constant::equal_to, m converted to Constant
+
+The backdraw of this approach is that a possibly costly conversion of iterator objects
+is forced on the user even in cases where direct comparison could be implemented
+in a much more efficient way. This problem arises especially for iterator_adaptor
+specializations and can be significantly slow down the iteration over ranges. Given the fact
+that iteration is a very basic operation this possible performance degradation is not 
+acceptable.
+
+Luckily whe can have our cake and eat it by a slightly more clever implementation of the binary 
+operators. ::
+
+  template<
+      class Derived1
+    , class Derived2
+  >
+  enable_if<is_convertible<Derived2, Derived1>, bool> operator==(
+      Derived1 const& lhs
+    , Derived2 const& rhs
+  )
+  {
+    return static_cast<Derived1 const&>(lhs).equal_to(static_cast<Derived2 const&(rhs));
+  } 
+
+  template<
+      class Derived1
+    , class Derived2
+  >
+  enable_if<is_convertible<Derived1, Derived2>, bool> operator==(
+      Derived1 const& lhs
+    , Derived2 const& rhs
+  )
+  {
+    return static_cast<Derived2 const&>(rhs).equal_to(static_cast<Derived1 const&(lhs));
+  } 
+
+Given our simple and obvious definition of Mutable and Constant nothing has changed yet. ::
+
+  c == m; // ok, dispatched to Constant::equal_to, m converted to Constant
+  m == c; // ok, dispatched to Constant::equal_to, m converted to Constant
+
+But now the user can avoid the type conversion by supplying the
+appropriate overload in Constant :: 
+
+  struct Constant : Facade<Constant>
+  {
+    Constant();
+    Constant(Constant const&);
+    Constant(Mutable const&);
+
+    ...
+
+    bool equal_to(Constant const&);  
+    bool equal_to(Mutable const&);  
+  };
+
+  c == m; // ok, dispatched to Constant::equal_to(Mutable const&), no conversion
+  m == c; // ok, dispatched to Constant::equal_to(Mutable const&), no conversion
+
+This definition of operator== introduces a possible ambiguity when both types are convertible
+to each other. I don't think this is a problem as this behaviour is the same with concrete types.
+I.e.  ::
+
+  struct A {};
+
+  bool operator==(A, A);
+
+  struct B { B(A); }; 
+
+  bool operator==(B, B);
+
+  A a;
+  B b(a);
+
+  a == b; // error, ambiguous overload
+
+Effect
+======
+
+Iterator implementations using iterator_facade look exactly as if they were
+"hand-implemented" (I am working on better wording).
+
+a) Less burden for the user
+
+b) The definition (standardese) of specialized adpters might be easier 
+   (This has to be proved yet)

doc/issues.html

@@ -1,165 +0,0 @@
-<?xml version="1.0" encoding="utf-8" ?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<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.2.8: http://docutils.sourceforge.net/" />
-<title>Problem with is_writable and is_swappable in N1550</title>
-<link rel="stylesheet" href="default.css" type="text/css" />
-</head>
-<body>
-<div class="document" id="problem-with-is-writable-and-is-swappable-in-n1550">
-<h1 class="title">Problem with <tt class="literal"><span class="pre">is_writable</span></tt> and <tt class="literal"><span class="pre">is_swappable</span></tt> in <a class="reference" href="http://www.boost-consulting.com/writing/n1550.html">N1550</a></h1>
-<table class="field-list" frame="void" rules="none">
-<col class="field-name" />
-<col class="field-body" />
-<tbody valign="top">
-<tr class="field"><th class="field-name">Author:</th><td class="field-body">David Abrahams and Jeremy Siek</td>
-</tr>
-<tr class="field"><th class="field-name">Contact:</th><td class="field-body"><a class="reference" href="mailto:dave&#64;boost-consulting.com">dave&#64;boost-consulting.com</a>, <a class="reference" href="mailto:jsiek&#64;osl.iu.edu">jsiek&#64;osl.iu.edu</a></td>
-</tr>
-<tr class="field"><th class="field-name">Organization:</th><td class="field-body"><a class="reference" href="http://www.boost-consulting.com">Boost Consulting</a>, Indiana University Bloomington</td>
-</tr>
-<tr class="field"><th class="field-name">date:</th><td class="field-body">$Date$</td>
-</tr>
-<tr class="field"><th class="field-name">Copyright:</th><td class="field-body">Copyright David Abrahams, Jeremy Siek 2003. Use, modification and
-distribution is subject to the Boost Software License,
-Version 1.0. (See accompanying file LICENSE_1_0.txt or copy
-at <a class="reference" href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>)</td>
-</tr>
-</tbody>
-</table>
-<div class="contents topic" id="table-of-contents">
-<p class="topic-title"><a name="table-of-contents">Table of Contents</a></p>
-<ul class="simple">
-<li><a class="reference" href="#introduction" id="id1" name="id1">Introduction</a></li>
-<li><a class="reference" href="#proposed-resolution" id="id2" name="id2">Proposed Resolution</a></li>
-<li><a class="reference" href="#rationale" id="id3" name="id3">Rationale</a></li>
-</ul>
-</div>
-<div class="section" id="introduction">
-<h1><a class="toc-backref" href="#id1" name="introduction">Introduction</a></h1>
-<p>The <tt class="literal"><span class="pre">is_writable</span></tt> and <tt class="literal"><span class="pre">is_swappable</span></tt> traits classes in <a class="reference" href="http://www.boost-consulting.com/writing/n1550.html">N1550</a>
-provide a mechanism for determining at compile time if an iterator
-type is a model of the new Writable Iterator and Swappable Iterator
-concepts, analogous to <tt class="literal"><span class="pre">iterator_traits&lt;X&gt;::iterator_category</span></tt>
-for the old iterator concepts. For backward compatibility,
-<tt class="literal"><span class="pre">is_writable</span></tt> and <tt class="literal"><span class="pre">is_swappable</span></tt> not only work with new
-iterators, but they also are intended to work for old
-iterators (iterators that meet the requirements for one of the
-iterator concepts in the current standard). In the case of old
-iterators, the writability and swapability is deduced based on the
-<tt class="literal"><span class="pre">iterator_category</span></tt> and also the <tt class="literal"><span class="pre">reference</span></tt> type. The
-specification for this deduction gives false positives for forward
-iterators that have non-assignable value types.</p>
-<p>To review, the part of the <tt class="literal"><span class="pre">is_writable</span></tt> trait definition which
-applies to old iterators is:</p>
-<pre class="literal-block">
-if (cat is convertible to output_iterator_tag)
-    return true;
-else if (cat is convertible to forward_iterator_tag
-         and iterator_traits&lt;Iterator&gt;::reference is a 
-             mutable reference)
-    return true;
-else
-    return false;
-</pre>
-<p>Suppose the <tt class="literal"><span class="pre">value_type</span></tt> of the iterator <tt class="literal"><span class="pre">It</span></tt> has a private
-assignment operator:</p>
-<pre class="literal-block">
-class B {
-public:
-  ...
-private:
-  B&amp; operator=(const B&amp;);
-};
-</pre>
-<p>and suppose the <tt class="literal"><span class="pre">reference</span></tt> type of the iterator is <tt class="literal"><span class="pre">B&amp;</span></tt>.  In
-that case, <tt class="literal"><span class="pre">is_writable&lt;It&gt;::value</span></tt> will be true when in fact
-attempting to write into <tt class="literal"><span class="pre">B</span></tt> will cause an error.</p>
-<p>The same problem applies to <tt class="literal"><span class="pre">is_swappable</span></tt>.</p>
-</div>
-<div class="section" id="proposed-resolution">
-<h1><a class="toc-backref" href="#id2" name="proposed-resolution">Proposed Resolution</a></h1>
-<ol class="arabic">
-<li><p class="first">Remove the <tt class="literal"><span class="pre">is_writable</span></tt> and <tt class="literal"><span class="pre">is_swappable</span></tt> traits, and remove the
-requirements in the Writable Iterator and Swappable Iterator concepts
-that require their models to support these traits.</p>
-</li>
-<li><p class="first">Change the <tt class="literal"><span class="pre">is_readable</span></tt> specification to be:
-<tt class="literal"><span class="pre">is_readable&lt;X&gt;::type</span></tt> is <tt class="literal"><span class="pre">true_type</span></tt> if the
-result type of <tt class="literal"><span class="pre">X::operator*</span></tt> is convertible to
-<tt class="literal"><span class="pre">iterator_traits&lt;X&gt;::value_type</span></tt> and is <tt class="literal"><span class="pre">false_type</span></tt>
-otherwise. Also, <tt class="literal"><span class="pre">is_readable</span></tt> is required to satisfy
-the requirements for the UnaryTypeTrait concept
-(defined in the type traits proposal).</p>
-<p>Remove the requirement for support of the <tt class="literal"><span class="pre">is_readable</span></tt> trait from
-the Readable Iterator concept.</p>
-</li>
-<li><p class="first">Remove the <tt class="literal"><span class="pre">iterator_tag</span></tt> class.</p>
-</li>
-<li><p class="first">Change the specification of <tt class="literal"><span class="pre">traversal_category</span></tt> to:</p>
-<pre class="literal-block">
-traversal-category(Iterator) =
-    let cat = iterator_traits&lt;Iterator&gt;::iterator_category
-    if (cat is convertible to incrementable_iterator_tag)
-      return cat; // Iterator is a new iterator
-    else if (cat is convertible to random_access_iterator_tag)
-        return random_access_traversal_tag;
-    else if (cat is convertible to bidirectional_iterator_tag)
-        return bidirectional_traversal_tag;
-    else if (cat is convertible to forward_iterator_tag)
-        return forward_traversal_tag;
-    else if (cat is convertible to input_iterator_tag)
-        return single_pass_iterator_tag;
-    else if (cat is convertible to output_iterator_tag)
-        return incrementable_iterator_tag;
-    else
-        return null_category_tag;
-</pre>
-</li>
-</ol>
-</div>
-<div class="section" id="rationale">
-<h1><a class="toc-backref" href="#id3" name="rationale">Rationale</a></h1>
-<ol class="arabic simple">
-<li>There are two reasons for removing <tt class="literal"><span class="pre">is_writable</span></tt>
-and <tt class="literal"><span class="pre">is_swappable</span></tt>. The first is that we do not know of
-a way to fix the specification so that it gives the correct
-answer for all iterators. Second, there was only a weak
-motivation for having <tt class="literal"><span class="pre">is_writable</span></tt> and <tt class="literal"><span class="pre">is_swappable</span></tt>
-there in the first place.  The main motivation was simply
-uniformity: we have tags for the old iterator categories
-so we should have tags for the new iterator categories.
-While having tags and the capability to dispatch based
-on the traversal categories is often used, we see
-less of a need for dispatching based on writability
-and swappability, since typically algorithms
-that need these capabilities have no alternative if
-they are not provided.</li>
-<li>We discovered that the <tt class="literal"><span class="pre">is_readable</span></tt> trait can be implemented
-using only the iterator type itself and its <tt class="literal"><span class="pre">value_type</span></tt>.
-Therefore we remove the requirement for <tt class="literal"><span class="pre">is_readable</span></tt> from the
-Readable Iterator concept, and change the definition of
-<tt class="literal"><span class="pre">is_readable</span></tt> so that it works for any iterator type.</li>
-<li>The purpose of the <tt class="literal"><span class="pre">iterator_tag</span></tt> class was to
-bundle the traversal and access category tags
-into the <tt class="literal"><span class="pre">iterator_category</span></tt> typedef.
-With <tt class="literal"><span class="pre">is_writable</span></tt> and <tt class="literal"><span class="pre">is_swappable</span></tt> gone, and
-<tt class="literal"><span class="pre">is_readable</span></tt> no longer in need of special hints,
-there is no reason for iterators to provide
-information about the access capabilities of an iterator.
-Thus there is no need for the <tt class="literal"><span class="pre">iterator_tag</span></tt>. The
-traversal tag can be directly used for the
-<tt class="literal"><span class="pre">iterator_category</span></tt>. If a new iterator is intended to be backward
-compatible with old iterator concepts, a tag type
-that is convertible to both one of the new traversal tags 
-and also to an old iterator tag can be created and use
-for the <tt class="literal"><span class="pre">iterator_category</span></tt>.</li>
-<li>The changes to the specification of <tt class="literal"><span class="pre">traversal_category</span></tt> are a 
-direct result of the removal of <tt class="literal"><span class="pre">iterator_tag</span></tt>.</li>
-</ol>
-</div>
-</div>
-</body>
-</html>

doc/issues.rst

@@ -3,7 +3,7 @@
 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 .. _N1550: http://www.boost-consulting.com/writing/n1550.html
-.. _N1530: http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2003/n1530.html
+.. _N1530: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2003/n1530.html
 
 :Author: David Abrahams and Jeremy Siek
 :Contact: dave@boost-consulting.com, jsiek@osl.iu.edu

doc/iter-issue-list.rst

@@ -1,942 +0,0 @@
-++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
- Our Personal Iterator Issue List
-++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-
-.. _N1550: http://www.boost-consulting.com/writing/n1550.html
-.. _N1530: http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2003/n1530.html
-
-:Author: David Abrahams and Jeremy Siek
-:Contact: dave@boost-consulting.com, jsiek@osl.iu.edu
-:Organization: `Boost Consulting`_, Indiana University Bloomington
-:date: $Date$
-:Copyright: Copyright David Abrahams, Jeremy Siek 2003. Use, modification and
-      distribution is subject to the Boost Software License,
-      Version 1.0. (See accompanying file LICENSE_1_0.txt or copy
-      at http://www.boost.org/LICENSE_1_0.txt)
-
-.. _`Boost Consulting`: http://www.boost-consulting.com
-
-
-.. contents:: Table of Contents
-
-
-problem with is_writable, is_swappable
-======================================
-
-See the separate writeup_.
-
-.. _writeup: ./issues.html
-
-
-reference requirements in readable iterator
-===========================================
-
-The DR has been submitted. This is a placeholder for updating our
-proposals with respects to the resolution of that DR.
-
-
-Subject: N1550: iterator_access overspecified?
-==============================================
-Date: Fri, 07 Nov 2003 10:25:45 -0500
-Message c++std-lib-12262
-
-The proposal includes:
- 
-enum iterator_access { readable_iterator = 1, writable_iterator = 2,
-swappable_iterator = 4, lvalue_iterator = 8 };
- 
-In general, the standard specifies thing like this as a bitmask type with a
-list of defined names, and specifies neither the exact type nor the
-specific values. Is there a reason for iterator_access to be more specific?
-
-
-Resolution
-----------
-
-The iterator_access enum has been removed, so this is no longer an issue.
-
-
-
-
-N1530: Minor Issues
-===================
-Message c++std-lib-12299
-Date: Tue, 11 Nov 2003 10:30:36 -0500
-
-1. operators of iterator_facade overspecified. In general, we've provided 
-operational semantics for things like operator++. That is, we've said that 
-++iter must work, without requiring either a member function or a 
-non-member function. iterator_facade specifies most operators as member 
-functions. There's no inherent reason for these to be members, so we should 
-remove this requirement. Similarly, some operations are specified as 
-non-member functions but could be implemented as members. Again, the 
-standard doesn't make either of these choices, and TR1 shouldn't, either. 
-So: operator*(), operator++(), operator++(int), operator--(), 
-operator--(int), operator+=, operator-=, operator-(difference_type), 
-operator-(iterator_facade instance), and operator+ should be specified with 
-operational semantics and not explicitly required to be members or non-members.
-
-2. enable_if_interoperable needs standardese. The only discussion of what 
-this means is in a note, so is non-normative. Further, the note seems to be 
-incorrect. It says that enable_if_interoperable only works for types that 
-"are interoperable, by which we mean they are convertible to each other." 
-This requirement is too strong: it should be that one of the types is 
-convertible to the other.
-
-3. iterator_adaptor has an extraneous 'bool' at the start of the template 
-definition.
-
-4. iterator_adaptor has a private member named m_iterator. Presumably this 
-is for exposition only, since it's an implementation detail. It needs to be 
-marked as such.
-
-5. iterator_adaptor operations specifications are a bit inconsistent. 
-iterator_adpator() has a Requires clause, that Base must be default 
-constructible. iterator_adaptor(Base) has no Requires clause, although the 
-Returns clause says that the Base member is copy construced from the 
-argument (this may actually be an oversight in N1550, which doesn't require 
-iterators to be copy constructible or assignable).
-
-6. similar to 2, "Specialized Adaptors" has a note describing 
-enable_if_convertible. This should be normative text.
-
-7. reverse iterator "flips the direction of the base iterator's motion". 
-This needs to be more formal, as in the current standard. Something like: 
-"iterates through the controlled sequence in the opposite direction"
-
-8. reverse_iterator::dereference is specified as calling a function named 
-'prior' which has no specification.
-
-9. Transform iterator has a two-part specification: it does this, in other 
-words, it does that. "In other words" always means "I didn't say it right, 
-so I'll try again." We need to say it once.
-
-10. similar to 4, transform_iterator has a private member named 'm_f' which 
-should be marked "exposition only."
-
-11. The description of Counting iterator is unclear. "The counting iterator 
-adaptor implements dereference by returning a reference to the base object. 
-The other operations are implemented by the base m_iterator, as per the 
-inheritance from iterator_adaptor."
-
-12. Counting iterator has the following note:
-
-[Note: implementers are encouraged to provide an implementation of 
-distance_to and a difference_type that avoids overflows in the cases when 
-the Incrementable type is a numeric type.]
-
-I'm not sure what this means. The user provides a template argument named 
-Difference, but there's no difference_type. I assume this is just a glitch 
-in the wording. But if implementors are encouraged to ignore this argument 
-if it won't work right, why is it there?
-
-
-Subject: N1550: iterator_facade Derived template argument underspecified
-========================================================================
-Message c++std-lib-12302,
-Date: Wed, 12 Nov 2003 11:16:49 -0500
- 
-The first template argument to iterator_facade is named Derived, and the
-proposal says:
- 
-        The Derived template parameter must be a class derived from iterator_facade.
- 
-First, iterator_facade is a template, so cannot be derived from. Rather,
-the class must be derived from a specialization of iterator_facade. More
-important, isn't Derived required to be the class that is being defined?
-That is, if I understand it right, the definition of D here this is not valid:
- 
-class C : public iterator_facade<C, ... > { ... };
- 
-class D : public iterator_facade<C, ...> { ... };
- 
-In the definition of D, the Derived argument to iterator_facade is a class
-derived from a specialization of iterator_facade, so the requirement is
-met. Shouldn't the requirement be more like "when using iterator_facade to
-define an iterator class Iter, the class Iter must be derived from a
-specialization of iterator_facade whose first template argument is Iter."
-That's a bit awkward, but at the moment I don't see a better way of
-phrasing it.
-
-
-Subject: N1550: return type of Iterator difference for iterator facade
-======================================================================
-Date: Wed, 12 Nov 2003 12:20:26 -0500
-Message c++std-lib-12303
- 
-The proposal says:
- 
->template <class Dr1, class V1, class AC1, class TC1, class R1, class D1,
->           class Dr2, class V2, class AC2, class TC2, class R2, class D2>
->typename enable_if_interoperable<Dr1, Dr2, bool>::type
->operator -(iterator_facade<Dr1, V1, AC1, TC1, R1, D1> const& lhs,
->            iterator_facade<Dr2, V2, AC2, TC2, R2, D2> const& rhs);
- 
-Shouldn't the return type be one of the two iterator types? Which one? The
-idea is that if one of the iterator types can be converted to the other
-type, then the subtraction is okay. Seems like the return type should then
-be the type that was converted to. Is that right?
-
-
-
-Subject: N1550: Minor Wording Issue
-=================================== 
-Date: Wed, 12 Nov 2003 13:19:07 -0500
-From: Pete Becker <petebecker@acm.org>
-Message c++std-lib-12305
- 
-In the table that lists the required (sort of) member functions of iterator
-types that are based on iterator_facade, the entry for c.equal(y) says:
- 
->true iff c and y refer to the same position. Implements c == y and c != y.
- 
-The second sentence is inside out. c.equal(y) does not implement either of
-these operations. It is used to implement them. Same thing in the
-description of c.distance_to(z).
-
-
-Subject: N1530: Problems in iterator facade operations
-======================================================
-Date: Wed, 12 Nov 2003 13:52:55 -0500
-From: Pete Becker <petebecker@acm.org>
-Message c++std-lib-12308
- 
-1. Several of the descriptions use the name X without defining it. This
-seems to be a carryover from the table immediately above this section, but
-the text preceding that table says "In the table below, X is the derived
-iterator type." Looks like the X:: qualifiers aren't really needed;
-X::reference can simply be reference, since that's defined by the
-iterator_facade specialization itself.
- 
-2. Several of the member functions return a Derived object or a Derived&.
-Their Effects clauses end with
-
-::
-    
-    return *this;
-
-This should be
-
-::
-
-    return *(Derived*)this;
-    
-
-3. The returns clause for operator[](difference_type n) const says
-
-::
-
-    Returns: an object convertible to X::reference and holding a copy p of a+n
-    such that, for a constant object v of type X::value_type,
-    X::reference(a[n] = v) is equivalent to p = v.
-    
-This needs to define 'a', but assuming it's supposed to be *this (or
-maybe *(Derived*)this), it still isn't clear what this
-says. Presumably, the idea is that you can index off of an iterator
-and assign to the result. But why the requirement that it hold a copy
-of a+n? Granted, that's probably how it's implemented, but it seems
-over-constrained. And the last phrase seems wrong. p is an iterator;
-there's no requirement that you can assign a value_type object to
-it. Should that be *p = v? But why the cast in reference(a[n] = v)?
- 
-4. operator- has both an effects clause and a returns clause. Looks like
-the returns clause should be removed.
-
-
-Subject: N1530: Problems in indirect_iterator operations
-========================================================
-Date: Wed, 12 Nov 2003 14:49:44 -0500
-From: Pete Becker <petebecker@acm.org>
-Message c++std-lib-12310
- 
-1. The default constructor returns "An instance of indirect_iterator with a
-default constructed base object", but the constructor that takes an
-Iterator object returns "An instance of indirect_iterator with the
-iterator_adaptor subobject copy constructed from x." The latter is the
-correct form, since it does not reach inside the base class for its
-semantics. So the default constructor shoudl return "An instance of
-indirect_iterator with a default-constructed iterator_adaptor subobject."
- 
-2. The templated constructor that takes an indirect_iterator with a
-different set of template arguments says that it returns "An instance of
-indirect_iterator that is a copy of [the argument]". But the type of the
-argument is different from the type of the object being constructed, and
-there is no description of what a "copy" means. The Iterator template
-parameter for the argument must be convertible to the Iterator template
-parameter for the type being constructed, which suggests that the
-argument's contained Iterator object should be converted to the target
-type's Iterator type. Is that what's meant here?
-
-
-Resolution
-----------
-
-1. As suggested, change the returns clause to read:
-
-:Returns: An instance of ``indirect_iterator`` with a default-constructed
-  ``iterator_adaptor`` subobject.
-
-
-2. Basically, yes. The return clause should be changed to:
-
-:Returns: An instance of ``indirect_iterator`` whose 
-  ``iterator_adaptor`` subobject is constructed from ``y.base()``.
-
-
-
-Subject: N1530: enable_if_convertible conflicts with requires
-=============================================================
-Date: Wed, 12 Nov 2003 15:09:48 -0500
-From: Pete Becker <petebecker@acm.org>
-Message c++std-lib-12312
- 
-In every place where enable_if_convertible is used it's used like this
-(simplified):
- 
-template<class T>
-struct C
-{
-template<class T1>
-C(T1, enable_if_convertible<T1, T>::type* = 0);
-};
- 
-The idea being that this constructor won't compile if T1 isn't convertible
-to T. As a result, the constructor won't be considered as a possible
-overload when constructing from an object x where the type of x isn't
-convertible to T. In addition, however, each of these constructors has a
-requires clause that requires convertibility, so the behavior of a program
-that attempts such a construction is undefined. Seems like the
-enable_if_convertible part is irrelevant, and should be removed.
-
-
-Subject: N1530: transform_iterator argument irregularity
-========================================================
-Date: Wed, 12 Nov 2003 15:22:58 -0500
-From: Pete Becker <petebecker@acm.org>
-Message c++std-lib-12315
- 
-The specialized adaptors that take both a Value and a Reference template
-argument all take them in that order, i.e. Value precedes Reference in the
-template argument list, with the exception of transform_iterator, where
-Reference precedes Value. This seems like a possible source of confusion.
-Is there a reason why this order is prefereable?
-
-
-Subject: N1530: function_output_iterator
-======================================== 
-Date: Wed, 12 Nov 2003 15:52:37 -0500
-From: Pete Becker <petebecker@acm.org>
-Message c++std-lib-12318
- 
-1. function_output_iterator requirements says: "The UnaryFunction must be
-Assignable, Copy Constructible, and the expression f(x) must be valid,
-where f is an object of type UnaryFunction and x is an object of a type
-accepted by f."
- 
-Everything starting with "and," somewhat reworded, is actually a constraint
-on output_proxy::operator=. All that's needed to create a
-function_output_iterator object is that the UnaryFunction type be
-Assignable and CopyConstructible. That's also sufficient to dereference and
-to increment such an object. It's only when you try to assign through a
-dereferenced iterator that f(x) has to work, and then only for the
-particular function object that the iterator holds and for the particular
-value that is being assigned.
- 
-2. Should output_proxy really be a named type? This means someone can store
-an output_proxy object for later use, whatever that means. It also
-constrains output_proxy to hold a copy of the function object, rather than
-a pointer to the iterator object. Is all this mechanism really necessary?
- 
-
-
-N1550: istreambuf_iterator isn't a Readable Iterator
-====================================================
-Date: Thu, 13 Nov 2003 08:24:39 -0500
-From: Pete Becker <petebecker@acm.org>
-Message c++std-lib-12333
- 
-N1550 requires that for a Readable Iterator a of type X, *a returns an
-object of type iterator_traits<X>::reference.
-istreambuf_iterator::operator* returns charT, but
-istreambuf_iterator::reference is charT&. So am I overlooking something, or
-is istreambuf_iterator not Readable?
-
-
-
-
-Subject: N1530: iterator_facade free functions unspecified
-========================================================== 
-Date: Tue, 02 Dec 2003 14:44:05 -0500
-From: Pete Becker <petebecker@acm.org>
-Message c++std-lib-12562
-
-
-The template functions operator==, operator!=, operator<, operator<=,
-operator>, operator>=, and operator- that take two arguments that are
-specializations of iterator_facade have no specification. The template
-function operator+ that takes an argument that is a specialization of
-iterator_facade and an argument of type difference_type has no specification.
-
-
-
-
-Subject: N1530, iterator_facade: too many equals?
-=================================================
-Date: Tue, 02 Dec 2003 17:24:55 -0500
-From: Pete Becker <petebecker@acm.org>
-Message c++std-lib-12563
-
- 
-The table listing the functions required for types derived from
-iterator_facade has two functions named equal and two named distance_to::
-
-    c.equal(b)
-    c.equal(y)
- 
-    c.distance_to(b)
-    c.distance_to(z)
- 
-where b and c are const objects of the derived type, y and z are constant
-objects of certain iterator types that are interoperable with the derived type.
- 
-Seems like the 'b' versions are redundant: in both cases, the other version
-will take a 'b'. In fact, iterator_adaptor is specified to use
-iterator_facade, but does not provide the 'b' versions of these functions.
- 
-Are the 'b' versions needed?
-
-
-
-Subject: Re: Proposed revision of N1550
-=======================================
-From: Pete Becker <petebecker@acm.org>
-Date: Wed, 03 Dec 2003 13:36:26 -0500
-Message c++std-lib-12566
-
-The footnote says:
- 
->The UnaryTypeTrait concept is defined in n1519; the LWG added the
->requirement that specializations are derived from their nested ::type.
- 
-This is not correct. We had a vague discussion of this in Kona and agreed
-in principle, but at the time there was no formal proposal. It's in the
-issues list as a new issue.
-
-
-Subject: Re: Proposed revision of N1550
-=======================================
-Date: Fri, 5 Dec 2003 15:09:32 -0500
-From: Howard Hinnant <hinnant@twcny.rr.com>
-Message c++std-lib-12585
-
-I'm wading thru
-
-http://boost-consulting.com/boost/libs/iterator/doc/new-iter-concepts.html
-
-and due to my desire to plow through this in a sequential manner, I'm  
-having trouble getting past one spot.  I've skimmed through the  
-previous discussions and didn't see that this issue was addressed  
-(sorry if I missed it).
-
-Readable Iterator Requirements says::
-
-    a->m      U&        pre: (*a).m is well-defined. Equivalent to (*a).m
-
-Do we mean to outlaw iterators with proxy references from meeting the  
-readable requirements?
-
-Consider::
-
-    template <class T>
-    class proxy_pointer
-    {
-    public:
-	 proxy_pointer(T* t) : t_(t) {}
-
-	 T* operator->() {return t_;}
-    private:
-	 T* t_;
-    };
-
-    template <class T>
-    class proxy_reference
-    {
-    public:
-	 proxy_reference(T& t) : t_(&t) {}
-
-	 proxy_reference& operator=(const T& t)
-	 {
-	     *t_ = t;
-	     return *this;
-	 }
-
-	 proxy_reference& operator=(const proxy_reference& p)
-	 {
-	     *t_ = p->t_;
-	     return *this;
-	 }
-
-	 operator T() const {return *t_;}
-
-	 proxy_pointer<T> operator&() const {return proxy_pointer<T>(t_);}
-    private:
-	 T* t_;
-    };
-
-    template <class T>
-    class iterator
-    {
-    public:
-	 typedef proxy_reference<T> reference;
-	 typedef proxy_pointer<T> pointer;
-
-	 iterator(T* t) : t_(t) {}
-	 reference operator*() const {return reference(*t_);}
-	 pointer operator->() const {return pointer(t_);}
-    private:
-	 T* t_;
-    };
-
-    int main()
-    {
-	 typedef std::pair<int, int> T;
-	 T p(1, 2);
-	 iterator<T> r(&p);
-	 int i = (*r).first;  // error
-	 int j = r->first;  // ok
-    }
-
-Would it be better for the requirements to read static_cast<T>(*a).m  
-instead of (*a).m ?
-
-
-Subject: N1530: counting_iterator Traversal argument unspecified
-================================================================
-Date: Tue, 09 Dec 2003 10:09:15 -0500
-From: Pete Becker <petebecker@acm.org>
-Message c++std-lib-12635
- 
-counting_iterator takes an argument for its Traversal type, with a default
-value of use_default. It is derived from an instance of iterator_adaptor,
-where the argument passed for the Traversal type is described as "/* see
-details for traversal category */". The details for counting_iterator
-describe constraints on the Incrementable type imposed by various traversal
-categories. There is no description of what the argument to
-iterator_adaptor should be.
-
-
-Subject: N1530: iterator_facade function requirements
-=====================================================
-Date: Tue, 09 Dec 2003 10:47:40 -0500
-From: Pete Becker <petebecker@acm.org>
-Message c++std-lib-12636
- 
-The table that lists required functions for the derived type X passed to
-iterator_facade lists, among others:
- 
-for a single pass iterator:
-c.equal(b)
-c.equal(y)
- 
-where b and c are const X objects, and y is a const object of a single pass
-iterator that is interoperable with X. Since X is interoperable with
-itself, c.equal(b) is redundant. There is a difference in their
-descriptions, but its meaning isn't clear. The first is "true iff b and c
-are equivalent", and the second is "true iff c and y refer to the same
-position." Is there a difference between the undefined term "equivalent"
-and "refer to the same position"?
- 
-Similarly, for a random access traversal iterator:
-c.distance_to(b)
-c.distance_to(z)
- 
-where z is a constant object of a random access traversal iterator that is
-interoperable with X. Again, X is interoperable with itself, so
-c.distance_to(b) is redundant.
- 
-Also, the specification for c.distance_to(z) isn't valid. It's written as
-"equivalent to distance(c, z)". The template function distance takes two
-arguments of the same type, so distance(c, z) isn't valid if c and z are
-different types. Should it be distance(c, (X)z)?
-
-
-
-Subject: N1530: iterator_facade requirements muddled
-====================================================
-Date: Tue, 09 Dec 2003 11:20:00 -0500
-From: Pete Becker <petebecker@acm.org>
-Message c++std-lib-12638
-
-Sorry for the title. The problem is that the section entitled 
-"iterator_facade requirements" mixes specification of the implementation 
-with specification of constraints on user-supplied types. The specification 
-of the implementation isn't really need, though. Paragraph by paragraph:
-
->Some of the constraints on template parameters to iterator_facade are 
->expressed in terms of resulting nested types and should be viewed in the 
->context of their impact on iterator_traits<Derived>.
-
-This isn't really true, once we go through the rest. Remove it.
-
->The Derived template parameter must be a class derived from iterator_facade.
-
-There's already an open issue on the wording here. No other changes needed.
-
->The nested ::value_type type will be the same as remove_cv<Value>::type, 
->so the Value parameter must be an (optionally const-qualified) 
->non-reference type.
-
-The first clause repeats what's already said in the definition of the 
-template. The second clause is the important part. Rewrite as:
-
-The Value parameter shall be an optionally const-qualified non-reference type.
-
->AccessCategory must be an unsigned value which uses no more bits than the 
->greatest value of iterator_access.
-
-There's an open issue in N1550 about the specification of access 
-categories. The standard defines "bitmask type" for this purpose. Using it 
-removes the problem of determining what "uses no more bits" means.
-
->The nested ::reference will be the same as the Reference parameter; it 
->must be a suitable reference type for the resulting iterator. The default 
->for the Reference parameter is Value&.
-
-The first clause repeats what's already said in the definition of the 
-template. The second clause has no technical meaning. The last sentence is 
-part of the specification of the template, and should be moved to the 
-definition of the template. Remove this paragraph, and change the template 
-argument in the definition of iterator_facade from
-
-         class Reference = /* see below */
-
-to
-
-         class Reference = Value&;
-
-Finally, something that isn't quite as clearcut:
-
->Depending on the resulting iterator's iterator_category, a subset of the 
->expressions listed in the table are required to be valid.
-
-Is it meaningful to have an iterator that is neither readable nor writable? 
-If not, then this can be phrased as "Depending on the template argument 
-TraversalCategory", and the first line of the following table can be 
-removed from the table and stated as an overall requirement.
-
-
-
-
-
-Subject: N1530: iterator_adaptor issues
-=======================================
-Date: Tue, 09 Dec 2003 12:36:44 -0500
-From: Pete Becker <petebecker@acm.org>
-Message c++std-lib-12639
-
-
-1. The Derived argument seems to be underspecified. Same problem as 
-described in N1541, 9.21 for iterator_facade.
-
-2. The name Base for the iterator that's being adapted (and in the member 
-functions base() and base_reference()) is confusing, since it's not a base 
-in the sense that the term is used in C++. The templates indirect_iterator 
-and reverse_iterator both name their iterator argument Iterator. We should 
-do the same here.
-
-3. The clause entitled "iterator_adaptor requirements" talks about 
-iterator_traits<Derived>::iterator_category. The base iterator_facade 
-defines iterator_category, so it would seem more natural to simply use 
-that. Unless, of course, Derived is permitted to provide its own definition 
-of iterator_category which is different from the one in the base, or that 
-iterator_traits<Derived> can be specialized to provide a differnt one. That 
-doesn't seem reasonable, since the type in the base is determined by the 
-Access and Traversal arguments that the user passed to iterator_adaptor. 
-Why would the user want to define it differently?
-
-4. The clause entitled "iterator_adaptor requirements" sets out 
-requirements in terms of the typedefs defined in iterator_facade. It would 
-be clearer to specify the arguments that should be passed to iterator_facade:
-
-Value argument to iterator_facade::
-
-    if (Value != use_default)
-        Value
-    else
-        iterator_traits<Base>::value_type
-
-But note that the default here is slightly different from the default 
-specified in the paper. The latter can't be implemented correctly with an 
-argument to iterator_facade, since iterator_traits<Base>::value_type might 
-be cv-qualified, and iterator_facade strips the cv-qualifier. The approch 
-I've given strips the cv-qualifier, too. In order to implement what the 
-paper says, iterator_adaptor would have to provide its own version of 
-value_type.
-
-AccessCategory argument to iterator_facade::
-
-    if (Access != use_default)
-	Access
-    else if (is_const<Value>)
-	access_category<Base>::value & ~writable_iterator
-    else
-	access_category<Base>::value
-
-This assumes (as does the paper) that there is a suitable definition of 
-access_category somewhere (N1550 doesn't specify it).
-
-TraversalCategory argument to iterator_facade::
-
-    if (Traversal != use_default)
-	Traversal
-    else
-	traversal_category<Base>::type
-
-This assumes (as does the paper) that there is a suitable definition of 
-traversal_category somewhere (N1550 doesn't specify it).
-
-iterator_category is redundant and should be removed.
-
-Reference argument to iterator_facade::
-
-    if (Reference != use_default)
-        Reference
-    else if (Value != use_default)
-        Value&
-    else
-        iterator_traits<Base>::reference
-
-The Difference argument to iterator_facade isn't specified here. Needs to 
-be added. By analogy, should it be this?::
-
-    if (Difference != use_default)
-	Difference
-    else
-	iterator_traits<Base>::difference_type
-
-
-
-
-
-Subject: N1530: indirect_iterator requirements muddled
-======================================================
-Date: Tue, 09 Dec 2003 13:35:20 -0500
-From: Pete Becker <petebecker@acm.org>
-Message c++std-lib-12640
-
-
-Part 1
-------
-
->The value_type of the Iterator template parameter should itself be 
->dereferenceable. The return type of the operator* for the value_type must 
->be the same type as the Reference template parameter.
-
-I'd say this a bit differently, to emphasize what's required:
-
-iterator_traits<Iterator>::value_type must be dereferenceable.
-
-The Reference template parameter must be the same type as 
-*iterator_traits<Iterator>::value_type().
-
-
-Resolution
-----------
-
-I don't think we want to require default constructible for
-``iterator_traits<Iterator>::value_type``, so I've reworded to avoid
-that implication.
-
-Change the text to:
-
-The following requirements are placed on the type
-``iterator_traits<Iterator>::value_type``. Let ``i`` be an object of
-type ``iterator_traits<Iterator>::value_type``.  Then ``*i`` must be a
-valid expression, and the type of ``*i`` must be the same as the
-``Reference`` template parameter.
-
-Part 2
-------
-
->The Value template parameter will be the value_type for the 
->indirect_iterator, unless Value is const. If Value is const X, then 
->value_type will be non- const X.
-
-Also non-volatile, right? In other words, if Value isn't use_default, it 
-just gets passed as the Value argument for iterator_adaptor.
-
-
-Resolution
-----------
-
-Yes, I think that's right. Dave, can you confirm?
-
-Here's the rewording:
-
-The ``Value`` template parameter will be the ``value_type`` for the
-``indirect_iterator``, unless ``Value`` is cv-qualified. If ``Value``
-is cv-qualified then ``value_type`` will be non-qualified version of
-the type.
-
-
-Part 3
-------
-
->The default for Value is
->
->iterator_traits< iterator_traits<Iterator>::value_type >::value_type
->
->If the default is used for Value, then there must be a valid 
->specialization of iterator_traits for the value type of the base iterator.
-
-The earlier requirement is that iterator_traits<Iterator>::value_type must 
-be dereferenceable. Now it's being treated as an iterator. Is this just a 
-pun, or is iterator_traits<Iterator>::value_type required to be some form 
-of iterator? If it's the former we need to find a different way to say it. 
-If it's the latter we need to say so.
-
-
-Resolution
-----------
-
-Dave, help!
-
-
-Part 4
-------
-
->The Reference parameter will be the reference type of the 
->indirect_iterator. The default is Value&.
-
-That is, the Reference parameter is passed unchanged as the Reference 
-argument to iterator_adaptor. Which is what it should say, instead of 
-repeating what iterator_adaptor does.
-
-Resolution
-----------
-
-Yes.
-
-
-Part 5
-------
-
->The Access and Traversal parameters are passed unchanged to the 
->corresponding parameters of the iterator_adaptor base class, and the 
->Iterator parameter is passed unchanged as the Base parameter to the 
->iterator_adaptor base class.
-
-Okay, but wordy. We should put it in the template definition:
-
-template<
-         class Iterator,
-         class Value = use_default,
-         class Access = use_default_access,
-         class Traversal = use_default,
-         class Reference = use_default,
-         clsas Difference = use_default>
-class indirect_iterator
-         : public iterator_adaptor<
-                 indirect_iterator<Iterator, Value, Access, Traversal, 
-Reference, Difference>,
-                 Iterator,
-                 /* Value = see below */,
-                 Access,
-                 Traversal,
-                 Reference,
-                 Difference>
-
-Resolution
-----------
-
-Yes.
-
-
-Part 6
-------
-
->The indirect iterator will model the most refined standard traversal 
->concept that is modeled by the Iterator type. The indirect iterator will 
->model the most refined standard access concept that is modeled by the 
->value type of Iterator.
-
-That's not strictly true. The Access and Traversal arguments can be more 
-restrictive than the Iterator, in which case the operations needed for the 
-most refined types are available, but iterator_traits<X>::iterator_category 
-won't reflect those capabilities.
-
-
-Resolution
-----------
-
-The indirect iterator will model the most refined standard traversal
-concept that is modeled by the ``Iterator`` type and that refines the
-traversal category specified in the ``CategoryOrTraversal`` parameter.
-The indirect iterator will model the most refined standard access
-concept that is modeled by the value type of ``Iterator``.
-
-.. I am not confident in the above. -JGS
-
-
-Subject: N1530: transform_iterator requirements
-===============================================
-Date: Tue, 09 Dec 2003 13:42:49 -0500
-From: Pete Becker <petebecker@acm.org>
-Message c++std-lib-12641
- 
->The reference type of transform_iterator is
->result_of<UnaryFunction(iterator_traits<Iterator>::reference)>::type. The
->value_type is remove_cv<remove_reference<reference> >::type.
- 
-These are the defaults, right? If the user supplies their own types that's
-what gets passed to iterator_adaptor. And again, the specification should
-be in terms of the specialization of iterator_adaptor, and not in terms of
-the result:
- 
-Reference argument to iterator_adaptor::
-
-    if (Reference != use_default)
-	Reference
-    else
-	result_of<UnaryFunction(iterator_traits<Iterator>::reference)>::type
-
-Value argument to iterator_adaptor::
-
-    if (Value != use_default)
-	Value
-    else if (Reference != use_default)
-	remove_reference<reference>::type
-    else
-	remove_reference<result_of<UnaryFunction(iterator_traits<Iterator>::reference)>::type>::type
- 
-There's probably a better way to specify that last alternative, but I've
-been at this too long, and it's all turning into a maze of twisty passages,
-all alike.
-
-
- 
-Subject: N1530: filter_iterator details unspecified
-===================================================
-Date: Tue, 09 Dec 2003 13:52:21 -0500
-From: Pete Becker <petebecker@acm.org>
-Message c++std-lib-12642
- 
-The paper says::
-
-    template<class Predicate, class Iterator>
-    class filter_iterator
-	     : public iterator_adaptor<
-		     filter_iterator<Predicate, Iterator>,
-		     Iterator,
-		     use_default,
-		     /* see details */ >
- 
-That comment covers the Access, Traversal, Reference, and Difference
-arguments. The only specification for any of these in the details is:
- 
->The access category of the filter_iterator will be the same as the access
->category of Iterator.
- 
-Needs more.
-
-

doc/iterator_adaptor.html

@@ -3,204 +3,13 @@
 <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.1: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
 <title>Iterator Adaptor</title>
 <meta name="author" content="David Abrahams, Jeremy Siek, Thomas Witt" />
 <meta name="organization" content="Boost Consulting, Indiana University Open Systems Lab, University of Hanover Institute for Transport Railway Operation and Construction" />
-<meta name="date" content="2003-09-14" />
-<meta name="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved" />
-<style type="text/css"><!--
-
-/*
-:Author: David Goodger
-:Contact: goodger@users.sourceforge.net
-:date: $Date$
-:version: $Revision$
-:copyright: This stylesheet has been placed in the public domain.
-
-Default cascading style sheet for the HTML output of Docutils.
-*/
-
-.first {
-  margin-top: 0 }
-
-.last {
-  margin-bottom: 0 }
-
-a.toc-backref {
-  text-decoration: none ;
-  color: black }
-
-dd {
-  margin-bottom: 0.5em }
-
-div.abstract {
-  margin: 2em 5em }
-
-div.abstract p.topic-title {
-  font-weight: bold ;
-  text-align: center }
-
-div.attention, div.caution, div.danger, div.error, div.hint,
-div.important, div.note, div.tip, div.warning {
-  margin: 2em ;
-  border: medium outset ;
-  padding: 1em }
-
-div.attention p.admonition-title, div.caution p.admonition-title,
-div.danger p.admonition-title, div.error p.admonition-title,
-div.warning p.admonition-title {
-  color: red ;
-  font-weight: bold ;
-  font-family: sans-serif }
-
-div.hint p.admonition-title, div.important p.admonition-title,
-div.note p.admonition-title, div.tip p.admonition-title {
-  font-weight: bold ;
-  font-family: sans-serif }
-
-div.dedication {
-  margin: 2em 5em ;
-  text-align: center ;
-  font-style: italic }
-
-div.dedication p.topic-title {
-  font-weight: bold ;
-  font-style: normal }
-
-div.figure {
-  margin-left: 2em }
-
-div.footer, div.header {
-  font-size: smaller }
-
-div.system-messages {
-  margin: 5em }
-
-div.system-messages h1 {
-  color: red }
-
-div.system-message {
-  border: medium outset ;
-  padding: 1em }
-
-div.system-message p.system-message-title {
-  color: red ;
-  font-weight: bold }
-
-div.topic {
-  margin: 2em }
-
-h1.title {
-  text-align: center }
-
-h2.subtitle {
-  text-align: center }
-
-hr {
-  width: 75% }
-
-ol.simple, ul.simple {
-  margin-bottom: 1em }
-
-ol.arabic {
-  list-style: decimal }
-
-ol.loweralpha {
-  list-style: lower-alpha }
-
-ol.upperalpha {
-  list-style: upper-alpha }
-
-ol.lowerroman {
-  list-style: lower-roman }
-
-ol.upperroman {
-  list-style: upper-roman }
-
-p.caption {
-  font-style: italic }
-
-p.credits {
-  font-style: italic ;
-  font-size: smaller }
-
-p.label {
-  white-space: nowrap }
-
-p.topic-title {
-  font-weight: bold }
-
-pre.address {
-  margin-bottom: 0 ;
-  margin-top: 0 ;
-  font-family: serif ;
-  font-size: 100% }
-
-pre.line-block {
-  font-family: serif ;
-  font-size: 100% }
-
-pre.literal-block, pre.doctest-block {
-  margin-left: 2em ;
-  margin-right: 2em ;
-  background-color: #eeeeee }
-
-span.classifier {
-  font-family: sans-serif ;
-  font-style: oblique }
-
-span.classifier-delimiter {
-  font-family: sans-serif ;
-  font-weight: bold }
-
-span.interpreted {
-  font-family: sans-serif }
-
-span.option-argument {
-  font-style: italic }
-
-span.pre {
-  white-space: pre }
-
-span.problematic {
-  color: red }
-
-table {
-  margin-top: 0.5em ;
-  margin-bottom: 0.5em }
-
-table.citation {
-  border-left: solid thin gray ;
-  padding-left: 0.5ex }
-
-table.docinfo {
-  margin: 2em 4em }
-
-table.footnote {
-  border-left: solid thin black ;
-  padding-left: 0.5ex }
-
-td, th {
-  padding-left: 0.5em ;
-  padding-right: 0.5em ;
-  vertical-align: top }
-
-th.docinfo-name, th.field-name {
-  font-weight: bold ;
-  text-align: left ;
-  white-space: nowrap }
-
-h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
-  font-size: 100% }
-
-tt {
-  background-color: #eeeeee }
-
-ul.auto-toc {
-  list-style-type: none }
-
---></style>
+<meta name="date" content="2006-09-11" />
+<meta name="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003." />
+<link rel="stylesheet" href="../../../rst.css" type="text/css" />
 </head>
 <body>
 <div class="document" id="iterator-adaptor">
@@ -212,18 +21,21 @@ ul.auto-toc {
 <tr><th class="docinfo-name">Author:</th>
 <td>David Abrahams, Jeremy Siek, Thomas Witt</td></tr>
 <tr><th class="docinfo-name">Contact:</th>
-<td><a class="first reference" href="mailto:dave&#64;boost-consulting.com">dave&#64;boost-consulting.com</a>, <a class="reference" href="mailto:jsiek&#64;osl.iu.edu">jsiek&#64;osl.iu.edu</a>, <a class="last reference" href="mailto:witt&#64;ive.uni-hannover.de">witt&#64;ive.uni-hannover.de</a></td></tr>
+<td><a class="first reference external" href="mailto:dave&#64;boost-consulting.com">dave&#64;boost-consulting.com</a>, <a class="reference external" href="mailto:jsiek&#64;osl.iu.edu">jsiek&#64;osl.iu.edu</a>, <a class="last reference external" href="mailto:witt&#64;ive.uni-hannover.de">witt&#64;ive.uni-hannover.de</a></td></tr>
 <tr><th class="docinfo-name">Organization:</th>
-<td><a class="first reference" href="http://www.boost-consulting.com">Boost Consulting</a>, Indiana University <a class="reference" href="http://www.osl.iu.edu">Open Systems
-Lab</a>, University of Hanover <a class="last reference" href="http://www.ive.uni-hannover.de">Institute for Transport
+<td><a class="first reference external" href="http://www.boost-consulting.com">Boost Consulting</a>, Indiana University <a class="reference external" href="http://www.osl.iu.edu">Open Systems
+Lab</a>, University of Hanover <a class="last reference external" href="http://www.ive.uni-hannover.de">Institute for Transport
 Railway Operation and Construction</a></td></tr>
 <tr><th class="docinfo-name">Date:</th>
-<td>2003-09-14</td></tr>
+<td>2006-09-11</td></tr>
 <tr><th class="docinfo-name">Copyright:</th>
-<td>Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved</td></tr>
+<td>Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003.</td></tr>
 </tbody>
 </table>
-<table class="field-list" frame="void" rules="none">
+<!-- Distributed under the Boost -->
+<!-- Software License, Version 1.0. (See accompanying -->
+<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
+<table class="docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
@@ -231,107 +43,117 @@ Railway Operation and Construction</a></td></tr>
 </tr>
 </tbody>
 </table>
+<!-- Distributed under the Boost -->
+<!-- Software License, Version 1.0. (See accompanying -->
+<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
 <!-- Version 1.1 of this ReStructuredText document corresponds to
 n1530_, the paper accepted by the LWG. -->
-<!-- Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All
-rights reserved -->
-<p>Each specialization of the <tt class="literal"><span class="pre">iterator_adaptor</span></tt> class template is derived from
-a specialization of <tt class="literal"><span class="pre">iterator_facade</span></tt>. The core interface functions
-expected by <tt class="literal"><span class="pre">iterator_facade</span></tt> are implemented in terms of the
-<tt class="literal"><span class="pre">iterator_adaptor</span></tt>'s <tt class="literal"><span class="pre">Base</span></tt> template parameter. A class derived
-from <tt class="literal"><span class="pre">iterator_adaptor</span></tt> typically redefines some of the core
-interface functions to adapt the behavior of the <tt class="literal"><span class="pre">Base</span></tt> type.
+<!-- Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. -->
+<p>Each specialization of the <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> class template is derived from
+a specialization of <tt class="docutils literal"><span class="pre">iterator_facade</span></tt>. The core interface functions
+expected by <tt class="docutils literal"><span class="pre">iterator_facade</span></tt> are implemented in terms of the
+<tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt>'s <tt class="docutils literal"><span class="pre">Base</span></tt> template parameter. A class derived
+from <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> typically redefines some of the core
+interface functions to adapt the behavior of the <tt class="docutils literal"><span class="pre">Base</span></tt> type.
 Whether the derived class models any of the standard iterator concepts
-depends on the operations supported by the <tt class="literal"><span class="pre">Base</span></tt> type and which
-core interface functions of <tt class="literal"><span class="pre">iterator_facade</span></tt> are redefined in the
-<tt class="literal"><span class="pre">Derived</span></tt> class.</p>
+depends on the operations supported by the <tt class="docutils literal"><span class="pre">Base</span></tt> type and which
+core interface functions of <tt class="docutils literal"><span class="pre">iterator_facade</span></tt> are redefined in the
+<tt class="docutils literal"><span class="pre">Derived</span></tt> class.</p>
 <div class="contents topic" id="table-of-contents">
-<p class="topic-title"><a name="table-of-contents">Table of Contents</a></p>
+<p class="topic-title first">Table of Contents</p>
 <ul class="simple">
-<li><a class="reference" href="#introduction" id="id3" name="id3">Introduction</a></li>
-<li><a class="reference" href="#reference" id="id4" name="id4">Reference</a><ul>
-<li><a class="reference" href="#iterator-adaptor-base-class-parameters" id="id5" name="id5"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> base class parameters</a></li>
-<li><a class="reference" href="#iterator-adaptor-usage" id="id6" name="id6"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> usage</a></li>
-<li><a class="reference" href="#iterator-adaptor-public-operations" id="id7" name="id7"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> public operations</a></li>
-<li><a class="reference" href="#iterator-adaptor-protected-member-functions" id="id8" name="id8"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> protected member functions</a></li>
-<li><a class="reference" href="#iterator-adaptor-private-member-functions" id="id9" name="id9"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> private member functions</a></li>
+<li><a class="reference internal" href="#overview" id="id6">Overview</a></li>
+<li><a class="reference internal" href="#reference" id="id7">Reference</a><ul>
+<li><a class="reference internal" href="#iterator-adaptor-requirements" id="id8"><tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> requirements</a></li>
+<li><a class="reference internal" href="#iterator-adaptor-base-class-parameters" id="id9"><tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> base class parameters</a></li>
+<li><a class="reference internal" href="#iterator-adaptor-public-operations" id="id10"><tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> public operations</a></li>
+<li><a class="reference internal" href="#iterator-adaptor-protected-member-functions" id="id11"><tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> protected member functions</a></li>
+<li><a class="reference internal" href="#iterator-adaptor-private-member-functions" id="id12"><tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> private member functions</a></li>
 </ul>
 </li>
+<li><a class="reference internal" href="#tutorial-example" id="id13">Tutorial Example</a></li>
 </ul>
 </div>
-<div class="section" id="introduction">
-<h1><a class="toc-backref" href="#id3" name="introduction">Introduction</a></h1>
+<div class="section" id="overview">
+<h1><a class="toc-backref" href="#id6">Overview</a></h1>
+<!-- Distributed under the Boost -->
+<!-- Software License, Version 1.0. (See accompanying -->
+<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
 <!-- Version 1.2 of this ReStructuredText document corresponds to
 n1530_, the paper accepted by the LWG for TR1. -->
-<!-- Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All
-rights reserved -->
-<p>The <tt class="literal"><span class="pre">iterator_adaptor</span></tt> class template adapts some <tt class="literal"><span class="pre">Base</span></tt> <a class="footnote-reference" href="#base" id="id1" name="id1"><sup>1</sup></a>
-type to create a new iterator.  Instantiations of <tt class="literal"><span class="pre">iterator_adaptor</span></tt>
-are derived from a corresponding instantiation of <tt class="literal"><span class="pre">iterator_facade</span></tt>
-and implement the core behaviors in terms of the <tt class="literal"><span class="pre">Base</span></tt> type. In
-essence, <tt class="literal"><span class="pre">iterator_adaptor</span></tt> merely forwards all operations to an
-instance of the <tt class="literal"><span class="pre">Base</span></tt> type, which it stores as a member.</p>
-<table class="footnote" frame="void" id="base" rules="none">
+<!-- Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. -->
+<p>The <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> class template adapts some <tt class="docutils literal"><span class="pre">Base</span></tt><a class="footnote-reference" href="#base" id="id1"><sup>1</sup></a>
+type to create a new iterator.  Instantiations of <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt>
+are derived from a corresponding instantiation of <tt class="docutils literal"><span class="pre">iterator_facade</span></tt>
+and implement the core behaviors in terms of the <tt class="docutils literal"><span class="pre">Base</span></tt> type. In
+essence, <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> merely forwards all operations to an
+instance of the <tt class="docutils literal"><span class="pre">Base</span></tt> type, which it stores as a member.</p>
+<table class="docutils footnote" frame="void" id="base" rules="none">
 <colgroup><col class="label" /><col /></colgroup>
 <tbody valign="top">
-<tr><td class="label"><a class="fn-backref" href="#id1" name="base">[1]</a></td><td>The term &quot;Base&quot; here does not refer to a base class and is
+<tr><td class="label">[1]</td><td><em>(<a class="fn-backref" href="#id1">1</a>, <a class="fn-backref" href="#id3">2</a>)</em> The term &quot;Base&quot; here does not refer to a base class and is
 not meant to imply the use of derivation. We have followed the lead
 of the standard library, which provides a base() function to access
-the underlying iterator object of a <tt class="literal"><span class="pre">reverse_iterator</span></tt> adaptor.</td></tr>
+the underlying iterator object of a <tt class="docutils literal"><span class="pre">reverse_iterator</span></tt> adaptor.</td></tr>
 </tbody>
 </table>
-<p>The user of <tt class="literal"><span class="pre">iterator_adaptor</span></tt> creates a class derived from an
-instantiation of <tt class="literal"><span class="pre">iterator_adaptor</span></tt> and then selectively
-redefines some of the core member functions described in the table
-above. The <tt class="literal"><span class="pre">Base</span></tt> type need not meet the full requirements for an
-iterator. It need only support the operations used by the core
-interface functions of <tt class="literal"><span class="pre">iterator_adaptor</span></tt> that have not been
-redefined in the user's derived class.</p>
-<p>Several of the template parameters of <tt class="literal"><span class="pre">iterator_adaptor</span></tt> default
-to <tt class="literal"><span class="pre">use_default</span></tt>. This allows the
+<p>The user of <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> creates a class derived from an
+instantiation of <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> and then selectively
+redefines some of the core member functions described in the
+<tt class="docutils literal"><span class="pre">iterator_facade</span></tt> core requirements table. The <tt class="docutils literal"><span class="pre">Base</span></tt> type need
+not meet the full requirements for an iterator; it need only
+support the operations used by the core interface functions of
+<tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> that have not been redefined in the user's
+derived class.</p>
+<p>Several of the template parameters of <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> default
+to <tt class="docutils literal"><span class="pre">use_default</span></tt>. This allows the
 user to make use of a default parameter even when she wants to
 specify a parameter later in the parameter list.  Also, the
 defaults for the corresponding associated types are somewhat
 complicated, so metaprogramming is required to compute them, and
-<tt class="literal"><span class="pre">use_default</span></tt> can help to simplify the implementation.  Finally,
-the identity of the <tt class="literal"><span class="pre">use_default</span></tt> type is not left unspecified
-because specification helps to highlight that the <tt class="literal"><span class="pre">Reference</span></tt>
+<tt class="docutils literal"><span class="pre">use_default</span></tt> can help to simplify the implementation.  Finally,
+the identity of the <tt class="docutils literal"><span class="pre">use_default</span></tt> type is not left unspecified
+because specification helps to highlight that the <tt class="docutils literal"><span class="pre">Reference</span></tt>
 template parameter may not always be identical to the iterator's
-<tt class="literal"><span class="pre">reference</span></tt> type, and will keep users from making mistakes based on
+<tt class="docutils literal"><span class="pre">reference</span></tt> type, and will keep users from making mistakes based on
 that assumption.</p>
 </div>
 <div class="section" id="reference">
-<h1><a class="toc-backref" href="#id4" name="reference">Reference</a></h1>
+<h1><a class="toc-backref" href="#id7">Reference</a></h1>
+<!-- Distributed under the Boost -->
+<!-- Software License, Version 1.0. (See accompanying -->
+<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
 <!-- Version 1.4 of this ReStructuredText document corresponds to
 n1530_, the paper accepted by the LWG for TR1. -->
-<!-- Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All
-rights reserved. -->
+<!-- Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. -->
 <pre class="literal-block">
 template &lt;
     class Derived
   , class Base
-  , class Value        = use_default
-  , class CategoryOrTraversal  = use_default
-  , class Reference  = use_default
+  , class Value               = use_default
+  , class CategoryOrTraversal = use_default
+  , class Reference           = use_default
   , class Difference = use_default
 &gt;
-class iterator_adaptor 
-  : public iterator_facade&lt;Derived, <em>V</em>, <em>C</em>, <em>R</em>, <em>D</em>&gt; // see <a class="reference" href="#base-parameters">details</a>
+class iterator_adaptor
+  : public iterator_facade&lt;Derived, <em>V'</em>, <em>C'</em>, <em>R'</em>, <em>D'</em>&gt; // see <a class="reference internal" href="#base-parameters">details</a>
 {
     friend class iterator_core_access;
  public:
     iterator_adaptor();
-    explicit iterator_adaptor(Base iter);
-    Base base() const;
+    explicit iterator_adaptor(Base const&amp; iter);
+    typedef Base base_type;
+    Base const&amp; base() const;
  protected:
+    typedef iterator_adaptor iterator_adaptor_;
     Base const&amp; base_reference() const;
     Base&amp; base_reference();
- private: // Core iterator interface for iterator_facade.  
+ private: // Core iterator interface for iterator_facade.
     typename iterator_adaptor::reference dereference() const;
 
     template &lt;
     class OtherDerived, class OtherIterator, class V, class C, class R, class D
-    &gt;   
+    &gt;
     bool equal(iterator_adaptor&lt;OtherDerived, OtherIterator, V, C, R, D&gt; const&amp; x) const;
 
     void advance(typename iterator_adaptor::difference_type n);
@@ -340,7 +162,7 @@ class iterator_adaptor
 
     template &lt;
         class OtherDerived, class OtherIterator, class V, class C, class R, class D
-    &gt;   
+    &gt;
     typename iterator_adaptor::difference_type distance_to(
         iterator_adaptor&lt;OtherDerived, OtherIterator, V, C, R, D&gt; const&amp; y) const;
 
@@ -348,23 +170,28 @@ class iterator_adaptor
     Base m_iterator; // exposition only
 };
 </pre>
-<a class="target" id="base-parameters" name="base-parameters"></a><div class="section" id="iterator-adaptor-base-class-parameters">
-<h2><a class="toc-backref" href="#id5" name="iterator-adaptor-base-class-parameters"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> base class parameters</a></h2>
-<p>The <em>V</em>, <em>C</em>, <em>R</em>, and <em>D</em> parameters of the <tt class="literal"><span class="pre">iterator_facade</span></tt>
-used as a base class in the summary of <tt class="literal"><span class="pre">iterator_adaptor</span></tt>
+<div class="section" id="iterator-adaptor-requirements">
+<span id="requirements"></span><h2><a class="toc-backref" href="#id8"><tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> requirements</a></h2>
+<p><tt class="docutils literal"><span class="pre">static_cast&lt;Derived*&gt;(iterator_adaptor*)</span></tt> shall be well-formed.
+The <tt class="docutils literal"><span class="pre">Base</span></tt> argument shall be Assignable and Copy Constructible.</p>
+</div>
+<div class="section" id="iterator-adaptor-base-class-parameters">
+<span id="base-parameters"></span><h2><a class="toc-backref" href="#id9"><tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> base class parameters</a></h2>
+<p>The <em>V'</em>, <em>C'</em>, <em>R'</em>, and <em>D'</em> parameters of the <tt class="docutils literal"><span class="pre">iterator_facade</span></tt>
+used as a base class in the summary of <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt>
 above are defined as follows:</p>
 <pre class="literal-block">
-<em>V</em> = if (Value is use_default)
+<em>V'</em> = if (Value is use_default)
           return iterator_traits&lt;Base&gt;::value_type
       else
           return Value
 
-<em>C</em> = if (CategoryOrTraversal is use_default)
+<em>C'</em> = if (CategoryOrTraversal is use_default)
           return iterator_traversal&lt;Base&gt;::type
       else
           return CategoryOrTraversal
 
-<em>R</em> = if (Reference is use_default)
+<em>R'</em> = if (Reference is use_default)
           if (Value is use_default)
               return iterator_traits&lt;Base&gt;::reference
           else
@@ -372,154 +199,263 @@ above are defined as follows:</p>
       else
           return Reference
 
-<em>D</em> = if (Difference is use_default)
+<em>D'</em> = if (Difference is use_default)
           return iterator_traits&lt;Base&gt;::difference_type
       else
           return Difference
 </pre>
-</div>
-<div class="section" id="iterator-adaptor-usage">
-<h2><a class="toc-backref" href="#id6" name="iterator-adaptor-usage"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> usage</a></h2>
-<p>The <tt class="literal"><span class="pre">Derived</span></tt> template parameter must be a publicly derived from
-<tt class="literal"><span class="pre">iterator_adaptor</span></tt>.  In order for <tt class="literal"><span class="pre">Derived</span></tt> to model the
-iterator concepts corresponding to
-<tt class="literal"><span class="pre">iterator_traits&lt;Derived&gt;::iterator_category</span></tt>, the expressions
-involving <tt class="literal"><span class="pre">m_iterator</span></tt> in the specifications of those private
-member functions of <tt class="literal"><span class="pre">iterator_adaptor</span></tt> that may be called by
-<tt class="literal"><span class="pre">iterator_facade&lt;Derived,</span> <span class="pre">``\</span> <span class="pre">*V*\</span></tt>, <tt class="literal"><span class="pre">\</span> <span class="pre">*C*\</span></tt>, <tt class="literal"><span class="pre">\</span> <span class="pre">*R*\</span></tt>, <tt class="literal"><span class="pre">\</span>
-<span class="pre">*D*\</span></tt>&gt;`` in evaluating any valid expression involving <tt class="literal"><span class="pre">Derived</span></tt>
-in those concepts' requirements.</p>
+<!-- ``iterator_adaptor`` models
+- - - - - - - - - - - - - - - - - - - - - - - - - - -
+
+In order for ``Derived`` to model the iterator concepts corresponding
+to ``iterator_traits<Derived>::iterator_category``, the expressions
+involving ``m_iterator`` in the specifications of those private member
+functions of ``iterator_adaptor`` that may be called by
+``iterator_facade<Derived, V, C, R, D>`` in evaluating any valid
+expression involving ``Derived`` in those concepts' requirements. -->
+<!-- The above is confusing and needs a rewrite. -JGS -->
+<!-- That's why it's removed.  We're embracing inheritance, remember? -->
 </div>
 <div class="section" id="iterator-adaptor-public-operations">
-<h2><a class="toc-backref" href="#id7" name="iterator-adaptor-public-operations"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> public operations</a></h2>
-<p><tt class="literal"><span class="pre">iterator_adaptor();</span></tt></p>
-<table class="field-list" frame="void" rules="none">
+<h2><a class="toc-backref" href="#id10"><tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> public operations</a></h2>
+<p><tt class="docutils literal"><span class="pre">iterator_adaptor();</span></tt></p>
+<table class="docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
-<tr class="field"><th class="field-name">Requires:</th><td class="field-body">The <tt class="literal"><span class="pre">Base</span></tt> type must be Default Constructible.</td>
+<tr class="field"><th class="field-name">Requires:</th><td class="field-body">The <tt class="docutils literal"><span class="pre">Base</span></tt> type must be Default Constructible.</td>
 </tr>
-<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="literal"><span class="pre">iterator_adaptor</span></tt> with 
-<tt class="literal"><span class="pre">m_iterator</span></tt> default constructed.</td>
+<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> with
+<tt class="docutils literal"><span class="pre">m_iterator</span></tt> default constructed.</td>
 </tr>
 </tbody>
 </table>
-<p><tt class="literal"><span class="pre">explicit</span> <span class="pre">iterator_adaptor(Base</span> <span class="pre">iter);</span></tt></p>
-<table class="field-list" frame="void" rules="none">
+<p><tt class="docutils literal"><span class="pre">explicit</span> <span class="pre">iterator_adaptor(Base</span> <span class="pre">const&amp;</span> <span class="pre">iter);</span></tt></p>
+<table class="docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
-<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="literal"><span class="pre">iterator_adaptor</span></tt> with
-<tt class="literal"><span class="pre">m_iterator</span></tt> copy constructed from <tt class="literal"><span class="pre">iter</span></tt>.</td>
+<tr class="field"><th class="field-name">Returns:</th><td class="field-body">An instance of <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> with
+<tt class="docutils literal"><span class="pre">m_iterator</span></tt> copy constructed from <tt class="docutils literal"><span class="pre">iter</span></tt>.</td>
 </tr>
 </tbody>
 </table>
-<p><tt class="literal"><span class="pre">Base</span> <span class="pre">base()</span> <span class="pre">const;</span></tt></p>
-<table class="field-list" frame="void" rules="none">
+<p><tt class="docutils literal"><span class="pre">Base</span> <span class="pre">const&amp;</span> <span class="pre">base()</span> <span class="pre">const;</span></tt></p>
+<table class="docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
-<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">m_iterator</span></tt></td>
+<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">m_iterator</span></tt></td>
 </tr>
 </tbody>
 </table>
 </div>
 <div class="section" id="iterator-adaptor-protected-member-functions">
-<h2><a class="toc-backref" href="#id8" name="iterator-adaptor-protected-member-functions"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> protected member functions</a></h2>
-<p><tt class="literal"><span class="pre">Base</span> <span class="pre">const&amp;</span> <span class="pre">base_reference()</span> <span class="pre">const;</span></tt></p>
-<table class="field-list" frame="void" rules="none">
+<h2><a class="toc-backref" href="#id11"><tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> protected member functions</a></h2>
+<p><tt class="docutils literal"><span class="pre">Base</span> <span class="pre">const&amp;</span> <span class="pre">base_reference()</span> <span class="pre">const;</span></tt></p>
+<table class="docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
-<tr class="field"><th class="field-name">Returns:</th><td class="field-body">A const reference to <tt class="literal"><span class="pre">m_iterator</span></tt>.</td>
+<tr class="field"><th class="field-name">Returns:</th><td class="field-body">A const reference to <tt class="docutils literal"><span class="pre">m_iterator</span></tt>.</td>
 </tr>
 </tbody>
 </table>
-<p><tt class="literal"><span class="pre">Base&amp;</span> <span class="pre">base_reference();</span></tt></p>
-<table class="field-list" frame="void" rules="none">
+<p><tt class="docutils literal"><span class="pre">Base&amp;</span> <span class="pre">base_reference();</span></tt></p>
+<table class="docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
-<tr class="field"><th class="field-name">Returns:</th><td class="field-body">A non-const reference to <tt class="literal"><span class="pre">m_iterator</span></tt>.</td>
+<tr class="field"><th class="field-name">Returns:</th><td class="field-body">A non-const reference to <tt class="docutils literal"><span class="pre">m_iterator</span></tt>.</td>
 </tr>
 </tbody>
 </table>
 </div>
 <div class="section" id="iterator-adaptor-private-member-functions">
-<h2><a class="toc-backref" href="#id9" name="iterator-adaptor-private-member-functions"><tt class="literal"><span class="pre">iterator_adaptor</span></tt> private member functions</a></h2>
-<p><tt class="literal"><span class="pre">typename</span> <span class="pre">iterator_adaptor::reference</span> <span class="pre">dereference()</span> <span class="pre">const;</span></tt></p>
-<table class="field-list" frame="void" rules="none">
+<h2><a class="toc-backref" href="#id12"><tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> private member functions</a></h2>
+<p><tt class="docutils literal"><span class="pre">typename</span> <span class="pre">iterator_adaptor::reference</span> <span class="pre">dereference()</span> <span class="pre">const;</span></tt></p>
+<table class="docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
-<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">*m_iterator</span></tt></td>
+<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">*m_iterator</span></tt></td>
 </tr>
 </tbody>
 </table>
 <pre class="literal-block">
 template &lt;
 class OtherDerived, class OtherIterator, class V, class C, class R, class D
-&gt;   
+&gt;
 bool equal(iterator_adaptor&lt;OtherDerived, OtherIterator, V, C, R, D&gt; const&amp; x) const;
 </pre>
-<table class="field-list" frame="void" rules="none">
+<table class="docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
-<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">m_iterator</span> <span class="pre">==</span> <span class="pre">x.base()</span></tt></td>
+<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">m_iterator</span> <span class="pre">==</span> <span class="pre">x.base()</span></tt></td>
 </tr>
 </tbody>
 </table>
-<p><tt class="literal"><span class="pre">void</span> <span class="pre">advance(typename</span> <span class="pre">iterator_adaptor::difference_type</span> <span class="pre">n);</span></tt></p>
-<table class="field-list" frame="void" rules="none">
+<p><tt class="docutils literal"><span class="pre">void</span> <span class="pre">advance(typename</span> <span class="pre">iterator_adaptor::difference_type</span> <span class="pre">n);</span></tt></p>
+<table class="docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
-<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><tt class="literal"><span class="pre">m_iterator</span> <span class="pre">+=</span> <span class="pre">n;</span></tt></td>
+<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><tt class="docutils literal"><span class="pre">m_iterator</span> <span class="pre">+=</span> <span class="pre">n;</span></tt></td>
 </tr>
 </tbody>
 </table>
-<p><tt class="literal"><span class="pre">void</span> <span class="pre">increment();</span></tt></p>
-<table class="field-list" frame="void" rules="none">
+<p><tt class="docutils literal"><span class="pre">void</span> <span class="pre">increment();</span></tt></p>
+<table class="docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
-<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><tt class="literal"><span class="pre">++m_iterator;</span></tt></td>
+<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><tt class="docutils literal"><span class="pre">++m_iterator;</span></tt></td>
 </tr>
 </tbody>
 </table>
-<p><tt class="literal"><span class="pre">void</span> <span class="pre">decrement();</span></tt></p>
-<table class="field-list" frame="void" rules="none">
+<p><tt class="docutils literal"><span class="pre">void</span> <span class="pre">decrement();</span></tt></p>
+<table class="docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
-<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><tt class="literal"><span class="pre">--m_iterator;</span></tt></td>
+<tr class="field"><th class="field-name">Effects:</th><td class="field-body"><tt class="docutils literal"><span class="pre">--m_iterator;</span></tt></td>
 </tr>
 </tbody>
 </table>
 <pre class="literal-block">
 template &lt;
     class OtherDerived, class OtherIterator, class V, class C, class R, class D
-&gt;   
+&gt;
 typename iterator_adaptor::difference_type distance_to(
     iterator_adaptor&lt;OtherDerived, OtherIterator, V, C, R, D&gt; const&amp; y) const;
 </pre>
-<table class="field-list" frame="void" rules="none">
+<table class="docutils field-list" frame="void" rules="none">
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
-<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="literal"><span class="pre">y.base()</span> <span class="pre">-</span> <span class="pre">m_iterator</span></tt></td>
+<tr class="field"><th class="field-name">Returns:</th><td class="field-body"><tt class="docutils literal"><span class="pre">y.base()</span> <span class="pre">-</span> <span class="pre">m_iterator</span></tt></td>
 </tr>
 </tbody>
 </table>
 </div>
 </div>
+<div class="section" id="tutorial-example">
+<h1><a class="toc-backref" href="#id13">Tutorial Example</a></h1>
+<!-- Copyright David Abrahams 2004. Use, modification and distribution is -->
+<!-- subject to the Boost Software License, Version 1.0. (See accompanying -->
+<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
+<p>In this section we'll further refine the <tt class="docutils literal"><span class="pre">node_iter</span></tt> class
+template we developed in the <a class="reference external" href="iterator_facade.html#tutorial-example"><tt class="docutils literal"><span class="pre">iterator_facade</span></tt> tutorial</a>.  If you haven't already
+read that material, you should go back now and check it out because
+we're going to pick up right where it left off.</p>
+<div class="sidebar">
+<p class="first sidebar-title"><tt class="docutils literal"><span class="pre">node_base*</span></tt> really <em>is</em> an iterator</p>
+<p class="last">It's not really a very interesting iterator, since <tt class="docutils literal"><span class="pre">node_base</span></tt>
+is an abstract class: a pointer to a <tt class="docutils literal"><span class="pre">node_base</span></tt> just points
+at some base subobject of an instance of some other class, and
+incrementing a <tt class="docutils literal"><span class="pre">node_base*</span></tt> moves it past this base subobject
+to who-knows-where?  The most we can do with that incremented
+position is to compare another <tt class="docutils literal"><span class="pre">node_base*</span></tt> to it.  In other
+words, the original iterator traverses a one-element array.</p>
+</div>
+<p>You probably didn't think of it this way, but the <tt class="docutils literal"><span class="pre">node_base*</span></tt>
+object that underlies <tt class="docutils literal"><span class="pre">node_iterator</span></tt> is itself an iterator,
+just like all other pointers.  If we examine that pointer closely
+from an iterator perspective, we can see that it has much in common
+with the <tt class="docutils literal"><span class="pre">node_iterator</span></tt> we're building.  First, they share most
+of the same associated types (<tt class="docutils literal"><span class="pre">value_type</span></tt>, <tt class="docutils literal"><span class="pre">reference</span></tt>,
+<tt class="docutils literal"><span class="pre">pointer</span></tt>, and <tt class="docutils literal"><span class="pre">difference_type</span></tt>).  Second, even some of the
+core functionality is the same: <tt class="docutils literal"><span class="pre">operator*</span></tt> and <tt class="docutils literal"><span class="pre">operator==</span></tt> on
+the <tt class="docutils literal"><span class="pre">node_iterator</span></tt> return the result of invoking the same
+operations on the underlying pointer, via the <tt class="docutils literal"><span class="pre">node_iterator</span></tt>'s
+<a class="reference external" href="iterator_facade.html#implementing-the-core-operations"><tt class="docutils literal"><span class="pre">dereference</span></tt> and <tt class="docutils literal"><span class="pre">equal</span></tt> member functions</a>).  The only real behavioral difference
+between <tt class="docutils literal"><span class="pre">node_base*</span></tt> and <tt class="docutils literal"><span class="pre">node_iterator</span></tt> can be observed when
+they are incremented: <tt class="docutils literal"><span class="pre">node_iterator</span></tt> follows the
+<tt class="docutils literal"><span class="pre">m_next</span></tt> pointer, while <tt class="docutils literal"><span class="pre">node_base*</span></tt> just applies an address offset.</p>
+<p>It turns out that the pattern of building an iterator on another
+iterator-like type (the <tt class="docutils literal"><span class="pre">Base</span></tt><a class="footnote-reference" href="#base" id="id3"><sup>1</sup></a> type) while modifying
+just a few aspects of the underlying type's behavior is an
+extremely common one, and it's the pattern addressed by
+<tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt>.  Using <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> is very much like
+using <tt class="docutils literal"><span class="pre">iterator_facade</span></tt>, but because iterator_adaptor tries to
+mimic as much of the <tt class="docutils literal"><span class="pre">Base</span></tt> type's behavior as possible, we
+neither have to supply a <tt class="docutils literal"><span class="pre">Value</span></tt> argument, nor implement any core
+behaviors other than <tt class="docutils literal"><span class="pre">increment</span></tt>.  The implementation of
+<tt class="docutils literal"><span class="pre">node_iter</span></tt> is thus reduced to:</p>
+<pre class="literal-block">
+template &lt;class Value&gt;
+class node_iter
+  : public boost::iterator_adaptor&lt;
+        node_iter&lt;Value&gt;                // Derived
+      , Value*                          // Base
+      , boost::use_default              // Value
+      , boost::forward_traversal_tag    // CategoryOrTraversal
+    &gt;
+{
+ private:
+    struct enabler {};  // a private type avoids misuse
+
+ public:
+    node_iter()
+      : node_iter::iterator_adaptor_(0) {}
+
+    explicit node_iter(Value* p)
+      : node_iter::iterator_adaptor_(p) {}
+
+    template &lt;class OtherValue&gt;
+    node_iter(
+        node_iter&lt;OtherValue&gt; const&amp; other
+      , typename boost::enable_if&lt;
+            boost::is_convertible&lt;OtherValue*,Value*&gt;
+          , enabler
+        &gt;::type = enabler()
+    )
+      : node_iter::iterator_adaptor_(other.base()) {}
+
+ private:
+    friend class boost::iterator_core_access;
+    void increment() { this-&gt;base_reference() = this-&gt;base()-&gt;next(); }
+};
+</pre>
+<p>Note the use of <tt class="docutils literal"><span class="pre">node_iter::iterator_adaptor_</span></tt> here: because
+<tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> defines a nested <tt class="docutils literal"><span class="pre">iterator_adaptor_</span></tt> type
+that refers to itself, that gives us a convenient way to refer to
+the complicated base class type of <tt class="docutils literal"><span class="pre">node_iter&lt;Value&gt;</span></tt>. [Note:
+this technique is known not to work with Borland C++ 5.6.4 and
+Metrowerks CodeWarrior versions prior to 9.0]</p>
+<p>You can see an example program that exercises this version of the
+node iterators <a class="reference external" href="../example/node_iterator3.cpp">here</a>.</p>
+<p>In the case of <tt class="docutils literal"><span class="pre">node_iter</span></tt>, it's not very compelling to pass
+<tt class="docutils literal"><span class="pre">boost::use_default</span></tt> as <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt>'s <tt class="docutils literal"><span class="pre">Value</span></tt>
+argument; we could have just passed <tt class="docutils literal"><span class="pre">node_iter</span></tt>'s <tt class="docutils literal"><span class="pre">Value</span></tt>
+along to <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt>, and that'd even be shorter!  Most
+iterator class templates built with <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt> are
+parameterized on another iterator type, rather than on its
+<tt class="docutils literal"><span class="pre">value_type</span></tt>.  For example, <tt class="docutils literal"><span class="pre">boost::reverse_iterator</span></tt> takes an
+iterator type argument and reverses its direction of traversal,
+since the original iterator and the reversed one have all the same
+associated types, <tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt>'s delegation of default
+types to its <tt class="docutils literal"><span class="pre">Base</span></tt> saves the implementor of
+<tt class="docutils literal"><span class="pre">boost::reverse_iterator</span></tt> from writing:</p>
+<pre class="literal-block">
+std::iterator_traits&lt;Iterator&gt;::<em>some-associated-type</em>
+</pre>
+<p>at least four times.</p>
+<p>We urge you to review the documentation and implementations of
+<a class="reference external" href="reverse_iterator.html"><tt class="docutils literal"><span class="pre">reverse_iterator</span></tt></a> and the other Boost <a class="reference external" href="index.html#specialized-adaptors">specialized iterator
+adaptors</a> to get an idea of the sorts of things you can do with
+<tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt>.  In particular, have a look at
+<a class="reference external" href="transform_iterator.html"><tt class="docutils literal"><span class="pre">transform_iterator</span></tt></a>, which is perhaps the most straightforward
+adaptor, and also <a class="reference external" href="counting_iterator.html"><tt class="docutils literal"><span class="pre">counting_iterator</span></tt></a>, which demonstrates that
+<tt class="docutils literal"><span class="pre">iterator_adaptor</span></tt>'s <tt class="docutils literal"><span class="pre">Base</span></tt> type needn't be an iterator.</p>
+</div>
 </div>
-<hr class="footer" />
 <div class="footer">
-<a class="reference" href="iterator_adaptor.rst">View document source</a>.
-Generated on: 2003-11-24 05:11 UTC.
-Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
+<hr class="footer" />
+<a class="reference external" href="iterator_adaptor.rst">View document source</a>.
+Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
+
 </div>
 </body>
 </html>

doc/iterator_adaptor.rst

@@ -1,3 +1,7 @@
+.. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
 +++++++++++++++++
  Iterator Adaptor
 +++++++++++++++++
@@ -8,7 +12,7 @@
                Lab`_, University of Hanover `Institute for Transport
                Railway Operation and Construction`_
 :date: $Date$
-:copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved
+:copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. 
 
 .. _`Boost Consulting`: http://www.boost-consulting.com
 .. _`Open Systems Lab`: http://www.osl.iu.edu
@@ -20,8 +24,8 @@
 
 .. contents:: Table of Contents
 
-Introduction
-============
+Overview
+========
 
 .. include:: iterator_adaptor_body.rst
 
@@ -30,3 +34,8 @@ Reference
 =========
 
 .. include:: iterator_adaptor_ref.rst
+
+Tutorial Example
+================
+
+.. include:: iterator_adaptor_tutorial.rst

doc/iterator_adaptor_abstract.rst

@@ -1,8 +1,11 @@
+.. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
 .. Version 1.1 of this ReStructuredText document corresponds to
    n1530_, the paper accepted by the LWG.
 
-.. Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All
-   rights reserved
+.. Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. 
 
 Each specialization of the ``iterator_adaptor`` class template is derived from
 a specialization of ``iterator_facade``. The core interface functions

doc/iterator_adaptor_body.rst

@@ -1,8 +1,11 @@
+.. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
 .. Version 1.2 of this ReStructuredText document corresponds to
    n1530_, the paper accepted by the LWG for TR1.
 
-.. Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All
-   rights reserved
+.. Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. 
 
 The ``iterator_adaptor`` class template adapts some ``Base`` [#base]_
 type to create a new iterator.  Instantiations of ``iterator_adaptor``
@@ -18,11 +21,12 @@ instance of the ``Base`` type, which it stores as a member.
 
 The user of ``iterator_adaptor`` creates a class derived from an
 instantiation of ``iterator_adaptor`` and then selectively
-redefines some of the core member functions described in the table
-above. The ``Base`` type need not meet the full requirements for an
-iterator. It need only support the operations used by the core
-interface functions of ``iterator_adaptor`` that have not been
-redefined in the user's derived class.
+redefines some of the core member functions described in the
+``iterator_facade`` core requirements table. The ``Base`` type need
+not meet the full requirements for an iterator; it need only
+support the operations used by the core interface functions of
+``iterator_adaptor`` that have not been redefined in the user's
+derived class.
 
 Several of the template parameters of ``iterator_adaptor`` default
 to ``use_default``. This allows the

doc/iterator_adaptor_ref.rst

@@ -1,28 +1,33 @@
+.. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
 .. Version 1.4 of this ReStructuredText document corresponds to
    n1530_, the paper accepted by the LWG for TR1.
 
-.. Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All
-   rights reserved.
+.. Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. 
 
 .. parsed-literal::
   
   template <
       class Derived
     , class Base
-    , class Value        = use_default
-    , class CategoryOrTraversal  = use_default
-    , class Reference  = use_default
+    , class Value               = use_default
+    , class CategoryOrTraversal = use_default
+    , class Reference           = use_default
     , class Difference = use_default
   >
   class iterator_adaptor 
-    : public iterator_facade<Derived, *V*, *C*, *R*, *D*> // see details__
+    : public iterator_facade<Derived, *V'*, *C'*, *R'*, *D'*> // see details__
   {
       friend class iterator_core_access;
    public:
       iterator_adaptor();
-      explicit iterator_adaptor(Base iter);
-      Base base() const;
+      explicit iterator_adaptor(Base const& iter);
+      typedef Base base_type;
+      Base const& base() const;
    protected:
+      typedef iterator_adaptor iterator_adaptor\_;
       Base const& base_reference() const;
       Base& base_reference();
    private: // Core iterator interface for iterator_facade.  
@@ -49,28 +54,37 @@
 
 __ base_parameters_
 
+.. _requirements:
+
+``iterator_adaptor`` requirements
+---------------------------------
+
+``static_cast<Derived*>(iterator_adaptor*)`` shall be well-formed.
+The ``Base`` argument shall be Assignable and Copy Constructible.
+
+
 .. _base_parameters:
 
 ``iterator_adaptor`` base class parameters
 ------------------------------------------
 
-The *V*, *C*, *R*, and *D* parameters of the ``iterator_facade``
+The *V'*, *C'*, *R'*, and *D'* parameters of the ``iterator_facade``
 used as a base class in the summary of ``iterator_adaptor``
 above are defined as follows:
 
 .. parsed-literal::
 
-   *V* = if (Value is use_default)
+   *V'* = if (Value is use_default)
              return iterator_traits<Base>::value_type
          else
              return Value
 
-   *C* = if (CategoryOrTraversal is use_default)
+   *C'* = if (CategoryOrTraversal is use_default)
              return iterator_traversal<Base>::type
          else
              return CategoryOrTraversal
 
-   *R* = if (Reference is use_default)
+   *R'* = if (Reference is use_default)
              if (Value is use_default)
                  return iterator_traits<Base>::reference
              else
@@ -78,23 +92,23 @@ above are defined as follows:
          else
              return Reference
 
-   *D* = if (Difference is use_default)
+   *D'* = if (Difference is use_default)
              return iterator_traits<Base>::difference_type
          else
              return Difference
 
-``iterator_adaptor`` usage
---------------------------
+.. ``iterator_adaptor`` models
+   ---------------------------
 
-The ``Derived`` template parameter must be a publicly derived from
-``iterator_adaptor``.  In order for ``Derived`` to model the
-iterator concepts corresponding to
-``iterator_traits<Derived>::iterator_category``, the expressions
-involving ``m_iterator`` in the specifications of those private
-member functions of ``iterator_adaptor`` that may be called by
-``iterator_facade<Derived, ``\ *V*\``, ``\ *C*\``, ``\ *R*\``, ``\
-*D*\``>`` in evaluating any valid expression involving ``Derived``
-in those concepts' requirements.
+   In order for ``Derived`` to model the iterator concepts corresponding
+   to ``iterator_traits<Derived>::iterator_category``, the expressions
+   involving ``m_iterator`` in the specifications of those private member
+   functions of ``iterator_adaptor`` that may be called by
+   ``iterator_facade<Derived, V, C, R, D>`` in evaluating any valid
+   expression involving ``Derived`` in those concepts' requirements.
+
+.. The above is confusing and needs a rewrite. -JGS
+.. That's why it's removed.  We're embracing inheritance, remember?
 
 ``iterator_adaptor`` public operations
 --------------------------------------
@@ -106,16 +120,15 @@ in those concepts' requirements.
     ``m_iterator`` default constructed.
 
 
-``explicit iterator_adaptor(Base iter);``
+``explicit iterator_adaptor(Base const& iter);``
 
 :Returns: An instance of ``iterator_adaptor`` with
     ``m_iterator`` copy constructed from ``iter``.
 
-``Base base() const;``
+``Base const& base() const;``
 
 :Returns: ``m_iterator``
 
-
 ``iterator_adaptor`` protected member functions
 -----------------------------------------------
 

doc/iterator_adaptor_tutorial.rst

@@ -0,0 +1,135 @@
+.. Copyright David Abrahams 2004. Use, modification and distribution is
+.. subject to the Boost Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+In this section we'll further refine the ``node_iter`` class
+template we developed in the |fac_tut|_.  If you haven't already
+read that material, you should go back now and check it out because
+we're going to pick up right where it left off.
+
+.. |fac_tut| replace:: ``iterator_facade`` tutorial
+.. _fac_tut: iterator_facade.html#tutorial-example
+
+.. sidebar:: ``node_base*`` really *is* an iterator
+
+   It's not really a very interesting iterator, since ``node_base``
+   is an abstract class: a pointer to a ``node_base`` just points
+   at some base subobject of an instance of some other class, and
+   incrementing a ``node_base*`` moves it past this base subobject
+   to who-knows-where?  The most we can do with that incremented
+   position is to compare another ``node_base*`` to it.  In other
+   words, the original iterator traverses a one-element array.
+
+You probably didn't think of it this way, but the ``node_base*``
+object that underlies ``node_iterator`` is itself an iterator,
+just like all other pointers.  If we examine that pointer closely
+from an iterator perspective, we can see that it has much in common
+with the ``node_iterator`` we're building.  First, they share most
+of the same associated types (``value_type``, ``reference``,
+``pointer``, and ``difference_type``).  Second, even some of the
+core functionality is the same: ``operator*`` and ``operator==`` on
+the ``node_iterator`` return the result of invoking the same
+operations on the underlying pointer, via the ``node_iterator``\ 's
+|dereference_and_equal|_).  The only real behavioral difference
+between ``node_base*`` and ``node_iterator`` can be observed when
+they are incremented: ``node_iterator`` follows the
+``m_next`` pointer, while ``node_base*`` just applies an address offset.   
+
+.. |dereference_and_equal| replace:: ``dereference`` and ``equal`` member functions
+.. _dereference_and_equal: iterator_facade.html#implementing-the-core-operations
+
+It turns out that the pattern of building an iterator on another
+iterator-like type (the ``Base`` [#base]_ type) while modifying
+just a few aspects of the underlying type's behavior is an
+extremely common one, and it's the pattern addressed by
+``iterator_adaptor``.  Using ``iterator_adaptor`` is very much like
+using ``iterator_facade``, but because iterator_adaptor tries to
+mimic as much of the ``Base`` type's behavior as possible, we
+neither have to supply a ``Value`` argument, nor implement any core
+behaviors other than ``increment``.  The implementation of
+``node_iter`` is thus reduced to::
+
+  template <class Value>
+  class node_iter
+    : public boost::iterator_adaptor<
+          node_iter<Value>                // Derived
+        , Value*                          // Base
+        , boost::use_default              // Value
+        , boost::forward_traversal_tag    // CategoryOrTraversal
+      >
+  {
+   private:
+      struct enabler {};  // a private type avoids misuse
+
+   public:
+      node_iter()
+        : node_iter::iterator_adaptor_(0) {}
+
+      explicit node_iter(Value* p)
+        : node_iter::iterator_adaptor_(p) {}
+
+      template <class OtherValue>
+      node_iter(
+          node_iter<OtherValue> const& other
+        , typename boost::enable_if<
+              boost::is_convertible<OtherValue*,Value*>
+            , enabler
+          >::type = enabler()
+      )
+        : node_iter::iterator_adaptor_(other.base()) {}
+
+   private:
+      friend class boost::iterator_core_access;
+      void increment() { this->base_reference() = this->base()->next(); }
+  };
+
+Note the use of ``node_iter::iterator_adaptor_`` here: because
+``iterator_adaptor`` defines a nested ``iterator_adaptor_`` type
+that refers to itself, that gives us a convenient way to refer to
+the complicated base class type of ``node_iter<Value>``. [Note:
+this technique is known not to work with Borland C++ 5.6.4 and
+Metrowerks CodeWarrior versions prior to 9.0]
+
+You can see an example program that exercises this version of the
+node iterators `here`__.
+
+__ ../example/node_iterator3.cpp
+
+In the case of ``node_iter``, it's not very compelling to pass
+``boost::use_default`` as ``iterator_adaptor``\ 's ``Value``
+argument; we could have just passed ``node_iter``\ 's ``Value``
+along to ``iterator_adaptor``, and that'd even be shorter!  Most
+iterator class templates built with ``iterator_adaptor`` are
+parameterized on another iterator type, rather than on its
+``value_type``.  For example, ``boost::reverse_iterator`` takes an
+iterator type argument and reverses its direction of traversal,
+since the original iterator and the reversed one have all the same
+associated types, ``iterator_adaptor``\ 's delegation of default
+types to its ``Base`` saves the implementor of
+``boost::reverse_iterator`` from writing:
+
+.. parsed-literal::
+
+   std::iterator_traits<Iterator>::*some-associated-type*
+
+at least four times.  
+
+We urge you to review the documentation and implementations of
+|reverse_iterator|_ and the other Boost `specialized iterator
+adaptors`__ to get an idea of the sorts of things you can do with
+``iterator_adaptor``.  In particular, have a look at
+|transform_iterator|_, which is perhaps the most straightforward
+adaptor, and also |counting_iterator|_, which demonstrates that
+``iterator_adaptor``\ 's ``Base`` type needn't be an iterator.
+
+.. |reverse_iterator| replace:: ``reverse_iterator``
+.. _reverse_iterator: reverse_iterator.html
+
+.. |counting_iterator| replace:: ``counting_iterator``
+.. _counting_iterator: counting_iterator.html
+
+.. |transform_iterator| replace:: ``transform_iterator``
+.. _transform_iterator: transform_iterator.html
+
+__ index.html#specialized-adaptors
+

doc/iterator_archetypes.html

@@ -0,0 +1,224 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<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.5: http://docutils.sourceforge.net/" />
+<title>Iterator Archetype</title>
+<meta name="author" content="David Abrahams, Jeremy Siek, Thomas Witt" />
+<meta name="organization" content="Boost Consulting, Indiana University Open Systems Lab, Zephyr Associates, Inc." />
+<meta name="date" content="2006-09-11" />
+<meta name="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2004." />
+<link rel="stylesheet" href="../../../rst.css" type="text/css" />
+</head>
+<body>
+<div class="document" id="iterator-archetype">
+<h1 class="title">Iterator Archetype</h1>
+<table class="docinfo" frame="void" rules="none">
+<col class="docinfo-name" />
+<col class="docinfo-content" />
+<tbody valign="top">
+<tr><th class="docinfo-name">Author:</th>
+<td>David Abrahams, Jeremy Siek, Thomas Witt</td></tr>
+<tr><th class="docinfo-name">Contact:</th>
+<td><a class="first reference external" href="mailto:dave&#64;boost-consulting.com">dave&#64;boost-consulting.com</a>, <a class="reference external" href="mailto:jsiek&#64;osl.iu.edu">jsiek&#64;osl.iu.edu</a>, <a class="last reference external" href="mailto:witt&#64;styleadvisor.com">witt&#64;styleadvisor.com</a></td></tr>
+<tr><th class="docinfo-name">Organization:</th>
+<td><a class="first reference external" href="http://www.boost-consulting.com">Boost Consulting</a>, Indiana University <a class="reference external" href="http://www.osl.iu.edu">Open Systems
+Lab</a>, <a class="last reference external" href="http://www.styleadvisor.com">Zephyr Associates, Inc.</a></td></tr>
+<tr><th class="docinfo-name">Date:</th>
+<td>2006-09-11</td></tr>
+<tr><th class="docinfo-name">Copyright:</th>
+<td>Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2004.</td></tr>
+</tbody>
+</table>
+<!-- Distributed under the Boost -->
+<!-- Software License, Version 1.0. (See accompanying -->
+<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
+<table class="docutils field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field"><th class="field-name">abstract:</th><td class="field-body">The <tt class="docutils literal"><span class="pre">iterator_archetype</span></tt> class constructs a minimal implementation of
+one of the iterator access concepts and one of the iterator traversal concepts.
+This is used for doing a compile-time check to see if a the type requirements
+of a template are really enough to cover the implementation of the template.
+For further information see the documentation for the <a class="reference external" href="../../concept_check/index.html"><tt class="docutils literal"><span class="pre">boost::concept_check</span></tt></a> library.</td>
+</tr>
+</tbody>
+</table>
+<div class="contents topic" id="table-of-contents">
+<p class="topic-title first">Table of Contents</p>
+<ul class="simple">
+<li><a class="reference internal" href="#reference" id="id1">Reference</a><ul>
+<li><a class="reference internal" href="#iterator-archetype-synopsis" id="id2"><tt class="docutils literal"><span class="pre">iterator_archetype</span></tt> Synopsis</a></li>
+<li><a class="reference internal" href="#access-category-tags" id="id3"><tt class="docutils literal"><span class="pre">Access</span> <span class="pre">Category</span> <span class="pre">Tags</span></tt></a></li>
+<li><a class="reference internal" href="#iterator-archetype-requirements" id="id4"><tt class="docutils literal"><span class="pre">iterator_archetype</span></tt> Requirements</a></li>
+<li><a class="reference internal" href="#iterator-archetype-models" id="id5"><tt class="docutils literal"><span class="pre">iterator_archetype</span></tt> Models</a></li>
+<li><a class="reference internal" href="#traits" id="id6"><tt class="docutils literal"><span class="pre">Traits</span></tt></a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="reference">
+<h1><a class="toc-backref" href="#id1">Reference</a></h1>
+<div class="section" id="iterator-archetype-synopsis">
+<h2><a class="toc-backref" href="#id2"><tt class="docutils literal"><span class="pre">iterator_archetype</span></tt> Synopsis</a></h2>
+<pre class="literal-block">
+namespace iterator_archetypes
+{
+    // Access categories
+
+    typedef /*implementation  defined*/ readable_iterator_t;
+    typedef /*implementation  defined*/ writable_iterator_t;
+    typedef /*implementation  defined*/ readable_writable_iterator_t;
+    typedef /*implementation  defined*/ readable_lvalue_iterator_t;
+    typedef /*implementation  defined*/ writable_lvalue_iterator_t;
+
+}
+
+template &lt;
+    class Value
+  , class AccessCategory
+  , class TraversalCategory
+&gt;
+class iterator_archetype
+{
+    typedef /* see below */ value_type;
+    typedef /* see below */ reference;
+    typedef /* see below */ pointer;
+    typedef /* see below */ difference_type;
+    typedef /* see below */ iterator_category;
+};
+</pre>
+</div>
+<div class="section" id="access-category-tags">
+<h2><a class="toc-backref" href="#id3"><tt class="docutils literal"><span class="pre">Access</span> <span class="pre">Category</span> <span class="pre">Tags</span></tt></a></h2>
+<p>The access category types provided correspond to the following
+standard iterator access concept combinations:</p>
+<pre class="literal-block">
+readable_iterator_t :=
+
+  Readable Iterator
+
+writable_iterator_t :=
+
+  Writeable Iterator
+
+readable_writable_iterator_t :=
+
+  Readable Iterator &amp; Writeable Iterator &amp; Swappable Iterator
+
+readable_lvalue_iterator_t :=
+
+  Readable Iterator &amp; Lvalue Iterator
+
+writeable_lvalue_iterator_t :=
+
+  Readable Iterator &amp; Writeable Iterator &amp; Swappable Iterator &amp; Lvalue Iterator
+</pre>
+</div>
+<div class="section" id="iterator-archetype-requirements">
+<h2><a class="toc-backref" href="#id4"><tt class="docutils literal"><span class="pre">iterator_archetype</span></tt> Requirements</a></h2>
+<p>The <tt class="docutils literal"><span class="pre">AccessCategory</span></tt> argument must be one of the predefined access
+category tags. The <tt class="docutils literal"><span class="pre">TraversalCategory</span></tt> must be one of the standard
+traversal tags. The <tt class="docutils literal"><span class="pre">Value</span></tt> type must satisfy the requirements of
+the iterator concept specified by <tt class="docutils literal"><span class="pre">AccessCategory</span></tt> and
+<tt class="docutils literal"><span class="pre">TraversalCategory</span></tt> as implied by the nested traits types.</p>
+</div>
+<div class="section" id="iterator-archetype-models">
+<h2><a class="toc-backref" href="#id5"><tt class="docutils literal"><span class="pre">iterator_archetype</span></tt> Models</a></h2>
+<p><tt class="docutils literal"><span class="pre">iterator_archetype</span></tt> models the iterator concepts specified by the
+<tt class="docutils literal"><span class="pre">AccessCategory</span></tt> and <tt class="docutils literal"><span class="pre">TraversalCategory</span></tt>
+arguments. <tt class="docutils literal"><span class="pre">iterator_archetype</span></tt> does not model any other access
+concepts or any more derived traversal concepts.</p>
+</div>
+<div class="section" id="traits">
+<h2><a class="toc-backref" href="#id6"><tt class="docutils literal"><span class="pre">Traits</span></tt></a></h2>
+<p>The nested trait types are defined as follows:</p>
+<pre class="literal-block">
+if (AccessCategory == readable_iterator_t)
+
+  value_type = Value
+  reference  = Value
+  pointer    = Value*
+
+else if (AccessCategory == writable_iterator_t)
+
+  value_type = void
+  reference  = void
+  pointer    = void
+
+else if (AccessCategory == readable_writable_iterator_t)
+
+  value_type = Value
+
+  reference :=
+
+    A type X that is convertible to Value for which the following
+    expression is valid. Given an object x of type X and v of type
+    Value.
+
+    x = v
+
+  pointer    = Value*
+
+else if (AccessCategory == readable_lvalue_iterator_t)
+
+  value_type = Value
+  reference  = Value const&amp;
+  pointer    = Value const*
+
+else if (AccessCategory == writable_lvalue_iterator_t)
+
+  value_type = Value
+  reference  = Value&amp;
+  pointer    = Value*
+
+if ( TraversalCategory is convertible to forward_traversal_tag )
+
+  difference_type := ptrdiff_t
+
+else
+
+  difference_type := unspecified type
+
+
+iterator_category :=
+
+  A type X satisfying the following two constraints:
+
+     1. X is convertible to X1, and not to any more-derived
+        type, where X1 is defined by:
+
+          if (reference is a reference type
+              &amp;&amp; TraversalCategory is convertible to forward_traversal_tag)
+          {
+              if (TraversalCategory is convertible to random_access_traversal_tag)
+                  X1 = random_access_iterator_tag
+              else if (TraversalCategory is convertible to bidirectional_traversal_tag)
+                  X1 = bidirectional_iterator_tag
+              else
+                  X1 = forward_iterator_tag
+          }
+          else
+          {
+              if (TraversalCategory is convertible to single_pass_traversal_tag
+                  &amp;&amp; reference != void)
+                  X1 = input_iterator_tag
+              else
+                  X1 = output_iterator_tag
+          }
+
+     2. X is convertible to TraversalCategory
+</pre>
+</div>
+</div>
+</div>
+<div class="footer">
+<hr class="footer" />
+<a class="reference external" href="iterator_archetypes.rst">View document source</a>.
+Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
+
+</div>
+</body>
+</html>

doc/iterator_archetypes.rst

@@ -0,0 +1,193 @@
+.. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+++++++++++++++++++++
+ Iterator Archetype
+++++++++++++++++++++
+
+:Author: David Abrahams, Jeremy Siek, Thomas Witt
+:Contact: dave@boost-consulting.com, jsiek@osl.iu.edu, witt@styleadvisor.com
+:organization: `Boost Consulting`_, Indiana University `Open Systems
+               Lab`_, `Zephyr Associates, Inc.`_
+:date: $Date$
+:copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2004. 
+
+.. _`Boost Consulting`: http://www.boost-consulting.com
+.. _`Open Systems Lab`: http://www.osl.iu.edu
+.. _`Zephyr Associates, Inc.`: http://www.styleadvisor.com
+
+:abstract: The ``iterator_archetype`` class constructs a minimal implementation of
+  one of the iterator access concepts and one of the iterator traversal concepts.
+  This is used for doing a compile-time check to see if a the type requirements
+  of a template are really enough to cover the implementation of the template.
+  For further information see the documentation for the |concepts|_ library.
+
+.. |concepts| replace:: ``boost::concept_check``
+.. _concepts: ../../concept_check/index.html
+
+
+.. contents:: Table of Contents
+
+Reference
+=========
+
+``iterator_archetype`` Synopsis
+...............................
+
+::
+
+    namespace iterator_archetypes
+    {
+        // Access categories
+
+        typedef /*implementation  defined*/ readable_iterator_t;
+        typedef /*implementation  defined*/ writable_iterator_t;
+        typedef /*implementation  defined*/ readable_writable_iterator_t;
+        typedef /*implementation  defined*/ readable_lvalue_iterator_t;
+        typedef /*implementation  defined*/ writable_lvalue_iterator_t;
+
+    }
+
+    template <
+        class Value
+      , class AccessCategory
+      , class TraversalCategory
+    >
+    class iterator_archetype
+    {
+        typedef /* see below */ value_type;
+        typedef /* see below */ reference;
+        typedef /* see below */ pointer;
+        typedef /* see below */ difference_type;
+        typedef /* see below */ iterator_category;
+    };
+
+``Access Category Tags``
+........................
+
+The access category types provided correspond to the following
+standard iterator access concept combinations:
+
+::
+
+    readable_iterator_t :=
+  
+      Readable Iterator
+
+    writable_iterator_t :=
+  
+      Writeable Iterator
+
+    readable_writable_iterator_t :=
+  
+      Readable Iterator & Writeable Iterator & Swappable Iterator
+
+    readable_lvalue_iterator_t :=
+  
+      Readable Iterator & Lvalue Iterator
+
+    writeable_lvalue_iterator_t :=
+  
+      Readable Iterator & Writeable Iterator & Swappable Iterator & Lvalue Iterator
+
+``iterator_archetype`` Requirements
+...................................
+
+The ``AccessCategory`` argument must be one of the predefined access
+category tags. The ``TraversalCategory`` must be one of the standard
+traversal tags. The ``Value`` type must satisfy the requirements of
+the iterator concept specified by ``AccessCategory`` and
+``TraversalCategory`` as implied by the nested traits types.
+
+``iterator_archetype`` Models
+.............................
+
+``iterator_archetype`` models the iterator concepts specified by the
+``AccessCategory`` and ``TraversalCategory``
+arguments. ``iterator_archetype`` does not model any other access
+concepts or any more derived traversal concepts.
+
+``Traits``
+..........
+
+The nested trait types are defined as follows:
+
+::
+
+   if (AccessCategory == readable_iterator_t)
+     
+     value_type = Value
+     reference  = Value
+     pointer    = Value*
+
+   else if (AccessCategory == writable_iterator_t)
+ 
+     value_type = void
+     reference  = void
+     pointer    = void
+
+   else if (AccessCategory == readable_writable_iterator_t)
+ 
+     value_type = Value
+
+     reference :=
+
+       A type X that is convertible to Value for which the following
+       expression is valid. Given an object x of type X and v of type 
+       Value.
+
+       x = v
+
+     pointer    = Value*
+
+   else if (AccessCategory == readable_lvalue_iterator_t)
+     
+     value_type = Value
+     reference  = Value const&
+     pointer    = Value const*
+
+   else if (AccessCategory == writable_lvalue_iterator_t)
+     
+     value_type = Value
+     reference  = Value&
+     pointer    = Value*
+
+   if ( TraversalCategory is convertible to forward_traversal_tag )
+
+     difference_type := ptrdiff_t
+
+   else
+  
+     difference_type := unspecified type
+
+   
+   iterator_category := 
+
+     A type X satisfying the following two constraints:
+
+        1. X is convertible to X1, and not to any more-derived
+           type, where X1 is defined by:
+
+             if (reference is a reference type
+                 && TraversalCategory is convertible to forward_traversal_tag)
+             {
+                 if (TraversalCategory is convertible to random_access_traversal_tag)
+                     X1 = random_access_iterator_tag
+                 else if (TraversalCategory is convertible to bidirectional_traversal_tag)
+                     X1 = bidirectional_iterator_tag
+                 else
+                     X1 = forward_iterator_tag
+             }
+             else
+             {
+                 if (TraversalCategory is convertible to single_pass_traversal_tag
+                     && reference != void)
+                     X1 = input_iterator_tag
+                 else
+                     X1 = output_iterator_tag
+             }
+
+        2. X is convertible to TraversalCategory
+
+        

doc/iterator_concepts.html

@@ -0,0 +1,127 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<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.5: http://docutils.sourceforge.net/" />
+<title>Iterator Concepts</title>
+<meta name="author" content="David Abrahams, Jeremy Siek, Thomas Witt" />
+<meta name="organization" content="Boost Consulting, Indiana University Open Systems Lab, Zephyr Associates, Inc." />
+<meta name="date" content="2006-09-11" />
+<meta name="copyright" content="Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2004." />
+<link rel="stylesheet" href="../../../rst.css" type="text/css" />
+</head>
+<body>
+<div class="document" id="iterator-concepts">
+<h1 class="title">Iterator Concepts</h1>
+<table class="docinfo" frame="void" rules="none">
+<col class="docinfo-name" />
+<col class="docinfo-content" />
+<tbody valign="top">
+<tr><th class="docinfo-name">Author:</th>
+<td>David Abrahams, Jeremy Siek, Thomas Witt</td></tr>
+<tr><th class="docinfo-name">Contact:</th>
+<td><a class="first reference external" href="mailto:dave&#64;boost-consulting.com">dave&#64;boost-consulting.com</a>, <a class="reference external" href="mailto:jsiek&#64;osl.iu.edu">jsiek&#64;osl.iu.edu</a>, <a class="last reference external" href="mailto:witt&#64;styleadvisor.com">witt&#64;styleadvisor.com</a></td></tr>
+<tr><th class="docinfo-name">Organization:</th>
+<td><a class="first reference external" href="http://www.boost-consulting.com">Boost Consulting</a>, Indiana University <a class="reference external" href="http://www.osl.iu.edu">Open Systems
+Lab</a>, <a class="last reference external" href="http://www.styleadvisor.com">Zephyr Associates, Inc.</a></td></tr>
+<tr><th class="docinfo-name">Date:</th>
+<td>2006-09-11</td></tr>
+<tr><th class="docinfo-name">Copyright:</th>
+<td>Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2004.</td></tr>
+</tbody>
+</table>
+<!-- Distributed under the Boost -->
+<!-- Software License, Version 1.0. (See accompanying -->
+<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
+<table class="docutils field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field"><th class="field-name">abstract:</th><td class="field-body">The iterator concept checking classes provide a mechanism for
+a template to report better error messages when a user instantiates
+the template with a type that does not meet the requirements of
+the template.</td>
+</tr>
+</tbody>
+</table>
+<p>For an introduction to using concept checking classes, see
+the documentation for the <a class="reference external" href="../../concept_check/index.html"><tt class="docutils literal"><span class="pre">boost::concept_check</span></tt></a> library.</p>
+<div class="section" id="reference">
+<h1>Reference</h1>
+<div class="section" id="iterator-access-concepts">
+<h2>Iterator Access Concepts</h2>
+<ul class="simple">
+<li><a class="reference external" href="ReadableIterator.html"><em>Readable Iterator</em></a></li>
+<li><a class="reference external" href="WritableIterator.html"><em>Writable Iterator</em></a></li>
+<li><a class="reference external" href="SwappableIterator.html"><em>Swappable Iterator</em></a></li>
+<li><a class="reference external" href="LvalueIterator.html"><em>Lvalue Iterator</em></a></li>
+</ul>
+</div>
+<div class="section" id="iterator-traversal-concepts">
+<h2>Iterator Traversal Concepts</h2>
+<ul class="simple">
+<li><a class="reference external" href="IncrementableIterator.html"><em>Incrementable Iterator</em></a></li>
+<li><a class="reference external" href="SinglePassIterator.html"><em>Single Pass Iterator</em></a></li>
+<li><a class="reference external" href="ForwardTraversal.html"><em>Forward Traversal</em></a></li>
+<li><a class="reference external" href="BidirectionalTraversal.html"><em>Bidirectional Traversal</em></a></li>
+<li><a class="reference external" href="RandomAccessTraversal.html"><em>Random Access Traversal</em></a></li>
+</ul>
+</div>
+<div class="section" id="iterator-concepts-hpp-synopsis">
+<h2><tt class="docutils literal"><span class="pre">iterator_concepts.hpp</span></tt> Synopsis</h2>
+<pre class="literal-block">
+namespace boost_concepts {
+
+    // Iterator Access Concepts
+
+    template &lt;typename Iterator&gt;
+    class ReadableIteratorConcept;
+
+    template &lt;
+        typename Iterator
+      , typename ValueType = std::iterator_traits&lt;Iterator&gt;::value_type
+    &gt;
+    class WritableIteratorConcept;
+
+    template &lt;typename Iterator&gt;
+    class SwappableIteratorConcept;
+
+    template &lt;typename Iterator&gt;
+    class LvalueIteratorConcept;
+
+    // Iterator Traversal Concepts
+
+    template &lt;typename Iterator&gt;
+    class IncrementableIteratorConcept;
+
+    template &lt;typename Iterator&gt;
+    class SinglePassIteratorConcept;
+
+    template &lt;typename Iterator&gt;
+    class ForwardTraversalConcept;
+
+    template &lt;typename Iterator&gt;
+    class BidirectionalTraversalConcept;
+
+    template &lt;typename Iterator&gt;
+    class RandomAccessTraversalConcept;
+
+    // Interoperability
+
+    template &lt;typename Iterator, typename ConstIterator&gt;
+    class InteroperableIteratorConcept;
+
+}
+</pre>
+</div>
+</div>
+</div>
+<div class="footer">
+<hr class="footer" />
+<a class="reference external" href="iterator_concepts.rst">View document source</a>.
+Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
+
+</div>
+</body>
+</html>

doc/iterator_concepts.rst

@@ -0,0 +1,130 @@
+.. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+++++++++++++++++++
+ Iterator Concepts
+++++++++++++++++++
+
+:Author: David Abrahams, Jeremy Siek, Thomas Witt
+:Contact: dave@boost-consulting.com, jsiek@osl.iu.edu, witt@styleadvisor.com
+:organization: `Boost Consulting`_, Indiana University `Open Systems
+               Lab`_, `Zephyr Associates, Inc.`_
+:date: $Date$
+:copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2004. 
+
+.. _`Boost Consulting`: http://www.boost-consulting.com
+.. _`Open Systems Lab`: http://www.osl.iu.edu
+.. _`Zephyr Associates, Inc.`: http://www.styleadvisor.com
+
+:abstract:  The iterator concept checking classes provide a mechanism for
+  a template to report better error messages when a user instantiates
+  the template with a type that does not meet the requirements of
+  the template.
+
+
+For an introduction to using concept checking classes, see
+the documentation for the |concepts|_ library.
+
+.. |concepts| replace:: ``boost::concept_check``
+.. _concepts: ../../concept_check/index.html
+
+
+Reference
+=========
+
+Iterator Access Concepts
+........................
+
+* |Readable|_ 
+* |Writable|_ 
+* |Swappable|_ 
+* |Lvalue|_ 
+
+.. |Readable| replace:: *Readable Iterator*
+.. _Readable: ReadableIterator.html
+
+.. |Writable| replace:: *Writable Iterator*
+.. _Writable: WritableIterator.html
+
+.. |Swappable| replace:: *Swappable Iterator*
+.. _Swappable: SwappableIterator.html
+
+.. |Lvalue| replace:: *Lvalue Iterator*
+.. _Lvalue: LvalueIterator.html
+
+
+Iterator Traversal Concepts
+...........................
+
+* |Incrementable|_
+* |SinglePass|_
+* |Forward|_
+* |Bidir|_
+* |Random|_
+
+
+.. |Incrementable| replace:: *Incrementable Iterator*
+.. _Incrementable: IncrementableIterator.html
+
+.. |SinglePass| replace:: *Single Pass Iterator*
+.. _SinglePass: SinglePassIterator.html
+
+.. |Forward| replace:: *Forward Traversal*
+.. _Forward: ForwardTraversal.html
+
+.. |Bidir| replace:: *Bidirectional Traversal*
+.. _Bidir: BidirectionalTraversal.html
+
+.. |Random| replace:: *Random Access Traversal*
+.. _Random: RandomAccessTraversal.html
+
+
+
+``iterator_concepts.hpp`` Synopsis
+..................................
+
+::
+
+    namespace boost_concepts {
+
+        // Iterator Access Concepts
+
+        template <typename Iterator>
+        class ReadableIteratorConcept;
+
+        template <
+            typename Iterator
+          , typename ValueType = std::iterator_traits<Iterator>::value_type
+        >
+        class WritableIteratorConcept;
+
+        template <typename Iterator>
+        class SwappableIteratorConcept;
+
+        template <typename Iterator>
+        class LvalueIteratorConcept;
+
+        // Iterator Traversal Concepts
+
+        template <typename Iterator>
+        class IncrementableIteratorConcept;
+
+        template <typename Iterator>
+        class SinglePassIteratorConcept;
+
+        template <typename Iterator>
+        class ForwardTraversalConcept;
+
+        template <typename Iterator>
+        class BidirectionalTraversalConcept;
+
+        template <typename Iterator>
+        class RandomAccessTraversalConcept;
+
+        // Interoperability
+
+        template <typename Iterator, typename ConstIterator>
+        class InteroperableIteratorConcept;
+
+    }

doc/iterator_facade.rst

@@ -1,3 +1,7 @@
+.. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
 ++++++++++++++++
  Iterator Facade
 ++++++++++++++++
@@ -8,7 +12,7 @@
                Lab`_, University of Hanover `Institute for Transport
                Railway Operation and Construction`_
 :date: $Date$
-:copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All rights reserved
+:copyright: Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. 
 
 .. _`Boost Consulting`: http://www.boost-consulting.com
 .. _`Open Systems Lab`: http://www.osl.iu.edu
@@ -16,20 +20,25 @@
 
 :abstract:
 
-.. include:: iterator_facade_abstract.rst
+  .. include:: iterator_facade_abstract.rst
 
 .. contents:: Table of Contents
 
-
-Motivation
-----------
+Overview
+========
 
 .. include:: iterator_facade_body.rst
 
 
 Reference
----------
+=========
 
 .. include:: iterator_facade_ref.rst
 
 .. _counting: counting_iterator.html
+
+Tutorial Example
+================
+
+.. include:: iterator_facade_tutorial.rst
+

doc/iterator_facade_abstract.rst

@@ -1,3 +1,7 @@
+.. Copyright David Abrahams 2006. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
 ``iterator_facade`` is a base class template that implements the
 interface of standard iterators in terms of a few core functions
 and associated types, to be supplied by a derived iterator class.

doc/iterator_facade_body.rst

@@ -1,8 +1,11 @@
+.. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
 .. Version 1.1 of this ReStructuredText document corresponds to
    n1530_, the paper accepted by the LWG for TR1.
 
-.. Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All
-   rights reserved
+.. Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. 
 
 
 While the iterator interface is rich, there is a core subset of the
@@ -21,11 +24,11 @@ include the associated types exposed through iterator traits:
 ``value_type``, ``reference``, ``difference_type``, and
 ``iterator_category``.
 
-Iterator facade uses the Curiously Recurring Template Pattern (CRTP)
-[Cop95]_ so that the user can specify the behavior of
-``iterator_facade`` in a derived class.  Former designs used policy
-objects to specify the behavior.  ``iterator_facade`` does not use policy
-objects for several reasons: 
+Iterator facade uses the Curiously Recurring Template
+Pattern (CRTP) [Cop95]_ so that the user can specify the behavior
+of ``iterator_facade`` in a derived class.  Former designs used
+policy objects to specify the behavior, but that approach was
+discarded for several reasons:
 
   1. the creation and eventual copying of the policy object may create
      overhead that can be avoided with the current approach.
@@ -36,9 +39,11 @@ objects for several reasons:
      implementations.
 
   3. Without the use of CRTP, the standard requirement that an
-     iterator's ``operator++`` returns the iterator type itself means
-     that all iterators generated by ``iterator_facade`` would be
-     specializations of ``iterator_facade``.  Cumbersome type generator
+     iterator's ``operator++`` returns the iterator type itself
+     would mean that all iterators built with the library would
+     have to be specializations of ``iterator_facade<...>``, rather
+     than something more descriptive like
+     ``indirect_iterator<T*>``.  Cumbersome type generator
      metafunctions would be needed to build new parameterized
      iterators, and a separate ``iterator_adaptor`` layer would be
      impossible.
@@ -46,14 +51,15 @@ objects for several reasons:
 Usage
 -----
 
-The user of ``iterator_facade`` derives his iterator class from an
-specialization of ``iterator_facade`` which takes the derived iterator
-class as the first template parameter.  The order of the other
-template parameters to ``iterator_facade`` have been carefully chosen
-to take advantage of useful defaults.  For example, when defining a
-constant lvalue iterator, the user can pass a const-qualified version
-of the iterator's ``value_type`` as ``iterator_facade``\ 's ``Value``
-parameter and omit the ``Reference`` parameter which follows.
+The user of ``iterator_facade`` derives his iterator class from a
+specialization of ``iterator_facade`` and passes the derived
+iterator class as ``iterator_facade``\ 's first template parameter.
+The order of the other template parameters have been carefully
+chosen to take advantage of useful defaults.  For example, when
+defining a constant lvalue iterator, the user can pass a
+const-qualified version of the iterator's ``value_type`` as
+``iterator_facade``\ 's ``Value`` parameter and omit the
+``Reference`` parameter which follows.
 
 The derived iterator class must define member functions implementing
 the iterator's core behaviors.  The following table describes
@@ -150,18 +156,20 @@ into the temporary iterator ``p+n``, which is destroyed when
 
 Writable iterators built with ``iterator_facade`` implement the
 semantics required by the preferred resolution to `issue 299`_ and
-adopted by proposal n1550_: the result of ``p[n]`` is a proxy object
-containing a copy of ``p+n``, and ``p[n] = x`` is equivalent to ``*(p
-+ n) = x``.  This approach will work properly for any random-access
-iterator regardless of the other details of its implementation.  A
-user who knows more about the implementation of her iterator is free
-to implement an ``operator[]`` which returns an lvalue in the derived
-iterator class; it will hide the one supplied by ``iterator_facade``
-from clients of her iterator.
+adopted by proposal n1550_: the result of ``p[n]`` is an object
+convertible to the iterator's ``value_type``, and ``p[n] = x`` is
+equivalent to ``*(p + n) = x`` (Note: This result object may be
+implemented as a proxy containing a copy of ``p+n``).  This approach
+will work properly for any random-access iterator regardless of the
+other details of its implementation.  A user who knows more about
+the implementation of her iterator is free to implement an
+``operator[]`` that returns an lvalue in the derived iterator
+class; it will hide the one supplied by ``iterator_facade`` from
+clients of her iterator.
 
-.. _n1550: http://anubis.dkuug.dk/JTC1/SC22/WG21/docs/papers/2003/n1550.html
+.. _n1550: http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2003/n1550.htm
 
-.. _`issue 299`: http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/lwg-active.html#299
+.. _`issue 299`: http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-active.html#299
 
 .. _`operator arrow`:
 
@@ -177,10 +185,10 @@ through ``operator->``.  Therefore, an iterator whose ``reference``
 type is not in fact a reference must return a proxy containing a copy
 of the referenced value from its ``operator->``.
 
-The return type for ``operator->`` and ``operator[]`` is not
-explicitly specified. Instead it requires each ``iterator_facade``
-specialization to meet the requirements of its ``iterator_category``.
-
+The return types for ``iterator_facade``\ 's ``operator->`` and
+``operator[]`` are not explicitly specified. Instead, those types
+are described in terms of a set of requirements, which must be
+satisfied by the ``iterator_facade`` implementation.
 
 .. [Cop95] [Coplien, 1995] Coplien, J., Curiously Recurring Template
    Patterns, C++ Report, February 1995, pp. 24-27.

doc/iterator_facade_ref.rst

@@ -1,8 +1,11 @@
+.. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
 .. Version 1.3 of this ReStructuredText document corresponds to
    n1530_, the paper accepted by the LWG for TR1.
 
-.. Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. All
-   rights reserved
+.. Copyright David Abrahams, Jeremy Siek, and Thomas Witt 2003. 
 
 
 .. parsed-literal::
@@ -15,10 +18,10 @@
     , class Difference = ptrdiff_t
   >
   class iterator_facade {
-  public:
+   public:
       typedef remove_const<Value>::type value_type;
       typedef Reference reference;
-      typedef Value* pointer;
+      typedef Value\* pointer;
       typedef Difference difference_type;
       typedef /* see below__ \*/ iterator_category;
 
@@ -32,72 +35,85 @@
       Derived& operator+=(difference_type n);
       Derived& operator-=(difference_type n);
       Derived operator-(difference_type n) const;
+   protected:
+      typedef iterator_facade iterator_facade\_;
   };
 
   // Comparison operators
   template <class Dr1, class V1, class TC1, class R1, class D1,
             class Dr2, class V2, class TC2, class R2, class D2>
-  typename enable_if_interoperable<Dr1, Dr2, bool>::type // exposition
-  operator ==(iterator_facade<Dr1, V1, TC1, R1, D1> const& lhs,
-              iterator_facade<Dr2, V2, TC2, R2, D2> const& rhs);
+  typename enable_if_interoperable<Dr1,Dr2,bool>::type // exposition
+  operator ==(iterator_facade<Dr1,V1,TC1,R1,D1> const& lhs,
+              iterator_facade<Dr2,V2,TC2,R2,D2> const& rhs);
 
   template <class Dr1, class V1, class TC1, class R1, class D1,
             class Dr2, class V2, class TC2, class R2, class D2>
-  typename enable_if_interoperable<Dr1, Dr2, bool>::type
-  operator !=(iterator_facade<Dr1, V1, TC1, R1, D1> const& lhs,
-              iterator_facade<Dr2, V2, TC2, R2, D2> const& rhs);
+  typename enable_if_interoperable<Dr1,Dr2,bool>::type
+  operator !=(iterator_facade<Dr1,V1,TC1,R1,D1> const& lhs,
+              iterator_facade<Dr2,V2,TC2,R2,D2> const& rhs);
 
   template <class Dr1, class V1, class TC1, class R1, class D1,
             class Dr2, class V2, class TC2, class R2, class D2>
-  typename enable_if_interoperable<Dr1, Dr2, bool>::type
-  operator <(iterator_facade<Dr1, V1, TC1, R1, D1> const& lhs,
-             iterator_facade<Dr2, V2, TC2, R2, D2> const& rhs);
+  typename enable_if_interoperable<Dr1,Dr2,bool>::type
+  operator <(iterator_facade<Dr1,V1,TC1,R1,D1> const& lhs,
+             iterator_facade<Dr2,V2,TC2,R2,D2> const& rhs);
 
   template <class Dr1, class V1, class TC1, class R1, class D1,
             class Dr2, class V2, class TC2, class R2, class D2>
-  typename enable_if_interoperable<Dr1, Dr2, bool>::type
-  operator <=(iterator_facade<Dr1, V1, TC1, R1, D1> const& lhs,
-              iterator_facade<Dr2, V2, TC2, R2, D2> const& rhs);
+  typename enable_if_interoperable<Dr1,Dr2,bool>::type
+  operator <=(iterator_facade<Dr1,V1,TC1,R1,D1> const& lhs,
+              iterator_facade<Dr2,V2,TC2,R2,D2> const& rhs);
 
   template <class Dr1, class V1, class TC1, class R1, class D1,
             class Dr2, class V2, class TC2, class R2, class D2>
-  typename enable_if_interoperable<Dr1, Dr2, bool>::type
-  operator >(iterator_facade<Dr1, V1, TC1, R1, D1> const& lhs,
-             iterator_facade<Dr2, V2, TC2, R2, D2> const& rhs);
+  typename enable_if_interoperable<Dr1,Dr2,bool>::type
+  operator >(iterator_facade<Dr1,V1,TC1,R1,D1> const& lhs,
+             iterator_facade<Dr2,V2,TC2,R2,D2> const& rhs);
 
   template <class Dr1, class V1, class TC1, class R1, class D1,
             class Dr2, class V2, class TC2, class R2, class D2>
-  typename enable_if_interoperable<Dr1, Dr2, bool>::type
-  operator >=(iterator_facade<Dr1, V1, TC1, R1, D1> const& lhs,
-              iterator_facade<Dr2, V2, TC2, R2, D2> const& rhs);
-
-  template <class Dr1, class V1, class TC1, class R1, class D1,
-            class Dr2, class V2, class TC2, class R2, class D2>
-  typename enable_if_interoperable<Dr1, Dr2, bool>::type
-  operator >=(iterator_facade<Dr1, V1, TC1, R1, D1> const& lhs,
-              iterator_facade<Dr2, V2, TC2, R2, D2> const& rhs);
+  typename enable_if_interoperable<Dr1,Dr2,bool>::type
+  operator >=(iterator_facade<Dr1,V1,TC1,R1,D1> const& lhs,
+              iterator_facade<Dr2,V2,TC2,R2,D2> const& rhs);
 
   // Iterator difference
   template <class Dr1, class V1, class TC1, class R1, class D1,
             class Dr2, class V2, class TC2, class R2, class D2>
-  typename enable_if_interoperable<Dr1, Dr2, bool>::type
-  operator -(iterator_facade<Dr1, V1, TC1, R1, D1> const& lhs,
-             iterator_facade<Dr2, V2, TC2, R2, D2> const& rhs);
+  /* see below__ \*/
+  operator-(iterator_facade<Dr1,V1,TC1,R1,D1> const& lhs,
+            iterator_facade<Dr2,V2,TC2,R2,D2> const& rhs);
 
   // Iterator addition
-  template <class Derived, class V, class TC, class R, class D>
-  Derived operator+ (iterator_facade<Derived, V, TC, R, D> const&,
-                     typename Derived::difference_type n)
+  template <class Dr, class V, class TC, class R, class D>
+  Derived operator+ (iterator_facade<Dr,V,TC,R,D> const&,
+                     typename Derived::difference_type n);
 
+  template <class Dr, class V, class TC, class R, class D>
+  Derived operator+ (typename Derived::difference_type n,
+                     iterator_facade<Dr,V,TC,R,D> const&);
 
-__ `facade iterator category`_
+__ `iterator category`_
 
 __ `operator arrow`_
 
 __ brackets_
 
+__ minus_
+
+.. _`iterator category`:
+
+The ``iterator_category`` member of ``iterator_facade`` is
+
+.. parsed-literal::
+
+  *iterator-category*\ (CategoryOrTraversal, reference, value_type)
+
+where *iterator-category* is defined as follows:
+
+.. include:: facade_iterator_category.rst
+
 The ``enable_if_interoperable`` template used above is for exposition
-purposes.  The member operators should be only be in an overload set
+purposes.  The member operators should only be in an overload set
 provided the derived types ``Dr1`` and ``Dr2`` are interoperable, 
 meaning that at least one of the types is convertible to the other.  The
 ``enable_if_interoperable`` approach uses SFINAE to take the operators
@@ -120,14 +136,15 @@ were defined to be::
   {};
 
 
-``iterator_facade`` usage
-.........................
+``iterator_facade`` Requirements
+--------------------------------
 
 The following table describes the typical valid expressions on
 ``iterator_facade``\ 's ``Derived`` parameter, depending on the
 iterator concept(s) it will model.  The operations in the first
 column must be made accessible to member functions of class
-``iterator_core_access``.
+``iterator_core_access``.  In addition,
+``static_cast<Derived*>(iterator_facade*)`` shall be well-formed.
 
 In the table below, ``F`` is ``iterator_facade<X,V,C,R,D>``, ``a`` is an
 object of type ``X``, ``b`` and ``c`` are objects of type ``const X``,
@@ -136,88 +153,37 @@ object of a single pass iterator type interoperable with ``X``, and ``z``
 is a constant object of a random access traversal iterator type
 interoperable with ``X``.
 
-+--------------------+----------------------+-------------------------------------+---------------------------+
-|Expression          |Return Type           |Assertion/Note                       |Used to implement Iterator |
-|                    |                      |                                     |Concept(s)                 |
-+====================+======================+=====================================+===========================+
-|``c.dereference()`` |``F::reference``      |                                     |Readable Iterator, Writable|
-|                    |                      |                                     |Iterator                   |
-+--------------------+----------------------+-------------------------------------+---------------------------+
-|``c.equal(b)``      |convertible to bool   |true iff ``b`` and ``c`` are         |Single Pass Iterator       |
-|                    |                      |equivalent.                          |                           |
-+--------------------+----------------------+-------------------------------------+---------------------------+
-|``c.equal(y)``      |convertible to bool   |true iff ``c`` and ``y`` refer to the|Single Pass Iterator       |
-|                    |                      |same position.  Implements ``c == y``|                           |
-|                    |                      |and ``c != y``.                      |                           |
-+--------------------+----------------------+-------------------------------------+---------------------------+
-|``a.advance(n)``    |unused                |                                     |Random Access Traversal    |
-|                    |                      |                                     |Iterator                   |
-+--------------------+----------------------+-------------------------------------+---------------------------+
-|``a.increment()``   |unused                |                                     |Incrementable Iterator     |
-+--------------------+----------------------+-------------------------------------+---------------------------+
-|``a.decrement()``   |unused                |                                     |Bidirectional Traversal    |
-|                    |                      |                                     |Iterator                   |
-+--------------------+----------------------+-------------------------------------+---------------------------+
-|``c.distance_to(b)``|convertible to        |equivalent to ``distance(c, b)``     |Random Access Traversal    |
-|                    |``F::difference_type``|                                     |Iterator                   |
-+--------------------+----------------------+-------------------------------------+---------------------------+
-|``c.distance_to(z)``|convertible to        |equivalent to ``distance(c, z)``.    |Random Access Traversal    |
-|                    |``F::difference_type``|Implements ``c - z``, ``c < z``, ``c |Iterator                   |
-|                    |                      |<= z``, ``c > z``, and ``c >= c``.   |                           |
-+--------------------+----------------------+-------------------------------------+---------------------------+
+.. _`core operations`:
 
-.. _facade iterator category:
+.. topic:: ``iterator_facade`` Core Operations
 
-``iterator_facade`` iterator category
-.....................................
+   +--------------------+----------------------+-------------------------+---------------------------+
+   |Expression          |Return Type           |Assertion/Note           |Used to implement Iterator |
+   |                    |                      |                         |Concept(s)                 |
+   +====================+======================+=========================+===========================+
+   |``c.dereference()`` |``F::reference``      |                         |Readable Iterator, Writable|
+   |                    |                      |                         |Iterator                   |
+   +--------------------+----------------------+-------------------------+---------------------------+
+   |``c.equal(y)``      |convertible to bool   |true iff ``c`` and ``y`` |Single Pass Iterator       |
+   |                    |                      |refer to the same        |                           |
+   |                    |                      |position.                |                           |
+   +--------------------+----------------------+-------------------------+---------------------------+
+   |``a.increment()``   |unused                |                         |Incrementable Iterator     |
+   +--------------------+----------------------+-------------------------+---------------------------+
+   |``a.decrement()``   |unused                |                         |Bidirectional Traversal    |
+   |                    |                      |                         |Iterator                   |
+   +--------------------+----------------------+-------------------------+---------------------------+
+   |``a.advance(n)``    |unused                |                         |Random Access Traversal    |
+   |                    |                      |                         |Iterator                   |
+   +--------------------+----------------------+-------------------------+---------------------------+
+   |``c.distance_to(z)``|convertible to        |equivalent to            |Random Access Traversal    |
+   |                    |``F::difference_type``|``distance(c, X(z))``.   |Iterator                   |
+   +--------------------+----------------------+-------------------------+---------------------------+
 
-The ``iterator_category`` member of ``iterator_facade<X,V,R,C,D>``
-is a type which satisfies the following conditions:
-
-   * if ``C`` is convertible to ``std::input_iterator_tag`` or
-     ``C`` is convertible to ``std::output_iterator_tag``,
-     ``iterator_category`` is the same as ``C``.  
-
-   * Otherwise, if ``C`` is not convertible to
-     ``incrementable_traversal_tag``, the program is ill-formed 
-
-   * Otherwise:
-
-     - ``iterator_category`` is convertible to the iterator
-       category tag or tags given by the following algorithm, and
-       not to any more-derived iterator category tag or tags::
-
-         if (R is a reference type
-             && C is convertible to forward_traversal_tag)
-         {
-             if (C is convertible to random_access_traversal_tag)
-                 return random_access_iterator_tag
-             else if (C is convertible to bidirectional_traversal_tag)
-                 return bidirectional_iterator_tag
-             else
-                 return forward_traversal_tag
-         }
-         else
-         {
-             if (C is convertible to single_pass_traversal_tag
-                 && R is convertible to V)
-             {
-                 if (V is const)
-                     return input_iterator_tag
-                 else
-                     return input_iterator_tag and output_iterator_tag
-             }
-             else
-                 return output_iterator_tag
-         }
-
-     - ``iterator_traversal<X>::type`` is convertible to the most
-       derived traversal tag type to which ``C`` is also
-       convertible, and not to any more-derived traversal tag type.
 
 
 ``iterator_facade`` operations
-..............................
+------------------------------
 
 The operations in this section are described in terms of operations on
 the core interface of ``Derived`` which may be inaccessible
@@ -245,10 +211,12 @@ __ `operator arrow`_
 
 *unspecified* ``operator[](difference_type n) const;``
 
-:Returns: an object convertible to ``reference`` and holding a copy
-     *p* of ``*static_cast<Derived const*>(this) + n`` such that, for a constant object ``v`` of type
-     ``value_type``, ``(*static_cast<Derived const*>(this))[n] = v`` is equivalent
-     to ``p = v``.
+:Returns: an object convertible to ``value_type``. For constant
+     objects ``v`` of type ``value_type``, and ``n`` of type
+     ``difference_type``, ``(*this)[n] = v`` is equivalent to
+     ``*(*this + n) = v``, and ``static_cast<value_type
+     const&>((*this)[n])`` is equivalent to
+     ``static_cast<value_type const&>(*(*this + n))``
 
 
 
@@ -279,7 +247,7 @@ __ `operator arrow`_
    ::
 
       static_cast<Derived*>(this)->decrement();
-      return static_cast<Derived*>(this);
+      return *static_cast<Derived*>(this);
 
 
 ``Derived operator--(int);``
@@ -300,7 +268,7 @@ __ `operator arrow`_
   ::
 
       static_cast<Derived*>(this)->advance(n);
-      return static_cast<Derived*>(this);
+      return *static_cast<Derived*>(this);
 
 
 ``Derived& operator-=(difference_type n);``
@@ -310,7 +278,7 @@ __ `operator arrow`_
   ::
 
       static_cast<Derived*>(this)->advance(-n);
-      return static_cast<Derived*>(this);
+      return *static_cast<Derived*>(this);
 
 
 ``Derived operator-(difference_type n) const;``
@@ -319,8 +287,155 @@ __ `operator arrow`_
 
   ::
 
-   Derived tmp(static_cast<Derived const*>(this));
-   return tmp -= n;
+    Derived tmp(static_cast<Derived const*>(this));
+    return tmp -= n;
+
+::
+
+  template <class Dr, class V, class TC, class R, class D>
+  Derived operator+ (iterator_facade<Dr,V,TC,R,D> const&,
+                     typename Derived::difference_type n);
+
+  template <class Dr, class V, class TC, class R, class D>
+  Derived operator+ (typename Derived::difference_type n,
+                     iterator_facade<Dr,V,TC,R,D> const&);
+
+:Effects:
+
+  ::
+
+    Derived tmp(static_cast<Derived const*>(this));
+    return tmp += n;
 
 
+::
 
+  template <class Dr1, class V1, class TC1, class R1, class D1,
+            class Dr2, class V2, class TC2, class R2, class D2>
+  typename enable_if_interoperable<Dr1,Dr2,bool>::type
+  operator ==(iterator_facade<Dr1,V1,TC1,R1,D1> const& lhs,
+              iterator_facade<Dr2,V2,TC2,R2,D2> const& rhs);
+
+:Returns: 
+  if ``is_convertible<Dr2,Dr1>::value``
+
+  then 
+    ``((Dr1 const&)lhs).equal((Dr2 const&)rhs)``.
+
+  Otherwise, 
+    ``((Dr2 const&)rhs).equal((Dr1 const&)lhs)``.
+
+::
+
+  template <class Dr1, class V1, class TC1, class R1, class D1,
+            class Dr2, class V2, class TC2, class R2, class D2>
+  typename enable_if_interoperable<Dr1,Dr2,bool>::type
+  operator !=(iterator_facade<Dr1,V1,TC1,R1,D1> const& lhs,
+              iterator_facade<Dr2,V2,TC2,R2,D2> const& rhs);
+
+:Returns: 
+  if ``is_convertible<Dr2,Dr1>::value``
+
+  then 
+    ``!((Dr1 const&)lhs).equal((Dr2 const&)rhs)``.
+
+  Otherwise, 
+    ``!((Dr2 const&)rhs).equal((Dr1 const&)lhs)``.
+
+::
+
+  template <class Dr1, class V1, class TC1, class R1, class D1,
+            class Dr2, class V2, class TC2, class R2, class D2>
+  typename enable_if_interoperable<Dr1,Dr2,bool>::type
+  operator <(iterator_facade<Dr1,V1,TC1,R1,D1> const& lhs,
+             iterator_facade<Dr2,V2,TC2,R2,D2> const& rhs);
+
+:Returns: 
+  if ``is_convertible<Dr2,Dr1>::value``
+
+  then 
+    ``((Dr1 const&)lhs).distance_to((Dr2 const&)rhs) < 0``.
+
+  Otherwise, 
+    ``((Dr2 const&)rhs).distance_to((Dr1 const&)lhs) > 0``.
+
+::
+
+  template <class Dr1, class V1, class TC1, class R1, class D1,
+            class Dr2, class V2, class TC2, class R2, class D2>
+  typename enable_if_interoperable<Dr1,Dr2,bool>::type
+  operator <=(iterator_facade<Dr1,V1,TC1,R1,D1> const& lhs,
+              iterator_facade<Dr2,V2,TC2,R2,D2> const& rhs);
+
+:Returns: 
+  if ``is_convertible<Dr2,Dr1>::value``
+
+  then 
+    ``((Dr1 const&)lhs).distance_to((Dr2 const&)rhs) <= 0``.
+
+  Otherwise, 
+    ``((Dr2 const&)rhs).distance_to((Dr1 const&)lhs) >= 0``.
+
+::
+
+  template <class Dr1, class V1, class TC1, class R1, class D1,
+            class Dr2, class V2, class TC2, class R2, class D2>
+  typename enable_if_interoperable<Dr1,Dr2,bool>::type
+  operator >(iterator_facade<Dr1,V1,TC1,R1,D1> const& lhs,
+             iterator_facade<Dr2,V2,TC2,R2,D2> const& rhs);
+
+:Returns: 
+  if ``is_convertible<Dr2,Dr1>::value``
+
+  then 
+    ``((Dr1 const&)lhs).distance_to((Dr2 const&)rhs) > 0``.
+
+  Otherwise, 
+    ``((Dr2 const&)rhs).distance_to((Dr1 const&)lhs) < 0``.
+
+
+::
+
+  template <class Dr1, class V1, class TC1, class R1, class D1,
+            class Dr2, class V2, class TC2, class R2, class D2>
+  typename enable_if_interoperable<Dr1,Dr2,bool>::type
+  operator >=(iterator_facade<Dr1,V1,TC1,R1,D1> const& lhs,
+              iterator_facade<Dr2,V2,TC2,R2,D2> const& rhs);
+
+:Returns: 
+  if ``is_convertible<Dr2,Dr1>::value``
+
+  then 
+    ``((Dr1 const&)lhs).distance_to((Dr2 const&)rhs) >= 0``.
+
+  Otherwise, 
+    ``((Dr2 const&)rhs).distance_to((Dr1 const&)lhs) <= 0``.
+
+.. _minus:
+
+::
+
+  template <class Dr1, class V1, class TC1, class R1, class D1,
+            class Dr2, class V2, class TC2, class R2, class D2>
+  typename enable_if_interoperable<Dr1,Dr2,difference>::type
+  operator -(iterator_facade<Dr1,V1,TC1,R1,D1> const& lhs,
+             iterator_facade<Dr2,V2,TC2,R2,D2> const& rhs);
+
+:Return Type: 
+  if ``is_convertible<Dr2,Dr1>::value``
+
+   then 
+    ``difference`` shall be
+    ``iterator_traits<Dr1>::difference_type``.
+
+   Otherwise 
+    ``difference`` shall be ``iterator_traits<Dr2>::difference_type``
+
+:Returns: 
+  if ``is_convertible<Dr2,Dr1>::value``
+
+  then 
+    ``-((Dr1 const&)lhs).distance_to((Dr2 const&)rhs)``.
+
+  Otherwise, 
+    ``((Dr2 const&)rhs).distance_to((Dr1 const&)lhs)``.

doc/iterator_facade_tutorial.rst

@@ -0,0 +1,523 @@
+.. Copyright David Abrahams 2004. Use, modification and distribution is
+.. subject to the Boost Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+In this section we'll walk through the implementation of a few
+iterators using ``iterator_facade``, based around the simple
+example of a linked list of polymorphic objects.  This example was
+inspired by a `posting`__ by Keith Macdonald on the `Boost-Users`_
+mailing list.
+
+.. _`Boost-Users`: http://www.boost.org/more/mailing_lists.htm#users
+
+__ http://thread.gmane.org/gmane.comp.lib.boost.user/5100
+
+The Problem
+-----------
+
+Say we've written a polymorphic linked list node base class::
+
+  # include <iostream>
+
+  struct node_base
+  {
+      node_base() : m_next(0) {}
+
+      // Each node manages all of its tail nodes
+      virtual ~node_base() { delete m_next; }
+
+      // Access the rest of the list
+      node_base* next() const { return m_next; }
+
+      // print to the stream
+      virtual void print(std::ostream& s) const = 0;
+      
+      // double the value
+      virtual void double_me() = 0;
+
+      void append(node_base* p)
+      {
+          if (m_next) 
+              m_next->append(p); 
+          else
+              m_next = p; 
+      }
+
+   private:
+      node_base* m_next;
+  };
+
+Lists can hold objects of different types by linking together
+specializations of the following template::
+
+  template <class T>
+  struct node : node_base
+  {
+      node(T x)
+        : m_value(x)
+      {}
+
+      void print(std::ostream& s) const { s << this->m_value; }
+      void double_me() { m_value += m_value; }
+
+   private:
+      T m_value;
+  };
+
+And we can print any node using the following streaming operator::
+
+  inline std::ostream& operator<<(std::ostream& s, node_base const& n)
+  {
+      n.print(s);
+      return s;
+  }
+
+Our first challenge is to build an appropriate iterator over these
+lists.
+
+A Basic Iterator Using ``iterator_facade``
+------------------------------------------
+
+We will construct a ``node_iterator`` class using inheritance from
+``iterator_facade`` to implement most of the iterator's operations.
+
+::
+
+  # include "node.hpp"
+  # include <boost/iterator/iterator_facade.hpp>
+
+  class node_iterator
+    : public boost::iterator_facade<...>
+  {
+     ...
+  };
+
+
+
+Template Arguments for ``iterator_facade``
+..........................................
+
+``iterator_facade`` has several template parameters, so we must decide
+what types to use for the arguments. The parameters are ``Derived``,
+``Value``, ``CategoryOrTraversal``, ``Reference``, and ``Difference``.
+
+
+``Derived``
+'''''''''''
+
+Because ``iterator_facade`` is meant to be used with the CRTP
+[Cop95]_ the first parameter is the iterator class name itself,
+``node_iterator``.
+
+``Value``
+'''''''''
+
+The ``Value`` parameter determines the ``node_iterator``\ 's
+``value_type``.  In this case, we are iterating over ``node_base``
+objects, so ``Value`` will be ``node_base``.
+
+
+``CategoryOrTraversal``
+'''''''''''''''''''''''
+
+Now we have to determine which `iterator traversal concept`_ our
+``node_iterator`` is going to model.  Singly-linked lists only have
+forward links, so our iterator can't can't be a `bidirectional
+traversal iterator`_.  Our iterator should be able to make multiple
+passes over the same linked list (unlike, say, an
+``istream_iterator`` which consumes the stream it traverses), so it
+must be a `forward traversal iterator`_.  Therefore, we'll pass
+``boost::forward_traversal_tag`` in this position [#category]_.
+
+.. [#category] ``iterator_facade`` also supports old-style category
+   tags, so we could have passed ``std::forward_iterator_tag`` here;
+   either way, the resulting iterator's ``iterator_category`` will
+   end up being ``std::forward_iterator_tag``.
+
+``Reference``
+'''''''''''''
+
+The ``Reference`` argument becomes the type returned by
+``node_iterator``\ 's dereference operation, and will also be the
+same as ``std::iterator_traits<node_iterator>::reference``.  The
+library's default for this parameter is ``Value&``; since
+``node_base&`` is a good choice for the iterator's ``reference``
+type, we can omit this argument, or pass ``use_default``.
+
+``Difference``
+''''''''''''''
+
+The ``Difference`` argument determines how the distance between
+two ``node_iterator``\ s will be measured and will also be the
+same as ``std::iterator_traits<node_iterator>::difference_type``.
+The library's default for ``Difference`` is ``std::ptrdiff_t``, an
+appropriate type for measuring the distance between any two
+addresses in memory, and one that works for almost any iterator,
+so we can omit this argument, too.
+
+The declaration of ``node_iterator`` will therefore look something
+like::
+
+  # include "node.hpp"
+  # include <boost/iterator/iterator_facade.hpp>
+
+  class node_iterator
+    : public boost::iterator_facade<
+          node_iterator
+        , node_base
+        , boost::forward_traversal_tag
+      >
+  {
+     ...
+  };
+
+Constructors and Data Members
+.............................
+
+Next we need to decide how to represent the iterator's position.
+This representation will take the form of data members, so we'll
+also need to write constructors to initialize them.  The
+``node_iterator``\ 's position is quite naturally represented using
+a pointer to a ``node_base``.  We'll need a constructor to build an
+iterator from a ``node_base*``, and a default constructor to
+satisfy the `forward traversal iterator`_ requirements [#default]_.
+Our ``node_iterator`` then becomes::
+
+  # include "node.hpp"
+  # include <boost/iterator/iterator_facade.hpp>
+
+  class node_iterator
+    : public boost::iterator_facade<
+          node_iterator
+        , node_base
+        , boost::forward_traversal_tag
+      >
+  {
+   public:
+      node_iterator()
+        : m_node(0)
+      {}
+
+      explicit node_iterator(node_base* p)
+        : m_node(p)
+      {}
+
+   private:
+      ...
+      node_base* m_node;
+  };
+
+.. [#default] Technically, the C++ standard places almost no
+   requirements on a default-constructed iterator, so if we were
+   really concerned with efficiency, we could've written the
+   default constructor to leave ``m_node`` uninitialized.
+
+Implementing the Core Operations
+................................
+
+The last step is to implement the `core operations`_ required by
+the concepts we want our iterator to model.  Referring to the
+table__, we can see that the first three rows are applicable
+because ``node_iterator`` needs to satisfy the requirements for
+`readable iterator`_, `single pass iterator`_, and `incrementable
+iterator`_.  
+
+__ `core operations`_
+
+We therefore need to supply ``dereference``,
+``equal``, and ``increment`` members.  We don't want these members
+to become part of ``node_iterator``\ 's public interface, so we can
+make them private and grant friendship to
+``boost::iterator_core_access``, a "back-door" that
+``iterator_facade`` uses to get access to the core operations::
+
+  # include "node.hpp"
+  # include <boost/iterator/iterator_facade.hpp>
+
+  class node_iterator
+    : public boost::iterator_facade<
+          node_iterator
+        , node_base
+        , boost::forward_traversal_tag
+      >
+  {
+   public:
+      node_iterator()
+        : m_node(0) {}
+
+      explicit node_iterator(node_base* p)
+        : m_node(p) {}
+
+   private:
+      friend class boost::iterator_core_access;
+
+      void increment() { m_node = m_node->next(); }
+
+      bool equal(node_iterator const& other) const
+      {
+          return this->m_node == other.m_node;
+      }
+
+      node_base& dereference() const { return *m_node; }
+
+      node_base* m_node;
+  };
+
+Voilà; a complete and conforming readable, forward-traversal
+iterator!  For a working example of its use, see `this program`__.
+
+__ ../example/node_iterator1.cpp
+
+A constant ``node_iterator``
+----------------------------
+
+.. Sidebar:: Constant and Mutable iterators
+
+   The term **mutable iterator** means an iterator through which
+   the object it references (its "referent") can be modified.  A
+   **constant iterator** is one which doesn't allow modification of
+   its referent.  
+
+   The words *constant* and *mutable* don't refer to the ability to
+   modify the iterator itself.  For example, an ``int const*`` is a
+   non-\ ``const`` *constant iterator*, which can be incremented
+   but doesn't allow modification of its referent, and ``int*
+   const`` is a ``const`` *mutable iterator*, which cannot be
+   modified but which allows modification of its referent.
+
+   Confusing?  We agree, but those are the standard terms.  It
+   probably doesn't help much that a container's constant iterator
+   is called ``const_iterator``.
+
+Now, our ``node_iterator`` gives clients access to both ``node``\
+'s ``print(std::ostream&) const`` member function, but also its
+mutating ``double_me()`` member.  If we wanted to build a
+*constant* ``node_iterator``, we'd only have to make three
+changes:
+
+.. parsed-literal::
+
+  class const_node_iterator
+    : public boost::iterator_facade<
+          const_node_iterator
+        , node_base **const**
+        , boost::forward_traversal_tag
+      >
+  {
+   public:
+      const_node_iterator()
+        : m_node(0) {}
+
+      explicit const_node_iterator(node_base* p)
+        : m_node(p) {}
+
+   private:
+      friend class boost::iterator_core_access;
+
+      void increment() { m_node = m_node->next(); }
+
+      bool equal(const_node_iterator const& other) const
+      {
+          return this->m_node == other.m_node;
+      }
+
+      node_base **const**\ & dereference() const { return \*m_node; }
+
+      node_base **const**\ * m_node;
+  };
+
+.. Sidebar:: ``const`` and an iterator's ``value_type``
+
+   The C++ standard requires an iterator's ``value_type`` *not* be
+   ``const``\ -qualified, so ``iterator_facade`` strips the
+   ``const`` from its ``Value`` parameter in order to produce the
+   iterator's ``value_type``.  Making the ``Value`` argument
+   ``const`` provides a useful hint to ``iterator_facade`` that the
+   iterator is a *constant iterator*, and the default ``Reference``
+   argument will be correct for all lvalue iterators.
+
+As a matter of fact, ``node_iterator`` and ``const_node_iterator``
+are so similar that it makes sense to factor the common code out
+into a template as follows::
+
+  template <class Value>
+  class node_iter
+    : public boost::iterator_facade<
+          node_iter<Value>
+        , Value
+        , boost::forward_traversal_tag
+      >
+  {
+   public:
+      node_iter()
+        : m_node(0) {}
+
+      explicit node_iter(Value* p)
+        : m_node(p) {}
+
+   private:
+      friend class boost::iterator_core_access;
+
+      bool equal(node_iter<Value> const& other) const
+      {
+          return this->m_node == other.m_node;
+      }
+
+      void increment()
+      { m_node = m_node->next(); }
+
+      Value& dereference() const
+      { return *m_node; }
+
+      Value* m_node;
+  };
+  typedef node_iter<node_base> node_iterator;
+  typedef node_iter<node_base const> node_const_iterator;
+
+
+Interoperability
+----------------
+
+Our ``const_node_iterator`` works perfectly well on its own, but
+taken together with ``node_iterator`` it doesn't quite meet
+expectations.  For example, we'd like to be able to pass a
+``node_iterator`` where a ``node_const_iterator`` was expected,
+just as you can with ``std::list<int>``\ 's ``iterator`` and
+``const_iterator``.  Furthermore, given a ``node_iterator`` and a
+``node_const_iterator`` into the same list, we should be able to
+compare them for equality.
+
+This expected ability to use two different iterator types together
+is known as |interoperability|_.  Achieving interoperability in
+our case is as simple as templatizing the ``equal`` function and
+adding a templatized converting constructor [#broken]_ [#random]_::
+
+  template <class Value>
+  class node_iter
+    : public boost::iterator_facade<
+          node_iter<Value>
+        , Value
+        , boost::forward_traversal_tag
+      >
+  {
+   public:
+      node_iter()
+        : m_node(0) {}
+
+      explicit node_iter(Value* p)
+        : m_node(p) {}
+
+      template <class OtherValue>
+      node_iter(node_iter<OtherValue> const& other)
+        : m_node(other.m_node) {}
+
+   private:
+      friend class boost::iterator_core_access;
+      template <class> friend class node_iter;
+
+      template <class OtherValue>
+      bool equal(node_iter<OtherValue> const& other) const
+      { 
+          return this->m_node == other.m_node;
+      }
+
+      void increment()
+      { m_node = m_node->next(); }
+
+      Value& dereference() const
+      { return *m_node; }
+
+      Value* m_node;
+  };
+  typedef impl::node_iterator<node_base> node_iterator;
+  typedef impl::node_iterator<node_base const> node_const_iterator;
+
+.. |interoperability| replace:: **interoperability**
+.. _interoperability: new-iter-concepts.html#interoperable-iterators-lib-interoperable-iterators
+
+.. [#broken] If you're using an older compiler and it can't handle
+   this example, see the `example code`__ for workarounds.
+
+.. [#random] If ``node_iterator`` had been a `random access
+   traversal iterator`_, we'd have had to templatize its
+   ``distance_to`` function as well.
+
+
+__ ../example/node_iterator2.hpp
+
+You can see an example program which exercises our interoperable
+iterators `here`__.
+
+__ ../example/node_iterator2.cpp
+
+Telling the Truth
+-----------------
+
+Now ``node_iterator`` and ``node_const_iterator`` behave exactly as
+you'd expect... almost.  We can compare them and we can convert in
+one direction: from ``node_iterator`` to ``node_const_iterator``.
+If we try to convert from ``node_const_iterator`` to
+``node_iterator``, we'll get an error when the converting
+constructor tries to initialize ``node_iterator``\ 's ``m_node``, a
+``node*`` with a ``node const*``.  So what's the problem?
+
+The problem is that
+``boost::``\ |is_convertible|_\ ``<node_const_iterator,node_iterator>::value``
+will be ``true``, but it should be ``false``.  |is_convertible|_
+lies because it can only see as far as the *declaration* of
+``node_iter``\ 's converting constructor, but can't look inside at
+the *definition* to make sure it will compile.  A perfect solution
+would make ``node_iter``\ 's converting constructor disappear when
+the ``m_node`` conversion would fail.
+
+.. |is_convertible| replace:: ``is_convertible``
+.. _is_convertible:  ../../type_traits/index.html#relationships
+
+In fact, that sort of magic is possible using
+|enable_if|__.  By rewriting the converting constructor as
+follows, we can remove it from the overload set when it's not
+appropriate::
+
+  #include <boost/type_traits/is_convertible.hpp>
+  #include <boost/utility/enable_if.hpp>
+
+    ...
+
+  private: 
+    struct enabler {};
+
+  public:
+    template <class OtherValue>
+    node_iter(
+        node_iter<OtherValue> const& other
+      , typename boost::enable_if<
+            boost::is_convertible<OtherValue*,Value*>
+          , enabler
+        >::type = enabler()
+    )
+      : m_node(other.m_node) {}
+
+.. |enable_if| replace:: ``boost::enable_if``
+__ ../../utility/enable_if.html
+
+
+Wrap Up
+-------
+
+This concludes our ``iterator_facade`` tutorial, but before you
+stop reading we urge you to take a look at |iterator_adaptor|__.
+There's another way to approach writing these iterators which might
+even be superior.
+
+.. |iterator_adaptor| replace:: ``iterator_adaptor``
+__ iterator_adaptor.html
+
+.. _`iterator traversal concept`: new-iter-concepts.html#iterator-traversal-concepts-lib-iterator-traversal
+.. _`readable iterator`: new-iter-concepts.html#readable-iterators-lib-readable-iterators
+.. _`lvalue iterator`: new-iter-concepts.html#lvalue-iterators-lib-lvalue-iterators
+.. _`single pass iterator`: new-iter-concepts.html#single-pass-iterators-lib-single-pass-iterators
+.. _`incrementable iterator`: new-iter-concepts.html#incrementable-iterators-lib-incrementable-iterators
+.. _`forward traversal iterator`: new-iter-concepts.html#forward-traversal-iterators-lib-forward-traversal-iterators
+.. _`bidirectional traversal iterator`: new-iter-concepts.html#bidirectional-traversal-iterators-lib-bidirectional-traversal-iterators
+.. _`random access traversal iterator`: new-iter-concepts.html#random-access-traversal-iterators-lib-random-access-traversal-iterators
+

doc/iterator_traits.html

@@ -0,0 +1,109 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<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.11: http://docutils.sourceforge.net/" />
+<title>Iterator Traits</title>
+<meta name="author" content="David Abrahams" />
+<meta name="organization" content="Boost Consulting" />
+<meta name="date" content="$Date$" />
+<meta name="copyright" content="Copyright David Abrahams 2004." />
+<link rel="stylesheet" href="../../../rst.css" type="text/css" />
+</head>
+<body>
+<div class="document" id="iterator-traits">
+<h1 class="title">Iterator Traits</h1>
+<table class="docinfo" frame="void" rules="none">
+<col class="docinfo-name" />
+<col class="docinfo-content" />
+<tbody valign="top">
+<tr><th class="docinfo-name">Author:</th>
+<td>David Abrahams</td></tr>
+<tr><th class="docinfo-name">Contact:</th>
+<td><a class="first last reference external" href="mailto:dave&#64;boost-consulting.com">dave&#64;boost-consulting.com</a></td></tr>
+<tr><th class="docinfo-name">Organization:</th>
+<td><a class="first last reference external" href="http://www.boost-consulting.com">Boost Consulting</a></td></tr>
+<tr><th class="docinfo-name">Date:</th>
+<td>$Date$</td></tr>
+<tr><th class="docinfo-name">Copyright:</th>
+<td>Copyright David Abrahams 2004.</td></tr>
+</tbody>
+</table>
+<!-- Distributed under the Boost -->
+<!-- Software License, Version 1.0. (See accompanying -->
+<!-- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->
+<table class="docutils field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field"><th class="field-name">abstract:</th><td class="field-body">Header <tt class="docutils literal">&lt;boost/iterator/iterator_traits.hpp&gt;</tt> provides
+the ability to access an iterator's associated types using
+MPL-compatible <a class="reference external" href="../../mpl/doc/index.html#metafunctions">metafunctions</a>.</td>
+</tr>
+</tbody>
+</table>
+<div class="section" id="overview">
+<h1>Overview</h1>
+<p><tt class="docutils literal"><span class="pre">std::iterator_traits</span></tt> provides access to five associated types
+of any iterator: its <tt class="docutils literal">value_type</tt>, <tt class="docutils literal">reference</tt>, <tt class="docutils literal">pointer</tt>,
+<tt class="docutils literal">iterator_category</tt>, and <tt class="docutils literal">difference_type</tt>.  Unfortunately,
+such a &quot;multi-valued&quot; traits template can be difficult to use in a
+metaprogramming context.  <tt class="docutils literal">&lt;boost/iterator/iterator_traits.hpp&gt;</tt>
+provides access to these types using a standard <a class="reference external" href="../../mpl/doc/index.html#metafunctions">metafunctions</a>.</p>
+</div>
+<div class="section" id="summary">
+<h1>Summary</h1>
+<p>Header <tt class="docutils literal">&lt;boost/iterator/iterator_traits.hpp&gt;</tt>:</p>
+<pre class="literal-block">
+template &lt;class Iterator&gt;
+struct iterator_value
+{
+    typedef typename
+      std::iterator_traits&lt;Iterator&gt;::value_type
+    type;
+};
+
+template &lt;class Iterator&gt;
+struct iterator_reference
+{
+    typedef typename
+      std::iterator_traits&lt;Iterator&gt;::reference
+    type;
+};
+
+
+template &lt;class Iterator&gt;
+struct iterator_pointer
+{
+    typedef typename
+      std::iterator_traits&lt;Iterator&gt;::pointer
+    type;
+};
+
+template &lt;class Iterator&gt;
+struct iterator_difference
+{
+    typedef typename
+      detail::iterator_traits&lt;Iterator&gt;::difference_type
+    type;
+};
+
+template &lt;class Iterator&gt;
+struct iterator_category
+{
+    typedef typename
+      detail::iterator_traits&lt;Iterator&gt;::iterator_category
+    type;
+};
+</pre>
+</div>
+</div>
+<div class="footer">
+<hr class="footer" />
+<a class="reference external" href="iterator_traits.rst">View document source</a>.
+Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
+
+</div>
+</body>
+</html>

doc/iterator_traits.rst

@@ -0,0 +1,77 @@
+.. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
++++++++++++++++++
+ Iterator Traits
++++++++++++++++++
+
+:Author: David Abrahams
+:Contact: dave@boost-consulting.com
+:organization: `Boost Consulting`_
+:date: $Date$
+:copyright: Copyright David Abrahams 2004. 
+
+.. _`Boost Consulting`: http://www.boost-consulting.com
+
+:abstract: Header ``<boost/iterator/iterator_traits.hpp>`` provides
+  the ability to access an iterator's associated types using
+  MPL-compatible metafunctions_.
+
+.. _metafunctions: ../../mpl/doc/index.html#metafunctions
+
+Overview
+========
+
+``std::iterator_traits`` provides access to five associated types
+of any iterator: its ``value_type``, ``reference``, ``pointer``,
+``iterator_category``, and ``difference_type``.  Unfortunately,
+such a "multi-valued" traits template can be difficult to use in a
+metaprogramming context.  ``<boost/iterator/iterator_traits.hpp>``
+provides access to these types using a standard metafunctions_.
+
+Summary
+=======
+
+Header ``<boost/iterator/iterator_traits.hpp>``::
+
+  template <class Iterator>
+  struct iterator_value
+  {
+      typedef typename 
+        std::iterator_traits<Iterator>::value_type 
+      type;
+  };
+
+  template <class Iterator>
+  struct iterator_reference
+  {
+      typedef typename 
+        std::iterator_traits<Iterator>::reference
+      type;
+  };
+
+
+  template <class Iterator>
+  struct iterator_pointer
+  {
+      typedef typename 
+        std::iterator_traits<Iterator>::pointer 
+      type;
+  };
+
+  template <class Iterator>
+  struct iterator_difference
+  {
+      typedef typename
+        detail::iterator_traits<Iterator>::difference_type
+      type;
+  };
+
+  template <class Iterator>
+  struct iterator_category
+  {
+      typedef typename
+        detail::iterator_traits<Iterator>::iterator_category
+      type;
+  };

doc/make_counting_iterator.rst

@@ -0,0 +1,12 @@
+.. Copyright David Abrahams 2006. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+::
+
+    template <class Incrementable>
+    counting_iterator<Incrementable> make_counting_iterator(Incrementable x);
+
+:Returns: An instance of ``counting_iterator<Incrementable>``
+    with ``current`` constructed from ``x``.
+

doc/make_filter_iterator.rst

@@ -0,0 +1,19 @@
+.. Copyright David Abrahams 2006. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+::
+
+    template <class Predicate, class Iterator>
+    filter_iterator<Predicate,Iterator>
+    make_filter_iterator(Predicate f, Iterator x, Iterator end = Iterator());
+
+:Returns: filter_iterator<Predicate,Iterator>(f, x, end)
+
+::
+
+    template <class Predicate, class Iterator>
+    filter_iterator<Predicate,Iterator>
+    make_filter_iterator(Iterator x, Iterator end = Iterator());
+
+:Returns: filter_iterator<Predicate,Iterator>(x, end)

doc/make_reverse_iterator.rst

@@ -0,0 +1,13 @@
+.. Copyright David Abrahams 2006. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+::
+
+  template <class BidirectionalIterator>
+  reverse_iterator<BidirectionalIterator>n
+  make_reverse_iterator(BidirectionalIterator x);
+
+:Returns: An instance of ``reverse_iterator<BidirectionalIterator>``
+  with a ``current`` constructed from ``x``.
+

doc/make_transform_iterator.rst

@@ -0,0 +1,23 @@
+.. Copyright David Abrahams 2006. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+::
+
+    template <class UnaryFunction, class Iterator>
+    transform_iterator<UnaryFunction, Iterator>
+    make_transform_iterator(Iterator it, UnaryFunction fun);
+
+:Returns: An instance of ``transform_iterator<UnaryFunction, Iterator>`` with ``m_f``
+  initialized to ``f`` and ``m_iterator`` initialized to ``x``.
+
+
+
+::
+
+    template <class UnaryFunction, class Iterator>
+    transform_iterator<UnaryFunction, Iterator>
+    make_transform_iterator(Iterator it);
+
+:Returns: An instance of ``transform_iterator<UnaryFunction, Iterator>`` with ``m_f``
+  default constructed and ``m_iterator`` initialized to ``x``.

doc/make_zip_iterator.rst

@@ -0,0 +1,12 @@
+.. Copyright David Abrahams 2006. Distributed under the Boost
+.. Software License, Version 1.0. (See accompanying
+.. file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+::
+
+    template<typename IteratorTuple> 
+    zip_iterator<IteratorTuple> 
+    make_zip_iterator(IteratorTuple t);
+
+:Returns: An instance of ``zip_iterator<IteratorTuple>`` with ``m_iterator_tuple``
+  initialized to ``t``.