Merge branch 'develop'

This commit is contained in:
Andrey Semashev
2017-08-26 20:07:54 +03:00
8 changed files with 222 additions and 220 deletions

View File

@ -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
;

View File

@ -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]

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 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]

View File

@ -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
@ -34,8 +34,9 @@ type `T`.
]
]
[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
@ -55,7 +56,9 @@ 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
@ -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 ]
@ -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
@ -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
@ -360,3 +372,5 @@ constant object of type `Distance`.
[endsect]
[endsect]
[endsect]

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
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

View File

@ -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,12 +74,16 @@ 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,
@ -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]

View File

@ -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`,

View File

@ -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]