*** empty log message ***

[SVN r11537]
changes for new policies interface
2025-10-11 08:05:21 +02:00 · 2001-11-02 20:12:01 +00:00 · 2001-11-01 17:25:27 +00:00 · 2001-10-22 17:04:24 +00:00 · 2001-10-21 16:36:47 +00:00 · 2001-10-12 21:58:50 +00:00
4 changed files with 1524 additions and 489 deletions
--- a/c++_type_traits.htm
+++ b/c++_type_traits.htm
@@ -1,489 +0,0 @@
-<html>
-
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
-<meta name="GENERATOR" content="Microsoft FrontPage 4.0">
-<meta name="ProgId" content="FrontPage.Editor.Document">
-<title>C++ Type traits</title>
-</head>
-
-<body bgcolor="#FFFFFF" link="#0000FF" vlink="#800080">
-
-<h2 align="center">C++ Type traits</h2>
-<p align="center"><em>by John Maddock and Steve Cleary</em></p>
-<p align="center"><em>This is a draft of an article that will appear in a future
-issue of </em><a href="http://www.ddj.com"><em>Dr Dobb's Journal</em></a></p>
-<p>Generic programming (writing code which works with any data type meeting a
-set of requirements) has become the method of choice for providing reusable
-code. However, there are times in generic programming when &quot;generic&quot;
-just isn't good enough - sometimes the differences between types are too large
-for an efficient generic implementation. This is when the traits technique
-becomes important - by encapsulating those properties that need to be considered
-on a type by type basis inside a traits class, we can minimise the amount of
-code that has to differ from one type to another, and maximise the amount of
-generic code.</p>
-<p>Consider an example: when working with character strings, one common
-operation is to determine the length of a null terminated string. Clearly it's
-possible to write generic code that can do this, but it turns out that there are
-much more efficient methods available: for example, the C library functions <font size="2" face="Courier New">strlen</font>
-and <font size="2" face="Courier New">wcslen</font> are usually written in
-assembler, and with suitable hardware support can be considerably faster than a
-generic version written in C++. The authors of the C++ standard library realised
-this, and abstracted the properties of <font size="2" face="Courier New">char</font>
-and <font size="2" face="Courier New">wchar_t</font> into the class <font size="2" face="Courier New">char_traits</font>.
-Generic code that works with character strings can simply use <font size="2" face="Courier New">char_traits&lt;&gt;::length</font>
-to determine the length of a null terminated string, safe in the knowledge that
-specialisations of <font size="2" face="Courier New">char_traits</font> will use
-the most appropriate method available to them.</p>
-<h4>Type traits</h4>
-<p>Class <font size="2" face="Courier New">char_traits</font> is a classic
-example of a collection of type specific properties wrapped up in a single class
- what Nathan Myers termed a <i>baggage class</i>[1]. In the Boost type-traits
-library, we[2] have written a set of very specific traits classes, each of which
-encapsulate a single trait from the C++ type system; for example, is a type a
-pointer or a reference type? Or does a type have a trivial constructor, or a
-const-qualifier? The type-traits classes share a unified design: each class has
-a single member <i>value</i>, a compile-time constant that is true if the type
-has the specified property, and false otherwise. As we will show, these classes
-can be used in generic programming to determine the properties of a given type
-and introduce optimisations that are appropriate for that case.</p>
-<p>The type-traits library also contains a set of classes that perform a
-specific transformation on a type; for example, they can remove a top-level
-const or volatile qualifier from a type. Each class that performs a
-transformation defines a single typedef-member <i>type</i> that is the result of
-the transformation. All of the type-traits classes are defined inside namespace <font size="2" face="Courier New">boost</font>;
-for brevity, namespace-qualification is omitted in most of the code samples
-given.</p>
-<h4>Implementation</h4>
-<p>There are far too many separate classes contained in the type-traits library
-to give a full implementation here - see the source code in the Boost library
-for the full details - however, most of the implementation is fairly repetitive
-anyway, so here we will just give you a flavour for how some of the classes are
-implemented. Beginning with possibly the simplest class in the library, is_void&lt;T&gt;
-has a member <i>value</i> that is true only if T is void.</p>
-<pre>template &lt;typename T&gt; 
-struct is_void
-{ static const bool value = false; };
-
-template &lt;&gt; 
-struct is_void&lt;void&gt;
-{ static const bool value = true; };</pre>
-<p>Here we define a primary version of the template class <font size="2" face="Courier New">is_void</font>,
-and provide a full-specialisation when T is void. While full specialisation of a
-template class is an important technique, sometimes we need a solution that is
-halfway between a fully generic solution, and a full specialisation. This is
-exactly the situation for which the standards committee defined partial
-template-class specialisation. As an example, consider the class
-boost::is_pointer&lt;T&gt;: here we needed a primary version that handles all
-the cases where T is not a pointer, and a partial specialisation to handle all
-the cases where T is a pointer:</p>
-<pre>template &lt;typename T&gt; 
-struct is_pointer 
-{ static const bool value = false; };
-
-template &lt;typename T&gt; 
-struct is_pointer&lt;T*&gt; 
-{ static const bool value = true; };</pre>
-<p>The syntax for partial specialisation is somewhat arcane and could easily
-occupy an article in its own right; like full specialisation, in order to write
-a partial specialisation for a class, you must first declare the primary
-template. The partial specialisation contains an extra &lt;<EFBFBD>&gt; after the
-class name that contains the partial specialisation parameters; these define the
-types that will bind to that partial specialisation rather than the default
-template. The rules for what can appear in a partial specialisation are somewhat
-convoluted, but as a rule of thumb if you can legally write two function
-overloads of the form:</p>
-<pre>void foo(T);
-void foo(U);</pre>
-<p>Then you can also write a partial specialisation of the form:</p>
-<pre>template &lt;typename T&gt;
-class c{ /*details*/ };
-
-template &lt;typename T&gt;
-
-class c&lt;U&gt;{ /*details*/ };</pre>
-<p>This rule is by no means foolproof, but it is reasonably simple to remember
-and close enough to the actual rule to be useful for everyday use.</p>
-<p>As a more complex example of partial specialisation consider the class
-remove_bounds&lt;T&gt;. This class defines a single typedef-member <i>type</i>
-that is the same type as T but with any top-level array bounds removed; this is
-an example of a traits class that performs a transformation on a type:</p>
-<pre>template &lt;typename T&gt; 
-struct remove_bounds
-{ typedef T type; };
-
-template &lt;typename T, std::size_t N&gt; 
-struct remove_bounds&lt;T[N]&gt;
-{ typedef T type; };</pre>
-<p>The aim of remove_bounds is this: imagine a generic algorithm that is passed
-an array type as a template parameter, <font size="2" face="Courier New">remove_bounds</font>
-provides a means of determining the underlying type of the array. For example <code>remove_bounds&lt;int[4][5]&gt;::type</code>
-would evaluate to the type <code>int[5]</code>. This example also shows that the
-number of template parameters in a partial specialisation does not have to match
-the number in the default template. However, the number of parameters that
-appear after the class name do have to match the number and type of the
-parameters in the default template.</p>
-<h4>Optimised copy</h4>
-<p>As an example of how the type traits classes can be used, consider the
-standard library algorithm copy:</p>
-<pre>template&lt;typename Iter1, typename Iter2&gt;
-Iter2 copy(Iter1 first, Iter1 last, Iter2 out);</pre>
-<p>Obviously, there's no problem writing a generic version of copy that works
-for all iterator types Iter1 and Iter2; however, there are some circumstances
-when the copy operation can best be performed by a call to <font size="2" face="Courier New">memcpy</font>.
-In order to implement copy in terms of <font size="2" face="Courier New">memcpy</font>
-all of the following conditions need to be met:</p>
-<ul>
-  <li>Both of the iterator types Iter1 and Iter2 must be pointers.</li>
-  <li>Both Iter1 and Iter2 must point to the same type - excluding <font size="2" face="Courier New">const</font>
-    and <font size="2" face="Courier New">volatile</font>-qualifiers.</li>
-  <li>The type pointed to by Iter1 must have a trivial assignment operator.</li>
-</ul>
-<p>By trivial assignment operator we mean that the type is either a scalar
-type[3] or:</p>
-<ul>
-  <li>The type has no user defined assignment operator.</li>
-  <li>The type does not have any data members that are references.</li>
-  <li>All base classes, and all data member objects must have trivial assignment
-    operators.</li>
-</ul>
-<p>If all these conditions are met then a type can be copied using <font size="2" face="Courier New">memcpy</font>
-rather than using a compiler generated assignment operator. The type-traits
-library provides a class <i>has_trivial_assign</i>, such that <code>has_trivial_assign&lt;T&gt;::value</code>
-is true only if T has a trivial assignment operator. This class &quot;just
-works&quot; for scalar types, but has to be explicitly specialised for
-class/struct types that also happen to have a trivial assignment operator. In
-other words if <i>has_trivial_assign</i> gives the wrong answer, it will give
-the &quot;safe&quot; wrong answer - that trivial assignment is not allowable.</p>
-<p>The code for an optimised version of copy that uses <font size="2" face="Courier New">memcpy</font>
-where appropriate is given in listing 1. The code begins by defining a template
-class <i>copier</i>, that takes a single Boolean template parameter, and has a
-static template member function <font size="2" face="Courier New">do_copy</font>
-which performs the generic version of <font size="2">copy</font> (in other words
-the &quot;slow but safe version&quot;). Following that there is a specialisation
-for <i>copier&lt;true&gt;</i>: again this defines a static template member
-function <font size="2" face="Courier New">do_copy</font>, but this version uses
-memcpy to perform an &quot;optimised&quot; copy.</p>
-<p>In order to complete the implementation, what we need now is a version of
-copy, that calls <code>copier&lt;true&gt;::do_copy</code> if it is safe to use <font size="2" face="Courier New">memcpy</font>,
-and otherwise calls <code>copier&lt;false&gt;::do_copy</code> to do a
-&quot;generic&quot; copy. This is what the version in listing 1 does. To
-understand how the code works look at the code for <font size="2" face="Courier New">copy</font>
-and consider first the two typedefs <i>v1_t</i> and <i>v2_t</i>. These use <code>std::iterator_traits&lt;Iter1&gt;::value_type</code>
-to determine what type the two iterators point to, and then feed the result into
-another type-traits class <i>remove_cv</i> that removes the top-level
-const-volatile-qualifiers: this will allow copy to compare the two types without
-regard to const- or volatile-qualifiers. Next, <font size="2" face="Courier New">copy</font>
-declares an enumerated value <i>can_opt</i> that will become the template
-parameter to copier - declaring this here as a constant is really just a
-convenience - the value could be passed directly to class <font size="2" face="Courier New">copier</font>.
-The value of <i>can_opt</i> is computed by verifying that all of the following
-are true:</p>
-<ul>
-  <li>first that the two iterators point to the same type by using a type-traits
-    class <i>is_same</i>.</li>
-  <li>Then that both iterators are real pointers - using the class <i>is_pointer</i>
-    described above.</li>
-  <li>Finally that the pointed-to types have a trivial assignment operator using
-    <i>has_trivial_assign</i>.</li>
-</ul>
-<p>Finally we can use the value of <i>can_opt</i> as the template argument to
-copier - this version of copy will now adapt to whatever parameters are passed
-to it, if its possible to use <font size="2" face="Courier New">memcpy</font>,
-then it will do so, otherwise it will use a generic copy.</p>
-<h4>Was it worth it?</h4>
-<p>It has often been repeated in these columns that &quot;premature optimisation
-is the root of all evil&quot; [4]. So the question must be asked: was our
-optimisation premature? To put this in perspective the timings for our version
-of copy compared a conventional generic copy[5] are shown in table 1.</p>
-<p>Clearly the optimisation makes a difference in this case; but, to be fair,
-the timings are loaded to exclude cache miss effects - without this accurate
-comparison between algorithms becomes difficult. However, perhaps we can add a
-couple of caveats to the premature optimisation rule:</p>
-<ul>
-  <li>If you use the right algorithm for the job in the first place then
-    optimisation will not be required; in some cases, <font size="2" face="Courier New">memcpy</font>
-    is the right algorithm.</li>
-  <li>If a component is going to be reused in many places by many people then
-    optimisations may well be worthwhile where they would not be so for a single
-    case - in other words, the likelihood that the optimisation will be
-    absolutely necessary somewhere, sometime is that much higher. Just as
-    importantly the perceived value of the stock implementation will be higher:
-    there is no point standardising an algorithm if users reject it on the
-    grounds that there are better, more heavily optimised versions available.</li>
-</ul>
-<h4>Table 1: Time taken to copy 1000 elements using copy&lt;const T*, T*&gt;
-(times in micro-seconds)</h4>
-<table border="1" cellpadding="7" cellspacing="1" width="529">
-  <tr>
-    <td valign="top" width="33%">
-      <p align="center">Version</p>
-    </td>
-    <td valign="top" width="33%">
-      <p align="center">T</p>
-    </td>
-    <td valign="top" width="33%">
-      <p align="center">Time</p>
-    </td>
-  </tr>
-  <tr>
-    <td valign="top" width="33%">&quot;Optimised&quot; copy</td>
-    <td valign="top" width="33%">char</td>
-    <td valign="top" width="33%">0.99</td>
-  </tr>
-  <tr>
-    <td valign="top" width="33%">Conventional copy</td>
-    <td valign="top" width="33%">char</td>
-    <td valign="top" width="33%">8.07</td>
-  </tr>
-  <tr>
-    <td valign="top" width="33%">&quot;Optimised&quot; copy</td>
-    <td valign="top" width="33%">int</td>
-    <td valign="top" width="33%">2.52</td>
-  </tr>
-  <tr>
-    <td valign="top" width="33%">Conventional copy</td>
-    <td valign="top" width="33%">int</td>
-    <td valign="top" width="33%">8.02</td>
-  </tr>
-</table>
-<p>&nbsp;</p>
-<h4>Pair of References</h4>
-<p>The optimised copy example shows how type traits may be used to perform
-optimisation decisions at compile-time. Another important usage of type traits
-is to allow code to compile that otherwise would not do so unless excessive
-partial specialization is used. This is possible by delegating partial
-specialization to the type traits classes. Our example for this form of usage is
-a pair that can hold references [6].</p>
-<p>First, let us examine the definition of &quot;std::pair&quot;, omitting the
-comparision operators, default constructor, and template copy constructor for
-simplicity:</p>
-<pre>template &lt;typename T1, typename T2&gt; 
-struct pair 
-{
-  typedef T1 first_type;
-  typedef T2 second_type;
-
-  T1 first;
-  T2 second;
-
-  pair(const T1 &amp; nfirst, const T2 &amp; nsecond)
-  :first(nfirst), second(nsecond) { }
-};</pre>
-<p>Now, this &quot;pair&quot; cannot hold references as it currently stands,
-because the constructor would require taking a reference to a reference, which
-is currently illegal [7]. Let us consider what the constructor's parameters
-would have to be in order to allow &quot;pair&quot; to hold non-reference types,
-references, and constant references:</p>
-<table border="1" cellpadding="7" cellspacing="1" width="638">
-  <tr>
-    <td valign="top" width="50%">Type of &quot;T1&quot;</td>
-    <td valign="top" width="50%">Type of parameter to initializing constructor</td>
-  </tr>
-  <tr>
-    <td valign="top" width="50%">
-      <pre>T</pre>
-    </td>
-    <td valign="top" width="50%">
-      <pre>const T &amp;</pre>
-    </td>
-  </tr>
-  <tr>
-    <td valign="top" width="50%">
-      <pre>T &amp;</pre>
-    </td>
-    <td valign="top" width="50%">
-      <pre>T &amp;</pre>
-    </td>
-  </tr>
-  <tr>
-    <td valign="top" width="50%">
-      <pre>const T &amp;</pre>
-    </td>
-    <td valign="top" width="50%">
-      <pre>const T &amp;</pre>
-    </td>
-  </tr>
-</table>
-<p>A little familiarity with the type traits classes allows us to construct a
-single mapping that allows us to determine the type of parameter from the type
-of the contained class. The type traits classes provide a transformation &quot;add_reference&quot;,
-which adds a reference to its type, unless it is already a reference.</p>
-<table border="1" cellpadding="7" cellspacing="1" width="580">
-  <tr>
-    <td valign="top" width="21%">Type of &quot;T1&quot;</td>
-    <td valign="top" width="27%">Type of &quot;const T1&quot;</td>
-    <td valign="top" width="53%">Type of &quot;add_reference&lt;const
-      T1&gt;::type&quot;</td>
-  </tr>
-  <tr>
-    <td valign="top" width="21%">
-      <pre>T</pre>
-    </td>
-    <td valign="top" width="27%">
-      <pre>const T</pre>
-    </td>
-    <td valign="top" width="53%">
-      <pre>const T &amp;</pre>
-    </td>
-  </tr>
-  <tr>
-    <td valign="top" width="21%">
-      <pre>T &amp;</pre>
-    </td>
-    <td valign="top" width="27%">
-      <pre>T &amp; [8]</pre>
-    </td>
-    <td valign="top" width="53%">
-      <pre>T &amp;</pre>
-    </td>
-  </tr>
-  <tr>
-    <td valign="top" width="21%">
-      <pre>const T &amp;</pre>
-    </td>
-    <td valign="top" width="27%">
-      <pre>const T &amp;</pre>
-    </td>
-    <td valign="top" width="53%">
-      <pre>const T &amp;</pre>
-    </td>
-  </tr>
-</table>
-<p>This allows us to build a primary template definition for &quot;pair&quot;
-that can contain non-reference types, reference types, and constant reference
-types:</p>
-<pre>template &lt;typename T1, typename T2&gt; 
-struct pair 
-{
-  typedef T1 first_type;
-  typedef T2 second_type;
-
-  T1 first;
-  T2 second;
-
-  pair(boost::add_reference&lt;const T1&gt;::type nfirst,
-       boost::add_reference&lt;const T2&gt;::type nsecond)
-  :first(nfirst), second(nsecond) { }
-};</pre>
-<p>Add back in the standard comparision operators, default constructor, and
-template copy constructor (which are all the same), and you have a std::pair
-that can hold reference types!</p>
-<p>This same extension <i>could</i> have been done using partial template
-specialization of &quot;pair&quot;, but to specialize &quot;pair&quot; in this
-way would require three partial specializations, plus the primary template. Type
-traits allows us to define a single primary template that adjusts itself
-auto-magically to any of these partial specializations, instead of a brute-force
-partial specialization approach. Using type traits in this fashion allows
-programmers to delegate partial specialization to the type traits classes,
-resulting in code that is easier to maintain and easier to understand.</p>
-<h4>Conclusion</h4>
-<p>We hope that in this article we have been able to give you some idea of what
-type-traits are all about. A more complete listing of the available classes are
-in the boost documentation, along with further examples using type traits.
-Templates have enabled C++ uses to take the advantage of the code reuse that
-generic programming brings; hopefully this article has shown that generic
-programming does not have to sink to the lowest common denominator, and that
-templates can be optimal as well as generic.</p>
-<h4>Acknowledgements</h4>
-<p>The authors would like to thank Beman Dawes and Howard Hinnant for their
-helpful comments when preparing this article.</p>
-<h4>References</h4>
-<ol>
-  <li>Nathan C. Myers, C++ Report, June 1995.</li>
-  <li>The type traits library is based upon contributions by Steve Cleary, Beman
-    Dawes, Howard Hinnant and John Maddock: it can be found at www.boost.org.</li>
-  <li>A scalar type is an arithmetic type (i.e. a built-in integer or floating
-    point type), an enumeration type, a pointer, a pointer to member, or a
-    const- or volatile-qualified version of one of these types.</li>
-  <li>This quote is from Donald Knuth, ACM Computing Surveys, December 1974, pg
-    268.</li>
-  <li>The test code is available as part of the boost utility library (see
-    algo_opt_examples.cpp), the code was compiled with gcc 2.95 with all
-    optimisations turned on, tests were conducted on a 400MHz Pentium II machine
-    running Microsoft Windows 98.</li>
-  <li>John Maddock and Howard Hinnant have submitted a &quot;compressed_pair&quot;
-    library to Boost, which uses a technique similar to the one described here
-    to hold references. Their pair also uses type traits to determine if any of
-    the types are empty, and will derive instead of contain to conserve space --
-    hence the name &quot;compressed&quot;.</li>
-  <li>This is actually an issue with the C++ Core Language Working Group (issue
-    #106), submitted by Bjarne Stroustrup. The tentative resolution is to allow
-    a &quot;reference to a reference to T&quot; to mean the same thing as a
-    &quot;reference to T&quot;, but only in template instantiation, in a method
-    similar to multiple cv-qualifiers.</li>
-  <li>For those of you who are wondering why this shouldn't be const-qualified,
-    remember that references are always implicitly constant (for example, you
-    can't re-assign a reference). Remember also that &quot;const T &amp;&quot;
-    is something completely different. For this reason, cv-qualifiers on
-    template type arguments that are references are ignored.</li>
-</ol>
-<h2>Listing 1</h2>
-<pre>namespace detail{
-
-template &lt;bool b&gt;
-struct copier
-{
-   template&lt;typename I1, typename I2&gt;
-   static I2 do_copy(I1 first, 
-                     I1 last, I2 out);
-};
-
-template &lt;bool b&gt;
-template&lt;typename I1, typename I2&gt;
-I2 copier&lt;b&gt;::do_copy(I1 first, 
-                      I1 last, 
-                      I2 out)
-{
-   while(first != last)
-   {
-      *out = *first;
-      ++out;
-      ++first;
-   }
-   return out;
-}
-
-template &lt;&gt;
-struct copier&lt;true&gt;
-{
-   template&lt;typename I1, typename I2&gt;
-   static I2* do_copy(I1* first, I1* last, I2* out)
-   {
-      memcpy(out, first, (last-first)*sizeof(I2));
-      return out+(last-first);
-   }
-};
-
-}
-
-template&lt;typename I1, typename I2&gt;
-inline I2 copy(I1 first, I1 last, I2 out)
-{
-   typedef typename 
-    boost::remove_cv&lt;
-     typename std::iterator_traits&lt;I1&gt;
-      ::value_type&gt;::type v1_t;
-
-   typedef typename 
-    boost::remove_cv&lt;
-     typename std::iterator_traits&lt;I2&gt;
-      ::value_type&gt;::type v2_t;
-
-   enum{ can_opt = 
-      boost::is_same&lt;v1_t, v2_t&gt;::value
-      &amp;&amp; boost::is_pointer&lt;I1&gt;::value
-      &amp;&amp; boost::is_pointer&lt;I2&gt;::value
-      &amp;&amp; boost::
-      has_trivial_assign&lt;v1_t&gt;::value 
-   };
-
-   return detail::copier&lt;can_opt&gt;::
-      do_copy(first, last, out);
-}</pre>
-<hr>
-<p><EFBFBD> Copyright John Maddock and Steve Cleary, 2000</p>
-
-</body>
-
-</html>
--- a/iterator_adaptor_test.cpp
+++ b/iterator_adaptor_test.cpp
@@ -0,0 +1,376 @@
+//  Test boost/iterator_adaptors.hpp
+
+//  (C) Copyright Jeremy Siek 1999. Permission to copy, use, modify,
+//  sell and distribute this software is granted provided this
+//  copyright notice appears in all copies. This software is provided
+//  "as is" without express or implied warranty, and with no claim as
+//  to its suitability for any purpose.
+
+//  See http://www.boost.org for most recent version including documentation.
+
+//  Revision History
+//  08 Mar 01 Moved indirect and transform tests to separate files.
+//            (Jeremy Siek)
+//  19 Feb 01 Take adavantage of improved iterator_traits to do more tests
+//            on MSVC. Hack around an MSVC-with-STLport internal compiler
+//            error. (David Abrahams)
+//  11 Feb 01 Added test of operator-> for forward and input iterators.
+//            (Jeremy Siek)
+//  11 Feb 01 Borland fixes (David Abrahams)
+//  10 Feb 01 Use new adaptors interface. (David Abrahams)
+//  10 Feb 01 Use new filter_ interface. (David Abrahams)
+//  09 Feb 01 Use new reverse_ and indirect_ interfaces. Replace
+//            BOOST_NO_STD_ITERATOR_TRAITS with
+//            BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION to prove we've
+//            normalized to core compiler capabilities (David Abrahams)
+//  08 Feb 01 Use Jeremy's new make_reverse_iterator form; add more
+//            comprehensive testing. Force-decay array function arguments to
+//            pointers.
+//  07 Feb 01 Added tests for the make_xxx_iterator() helper functions.
+//            (Jeremy Siek)
+//  07 Feb 01 Replaced use of xxx_pair_generator with xxx_generator where
+//            possible (which was all but the projection iterator).
+//            (Jeremy Siek)
+//  06 Feb 01 Removed now-defaulted template arguments where possible
+//            Updated names to correspond to new generator naming convention.
+//            Added a trivial test for make_transform_iterator().
+//            Gave traits for const iterators a mutable value_type, per std.
+//            Resurrected my original tests for indirect iterators.
+//            (David Abrahams)
+//  04 Feb 01 Fix for compilers without standard iterator_traits
+//            (David Abrahams)
+//  13 Jun 00 Added const version of the iterator tests (Jeremy Siek)
+//  12 Dec 99 Initial version with iterator operators (Jeremy Siek)
+
+#include <boost/config.hpp>
+#include <iostream>
+
+#include <algorithm>
+#include <functional>
+
+#include <boost/iterator_adaptors.hpp>
+#include <boost/pending/iterator_tests.hpp>
+#include <boost/pending/integer_range.hpp>
+#include <boost/concept_archetype.hpp>
+#include <boost/type_traits/same_traits.hpp>
+#include <stdlib.h>
+#include <vector>
+#include <deque>
+#include <set>
+
+struct my_iterator_tag : public std::random_access_iterator_tag { };
+
+using boost::dummyT;
+
+
+struct mult_functor {
+  typedef int result_type;
+  typedef int argument_type;
+  // Functors used with transform_iterator must be
+  // DefaultConstructible, as the transform_iterator must be
+  // DefaultConstructible to satisfy the requirements for
+  // TrivialIterator.
+  mult_functor() { }
+  mult_functor(int aa) : a(aa) { }
+  int operator()(int b) const { return a * b; }
+  int a;
+};
+
+template <class Pair>
+struct select1st_ 
+  : public std::unary_function<Pair, typename Pair::first_type>
+{
+  const typename Pair::first_type& operator()(const Pair& x) const {
+    return x.first;
+  }
+  typename Pair::first_type& operator()(Pair& x) const {
+    return x.first;
+  }
+};
+
+struct one_or_four {
+  bool operator()(dummyT x) const {
+    return x.foo() == 1 || x.foo() == 4;
+  }
+};
+
+typedef std::deque<int> storage;
+typedef std::deque<int*> pointer_deque;
+typedef std::set<storage::iterator> iterator_set;
+
+template <class T> struct foo;
+
+int
+main()
+{
+  dummyT array[] = { dummyT(0), dummyT(1), dummyT(2), 
+                     dummyT(3), dummyT(4), dummyT(5) };
+  const int N = sizeof(array)/sizeof(dummyT);
+
+  // sanity check, if this doesn't pass the test is buggy
+  boost::random_access_iterator_test(array, N, array);
+
+#if 0
+  // Check that the policy concept checks and the default policy
+  // implementation match up.
+  boost::function_requires< 
+     boost::RandomAccessIteratorPoliciesConcept<
+       boost::default_iterator_policies,
+       boost::iterator_adaptor<int*, boost::default_iterator_policies>,
+       boost::iterator<std::random_access_iterator_tag, int, std::ptrdiff_t,
+                      int*, int&>
+      > >();
+
+  // Test the named parameters
+  {
+    // Test computation of defaults
+    typedef boost::iterator_adaptor<int*, boost::default_iterator_policies,
+      boost::value_type_is<int> > Iter1;
+    BOOST_STATIC_ASSERT((boost::is_same<std::iterator_traits<Iter1>::value_type, int>::value));
+    BOOST_STATIC_ASSERT((boost::is_same<std::iterator_traits<Iter1>::reference, int&>::value));
+    BOOST_STATIC_ASSERT((boost::is_same<std::iterator_traits<Iter1>::pointer, int*>::value));
+    BOOST_STATIC_ASSERT((boost::is_same<std::iterator_traits<Iter1>::difference_type, std::ptrdiff_t>::value));
+    BOOST_STATIC_ASSERT((boost::is_same<std::iterator_traits<Iter1>::iterator_category, std::random_access_iterator_tag>::value));
+  }
+  {  
+    // Test computation of default when the Value is const
+    typedef boost::iterator_adaptor<int*, boost::default_iterator_policies,
+      boost::value_type_is<const int> > Iter1;
+    BOOST_STATIC_ASSERT((boost::is_same<std::iterator_traits<Iter1>::value_type, int>::value));
+    BOOST_STATIC_ASSERT((boost::is_same<std::iterator_traits<Iter1>::reference, const int&>::value));
+    BOOST_STATIC_ASSERT((boost::is_same<std::iterator_traits<Iter1>::pointer, const int*>::value));
+  }
+  {
+    // Test with no defaults
+    typedef boost::iterator_adaptor<int*, boost::default_iterator_policies,
+      boost::reference_is<long>,
+      boost::pointer_is<float>,
+      boost::value_type_is<char>,
+      boost::iterator_category_is<std::input_iterator_tag>,
+      boost::difference_type_is<int>
+    > Iter1;
+    BOOST_STATIC_ASSERT((boost::is_same<std::iterator_traits<Iter1>::value_type, char>::value));
+    BOOST_STATIC_ASSERT((boost::is_same<std::iterator_traits<Iter1>::reference, long>::value));
+    BOOST_STATIC_ASSERT((boost::is_same<std::iterator_traits<Iter1>::pointer, float>::value));
+    BOOST_STATIC_ASSERT((boost::is_same<std::iterator_traits<Iter1>::difference_type, int>::value));
+    BOOST_STATIC_ASSERT((boost::is_same<std::iterator_traits<Iter1>::iterator_category, std::input_iterator_tag>::value));
+  }
+  
+  // Test the iterator_adaptor
+  {
+    boost::iterator_adaptor<dummyT*, boost::default_iterator_policies, dummyT> i(array);
+    boost::random_access_iterator_test(i, N, array);
+    
+    boost::iterator_adaptor<const dummyT*, boost::default_iterator_policies, const dummyT> j(array);
+    boost::random_access_iterator_test(j, N, array);
+    boost::const_nonconst_iterator_test(i, ++j);
+  }
+
+  // Test projection_iterator_pair_generator
+  {    
+    typedef std::pair<dummyT,dummyT> Pair;
+    Pair pair_array[N];
+    for (int k = 0; k < N; ++k)
+      pair_array[k].first = array[k];
+
+    typedef boost::projection_iterator_pair_generator<select1st_<Pair>,
+      Pair*, const Pair*
+      > Projection;
+    
+    Projection::iterator i(pair_array);
+    boost::random_access_iterator_test(i, N, array);
+
+    boost::random_access_iterator_test(boost::make_projection_iterator(pair_array, select1st_<Pair>()), N, array);    
+    boost::random_access_iterator_test(boost::make_projection_iterator< select1st_<Pair> >(pair_array), N, array);    
+
+    Projection::const_iterator j(pair_array);
+    boost::random_access_iterator_test(j, N, array);
+
+    boost::random_access_iterator_test(boost::make_const_projection_iterator(pair_array, select1st_<Pair>()), N, array);
+    boost::random_access_iterator_test(boost::make_const_projection_iterator<select1st_<Pair> >(pair_array), N, array);
+
+    boost::const_nonconst_iterator_test(i, ++j);
+  }
+
+  // Test reverse_iterator_generator
+  {
+    dummyT reversed[N];
+    std::copy(array, array + N, reversed);
+    std::reverse(reversed, reversed + N);
+    
+    typedef boost::reverse_iterator_generator<dummyT*
+#ifdef BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION
+        , dummyT
+#endif
+      >::type reverse_iterator;
+    
+    reverse_iterator i(reversed + N);
+    boost::random_access_iterator_test(i, N, array);
+
+#ifndef BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION
+    boost::random_access_iterator_test(boost::make_reverse_iterator(reversed + N), N, array);
+#endif
+
+    typedef boost::reverse_iterator_generator<const dummyT*
+#ifdef BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION
+      , dummyT, const dummyT&, const dummyT
+#endif
+      >::type const_reverse_iterator;
+    
+    const_reverse_iterator j(reversed + N);
+    boost::random_access_iterator_test(j, N, array);
+
+    const dummyT* const_reversed = reversed;
+    
+#ifndef BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION
+    boost::random_access_iterator_test(boost::make_reverse_iterator(const_reversed + N), N, array);
+#endif
+    
+    boost::const_nonconst_iterator_test(i, ++j);    
+  }
+
+  // Test reverse_iterator_generator again, with traits fully deducible on all platforms
+  {
+    std::deque<dummyT> reversed_container;
+    std::reverse_copy(array, array + N, std::back_inserter(reversed_container));
+    const std::deque<dummyT>::iterator reversed = reversed_container.begin();
+
+
+    typedef boost::reverse_iterator_generator<
+        std::deque<dummyT>::iterator>::type reverse_iterator;
+    typedef boost::reverse_iterator_generator<
+        std::deque<dummyT>::const_iterator, const dummyT>::type const_reverse_iterator;
+
+    // MSVC/STLport gives an INTERNAL COMPILER ERROR when any computation
+    // (e.g. "reversed + N") is used in the constructor below.
+    const std::deque<dummyT>::iterator finish = reversed_container.end();
+    reverse_iterator i(finish);
+    
+    boost::random_access_iterator_test(i, N, array);
+    boost::random_access_iterator_test(boost::make_reverse_iterator(reversed + N), N, array);
+
+    const_reverse_iterator j = reverse_iterator(finish);
+    boost::random_access_iterator_test(j, N, array);
+
+    const std::deque<dummyT>::const_iterator const_reversed = reversed;
+    boost::random_access_iterator_test(boost::make_reverse_iterator(const_reversed + N), N, array);
+    
+    // Many compilers' builtin deque iterators don't interoperate well, though
+    // STLport fixes that problem.
+#if defined(__SGI_STL_PORT) || !defined(__GNUC__) && !defined(__BORLANDC__) && !defined(BOOST_MSVC)
+    boost::const_nonconst_iterator_test(i, ++j);
+#endif
+  }
+  
+  // Test integer_range's iterators
+  {
+    int int_array[] = { 0, 1, 2, 3, 4, 5 };
+    boost::integer_range<int> r(0, 5);
+    boost::random_access_iterator_test(r.begin(), r.size(), int_array);
+  }
+
+  // Test filter iterator
+  {
+    // Using typedefs for filter_gen::type confused Borland terribly.
+    typedef boost::detail::non_bidirectional_category<dummyT*>::type category;
+    
+    typedef boost::filter_iterator_generator<one_or_four, dummyT*
+#ifdef BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION
+        , dummyT
+#endif
+        >::type filter_iter;
+
+#if defined(__BORLANDC__)
+    // Borland is choking on accessing the policies_type explicitly
+    // from the filter_iter. 
+    boost::forward_iterator_test(make_filter_iterator(array, array+N, 
+						      one_or_four()),
+				 dummyT(1), dummyT(4));
+#else
+    filter_iter i(array, filter_iter::policies_type(one_or_four(), array + N));
+    boost::forward_iterator_test(i, dummyT(1), dummyT(4));
+#endif
+
+#if !defined(__BORLANDC__)
+    // 
+    enum { is_forward = boost::is_same<
+           filter_iter::iterator_category,
+           std::forward_iterator_tag>::value };
+    BOOST_STATIC_ASSERT(is_forward);
+#endif
+
+    // On compilers not supporting partial specialization, we can do more type
+    // deduction with deque iterators than with pointers... unless the library
+    // is broken ;-(
+#if !defined(BOOST_MSVC) || defined(__SGI_STL_PORT)
+    std::deque<dummyT> array2;
+    std::copy(array+0, array+N, std::back_inserter(array2));
+    boost::forward_iterator_test(
+        boost::make_filter_iterator(array2.begin(), array2.end(), one_or_four()),
+        dummyT(1), dummyT(4));
+
+    boost::forward_iterator_test(
+        boost::make_filter_iterator<one_or_four>(array2.begin(), array2.end()),
+        dummyT(1), dummyT(4));
+#endif
+
+#if !defined(BOOST_MSVC) // This just freaks MSVC out completely
+    boost::forward_iterator_test(
+        boost::make_filter_iterator<one_or_four>(
+            boost::make_reverse_iterator(array2.end()),
+            boost::make_reverse_iterator(array2.begin())
+            ),
+        dummyT(4), dummyT(1));
+#endif
+    
+#ifndef BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION
+    boost::forward_iterator_test(
+        boost::make_filter_iterator(array+0, array+N, one_or_four()),
+        dummyT(1), dummyT(4));
+
+    boost::forward_iterator_test(
+        boost::make_filter_iterator<one_or_four>(array, array + N),
+        dummyT(1), dummyT(4));
+
+#endif
+  }
+
+  // check operator-> with a forward iterator
+  {
+    boost::forward_iterator_archetype<dummyT> forward_iter;
+#if defined(__BORLANDC__)
+    typedef boost::iterator_adaptor<boost::forward_iterator_archetype<dummyT>,
+      boost::default_iterator_policies,
+      dummyT, const dummyT&, const dummyT*, 
+      std::forward_iterator_tag, std::ptrdiff_t> adaptor_type;
+#else
+    typedef boost::iterator_adaptor<boost::forward_iterator_archetype<dummyT>,
+      boost::default_iterator_policies,
+      boost::reference_is<const dummyT&>,
+      boost::pointer_is<const dummyT*> ,
+      boost::iterator_category_is<std::forward_iterator_tag>,
+      boost::value_type_is<dummyT>,
+      boost::difference_type_is<std::ptrdiff_t>
+    > adaptor_type;
+#endif
+    adaptor_type i(forward_iter);
+    int zero = 0;
+    if (zero) // don't do this, just make sure it compiles
+      assert((*i).m_x == i->foo());      
+  }
+  // check operator-> with an input iterator
+  {
+    boost::input_iterator_archetype<dummyT> input_iter;
+    typedef boost::iterator_adaptor<boost::input_iterator_archetype<dummyT>,
+      boost::default_iterator_policies,
+      dummyT, const dummyT&, const dummyT*, 
+      std::input_iterator_tag, std::ptrdiff_t> adaptor_type;
+    adaptor_type i(input_iter);
+    int zero = 0;
+    if (zero) // don't do this, just make sure it compiles
+      assert((*i).m_x == i->foo());      
+  }
+#endif
+  std::cout << "test successful " << std::endl;
+  return 0;
+}
--- a/iterator_adaptors.htm
+++ b/iterator_adaptors.htm
@@ -0,0 +1,928 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+
+<html>
+<head>
+    <meta name="generator" content="HTML Tidy, see www.w3.org">
+    <meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
+    <meta name="GENERATOR" content="Microsoft FrontPage 4.0">
+    <meta name="ProgId" content="FrontPage.Editor.Document">
+
+    <title>Boost Iterator Adaptor Library</title>
+</head>
+
+<body bgcolor="#FFFFFF" text="#000000">
+
+    <img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)" align=
+    "center" width="277" height="86"> 
+
+    <h1>Boost Iterator Adaptor Library</h1>
+
+    <h2>Introduction</h2>
+
+    <p>The Iterator Adaptor library allows you transform an arbitrary ``base''
+    type into a standard-conforming iterator with the behaviors you choose.
+    Doing so is especially easy if the ``base'' type is itself an iterator. The
+    library also supplies several example <a href=
+    "../../more/generic_programming.html#adaptors">adaptors</a> which apply
+    specific useful behaviors to arbitrary base iterators.
+
+    <h2>Backward Compatibility Note</h2>
+
+    <p>The library's interface has changed since it was first released, breaking
+    backward compatibility:
+
+    <ol>
+
+    <li><a href="#policies">Policies classes</a> now operate on instances of the
+    whole <tt>iterator_adaptor</tt> object, rather than just operating on the
+    <tt>Base</tt> object. This change not only gives the policies class access
+    to both members of a pair of interacting iterators, but also eliminates the
+    need for the ugly <tt>type&lt;Reference&gt;</tt> and
+    <tt>type&lt;Difference&gt;</tt> parameters to various policy functions.
+
+    <li>The <a href="#named_template_parameters">Named Template Parameter</a>
+    interface has been made simpler, easier to use, and compatible with more
+    compilers.
+
+    </ol>
+
+    <h2>Other Documentation</h2>
+
+    <p><a href="iterator_adaptors.pdf">``Policy Adaptors and the Boost Iterator
+    Adaptor Library''</a> is a technical paper describing this library and the
+    powerful design pattern on which it is based. It was presented at the <a
+    href="http://www.oonumerics.org/tmpw01">C++ Template Workshop</a> at OOPSLA
+    2001; the slides from the talk are available <a
+    href="iterator_adaptors.ppt">here</a>. Please note that while the slides
+    incorporate the minor interface changes described in the previous section,
+    the paper does not.
+
+    <h2>Table of Contents</h2>
+
+    <ul>
+      <li>
+        Header <tt><a href=
+        "../../boost/iterator_adaptors.hpp">boost/iterator_adaptors.hpp</a></tt>
+        
+
+        <ul>
+          <li>
+            Generalized Iterator Adaptor 
+
+            <ul>
+              <li>Class template <tt><a href=
+              "#iterator_adaptor">iterator_adaptor</a></tt>
+
+              <li><a href="#template_parameters">Template Parameters</a>
+
+              <li><a href="#named_template_parameters">Named Template Parameters</a>
+
+              <li><a href="#policies">The Policies Class</a>
+
+              <li><a href="#additional_members">Additional Class Members</a>
+
+              <li><a href="#example">Example</a>
+
+              <li>(<tt>const</tt>/non-<tt>const</tt>) <a href=
+              "#iterator_interactions">Iterator Interactions</a>
+
+              <li><a href="#challenge">Challenge</a>
+
+              <li><a href="#concept_model">Concept Model</a>
+
+              <li><a href="#declaration_synopsis">Declaration Synopsis</a>
+
+              <li><a href="#notes">Notes</a>
+            </ul>
+
+          <li>
+            <a name="specialized_adaptors">Specialized Iterator Adaptors</a> 
+
+            <ul>
+              <li><a href="indirect_iterator.htm">Indirect Iterator Adaptor</a>
+
+              <li><a href="reverse_iterator.htm">Reverse Iterator Adaptor</a>
+
+              <li><a href="transform_iterator.htm">Transform Iterator
+              Adaptor</a>
+
+              <li><a href="projection_iterator.htm">Projection Iterator
+              Adaptor</a>
+
+              <li><a href="filter_iterator.htm">Filter Iterator Adaptor</a>
+            </ul>
+        </ul>
+
+      <li>Header <tt><a href=
+      "../../boost/counting_iterator.hpp">boost/counting_iterator.hpp</a></tt><br>
+
+       <a href="counting_iterator.htm">Counting Iterator Adaptor</a>
+
+      <li>Header <tt><a href=
+      "../../boost/function_output_iterator.hpp">boost/function_output_iterator.hpp</a></tt><br>
+
+       <a href="function_output_iterator.htm">Function Output Iterator Adaptor</a>
+    </ul>
+
+    <p><b><a href="../../people/dave_abrahams.htm">Dave
+    Abrahams</a></b> started the library, applying <a href=
+    "../../more/generic_programming.html#policy">policy class</a> technique and
+    handling const/non-const iterator interactions. He also contributed the
+    <tt><a href="indirect_iterator.htm">indirect_</a></tt> and <tt><a href=
+    "reverse_iterator.htm">reverse_</a></tt> iterator generators, and expanded
+    <tt><a href="counting_iterator.htm">counting_iterator_generator</a></tt> to
+    cover all incrementable types. He edited most of the documentation,
+    sometimes heavily.<br>
+     <b><a href="../../people/jeremy_siek.htm">Jeremy
+    Siek</a></b> contributed the <a href="transform_iterator.htm">transform
+    iterator</a> adaptor, the integer-only version of <tt><a href=
+    "counting_iterator.htm">counting_iterator_generator</a></tt>, 
+    the <a href="function_output_iterator.htm">function output iterator</a> 
+    adaptor, and most of the documentation.<br>
+     <b><a href="http://www.boost.org/people/john_potter.htm">John
+    Potter</a></b> contributed the <tt><a href=
+    "projection_iterator.htm">projection_</a></tt> and <tt><a href=
+    "filter_iterator.htm">filter_</a></tt> iterator generators and made some
+    simplifications to the main <tt><a href=
+    "#iterator_adaptor">iterator_adaptor</a></tt> template.<br>
+
+
+    <h2><a name="iterator_adaptor">Class template</a>
+    <tt>iterator_adaptor</tt></h2>
+    Implementing standard conforming iterators is a non-trivial task. There are
+    some fine points such as the interactions between an iterator and its
+    corresponding const_iterator, and there are myriad operators that should be
+    implemented but are easily forgotten or mishandled, such as
+    <tt>operator-&gt;()</tt>. Using <tt>iterator_adaptor</tt>, you can easily
+    implement an iterator class, and even more easily extend and <a href=
+    "../../more/generic_programming.html#adaptors">adapt</a> existing iterator
+    types. Moreover, it is easy to make a pair of interoperable <tt>const</tt>
+    and <tt>non-const</tt> iterators. 
+
+    <p><tt>iterator_adaptor</tt> is declared like this:
+<pre>
+template &lt;class Base, class Policies, 
+    class ValueOrNamedParam = typename std::iterator_traits&lt;Base&gt;::value_type,
+    class ReferenceOrNamedParam = <i>...(see below)</i>,
+    class PointerOrNamedParam = <i>...(see below)</i>,
+    class CategoryOrNamedParam = typename std::iterator_traits&lt;Base&gt;::iterator_category,
+    class DistanceOrNamedParam = typename std::iterator_traits&lt;Base&gt;::difference_type&gt;
+struct iterator_adaptor;
+</pre>
+
+    <h3><a name="template_parameters">Template Parameters</a></h3>
+
+    <p>Although <tt>iterator_adaptor</tt> takes seven template parameters,
+    defaults have been carefully chosen to minimize the number of parameters
+    you must supply in most cases, especially if <tt>BaseType</tt> is an
+    iterator.
+
+    <table border="1" summary="iterator_adaptor template parameters">
+      <tr>
+        <th>Parameter
+
+        <th>Description
+
+      <tr>
+        <td><tt>BaseType</tt> 
+
+        <td>The type being wrapped.
+
+      <tr>
+        <td><tt>Policies</tt> 
+
+        <td>A <a href="../../more/generic_programming.html#policy">policy
+        class</a> that supplies core functionality to the resulting iterator. A
+        detailed description can be found <a href="#policies">below</a>.
+
+      <tr>
+        <td><tt>Value</tt> 
+
+        <td>The <tt>value_type</tt> of the resulting iterator, unless const. If
+        Value is <tt>const X</tt> the
+        <tt>value_type</tt> will be (<i>non-</i><tt>const</tt>) <tt>X</tt><a href=
+        "#1">[1]</a>. If the <tt>value_type</tt> you wish to use is an abstract
+        base class see note <a href="#5">[5]</a>.<br>
+         <b>Default:</b>
+        <tt>std::iterator_traits&lt;BaseType&gt;::value_type</tt> <a href=
+        "#2">[2]</a>
+
+      <tr>
+        <td><tt>Reference</tt> 
+
+        <td>The <tt>reference</tt> type of the resulting iterator, and in
+        particular, the result type of <tt>operator*()</tt>.<br>
+         <b>Default:</b> If <tt>Value</tt> is supplied, <tt>Value&amp;</tt> is
+        used. Otherwise
+        <tt>std::iterator_traits&lt;BaseType&gt;::reference</tt> is used. <a href="#7">[7]</a>
+
+      <tr>
+        <td><tt>Pointer</tt> 
+
+        <td>The <tt>pointer</tt> type of the resulting iterator, and in
+        particular, the result type of <tt>operator-&gt;()</tt>.<br>
+         <b>Default:</b> If <tt>Value</tt> was supplied, then <tt>Value*</tt>,
+        otherwise <tt>std::iterator_traits&lt;BaseType&gt;::pointer</tt>. <a href="#7">[7]</a>
+
+      <tr>
+        <td><tt>Category</tt> 
+
+        <td>The <tt>iterator_category</tt> type for the resulting iterator.<br>
+         <b>Default:</b>
+        <tt>std::iterator_traits&lt;BaseType&gt;::iterator_category</tt> 
+
+      <tr>
+        <td><tt>Distance</tt> 
+
+        <td>The <tt>difference_type</tt> for the resulting iterator.<br>
+         <b>Default:</b>
+        <tt>std::iterator_traits&lt;BaseType&gt;::difference_type</tt> 
+
+      <tr>
+         <td><tt>NamedParam</tt>
+
+         <td>A named template parameter (see below).
+    </table>
+
+    <h3><a name="named_template_parameters">Named Template Parameters</a></h3>
+    
+    With seven template parameters, providing arguments for
+    <tt>iterator_adaptor</tt> in the correct order can be challenging.
+    Also, often times one would like to specify the sixth or seventh
+    template parameter, but use the defaults for the third through
+    fifth. As a solution to these problems we provide a mechanism for
+    naming the last five template parameters, and providing them in
+    any order through a set of named template parameters. The following
+    classes are provided for specifying the parameters. Any of these
+    classes can be used for any of the last five template parameters
+    of <tt>iterator_adaptor</tt>.
+    <blockquote>
+<pre>
+template &lt;class Value&gt; struct value_type_is;
+template &lt;class Reference&gt; struct reference_is;
+template &lt;class Pointer&gt; struct pointer_is;
+template &lt;class Distance&gt; struct difference_type_is;
+template &lt;class Category&gt; struct iterator_category_is;
+</pre>
+    </blockquote>
+
+    For example, the following adapts <tt>foo_iterator</tt> to create
+    an <a href=
+    "http://www.sgi.com/tech/stl/InputIterator.html">InputIterator</a>
+    with <tt>reference</tt> type <tt>foo</tt>, and whose other traits
+    are determined according to the defaults described <a
+    href="#template_parameters">above</a>.
+
+    <blockquote>
+<pre>
+typedef iterator_adaptor&lt;foo_iterator, foo_policies,
+  reference_is&lt;foo&gt;, iterator_category_is&lt;std::input_iterator_tag&gt;
+  &gt; MyIterator;
+</pre>
+    </blockquote>
+
+    
+    <h3><a name="policies">The Policies Class</a></h3>
+
+    <p>The main task in using <tt>iterator_adaptor</tt> is creating an
+    appropriate <tt>Policies</tt> class. The <tt>Policies</tt> class will become
+    the functional heart of the resulting iterator, supplying the core
+    operations that determine its behavior. The <tt>iterator_adaptor</tt>
+    template defines all of the operators required of a <a href=
+    "http://www.sgi.com/tech/stl/RandomAccessIterator.html">Random Access
+    Iterator</a> by dispatching to a <tt>Policies</tt> object. Your
+    <tt>Policies</tt> class must implement a subset of the core iterator
+    operations below corresponding to the iterator categories you want it to
+    support.<br>
+    <br>
+    
+
+    <table border="1" summary="iterator_adaptor Policies operations">
+      <caption>
+        <b>Core Iterator Operations</b><br>
+        <tt>T</tt>: adapted iterator type; <tt>p</tt>: object of type T; <tt>n</tt>: <tt>T::size_type</tt>; <tt>x</tt>: <tt>T::difference_type</tt>; <tt>p1</tt>, <tt>p2</tt>: iterators
+      </caption>
+
+      <tr>
+        <th>Operation
+
+        <th>Effects
+
+        <th>Implements Operations
+
+        <th>Required for Iterator Categories
+
+      <tr>
+        <td><tt>initialize</tt>
+
+        <td>optionally modify base iterator during iterator construction
+
+        <td>constructors
+
+        <td rowspan="4"><a href=
+        "http://www.sgi.com/tech/stl/InputIterator.html">Input</a>/ <a href=
+        "http://www.sgi.com/tech/stl/OutputIterator.html">Output</a>/ <a href=
+        "http://www.sgi.com/tech/stl/ForwardIterator.html">Forward</a>/ <a
+        href=
+        "http://www.sgi.com/tech/stl/BidirectionalIterator.html">Bidirectional</a>/
+        <a href="http://www.sgi.com/tech/stl/RandomAccessIterator.html">Random
+        Access</a> 
+
+	  
+      <tr>
+        <td><tt>dereference</tt> 
+
+        <td>returns an element of the iterator's <tt>reference</tt> type
+        
+        <td><tt>*p</tt>, <tt>p[n]</tt>
+
+
+      <tr>
+        <td><tt>equal</tt> 
+
+        <td>tests the iterator for equality
+
+        <td><tt>p1&nbsp;==&nbsp;p2</tt>, <tt>p1&nbsp;!=&nbsp;p2</tt>
+
+      <tr>
+        <td><tt>increment</tt> 
+
+        <td>increments the iterator
+
+        <td><tt>++p</tt>, <tt>p++</tt>
+
+      <tr>
+        <td><tt>decrement</tt> 
+
+        <td>decrements the iterator
+
+        <td><tt>--p</tt>, <tt>p--</tt>
+
+        <td><a href=
+        "http://www.sgi.com/tech/stl/BidirectionalIterator.html">Bidirectional</a>/
+        <a href="http://www.sgi.com/tech/stl/RandomAccessIterator.html">Random
+        Access</a> 
+
+      <tr>
+        <td><tt>less</tt> 
+
+        <td>imposes a <a href=
+        "http://www.sgi.com/tech/stl/StrictWeakOrdering.html">Strict Weak
+        Ordering</a> relation on iterators
+
+        <td> 
+           <tt>p1&nbsp;&lt;&nbsp;p2</tt>,
+           <tt>p1&nbsp;&lt;=&nbsp;p2</tt>,
+           <tt>p1&nbsp;&gt;&nbsp;p2</tt>,
+           <tt>p1&nbsp;&gt;=&nbsp;p2</tt>
+
+        <td rowspan="3"><a href=
+        "http://www.sgi.com/tech/stl/RandomAccessIterator.html">Random
+        Access</a> 
+
+      <tr>
+        <td><tt>distance</tt> 
+
+        <td>measures the distance between iterators
+
+        <td><tt>p1 - p2</tt>
+
+      <tr>
+        <td><tt>advance</tt> 
+
+        <td>adds an integer offset to iterators
+
+        <td>
+<tt>p&nbsp;+&nbsp;x</tt>,
+<tt>x&nbsp;+&nbsp;p</tt>,
+<tt>p&nbsp;+=&nbsp;x</tt>,
+<tt>p&nbsp;-&nbsp;x</tt>,
+<tt>p&nbsp;-=&nbsp;x</tt>
+        
+    </table>
+
+    <p>The library also supplies a "trivial" policy class,
+    <tt>default_iterator_policies</tt>, which implements all seven of the core
+    operations in the usual way. If you wish to create an iterator adaptor that
+    only changes a few of the base type's behaviors, then you can derive your
+    new policy class from <tt>default_iterator_policies</tt> to avoid retyping
+    the usual behaviors. You should also look at
+    <tt>default_iterator_policies</tt> as the ``boilerplate'' for your own
+    policy classes, defining functions with the same interface. This is the
+    definition of <tt>default_iterator_policies</tt>:<br>
+    <br>
+
+    <blockquote>
+<pre>
+struct <a name="default_iterator_policies">default_iterator_policies</a>
+{
+    // Some of these members were defined static, but Borland got confused
+    // and thought they were non-const. Also, Sun C++ does not like static
+    // function templates.
+
+    template &lt;class Base&gt;
+    void initialize(Base&amp;)
+        { }
+
+    template &lt;class IteratorAdaptor&gt;
+    typename IteratorAdaptor::reference dereference(const IteratorAdaptor&amp; x) const
+        { return *x.base(); }
+
+    template &lt;class IteratorAdaptor&gt;
+    void increment(IteratorAdaptor&amp; x)
+        { ++x.base(); }
+
+    template &lt;class IteratorAdaptor&gt;
+    void decrement(IteratorAdaptor&amp; x)
+        { --x.base(); }
+
+    template &lt;class IteratorAdaptor, class DifferenceType&gt;
+    void advance(IteratorAdaptor&amp; x, DifferenceType n)
+        { x.base() += n; }
+
+    template &lt;class IteratorAdaptor1, class IteratorAdaptor2&gt;
+    typename IteratorAdaptor1::difference_type
+    distance(const IteratorAdaptor1&amp; x, const IteratorAdaptor2&amp; y) const
+        { return y.base() - x.base(); }
+
+    template &lt;class IteratorAdaptor1, class IteratorAdaptor2&gt;
+    bool equal(const IteratorAdaptor1&amp; x, const IteratorAdaptor2&amp; y) const
+        { return x.base() == y.base(); }
+};
+</pre></blockquote>
+
+    <p>Template member functions are used throughout
+    <tt>default_iterator_policies</tt> so that it can be employed with a wide
+    range of iterators. If we had used concrete types above, we'd have tied the
+    usefulness of <tt>default_iterator_policies</tt> to a particular range of
+    adapted iterators. If you follow the same pattern with your
+    <tt>Policies</tt> classes, you can use them to generate more specialized
+    adaptors along the lines of <a href="#specialized_adaptors">those supplied by this library</a>.
+
+    <h3><a name="additional_members">Additional Members</a></h3>
+    In addition to all of the member functions required of a <a href=
+    "http://www.sgi.com/tech/stl/RandomAccessIterator.html">Random Access
+    Iterator</a>, the <tt>iterator_adaptor</tt> class template defines the
+    following members. <br>
+     <br>
+     
+
+    <table border="1" summary="additional iterator_adaptor members">
+      <tr>
+        <td><tt>explicit iterator_adaptor(const Base&amp;, const Policies&amp; =
+        Policies())</tt>
+         <br><br>
+         Construct an adapted iterator from a base object and a policies
+         object. As this constructor is <tt>explicit</tt>, it does not
+         provide for implicit conversions from the <tt>Base</tt> type to
+         the iterator adaptor.
+
+      <tr>
+        <td><tt>template &lt;class B, class V, class R, class P&gt;<br>
+         iterator_adaptor(const
+        iterator_adaptor&lt;B,Policies,V,R,P,Category,Distance&gt;&amp;)</tt>
+        <br><br>
+         This constructor allows for conversion from mutable to
+        constant adapted iterators. See <a href=
+        "#iterator_interactions">below</a> for more details.<br>
+         Requires: <tt>B</tt> is convertible to <tt>Base</tt>.
+
+      <tr>
+        <td><tt>base_type base() const;</tt>
+         <br><br>
+         Return a copy of the base object.
+    </table>
+
+    <h3><a name="example">Example</a></h3>
+
+    <p>It is often useful to automatically apply some function to the value
+    returned by dereferencing an iterator. The <a href=
+    "./transform_iterator.htm">transform iterator</a> makes it easy to create
+    an iterator adaptor which does just that. Here we will show how easy it is
+    to implement the transform iterator using the <tt>iterator_adaptor</tt>
+    template.
+
+    <p>We want to be able to adapt a range of iterators and functions, so the
+    policies class will have a template parameter for the function type and it
+    will have a data member of that type. We know that the function takes one
+    argument and that we'll need to be able to deduce the <tt>result_type</tt>
+    of the function so we can use it for the adapted iterator's
+    <tt>value_type</tt>. <a href=
+    "http://www.sgi.com/Technology/STL/AdaptableUnaryFunction.html">AdaptableUnaryFunction</a>
+    is the <a href="../../more/generic_programming.html#concept">Concept</a>
+    that fulfills those requirements.
+
+    <p>To implement a transform iterator we will only change one of the base
+    iterator's behaviors, so the <tt>transform_iterator_policies</tt> class can
+    inherit the rest from <tt>default_iterator_policies</tt>. We will define the
+    <tt>dereference()</tt> member function, which is used to implement
+    <tt>operator*()</tt> of the adapted iterator. The implementation will
+    dereference the base iterator and apply the function object. The complete
+    code for <tt>transform_iterator_policies</tt> is:<br>
+    <br>
+
+<blockquote><pre>
+template &lt;class AdaptableUnaryFunction&gt;
+struct transform_iterator_policies : public default_iterator_policies
+{
+    transform_iterator_policies() { }
+
+    transform_iterator_policies(const AdaptableUnaryFunction&amp; f)
+        : m_f(f) { }
+    
+    template &lt;class IteratorAdaptor&gt;
+    typename IteratorAdaptor::reference
+    dereference(const IteratorAdaptor&amp; iter) const
+        { return m_f(*iter.base()); }
+
+    AdaptableUnaryFunction m_f;
+};
+
+</pre></blockquote>
+
+    <p>The next step is to use the <tt>iterator_adaptor</tt> template to
+    construct the transform iterator type. The nicest way to package the
+    construction of the transform iterator is to create a <a href=
+    "../../more/generic_programming.html#type_generator">type generator</a>.
+    The first template parameter to the generator will be the type of the
+    function object and the second will be the base iterator type. We use
+    <tt>iterator_adaptor</tt> to define the transform iterator type as a nested
+    <tt>typedef</tt> inside the <tt>transform_iterator_generator</tt> class.
+    Because the function may return by-value, we must limit the
+    <tt>iterator_category</tt> to <a href=
+    "http://www.sgi.com/tech/stl/InputIterator.html">Input Iterator</a>, and
+    the iterator's <tt>reference</tt> type cannot be a true reference (the
+    standard allows this for input iterators), so in this case we can use few
+    of <tt>iterator_adaptor</tt>'s default template arguments.<br>
+    <br>
+
+
+    <blockquote>
+<pre>
+template &lt;class AdaptableUnaryFunction, class Iterator&gt;
+struct transform_iterator_generator
+{
+    typedef typename AdaptableUnaryFunction::result_type value_type;
+public:
+    typedef iterator_adaptor&lt;Iterator, 
+        transform_iterator_policies&lt;AdaptableUnaryFunction&gt;,
+        value_type, value_type, value_type*, std::input_iterator_tag&gt;
+      type;
+};
+</pre>
+    </blockquote>
+
+    <p>As a finishing touch, we will create an <a href=
+    "../../more/generic_programming.html#object_generator">object generator</a>
+    for the transform iterator. Our object generator makes it more
+    convenient to create a transform iterator.<br>
+    <br>
+
+
+    <blockquote>
+<pre>
+template &lt;class AdaptableUnaryFunction, class Iterator&gt;
+typename transform_iterator_generator&lt;AdaptableUnaryFunction,Iterator&gt;::type
+make_transform_iterator(Iterator base,
+                        const AdaptableUnaryFunction&amp; f = AdaptableUnaryFunction())
+{
+    typedef typename transform_iterator_generator&lt;AdaptableUnaryFunction,
+      Iterator&gt;::type result_t;
+    return result_t(base, f);
+}
+</pre>
+    </blockquote>
+
+    <p>Here is an example that shows how to use a transform iterator to iterate
+    through a range of numbers, multiplying each of them by 2 and printing the
+    result to standard output.<br>
+    <br>
+
+
+    <blockquote>
+<pre>
+#include &lt;functional&gt;
+#include &lt;algorithm&gt;
+#include &lt;iostream&gt;
+#include &lt;boost/iterator_adaptors.hpp&gt;
+
+int main(int, char*[])
+{
+  int x[] = { 1, 2, 3, 4, 5, 6, 7, 8 };
+  const int N = sizeof(x)/sizeof(int);
+  std::cout &lt;&lt; &quot;multiplying the array by 2:&quot; &lt;&lt; std::endl;
+  std::copy(boost::make_transform_iterator(x, std::bind1st(std::multiplies&lt;int&gt;(), 2)),
+      boost::make_transform_iterator(x + N, std::bind1st(std::multiplies&lt;int&gt;(), 2)),
+      std::ostream_iterator&lt;int&gt;(std::cout, &quot; &quot;));
+  std::cout &lt;&lt; std::endl;
+  return 0;
+}
+</pre>
+      This output is: 
+<pre>
+2 4 6 8 10 12 14 16
+</pre>
+    </blockquote>
+
+    <h3><a name="iterator_interactions">Iterator Interactions</a></h3>
+
+    <p>C++ allows <tt>const</tt> and non-<tt>const</tt> pointers to interact in
+    the following intuitive ways:
+
+    <ul>
+      <li>a non-<tt>const</tt> pointer to <tt>T</tt> can be implicitly
+      converted to a <tt>const</tt> pointer to <tt>T</tt>.
+
+      <li><tt>const</tt> and non-<tt>const</tt> pointers to <tt>T</tt> can be
+      freely mixed in comparison expressions.
+
+      <li><tt>const</tt> and non-<tt>const</tt> pointers to <tt>T</tt> can be
+      freely subtracted, in any order.
+    </ul>
+
+    Getting user-defined iterators to work together that way is nontrivial (see
+    <a href="reverse_iterator.htm#interactions">here</a> for an example of where
+    the C++ standard got it wrong), but <tt>iterator_adaptor</tt> can make it
+    easy. The rules are as follows:
+
+    <ul>
+      <li><a name="interoperable">Adapted iterators that share the same <tt>Policies</tt>,
+      <tt>Category</tt>, and <tt>Distance</tt> parameters are called
+      <i>interoperable</i>.</a>
+
+      <li>An adapted iterator can be implicitly converted to any other adapted
+      iterator with which it is interoperable, so long as the <tt>Base</tt>
+      type of the source iterator can be converted to the <tt>Base</tt> type of
+      the target iterator.
+
+      <li>Interoperable iterators can be freely mixed in comparison expressions
+      so long as the <tt>Policies</tt> class has <tt>equal</tt> (and, for
+      random access iterators, <tt>less</tt>) members that can accept both
+      <tt>Base</tt> types in either order.
+
+      <li>Interoperable iterators can be freely mixed in subtraction
+      expressions so long as the <tt>Policies</tt> class has a
+      <tt>distance</tt> member that can accept both <tt>Base</tt> types in
+      either order.
+    </ul>
+
+    <h4>Example</h4>
+    
+    <p>The <a href="projection_iterator.htm">Projection Iterator</a> adaptor is similar to the <a
+href="./transform_iterator.htm">transform iterator adaptor</a> in that
+its <tt>operator*()</tt> applies some function to the result of
+dereferencing the base iterator and then returns the result. The
+difference is that the function must return a reference to some
+existing object (for example, a data member within the
+<tt>value_type</tt> of the base iterator). 
+
+    <p>
+The <a
+    href="projection_iterator.htm#projection_iterator_pair_generator">projection_iterator_pair_generator</a> template
+    is a special two-<a href="../../more/generic_programming.html#type_generator">type generator</a> for mutable and constant versions of a
+    projection iterator. It is defined as follows:
+<blockquote>
+<pre>
+template &lt;class AdaptableUnaryFunction, class Iterator, class ConstIterator&gt;
+struct projection_iterator_pair_generator {
+    typedef typename AdaptableUnaryFunction::result_type value_type;
+    typedef projection_iterator_policies&lt;AdaptableUnaryFunction&gt; policies;
+public:
+    typedef iterator_adaptor&lt;Iterator,policies,value_type&gt; iterator;
+    typedef iterator_adaptor&lt;ConstIterator,policies,value_type,
+        const value_type&amp;,const value_type*&gt; const_iterator;
+};
+</pre>
+</blockquote>
+
+<p>It is assumed that the <tt>Iterator</tt> and <tt>ConstIterator</tt> arguments are corresponding mutable
+and constant iterators. <ul>
+<li>
+Clearly, then, the
+<tt>projection_iterator_pair_generator</tt>'s <tt>iterator</tt> and
+<tt>const_iterator</tt> are <a href="#interoperable">interoperable</a>, since
+they share the same <tt>Policies</tt> and since <tt>Category</tt> and
+<tt>Distance</tt> as supplied by <tt>std::iterator_traits</tt> through the
+<a href="#template_parameters">default template parameters</a> to
+<tt>iterator_adaptor</tt> should be the same.
+
+<li>Since <tt>Iterator</tt> can presumably be converted to
+<tt>ConstIterator</tt>, the projection <tt>iterator</tt> will be convertible to
+the projection <tt>const_iterator</tt>.
+
+<li> Since <tt>projection_iterator_policies</tt> implements only the
+<tt>dereference</tt> operation, and inherits all other behaviors from <tt><a
+href="#default_iterator_policies">default_iterator_policies</a></tt>, which has
+fully-templatized <tt>equal</tt>, <tt>less</tt>, and <tt>distance</tt>
+operations, the <tt>iterator</tt> and <tt>const_iterator</tt> can be freely
+mixed in comparison and subtraction expressions.
+
+</ul>
+
+    <h3><a name="challenge">Challenge</a></h3>
+
+    <p>There is an unlimited number of ways the <tt>iterator_adaptors</tt>
+    class can be used to create iterators. One interesting exercise would be to
+    re-implement the iterators of <tt>std::list</tt> and <tt>std::slist</tt>
+    using <tt>iterator_adaptors</tt>, where the adapted <tt>Iterator</tt> types
+    would be node pointers.
+
+    <h3><a name="concept_model">Concept Model</a></h3>
+    Depending on the <tt>Base</tt> and <tt>Policies</tt> template parameters,
+    an <tt>iterator_adaptor</tt> can be a <a href=
+    "http://www.sgi.com/tech/stl/InputIterator.html">Input Iterator</a>, <a
+    href="http://www.sgi.com/tech/stl/ForwardIterator.html">Forward
+    Iterator</a>, <a href=
+    "http://www.sgi.com/tech/stl/BidirectionalIterator.html">Bidirectional
+    Iterator</a>, or <a href=
+    "http://www.sgi.com/tech/stl/RandomAccessIterator.html">Random Access
+    Iterator</a>. 
+
+    <h3><a name="declaration_synopsis">Declaration Synopsis</a></h3>
+<pre>
+template &lt;class Base, class Policies, 
+    class Value = typename std::iterator_traits&lt;Base&gt;::value_type,
+    class Reference = <i>...(see below)</i>,
+    class Pointer = <i>...(see below)</i>,
+    class Category = typename std::iterator_traits&lt;Base&gt;::iterator_category,
+    class Distance = typename std::iterator_traits&lt;Base&gt;::difference_type
+         &gt;
+struct iterator_adaptor
+{
+    typedef Distance difference_type;
+    typedef typename boost::remove_const&lt;Value&gt;::type value_type;
+    typedef Pointer pointer;
+    typedef Reference reference;
+    typedef Category iterator_category;
+    typedef Base base_type;
+    typedef Policies policies_type;
+
+    iterator_adaptor();
+    explicit iterator_adaptor(const Base&amp;, const Policies&amp; = Policies());
+
+    base_type base() const;
+
+    template &lt;class B, class V, class R, class P&gt;
+    iterator_adaptor(
+        const iterator_adaptor&lt;B,Policies,V,R,P,Category,Distance&gt;&amp;);
+
+    reference operator*() const; <a href="#6">[6]</a>
+    <i>operator_arrow_result_type</i> operator-&gt;() const; <a href=
+"#3">[3]</a>
+    <i>value_type</i> operator[](difference_type n) const; <a href="#3">[4]</a>, <a href="#6">[6]</a>
+
+    iterator_adaptor&amp; operator++();
+    iterator_adaptor&amp; operator++(int);
+    iterator_adaptor&amp; operator--();
+    iterator_adaptor&amp; operator--(int);
+
+    iterator_adaptor&amp; operator+=(difference_type n);
+    iterator_adaptor&amp; operator-=(difference_type n);
+
+    iterator_adaptor&amp; operator-(Distance x) const;
+};
+
+template &lt;class B, class P, class V, class R, class Ptr, 
+    class C, class D1, class D2&gt;
+iterator_adaptor&lt;B,P,V,R,Ptr,C,D1&gt;
+operator+(iterator_adaptor&lt;B,P,V,R,Ptr,C,D1&gt;, D2);
+
+template &lt;class B, class P, class V, class R, class Ptr,
+    class C, class D1, class D2&gt;
+iterator_adaptor&lt;B,P,V,R,P,C,D1&gt;
+operator+(D2, iterator_adaptor&lt;B,P,V,R,Ptr,C,D1&gt; p);
+
+template &lt;class B1, class B2, class P, class V1, class V2,
+    class R1, class R2, class P1, class P2, class C, class D&gt;
+Distance operator-(const iterator_adaptor&lt;B1,P,V1,R1,P1,C,D&gt;&amp;, 
+                   const iterator_adaptor&lt;B2,P,V2,R2,P2,C,D&gt;&amp;);
+
+template &lt;class B1, class B2, class P, class V1, class V2,
+    class R1, class R2, class P1, class P2, class C, class D&gt;
+bool operator==(const iterator_adaptor&lt;B1,P,V1,R1,P1,C,D&gt;&amp;, 
+                const iterator_adaptor&lt;B2,P,V2,R2,P2,C,D&gt;&amp;);
+
+// and similarly for operators !=, &lt;, &lt;=, &gt;=, &gt;
+</pre>
+
+    <h3><a name="notes">Notes</a></h3>
+
+    <p><a name="1">[1]</a> The standard specifies that the <tt>value_type</tt>
+    of <tt>const</tt> iterators to <tt>T</tt> (e.g. <tt>const T*</tt>) is
+    <tt><i>non-</i>const T</tt>, while the <tt>pointer</tt> and
+    <tt>reference</tt> types for all <a href=
+    "http://www.sgi.com/tech/stl/ForwardIterator.html">Forward Iterators</a> are
+    <tt>const T*</tt> and <tt>const T&amp;</tt>, respectively. Stripping the
+    <tt>const</tt>-ness of <tt>Value</tt> allows you to easily make a constant
+    iterator by supplying a <tt>const</tt> type for <tt>Value</tt>, and allowing
+    the defaults for the <tt>Pointer</tt> and <tt>Reference</tt> parameters to
+    take effect. Although compilers that don't support partial specialization
+    won't strip <tt>const</tt> for you, having a <tt>const value_type</tt> is
+    often harmless in practice.
+
+    <p><a name="2">[2]</a> If your compiler does not support partial
+    specialization and the base iterator is a builtin pointer type, you
+    will not be able to use the default for <tt>Value</tt> and will have to
+    specify this type explicitly.
+
+    <p><a name="3">[3]</a> The result type for the <tt>operator-&gt;()</tt>
+    depends on the category and value type of the iterator and is somewhat
+    complicated to describe. But be assured, it works in a stardard conforming
+    fashion, providing access to members of the objects pointed to by the
+    iterator.
+
+    <p><a name="4">[4]</a> The result type of <tt>operator[]()</tt> is
+    <tt>value_type</tt> instead of <tt>reference</tt> as might be expected.
+    There are two reasons for this choice. First, the C++ standard only
+    requires that the return type of an arbitrary <a href=
+    "http://www.sgi.com/tech/stl/RandomAccessIterator.html">Random Access
+    Iterator</a>'s <tt>operator[]</tt>be ``convertible to T'' (Table 76), so
+    when adapting an arbitrary base iterator we may not have a reference to
+    return. Second, and more importantly, for certain kinds of iterators,
+    returning a reference could cause serious memory problems due to the
+    reference being bound to a temporary object whose lifetime ends inside of
+    the <tt>operator[]</tt>.
+
+    <p><a name="5">[5]</a>
+    The <tt>value_type</tt> of an iterator may not be
+    an abstract base class, however many common uses of iterators
+    never need the <tt>value_type</tt>, only the <tt>reference</tt> type.
+    If you wish to create such an iterator adaptor, use a dummy
+    type such as <tt>char</tt> for the <tt>Value</tt> parameter,
+    and use a reference to your abstract base class for
+    the <tt>Reference</tt> parameter. Note that such an iterator
+    does not fulfill the C++ standards requirements for a
+    <a href= "http://www.sgi.com/tech/stl/ForwardIterator.html">
+    Forward Iterator</a>, so you will need to use a less restrictive
+    iterator category such as <tt>std::input_iterator_tag</tt>.
+
+    <p><a name="6">[6]</a>
+    There is a common misconception that an iterator should have two
+    versions of <tt>operator*</tt> and of <tt>operator[]</tt>, one
+    version that is a <tt>const</tt> member function and one version
+    that is non-<tt>const</tt>. Perhaps the source of this
+    misconception is that containers typically have const and
+    non-const versions of many of their member functions.  Iterators,
+    however, are different. A particular iterator type can be either
+    <i>mutable</i> or <i>constant</i> (but not both).  One can assign
+    to and change the object pointed to by a mutable iterator whereas a
+    constant iterator returns constant objects when dereferenced. Whether
+    the iterator object itself is <tt>const</tt> has nothing to do with
+    whether the iterator is mutable or constant.  This is analogous to
+    the way built-in pointer types behave.  For example, one can
+    modify objects pointed to by a <tt>const</tt> pointer
+<pre>
+    int* const x = new int;
+    int i = 3;
+    *x = i;
+</pre>
+    but one cannot modify objects pointed to by a pointer
+    to <tt>const</tt>
+<pre>
+    int const* x = new int;
+    int i = 3;
+    *x = i;
+</pre>
+
+    <p><a name="7">[7]</a>
+    If you are using a compiler that does not have a version of
+    <tt>std::iterator_traits</tt> that works for pointers (i.e., if your
+    compiler does not support partial specialization) then if the
+    <tt>Base</tt> type is a const pointer, then the correct defaults
+    for the <tt>reference</tt> and <tt>pointer</tt> types can not be
+    deduced. You must specify these types explicitly.
+
+    <hr>
+
+    <p>Revised 
+    <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %b %Y" startspan -->18 Sep 2001<!--webbot bot="Timestamp" endspan i-checksum="14941" -->
+
+
+    <p>&copy; Copyright Dave Abrahams and Jeremy Siek 2001. Permission to copy,
+    use, modify, sell and distribute this document is granted provided this
+    copyright notice appears in all copies. This document is provided "as is"
+    without express or implied warranty, and with no claim as to its
+    suitability for any purpose. 
+
+</body>
+
+    <!--  LocalWords:  HTML html charset alt gif abrahams htm const iterator
+        incrementable david abrahams
+         -->
+     
+    <!--  LocalWords:  jeremy siek mishandled interoperable typename struct Iter iter src
+         -->
+     
+    <!--  LocalWords:  int bool ForwardIterator BidirectionalIterator BaseIterator
+         -->
+     
+    <!--  LocalWords:  RandomAccessIterator DifferenceType AdaptableUnaryFunction
+         -->
+     
+    <!--  LocalWords:  iostream hpp sizeof InputIterator constness ConstIterator
+         David Abrahams
+         -->
+<!--  LocalWords:  Iterators dereferenced
+ -->
+</html>
+
--- a/iterator_traits_test.cpp
+++ b/iterator_traits_test.cpp
@@ -0,0 +1,220 @@
+//  (C) Copyright David Abrahams 2001. Permission to copy, use, modify,
+//  sell and distribute this software is granted provided this
+//  copyright notice appears in all copies. This software is provided
+//  "as is" without express or implied warranty, and with no claim as
+//  to its suitability for any purpose.
+
+//  See http://www.boost.org for most recent version including documentation.
+
+//  Revision History
+//  12 Oct 2001 Put static asserts in functions for MWERSK (Dave Abrahams)
+//  04 Mar 2001 Patches for Intel C++ (Dave Abrahams)
+//  19 Feb 2001 Take advantage of improved iterator_traits to do more tests
+//              on MSVC. Reordered some #ifdefs for coherency.
+//              (David Abrahams)
+//  13 Feb 2001 Test new VC6 workarounds (David Abrahams)
+//  11 Feb 2001 Final fixes for Borland (David Abrahams)
+//  11 Feb 2001 Some fixes for Borland get it closer on that compiler
+//              (David Abrahams)
+//  07 Feb 2001 More comprehensive testing; factored out static tests for
+//              better reuse (David Abrahams)
+//  21 Jan 2001 Quick fix to my_iterator, which wasn't returning a
+//              reference type from operator* (David Abrahams)
+//  19 Jan 2001 Initial version with iterator operators (David Abrahams)
+
+#include <boost/detail/iterator.hpp>
+#include <boost/type_traits.hpp>
+#include <boost/operators.hpp>
+#include <boost/static_assert.hpp>
+#include <iterator>
+#include <vector>
+#include <list>
+#include <cassert>
+#include <iostream>
+
+// An iterator for which we can get traits.
+struct my_iterator1
+    : boost::forward_iterator_helper<my_iterator1, char, long, const char*, const char&>
+{
+    my_iterator1(const char* p) : m_p(p) {}
+    
+    bool operator==(const my_iterator1& rhs) const
+        { return this->m_p == rhs.m_p; }
+
+    my_iterator1& operator++() { ++this->m_p; return *this; }
+    const char& operator*() { return *m_p; }
+ private:
+    const char* m_p;
+};
+
+// Used to prove that we don't require std::iterator<> in the hierarchy under
+// MSVC6, and that we can compute all the traits for a standard-conforming UDT
+// iterator.
+struct my_iterator2
+    : boost::equality_comparable<my_iterator2
+    , boost::incrementable<my_iterator2
+    , boost::dereferenceable<my_iterator2,const char*> > >
+{
+    typedef char value_type;
+    typedef long difference_type;
+    typedef const char* pointer;
+    typedef const char& reference;
+    typedef std::forward_iterator_tag iterator_category;
+    
+    my_iterator2(const char* p) : m_p(p) {}
+    
+    bool operator==(const my_iterator2& rhs) const
+        { return this->m_p == rhs.m_p; }
+
+    my_iterator2& operator++() { ++this->m_p; return *this; }
+    const char& operator*() { return *m_p; }
+ private:
+    const char* m_p;
+};
+
+// Used to prove that we're not overly confused by the existence of
+// std::iterator<> in the hierarchy under MSVC6 - we should find that
+// boost::detail::iterator_traits<my_iterator3>::difference_type is int.
+struct my_iterator3 : my_iterator1
+{
+    typedef int difference_type;
+    my_iterator3(const char* p) : my_iterator1(p) {}
+};
+
+template <class Iterator,
+    class value_type, class difference_type, class pointer, class reference, class category>
+struct non_portable_tests
+{
+    non_portable_tests()
+    {
+        // Unfortunately, the VC6 standard library doesn't supply these :(
+        BOOST_STATIC_ASSERT((
+            boost::is_same<
+            typename boost::detail::iterator_traits<Iterator>::pointer,
+            pointer
+            >::value));
+
+        BOOST_STATIC_ASSERT((
+            boost::is_same<
+            typename boost::detail::iterator_traits<Iterator>::reference,
+            reference
+            >::value));
+    }
+};
+
+template <class Iterator,
+    class value_type, class difference_type, class pointer, class reference, class category>
+struct portable_tests
+{
+    portable_tests()
+    {
+        BOOST_STATIC_ASSERT((
+            boost::is_same<
+            typename boost::detail::iterator_traits<Iterator>::difference_type,
+            difference_type
+            >::value));
+
+        BOOST_STATIC_ASSERT((
+            boost::is_same<
+            typename boost::detail::iterator_traits<Iterator>::iterator_category,
+            category
+            >::value));
+    }
+};
+
+// Test iterator_traits
+template <class Iterator,
+    class value_type, class difference_type, class pointer, class reference, class category>
+struct input_iterator_test
+    : portable_tests<Iterator,value_type,difference_type,pointer,reference,category>
+{
+    input_iterator_test()
+    {
+        BOOST_STATIC_ASSERT((
+            boost::is_same<
+            typename boost::detail::iterator_traits<Iterator>::value_type,
+            value_type
+            >::value));
+    }
+};
+
+template <class Iterator,
+    class value_type, class difference_type, class pointer, class reference, class category>
+struct non_pointer_test
+    : input_iterator_test<Iterator,value_type,difference_type,pointer,reference,category>
+      , non_portable_tests<Iterator,value_type,difference_type,pointer,reference,category>
+{
+};
+
+template <class Iterator,
+    class value_type, class difference_type, class pointer, class reference, class category>
+struct maybe_pointer_test
+    : portable_tests<Iterator,value_type,difference_type,pointer,reference,category>
+#ifndef BOOST_NO_TEMPLATE_PARTIAL_SPECIALIZATION
+      , non_portable_tests<Iterator,value_type,difference_type,pointer,reference,category>
+#endif
+{
+};
+
+input_iterator_test<std::istream_iterator<int>, int, std::ptrdiff_t, int*, int&, std::input_iterator_tag>
+        istream_iterator_test;
+
+// 
+#if defined(__BORLANDC__) && !defined(__SGI_STL_PORT)
+typedef ::std::char_traits<char>::off_type distance;
+non_pointer_test<std::ostream_iterator<int>,int,
+    distance,int*,int&,std::output_iterator_tag> ostream_iterator_test;
+#elif defined(BOOST_MSVC_STD_ITERATOR)
+non_pointer_test<std::ostream_iterator<int>,
+    int, void, void, void, std::output_iterator_tag>
+        ostream_iterator_test;
+#else
+non_pointer_test<std::ostream_iterator<int>,
+    void, void, void, void, std::output_iterator_tag>
+        ostream_iterator_test;
+#endif
+
+
+#ifdef __KCC
+  typedef long std_list_diff_type;
+#else
+  typedef std::ptrdiff_t std_list_diff_type;
+#endif
+non_pointer_test<std::list<int>::iterator, int, std_list_diff_type, int*, int&, std::bidirectional_iterator_tag>
+        list_iterator_test;
+
+maybe_pointer_test<std::vector<int>::iterator, int, std::ptrdiff_t, int*, int&, std::random_access_iterator_tag>
+        vector_iterator_test;
+
+maybe_pointer_test<int*, int, std::ptrdiff_t, int*, int&, std::random_access_iterator_tag>
+        int_pointer_test;
+
+non_pointer_test<my_iterator1, char, long, const char*, const char&, std::forward_iterator_tag>
+       my_iterator1_test;
+                    
+non_pointer_test<my_iterator2, char, long, const char*, const char&, std::forward_iterator_tag>
+       my_iterator2_test;
+                    
+non_pointer_test<my_iterator3, char, int, const char*, const char&, std::forward_iterator_tag>
+       my_iterator3_test;
+                    
+int main()
+{
+    char chars[100];
+    int ints[100];
+    
+    for (std::ptrdiff_t length = 3; length < 100; length += length / 3)
+    {
+        std::list<int> l(length);
+        assert(boost::detail::distance(l.begin(), l.end()) == length);
+        
+        std::vector<int> v(length);
+        assert(boost::detail::distance(v.begin(), v.end()) == length);
+
+        assert(boost::detail::distance(&ints[0], ints + length) == length);
+        assert(boost::detail::distance(my_iterator1(chars), my_iterator1(chars + length)) == length);
+        assert(boost::detail::distance(my_iterator2(chars), my_iterator2(chars + length)) == length);
+        assert(boost::detail::distance(my_iterator3(chars), my_iterator3(chars + length)) == length);
+    }
+    return 0;
+}