This commit was manufactured by cvs2svn to create branch 'RC_1_31_0'.

[SVN r21650]

doc/counting_iterator_eg.rst

@@ -0,0 +1,40 @@
+
+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/filter_iterator_eg.rst

@@ -0,0 +1,69 @@
+
+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/function_output_iterator_eg.rst

@@ -0,0 +1,35 @@
+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/indirect_iterator_eg.rst

@@ -0,0 +1,69 @@
+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/interoperability-revisited.rst

@@ -0,0 +1,232 @@
+++++++++++++++++++++++++++++
+ Interoperability Revisited 
+++++++++++++++++++++++++++++
+
+:date: $Date$
+:copyright: Copyright Thomas Witt 2004.
+
+
+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 neccessary
+
+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 neccessary 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/make_counting_iterator.rst

@@ -0,0 +1,9 @@
+
+::
+
+    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_reverse_iterator.rst

@@ -0,0 +1,9 @@
+::
+
+  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,19 @@
+::
+
+    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/permutation_iterator_eg.rst

@@ -0,0 +1,67 @@
+::
+
+    using namespace boost;
+    int i = 0;
+
+    typedef std::vector< int > element_range_type;
+    typedef std::list< int > index_type;
+
+    static const int element_range_size = 10;
+    static const int index_size = 4;
+
+    element_range_type elements( element_range_size );
+    for(element_range_type::iterator el_it = elements.begin() ; el_it != elements.end() ; ++el_it)
+      *el_it = std::distance(elements.begin(), el_it);
+
+    index_type indices( index_size );
+    for(index_type::iterator i_it = indices.begin() ; i_it != indices.end() ; ++i_it ) 
+      *i_it = element_range_size - index_size + std::distance(indices.begin(), i_it);
+    std::reverse( indices.begin(), indices.end() );
+
+    typedef permutation_iterator< element_range_type::iterator, index_type::iterator > permutation_type;
+    permutation_type begin = make_permutation_iterator( elements.begin(), indices.begin() );
+    permutation_type it = begin;
+    permutation_type end = make_permutation_iterator( elements.begin(), indices.end() );
+
+    std::cout << "The original range is : ";
+    std::copy( elements.begin(), elements.end(), std::ostream_iterator< int >( std::cout, " " ) );
+    std::cout << "\n";
+
+    std::cout << "The reindexing scheme is : ";
+    std::copy( indices.begin(), indices.end(), std::ostream_iterator< int >( std::cout, " " ) );
+    std::cout << "\n";
+
+    std::cout << "The permutated range is : ";
+    std::copy( begin, end, std::ostream_iterator< int >( std::cout, " " ) );
+    std::cout << "\n";
+
+    std::cout << "Elements at even indices in the permutation : ";
+    it = begin;
+    for(i = 0; i < index_size / 2 ; ++i, it+=2 ) std::cout << *it << " ";
+    std::cout << "\n";
+
+    std::cout << "Permutation backwards : ";
+    it = begin + (index_size);
+    assert( it != begin );
+    for( ; it-- != begin ; ) std::cout << *it << " ";
+    std::cout << "\n";
+
+    std::cout << "Iterate backward with stride 2 : ";
+    it = begin + (index_size - 1);
+    for(i = 0 ; i < index_size / 2 ; ++i, it-=2 ) std::cout << *it << " ";
+    std::cout << "\n";
+
+
+The output is::
+
+    The original range is : 0 1 2 3 4 5 6 7 8 9 
+    The reindexing scheme is : 9 8 7 6 
+    The permutated range is : 9 8 7 6 
+    Elements at even indices in the permutation : 9 7 
+    Permutation backwards : 6 7 8 9 
+    Iterate backward with stride 2 : 6 8 
+
+
+The source code for this example can be found `here`__.
+
+__ ../example/permutation_iterator_example.cpp

doc/reverse_iterator_eg.rst

@@ -0,0 +1,42 @@
+
+Example
+.......
+
+The following example prints an array of characters in reverse order
+using ``reverse_iterator``.
+
+::
+    
+    char letters_[] = "hello world!";
+    const int N = sizeof(letters_)/sizeof(char) - 1;
+    typedef char* base_iterator;
+    base_iterator letters(letters_);
+    std::cout << "original sequence of letters:\t\t\t" << letters_ << std::endl;
+
+    boost::reverse_iterator<base_iterator>
+      reverse_letters_first(letters + N),
+      reverse_letters_last(letters);
+
+    std::cout << "sequence in reverse order:\t\t\t";
+    std::copy(reverse_letters_first, reverse_letters_last,
+              std::ostream_iterator<char>(std::cout));
+    std::cout << std::endl;
+
+    std::cout << "sequence in double-reversed (normal) order:\t";
+    std::copy(boost::make_reverse_iterator(reverse_letters_last),
+              boost::make_reverse_iterator(reverse_letters_first),
+              std::ostream_iterator<char>(std::cout));
+    std::cout << std::endl;
+
+
+
+The output is::
+
+    original sequence of letters:                   hello world!
+    sequence in reverse order:                      !dlrow olleh
+    sequence in double-reversed (normal) order:     hello world!
+
+
+The source code for this example can be found `here`__.
+
+__ ../example/reverse_iterator_example.cpp

doc/transform_iterator_eg.rst

@@ -0,0 +1,42 @@
+Example
+.......
+
+This is a simple example of using the transform_iterators class to
+generate iterators that multiply (or add to) the value returned by
+dereferencing the iterator. It would be cooler to use lambda library
+in this example.
+
+::
+
+    int x[] = { 1, 2, 3, 4, 5, 6, 7, 8 };
+    const int N = sizeof(x)/sizeof(int);
+
+    typedef boost::binder1st< std::multiplies<int> > Function;
+    typedef boost::transform_iterator<Function, int*> doubling_iterator;
+
+    doubling_iterator i(x, boost::bind1st(std::multiplies<int>(), 2)),
+      i_end(x + N, boost::bind1st(std::multiplies<int>(), 2));
+
+    std::cout << "multiplying the array by 2:" << std::endl;
+    while (i != i_end)
+      std::cout << *i++ << " ";
+    std::cout << std::endl;
+
+    std::cout << "adding 4 to each element in the array:" << std::endl;
+    std::copy(boost::make_transform_iterator(x, boost::bind1st(std::plus<int>(), 4)),
+	      boost::make_transform_iterator(x + N, boost::bind1st(std::plus<int>(), 4)),
+	      std::ostream_iterator<int>(std::cout, " "));
+    std::cout << std::endl;
+
+
+The output is::
+
+    multiplying the array by 2:
+    2 4 6 8 10 12 14 16 
+    adding 4 to each element in the array:
+    5 6 7 8 9 10 11 12
+
+
+The source code for this example can be found `here`__.
+
+__ ../example/transform_iterator_example.cpp