mirror of
https://github.com/boostorg/iterator.git
synced 2025-05-09 23:23:54 +00:00
Added documentation for advance and distance. Various cleanup and fixes.
- 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.
This commit is contained in:
Andrey Semashev
parent
52fbe950ec
commit
eaf1a48583
@ -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,12 +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 defined in `boost/next_prior.hpp` provide a simple way around these problems.
|
||||
|
||||
[section Synopsis]
|
||||
[heading Synopsis]
|
||||
|
||||
template <class T>
|
||||
T next(T x)
|
||||
@ -36,7 +120,7 @@ The `next()` and `prior()` functions defined in `boost/next_prior.hpp` provide a
|
||||
|
||||
[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.]
|
||||
|
||||
[endsect]
|
||||
[heading Usage]
|
||||
|
||||
Usage is simple:
|
||||
|
||||
@ -56,12 +140,10 @@ First, `boost::next()` and `boost::prior()` are compatible not only with iterato
|
||||
|
||||
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]
|
||||
Loading…
x
Reference in New Issue
Block a user