diff --git a/doc/quickbook/algorithms.qbk b/doc/quickbook/algorithms.qbk new file mode 100644 index 0000000..e316c3a --- /dev/null +++ b/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 + T next(T x) + { + return ++x; + } + + template + T next(T x, Distance n) + { + std::advance(x, n); + return x; + } + + template + T prior(T x) + { + return --x; + } + + template + 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::iterator p = get_some_iterator(); + const std::list::iterator prev = boost::prior(p); + const std::list::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] diff --git a/doc/quickbook/iterator.qbk b/doc/quickbook/iterator.qbk index 0ec20b2..ff772de 100644 --- a/doc/quickbook/iterator.qbk +++ b/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]]