Added first (rough) draft of quickbook documentation

[SVN r30962]

doc/quickbook/counting_iterator.qbk

@@ -0,0 +1,192 @@
+
+[section:counting Counting Iterator]
+
+A `counting_iterator` adapts an object by adding an `operator*` that
+returns the current value of the object. All other iterator operations
+are forwarded to the adapted object.
+
+
+[h2 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 [@../example/counting_iterator_example.cpp here].
+
+[h2 Reference]
+
+
+[h3 Synopsis]
+
+  template <
+      class Incrementable
+    , class CategoryOrTraversal = use_default
+    , class Difference = use_default
+  >
+  class counting_iterator
+  {
+  public:
+      typedef Incrementable value_type;
+      typedef const Incrementable& reference;
+      typedef const Incrementable* pointer;
+      typedef /* see below */ difference_type;
+      typedef /* see below */ iterator_category;
+
+      counting_iterator();
+      counting_iterator(counting_iterator const& rhs);
+      explicit counting_iterator(Incrementable x);
+      Incrementable const& base() const;
+      reference operator*() const;
+      counting_iterator& operator++();
+      counting_iterator& operator--();
+  private:
+      Incrementable m_inc; // exposition
+  };
+
+
+If the `Difference` argument is `use_default` then
+`difference_type` is an unspecified signed integral
+type. Otherwise `difference_type` is `Difference`.
+
+`iterator_category` is determined according to the following
+algorithm:
+
+   if (CategoryOrTraversal is not use_default)
+       return CategoryOrTraversal
+   else if (numeric_limits<Incrementable>::is_specialized)
+       return |iterator-category|_\ (
+           random_access_traversal_tag, Incrementable, const Incrementable&)
+   else
+       return |iterator-category|_\ (
+            iterator_traversal<Incrementable>::type, 
+            Incrementable, const Incrementable&)
+        
+[blurb *Note:* implementers are encouraged to provide an implementation of
+  `operator-` and a `difference_type` that avoids overflows in
+  the cases where `std::numeric_limits<Incrementable>::is_specialized`
+  is true.]
+
+[h3 Requirements]
+
+
+The `Incrementable` argument shall be Copy Constructible and Assignable.
+
+If `iterator_category` is convertible to `forward_iterator_tag`
+or `forward_traversal_tag`, the following must be well-formed:
+
+    Incrementable i, j;
+    ++i;         // pre-increment
+    i == j;      // operator equal
+
+
+If `iterator_category` is convertible to
+`bidirectional_iterator_tag` or `bidirectional_traversal_tag`,
+the following expression must also be well-formed:
+
+    --i
+
+If `iterator_category` is convertible to
+`random_access_iterator_tag` or `random_access_traversal_tag`,
+the following must must also be valid:
+
+    counting_iterator::difference_type n;
+    i += n;
+    n = i - j;
+    i < j;
+
+
+[h3 Concepts]
+
+
+Specializations of `counting_iterator` model Readable Lvalue
+Iterator. In addition, they model the concepts corresponding to the
+iterator tags to which their `iterator_category` is convertible.
+Also, if `CategoryOrTraversal` is not `use_default` then
+`counting_iterator` models the concept corresponding to the iterator
+tag `CategoryOrTraversal`.  Otherwise, if
+`numeric_limits<Incrementable>::is_specialized`, then
+`counting_iterator` models Random Access Traversal Iterator.
+Otherwise, `counting_iterator` models the same iterator traversal
+concepts modeled by `Incrementable`.
+
+`counting_iterator<X,C1,D1>` is interoperable with
+`counting_iterator<Y,C2,D2>` if and only if `X` is
+interoperable with `Y`.
+
+
+[h3 Operations]
+
+
+In addition to the operations required by the concepts modeled by
+`counting_iterator`, `counting_iterator` provides the following
+operations.
+
+
+  counting_iterator();
+
+[*Requires: ] `Incrementable` is Default Constructible.\n
+[*Effects: ] Default construct the member `m_inc`.
+
+
+  counting_iterator(counting_iterator const& rhs);
+
+[*Effects: ] Construct member `m_inc` from `rhs.m_inc`.
+
+
+
+  explicit counting_iterator(Incrementable x);
+
+[*Effects: ] Construct member `m_inc` from `x`.
+
+
+  reference operator*() const;
+
+[*Returns: ] `m_inc`
+
+
+  counting_iterator& operator++();
+
+[*Effects: ] `++m_inc`\n
+[*Returns: ] `*this`
+
+
+  counting_iterator& operator--();
+
+[*Effects: ] `--m_inc`\n
+[*Returns: ] `*this`  
+
+
+  Incrementable const& base() const;
+
+[*Returns: ] `m_inc`
+
+
+[endsect]