boost_mirror/iterator
1
0
Fork 0
mirror of https://github.com/boostorg/iterator.git synced 2025-05-11 05:23:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

Added documentation for advance and distance. Various cleanup and fixes.

Browse Source 
- 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 2017-08-26 19:56:23 +03:00
parent 52fbe950ec
commit eaf1a48583
8 changed files with 215 additions and 217 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/Jamfile.v2
View File

@ -16,7 +16,7 @@ boostbook standalone
<xsl:param>boost.root=../../../.. <xsl:param>boost.root=../../../..
<xsl:param>toc.max.depth=3 <xsl:param>toc.max.depth=3
<xsl:param>toc.section.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 <format>pdf:<xsl:param>boost.url.prefix=http://www.boost.org/doc/libs/release/libs/iterator/doc
; ;

92
doc/quickbook/algorithms.qbk
View File

@ -1,12 +1,96 @@
[section:algorithms Algorithms] [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()`] [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. 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. 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> template <class T>
T next(T x) 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.] [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: 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. 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. Contributed by [@http://www.boost.org/people/dave_abrahams.htm Dave Abrahams]. Two-argument versions by Daniel Walker.
[endsect] [endsect]
[endsect] [endsect]
[endsect]

4
doc/quickbook/concept_checking.qbk
View File

@ -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 to report better error messages when a user instantiates the
template with a type that does not meet the requirements of the template with a type that does not meet the requirements of the
template. For an introduction to using concept checking classes, see 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] [h2 `iterator_concepts.hpp` Synopsis]
@ -51,4 +51,4 @@ the documentation for the boost::concept_check library.
} }
[endsect] [endsect]

74
doc/quickbook/concepts.qbk
View File

@ -3,7 +3,7 @@
[section:concepts_access Access] [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 A class or built-in type `X` models the *Readable Iterator* concept
for value type `T` if, in addition to `X` being Assignable and for value type `T` if, in addition to `X` being Assignable and
@ -32,17 +32,18 @@ type `T`.
[`U&`] [`U&`]
[pre: `(*a).m` is well-defined. Equivalent to `(*a).m`.] [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 A class or built-in type `X` models the *Writable Iterator* concept
if, in addition to `X` being Copy Constructible, the following if, in addition to `X` being Copy Constructible, the following
expressions are valid and respect the stated semantics. Writable expressions are valid and respect the stated semantics. Writable
Iterators have an associated *set of value types*. 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] [Expression]
[Return Type] [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 A class or built-in type `X` models the *Swappable Iterator* concept
if, in addition to `X` being Copy Constructible, the following if, in addition to `X` being Copy Constructible, the following
expressions are valid and respect the stated semantics. 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] [Expression]
[Return Type] [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 [blurb *Note:* An iterator that is a model of the *Readable* and *Writable Iterator* concepts
is also a model of *Swappable Iterator*. *--end note*] 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 The *Lvalue Iterator* concept adds the requirement that the return
type of `operator*` type be a reference to the value type of the type of `operator*` type be a reference to the value type of the
@ -101,17 +106,17 @@ iterator.
[endsect] [endsect]
[endsect]
[section:concepts_traversal Traversal] [section:concepts_traversal Traversal]
[h2 Incrementable Iterator Concept] [section:incrementable Incrementable Iterator Concept]
A class or built-in type `X` models the *Incrementable Iterator* A class or built-in type `X` models the *Incrementable Iterator*
concept if, in addition to `X` being Assignable and Copy concept if, in addition to `X` being Assignable and Copy
Constructible, the following expressions are valid and respect the Constructible, the following expressions are valid and respect the
stated semantics. stated semantics.
[table Incrementable Iterator Requirements (in addition to Assignable, Copy Constructible) [table Incrementable Iterator Requirements (in addition to Assignable, Copy Constructible)
[ [
[Expression ] [Expression ]
@ -129,7 +134,7 @@ stated semantics.
[`` [``
{ {
X tmp = r; X tmp = r;
++r; ++r;
return tmp; 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* A class or built-in type `X` models the *Single Pass Iterator*
concept if the following expressions are valid and respect the stated 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* A class or built-in type `X` models the *Forward Traversal*
concept if, in addition to `X` meeting the requirements of Default 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* A class or built-in type `X` models the *Bidirectional Traversal*
concept if, in addition to `X` meeting the requirements of Forward concept if, in addition to `X` meeting the requirements of Forward
@ -223,7 +233,7 @@ the stated semantics.
[Expression] [Expression]
[Return Type] [Return Type]
[Assertion/Semantics/Pre-/Post-condition] [Assertion/Semantics/Pre-/Post-condition]
] ]
[ [
[`--r`] [`--r`]
[`X&`] [`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* A class or built-in type `X` models the *Random Access Traversal*
concept if the following expressions are valid and respect the stated 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 `iterator_traits<X>::difference_type` and `n` represents a
constant object of type `Distance`. 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] [Expression]
[Return Type] [Return Type]
[Operational Semantics] [Operational Semantics]
@ -266,10 +278,10 @@ constant object of type `Distance`.
[`r += n`] [`r += n`]
[ `X&`] [ `X&`]
[`` [``
{ {
Distance m = n; Distance m = n;
if (m >= 0) if (m >= 0)
while (m--) while (m--)
++r; ++r;
else else
while (m++) while (m++)
@ -279,18 +291,18 @@ constant object of type `Distance`.
``] ``]
[ ] [ ]
] ]
[ [
[`a + n`, `n + a`] [`a + n`, `n + a`]
[`X`] [`X`]
[`` [``
{ {
X tmp = a; X tmp = a;
return tmp+= n; return tmp+= n;
} }
``] ``]
[] []
] ]
[ [
[`r -= n`] [`r -= n`]
[`X&`] [`X&`]
[`return r += -n`] [`return r += -n`]
@ -300,9 +312,9 @@ constant object of type `Distance`.
[`a - n`] [`a - n`]
[`X`] [`X`]
[`` [``
{ {
X tmp = a; X tmp = a;
return tmp-= n; return tmp-= n;
} }
``] ``]
[] []
@ -320,7 +332,7 @@ constant object of type `Distance`.
[pre: a is a *Readable Iterator*] [pre: a is a *Readable Iterator*]
] ]
[ [
[`a\[n\] = v`] [`a\[n\] = v`]
[convertible to T] [convertible to T]
[`*(a + n) = v`] [`*(a + n) = v`]
[pre: a is a *Writable iterator*] [pre: a is a *Writable iterator*]
@ -359,4 +371,6 @@ constant object of type `Distance`.
[endsect] [endsect]
[endsect] [endsect]
[endsect]

60
doc/quickbook/facade.qbk
View File

@ -141,7 +141,7 @@ standardize the gateway protocol. Note that even if
open a safety loophole, as every core member function preserves the open a safety loophole, as every core member function preserves the
invariants of the iterator. invariants of the iterator.
[h2 `operator\[\]`] [h2 `operator[]`]
The indexing operator for a generalized iterator presents special The indexing operator for a generalized iterator presents special
challenges. A random access iterator's `operator[]` is only 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 The `enable_if_interoperable` template used above is for exposition
purposes. The member operators should only be in an overload set 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 meaning that at least one of the types is convertible to the other. The
`enable_if_interoperable` approach uses SFINAE to take the operators `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` The operators should behave *as-if* `enable_if_interoperable`
were defined to be: were defined to be:
@ -400,7 +400,7 @@ through member functions of class `iterator_core_access`.
__ `operator arrow`_ __ `operator arrow`_
[*Returns:] If `reference` is a reference type, an object of type `pointer` equal to: `&static_cast<Derived const*>(this)->dereference()` [*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), `(*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`. 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++(); Derived& operator++();
[*Effects:] [*Effects:]
static_cast<Derived*>(this)->increment(); static_cast<Derived*>(this)->increment();
return *static_cast<Derived*>(this); 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); Derived& operator-=(difference_type n);
[*Effects:] [*Effects:]
static_cast<Derived*>(this)->advance(-n); static_cast<Derived*>(this)->advance(-n);
return *static_cast<Derived*>(this); return *static_cast<Derived*>(this);
@ -493,10 +493,10 @@ w.m)` for some temporary object `w` of type `value_type`.
[pre [pre
if `is_convertible<Dr2,Dr1>::value` if `is_convertible<Dr2,Dr1>::value`
then then
`((Dr1 const&)lhs).equal((Dr2 const&)rhs)`. `((Dr1 const&)lhs).equal((Dr2 const&)rhs)`.
Otherwise, Otherwise,
`((Dr2 const&)rhs).equal((Dr1 const&)lhs)`. `((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); iterator_facade<Dr2,V2,TC2,R2,D2> const& rhs);
[*Returns:] [*Returns:]
[pre [pre
if `is_convertible<Dr2,Dr1>::value` if `is_convertible<Dr2,Dr1>::value`
then then
`!((Dr1 const&)lhs).equal((Dr2 const&)rhs)`. `!((Dr1 const&)lhs).equal((Dr2 const&)rhs)`.
Otherwise, Otherwise,
`!((Dr2 const&)rhs).equal((Dr1 const&)lhs)`. `!((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); iterator_facade<Dr2,V2,TC2,R2,D2> const& rhs);
[*Returns:] [*Returns:]
[pre [pre
if `is_convertible<Dr2,Dr1>::value` if `is_convertible<Dr2,Dr1>::value`
then then
`((Dr1 const&)lhs).distance_to((Dr2 const&)rhs) < 0`. `((Dr1 const&)lhs).distance_to((Dr2 const&)rhs) < 0`.
Otherwise, Otherwise,
`((Dr2 const&)rhs).distance_to((Dr1 const&)lhs) > 0`. `((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); iterator_facade<Dr2,V2,TC2,R2,D2> const& rhs);
[*Returns:] [*Returns:]
[pre [pre
if `is_convertible<Dr2,Dr1>::value` if `is_convertible<Dr2,Dr1>::value`
then then
`((Dr1 const&)lhs).distance_to((Dr2 const&)rhs) <= 0`. `((Dr1 const&)lhs).distance_to((Dr2 const&)rhs) <= 0`.
Otherwise, Otherwise,
`((Dr2 const&)rhs).distance_to((Dr1 const&)lhs) >= 0`. `((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); iterator_facade<Dr2,V2,TC2,R2,D2> const& rhs);
[*Returns:] [*Returns:]
[pre [pre
if `is_convertible<Dr2,Dr1>::value` if `is_convertible<Dr2,Dr1>::value`
then then
`((Dr1 const&)lhs).distance_to((Dr2 const&)rhs) > 0`. `((Dr1 const&)lhs).distance_to((Dr2 const&)rhs) > 0`.
Otherwise, Otherwise,
`((Dr2 const&)rhs).distance_to((Dr1 const&)lhs) < 0`. `((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); iterator_facade<Dr2,V2,TC2,R2,D2> const& rhs);
[*Returns:] [*Returns:]
[pre [pre
if `is_convertible<Dr2,Dr1>::value` if `is_convertible<Dr2,Dr1>::value`
then then
`((Dr1 const&)lhs).distance_to((Dr2 const&)rhs) >= 0`. `((Dr1 const&)lhs).distance_to((Dr2 const&)rhs) >= 0`.
Otherwise, Otherwise,
`((Dr2 const&)rhs).distance_to((Dr1 const&)lhs) <= 0`. `((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); iterator_facade<Dr2,V2,TC2,R2,D2> const& rhs);
[*Return Type:] [*Return Type:]
[pre [pre
if `is_convertible<Dr2,Dr1>::value` if `is_convertible<Dr2,Dr1>::value`
then then
`difference` shall be `difference` shall be
`iterator_traits<Dr1>::difference_type`. `iterator_traits<Dr1>::difference_type`.
Otherwise Otherwise
`difference` shall be `iterator_traits<Dr2>::difference_type` `difference` shall be `iterator_traits<Dr2>::difference_type`
] ]
[*Returns:] [*Returns:]
[pre [pre
if `is_convertible<Dr2,Dr1>::value` if `is_convertible<Dr2,Dr1>::value`
then then
`-((Dr1 const&)lhs).distance_to((Dr2 const&)rhs)`. `-((Dr1 const&)lhs).distance_to((Dr2 const&)rhs)`.
Otherwise, Otherwise,
`((Dr2 const&)rhs).distance_to((Dr1 const&)lhs)`. `((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] [include facade_tutorial.qbk]
[endsect] [endsect]

73
doc/quickbook/iterator.qbk
View File

@ -29,7 +29,10 @@
[/ Links ] [/ 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] [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 patching up `vector<bool>`, though: there are lots of other
iterators already in use which can't be adequately represented by iterators already in use which can't be adequately represented by
the existing concepts. For details about the new iterator 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] [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 Writing standard-conforming iterators is tricky, but the need comes
up often. In order to ease the implementation of new iterators, up often. In order to ease the implementation of new iterators,
the Boost.Iterator library provides the _facade_ class template, the Boost.Iterator library provides the _facade_ class template,
which implements many useful defaults and compile-time checks which implements many useful defaults and compile-time checks
designed to help the iterator author ensure that his iterator is 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 It is also common to define a new iterator that is similar to some
underlying iterator or iterator-like type, but that modifies 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 designed to take advantage of as much of the underlying type's
behavior as possible. behavior as possible.
Both _facade_ and _adaptor_ as well as many of the `specialized Both _facade_ and _adaptor_ as well as many of the [link iterator.specialized specialized
adaptors`_ mentioned below have been proposed for standardization adaptors] mentioned below have been proposed for standardization
([@./facade-and-adaptor.html Standard Proposal For Iterator Facade and Adaptor]). ([@../facade-and-adaptor.html Standard Proposal For Iterator Facade and Adaptor]).
[h2 Specialized Adaptors] [h2 Specialized Adaptors]
@ -103,15 +110,15 @@ iterator templates based on the Boost [link
iterator.intro.iterator_facade_and_adaptor iterator facade and adaptor] iterator.intro.iterator_facade_and_adaptor iterator facade and adaptor]
templates. templates.
[def _counting_ [@./counting_iterator.html `counting_iterator`]] [def _counting_ [link iterator.specialized.counting `counting_iterator`]]
[def _filter_ [@./filter_iterator.html `filter_iterator`]] [def _filter_ [link iterator.specialized.filter `filter_iterator`]]
[def _function_ [@./function_output_iterator.html `function_output_iterator`]] [def _function_ [link iterator.specialized.function_output `function_output_iterator`]]
[def _indirect_ [@./indirect_iterator.html `indirect_iterator`]] [def _indirect_ [link iterator.specialized.indirect `indirect_iterator`]]
[def _permutation_ [@./permutation_iterator.html `permutation_iterator`]] [def _permutation_ [link iterator.specialized.permutation `permutation_iterator`]]
[def _reverse_ [@./reverse_iterator.html `reverse_iterator`]] [def _reverse_ [link iterator.specialized.reverse `reverse_iterator`]]
[def _shared_ [@./shared_container_iterator.html `shared_container_iterator`]] [def _shared_ [link iterator.specialized.shared_container `shared_container_iterator`]]
[def _transform_ [@./transform_iterator.html `transform_iterator`]] [def _transform_ [link iterator.specialized.transform `transform_iterator`]]
[def _zip_ [@./zip_iterator.html `zip_iterator`]] [def _zip_ [link iterator.specialized.zip `zip_iterator`]]
[def _shared_ptr_ [@../../smart_ptr/shared_ptr.htm `shared_ptr`]] [def _shared_ptr_ [@../../smart_ptr/shared_ptr.htm `shared_ptr`]]
@ -133,7 +140,7 @@ templates.
* _reverse_: an iterator which traverses the elements of some * _reverse_: an iterator which traverses the elements of some
bidirectional sequence in reverse. Corrects many of the 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 * _shared_: an iterator over elements of a container whose
lifetime is maintained by a _shared_ptr_ stored in the iterator. 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 * _transform_: an iterator over elements which are the result of
applying some functional transformation to the elements of an applying some functional transformation to the elements of an
underlying sequence. This component also replaces the old underlying sequence. This component also replaces the old
``projection_iterator_adaptor``. `projection_iterator_adaptor`.
* _zip_: an iterator over tuples of the elements at corresponding * _zip_: an iterator over tuples of the elements at corresponding
positions of heterogeneous underlying iterators. positions of heterogeneous underlying iterators.
@ -150,9 +157,9 @@ templates.
[h3 Traits] [h3 Traits]
[def _pointee_ [@./pointee.html `pointee.hpp`]] [def _pointee_ [link iterator.utilities.traits `pointee.hpp`]]
[def _iterator_traits_ [@./iterator_traits.html `iterator_traits.hpp`]] [def _iterator_traits_ [link iterator.utilities.iterator_traits `iterator_traits.hpp`]]
[def _interoperable_ [@./interoperable.html `interoperable.hpp`]] [def _interoperable_ [@../interoperable.html `interoperable.hpp`]]
[def _MPL_ [@../../mpl/doc/index.html [*MPL]]] [def _MPL_ [@../../mpl/doc/index.html [*MPL]]]
* _pointee_: Provides the capability to deduce the referent types * _pointee_: Provides the capability to deduce the referent types
@ -163,14 +170,15 @@ templates.
retrieve an iterator's traits. Also corrects for the deficiencies retrieve an iterator's traits. Also corrects for the deficiencies
of broken implementations of `std::iterator_traits`. 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] [h3 Testing and Concept Checking]
[def _iterator_concepts_ [@./iterator_concepts.html `iterator_concepts.hpp`]] [def _iterator_concepts_ [link iterator.concepts `iterator_concepts.hpp`]]
[def _iterator_archetypes_ [@./iterator_archetypes.html `iterator_archetypes.hpp`]] [def _iterator_archetypes_ [link iterator.utilities.archetypes `iterator_archetypes.hpp`]]
* _iterator_concepts_: Concept checking classes for the new iterator concepts. * _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 algorithms take advantage of the new concepts defined by the library to provide
better performance and functionality. 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`]] [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_prior_: Provides `next()` and `prior()` functions for obtaining
next and prior iterators to a given iterator. The functions are also compatible next and prior iterators to a given iterator. The functions are also compatible
with non-iterator types. with non-iterator types.
@ -208,9 +224,9 @@ better performance and functionality.
[include concept_checking.qbk] [include concept_checking.qbk]
[include traits.qbk] [include iterator_traits.qbk]
[include utilities.qbk] [include type_traits.qbk]
[endsect] [endsect]
@ -280,4 +296,3 @@ library you see today.
[endsect] [endsect]

12
doc/quickbook/traits.qbk → doc/quickbook/iterator_traits.qbk
View File

@ -1,5 +1,5 @@
[section:traits Iterator Traits] [section:iterator_traits Iterator Traits]
`std::iterator_traits` provides access to five associated types `std::iterator_traits` provides access to five associated types
of any iterator: its `value_type`, `reference`, `pointer`, of any iterator: its `value_type`, `reference`, `pointer`,
@ -15,15 +15,15 @@ Header `<boost/iterator/iterator_traits.hpp>`:
template <class Iterator> template <class Iterator>
struct iterator_value struct iterator_value
{ {
typedef typename typedef typename
std::iterator_traits<Iterator>::value_type std::iterator_traits<Iterator>::value_type
type; type;
}; };
template <class Iterator> template <class Iterator>
struct iterator_reference struct iterator_reference
{ {
typedef typename typedef typename
std::iterator_traits<Iterator>::reference std::iterator_traits<Iterator>::reference
type; type;
}; };
@ -31,8 +31,8 @@ Header `<boost/iterator/iterator_traits.hpp>`:
template <class Iterator> template <class Iterator>
struct iterator_pointer struct iterator_pointer
{ {
typedef typename typedef typename
std::iterator_traits<Iterator>::pointer std::iterator_traits<Iterator>::pointer
type; type;
}; };

115
doc/quickbook/utilities.qbk → doc/quickbook/type_traits.qbk
View File

@ -1,7 +1,4 @@
[section:traits Type Traits]
[section:utilities Iterator Utilities]
[section:utilities_traits Traits]
[h2 Overview] [h2 Overview]
@ -212,113 +209,3 @@ Otherwise, `type` is defined to the closest iterator traversal tag matching `C`.
[*Requires:] `Iterator` shall be an iterator. [*Requires:] `Iterator` shall be an iterator.
[endsect] [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]