mirror of
https://github.com/boostorg/iterator.git
synced 2025-07-29 12:27:33 +02:00
Merge branch 'develop'
This commit is contained in:
Andrey Semashev
@ -16,7 +16,7 @@ boostbook standalone
|
||||
<xsl:param>boost.root=../../../..
|
||||
<xsl:param>toc.max.depth=3
|
||||
<xsl:param>toc.section.depth=3
|
||||
<xsl:param>chunk.section.depth=4
|
||||
<xsl:param>chunk.section.depth=2
|
||||
<format>pdf:<xsl:param>boost.url.prefix=http://www.boost.org/doc/libs/release/libs/iterator/doc
|
||||
;
|
||||
|
||||
|
||||
@ -1,10 +1,96 @@
|
||||
[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 provide a simple way around these problems:
|
||||
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)
|
||||
@ -32,7 +118,9 @@ The `next()` and `prior()` functions provide a simple way around these problems:
|
||||
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.]
|
||||
[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:
|
||||
|
||||
@ -42,22 +130,20 @@ Usage is simple:
|
||||
|
||||
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()`:
|
||||
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:
|
||||
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);
|
||||
|
||||
- `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.
|
||||
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.
|
||||
|
||||
[section Acknowledgements]
|
||||
[heading Acknowledgements]
|
||||
|
||||
Contributed by [@http://www.boost.org/people/dave_abrahams.htm Dave Abrahams]. Two-argument versions by Daniel Walker.
|
||||
|
||||
[endsect]
|
||||
|
||||
[endsect]
|
||||
|
||||
[endsect]
|
||||
|
||||
@ -4,7 +4,7 @@ The iterator concept checking classes provide a mechanism for a
|
||||
template to report better error messages when a user instantiates the
|
||||
template with a type that does not meet the requirements of the
|
||||
template. For an introduction to using concept checking classes, see
|
||||
the documentation for the boost::concept_check library.
|
||||
the documentation for the _concept_check_ library.
|
||||
|
||||
[h2 `iterator_concepts.hpp` Synopsis]
|
||||
|
||||
@ -51,4 +51,4 @@ the documentation for the boost::concept_check library.
|
||||
|
||||
}
|
||||
|
||||
[endsect]
|
||||
[endsect]
|
||||
|
||||
@ -3,7 +3,7 @@
|
||||
|
||||
[section:concepts_access Access]
|
||||
|
||||
[h2 Readable Iterator Concept]
|
||||
[section:readable Readable Iterator Concept]
|
||||
|
||||
A class or built-in type `X` models the *Readable Iterator* concept
|
||||
for value type `T` if, in addition to `X` being Assignable and
|
||||
@ -32,17 +32,18 @@ type `T`.
|
||||
[`U&`]
|
||||
[pre: `(*a).m` is well-defined. Equivalent to `(*a).m`.]
|
||||
]
|
||||
]
|
||||
|
||||
[h2 Writable Iterator Concept ]
|
||||
|
||||
|
||||
]
|
||||
|
||||
[endsect]
|
||||
|
||||
[section:writable Writable Iterator Concept]
|
||||
|
||||
A class or built-in type `X` models the *Writable Iterator* concept
|
||||
if, in addition to `X` being Copy Constructible, the following
|
||||
expressions are valid and respect the stated semantics. Writable
|
||||
Iterators have an associated *set of value types*.
|
||||
|
||||
[table Writable Iterator Requirements (in addition to Copy Constructible)
|
||||
[table Writable Iterator Requirements (in addition to Copy Constructible)
|
||||
[
|
||||
[Expression]
|
||||
[Return Type]
|
||||
@ -55,13 +56,15 @@ Iterators have an associated *set of value types*.
|
||||
]
|
||||
]
|
||||
|
||||
[h2 Swappable Iterator Concept]
|
||||
[endsect]
|
||||
|
||||
[section:swappable Swappable Iterator Concept]
|
||||
|
||||
A class or built-in type `X` models the *Swappable Iterator* concept
|
||||
if, in addition to `X` being Copy Constructible, the following
|
||||
expressions are valid and respect the stated semantics.
|
||||
|
||||
[table Swappable Iterator Requirements (in addition to Copy Constructible)
|
||||
[table Swappable Iterator Requirements (in addition to Copy Constructible)
|
||||
[
|
||||
[Expression]
|
||||
[Return Type]
|
||||
@ -77,7 +80,9 @@ expressions are valid and respect the stated semantics.
|
||||
[blurb *Note:* An iterator that is a model of the *Readable* and *Writable Iterator* concepts
|
||||
is also a model of *Swappable Iterator*. *--end note*]
|
||||
|
||||
[h2 Lvalue Iterator Concept]
|
||||
[endsect]
|
||||
|
||||
[section:lvalue Lvalue Iterator Concept]
|
||||
|
||||
The *Lvalue Iterator* concept adds the requirement that the return
|
||||
type of `operator*` type be a reference to the value type of the
|
||||
@ -101,17 +106,17 @@ iterator.
|
||||
|
||||
[endsect]
|
||||
|
||||
[endsect]
|
||||
|
||||
[section:concepts_traversal Traversal]
|
||||
|
||||
[h2 Incrementable Iterator Concept]
|
||||
|
||||
[section:incrementable Incrementable Iterator Concept]
|
||||
|
||||
A class or built-in type `X` models the *Incrementable Iterator*
|
||||
concept if, in addition to `X` being Assignable and Copy
|
||||
Constructible, the following expressions are valid and respect the
|
||||
stated semantics.
|
||||
|
||||
|
||||
[table Incrementable Iterator Requirements (in addition to Assignable, Copy Constructible)
|
||||
[
|
||||
[Expression ]
|
||||
@ -129,7 +134,7 @@ stated semantics.
|
||||
[``
|
||||
{
|
||||
X tmp = r;
|
||||
++r;
|
||||
++r;
|
||||
return tmp;
|
||||
}
|
||||
``]
|
||||
@ -141,7 +146,9 @@ stated semantics.
|
||||
]
|
||||
]
|
||||
|
||||
[h2 Single Pass Iterator Concept]
|
||||
[endsect]
|
||||
|
||||
[section:single_pass Single Pass Iterator Concept]
|
||||
|
||||
A class or built-in type `X` models the *Single Pass Iterator*
|
||||
concept if the following expressions are valid and respect the stated
|
||||
@ -175,8 +182,9 @@ semantics.
|
||||
]
|
||||
]
|
||||
|
||||
[endsect]
|
||||
|
||||
[h2 Forward Traversal Concept]
|
||||
[section:forward Forward Traversal Concept]
|
||||
|
||||
A class or built-in type `X` models the *Forward Traversal*
|
||||
concept if, in addition to `X` meeting the requirements of Default
|
||||
@ -211,7 +219,9 @@ valid and respect the stated semantics.
|
||||
]
|
||||
]
|
||||
|
||||
[h2 Bidirectional Traversal Concept]
|
||||
[endsect]
|
||||
|
||||
[section:bidirectional Bidirectional Traversal Concept]
|
||||
|
||||
A class or built-in type `X` models the *Bidirectional Traversal*
|
||||
concept if, in addition to `X` meeting the requirements of Forward
|
||||
@ -223,7 +233,7 @@ the stated semantics.
|
||||
[Expression]
|
||||
[Return Type]
|
||||
[Assertion/Semantics/Pre-/Post-condition]
|
||||
]
|
||||
]
|
||||
[
|
||||
[`--r`]
|
||||
[`X&`]
|
||||
@ -247,7 +257,9 @@ the stated semantics.
|
||||
]
|
||||
]
|
||||
|
||||
[h2 Random Access Traversal Concept]
|
||||
[endsect]
|
||||
|
||||
[section:random_access Random Access Traversal Concept]
|
||||
|
||||
A class or built-in type `X` models the *Random Access Traversal*
|
||||
concept if the following expressions are valid and respect the stated
|
||||
@ -255,8 +267,8 @@ semantics. In the table below, `Distance` is
|
||||
`iterator_traits<X>::difference_type` and `n` represents a
|
||||
constant object of type `Distance`.
|
||||
|
||||
[table Random Access Traversal Iterator Requirements (in addition to Bidirectional Traversal)
|
||||
[
|
||||
[table Random Access Traversal Iterator Requirements (in addition to Bidirectional Traversal)
|
||||
[
|
||||
[Expression]
|
||||
[Return Type]
|
||||
[Operational Semantics]
|
||||
@ -266,10 +278,10 @@ constant object of type `Distance`.
|
||||
[`r += n`]
|
||||
[ `X&`]
|
||||
[``
|
||||
{
|
||||
{
|
||||
Distance m = n;
|
||||
if (m >= 0)
|
||||
while (m--)
|
||||
while (m--)
|
||||
++r;
|
||||
else
|
||||
while (m++)
|
||||
@ -279,18 +291,18 @@ constant object of type `Distance`.
|
||||
``]
|
||||
[ ]
|
||||
]
|
||||
[
|
||||
[
|
||||
[`a + n`, `n + a`]
|
||||
[`X`]
|
||||
[``
|
||||
{
|
||||
{
|
||||
X tmp = a;
|
||||
return tmp+= n;
|
||||
}
|
||||
``]
|
||||
[]
|
||||
]
|
||||
[
|
||||
[
|
||||
[`r -= n`]
|
||||
[`X&`]
|
||||
[`return r += -n`]
|
||||
@ -300,9 +312,9 @@ constant object of type `Distance`.
|
||||
[`a - n`]
|
||||
[`X`]
|
||||
[``
|
||||
{
|
||||
{
|
||||
X tmp = a;
|
||||
return tmp-= n;
|
||||
return tmp-= n;
|
||||
}
|
||||
``]
|
||||
[]
|
||||
@ -320,7 +332,7 @@ constant object of type `Distance`.
|
||||
[pre: a is a *Readable Iterator*]
|
||||
]
|
||||
[
|
||||
[`a\[n\] = v`]
|
||||
[`a\[n\] = v`]
|
||||
[convertible to T]
|
||||
[`*(a + n) = v`]
|
||||
[pre: a is a *Writable iterator*]
|
||||
@ -359,4 +371,6 @@ constant object of type `Distance`.
|
||||
|
||||
[endsect]
|
||||
|
||||
[endsect]
|
||||
[endsect]
|
||||
|
||||
[endsect]
|
||||
|
||||
@ -141,7 +141,7 @@ standardize the gateway protocol. Note that even if
|
||||
open a safety loophole, as every core member function preserves the
|
||||
invariants of the iterator.
|
||||
|
||||
[h2 `operator\[\]`]
|
||||
[h2 `operator[]`]
|
||||
|
||||
The indexing operator for a generalized iterator presents special
|
||||
challenges. A random access iterator's `operator[]` is only
|
||||
@ -297,10 +297,10 @@ where *iterator-category* is defined as follows:
|
||||
|
||||
The `enable_if_interoperable` template used above is for exposition
|
||||
purposes. The member operators should only be in an overload set
|
||||
provided the derived types `Dr1` and `Dr2` are interoperable,
|
||||
provided the derived types `Dr1` and `Dr2` are interoperable,
|
||||
meaning that at least one of the types is convertible to the other. The
|
||||
`enable_if_interoperable` approach uses SFINAE to take the operators
|
||||
out of the overload set when the types are not interoperable.
|
||||
out of the overload set when the types are not interoperable.
|
||||
The operators should behave *as-if* `enable_if_interoperable`
|
||||
were defined to be:
|
||||
|
||||
@ -400,7 +400,7 @@ through member functions of class `iterator_core_access`.
|
||||
__ `operator arrow`_
|
||||
|
||||
[*Returns:] If `reference` is a reference type, an object of type `pointer` equal to: `&static_cast<Derived const*>(this)->dereference()`
|
||||
Otherwise returns an object of unspecified type such that,
|
||||
Otherwise returns an object of unspecified type such that,
|
||||
`(*static_cast<Derived const*>(this))->m` is equivalent to `(w = **static_cast<Derived const*>(this),
|
||||
w.m)` for some temporary object `w` of type `value_type`.
|
||||
|
||||
@ -417,7 +417,7 @@ w.m)` for some temporary object `w` of type `value_type`.
|
||||
|
||||
Derived& operator++();
|
||||
|
||||
[*Effects:]
|
||||
[*Effects:]
|
||||
|
||||
static_cast<Derived*>(this)->increment();
|
||||
return *static_cast<Derived*>(this);
|
||||
@ -457,7 +457,7 @@ w.m)` for some temporary object `w` of type `value_type`.
|
||||
Derived& operator-=(difference_type n);
|
||||
|
||||
[*Effects:]
|
||||
|
||||
|
||||
static_cast<Derived*>(this)->advance(-n);
|
||||
return *static_cast<Derived*>(this);
|
||||
|
||||
@ -493,10 +493,10 @@ w.m)` for some temporary object `w` of type `value_type`.
|
||||
[pre
|
||||
if `is_convertible<Dr2,Dr1>::value`
|
||||
|
||||
then
|
||||
then
|
||||
`((Dr1 const&)lhs).equal((Dr2 const&)rhs)`.
|
||||
|
||||
Otherwise,
|
||||
Otherwise,
|
||||
`((Dr2 const&)rhs).equal((Dr1 const&)lhs)`.
|
||||
]
|
||||
|
||||
@ -508,14 +508,14 @@ w.m)` for some temporary object `w` of type `value_type`.
|
||||
iterator_facade<Dr2,V2,TC2,R2,D2> const& rhs);
|
||||
|
||||
[*Returns:]
|
||||
|
||||
|
||||
[pre
|
||||
if `is_convertible<Dr2,Dr1>::value`
|
||||
|
||||
then
|
||||
then
|
||||
`!((Dr1 const&)lhs).equal((Dr2 const&)rhs)`.
|
||||
|
||||
Otherwise,
|
||||
Otherwise,
|
||||
`!((Dr2 const&)rhs).equal((Dr1 const&)lhs)`.
|
||||
]
|
||||
|
||||
@ -527,14 +527,14 @@ w.m)` for some temporary object `w` of type `value_type`.
|
||||
iterator_facade<Dr2,V2,TC2,R2,D2> const& rhs);
|
||||
|
||||
[*Returns:]
|
||||
|
||||
|
||||
[pre
|
||||
if `is_convertible<Dr2,Dr1>::value`
|
||||
|
||||
then
|
||||
then
|
||||
`((Dr1 const&)lhs).distance_to((Dr2 const&)rhs) < 0`.
|
||||
|
||||
Otherwise,
|
||||
Otherwise,
|
||||
`((Dr2 const&)rhs).distance_to((Dr1 const&)lhs) > 0`.
|
||||
]
|
||||
|
||||
@ -546,14 +546,14 @@ w.m)` for some temporary object `w` of type `value_type`.
|
||||
iterator_facade<Dr2,V2,TC2,R2,D2> const& rhs);
|
||||
|
||||
[*Returns:]
|
||||
|
||||
|
||||
[pre
|
||||
if `is_convertible<Dr2,Dr1>::value`
|
||||
|
||||
then
|
||||
then
|
||||
`((Dr1 const&)lhs).distance_to((Dr2 const&)rhs) <= 0`.
|
||||
|
||||
Otherwise,
|
||||
Otherwise,
|
||||
`((Dr2 const&)rhs).distance_to((Dr1 const&)lhs) >= 0`.
|
||||
]
|
||||
|
||||
@ -565,14 +565,14 @@ w.m)` for some temporary object `w` of type `value_type`.
|
||||
iterator_facade<Dr2,V2,TC2,R2,D2> const& rhs);
|
||||
|
||||
[*Returns:]
|
||||
|
||||
|
||||
[pre
|
||||
if `is_convertible<Dr2,Dr1>::value`
|
||||
|
||||
then
|
||||
then
|
||||
`((Dr1 const&)lhs).distance_to((Dr2 const&)rhs) > 0`.
|
||||
|
||||
Otherwise,
|
||||
Otherwise,
|
||||
`((Dr2 const&)rhs).distance_to((Dr1 const&)lhs) < 0`.
|
||||
]
|
||||
|
||||
@ -584,14 +584,14 @@ w.m)` for some temporary object `w` of type `value_type`.
|
||||
iterator_facade<Dr2,V2,TC2,R2,D2> const& rhs);
|
||||
|
||||
[*Returns:]
|
||||
|
||||
|
||||
[pre
|
||||
if `is_convertible<Dr2,Dr1>::value`
|
||||
|
||||
then
|
||||
then
|
||||
`((Dr1 const&)lhs).distance_to((Dr2 const&)rhs) >= 0`.
|
||||
|
||||
Otherwise,
|
||||
Otherwise,
|
||||
`((Dr2 const&)rhs).distance_to((Dr1 const&)lhs) <= 0`.
|
||||
]
|
||||
|
||||
@ -605,27 +605,27 @@ w.m)` for some temporary object `w` of type `value_type`.
|
||||
iterator_facade<Dr2,V2,TC2,R2,D2> const& rhs);
|
||||
|
||||
[*Return Type:]
|
||||
|
||||
|
||||
[pre
|
||||
if `is_convertible<Dr2,Dr1>::value`
|
||||
|
||||
then
|
||||
then
|
||||
`difference` shall be
|
||||
`iterator_traits<Dr1>::difference_type`.
|
||||
|
||||
Otherwise
|
||||
Otherwise
|
||||
`difference` shall be `iterator_traits<Dr2>::difference_type`
|
||||
]
|
||||
|
||||
[*Returns:]
|
||||
|
||||
|
||||
[pre
|
||||
if `is_convertible<Dr2,Dr1>::value`
|
||||
|
||||
then
|
||||
then
|
||||
`-((Dr1 const&)lhs).distance_to((Dr2 const&)rhs)`.
|
||||
|
||||
Otherwise,
|
||||
Otherwise,
|
||||
`((Dr2 const&)rhs).distance_to((Dr1 const&)lhs)`.
|
||||
]
|
||||
|
||||
@ -634,4 +634,4 @@ w.m)` for some temporary object `w` of type `value_type`.
|
||||
|
||||
[include facade_tutorial.qbk]
|
||||
|
||||
[endsect]
|
||||
[endsect]
|
||||
|
||||
@ -29,7 +29,10 @@
|
||||
|
||||
[/ Links ]
|
||||
|
||||
[def _iterator_ [@../../libs/iterator/doc/index.html Boost.Iterator]]
|
||||
[def _iterator_ [@../../../iterator/doc/index.html Boost.Iterator]]
|
||||
[def _concept_check_ [@../../../concept_check/index.html Boost.ConceptCheck]]
|
||||
|
||||
[template sub[x]'''<subscript>'''[x]'''</subscript>''']
|
||||
|
||||
[section:intro Introduction]
|
||||
|
||||
@ -71,19 +74,23 @@ and a _GOTW_50_. New-style iterators go well beyond
|
||||
patching up `vector<bool>`, though: there are lots of other
|
||||
iterators already in use which can't be adequately represented by
|
||||
the existing concepts. For details about the new iterator
|
||||
concepts, see our [@./new-iter-concepts.html Standard Proposal for New-Style Iterators].
|
||||
concepts, see our [@../new-iter-concepts.html Standard Proposal for New-Style Iterators].
|
||||
|
||||
[h2 Iterator Facade and Adaptor]
|
||||
|
||||
[def _facade_ [@./iterator_facade.html facade]]
|
||||
[def _adaptor_ [@./iterator_adaptor.html adaptor]]
|
||||
[/
|
||||
[def _facade_ [link iterator.generic.facade facade]]
|
||||
[def _adaptor_ [link iterator.generic.adaptor adaptor]]
|
||||
]
|
||||
[def _facade_ [@../iterator_facade.html facade]]
|
||||
[def _adaptor_ [@../iterator_adaptor.html adaptor]]
|
||||
|
||||
Writing standard-conforming iterators is tricky, but the need comes
|
||||
up often. In order to ease the implementation of new iterators,
|
||||
the Boost.Iterator library provides the _facade_ class template,
|
||||
which implements many useful defaults and compile-time checks
|
||||
designed to help the iterator author ensure that his iterator is
|
||||
correct.
|
||||
correct.
|
||||
|
||||
It is also common to define a new iterator that is similar to some
|
||||
underlying iterator or iterator-like type, but that modifies some
|
||||
@ -92,9 +99,9 @@ library supplies the _adaptor_ class template, which is specially
|
||||
designed to take advantage of as much of the underlying type's
|
||||
behavior as possible.
|
||||
|
||||
Both _facade_ and _adaptor_ as well as many of the `specialized
|
||||
adaptors`_ mentioned below have been proposed for standardization
|
||||
([@./facade-and-adaptor.html Standard Proposal For Iterator Facade and Adaptor]).
|
||||
Both _facade_ and _adaptor_ as well as many of the [link iterator.specialized specialized
|
||||
adaptors] mentioned below have been proposed for standardization
|
||||
([@../facade-and-adaptor.html Standard Proposal For Iterator Facade and Adaptor]).
|
||||
|
||||
[h2 Specialized Adaptors]
|
||||
|
||||
@ -103,15 +110,15 @@ iterator templates based on the Boost [link
|
||||
iterator.intro.iterator_facade_and_adaptor iterator facade and adaptor]
|
||||
templates.
|
||||
|
||||
[def _counting_ [@./counting_iterator.html `counting_iterator`]]
|
||||
[def _filter_ [@./filter_iterator.html `filter_iterator`]]
|
||||
[def _function_ [@./function_output_iterator.html `function_output_iterator`]]
|
||||
[def _indirect_ [@./indirect_iterator.html `indirect_iterator`]]
|
||||
[def _permutation_ [@./permutation_iterator.html `permutation_iterator`]]
|
||||
[def _reverse_ [@./reverse_iterator.html `reverse_iterator`]]
|
||||
[def _shared_ [@./shared_container_iterator.html `shared_container_iterator`]]
|
||||
[def _transform_ [@./transform_iterator.html `transform_iterator`]]
|
||||
[def _zip_ [@./zip_iterator.html `zip_iterator`]]
|
||||
[def _counting_ [link iterator.specialized.counting `counting_iterator`]]
|
||||
[def _filter_ [link iterator.specialized.filter `filter_iterator`]]
|
||||
[def _function_ [link iterator.specialized.function_output `function_output_iterator`]]
|
||||
[def _indirect_ [link iterator.specialized.indirect `indirect_iterator`]]
|
||||
[def _permutation_ [link iterator.specialized.permutation `permutation_iterator`]]
|
||||
[def _reverse_ [link iterator.specialized.reverse `reverse_iterator`]]
|
||||
[def _shared_ [link iterator.specialized.shared_container `shared_container_iterator`]]
|
||||
[def _transform_ [link iterator.specialized.transform `transform_iterator`]]
|
||||
[def _zip_ [link iterator.specialized.zip `zip_iterator`]]
|
||||
|
||||
[def _shared_ptr_ [@../../smart_ptr/shared_ptr.htm `shared_ptr`]]
|
||||
|
||||
@ -133,7 +140,7 @@ templates.
|
||||
|
||||
* _reverse_: an iterator which traverses the elements of some
|
||||
bidirectional sequence in reverse. Corrects many of the
|
||||
shortcomings of C++98's ``std::reverse_iterator``.
|
||||
shortcomings of C++98's `std::reverse_iterator`.
|
||||
|
||||
* _shared_: an iterator over elements of a container whose
|
||||
lifetime is maintained by a _shared_ptr_ stored in the iterator.
|
||||
@ -141,7 +148,7 @@ templates.
|
||||
* _transform_: an iterator over elements which are the result of
|
||||
applying some functional transformation to the elements of an
|
||||
underlying sequence. This component also replaces the old
|
||||
``projection_iterator_adaptor``.
|
||||
`projection_iterator_adaptor`.
|
||||
|
||||
* _zip_: an iterator over tuples of the elements at corresponding
|
||||
positions of heterogeneous underlying iterators.
|
||||
@ -150,9 +157,9 @@ templates.
|
||||
|
||||
[h3 Traits]
|
||||
|
||||
[def _pointee_ [@./pointee.html `pointee.hpp`]]
|
||||
[def _iterator_traits_ [@./iterator_traits.html `iterator_traits.hpp`]]
|
||||
[def _interoperable_ [@./interoperable.html `interoperable.hpp`]]
|
||||
[def _pointee_ [link iterator.utilities.traits `pointee.hpp`]]
|
||||
[def _iterator_traits_ [link iterator.utilities.iterator_traits `iterator_traits.hpp`]]
|
||||
[def _interoperable_ [@../interoperable.html `interoperable.hpp`]]
|
||||
[def _MPL_ [@../../mpl/doc/index.html [*MPL]]]
|
||||
|
||||
* _pointee_: Provides the capability to deduce the referent types
|
||||
@ -163,14 +170,15 @@ templates.
|
||||
retrieve an iterator's traits. Also corrects for the deficiencies
|
||||
of broken implementations of `std::iterator_traits`.
|
||||
|
||||
[\ * |interoperable|_ (PDF__): Provides an _MPL_ compatible metafunction for
|
||||
testing iterator interoperability
|
||||
[/
|
||||
* _interoperable_: Provides an _MPL_ compatible metafunction for
|
||||
testing iterator interoperability
|
||||
]
|
||||
|
||||
[h3 Testing and Concept Checking]
|
||||
|
||||
[def _iterator_concepts_ [@./iterator_concepts.html `iterator_concepts.hpp`]]
|
||||
[def _iterator_archetypes_ [@./iterator_archetypes.html `iterator_archetypes.hpp`]]
|
||||
[def _iterator_concepts_ [link iterator.concepts `iterator_concepts.hpp`]]
|
||||
[def _iterator_archetypes_ [link iterator.utilities.archetypes `iterator_archetypes.hpp`]]
|
||||
|
||||
* _iterator_concepts_: Concept checking classes for the new iterator concepts.
|
||||
|
||||
@ -182,8 +190,16 @@ The library provides a number of generic algorithms for use with iterators. Thes
|
||||
algorithms take advantage of the new concepts defined by the library to provide
|
||||
better performance and functionality.
|
||||
|
||||
[def _advance_ [link iterator.algorithms.advance `advance.hpp`]]
|
||||
[def _distance_ [link iterator.algorithms.distance `distance.hpp`]]
|
||||
[def _next_prior_ [link iterator.algorithms.next_prior `next_prior.hpp`]]
|
||||
|
||||
* _advance_: Provides `advance()` function for advancing an iterator a given number
|
||||
of positions forward or backward.
|
||||
|
||||
* _distance_: Provides `distance()` function for computing distance between two
|
||||
iterators.
|
||||
|
||||
* _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.
|
||||
@ -208,9 +224,9 @@ better performance and functionality.
|
||||
|
||||
[include concept_checking.qbk]
|
||||
|
||||
[include traits.qbk]
|
||||
[include iterator_traits.qbk]
|
||||
|
||||
[include utilities.qbk]
|
||||
[include type_traits.qbk]
|
||||
|
||||
[endsect]
|
||||
|
||||
@ -280,4 +296,3 @@ library you see today.
|
||||
|
||||
[endsect]
|
||||
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
|
||||
[section:traits Iterator Traits]
|
||||
[section:iterator_traits Iterator Traits]
|
||||
|
||||
`std::iterator_traits` provides access to five associated types
|
||||
of any iterator: its `value_type`, `reference`, `pointer`,
|
||||
@ -15,15 +15,15 @@ Header `<boost/iterator/iterator_traits.hpp>`:
|
||||
template <class Iterator>
|
||||
struct iterator_value
|
||||
{
|
||||
typedef typename
|
||||
std::iterator_traits<Iterator>::value_type
|
||||
typedef typename
|
||||
std::iterator_traits<Iterator>::value_type
|
||||
type;
|
||||
};
|
||||
|
||||
template <class Iterator>
|
||||
struct iterator_reference
|
||||
{
|
||||
typedef typename
|
||||
typedef typename
|
||||
std::iterator_traits<Iterator>::reference
|
||||
type;
|
||||
};
|
||||
@ -31,8 +31,8 @@ Header `<boost/iterator/iterator_traits.hpp>`:
|
||||
template <class Iterator>
|
||||
struct iterator_pointer
|
||||
{
|
||||
typedef typename
|
||||
std::iterator_traits<Iterator>::pointer
|
||||
typedef typename
|
||||
std::iterator_traits<Iterator>::pointer
|
||||
type;
|
||||
};
|
||||
|
||||
@ -1,7 +1,4 @@
|
||||
|
||||
[section:utilities Iterator Utilities]
|
||||
|
||||
[section:utilities_traits Traits]
|
||||
[section:traits Type Traits]
|
||||
|
||||
[h2 Overview]
|
||||
|
||||
@ -212,113 +209,3 @@ Otherwise, `type` is defined to the closest iterator traversal tag matching `C`.
|
||||
[*Requires:] `Iterator` shall be an iterator.
|
||||
|
||||
[endsect]
|
||||
|
||||
[section:utilities_testing Testing and Concept Checking]
|
||||
|
||||
The iterator concept checking classes provide a mechanism for a
|
||||
template to report better error messages when a user instantiates
|
||||
the template with a type that does not meet the requirements of the
|
||||
template.
|
||||
|
||||
For an introduction to using concept checking classes, see
|
||||
the documentation for the
|
||||
[@../../concept_check/index.html `boost::concept_check`] library.
|
||||
|
||||
|
||||
[h2 Reference]
|
||||
|
||||
[h3 Iterator Access Concepts]
|
||||
|
||||
* |Readable|_
|
||||
* |Writable|_
|
||||
* |Swappable|_
|
||||
* |Lvalue|_
|
||||
|
||||
[/ .. |Readable| replace:: *Readable Iterator* ]
|
||||
[/ .. _Readable: ReadableIterator.html ]
|
||||
[/ ]
|
||||
[/ .. |Writable| replace:: *Writable Iterator* ]
|
||||
[/ .. _Writable: WritableIterator.html ]
|
||||
[/ ]
|
||||
[/ .. |Swappable| replace:: *Swappable Iterator* ]
|
||||
[/ .. _Swappable: SwappableIterator.html ]
|
||||
[/ ]
|
||||
[/ .. |Lvalue| replace:: *Lvalue Iterator* ]
|
||||
[/ .. _Lvalue: LvalueIterator.html ]
|
||||
|
||||
|
||||
Iterator Traversal Concepts
|
||||
...........................
|
||||
|
||||
* |Incrementable|_
|
||||
* |SinglePass|_
|
||||
* |Forward|_
|
||||
* |Bidir|_
|
||||
* |Random|_
|
||||
|
||||
|
||||
[/ .. |Incrementable| replace:: *Incrementable Iterator* ]
|
||||
[/ .. _Incrementable: IncrementableIterator.html ]
|
||||
[/ ]
|
||||
[/ .. |SinglePass| replace:: *Single Pass Iterator* ]
|
||||
[/ .. _SinglePass: SinglePassIterator.html ]
|
||||
[/ ]
|
||||
[/ .. |Forward| replace:: *Forward Traversal* ]
|
||||
[/ .. _Forward: ForwardTraversal.html ]
|
||||
[/ ]
|
||||
[/ .. |Bidir| replace:: *Bidirectional Traversal* ]
|
||||
[/ .. _Bidir: BidirectionalTraversal.html ]
|
||||
[/ ]
|
||||
[/ .. |Random| replace:: *Random Access Traversal* ]
|
||||
[/ .. _Random: RandomAccessTraversal.html ]
|
||||
|
||||
|
||||
|
||||
[h3 `iterator_concepts.hpp` Synopsis]
|
||||
|
||||
namespace boost_concepts {
|
||||
|
||||
// Iterator Access Concepts
|
||||
|
||||
template <typename Iterator>
|
||||
class ReadableIteratorConcept;
|
||||
|
||||
template <
|
||||
typename Iterator
|
||||
, typename ValueType = std::iterator_traits<Iterator>::value_type
|
||||
>
|
||||
class WritableIteratorConcept;
|
||||
|
||||
template <typename Iterator>
|
||||
class SwappableIteratorConcept;
|
||||
|
||||
template <typename Iterator>
|
||||
class LvalueIteratorConcept;
|
||||
|
||||
// Iterator Traversal Concepts
|
||||
|
||||
template <typename Iterator>
|
||||
class IncrementableIteratorConcept;
|
||||
|
||||
template <typename Iterator>
|
||||
class SinglePassIteratorConcept;
|
||||
|
||||
template <typename Iterator>
|
||||
class ForwardTraversalConcept;
|
||||
|
||||
template <typename Iterator>
|
||||
class BidirectionalTraversalConcept;
|
||||
|
||||
template <typename Iterator>
|
||||
class RandomAccessTraversalConcept;
|
||||
|
||||
// Interoperability
|
||||
|
||||
template <typename Iterator, typename ConstIterator>
|
||||
class InteroperableIteratorConcept;
|
||||
|
||||
}
|
||||
|
||||
[endsect]
|
||||
|
||||
[endsect]
|
||||
Reference in New Issue
Block a user