mirror of
https://github.com/boostorg/iterator.git
synced 2025-05-10 07:33:53 +00:00
eaf1a48583
- Fixed multiple broken links to the documentation. Converted some of the links to internal references to the QuickBook documentation. Not all links converted because some of the QuickBook pages are not completely converted. - Renamed utilities.qbk to type_traits.qbk and removed the part duplicated by concept_checking.qbk. - Renamed traits.qbk to iterator_traits.qbk to better disambiguate with other type traits documented in type_traits.qbk. - Converted some of the headings in iterator concepts to sections to be able to give those sections ids. This allows to reference those sections from other places in the documentation. - In order to preserve the more compact pagination of the new sections (i.e. to have multiple sections on one page, like it was with headings) set chunk.section.depth=2 in the docs Jamfile.
150 lines
5.4 KiB
Plaintext
150 lines
5.4 KiB
Plaintext
[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.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.concepts_traversal.bidirectional Bidirectional Traversal Iterator], `n` should be non-negative.
|
|
|
|
[heading Complexity]
|
|
|
|
If `Iterator` models [link iterator.concepts.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.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.concepts_traversal.single_pass Single Pass Iterator].
|
|
|
|
[heading Preconditions]
|
|
|
|
If `Iterator` models [link iterator.concepts.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.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.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]
|