forked from boostorg/range
Boost.Range documentation update iteration.
[SVN r61647]
This commit is contained in:
Neil Groves
@ -1,6 +1,6 @@
|
||||
[section:adaptors Range Adaptors]
|
||||
|
||||
[section:adaptors_introduction Introduction and motivation]
|
||||
[section:introduction Introduction and motivation]
|
||||
|
||||
A [*Range Adaptor] is a class that wraps an existing Range to provide a new Range with different behaviour. Since the behaviour of Ranges is determined by their associated iterators, a Range Adaptor simply wraps the underlying iterators with new special iterators. In this example
|
||||
|
||||
@ -145,7 +145,7 @@ rng | boost::adaptors::uniqued
|
||||
|
||||
[endsect]
|
||||
|
||||
[section:adaptors_general_requirements General Requirements]
|
||||
[section:general_requirements General Requirements]
|
||||
|
||||
In the description of generator expressions, the following notation is used:
|
||||
|
||||
@ -183,7 +183,7 @@ rng | boost::adaptors::adaptor_generator
|
||||
|
||||
[endsect]
|
||||
|
||||
[section:adaptors_reference Reference]
|
||||
[section:reference Reference]
|
||||
[include adaptors/adjacent_filtered.qbk]
|
||||
[include adaptors/copied.qbk]
|
||||
[include adaptors/filtered.qbk]
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
[section:adjacent_find Range Algorithm - adjacent_find]
|
||||
[section:adjacent_find adjacent_find]
|
||||
|
||||
[heading Prototype]
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
[section:copy Range Algorithm - copy]
|
||||
[section:copy copy]
|
||||
|
||||
[heading Prototype]
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
[section:copy_backward Range Algorithm - copy_backward]
|
||||
[section:copy_backward copy_backward]
|
||||
|
||||
[heading Prototype]
|
||||
|
||||
|
||||
32
doc/reference/algorithm/count_if.qbk
Normal file
32
doc/reference/algorithm/count_if.qbk
Normal file
@ -0,0 +1,32 @@
|
||||
[section:count_if count_if]
|
||||
|
||||
[heading Prototype]
|
||||
|
||||
``
|
||||
template<class SinglePassRange, class UnaryPredicate>
|
||||
typename range_difference<const SinglePassRange>::type
|
||||
count_if(const SinglePassRange& rng, UnaryPredicate pred);
|
||||
``
|
||||
|
||||
[heading Description]
|
||||
|
||||
`count_if` returns the number of elements `x` in `rng` where `pred(x)` is `true`.
|
||||
|
||||
[heading Definition]
|
||||
|
||||
Defined in the header file `boost/range/algorithm/count_if.hpp`
|
||||
|
||||
[heading Requirements]
|
||||
|
||||
* `SinglePassRange` is a model of the __single_pass_range__ Concept.
|
||||
* `UnaryPredicate` is a model of the `UnaryPredicateConcept`.
|
||||
* `SinglePassRange`'s value type is a model of the `EqualityComparableConcept`.
|
||||
* The value type of `SinglePassRange` is convertible to the argument type of `UnaryPredicate`.
|
||||
|
||||
[heading Complexity]
|
||||
|
||||
Linear. Exactly `distance(rng)` invocations of `pred`.
|
||||
|
||||
[endsect]
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
[section:fill Range Algorithm - fill]
|
||||
[section:fill fill]
|
||||
|
||||
[heading Prototype]
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
[section:fill_n Range Algorithm - fill_n]
|
||||
[section:fill_n fill_n]
|
||||
|
||||
[heading Prototype]
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
[section:generate Range Algorithm - generate]
|
||||
[section:generate generate]
|
||||
|
||||
[heading Prototype]
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
[section:inplace_merge Range Algorithm - inplace_merge]
|
||||
[section:inplace_merge inplace_merge]
|
||||
|
||||
[heading Prototype]
|
||||
|
||||
@ -7,18 +7,18 @@ template<class BidirectionalRange>
|
||||
BidirectionalRange&
|
||||
inplace_merge( BidirectionalRange& rng,
|
||||
typename range_iterator<BidirectionalRange>::type middle );
|
||||
|
||||
|
||||
template<class BidirectionalRange>
|
||||
const BidirectionalRange&
|
||||
inplace_merge( const BidirectionalRange& rng,
|
||||
typename range_iterator<const BidirectionalRange>::type middle );
|
||||
|
||||
|
||||
template<class BidirectionalRange, class BinaryPredicate>
|
||||
BidirectionalRange&
|
||||
inplace_merge( BidirectionalRange& rng,
|
||||
typename range_iterator<BidirectionalRange>::type middle,
|
||||
BinaryPredicate pred );
|
||||
|
||||
|
||||
template<class BidirectionalRange, class BinaryPredicate>
|
||||
const BidirectionalRange&
|
||||
inplace_merge( const BidirectionalRange& rng,
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
[section:merge Range Algorithm - merge]
|
||||
[section:merge merge]
|
||||
|
||||
[heading Prototype]
|
||||
|
||||
|
||||
@ -75,7 +75,7 @@ mismatch(const SinglePassRange1& rng1, SinglePassRange2& rng2,
|
||||
|
||||
[heading Description]
|
||||
|
||||
The versions of `mismatch` that return an iterator, return an iterator to the first position where `rng1` and `rng2` differ.
|
||||
`mismatch` finds the first position where the two ranges `rng1` and `rng2` differ.
|
||||
|
||||
Equality is determined by `operator==` for non-predicate versions of `mismatch`, and by satisfying `pred` in the predicate versions.
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
[section:nth_element Range Algorithm - nth_element]
|
||||
[section:nth_element nth_element]
|
||||
|
||||
[heading Prototype]
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
[section:partial_sort Range Algorithm - partial_sort]
|
||||
[section:partial_sort partial_sort]
|
||||
|
||||
[heading Prototype]
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
[section:partition Range Algorithm - partition]
|
||||
[section:partition partition]
|
||||
|
||||
[heading Prototype]
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
[section:random_shuffle Range Algorithm - random_shuffle]
|
||||
[section:random_shuffle random_shuffle]
|
||||
|
||||
[heading Prototype]
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
[section:remove Range Algorithm - remove]
|
||||
[section:remove remove]
|
||||
|
||||
[heading Prototype]
|
||||
|
||||
|
||||
34
doc/reference/algorithm/remove_copy.qbk
Normal file
34
doc/reference/algorithm/remove_copy.qbk
Normal file
@ -0,0 +1,34 @@
|
||||
[section:remove_copy remove_copy]
|
||||
|
||||
[heading Prototype]
|
||||
|
||||
``
|
||||
template<class ForwardRange, class Outputiterator, class Value>
|
||||
OutputIterator
|
||||
remove_copy(ForwardRange& rng, OutputIterator out, const Value& val);
|
||||
|
||||
template<class ForwardRange, class OutputIterator, class Value>
|
||||
OutputIterator
|
||||
remove_copy(const ForwardRange& rng, OutputIterator out, const Value& val);
|
||||
``
|
||||
|
||||
[heading Description]
|
||||
|
||||
`remove_copy` copied all of the elements `x` from `rng` for which `x == val` is `false`.
|
||||
|
||||
[heading Definition]
|
||||
|
||||
Defined in the header file `boost/range/algorithm/remove_copy.hpp`
|
||||
|
||||
[heading Requirements]
|
||||
|
||||
* `ForwardRange` is a model of the __forward_range__ Concept.
|
||||
* `ForwardRange` is mutable.
|
||||
* `Value` is a model of the `EqualityComparableConcept`.
|
||||
* Objects of type `Value` can be compared for equality with objects of `ForwardRange`'s value type.
|
||||
|
||||
[heading Complexity]
|
||||
|
||||
Linear. `remove_copy` performs exactly `distance(rng)` comparisons for equality.
|
||||
|
||||
[endsect]
|
||||
33
doc/reference/algorithm/remove_copy_if.qbk
Normal file
33
doc/reference/algorithm/remove_copy_if.qbk
Normal file
@ -0,0 +1,33 @@
|
||||
[section:remove_copy_if remove_copy_if]
|
||||
|
||||
[heading Prototype]
|
||||
|
||||
``
|
||||
template<class ForwardRange, class Outputiterator, class UnaryPred>
|
||||
OutputIterator
|
||||
remove_copy_if(ForwardRange& rng, OutputIterator out, UnaryPred pred);
|
||||
|
||||
template<class ForwardRange, class OutputIterator, class UnaryPred>
|
||||
OutputIterator
|
||||
remove_copy_if(const ForwardRange& rng, OutputIterator out, UnaryPred pred);
|
||||
``
|
||||
|
||||
[heading Description]
|
||||
|
||||
`remove_copy_if` copied all of the elements `x` from `rng` for which `pred(x)` is `false`.
|
||||
|
||||
[heading Definition]
|
||||
|
||||
Defined in the header file `boost/range/algorithm/remove_copy_if.hpp`
|
||||
|
||||
[heading Requirements]
|
||||
|
||||
* `ForwardRange` is a model of the __forward_range__ Concept.
|
||||
* `ForwardRange` is mutable.
|
||||
* `UnaryPred` is a model of the `UnaryPredicateConcept`.
|
||||
|
||||
[heading Complexity]
|
||||
|
||||
Linear. `remove_copy_if` performs exactly `distance(rng)` comparisons with UnaryPred.
|
||||
|
||||
[endsect]
|
||||
@ -1,4 +1,4 @@
|
||||
[section:remove_if Range Algorithm - remove_if]
|
||||
[section:remove_if remove_if]
|
||||
|
||||
[heading Prototype]
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
[section:replace Range Algorithm - replace]
|
||||
[section:replace replace]
|
||||
|
||||
[heading Prototype]
|
||||
|
||||
|
||||
33
doc/reference/algorithm/replace_copy.qbk
Normal file
33
doc/reference/algorithm/replace_copy.qbk
Normal file
@ -0,0 +1,33 @@
|
||||
[section:replace_copy replace_copy]
|
||||
|
||||
[heading Prototype]
|
||||
|
||||
``
|
||||
template<class ForwardRange, class OutputIterator, class Value>
|
||||
OutputIterator replace_copy(const ForwardRange& rng, OutputIterator out,
|
||||
const Value& what, const Value& with_what);
|
||||
``
|
||||
|
||||
[heading Description]
|
||||
|
||||
`replace_copy` copy every element `x` in `rng` such that the corresponding element in the output range `y` is `x == what ? with_what : x`.
|
||||
|
||||
[heading Definition]
|
||||
|
||||
Defined in the header file `boost/range/algorithm/replace_copy.hpp`
|
||||
|
||||
[heading Requirements]
|
||||
|
||||
* `ForwardRange` is a model of the __forward_range__ Concept.
|
||||
* `ForwardRange` is mutable.
|
||||
* `Value` is convertible to `ForwardRange`'s value type.
|
||||
* `Value` is a model of the `AssignableConcept`.
|
||||
* `OutputIterator` is a model of the `OutputIteratorConcept`.
|
||||
|
||||
[heading Complexity]
|
||||
|
||||
Linear. `replace_copy` performs exactly `distance(rng)`.
|
||||
|
||||
[endsect]
|
||||
|
||||
|
||||
34
doc/reference/algorithm/replace_copy_if.qbk
Normal file
34
doc/reference/algorithm/replace_copy_if.qbk
Normal file
@ -0,0 +1,34 @@
|
||||
[section:replace_copy_if replace_copy_if]
|
||||
|
||||
[heading Prototype]
|
||||
|
||||
``
|
||||
template<class ForwardRange, class OutputIterator, class UnaryPredicate, class Value>
|
||||
OutputIterator replace_copy_if(const ForwardRange& rng, OutputIterator out,
|
||||
UnaryPredicate pred, const Value& with_what);
|
||||
``
|
||||
|
||||
[heading Description]
|
||||
|
||||
`replace_copy_if` copy every element `x` in `rng` such that the corresponding element in the output range `y` is `pred(x) ? with_what : x`.
|
||||
|
||||
[heading Definition]
|
||||
|
||||
Defined in the header file `boost/range/algorithm/replace_copy_if.hpp`
|
||||
|
||||
[heading Requirements]
|
||||
|
||||
* `ForwardRange` is a model of the __forward_range__ Concept.
|
||||
* `ForwardRange` is mutable.
|
||||
* `Value` is convertible to `ForwardRange`'s value type.
|
||||
* `Value` is a model of the `AssignableConcept`.
|
||||
* `OutputIterator` is a model of the `OutputIteratorConcept`.
|
||||
* `UnaryPredicate` is a model of the `UnaryPredicateConcept`.
|
||||
|
||||
[heading Complexity]
|
||||
|
||||
Linear. `replace_copy_if` performs exactly `distance(rng)` evaluations of `pred`.
|
||||
|
||||
[endsect]
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
[section:replace_if Range Algorithm - replace_if]
|
||||
[section:replace_if replace_if]
|
||||
|
||||
[heading Prototype]
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
[section:reverse Range Algorithm - reverse]
|
||||
[section:reverse reverse]
|
||||
|
||||
[heading Prototype]
|
||||
|
||||
|
||||
31
doc/reference/algorithm/reverse_copy.qbk
Normal file
31
doc/reference/algorithm/reverse_copy.qbk
Normal file
@ -0,0 +1,31 @@
|
||||
[section:reverse_copy reverse_copy]
|
||||
|
||||
[heading Prototype]
|
||||
|
||||
``
|
||||
template<class BidirectionalRange, class OutputIterator>
|
||||
OutputIterator reverse_copy(const BidirectionalRange& rng, OutputIterator out);
|
||||
``
|
||||
|
||||
[heading Description]
|
||||
|
||||
`reverse_copy` copies the elements from `rng` in reverse order to `out`.
|
||||
Returns the output iterator one passed the last copied element.
|
||||
|
||||
[heading Definition]
|
||||
|
||||
Defined in the header file `boost/range/algorithm/reverse_copy.hpp`
|
||||
|
||||
[heading Requirements]
|
||||
|
||||
* `BidirectionalRange` is a model of the __bidirectional_range__ Concept.
|
||||
* `BidirectionalRange` is mutable.
|
||||
* `OutputIterator` is a model of the `OutputIteratorConcept`.
|
||||
|
||||
[heading Complexity]
|
||||
|
||||
Linear. `reverse_copy` makes `distance(rng)` copies.
|
||||
|
||||
[endsect]
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
[section:rotate Range Algorithm - rotate]
|
||||
[section:rotate rotate]
|
||||
|
||||
[heading Prototype]
|
||||
|
||||
@ -6,7 +6,7 @@
|
||||
template<class ForwardRange>
|
||||
ForwardRange& rotate(ForwardRange& rng,
|
||||
typename range_iterator<ForwardRange>::type middle);
|
||||
|
||||
|
||||
template<class ForwardRange>
|
||||
const ForwardRange& rotate(const ForwardRange& rng,
|
||||
typename range_iterator<const ForwardRange>::type middle);
|
||||
|
||||
38
doc/reference/algorithm/rotate_copy.qbk
Normal file
38
doc/reference/algorithm/rotate_copy.qbk
Normal file
@ -0,0 +1,38 @@
|
||||
[section:rotate_copy rotate_copy]
|
||||
|
||||
[heading Prototype]
|
||||
|
||||
``
|
||||
template<class ForwardRange, class OutputIterator>
|
||||
OutputIterator rotate_copy(
|
||||
const ForwardRange& rng,
|
||||
typename range_iterator<ForwardRange>::type middle,
|
||||
OutputIterator out);
|
||||
``
|
||||
|
||||
[heading Description]
|
||||
|
||||
`rotate_copy` rotates the elements in a range. It copies the two ranges `[begin(rng), middle)` and `[middle, end(rng))` to `out`.
|
||||
|
||||
[heading Definition]
|
||||
|
||||
Defined in the header file `boost/range/algorithm/rotate_copy.hpp`
|
||||
|
||||
[heading Requirements]
|
||||
|
||||
* `ForwardRange` is a model of the __forward_range__ Concept.
|
||||
* `ForwardRange` is mutable.
|
||||
* `OutputIterator` is a model of the `OutputIteratorConcept`.
|
||||
|
||||
[heading Precondition:]
|
||||
|
||||
* `[begin(rng), middle)` is a valid range.
|
||||
* `[middle, end(rng))` is a valid range.
|
||||
|
||||
[heading Complexity]
|
||||
|
||||
Linear. Exactly `distance(rng)` elements are copied.
|
||||
|
||||
[endsect]
|
||||
|
||||
|
||||
58
doc/reference/algorithm/search_n.qbk
Normal file
58
doc/reference/algorithm/search_n.qbk
Normal file
@ -0,0 +1,58 @@
|
||||
[section:search_n search_n]
|
||||
|
||||
[heading Prototype]
|
||||
|
||||
``
|
||||
template<class ForwardRange, class Integer, class Value>
|
||||
typename range_iterator<ForwardRange>::type
|
||||
search_n(ForwardRange& rng, Integer n, const Value& value);
|
||||
|
||||
template<class ForwardRange, class Integer, class Value>
|
||||
typename range_iterator<const ForwardRange>::type
|
||||
search_n(const ForwardRange& rng, Integer n, const Value& value);
|
||||
|
||||
template<class ForwardRange, class Integer, class Value, class BinaryPredicate>
|
||||
typename range_iterator<ForwardRange>::type
|
||||
search_n(ForwardRange& rng, Integer n, const Value& value,
|
||||
BinaryPredicate binary_pred);
|
||||
|
||||
template<class ForwardRange, class Integer, class Value, class BinaryPredicate>
|
||||
typename range_iterator<const ForwardRange>::type
|
||||
search_n(const ForwardRange& rng, Integer n, const Value& value,
|
||||
BinaryPredicate binary_pred);
|
||||
``
|
||||
|
||||
[heading Description]
|
||||
|
||||
`search_n` searches `rng` for a sequence of length `n` equal to `value` where
|
||||
equality is determined by operator== in the non-predicate case, and by a
|
||||
predicate when one is supplied.
|
||||
|
||||
[heading Definition]
|
||||
|
||||
Defined in the header file `boost/range/algorithm/search_n.hpp`
|
||||
|
||||
[heading Requirements]
|
||||
|
||||
[*For the non-predicate versions:]
|
||||
|
||||
* `ForwardRange` is a model of the __forward_range__ Concept.
|
||||
* `ForwardRange`'s value type is a model of the `EqualityComparableConcept`.
|
||||
* `ForwardRange`s value type can be compared for equality with `Value`.
|
||||
* `Integer` is a model of the `IntegerConcept`.
|
||||
|
||||
[*For the predicate versions:]
|
||||
|
||||
* `ForwardRange` is a model of the __forward_range__ Concept.
|
||||
* `BinaryPredicate` is a model of the `BinaryPredicateConcept`.
|
||||
* `ForwardRange`'s value type is convertible to `BinaryPredicate`'s first argument type.
|
||||
* `Value` is convertible to `BinaryPredicate`'s second argument type.
|
||||
* `Integer` is a model of the `IntegerConcept`.
|
||||
|
||||
[heading Complexity]
|
||||
|
||||
Average complexity is Linear. Worst-case complexity is quadratic.
|
||||
|
||||
[endsect]
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
[section:sort Range Algorithm - sort]
|
||||
[section:sort sort]
|
||||
|
||||
[heading Prototype]
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
[section:stable_partition Range Algorithm - stable_partition]
|
||||
[section:stable_partition stable_partition]
|
||||
|
||||
[heading Prototype]
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
[section:stable_sort Range Algorithm - stable_sort]
|
||||
[section:stable_sort stable_sort]
|
||||
|
||||
[heading Prototype]
|
||||
|
||||
|
||||
32
doc/reference/algorithm/swap_ranges.qbk
Normal file
32
doc/reference/algorithm/swap_ranges.qbk
Normal file
@ -0,0 +1,32 @@
|
||||
[section:swap_ranges swap_ranges]
|
||||
|
||||
[heading Prototype]
|
||||
|
||||
``
|
||||
template<class SinglePassRange1, class SinglePassRange2>
|
||||
SinglePassRange2& swap_ranges(SinglePassRange1& rng1, SinglePassRange& rng2);
|
||||
``
|
||||
|
||||
[heading Description]
|
||||
|
||||
`swap_ranges` swaps each element `x` in `rng1` with the corresponding element `y` in `rng2`.
|
||||
Returns a reference to `rng2`.
|
||||
|
||||
[heading Definition]
|
||||
|
||||
Defined in the header file `boost/range/algorithm/swap_ranges.hpp`
|
||||
|
||||
[heading Requirements]
|
||||
|
||||
* `SinglePassRange1` is a model of the __single_pass_range__ Concept.
|
||||
* `SinglePassRange1` is mutable.
|
||||
* `SinglePassRange2` is a model of the __single_pass_range__ Concept.
|
||||
* `SinglePassRange2` is mutable.
|
||||
|
||||
[heading Complexity]
|
||||
|
||||
Linear. Exactly `distance(rng1)` elements are swapped.
|
||||
|
||||
[endsect]
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
[section:transform Range Algorithm - transform]
|
||||
[section:transform transform]
|
||||
|
||||
[heading Prototype]
|
||||
|
||||
@ -11,7 +11,7 @@ template<
|
||||
OutputIterator transform(const SinglePassRange1& rng,
|
||||
OutputIterator out,
|
||||
UnaryOperation fun);
|
||||
|
||||
|
||||
template<
|
||||
class SinglePassRange1,
|
||||
class SinglePassRange2,
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
[section:unique Range Algorithm - unique]
|
||||
[section:unique unique]
|
||||
|
||||
[heading Prototype]
|
||||
|
||||
|
||||
44
doc/reference/algorithm/unique_copy.qbk
Normal file
44
doc/reference/algorithm/unique_copy.qbk
Normal file
@ -0,0 +1,44 @@
|
||||
[section:unique_copy unique_copy]
|
||||
|
||||
[heading Prototype]
|
||||
|
||||
``
|
||||
template<class SinglePassRange, class OutputIterator>
|
||||
OutputIterator unique_copy(const SinglePassRange& rng, OutputIterator out);
|
||||
|
||||
template<class SinglePassRange, class OutputIterator, class BinaryPredicate>
|
||||
OutputIterator unique_copy(const SinglePassRange& rng, OutputIterator out, BinaryPredicate pred);
|
||||
``
|
||||
|
||||
[heading Description]
|
||||
|
||||
`unique_copy` copies the first element of each sequence of duplicates encountered in `rng` to `out`.
|
||||
|
||||
Equality is determined by the predicate if one is supplied, or by `operator==()` for `SinglePassRange`'s value type.
|
||||
|
||||
[heading Definition]
|
||||
|
||||
Defined in the header file `boost/range/algorithm/unique_copy.hpp`
|
||||
|
||||
[heading Requirements]
|
||||
|
||||
[*For the non-predicate versions of unique:]
|
||||
|
||||
* `SinglePassRange` is a model of the __single_pass_range__ Concept.
|
||||
* `SinglePassRange` is mutable.
|
||||
* `SinglePassRange`'s value type is a model of the `EqualityComparableConcept`.
|
||||
* `OutputIterator` is a model of the `OutputIteratorConcept`.
|
||||
|
||||
[*For the predicate versions of unique:]
|
||||
|
||||
* `SinglePassRange` is a model of the __single_pass_range__ Concept.
|
||||
* `SinglePassRange` is mutable.
|
||||
* `BinaryPredicate` is a model of the `BinaryPredicateConcept`.
|
||||
* `SinglePassRange`'s value type is convertible to `BinaryPredicate`'s first argument type and to `BinaryPredicate`'s second argument type.
|
||||
* `OutputIterator` is a model of the `OutputIteratorConcept`.
|
||||
|
||||
[heading Complexity]
|
||||
|
||||
Linear. `O(N)` where `N` is `distance(rng)`. Exactly `distance(rng)` comparisons are performed.
|
||||
|
||||
[endsect]
|
||||
32
doc/reference/algorithm_ext/copy_n.qbk
Normal file
32
doc/reference/algorithm_ext/copy_n.qbk
Normal file
@ -0,0 +1,32 @@
|
||||
[section:copy_n copy_n]
|
||||
|
||||
[heading Prototype]
|
||||
|
||||
``
|
||||
template<class SinglePassRange, class Size, class OutputIterator>
|
||||
OutputIterator copy_n(const SinglePassRange& rng, Size n, OutputIterator out);
|
||||
``
|
||||
|
||||
[heading Description]
|
||||
|
||||
`copy_n` is provided to completely replicate the standard algorithm header,
|
||||
it is preferable to use Range Adaptors and the extension functions to achieve
|
||||
the same result with greater safety.
|
||||
|
||||
`copy_n` copies elements from `[boost::begin(rng), boost::begin(rng) + n)` to the range `[out, out + n)`
|
||||
|
||||
[heading Definition]
|
||||
|
||||
Defined in the header file `boost/range/algorithm_ext/copy_n.hpp`
|
||||
|
||||
[heading Requirements]
|
||||
|
||||
# `SinglePassRange` is a model of the __single_pass_range__ Concept.
|
||||
# `Size` is a model of the `Integer` Concept.
|
||||
# `OutputIterator` is a model of the `OutputIteratorConcept`.
|
||||
|
||||
[heading Complexity]
|
||||
|
||||
Linear. Exactly `n` elements are copied.
|
||||
|
||||
[endsect]
|
||||
35
doc/reference/algorithm_ext/is_sorted.qbk
Normal file
35
doc/reference/algorithm_ext/is_sorted.qbk
Normal file
@ -0,0 +1,35 @@
|
||||
[section:is_sorted is_sorted]
|
||||
|
||||
[heading Prototype]
|
||||
|
||||
``
|
||||
template<class SinglePassRange>
|
||||
bool is_sorted(const SinglePassRange& rng);
|
||||
|
||||
template<class SinglePassRange, class BinaryPredicate>
|
||||
bool is_sorted(const SinglePassRange& rng, BinaryPredicate pred);
|
||||
``
|
||||
|
||||
[heading Description]
|
||||
|
||||
`is_sorted` determines if a range is sorted.
|
||||
For the non-predicate version the return value is `true` if and only if for
|
||||
each adjacent elements `[x,y]` the expression `x < y` is `true`.
|
||||
For the predicate version the return value is `true` is and only if for each
|
||||
adjacent elements `[x,y]` the expression `pred(x,y)` is `true`.
|
||||
|
||||
[heading Definition]
|
||||
|
||||
Defined in the header file `boost/range/algorithm_ext/is_sorted.hpp`
|
||||
|
||||
[heading Requirements]
|
||||
|
||||
# `SinglePassRange` is a model of the __single_pass_range__ Concept.
|
||||
# `BinaryPredicate` is a model of the `BinaryPredicate` Concept.
|
||||
# The value type of `SinglePassRange` is convertible to both argument types of `BinaryPredicate`.
|
||||
|
||||
[heading Complexity]
|
||||
|
||||
Linear. A maximum of `distance(rng)` comparisons are performed.
|
||||
|
||||
[endsect]
|
||||
@ -78,7 +78,7 @@ and there is no need to worry about generating an invalid range. Furthermore, if
|
||||
|
||||
[endsect]
|
||||
|
||||
[section:range_algorithm_mutating_algorithms Mutating algorithms]
|
||||
[section:mutating Mutating algorithms]
|
||||
[include algorithm/copy.qbk]
|
||||
[include algorithm/copy_backward.qbk]
|
||||
[include algorithm/fill.qbk]
|
||||
@ -91,21 +91,31 @@ and there is no need to worry about generating an invalid range. Furthermore, if
|
||||
[include algorithm/partition.qbk]
|
||||
[include algorithm/random_shuffle.qbk]
|
||||
[include algorithm/remove.qbk]
|
||||
[include algorithm/remove_copy.qbk]
|
||||
[include algorithm/remove_copy_if.qbk]
|
||||
[include algorithm/remove_if.qbk]
|
||||
[include algorithm/replace.qbk]
|
||||
[include algorithm/replace_copy.qbk]
|
||||
[include algorithm/replace_copy_if.qbk]
|
||||
[include algorithm/replace_if.qbk]
|
||||
[include algorithm/reverse.qbk]
|
||||
[include algorithm/reverse_copy.qbk]
|
||||
[include algorithm/rotate.qbk]
|
||||
[include algorithm/rotate_copy.qbk]
|
||||
[include algorithm/sort.qbk]
|
||||
[include algorithm/stable_partition.qbk]
|
||||
[include algorithm/stable_sort.qbk]
|
||||
[include algorithm/swap_ranges.qbk]
|
||||
[include algorithm/transform.qbk]
|
||||
[include algorithm/unique.qbk]
|
||||
[include algorithm/unique_copy.qbk]
|
||||
[endsect]
|
||||
|
||||
[section:range_algorithm_non_mutating_algorithms Non-mutating algorithms]
|
||||
[section:non_mutating Non-mutating algorithms]
|
||||
[include algorithm/adjacent_find.qbk]
|
||||
[include algorithm/binary_search.qbk]
|
||||
[include algorithm/count.qbk]
|
||||
[include algorithm/count_if.qbk]
|
||||
[include algorithm/equal.qbk]
|
||||
[include algorithm/equal_range.qbk]
|
||||
[include algorithm/for_each.qbk]
|
||||
@ -119,10 +129,11 @@ and there is no need to worry about generating an invalid range. Furthermore, if
|
||||
[include algorithm/min_element.qbk]
|
||||
[include algorithm/mismatch.qbk]
|
||||
[include algorithm/search.qbk]
|
||||
[include algorithm/search_n.qbk]
|
||||
[include algorithm/upper_bound.qbk]
|
||||
[endsect]
|
||||
|
||||
[section:set_algorithms Set algorithms]
|
||||
[section:set Set algorithms]
|
||||
[include algorithm/includes.qbk]
|
||||
[include algorithm/set_union.qbk]
|
||||
[include algorithm/set_intersection.qbk]
|
||||
@ -130,23 +141,25 @@ and there is no need to worry about generating an invalid range. Furthermore, if
|
||||
[include algorithm/set_symmetric_difference.qbk]
|
||||
[endsect]
|
||||
|
||||
[section:heap_algorithms Heap algorithms]
|
||||
[section:heap Heap algorithms]
|
||||
[include algorithm/push_heap.qbk]
|
||||
[include algorithm/pop_heap.qbk]
|
||||
[include algorithm/make_heap.qbk]
|
||||
[include algorithm/sort_heap.qbk]
|
||||
[endsect]
|
||||
|
||||
[section:permutation_algorithms Permutation algorithms]
|
||||
[section:permutation Permutation algorithms]
|
||||
[include algorithm/next_permutation.qbk]
|
||||
[include algorithm/prev_permutation.qbk]
|
||||
[endsect]
|
||||
|
||||
[section:range_algorithm_new_algorithms New algorithms]
|
||||
[section:new New algorithms]
|
||||
[include algorithm_ext/copy_n.qbk]
|
||||
[include algorithm_ext/erase.qbk]
|
||||
[include algorithm_ext/for_each.qbk]
|
||||
[include algorithm_ext/insert.qbk]
|
||||
[include algorithm_ext/iota.qbk]
|
||||
[include algorithm_ext/is_sorted.qbk]
|
||||
[include algorithm_ext/overwrite.qbk]
|
||||
[include algorithm_ext/push_back.qbk]
|
||||
[include algorithm_ext/push_front.qbk]
|
||||
@ -154,7 +167,7 @@ and there is no need to worry about generating an invalid range. Furthermore, if
|
||||
[include algorithm_ext/remove_erase_if.qbk]
|
||||
[endsect]
|
||||
|
||||
[section:range_numeric Numeric algorithms]
|
||||
[section:numeric Numeric algorithms]
|
||||
[include numeric/accumulate.qbk]
|
||||
[include numeric/adjacent_difference.qbk]
|
||||
[include numeric/inner_product.qbk]
|
||||
|
||||
296
doc/reference/utilities.qbk
Normal file
296
doc/reference/utilities.qbk
Normal file
@ -0,0 +1,296 @@
|
||||
[section:utilities Utilities]
|
||||
|
||||
Having an abstraction that encapsulates a pair of iterators is very useful. The standard library uses `std::pair` in some circumstances, but that class is cumbersome to use because we need to specify two template arguments, and for all range algorithm purposes we must enforce the two template arguments to be the same. Moreover, `std::pair<iterator,iterator>` is hardly self-documenting whereas more domain specific class names are. Therefore these two classes are provided:
|
||||
|
||||
* Class `iterator_range`
|
||||
* Class `sub_range`
|
||||
* Function `join`
|
||||
|
||||
The `iterator_range` class is templated on an __forward_traversal_iterator__ and should be used whenever fairly general code is needed. The `sub_range` class is templated on an __forward_range__ and it is less general, but a bit easier to use since its template argument is easier to specify. The biggest difference is, however, that a `sub_range` can propagate constness because it knows what a corresponding `const_iterator` is.
|
||||
|
||||
Both classes can be used as ranges since they implement the __minimal_interface__ required for this to work automatically.
|
||||
|
||||
[section:iterator_range Class `iterator_range`]
|
||||
|
||||
The intention of the `iterator_range` class is to encapsulate two iterators so they fulfill the __forward_range__ concept. A few other functions are also provided for convenience.
|
||||
|
||||
If the template argument is not a model of __forward_traversal_iterator__, one can still use a subset of the interface. In particular, `size()` requires Random Access Traversal Iterators whereas `empty()` only requires Single Pass Iterators.
|
||||
|
||||
Recall that many default constructed iterators are [*/singular/] and hence can only be assigned, but not compared or incremented or anything. However, if one creates a default constructed `iterator_range`, then one can still call all its member functions. This design decision avoids the `iterator_range` imposing limitations upon ranges of iterators that are not singular. Any singularity limitation is simply propogated from the underlying iterator type.
|
||||
|
||||
|
||||
[h4 Synopsis]
|
||||
|
||||
``
|
||||
namespace boost
|
||||
{
|
||||
template< class ForwardTraversalIterator >
|
||||
class iterator_range
|
||||
{
|
||||
public: // Forward Range types
|
||||
typedef ForwardTraversalIterator iterator;
|
||||
typedef ForwardTraversalIterator const_iterator;
|
||||
typedef iterator_difference<iterator>::type difference_type;
|
||||
|
||||
public: // construction, assignment
|
||||
template< class ForwardTraversalIterator2 >
|
||||
iterator_range( ForwardTraversalIterator2 Begin, ForwardTraversalIterator2 End );
|
||||
|
||||
template< class ForwardRange >
|
||||
iterator_range( ForwardRange& r );
|
||||
|
||||
template< class ForwardRange >
|
||||
iterator_range( const ForwardRange& r );
|
||||
|
||||
template< class ForwardRange >
|
||||
iterator_range& operator=( ForwardRange& r );
|
||||
|
||||
template< class ForwardRange >
|
||||
iterator_range& operator=( const ForwardRange& r );
|
||||
|
||||
public: // Forward Range functions
|
||||
iterator begin() const;
|
||||
iterator end() const;
|
||||
|
||||
public: // convenience
|
||||
operator unspecified_bool_type() const;
|
||||
bool equal( const iterator_range& ) const;
|
||||
value_type& front() const;
|
||||
value_type& back() const;
|
||||
iterator_range& advance_begin(difference_type n);
|
||||
iterator_range& advance_end(difference_type n);
|
||||
bool empty() const;
|
||||
// for Random Access Range only:
|
||||
reference operator[]( difference_type at ) const;
|
||||
value_type operator()( difference_type at ) const;
|
||||
size_type size() const;
|
||||
};
|
||||
|
||||
// stream output
|
||||
template< class ForwardTraversalIterator, class T, class Traits >
|
||||
std::basic_ostream<T,Traits>&
|
||||
operator<<( std::basic_ostream<T,Traits>& Os,
|
||||
const iterator_range<ForwardTraversalIterator>& r );
|
||||
|
||||
// comparison
|
||||
template< class ForwardTraversalIterator, class ForwardTraversalIterator2 >
|
||||
bool operator==( const iterator_range<ForwardTraversalIterator>& l,
|
||||
const iterator_range<ForwardTraversalIterator2>& r );
|
||||
|
||||
template< class ForwardTraversalIterator, class ForwardRange >
|
||||
bool operator==( const iterator_range<ForwardTraversalIterator>& l,
|
||||
const ForwardRange& r );
|
||||
|
||||
template< class ForwardTraversalIterator, class ForwardRange >
|
||||
bool operator==( const ForwardRange& l,
|
||||
const iterator_range<ForwardTraversalIterator>& r );
|
||||
|
||||
template< class ForwardTraversalIterator, class ForwardTraversalIterator2 >
|
||||
bool operator!=( const iterator_range<ForwardTraversalIterator>& l,
|
||||
const iterator_range<ForwardTraversalIterator2>& r );
|
||||
|
||||
template< class ForwardTraversalIterator, class ForwardRange >
|
||||
bool operator!=( const iterator_range<ForwardTraversalIterator>& l,
|
||||
const ForwardRange& r );
|
||||
|
||||
template< class ForwardTraversalIterator, class ForwardRange >
|
||||
bool operator!=( const ForwardRange& l,
|
||||
const iterator_range<ForwardTraversalIterator>& r );
|
||||
|
||||
template< class ForwardTraversalIterator, class ForwardTraversalIterator2 >
|
||||
bool operator<( const iterator_range<ForwardTraversalIterator>& l,
|
||||
const iterator_range<ForwardTraversalIterator2>& r );
|
||||
|
||||
template< class ForwardTraversalIterator, class ForwardRange >
|
||||
bool operator<( const iterator_range<ForwardTraversalIterator>& l,
|
||||
const ForwardRange& r );
|
||||
|
||||
template< class ForwardTraversalIterator, class ForwardRange >
|
||||
bool operator<( const ForwardRange& l,
|
||||
const iterator_range<ForwardTraversalIterator>& r );
|
||||
|
||||
// external construction
|
||||
template< class ForwardTraversalIterator >
|
||||
iterator_range< ForwardTraversalIterator >
|
||||
make_iterator_range( ForwardTraversalIterator Begin,
|
||||
ForwardTraversalIterator End );
|
||||
|
||||
template< class ForwardRange >
|
||||
iterator_range< typename range_iterator<ForwardRange>::type >
|
||||
make_iterator_range( ForwardRange& r );
|
||||
|
||||
template< class ForwardRange >
|
||||
iterator_range< typename range_iterator<const ForwardRange>::type >
|
||||
make_iterator_range( const ForwardRange& r );
|
||||
|
||||
template< class Range >
|
||||
iterator_range< typename range_iterator<Range>::type >
|
||||
make_iterator_range( Range& r,
|
||||
typename range_difference<Range>::type advance_begin,
|
||||
typename range_difference<Range>::type advance_end );
|
||||
|
||||
template< class Range >
|
||||
iterator_range< typename range_iterator<const Range>::type >
|
||||
make_iterator_range( const Range& r,
|
||||
typename range_difference<const Range>::type advance_begin,
|
||||
typename range_difference<const Range>::type advance_end );
|
||||
|
||||
// convenience
|
||||
template< class Sequence, class ForwardRange >
|
||||
Sequence copy_range( const ForwardRange& r );
|
||||
|
||||
} // namespace 'boost'
|
||||
``
|
||||
|
||||
If an instance of `iterator_range` is constructed by a client with two iterators, the client must ensure that the two iterators delimit a valid closed-open range [begin,end).
|
||||
|
||||
It is worth noticing that the templated constructors and assignment operators allow conversion from `iterator_range<iterator>` to `iterator_range<const_iterator>`. Similarly, since the comparison operators have two template arguments, we can compare ranges whenever the iterators are comparable; for example when we are dealing with const and non-const iterators from the same container.
|
||||
|
||||
[h4 Details member functions]
|
||||
|
||||
`operator unspecified_bool_type() const;`
|
||||
|
||||
[:['[*Returns]] `!empty();`]
|
||||
|
||||
`bool equal( iterator_range& r ) const;`
|
||||
|
||||
[:['[*Returns]] `begin() == r.begin() && end() == r.end();`]
|
||||
|
||||
[h4 Details functions]
|
||||
|
||||
`bool operator==( const ForwardRange1& l, const ForwardRange2& r );`
|
||||
|
||||
[:['[*Returns]] `size(l) != size(r) ? false : std::equal( begin(l), end(l), begin(r) );`]
|
||||
|
||||
`bool operator!=( const ForwardRange1& l, const ForwardRange2& r );`
|
||||
|
||||
[:['[*Returns]] `!( l == r );`]
|
||||
|
||||
`bool operator<( const ForwardRange1& l, const ForwardRange2& r );`
|
||||
|
||||
[:['[*Returns]] `std::lexicographical_compare( begin(l), end(l), begin(r), end(r) );`]
|
||||
|
||||
``
|
||||
iterator_range make_iterator_range( Range& r,
|
||||
typename range_difference<Range>::type advance_begin,
|
||||
typename range_difference<Range>::type advance_end );
|
||||
``
|
||||
|
||||
[:['[*Effects:]]]
|
||||
|
||||
``
|
||||
iterator new_begin = begin( r ),
|
||||
iterator new_end = end( r );
|
||||
std::advance( new_begin, advance_begin );
|
||||
std::advance( new_end, advance_end );
|
||||
return make_iterator_range( new_begin, new_end );
|
||||
``
|
||||
|
||||
`Sequence copy_range( const ForwardRange& r );`
|
||||
|
||||
[:['[*Returns]] `Sequence( begin(r), end(r) );`]
|
||||
|
||||
[endsect]
|
||||
|
||||
[section:sub_range Class `sub_range`]
|
||||
|
||||
The `sub_range` class inherits all its functionality from the __iterator_range__ class. The `sub_range` class is often easier to use because one must specify the __forward_range__ template argument instead of an iterator. Moreover, the `sub_range` class can propagate constness since it knows what a corresponding `const_iterator` is.
|
||||
|
||||
[h4 Synopsis]
|
||||
|
||||
``
|
||||
namespace boost
|
||||
{
|
||||
template< class ForwardRange >
|
||||
class sub_range : public iterator_range< typename range_iterator<ForwardRange>::type >
|
||||
{
|
||||
public:
|
||||
typedef typename range_iterator<ForwardRange>::type iterator;
|
||||
typedef typename range_iterator<const ForwardRange>::type const_iterator;
|
||||
typedef typename iterator_difference<iterator>::type difference_type;
|
||||
|
||||
public: // construction, assignment
|
||||
template< class ForwardTraversalIterator >
|
||||
sub_range( ForwardTraversalIterator Begin, ForwardTraversalIterator End );
|
||||
|
||||
template< class ForwardRange2 >
|
||||
sub_range( ForwardRange2& r );
|
||||
|
||||
template< class ForwardRange2 >
|
||||
sub_range( const Range2& r );
|
||||
|
||||
template< class ForwardRange2 >
|
||||
sub_range& operator=( ForwardRange2& r );
|
||||
|
||||
template< class ForwardRange2 >
|
||||
sub_range& operator=( const ForwardRange2& r );
|
||||
|
||||
public: // Forward Range functions
|
||||
iterator begin();
|
||||
const_iterator begin() const;
|
||||
iterator end();
|
||||
const_iterator end() const;
|
||||
|
||||
public: // convenience
|
||||
value_type& front();
|
||||
const value_type& front() const;
|
||||
value_type& back();
|
||||
const value_type& back() const;
|
||||
// for Random Access Range only:
|
||||
value_type& operator[]( size_type at );
|
||||
const value_type& operator[]( size_type at ) const;
|
||||
|
||||
public:
|
||||
// rest of interface inherited from iterator_range
|
||||
};
|
||||
|
||||
} // namespace 'boost'
|
||||
``
|
||||
|
||||
The class should be trivial to use as seen below. Imagine that we have an algorithm that searches for a sub-string in a string. The result is an iterator_range, that delimits the match. We need to store the result from this algorithm. Here is an example of how we can do it with and without `sub_range`
|
||||
|
||||
``
|
||||
std::string str("hello");
|
||||
iterator_range<std::string::iterator> ir = find_first( str, "ll" );
|
||||
sub_range<std::string> sub = find_first( str, "ll" );
|
||||
``
|
||||
|
||||
[endsect]
|
||||
|
||||
[section:join Function join]
|
||||
|
||||
The intention of the `join` function is to join two ranges into one longer range.
|
||||
|
||||
The resultant range will have the lowest common traversal of the two ranges supplied as parameters.
|
||||
|
||||
Note that the joined range incurs a performance cost due to the need to check if the end of a range has been reached internally during traversal.
|
||||
|
||||
[h4 Synposis]
|
||||
``
|
||||
template<typename SinglePassRange1, typename SinglePassRange2>
|
||||
iterator_range<range_detail::join_iterator<
|
||||
typename range_iterator<const SinglePassRange1>::type,
|
||||
typename range_iterator<const SinglePassRange2>::type,
|
||||
typename add_const<
|
||||
typename range_value<const SinglePassRange1>::type>::type>
|
||||
>
|
||||
join(const SinglePassRange1& rng1, const SinglePassRange2& rng2)
|
||||
|
||||
template<typename SinglePassRange1, typename SinglePassRange2>
|
||||
iterator_range<range_detail::join_iterator<
|
||||
typename range_iterator<SinglePassRange1>::type,
|
||||
typename range_iterator<SinglePassRange2>::type,
|
||||
typename range_value<SinglePassRange1>::type>
|
||||
>
|
||||
join(SinglePassRange1& rng1, SinglePassRange2& rng2);
|
||||
``
|
||||
|
||||
[h4 Example]
|
||||
|
||||
The expression `join(irange(0,5), irange(5,10))` would evaluate to a range representing an integer range `[0,10)`
|
||||
|
||||
|
||||
[endsect]
|
||||
|
||||
[endsect]
|
||||
|
||||
Reference in New Issue
Block a user