Squashed 'third_party/boostorg/iterator/' content from commit b2adecb
Change-Id: I284a73816f9cc846742923879275b84c6e0c915c
git-subtree-dir: third_party/boostorg/iterator
git-subtree-split: b2adecb951af025698618f19a3c838bd314966dc
diff --git a/doc/quickbook/algorithms.qbk b/doc/quickbook/algorithms.qbk
new file mode 100644
index 0000000..0904123
--- /dev/null
+++ b/doc/quickbook/algorithms.qbk
@@ -0,0 +1,149 @@
+[section:algorithms Algorithms]
+
+[section:advance Function template `advance()`]
+
+The `boost::iterators::advance` function template is an adapted version of `std::advance` for the Boost iterator [link iterator.concepts.traversal traversal concepts].
+
+[heading Header]
+
+ <boost/iterator/advance.hpp>
+
+[heading Synopsis]
+
+ template <typename Iterator, typename Distance>
+ constexpr void advance(Iterator& it, Distance n);
+
+
+[heading Description]
+
+Moves `it` forward by `n` increments (or backward by `|n|` decrements if `n` is negative).
+
+[heading Requirements]
+
+`Iterator` should model Incrementable Iterator.
+
+[heading Preconditions]
+
+Let `it`[sub `i`] be the iterator obtained by incrementing (or decrementing if `n` is negative) `it` by `i`. All the iterators `it`[sub `i`] for `i` = 0, 1, 2, ..., `|n|` should be valid.
+
+If `Iterator` does not model [link iterator.concepts.traversal.bidirectional Bidirectional Traversal Iterator], `n` should be non-negative.
+
+[heading Complexity]
+
+If `Iterator` models [link iterator.concepts.traversal.random_access Random Access Traversal Iterator], it takes constant time; otherwise it takes linear time.
+
+[heading Notes]
+
+* This function is not a customization point and is protected against being found by argument-dependent lookup (ADL).
+* This function is `constexpr` only in C++14 or later.
+
+[heading Acknowledgements]
+
+Contributed by Michel Morin.
+
+[endsect]
+
+[section:distance Function template `distance()`]
+
+The `boost::iterators::distance` function template is an adapted version of `std::distance` for the Boost iterator [link iterator.concepts.traversal traversal concepts].
+
+[heading Header]
+
+ <boost/iterator/distance.hpp>
+
+[heading Synopsis]
+
+ template <typename Iterator>
+ constexpr typename iterator_difference<Iterator>::type
+ distance(Iterator first, Iterator last);
+
+[heading Description]
+
+Computes the (signed) distance from `first` to `last`.
+
+[heading Requirements]
+
+`Iterator` should model [link iterator.concepts.traversal.single_pass Single Pass Iterator].
+
+[heading Preconditions]
+
+If `Iterator` models [link iterator.concepts.traversal.random_access Random Access Traversal Iterator], `[first, last)` or `[last, first)` should be valid; otherwise `[first, last)` should be valid.
+
+[heading Complexity]
+
+If `Iterator` models [link iterator.concepts.traversal.random_access Random Access Traversal Iterator], it takes constant time; otherwise it takes linear time.
+
+[heading Notes]
+
+* This function is not a customization point and is protected against being found by argument-dependent lookup (ADL).
+* This function is `constexpr` only in C++14 or later.
+
+[heading Acknowledgements]
+
+Contributed by Michel Morin.
+
+[endsect]
+
+[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 defined in `boost/next_prior.hpp` provide a simple way around these problems.
+
+[heading Synopsis]
+
+ 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 implementations above are given for exposition only. The actual implementation has the same effect for iterators, but has different properties, as documented later.]
+
+[heading Usage]
+
+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()`.
+
+First, `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);
+
+Second, `boost::next()` and `boost::prior()` use [link iterator.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.
+
+[heading Acknowledgements]
+
+Contributed by [@http://www.boost.org/people/dave_abrahams.htm Dave Abrahams]. Two-argument versions by Daniel Walker.
+
+[endsect]
+
+[endsect]