Added next/prior documentation.

doc/quickbook/algorithms.qbk

@@ -0,0 +1,63 @@
+[section:algorithms Algorithms]
+
+[section:next_prior Function templates `next()` and `prior()`]
+
+Certain data types, such as the C++ Standard Library's forward and bidirectional iterators, do not provide addition and subtraction via `operator+()` or `operator-()`. This means that non-modifying computation of the next or prior value requires a temporary, even though `operator++()` or `operator--()` is provided. It also means that writing code like `itr+1` inside a template restricts the iterator category to random access iterators.
+
+The `next()` and `prior()` functions provide a simple way around these problems:
+
+    template <class T>
+    T next(T x)
+    {
+        return ++x;
+    }
+
+    template <class T, class Distance>
+    T next(T x, Distance n)
+    {
+        std::advance(x, n);
+        return x;
+    }
+
+    template <class T>
+    T prior(T x)
+    {
+        return --x;
+    }
+
+    template <class T, class Distance>
+    T prior(T x, Distance n)
+    {
+        std::advance(x, -n);
+        return x;
+    }
+
+[note Function implementation above is given for exposition only. The actual implementation has the same effect for iterators, but has different properties, as documented later.]
+
+Usage is simple:
+
+    const std::list<T>::iterator p = get_some_iterator();
+    const std::list<T>::iterator prev = boost::prior(p);
+    const std::list<T>::iterator next = boost::next(prev, 2);
+
+The distance from the given iterator should be supplied as an absolute value. For example, the iterator four iterators prior to the given iterator `p` may be obtained by `prior(p, 4)`.
+
+With C++11, the standard library provides `std::next()` and `std::prev()` function templates, which serve the same purpose. However, there are advantages to `boost::next()` and `boost::prior()`:
+
+- `boost::next()` and `boost::prior()` are compatible not only with iterators but with any type that provides arithmetic operators `operator++()`, `operator--()`, `operator+()`, `operator-()`, `operator+=()` or `operator-=()`. For example, this is possible:
+
+    int x = 10;
+    int y = boost::next(x, 5);
+    assert(y == 15);
+
+- `boost::next()` and `boost::prior()` use [link iterator.concepts.concepts_traversal traversal categories] to select the most efficient implementation. For some kinds of iterators, such as [link iterator.specialized.transform transform iterators], the standard iterator category does not reflect the traversal category correctly and therefore `std::next()` and `std::prev()` will fall back to linear complexity.
+
+[section Acknowledgements]
+
+Contributed by [@http://www.boost.org/people/dave_abrahams.htm Dave Abrahams]. Two-argument versions by Daniel Walker.
+
+[endsect]
+
+[endsect]
+
+[endsect]

doc/quickbook/iterator.qbk

@@ -176,6 +176,18 @@ templates.
 
 * _iterator_archetypes_: Concept archetype classes for the new iterators concepts.
 
+[h2 Iterator Algorithms]
+
+The library provides a number of generic algorithms for use with iterators. These
+algorithms take advantage of the new concepts defined by the library to provide
+better performance and functionality.
+
+[def _next_prior_       [link iterator.algorithms.next_prior `next_prior.hpp`]]
+
+* _next_prior_: Provides `next()` and `prior()` functions for obtaining
+  next and prior iterators to a given iterator. The functions are also compatible
+  with non-iterator types.
+
 [endsect]
 
 [include concepts.qbk]
@@ -202,6 +214,8 @@ templates.
 
 [endsect]
 
+[include algorithms.qbk]
+
 [section:upgrading Upgrading from the old Boost Iterator Adaptor Library]
 
 [def _type_generator_ [@http://www.boost.org/more/generic_programming.html#type_generator type generator]]