- tmp/tmpp1gp4c30/{from.md → to.md} +594 -498
tmp/tmpp1gp4c30/{from.md → to.md}
RENAMED
|
@@ -27,16 +27,16 @@ summarized in Table [[tab:iterators.lib.summary]].
|
|
| 27 |
Iterators are a generalization of pointers that allow a C++program to
|
| 28 |
work with different data structures (containers) in a uniform manner. To
|
| 29 |
be able to construct template algorithms that work correctly and
|
| 30 |
efficiently on different types of data structures, the library
|
| 31 |
formalizes not just the interfaces but also the semantics and complexity
|
| 32 |
-
assumptions of iterators.
|
| 33 |
`*i`, resulting in a value of some object type `T`, called the *value
|
| 34 |
-
type* of the iterator.
|
| 35 |
-
|
| 36 |
-
|
| 37 |
-
|
| 38 |
the expression `i->m` with the same semantics as `(*i).m`. For every
|
| 39 |
iterator type `X` for which equality is defined, there is a
|
| 40 |
corresponding signed integer type called the *difference type* of the
|
| 41 |
iterator.
|
| 42 |
|
|
@@ -63,33 +63,58 @@ iterators also satisfy all the requirements of forward iterators and can
|
|
| 63 |
be used whenever a forward iterator is specified; Random access
|
| 64 |
iterators also satisfy all the requirements of bidirectional iterators
|
| 65 |
and can be used whenever a bidirectional iterator is specified.
|
| 66 |
|
| 67 |
Iterators that further satisfy the requirements of output iterators are
|
| 68 |
-
called *mutable
|
| 69 |
-
*constant
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 70 |
|
| 71 |
Just as a regular pointer to an array guarantees that there is a pointer
|
| 72 |
value pointing past the last element of the array, so for any iterator
|
| 73 |
type there is an iterator value that points past the last element of a
|
| 74 |
corresponding sequence. These values are called *past-the-end* values.
|
| 75 |
Values of an iterator `i` for which the expression `*i` is defined are
|
| 76 |
called *dereferenceable*. The library never assumes that past-the-end
|
| 77 |
values are dereferenceable. Iterators can also have singular values that
|
| 78 |
-
are not associated with any sequence.
|
| 79 |
-
|
| 80 |
-
|
| 81 |
-
|
| 82 |
-
|
| 83 |
-
|
| 84 |
-
|
| 85 |
-
|
| 86 |
-
|
| 87 |
-
|
| 88 |
-
|
| 89 |
-
|
| 90 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 91 |
|
| 92 |
An iterator `j` is called *reachable* from an iterator `i` if and only
|
| 93 |
if there is a finite sequence of applications of the expression `++i`
|
| 94 |
that makes `i == j`. If `j` is reachable from `i`, they refer to
|
| 95 |
elements of the same sequence.
|
|
@@ -117,23 +142,24 @@ In the following sections, `a` and `b` denote values of type `X` or
|
|
| 117 |
`const X`, `difference_type` and `reference` refer to the types
|
| 118 |
`iterator_traits<X>::difference_type` and
|
| 119 |
`iterator_traits<X>::reference`, respectively, `n` denotes a value of
|
| 120 |
`difference_type`, `u`, `tmp`, and `m` denote identifiers, `r` denotes a
|
| 121 |
value of `X&`, `t` denotes a value of value type `T`, `o` denotes a
|
| 122 |
-
value of some type that is writable to the output iterator.
|
| 123 |
-
|
| 124 |
-
`
|
|
|
|
| 125 |
|
| 126 |
### Iterator <a id="iterator.iterators">[[iterator.iterators]]</a>
|
| 127 |
|
| 128 |
The `Iterator` requirements form the basis of the iterator concept
|
| 129 |
taxonomy; every iterator satisfies the `Iterator` requirements. This set
|
| 130 |
of requirements specifies operations for dereferencing and incrementing
|
| 131 |
an iterator. Most algorithms will require additional operations to
|
| 132 |
read ([[input.iterators]]) or write ([[output.iterators]]) values, or
|
| 133 |
to provide a richer set of iterator movements ([[forward.iterators]],
|
| 134 |
-
[[bidirectional.iterators]], [[random.access.iterators]]).
|
| 135 |
|
| 136 |
A type `X` satisfies the `Iterator` requirements if:
|
| 137 |
|
| 138 |
- `X` satisfies the `CopyConstructible`, `CopyAssignable`, and
|
| 139 |
`Destructible` requirements ([[utility.arg.requirements]]) and
|
|
@@ -142,85 +168,89 @@ A type `X` satisfies the `Iterator` requirements if:
|
|
| 142 |
have the indicated semantics.
|
| 143 |
|
| 144 |
### Input iterators <a id="input.iterators">[[input.iterators]]</a>
|
| 145 |
|
| 146 |
A class or pointer type `X` satisfies the requirements of an input
|
| 147 |
-
iterator for the value type `T` if X satisfies the `Iterator` (
|
| 148 |
[[iterator.iterators]]) and `EqualityComparable` (Table
|
| 149 |
-
[[equalitycomparable]]) requirements and the expressions in Table
|
| 150 |
[[tab:iterator.input.requirements]] are valid and have the indicated
|
| 151 |
semantics.
|
| 152 |
|
| 153 |
In Table [[tab:iterator.input.requirements]], the term *the domain of
|
| 154 |
`==`* is used in the ordinary mathematical sense to denote the set of
|
| 155 |
values over which `==` is (required to be) defined. This set can change
|
| 156 |
over time. Each algorithm places additional requirements on the domain
|
| 157 |
of `==` for the iterator values it uses. These requirements can be
|
| 158 |
-
inferred from the uses that algorithm makes of `==` and `!=`.
|
| 159 |
-
`find(a,b,x)` is defined only if the value of `a` has the property *p*
|
| 160 |
-
defined as follows: `b` has property *p* and a value `i` has property
|
| 161 |
-
*p* if `(*i==x)` or if `(*i!=x` and `++i` has property `p`).
|
| 162 |
|
| 163 |
-
|
| 164 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 165 |
transparency.) Algorithms on input iterators should never attempt to
|
| 166 |
pass through the same iterator twice. They should be *single pass*
|
| 167 |
-
algorithms. Value type T is not required to be a `CopyAssignable` type
|
| 168 |
-
(Table [[copyassignable]]). These algorithms can be used with
|
| 169 |
-
as the source of the input data through the `istream_iterator`
|
| 170 |
-
template.
|
| 171 |
|
| 172 |
### Output iterators <a id="output.iterators">[[output.iterators]]</a>
|
| 173 |
|
| 174 |
A class or pointer type `X` satisfies the requirements of an output
|
| 175 |
iterator if `X` satisfies the `Iterator` requirements (
|
| 176 |
[[iterator.iterators]]) and the expressions in Table
|
| 177 |
[[tab:iterator.output.requirements]] are valid and have the indicated
|
| 178 |
semantics.
|
| 179 |
|
| 180 |
-
The only valid use of an `operator*` is on the left side of
|
| 181 |
-
assignment statement. *Assignment through the same value of the
|
| 182 |
-
happens only once.* Algorithms on output iterators should never
|
| 183 |
-
to pass through the same iterator twice. They should be *single
|
| 184 |
-
algorithms. Equality and inequality might not be defined.
|
| 185 |
-
that take output iterators can be used with ostreams as the
|
| 186 |
-
for placing data through the `ostream_iterator` class as
|
| 187 |
-
insert iterators and insert pointers.
|
| 188 |
|
| 189 |
### Forward iterators <a id="forward.iterators">[[forward.iterators]]</a>
|
| 190 |
|
| 191 |
A class or pointer type `X` satisfies the requirements of a forward
|
| 192 |
iterator if
|
| 193 |
|
| 194 |
- `X` satisfies the requirements of an input iterator (
|
| 195 |
[[input.iterators]]),
|
| 196 |
-
- X satisfies the `DefaultConstructible` requirements (
|
| 197 |
[[utility.arg.requirements]]),
|
| 198 |
- if `X` is a mutable iterator, `reference` is a reference to `T`; if
|
| 199 |
-
`X` is a
|
| 200 |
- the expressions in Table [[tab:iterator.forward.requirements]] are
|
| 201 |
valid and have the indicated semantics, and
|
| 202 |
- objects of type `X` offer the multi-pass guarantee, described below.
|
| 203 |
|
| 204 |
-
The domain of == for forward iterators is that of iterators over the
|
| 205 |
same underlying sequence. However, value-initialized iterators may be
|
| 206 |
compared and shall compare equal to other value-initialized iterators of
|
| 207 |
-
the same type.
|
| 208 |
-
|
|
|
|
|
|
|
| 209 |
|
| 210 |
Two dereferenceable iterators `a` and `b` of type `X` offer the
|
| 211 |
*multi-pass guarantee* if:
|
| 212 |
|
| 213 |
- `a == b` implies `++a == ++b` and
|
| 214 |
- `X` is a pointer type or the expression `(void)++X(a), *a` is
|
| 215 |
equivalent to the expression `*a`.
|
| 216 |
|
| 217 |
-
The requirement that `a == b` implies `++a == ++b` (which is
|
| 218 |
-
for input and output iterators) and the removal of the
|
| 219 |
-
the number of the assignments through a mutable iterator
|
| 220 |
-
to output iterators) allows the use of multi-pass
|
| 221 |
-
algorithms with forward iterators.
|
| 222 |
|
| 223 |
If `a` and `b` are equal, then either `a` and `b` are both
|
| 224 |
dereferenceable or else neither is dereferenceable.
|
| 225 |
|
| 226 |
If `a` and `b` are both dereferenceable, then `a == b` if and only if
|
|
@@ -231,12 +261,12 @@ If `a` and `b` are both dereferenceable, then `a == b` if and only if
|
|
| 231 |
A class or pointer type `X` satisfies the requirements of a
|
| 232 |
bidirectional iterator if, in addition to satisfying the requirements
|
| 233 |
for forward iterators, the following expressions are valid as shown in
|
| 234 |
Table [[tab:iterator.bidirectional.requirements]].
|
| 235 |
|
| 236 |
-
Bidirectional iterators allow algorithms to move iterators
|
| 237 |
-
well as forward.
|
| 238 |
|
| 239 |
### Random access iterators <a id="random.access.iterators">[[random.access.iterators]]</a>
|
| 240 |
|
| 241 |
A class or pointer type `X` satisfies the requirements of a random
|
| 242 |
access iterator if, in addition to satisfying the requirements for
|
|
@@ -245,76 +275,74 @@ Table [[tab:iterator.random.access.requirements]].
|
|
| 245 |
|
| 246 |
## Header `<iterator>` synopsis <a id="iterator.synopsis">[[iterator.synopsis]]</a>
|
| 247 |
|
| 248 |
``` cpp
|
| 249 |
namespace std {
|
| 250 |
-
// [iterator.primitives], primitives
|
| 251 |
template<class Iterator> struct iterator_traits;
|
| 252 |
template<class T> struct iterator_traits<T*>;
|
| 253 |
-
|
| 254 |
-
template<class Category, class T, class Distance = ptrdiff_t,
|
| 255 |
-
class Pointer = T*, class Reference = T&> struct iterator;
|
| 256 |
|
| 257 |
struct input_iterator_tag { };
|
| 258 |
struct output_iterator_tag { };
|
| 259 |
struct forward_iterator_tag: public input_iterator_tag { };
|
| 260 |
struct bidirectional_iterator_tag: public forward_iterator_tag { };
|
| 261 |
struct random_access_iterator_tag: public bidirectional_iterator_tag { };
|
| 262 |
|
| 263 |
-
// [iterator.operations], iterator operations
|
| 264 |
template <class InputIterator, class Distance>
|
| 265 |
-
void advance(InputIterator& i, Distance n);
|
| 266 |
template <class InputIterator>
|
| 267 |
-
typename iterator_traits<InputIterator>::difference_type
|
| 268 |
distance(InputIterator first, InputIterator last);
|
| 269 |
-
template <class
|
| 270 |
-
|
| 271 |
-
typename
|
| 272 |
template <class BidirectionalIterator>
|
| 273 |
-
BidirectionalIterator prev(BidirectionalIterator x,
|
| 274 |
-
typename
|
| 275 |
|
| 276 |
-
// [predef.iterators], predefined iterators
|
| 277 |
template <class Iterator> class reverse_iterator;
|
| 278 |
|
| 279 |
template <class Iterator1, class Iterator2>
|
| 280 |
-
bool operator==(
|
| 281 |
const reverse_iterator<Iterator1>& x,
|
| 282 |
const reverse_iterator<Iterator2>& y);
|
| 283 |
template <class Iterator1, class Iterator2>
|
| 284 |
-
bool operator<(
|
| 285 |
const reverse_iterator<Iterator1>& x,
|
| 286 |
const reverse_iterator<Iterator2>& y);
|
| 287 |
template <class Iterator1, class Iterator2>
|
| 288 |
-
bool operator!=(
|
| 289 |
const reverse_iterator<Iterator1>& x,
|
| 290 |
const reverse_iterator<Iterator2>& y);
|
| 291 |
template <class Iterator1, class Iterator2>
|
| 292 |
-
bool operator>(
|
| 293 |
const reverse_iterator<Iterator1>& x,
|
| 294 |
const reverse_iterator<Iterator2>& y);
|
| 295 |
template <class Iterator1, class Iterator2>
|
| 296 |
-
bool operator>=(
|
| 297 |
const reverse_iterator<Iterator1>& x,
|
| 298 |
const reverse_iterator<Iterator2>& y);
|
| 299 |
template <class Iterator1, class Iterator2>
|
| 300 |
-
bool operator<=(
|
| 301 |
const reverse_iterator<Iterator1>& x,
|
| 302 |
const reverse_iterator<Iterator2>& y);
|
| 303 |
|
| 304 |
template <class Iterator1, class Iterator2>
|
| 305 |
-
auto operator-(
|
| 306 |
const reverse_iterator<Iterator1>& x,
|
| 307 |
const reverse_iterator<Iterator2>& y) ->decltype(y.base() - x.base());
|
| 308 |
template <class Iterator>
|
| 309 |
-
reverse_iterator<Iterator>
|
| 310 |
operator+(
|
| 311 |
typename reverse_iterator<Iterator>::difference_type n,
|
| 312 |
const reverse_iterator<Iterator>& x);
|
| 313 |
|
| 314 |
template <class Iterator>
|
| 315 |
-
reverse_iterator<Iterator> make_reverse_iterator(Iterator i);
|
| 316 |
|
| 317 |
template <class Container> class back_insert_iterator;
|
| 318 |
template <class Container>
|
| 319 |
back_insert_iterator<Container> back_inserter(Container& x);
|
| 320 |
|
|
@@ -326,39 +354,39 @@ namespace std {
|
|
| 326 |
template <class Container>
|
| 327 |
insert_iterator<Container> inserter(Container& x, typename Container::iterator i);
|
| 328 |
|
| 329 |
template <class Iterator> class move_iterator;
|
| 330 |
template <class Iterator1, class Iterator2>
|
| 331 |
-
bool operator==(
|
| 332 |
const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 333 |
template <class Iterator1, class Iterator2>
|
| 334 |
-
bool operator!=(
|
| 335 |
const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 336 |
template <class Iterator1, class Iterator2>
|
| 337 |
-
bool operator<(
|
| 338 |
const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 339 |
template <class Iterator1, class Iterator2>
|
| 340 |
-
bool operator<=(
|
| 341 |
const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 342 |
template <class Iterator1, class Iterator2>
|
| 343 |
-
bool operator>(
|
| 344 |
const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 345 |
template <class Iterator1, class Iterator2>
|
| 346 |
-
bool operator>=(
|
| 347 |
const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 348 |
|
| 349 |
template <class Iterator1, class Iterator2>
|
| 350 |
-
auto operator-(
|
| 351 |
const move_iterator<Iterator1>& x,
|
| 352 |
const move_iterator<Iterator2>& y) -> decltype(x.base() - y.base());
|
| 353 |
template <class Iterator>
|
| 354 |
-
move_iterator<Iterator> operator+(
|
| 355 |
typename move_iterator<Iterator>::difference_type n, const move_iterator<Iterator>& x);
|
| 356 |
template <class Iterator>
|
| 357 |
-
move_iterator<Iterator> make_move_iterator(Iterator i);
|
| 358 |
|
| 359 |
-
// [stream.iterators], stream iterators
|
| 360 |
template <class T, class charT = char, class traits = char_traits<charT>,
|
| 361 |
class Distance = ptrdiff_t>
|
| 362 |
class istream_iterator;
|
| 363 |
template <class T, class charT, class traits, class Distance>
|
| 364 |
bool operator==(const istream_iterator<T,charT,traits,Distance>& x,
|
|
@@ -380,31 +408,42 @@ namespace std {
|
|
| 380 |
const istreambuf_iterator<charT,traits>& b);
|
| 381 |
|
| 382 |
template <class charT, class traits = char_traits<charT>>
|
| 383 |
class ostreambuf_iterator;
|
| 384 |
|
| 385 |
-
// [iterator.range], range access
|
| 386 |
-
template <class C> auto begin(C& c) -> decltype(c.begin());
|
| 387 |
-
template <class C> auto begin(const C& c) -> decltype(c.begin());
|
| 388 |
-
template <class C> auto end(C& c) -> decltype(c.end());
|
| 389 |
-
template <class C> auto end(const C& c) -> decltype(c.end());
|
| 390 |
template <class T, size_t N> constexpr T* begin(T (&array)[N]) noexcept;
|
| 391 |
template <class T, size_t N> constexpr T* end(T (&array)[N]) noexcept;
|
| 392 |
template <class C> constexpr auto cbegin(const C& c) noexcept(noexcept(std::begin(c)))
|
| 393 |
-> decltype(std::begin(c));
|
| 394 |
template <class C> constexpr auto cend(const C& c) noexcept(noexcept(std::end(c)))
|
| 395 |
-> decltype(std::end(c));
|
| 396 |
-
template <class C> auto rbegin(C& c) -> decltype(c.rbegin());
|
| 397 |
-
template <class C> auto rbegin(const C& c) -> decltype(c.rbegin());
|
| 398 |
-
template <class C> auto rend(C& c) -> decltype(c.rend());
|
| 399 |
-
template <class C> auto rend(const C& c) -> decltype(c.rend());
|
| 400 |
-
template <class T, size_t N> reverse_iterator<T*> rbegin(T (&array)[N]);
|
| 401 |
-
template <class T, size_t N> reverse_iterator<T*> rend(T (&array)[N]);
|
| 402 |
-
template <class E> reverse_iterator<const E*> rbegin(initializer_list<E> il);
|
| 403 |
-
template <class E> reverse_iterator<const E*> rend(initializer_list<E> il);
|
| 404 |
-
template <class C> auto crbegin(const C& c) -> decltype(std::rbegin(c));
|
| 405 |
-
template <class C> auto crend(const C& c) -> decltype(std::rend(c));
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 406 |
}
|
| 407 |
```
|
| 408 |
|
| 409 |
## Iterator primitives <a id="iterator.primitives">[[iterator.primitives]]</a>
|
| 410 |
|
|
@@ -443,52 +482,56 @@ iterator_traits<Iterator>::reference
|
|
| 443 |
iterator_traits<Iterator>::pointer
|
| 444 |
```
|
| 445 |
|
| 446 |
may be defined as `void`.
|
| 447 |
|
| 448 |
-
|
|
|
|
|
|
|
|
|
|
| 449 |
|
| 450 |
``` cpp
|
| 451 |
-
|
| 452 |
-
|
| 453 |
-
|
| 454 |
-
|
| 455 |
-
|
| 456 |
-
typedef typename Iterator::reference reference;
|
| 457 |
-
typedef typename Iterator::iterator_category iterator_category;
|
| 458 |
-
};
|
| 459 |
-
}
|
| 460 |
```
|
| 461 |
|
|
|
|
|
|
|
|
|
|
| 462 |
It is specialized for pointers as
|
| 463 |
|
| 464 |
``` cpp
|
| 465 |
namespace std {
|
| 466 |
template<class T> struct iterator_traits<T*> {
|
| 467 |
-
|
| 468 |
-
|
| 469 |
-
|
| 470 |
-
|
| 471 |
-
|
| 472 |
};
|
| 473 |
}
|
| 474 |
```
|
| 475 |
|
| 476 |
and for pointers to const as
|
| 477 |
|
| 478 |
``` cpp
|
| 479 |
namespace std {
|
| 480 |
template<class T> struct iterator_traits<const T*> {
|
| 481 |
-
|
| 482 |
-
|
| 483 |
-
|
| 484 |
-
|
| 485 |
-
|
| 486 |
};
|
| 487 |
}
|
| 488 |
```
|
| 489 |
|
|
|
|
|
|
|
| 490 |
To implement a generic `reverse` function, a C++program can do the
|
| 491 |
following:
|
| 492 |
|
| 493 |
``` cpp
|
| 494 |
template <class BidirectionalIterator>
|
|
@@ -504,28 +547,11 @@ void reverse(BidirectionalIterator first, BidirectionalIterator last) {
|
|
| 504 |
n -= 2;
|
| 505 |
}
|
| 506 |
}
|
| 507 |
```
|
| 508 |
|
| 509 |
-
|
| 510 |
-
|
| 511 |
-
The `iterator` template may be used as a base class to ease the
|
| 512 |
-
definition of required types for new iterators.
|
| 513 |
-
|
| 514 |
-
``` cpp
|
| 515 |
-
namespace std {
|
| 516 |
-
template<class Category, class T, class Distance = ptrdiff_t,
|
| 517 |
-
class Pointer = T*, class Reference = T&>
|
| 518 |
-
struct iterator {
|
| 519 |
-
typedef T value_type;
|
| 520 |
-
typedef Distance difference_type;
|
| 521 |
-
typedef Pointer pointer;
|
| 522 |
-
typedef Reference reference;
|
| 523 |
-
typedef Category iterator_category;
|
| 524 |
-
};
|
| 525 |
-
}
|
| 526 |
-
```
|
| 527 |
|
| 528 |
### Standard iterator tags <a id="std.iterator.tags">[[std.iterator.tags]]</a>
|
| 529 |
|
| 530 |
It is often desirable for a function template specialization to find out
|
| 531 |
what is the most specific category of its iterator argument, so that the
|
|
@@ -546,26 +572,29 @@ namespace std {
|
|
| 546 |
struct bidirectional_iterator_tag: public forward_iterator_tag { };
|
| 547 |
struct random_access_iterator_tag: public bidirectional_iterator_tag { };
|
| 548 |
}
|
| 549 |
```
|
| 550 |
|
|
|
|
|
|
|
| 551 |
For a program-defined iterator `BinaryTreeIterator`, it could be
|
| 552 |
included into the bidirectional iterator category by specializing the
|
| 553 |
`iterator_traits` template:
|
| 554 |
|
| 555 |
``` cpp
|
| 556 |
template<class T> struct iterator_traits<BinaryTreeIterator<T>> {
|
| 557 |
-
|
| 558 |
-
|
| 559 |
-
|
| 560 |
-
|
| 561 |
-
|
| 562 |
};
|
| 563 |
```
|
| 564 |
|
| 565 |
-
|
| 566 |
-
|
|
|
|
| 567 |
|
| 568 |
If `evolve()` is well defined for bidirectional iterators, but can be
|
| 569 |
implemented more efficiently for random access iterators, then the
|
| 570 |
implementation is as follows:
|
| 571 |
|
|
@@ -588,22 +617,11 @@ void evolve(RandomAccessIterator first, RandomAccessIterator last,
|
|
| 588 |
random_access_iterator_tag) {
|
| 589 |
// more efficient, but less generic algorithm
|
| 590 |
}
|
| 591 |
```
|
| 592 |
|
| 593 |
-
|
| 594 |
-
structure containing `double` and such that it works on a large memory
|
| 595 |
-
model of the implementation, it can do so with:
|
| 596 |
-
|
| 597 |
-
``` cpp
|
| 598 |
-
class MyIterator :
|
| 599 |
-
public iterator<bidirectional_iterator_tag, double, long, T*, T&> {
|
| 600 |
-
// code implementing ++, etc.
|
| 601 |
-
};
|
| 602 |
-
```
|
| 603 |
-
|
| 604 |
-
Then there is no need to specialize the `iterator_traits` template.
|
| 605 |
|
| 606 |
### Iterator operations <a id="iterator.operations">[[iterator.operations]]</a>
|
| 607 |
|
| 608 |
Since only random access iterators provide `+` and `-` operators, the
|
| 609 |
library provides two function templates `advance` and `distance`. These
|
|
@@ -611,22 +629,22 @@ function templates use `+` and `-` for random access iterators (and are,
|
|
| 611 |
therefore, constant time for them); for input, forward and bidirectional
|
| 612 |
iterators they use `++` to provide linear time implementations.
|
| 613 |
|
| 614 |
``` cpp
|
| 615 |
template <class InputIterator, class Distance>
|
| 616 |
-
void advance(InputIterator& i, Distance n);
|
| 617 |
```
|
| 618 |
|
| 619 |
*Requires:* `n` shall be negative only for bidirectional and random
|
| 620 |
access iterators.
|
| 621 |
|
| 622 |
*Effects:* Increments (or decrements for negative `n`) iterator
|
| 623 |
reference `i` by `n`.
|
| 624 |
|
| 625 |
``` cpp
|
| 626 |
template <class InputIterator>
|
| 627 |
-
|
| 628 |
distance(InputIterator first, InputIterator last);
|
| 629 |
```
|
| 630 |
|
| 631 |
*Effects:* If `InputIterator` meets the requirements of random access
|
| 632 |
iterator, returns `(last - first)`; otherwise, returns the number of
|
|
@@ -636,24 +654,24 @@ increments needed to get from `first` to `last`.
|
|
| 636 |
iterator, `last` shall be reachable from `first` or `first` shall be
|
| 637 |
reachable from `last`; otherwise, `last` shall be reachable from
|
| 638 |
`first`.
|
| 639 |
|
| 640 |
``` cpp
|
| 641 |
-
template <class
|
| 642 |
-
|
| 643 |
-
typename
|
| 644 |
```
|
| 645 |
|
| 646 |
-
*Effects:* Equivalent to `advance(x, n); return x;`
|
| 647 |
|
| 648 |
``` cpp
|
| 649 |
template <class BidirectionalIterator>
|
| 650 |
-
BidirectionalIterator prev(BidirectionalIterator x,
|
| 651 |
-
typename
|
| 652 |
```
|
| 653 |
|
| 654 |
-
*Effects:* Equivalent to `advance(x, -n); return x;`
|
| 655 |
|
| 656 |
## Iterator adaptors <a id="predef.iterators">[[predef.iterators]]</a>
|
| 657 |
|
| 658 |
### Reverse iterators <a id="reverse.iterators">[[reverse.iterators]]</a>
|
| 659 |
|
|
@@ -666,94 +684,91 @@ identity: `&*(reverse_iterator(i)) == &*(i - 1)`.
|
|
| 666 |
#### Class template `reverse_iterator` <a id="reverse.iterator">[[reverse.iterator]]</a>
|
| 667 |
|
| 668 |
``` cpp
|
| 669 |
namespace std {
|
| 670 |
template <class Iterator>
|
| 671 |
-
class reverse_iterator
|
| 672 |
-
iterator<typename iterator_traits<Iterator>::iterator_category,
|
| 673 |
-
typename iterator_traits<Iterator>::value_type,
|
| 674 |
-
typename iterator_traits<Iterator>::difference_type,
|
| 675 |
-
typename iterator_traits<Iterator>::pointer,
|
| 676 |
-
typename iterator_traits<Iterator>::reference> {
|
| 677 |
public:
|
| 678 |
-
|
| 679 |
-
|
| 680 |
-
|
| 681 |
-
|
|
|
|
|
|
|
| 682 |
|
| 683 |
-
reverse_iterator();
|
| 684 |
-
explicit reverse_iterator(Iterator x);
|
| 685 |
-
template <class U> reverse_iterator(const reverse_iterator<U>& u);
|
| 686 |
-
template <class U> reverse_iterator& operator=(const reverse_iterator<U>& u);
|
| 687 |
|
| 688 |
-
Iterator base() const; // explicit
|
| 689 |
-
reference operator*() const;
|
| 690 |
-
pointer operator->() const;
|
| 691 |
|
| 692 |
-
reverse_iterator& operator++();
|
| 693 |
-
reverse_iterator operator++(int);
|
| 694 |
-
reverse_iterator& operator--();
|
| 695 |
-
reverse_iterator operator--(int);
|
| 696 |
|
| 697 |
-
reverse_iterator operator+ (difference_type n) const;
|
| 698 |
-
reverse_iterator& operator+=(difference_type n);
|
| 699 |
-
reverse_iterator operator- (difference_type n) const;
|
| 700 |
-
reverse_iterator& operator-=(difference_type n);
|
| 701 |
-
unspecified operator[](difference_type n) const;
|
| 702 |
protected:
|
| 703 |
Iterator current;
|
| 704 |
};
|
| 705 |
|
| 706 |
template <class Iterator1, class Iterator2>
|
| 707 |
-
bool operator==(
|
| 708 |
const reverse_iterator<Iterator1>& x,
|
| 709 |
const reverse_iterator<Iterator2>& y);
|
| 710 |
template <class Iterator1, class Iterator2>
|
| 711 |
-
bool operator<(
|
| 712 |
const reverse_iterator<Iterator1>& x,
|
| 713 |
const reverse_iterator<Iterator2>& y);
|
| 714 |
template <class Iterator1, class Iterator2>
|
| 715 |
-
bool operator!=(
|
| 716 |
const reverse_iterator<Iterator1>& x,
|
| 717 |
const reverse_iterator<Iterator2>& y);
|
| 718 |
template <class Iterator1, class Iterator2>
|
| 719 |
-
bool operator>(
|
| 720 |
const reverse_iterator<Iterator1>& x,
|
| 721 |
const reverse_iterator<Iterator2>& y);
|
| 722 |
template <class Iterator1, class Iterator2>
|
| 723 |
-
bool operator>=(
|
| 724 |
const reverse_iterator<Iterator1>& x,
|
| 725 |
const reverse_iterator<Iterator2>& y);
|
| 726 |
template <class Iterator1, class Iterator2>
|
| 727 |
-
bool operator<=(
|
| 728 |
const reverse_iterator<Iterator1>& x,
|
| 729 |
const reverse_iterator<Iterator2>& y);
|
| 730 |
template <class Iterator1, class Iterator2>
|
| 731 |
-
auto operator-(
|
| 732 |
const reverse_iterator<Iterator1>& x,
|
| 733 |
const reverse_iterator<Iterator2>& y) -> decltype(y.base() - x.base());
|
| 734 |
template <class Iterator>
|
| 735 |
-
reverse_iterator<Iterator> operator+(
|
| 736 |
typename reverse_iterator<Iterator>::difference_type n,
|
| 737 |
const reverse_iterator<Iterator>& x);
|
| 738 |
|
| 739 |
template <class Iterator>
|
| 740 |
-
reverse_iterator<Iterator> make_reverse_iterator(Iterator i);
|
| 741 |
}
|
| 742 |
```
|
| 743 |
|
| 744 |
#### `reverse_iterator` requirements <a id="reverse.iter.requirements">[[reverse.iter.requirements]]</a>
|
| 745 |
|
| 746 |
The template parameter `Iterator` shall meet all the requirements of a
|
| 747 |
Bidirectional Iterator ([[bidirectional.iterators]]).
|
| 748 |
|
| 749 |
-
Additionally, `Iterator` shall meet the requirements of a
|
| 750 |
-
|
| 751 |
`operator+` ([[reverse.iter.op+]]), `operator-` (
|
| 752 |
[[reverse.iter.op-]]), `operator+=` ([[reverse.iter.op+=]]),
|
| 753 |
`operator-=` ([[reverse.iter.op-=]]), `operator[]` (
|
| 754 |
-
[[reverse.iter.opindex]]), or the
|
| 755 |
[[reverse.iter.op<]]), `operator>` ([[reverse.iter.op>]]),
|
| 756 |
`operator<=` ([[reverse.iter.op<=]]), `operator>=` (
|
| 757 |
[[reverse.iter.op>=]]), `operator-` ([[reverse.iter.opdiff]]) or
|
| 758 |
`operator+` ([[reverse.iter.opsum]]) are referenced in a way that
|
| 759 |
requires instantiation ([[temp.inst]]).
|
|
@@ -761,257 +776,252 @@ requires instantiation ([[temp.inst]]).
|
|
| 761 |
#### `reverse_iterator` operations <a id="reverse.iter.ops">[[reverse.iter.ops]]</a>
|
| 762 |
|
| 763 |
##### `reverse_iterator` constructor <a id="reverse.iter.cons">[[reverse.iter.cons]]</a>
|
| 764 |
|
| 765 |
``` cpp
|
| 766 |
-
reverse_iterator();
|
| 767 |
```
|
| 768 |
|
| 769 |
-
*Effects:* Value
|
| 770 |
the resulting iterator have defined behavior if and only if the
|
| 771 |
corresponding operations are defined on a value-initialized iterator of
|
| 772 |
type `Iterator`.
|
| 773 |
|
| 774 |
``` cpp
|
| 775 |
-
explicit reverse_iterator(Iterator x);
|
| 776 |
```
|
| 777 |
|
| 778 |
*Effects:* Initializes `current` with `x`.
|
| 779 |
|
| 780 |
``` cpp
|
| 781 |
-
template <class U> reverse_iterator(const reverse_iterator<U>
|
| 782 |
```
|
| 783 |
|
| 784 |
*Effects:* Initializes `current` with `u.current`.
|
| 785 |
|
| 786 |
##### `reverse_iterator::operator=` <a id="reverse.iter.op=">[[reverse.iter.op=]]</a>
|
| 787 |
|
| 788 |
``` cpp
|
| 789 |
template <class U>
|
| 790 |
-
reverse_iterator&
|
| 791 |
operator=(const reverse_iterator<U>& u);
|
| 792 |
```
|
| 793 |
|
| 794 |
*Effects:* Assigns `u.base()` to current.
|
| 795 |
|
| 796 |
*Returns:* `*this`.
|
| 797 |
|
| 798 |
##### Conversion <a id="reverse.iter.conv">[[reverse.iter.conv]]</a>
|
| 799 |
|
| 800 |
``` cpp
|
| 801 |
-
Iterator base() const; // explicit
|
| 802 |
```
|
| 803 |
|
| 804 |
*Returns:* `current`.
|
| 805 |
|
| 806 |
##### `operator*` <a id="reverse.iter.op.star">[[reverse.iter.op.star]]</a>
|
| 807 |
|
| 808 |
``` cpp
|
| 809 |
-
reference operator*() const;
|
| 810 |
```
|
| 811 |
|
| 812 |
-
*Effects:*
|
| 813 |
|
| 814 |
``` cpp
|
| 815 |
Iterator tmp = current;
|
| 816 |
return *--tmp;
|
| 817 |
```
|
| 818 |
|
| 819 |
##### `operator->` <a id="reverse.iter.opref">[[reverse.iter.opref]]</a>
|
| 820 |
|
| 821 |
``` cpp
|
| 822 |
-
pointer operator->() const;
|
| 823 |
```
|
| 824 |
|
| 825 |
-
*Returns:* `
|
| 826 |
|
| 827 |
##### `operator++` <a id="reverse.iter.op++">[[reverse.iter.op++]]</a>
|
| 828 |
|
| 829 |
``` cpp
|
| 830 |
-
reverse_iterator& operator++();
|
| 831 |
```
|
| 832 |
|
| 833 |
-
*Effects:* `current;`
|
| 834 |
|
| 835 |
*Returns:* `*this`.
|
| 836 |
|
| 837 |
``` cpp
|
| 838 |
-
reverse_iterator operator++(int);
|
| 839 |
```
|
| 840 |
|
| 841 |
-
*Effects:*
|
| 842 |
|
| 843 |
``` cpp
|
| 844 |
reverse_iterator tmp = *this;
|
| 845 |
--current;
|
| 846 |
return tmp;
|
| 847 |
```
|
| 848 |
|
| 849 |
\[reverse.iter.op\]`operator\dcr`
|
| 850 |
|
| 851 |
``` cpp
|
| 852 |
-
reverse_iterator& operator--();
|
| 853 |
```
|
| 854 |
|
| 855 |
-
*Effects:* `++current`
|
| 856 |
|
| 857 |
*Returns:* `*this`.
|
| 858 |
|
| 859 |
``` cpp
|
| 860 |
-
reverse_iterator operator--(int);
|
| 861 |
```
|
| 862 |
|
| 863 |
-
*Effects:*
|
| 864 |
|
| 865 |
``` cpp
|
| 866 |
reverse_iterator tmp = *this;
|
| 867 |
++current;
|
| 868 |
return tmp;
|
| 869 |
```
|
| 870 |
|
| 871 |
##### `operator+` <a id="reverse.iter.op+">[[reverse.iter.op+]]</a>
|
| 872 |
|
| 873 |
``` cpp
|
| 874 |
-
reverse_iterator
|
| 875 |
-
operator+(typename reverse_iterator<Iterator>::difference_type n) const;
|
| 876 |
```
|
| 877 |
|
| 878 |
*Returns:* `reverse_iterator(current-n)`.
|
| 879 |
|
| 880 |
##### `operator+=` <a id="reverse.iter.op+=">[[reverse.iter.op+=]]</a>
|
| 881 |
|
| 882 |
``` cpp
|
| 883 |
-
reverse_iterator&
|
| 884 |
-
operator+=(typename reverse_iterator<Iterator>::difference_type n);
|
| 885 |
```
|
| 886 |
|
| 887 |
-
*Effects:* `current -= n;`
|
| 888 |
|
| 889 |
*Returns:* `*this`.
|
| 890 |
|
| 891 |
##### `operator-` <a id="reverse.iter.op-">[[reverse.iter.op-]]</a>
|
| 892 |
|
| 893 |
``` cpp
|
| 894 |
-
reverse_iterator
|
| 895 |
-
operator-(typename reverse_iterator<Iterator>::difference_type n) const;
|
| 896 |
```
|
| 897 |
|
| 898 |
*Returns:* `reverse_iterator(current+n)`.
|
| 899 |
|
| 900 |
##### `operator-=` <a id="reverse.iter.op-=">[[reverse.iter.op-=]]</a>
|
| 901 |
|
| 902 |
``` cpp
|
| 903 |
-
reverse_iterator&
|
| 904 |
-
operator-=(typename reverse_iterator<Iterator>::difference_type n);
|
| 905 |
```
|
| 906 |
|
| 907 |
-
*Effects:* `current += n;`
|
| 908 |
|
| 909 |
*Returns:* `*this`.
|
| 910 |
|
| 911 |
##### `operator[]` <a id="reverse.iter.opindex">[[reverse.iter.opindex]]</a>
|
| 912 |
|
| 913 |
``` cpp
|
| 914 |
-
unspecified operator[](
|
| 915 |
-
typename reverse_iterator<Iterator>::difference_type n) const;
|
| 916 |
```
|
| 917 |
|
| 918 |
*Returns:* `current[-n-1]`.
|
| 919 |
|
| 920 |
##### `operator==` <a id="reverse.iter.op==">[[reverse.iter.op==]]</a>
|
| 921 |
|
| 922 |
``` cpp
|
| 923 |
template <class Iterator1, class Iterator2>
|
| 924 |
-
bool operator==(
|
| 925 |
const reverse_iterator<Iterator1>& x,
|
| 926 |
const reverse_iterator<Iterator2>& y);
|
| 927 |
```
|
| 928 |
|
| 929 |
*Returns:* `x.current == y.current`.
|
| 930 |
|
| 931 |
##### `operator<` <a id="reverse.iter.op<">[[reverse.iter.op<]]</a>
|
| 932 |
|
| 933 |
``` cpp
|
| 934 |
template <class Iterator1, class Iterator2>
|
| 935 |
-
bool operator<(
|
| 936 |
const reverse_iterator<Iterator1>& x,
|
| 937 |
const reverse_iterator<Iterator2>& y);
|
| 938 |
```
|
| 939 |
|
| 940 |
*Returns:* `x.current > y.current`.
|
| 941 |
|
| 942 |
##### `operator!=` <a id="reverse.iter.op!=">[[reverse.iter.op!=]]</a>
|
| 943 |
|
| 944 |
``` cpp
|
| 945 |
template <class Iterator1, class Iterator2>
|
| 946 |
-
bool operator!=(
|
| 947 |
const reverse_iterator<Iterator1>& x,
|
| 948 |
const reverse_iterator<Iterator2>& y);
|
| 949 |
```
|
| 950 |
|
| 951 |
*Returns:* `x.current != y.current`.
|
| 952 |
|
| 953 |
##### `operator>` <a id="reverse.iter.op>">[[reverse.iter.op>]]</a>
|
| 954 |
|
| 955 |
``` cpp
|
| 956 |
template <class Iterator1, class Iterator2>
|
| 957 |
-
bool operator>(
|
| 958 |
const reverse_iterator<Iterator1>& x,
|
| 959 |
const reverse_iterator<Iterator2>& y);
|
| 960 |
```
|
| 961 |
|
| 962 |
*Returns:* `x.current < y.current`.
|
| 963 |
|
| 964 |
##### `operator>=` <a id="reverse.iter.op>=">[[reverse.iter.op>=]]</a>
|
| 965 |
|
| 966 |
``` cpp
|
| 967 |
template <class Iterator1, class Iterator2>
|
| 968 |
-
bool operator>=(
|
| 969 |
const reverse_iterator<Iterator1>& x,
|
| 970 |
const reverse_iterator<Iterator2>& y);
|
| 971 |
```
|
| 972 |
|
| 973 |
*Returns:* `x.current <= y.current`.
|
| 974 |
|
| 975 |
##### `operator<=` <a id="reverse.iter.op<=">[[reverse.iter.op<=]]</a>
|
| 976 |
|
| 977 |
``` cpp
|
| 978 |
template <class Iterator1, class Iterator2>
|
| 979 |
-
bool operator<=(
|
| 980 |
const reverse_iterator<Iterator1>& x,
|
| 981 |
const reverse_iterator<Iterator2>& y);
|
| 982 |
```
|
| 983 |
|
| 984 |
*Returns:* `x.current >= y.current`.
|
| 985 |
|
| 986 |
##### `operator-` <a id="reverse.iter.opdiff">[[reverse.iter.opdiff]]</a>
|
| 987 |
|
| 988 |
``` cpp
|
| 989 |
template <class Iterator1, class Iterator2>
|
| 990 |
-
auto operator-(
|
| 991 |
const reverse_iterator<Iterator1>& x,
|
| 992 |
const reverse_iterator<Iterator2>& y) -> decltype(y.base() - x.base());
|
| 993 |
```
|
| 994 |
|
| 995 |
*Returns:* `y.current - x.current`.
|
| 996 |
|
| 997 |
##### `operator+` <a id="reverse.iter.opsum">[[reverse.iter.opsum]]</a>
|
| 998 |
|
| 999 |
``` cpp
|
| 1000 |
template <class Iterator>
|
| 1001 |
-
reverse_iterator<Iterator> operator+(
|
| 1002 |
typename reverse_iterator<Iterator>::difference_type n,
|
| 1003 |
const reverse_iterator<Iterator>& x);
|
| 1004 |
```
|
| 1005 |
|
| 1006 |
*Returns:* `reverse_iterator<Iterator> (x.current - n)`.
|
| 1007 |
|
| 1008 |
##### Non-member function `make_reverse_iterator()` <a id="reverse.iter.make">[[reverse.iter.make]]</a>
|
| 1009 |
|
| 1010 |
``` cpp
|
| 1011 |
template <class Iterator>
|
| 1012 |
-
reverse_iterator<Iterator> make_reverse_iterator(Iterator i);
|
| 1013 |
```
|
| 1014 |
|
| 1015 |
*Returns:* `reverse_iterator<Iterator>(i)`.
|
| 1016 |
|
| 1017 |
### Insert iterators <a id="insert.iterators">[[insert.iterators]]</a>
|
|
@@ -1048,26 +1058,29 @@ iterators out of a container.
|
|
| 1048 |
#### Class template `back_insert_iterator` <a id="back.insert.iterator">[[back.insert.iterator]]</a>
|
| 1049 |
|
| 1050 |
``` cpp
|
| 1051 |
namespace std {
|
| 1052 |
template <class Container>
|
| 1053 |
-
class back_insert_iterator
|
| 1054 |
-
public iterator<output_iterator_tag,void,void,void,void> {
|
| 1055 |
protected:
|
| 1056 |
Container* container;
|
| 1057 |
|
| 1058 |
public:
|
| 1059 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1060 |
explicit back_insert_iterator(Container& x);
|
| 1061 |
-
back_insert_iterator
|
| 1062 |
-
|
| 1063 |
-
back_insert_iterator<Container>&
|
| 1064 |
-
operator=(typename Container::value_type&& value);
|
| 1065 |
|
| 1066 |
-
back_insert_iterator
|
| 1067 |
-
back_insert_iterator
|
| 1068 |
-
back_insert_iterator
|
| 1069 |
};
|
| 1070 |
|
| 1071 |
template <class Container>
|
| 1072 |
back_insert_iterator<Container> back_inserter(Container& x);
|
| 1073 |
}
|
|
@@ -1079,45 +1092,43 @@ namespace std {
|
|
| 1079 |
|
| 1080 |
``` cpp
|
| 1081 |
explicit back_insert_iterator(Container& x);
|
| 1082 |
```
|
| 1083 |
|
| 1084 |
-
*Effects:* Initializes `container` with `
|
| 1085 |
|
| 1086 |
##### `back_insert_iterator::operator=` <a id="back.insert.iter.op=">[[back.insert.iter.op=]]</a>
|
| 1087 |
|
| 1088 |
``` cpp
|
| 1089 |
-
back_insert_iterator
|
| 1090 |
-
operator=(const typename Container::value_type& value);
|
| 1091 |
```
|
| 1092 |
|
| 1093 |
-
*Effects:* `container->push_back(value);`
|
| 1094 |
|
| 1095 |
*Returns:* `*this`.
|
| 1096 |
|
| 1097 |
``` cpp
|
| 1098 |
-
back_insert_iterator
|
| 1099 |
-
operator=(typename Container::value_type&& value);
|
| 1100 |
```
|
| 1101 |
|
| 1102 |
-
*Effects:* `container->push_back(std::move(value));`
|
| 1103 |
|
| 1104 |
*Returns:* `*this`.
|
| 1105 |
|
| 1106 |
##### `back_insert_iterator::operator*` <a id="back.insert.iter.op*">[[back.insert.iter.op*]]</a>
|
| 1107 |
|
| 1108 |
``` cpp
|
| 1109 |
-
back_insert_iterator
|
| 1110 |
```
|
| 1111 |
|
| 1112 |
*Returns:* `*this`.
|
| 1113 |
|
| 1114 |
##### `back_insert_iterator::operator++` <a id="back.insert.iter.op++">[[back.insert.iter.op++]]</a>
|
| 1115 |
|
| 1116 |
``` cpp
|
| 1117 |
-
back_insert_iterator
|
| 1118 |
-
back_insert_iterator
|
| 1119 |
```
|
| 1120 |
|
| 1121 |
*Returns:* `*this`.
|
| 1122 |
|
| 1123 |
##### `back_inserter` <a id="back.inserter">[[back.inserter]]</a>
|
|
@@ -1132,26 +1143,29 @@ template <class Container>
|
|
| 1132 |
#### Class template `front_insert_iterator` <a id="front.insert.iterator">[[front.insert.iterator]]</a>
|
| 1133 |
|
| 1134 |
``` cpp
|
| 1135 |
namespace std {
|
| 1136 |
template <class Container>
|
| 1137 |
-
class front_insert_iterator
|
| 1138 |
-
public iterator<output_iterator_tag,void,void,void,void> {
|
| 1139 |
protected:
|
| 1140 |
Container* container;
|
| 1141 |
|
| 1142 |
public:
|
| 1143 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1144 |
explicit front_insert_iterator(Container& x);
|
| 1145 |
-
front_insert_iterator
|
| 1146 |
-
|
| 1147 |
-
front_insert_iterator<Container>&
|
| 1148 |
-
operator=(typename Container::value_type&& value);
|
| 1149 |
|
| 1150 |
-
front_insert_iterator
|
| 1151 |
-
front_insert_iterator
|
| 1152 |
-
front_insert_iterator
|
| 1153 |
};
|
| 1154 |
|
| 1155 |
template <class Container>
|
| 1156 |
front_insert_iterator<Container> front_inserter(Container& x);
|
| 1157 |
}
|
|
@@ -1163,45 +1177,43 @@ namespace std {
|
|
| 1163 |
|
| 1164 |
``` cpp
|
| 1165 |
explicit front_insert_iterator(Container& x);
|
| 1166 |
```
|
| 1167 |
|
| 1168 |
-
*Effects:* Initializes `container` with `
|
| 1169 |
|
| 1170 |
##### `front_insert_iterator::operator=` <a id="front.insert.iter.op=">[[front.insert.iter.op=]]</a>
|
| 1171 |
|
| 1172 |
``` cpp
|
| 1173 |
-
front_insert_iterator
|
| 1174 |
-
operator=(const typename Container::value_type& value);
|
| 1175 |
```
|
| 1176 |
|
| 1177 |
-
*Effects:* `container->push_front(value);`
|
| 1178 |
|
| 1179 |
*Returns:* `*this`.
|
| 1180 |
|
| 1181 |
``` cpp
|
| 1182 |
-
front_insert_iterator
|
| 1183 |
-
operator=(typename Container::value_type&& value);
|
| 1184 |
```
|
| 1185 |
|
| 1186 |
-
*Effects:* `container->push_front(std::move(value));`
|
| 1187 |
|
| 1188 |
*Returns:* `*this`.
|
| 1189 |
|
| 1190 |
##### `front_insert_iterator::operator*` <a id="front.insert.iter.op*">[[front.insert.iter.op*]]</a>
|
| 1191 |
|
| 1192 |
``` cpp
|
| 1193 |
-
front_insert_iterator
|
| 1194 |
```
|
| 1195 |
|
| 1196 |
*Returns:* `*this`.
|
| 1197 |
|
| 1198 |
##### `front_insert_iterator::operator++` <a id="front.insert.iter.op++">[[front.insert.iter.op++]]</a>
|
| 1199 |
|
| 1200 |
``` cpp
|
| 1201 |
-
front_insert_iterator
|
| 1202 |
-
front_insert_iterator
|
| 1203 |
```
|
| 1204 |
|
| 1205 |
*Returns:* `*this`.
|
| 1206 |
|
| 1207 |
##### `front_inserter` <a id="front.inserter">[[front.inserter]]</a>
|
|
@@ -1216,27 +1228,30 @@ template <class Container>
|
|
| 1216 |
#### Class template `insert_iterator` <a id="insert.iterator">[[insert.iterator]]</a>
|
| 1217 |
|
| 1218 |
``` cpp
|
| 1219 |
namespace std {
|
| 1220 |
template <class Container>
|
| 1221 |
-
class insert_iterator
|
| 1222 |
-
public iterator<output_iterator_tag,void,void,void,void> {
|
| 1223 |
protected:
|
| 1224 |
Container* container;
|
| 1225 |
typename Container::iterator iter;
|
| 1226 |
|
| 1227 |
public:
|
| 1228 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1229 |
insert_iterator(Container& x, typename Container::iterator i);
|
| 1230 |
-
insert_iterator
|
| 1231 |
-
|
| 1232 |
-
insert_iterator<Container>&
|
| 1233 |
-
operator=(typename Container::value_type&& value);
|
| 1234 |
|
| 1235 |
-
insert_iterator
|
| 1236 |
-
insert_iterator
|
| 1237 |
-
insert_iterator
|
| 1238 |
};
|
| 1239 |
|
| 1240 |
template <class Container>
|
| 1241 |
insert_iterator<Container> inserter(Container& x, typename Container::iterator i);
|
| 1242 |
}
|
|
@@ -1248,35 +1263,33 @@ namespace std {
|
|
| 1248 |
|
| 1249 |
``` cpp
|
| 1250 |
insert_iterator(Container& x, typename Container::iterator i);
|
| 1251 |
```
|
| 1252 |
|
| 1253 |
-
*Effects:* Initializes `container` with `
|
| 1254 |
-
|
| 1255 |
|
| 1256 |
##### `insert_iterator::operator=` <a id="insert.iter.op=">[[insert.iter.op=]]</a>
|
| 1257 |
|
| 1258 |
``` cpp
|
| 1259 |
-
insert_iterator
|
| 1260 |
-
operator=(const typename Container::value_type& value);
|
| 1261 |
```
|
| 1262 |
|
| 1263 |
-
*Effects:*
|
| 1264 |
|
| 1265 |
``` cpp
|
| 1266 |
iter = container->insert(iter, value);
|
| 1267 |
++iter;
|
| 1268 |
```
|
| 1269 |
|
| 1270 |
*Returns:* `*this`.
|
| 1271 |
|
| 1272 |
``` cpp
|
| 1273 |
-
insert_iterator
|
| 1274 |
-
operator=(typename Container::value_type&& value);
|
| 1275 |
```
|
| 1276 |
|
| 1277 |
-
*Effects:*
|
| 1278 |
|
| 1279 |
``` cpp
|
| 1280 |
iter = container->insert(iter, std::move(value));
|
| 1281 |
++iter;
|
| 1282 |
```
|
|
@@ -1284,20 +1297,20 @@ iter = container->insert(iter, std::move(value));
|
|
| 1284 |
*Returns:* `*this`.
|
| 1285 |
|
| 1286 |
##### `insert_iterator::operator*` <a id="insert.iter.op*">[[insert.iter.op*]]</a>
|
| 1287 |
|
| 1288 |
``` cpp
|
| 1289 |
-
insert_iterator
|
| 1290 |
```
|
| 1291 |
|
| 1292 |
*Returns:* `*this`.
|
| 1293 |
|
| 1294 |
##### `insert_iterator::operator++` <a id="insert.iter.op++">[[insert.iter.op++]]</a>
|
| 1295 |
|
| 1296 |
``` cpp
|
| 1297 |
-
insert_iterator
|
| 1298 |
-
insert_iterator
|
| 1299 |
```
|
| 1300 |
|
| 1301 |
*Returns:* `*this`.
|
| 1302 |
|
| 1303 |
##### `inserter` <a id="inserter">[[inserter]]</a>
|
|
@@ -1312,335 +1325,349 @@ template <class Container>
|
|
| 1312 |
### Move iterators <a id="move.iterators">[[move.iterators]]</a>
|
| 1313 |
|
| 1314 |
Class template `move_iterator` is an iterator adaptor with the same
|
| 1315 |
behavior as the underlying iterator except that its indirection operator
|
| 1316 |
implicitly converts the value returned by the underlying iterator’s
|
| 1317 |
-
indirection operator to an rvalue
|
| 1318 |
-
|
|
|
|
|
|
|
| 1319 |
|
| 1320 |
``` cpp
|
| 1321 |
list<string> s;
|
| 1322 |
// populate the list s
|
| 1323 |
vector<string> v1(s.begin(), s.end()); // copies strings into v1
|
| 1324 |
vector<string> v2(make_move_iterator(s.begin()),
|
| 1325 |
make_move_iterator(s.end())); // moves strings into v2
|
| 1326 |
```
|
| 1327 |
|
|
|
|
|
|
|
| 1328 |
#### Class template `move_iterator` <a id="move.iterator">[[move.iterator]]</a>
|
| 1329 |
|
| 1330 |
``` cpp
|
| 1331 |
namespace std {
|
| 1332 |
template <class Iterator>
|
| 1333 |
class move_iterator {
|
| 1334 |
public:
|
| 1335 |
-
|
| 1336 |
-
|
| 1337 |
-
|
| 1338 |
-
|
| 1339 |
-
|
| 1340 |
-
|
| 1341 |
|
| 1342 |
-
move_iterator();
|
| 1343 |
-
explicit move_iterator(Iterator i);
|
| 1344 |
-
template <class U> move_iterator(const move_iterator<U>& u);
|
| 1345 |
-
template <class U> move_iterator& operator=(const move_iterator<U>& u);
|
| 1346 |
|
| 1347 |
-
iterator_type base() const;
|
| 1348 |
-
reference operator*() const;
|
| 1349 |
-
pointer operator->() const;
|
| 1350 |
|
| 1351 |
-
move_iterator& operator++();
|
| 1352 |
-
move_iterator operator++(int);
|
| 1353 |
-
move_iterator& operator--();
|
| 1354 |
-
move_iterator operator--(int);
|
| 1355 |
|
| 1356 |
-
move_iterator operator+(difference_type n) const;
|
| 1357 |
-
move_iterator& operator+=(difference_type n);
|
| 1358 |
-
move_iterator operator-(difference_type n) const;
|
| 1359 |
-
move_iterator& operator-=(difference_type n);
|
| 1360 |
-
unspecified operator[](difference_type n) const;
|
| 1361 |
|
| 1362 |
private:
|
| 1363 |
Iterator current; // exposition only
|
| 1364 |
};
|
| 1365 |
|
| 1366 |
template <class Iterator1, class Iterator2>
|
| 1367 |
-
bool operator==(
|
| 1368 |
const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 1369 |
template <class Iterator1, class Iterator2>
|
| 1370 |
-
bool operator!=(
|
| 1371 |
const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 1372 |
template <class Iterator1, class Iterator2>
|
| 1373 |
-
bool operator<(
|
| 1374 |
const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 1375 |
template <class Iterator1, class Iterator2>
|
| 1376 |
-
bool operator<=(
|
| 1377 |
const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 1378 |
template <class Iterator1, class Iterator2>
|
| 1379 |
-
bool operator>(
|
| 1380 |
const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 1381 |
template <class Iterator1, class Iterator2>
|
| 1382 |
-
bool operator>=(
|
| 1383 |
const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 1384 |
|
| 1385 |
template <class Iterator1, class Iterator2>
|
| 1386 |
-
auto operator-(
|
| 1387 |
const move_iterator<Iterator1>& x,
|
| 1388 |
const move_iterator<Iterator2>& y) -> decltype(x.base() - y.base());
|
| 1389 |
template <class Iterator>
|
| 1390 |
-
move_iterator<Iterator> operator+(
|
| 1391 |
typename move_iterator<Iterator>::difference_type n, const move_iterator<Iterator>& x);
|
| 1392 |
template <class Iterator>
|
| 1393 |
-
move_iterator<Iterator> make_move_iterator(Iterator i);
|
| 1394 |
}
|
| 1395 |
```
|
| 1396 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1397 |
#### `move_iterator` requirements <a id="move.iter.requirements">[[move.iter.requirements]]</a>
|
| 1398 |
|
| 1399 |
-
The template parameter `Iterator` shall meet the requirements
|
| 1400 |
-
|
| 1401 |
bidirectional or random access traversal functions are instantiated, the
|
| 1402 |
template parameter shall meet the requirements for a Bidirectional
|
| 1403 |
Iterator ([[bidirectional.iterators]]) or a Random Access Iterator (
|
| 1404 |
[[random.access.iterators]]), respectively.
|
| 1405 |
|
| 1406 |
#### `move_iterator` operations <a id="move.iter.ops">[[move.iter.ops]]</a>
|
| 1407 |
|
| 1408 |
##### `move_iterator` constructors <a id="move.iter.op.const">[[move.iter.op.const]]</a>
|
| 1409 |
|
| 1410 |
``` cpp
|
| 1411 |
-
move_iterator();
|
| 1412 |
```
|
| 1413 |
|
| 1414 |
-
*Effects:* Constructs a `move_iterator`, value
|
| 1415 |
Iterator operations applied to the resulting iterator have defined
|
| 1416 |
behavior if and only if the corresponding operations are defined on a
|
| 1417 |
value-initialized iterator of type `Iterator`.
|
| 1418 |
|
| 1419 |
``` cpp
|
| 1420 |
-
explicit move_iterator(Iterator i);
|
| 1421 |
```
|
| 1422 |
|
| 1423 |
*Effects:* Constructs a `move_iterator`, initializing `current` with
|
| 1424 |
`i`.
|
| 1425 |
|
| 1426 |
``` cpp
|
| 1427 |
-
template <class U> move_iterator(const move_iterator<U>& u);
|
| 1428 |
```
|
| 1429 |
|
| 1430 |
*Effects:* Constructs a `move_iterator`, initializing `current` with
|
| 1431 |
`u.base()`.
|
| 1432 |
|
| 1433 |
*Requires:* `U` shall be convertible to `Iterator`.
|
| 1434 |
|
| 1435 |
##### `move_iterator::operator=` <a id="move.iter.op=">[[move.iter.op=]]</a>
|
| 1436 |
|
| 1437 |
``` cpp
|
| 1438 |
-
template <class U> move_iterator& operator=(const move_iterator<U>& u);
|
| 1439 |
```
|
| 1440 |
|
| 1441 |
*Effects:* Assigns `u.base()` to `current`.
|
| 1442 |
|
| 1443 |
*Requires:* `U` shall be convertible to `Iterator`.
|
| 1444 |
|
| 1445 |
##### `move_iterator` conversion <a id="move.iter.op.conv">[[move.iter.op.conv]]</a>
|
| 1446 |
|
| 1447 |
``` cpp
|
| 1448 |
-
Iterator base() const;
|
| 1449 |
```
|
| 1450 |
|
| 1451 |
*Returns:* `current`.
|
| 1452 |
|
| 1453 |
##### `move_iterator::operator*` <a id="move.iter.op.star">[[move.iter.op.star]]</a>
|
| 1454 |
|
| 1455 |
``` cpp
|
| 1456 |
-
reference operator*() const;
|
| 1457 |
```
|
| 1458 |
|
| 1459 |
-
*Returns:* `
|
| 1460 |
|
| 1461 |
##### `move_iterator::operator->` <a id="move.iter.op.ref">[[move.iter.op.ref]]</a>
|
| 1462 |
|
| 1463 |
``` cpp
|
| 1464 |
-
pointer operator->() const;
|
| 1465 |
```
|
| 1466 |
|
| 1467 |
*Returns:* `current`.
|
| 1468 |
|
| 1469 |
##### `move_iterator::operator++` <a id="move.iter.op.incr">[[move.iter.op.incr]]</a>
|
| 1470 |
|
| 1471 |
``` cpp
|
| 1472 |
-
move_iterator& operator++();
|
| 1473 |
```
|
| 1474 |
|
| 1475 |
-
*Effects:* `++current`.
|
| 1476 |
|
| 1477 |
*Returns:* `*this`.
|
| 1478 |
|
| 1479 |
``` cpp
|
| 1480 |
-
move_iterator operator++(int);
|
| 1481 |
```
|
| 1482 |
|
| 1483 |
-
*Effects:*
|
| 1484 |
|
| 1485 |
``` cpp
|
| 1486 |
move_iterator tmp = *this;
|
| 1487 |
++current;
|
| 1488 |
return tmp;
|
| 1489 |
```
|
| 1490 |
|
| 1491 |
##### `move_iterator::operator-{-}` <a id="move.iter.op.decr">[[move.iter.op.decr]]</a>
|
| 1492 |
|
| 1493 |
``` cpp
|
| 1494 |
-
move_iterator& operator--();
|
| 1495 |
```
|
| 1496 |
|
| 1497 |
-
*Effects:*
|
| 1498 |
|
| 1499 |
*Returns:* `*this`.
|
| 1500 |
|
| 1501 |
``` cpp
|
| 1502 |
-
move_iterator operator--(int);
|
| 1503 |
```
|
| 1504 |
|
| 1505 |
-
*Effects:*
|
| 1506 |
|
| 1507 |
``` cpp
|
| 1508 |
move_iterator tmp = *this;
|
| 1509 |
--current;
|
| 1510 |
return tmp;
|
| 1511 |
```
|
| 1512 |
|
| 1513 |
##### `move_iterator::operator+` <a id="move.iter.op.+">[[move.iter.op.+]]</a>
|
| 1514 |
|
| 1515 |
``` cpp
|
| 1516 |
-
move_iterator operator+(difference_type n) const;
|
| 1517 |
```
|
| 1518 |
|
| 1519 |
*Returns:* `move_iterator(current + n)`.
|
| 1520 |
|
| 1521 |
##### `move_iterator::operator+=` <a id="move.iter.op.+=">[[move.iter.op.+=]]</a>
|
| 1522 |
|
| 1523 |
``` cpp
|
| 1524 |
-
move_iterator& operator+=(difference_type n);
|
| 1525 |
```
|
| 1526 |
|
| 1527 |
-
*Effects:* `current += n`
|
| 1528 |
|
| 1529 |
*Returns:* `*this`.
|
| 1530 |
|
| 1531 |
##### `move_iterator::operator-` <a id="move.iter.op.-">[[move.iter.op.-]]</a>
|
| 1532 |
|
| 1533 |
``` cpp
|
| 1534 |
-
move_iterator operator-(difference_type n) const;
|
| 1535 |
```
|
| 1536 |
|
| 1537 |
*Returns:* `move_iterator(current - n)`.
|
| 1538 |
|
| 1539 |
##### `move_iterator::operator-=` <a id="move.iter.op.-=">[[move.iter.op.-=]]</a>
|
| 1540 |
|
| 1541 |
``` cpp
|
| 1542 |
-
move_iterator& operator-=(difference_type n);
|
| 1543 |
```
|
| 1544 |
|
| 1545 |
-
*Effects:* `current -= n`
|
| 1546 |
|
| 1547 |
*Returns:* `*this`.
|
| 1548 |
|
| 1549 |
##### `move_iterator::operator[]` <a id="move.iter.op.index">[[move.iter.op.index]]</a>
|
| 1550 |
|
| 1551 |
``` cpp
|
| 1552 |
-
unspecified operator[](difference_type n) const;
|
| 1553 |
```
|
| 1554 |
|
| 1555 |
-
*Returns:* `std::move(
|
| 1556 |
|
| 1557 |
##### `move_iterator` comparisons <a id="move.iter.op.comp">[[move.iter.op.comp]]</a>
|
| 1558 |
|
| 1559 |
``` cpp
|
| 1560 |
template <class Iterator1, class Iterator2>
|
| 1561 |
-
bool operator==(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 1562 |
```
|
| 1563 |
|
| 1564 |
*Returns:* `x.base() == y.base()`.
|
| 1565 |
|
| 1566 |
``` cpp
|
| 1567 |
template <class Iterator1, class Iterator2>
|
| 1568 |
-
bool operator!=(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 1569 |
```
|
| 1570 |
|
| 1571 |
*Returns:* `!(x == y)`.
|
| 1572 |
|
| 1573 |
``` cpp
|
| 1574 |
template <class Iterator1, class Iterator2>
|
| 1575 |
-
bool operator<(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 1576 |
```
|
| 1577 |
|
| 1578 |
*Returns:* `x.base() < y.base()`.
|
| 1579 |
|
| 1580 |
``` cpp
|
| 1581 |
template <class Iterator1, class Iterator2>
|
| 1582 |
-
bool operator<=(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 1583 |
```
|
| 1584 |
|
| 1585 |
*Returns:* `!(y < x)`.
|
| 1586 |
|
| 1587 |
``` cpp
|
| 1588 |
template <class Iterator1, class Iterator2>
|
| 1589 |
-
bool operator>(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 1590 |
```
|
| 1591 |
|
| 1592 |
*Returns:* `y < x`.
|
| 1593 |
|
| 1594 |
``` cpp
|
| 1595 |
template <class Iterator1, class Iterator2>
|
| 1596 |
-
bool operator>=(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 1597 |
```
|
| 1598 |
|
| 1599 |
*Returns:* `!(x < y)`.
|
| 1600 |
|
| 1601 |
##### `move_iterator` non-member functions <a id="move.iter.nonmember">[[move.iter.nonmember]]</a>
|
| 1602 |
|
| 1603 |
``` cpp
|
| 1604 |
template <class Iterator1, class Iterator2>
|
| 1605 |
-
auto operator-(
|
| 1606 |
const move_iterator<Iterator1>& x,
|
| 1607 |
const move_iterator<Iterator2>& y) -> decltype(x.base() - y.base());
|
| 1608 |
```
|
| 1609 |
|
| 1610 |
*Returns:* `x.base() - y.base()`.
|
| 1611 |
|
| 1612 |
``` cpp
|
| 1613 |
template <class Iterator>
|
| 1614 |
-
move_iterator<Iterator> operator+(
|
| 1615 |
typename move_iterator<Iterator>::difference_type n, const move_iterator<Iterator>& x);
|
| 1616 |
```
|
| 1617 |
|
| 1618 |
*Returns:* `x + n`.
|
| 1619 |
|
| 1620 |
``` cpp
|
| 1621 |
template <class Iterator>
|
| 1622 |
-
move_iterator<Iterator> make_move_iterator(Iterator i);
|
| 1623 |
```
|
| 1624 |
|
| 1625 |
*Returns:* `move_iterator<Iterator>(i)`.
|
| 1626 |
|
| 1627 |
## Stream iterators <a id="stream.iterators">[[stream.iterators]]</a>
|
| 1628 |
|
| 1629 |
To make it possible for algorithmic templates to work directly with
|
| 1630 |
input/output streams, appropriate iterator-like class templates are
|
| 1631 |
provided.
|
| 1632 |
|
|
|
|
|
|
|
| 1633 |
``` cpp
|
| 1634 |
partial_sum(istream_iterator<double, char>(cin),
|
| 1635 |
istream_iterator<double, char>(),
|
| 1636 |
ostream_iterator<double, char>(cout, "\n"));
|
| 1637 |
```
|
| 1638 |
|
| 1639 |
-
reads a file containing floating
|
| 1640 |
the partial sums onto `cout`.
|
| 1641 |
|
|
|
|
|
|
|
| 1642 |
### Class template `istream_iterator` <a id="istream.iterator">[[istream.iterator]]</a>
|
| 1643 |
|
| 1644 |
The class template `istream_iterator` is an input iterator (
|
| 1645 |
[[input.iterators]]) that reads (using `operator>>`) successive elements
|
| 1646 |
from the input stream for which it was constructed. After it is
|
|
@@ -1653,35 +1680,42 @@ object, which is the only legitimate iterator to be used for the end
|
|
| 1653 |
condition. The result of `operator*` on an end-of-stream iterator is not
|
| 1654 |
defined. For any other iterator value a `const T&` is returned. The
|
| 1655 |
result of `operator->` on an end-of-stream iterator is not defined. For
|
| 1656 |
any other iterator value a `const T*` is returned. The behavior of a
|
| 1657 |
program that applies `operator++()` to an end-of-stream iterator is
|
| 1658 |
-
undefined. It is impossible to store things into istream iterators.
|
|
|
|
|
|
|
| 1659 |
|
| 1660 |
Two end-of-stream iterators are always equal. An end-of-stream iterator
|
| 1661 |
is not equal to a non-end-of-stream iterator. Two non-end-of-stream
|
| 1662 |
iterators are equal when they are constructed from the same stream.
|
| 1663 |
|
| 1664 |
``` cpp
|
| 1665 |
namespace std {
|
| 1666 |
template <class T, class charT = char, class traits = char_traits<charT>,
|
| 1667 |
class Distance = ptrdiff_t>
|
| 1668 |
-
class istream_iterator
|
| 1669 |
-
public iterator<input_iterator_tag, T, Distance, const T*, const T&> {
|
| 1670 |
public:
|
| 1671 |
-
|
| 1672 |
-
|
| 1673 |
-
|
| 1674 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1675 |
istream_iterator(istream_type& s);
|
| 1676 |
istream_iterator(const istream_iterator& x) = default;
|
| 1677 |
~istream_iterator() = default;
|
| 1678 |
|
| 1679 |
const T& operator*() const;
|
| 1680 |
const T* operator->() const;
|
| 1681 |
-
istream_iterator
|
| 1682 |
-
istream_iterator
|
| 1683 |
private:
|
| 1684 |
basic_istream<charT,traits>* in_stream; // exposition only
|
| 1685 |
T value; // exposition only
|
| 1686 |
};
|
| 1687 |
|
|
@@ -1695,77 +1729,80 @@ namespace std {
|
|
| 1695 |
```
|
| 1696 |
|
| 1697 |
#### `istream_iterator` constructors and destructor <a id="istream.iterator.cons">[[istream.iterator.cons]]</a>
|
| 1698 |
|
| 1699 |
``` cpp
|
| 1700 |
-
|
| 1701 |
```
|
| 1702 |
|
| 1703 |
-
*Effects:* Constructs the end-of-stream iterator. If
|
| 1704 |
-
|
|
|
|
| 1705 |
|
| 1706 |
-
`in_stream == 0`.
|
| 1707 |
|
| 1708 |
``` cpp
|
| 1709 |
istream_iterator(istream_type& s);
|
| 1710 |
```
|
| 1711 |
|
| 1712 |
-
*Effects:* Initializes
|
| 1713 |
-
during construction or the first time it is referenced.
|
| 1714 |
|
| 1715 |
-
`in_stream ==
|
| 1716 |
|
| 1717 |
``` cpp
|
| 1718 |
istream_iterator(const istream_iterator& x) = default;
|
| 1719 |
```
|
| 1720 |
|
| 1721 |
-
*Effects:* Constructs a copy of `x`. If
|
| 1722 |
-
|
|
|
|
| 1723 |
|
| 1724 |
-
`in_stream == x.in_stream`.
|
| 1725 |
|
| 1726 |
``` cpp
|
| 1727 |
~istream_iterator() = default;
|
| 1728 |
```
|
| 1729 |
|
| 1730 |
-
*Effects:* The iterator is destroyed. If
|
| 1731 |
-
|
|
|
|
| 1732 |
|
| 1733 |
#### `istream_iterator` operations <a id="istream.iterator.ops">[[istream.iterator.ops]]</a>
|
| 1734 |
|
| 1735 |
``` cpp
|
| 1736 |
const T& operator*() const;
|
| 1737 |
```
|
| 1738 |
|
| 1739 |
-
*Returns:*
|
| 1740 |
|
| 1741 |
``` cpp
|
| 1742 |
const T* operator->() const;
|
| 1743 |
```
|
| 1744 |
|
| 1745 |
-
*Returns:* `
|
| 1746 |
|
| 1747 |
``` cpp
|
| 1748 |
-
istream_iterator
|
| 1749 |
```
|
| 1750 |
|
| 1751 |
*Requires:* `in_stream != 0`.
|
| 1752 |
|
| 1753 |
-
*Effects:* `*in_stream >>value`
|
| 1754 |
|
| 1755 |
*Returns:* `*this`.
|
| 1756 |
|
| 1757 |
``` cpp
|
| 1758 |
-
istream_iterator
|
| 1759 |
```
|
| 1760 |
|
| 1761 |
*Requires:* `in_stream != 0`.
|
| 1762 |
|
| 1763 |
-
*Effects:*
|
| 1764 |
|
| 1765 |
``` cpp
|
| 1766 |
-
istream_iterator
|
| 1767 |
*in_stream >> value;
|
| 1768 |
return (tmp);
|
| 1769 |
```
|
| 1770 |
|
| 1771 |
``` cpp
|
|
@@ -1803,25 +1840,30 @@ while (first != last)
|
|
| 1803 |
is defined as:
|
| 1804 |
|
| 1805 |
``` cpp
|
| 1806 |
namespace std {
|
| 1807 |
template <class T, class charT = char, class traits = char_traits<charT>>
|
| 1808 |
-
class ostream_iterator
|
| 1809 |
-
public iterator<output_iterator_tag, void, void, void, void> {
|
| 1810 |
public:
|
| 1811 |
-
|
| 1812 |
-
|
| 1813 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1814 |
ostream_iterator(ostream_type& s);
|
| 1815 |
ostream_iterator(ostream_type& s, const charT* delimiter);
|
| 1816 |
-
ostream_iterator(const ostream_iterator
|
| 1817 |
~ostream_iterator();
|
| 1818 |
-
ostream_iterator
|
| 1819 |
|
| 1820 |
-
ostream_iterator
|
| 1821 |
-
ostream_iterator
|
| 1822 |
-
ostream_iterator
|
| 1823 |
private:
|
| 1824 |
basic_ostream<charT,traits>* out_stream; // exposition only
|
| 1825 |
const charT* delim; // exposition only
|
| 1826 |
};
|
| 1827 |
}
|
|
@@ -1831,17 +1873,18 @@ namespace std {
|
|
| 1831 |
|
| 1832 |
``` cpp
|
| 1833 |
ostream_iterator(ostream_type& s);
|
| 1834 |
```
|
| 1835 |
|
| 1836 |
-
*Effects:* Initializes
|
|
|
|
| 1837 |
|
| 1838 |
``` cpp
|
| 1839 |
ostream_iterator(ostream_type& s, const charT* delimiter);
|
| 1840 |
```
|
| 1841 |
|
| 1842 |
-
*Effects:* Initializes
|
| 1843 |
`delimiter`.
|
| 1844 |
|
| 1845 |
``` cpp
|
| 1846 |
ostream_iterator(const ostream_iterator& x);
|
| 1847 |
```
|
|
@@ -1858,11 +1901,11 @@ ostream_iterator(const ostream_iterator& x);
|
|
| 1858 |
|
| 1859 |
``` cpp
|
| 1860 |
ostream_iterator& operator=(const T& value);
|
| 1861 |
```
|
| 1862 |
|
| 1863 |
-
*Effects:*
|
| 1864 |
|
| 1865 |
``` cpp
|
| 1866 |
*out_stream << value;
|
| 1867 |
if (delim != 0)
|
| 1868 |
*out_stream << delim;
|
|
@@ -1885,49 +1928,50 @@ ostream_iterator& operator++(int);
|
|
| 1885 |
### Class template `istreambuf_iterator` <a id="istreambuf.iterator">[[istreambuf.iterator]]</a>
|
| 1886 |
|
| 1887 |
The class template `istreambuf_iterator` defines an input iterator (
|
| 1888 |
[[input.iterators]]) that reads successive *characters* from the
|
| 1889 |
streambuf for which it was constructed. `operator*` provides access to
|
| 1890 |
-
the current input character, if any. `operator
|
| 1891 |
-
|
| 1892 |
-
|
| 1893 |
-
|
| 1894 |
-
|
| 1895 |
-
constructor `istreambuf_iterator()`
|
| 1896 |
-
|
| 1897 |
-
|
| 1898 |
-
`istreambuf_iterator` shall have a trivial copy constructor, a
|
| 1899 |
`constexpr` default constructor, and a trivial destructor.
|
| 1900 |
|
| 1901 |
The result of `operator*()` on an end-of-stream iterator is undefined.
|
| 1902 |
For any other iterator value a `char_type` value is returned. It is
|
| 1903 |
impossible to assign a character via an input iterator.
|
| 1904 |
|
| 1905 |
``` cpp
|
| 1906 |
namespace std {
|
| 1907 |
template<class charT, class traits = char_traits<charT>>
|
| 1908 |
-
class istreambuf_iterator
|
| 1909 |
-
: public iterator<input_iterator_tag, charT,
|
| 1910 |
-
typename traits::off_type, unspecified, charT> {
|
| 1911 |
public:
|
| 1912 |
-
|
| 1913 |
-
|
| 1914 |
-
|
| 1915 |
-
|
| 1916 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1917 |
|
| 1918 |
class proxy; // exposition only
|
| 1919 |
|
| 1920 |
constexpr istreambuf_iterator() noexcept;
|
| 1921 |
istreambuf_iterator(const istreambuf_iterator&) noexcept = default;
|
| 1922 |
~istreambuf_iterator() = default;
|
| 1923 |
istreambuf_iterator(istream_type& s) noexcept;
|
| 1924 |
istreambuf_iterator(streambuf_type* s) noexcept;
|
| 1925 |
istreambuf_iterator(const proxy& p) noexcept;
|
| 1926 |
charT operator*() const;
|
| 1927 |
-
|
| 1928 |
-
istreambuf_iterator<charT,traits>& operator++();
|
| 1929 |
proxy operator++(int);
|
| 1930 |
bool equal(const istreambuf_iterator& b) const;
|
| 1931 |
private:
|
| 1932 |
streambuf_type* sbuf_; // exposition only
|
| 1933 |
};
|
|
@@ -1939,11 +1983,11 @@ namespace std {
|
|
| 1939 |
bool operator!=(const istreambuf_iterator<charT,traits>& a,
|
| 1940 |
const istreambuf_iterator<charT,traits>& b);
|
| 1941 |
}
|
| 1942 |
```
|
| 1943 |
|
| 1944 |
-
#### Class template `istreambuf_iterator::proxy` <a id="istreambuf.iterator
|
| 1945 |
|
| 1946 |
``` cpp
|
| 1947 |
namespace std {
|
| 1948 |
template <class charT, class traits = char_traits<charT>>
|
| 1949 |
class istreambuf_iterator<charT, traits>::proxy { // exposition only
|
|
@@ -1965,81 +2009,77 @@ placeholder as the return value of the post-increment operator
|
|
| 1965 |
(`operator++`). It keeps the character pointed to by the previous value
|
| 1966 |
of the iterator for some possible future access to get the character.
|
| 1967 |
|
| 1968 |
#### `istreambuf_iterator` constructors <a id="istreambuf.iterator.cons">[[istreambuf.iterator.cons]]</a>
|
| 1969 |
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1970 |
``` cpp
|
| 1971 |
constexpr istreambuf_iterator() noexcept;
|
| 1972 |
```
|
| 1973 |
|
| 1974 |
-
*Effects:*
|
| 1975 |
|
| 1976 |
``` cpp
|
| 1977 |
-
istreambuf_iterator(
|
| 1978 |
-
istreambuf_iterator(basic_streambuf<charT,traits>* s) noexcept;
|
| 1979 |
```
|
| 1980 |
|
| 1981 |
-
*Effects:*
|
| 1982 |
-
|
| 1983 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1984 |
|
| 1985 |
``` cpp
|
| 1986 |
istreambuf_iterator(const proxy& p) noexcept;
|
| 1987 |
```
|
| 1988 |
|
| 1989 |
-
*Effects:*
|
| 1990 |
-
`basic_streambuf<>` object pointed to by the `proxy` object’s
|
| 1991 |
-
constructor argument `p`.
|
| 1992 |
|
| 1993 |
-
#### `istreambuf_iterator
|
| 1994 |
|
| 1995 |
``` cpp
|
| 1996 |
charT operator*() const
|
| 1997 |
```
|
| 1998 |
|
| 1999 |
*Returns:* The character obtained via the `streambuf` member
|
| 2000 |
`sbuf_->sgetc()`.
|
| 2001 |
|
| 2002 |
-
#### `istreambuf_iterator::operator++` <a id="istreambuf.iterator::op++">[[istreambuf.iterator::op++]]</a>
|
| 2003 |
-
|
| 2004 |
``` cpp
|
| 2005 |
-
istreambuf_iterator
|
| 2006 |
-
istreambuf_iterator<charT,traits>::operator++();
|
| 2007 |
```
|
| 2008 |
|
| 2009 |
-
*Effects:* `sbuf_->sbumpc()`.
|
| 2010 |
|
| 2011 |
*Returns:* `*this`.
|
| 2012 |
|
| 2013 |
``` cpp
|
| 2014 |
-
proxy
|
| 2015 |
```
|
| 2016 |
|
| 2017 |
*Returns:* `proxy(sbuf_->sbumpc(), sbuf_)`.
|
| 2018 |
|
| 2019 |
-
#### `istreambuf_iterator::equal` <a id="istreambuf.iterator::equal">[[istreambuf.iterator::equal]]</a>
|
| 2020 |
-
|
| 2021 |
``` cpp
|
| 2022 |
-
bool equal(const istreambuf_iterator
|
| 2023 |
```
|
| 2024 |
|
| 2025 |
*Returns:* `true` if and only if both iterators are at end-of-stream, or
|
| 2026 |
neither is at end-of-stream, regardless of what `streambuf` object they
|
| 2027 |
use.
|
| 2028 |
|
| 2029 |
-
#### `operator==` <a id="istreambuf.iterator::op==">[[istreambuf.iterator::op==]]</a>
|
| 2030 |
-
|
| 2031 |
``` cpp
|
| 2032 |
template <class charT, class traits>
|
| 2033 |
bool operator==(const istreambuf_iterator<charT,traits>& a,
|
| 2034 |
const istreambuf_iterator<charT,traits>& b);
|
| 2035 |
```
|
| 2036 |
|
| 2037 |
*Returns:* `a.equal(b)`.
|
| 2038 |
|
| 2039 |
-
#### `operator!=` <a id="istreambuf.iterator::op!=">[[istreambuf.iterator::op!=]]</a>
|
| 2040 |
-
|
| 2041 |
``` cpp
|
| 2042 |
template <class charT, class traits>
|
| 2043 |
bool operator!=(const istreambuf_iterator<charT,traits>& a,
|
| 2044 |
const istreambuf_iterator<charT,traits>& b);
|
| 2045 |
```
|
|
@@ -2049,19 +2089,22 @@ template <class charT, class traits>
|
|
| 2049 |
### Class template `ostreambuf_iterator` <a id="ostreambuf.iterator">[[ostreambuf.iterator]]</a>
|
| 2050 |
|
| 2051 |
``` cpp
|
| 2052 |
namespace std {
|
| 2053 |
template <class charT, class traits = char_traits<charT>>
|
| 2054 |
-
class ostreambuf_iterator
|
| 2055 |
-
public iterator<output_iterator_tag, void, void, void, void> {
|
| 2056 |
public:
|
| 2057 |
-
|
| 2058 |
-
|
| 2059 |
-
|
| 2060 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 2061 |
|
| 2062 |
-
public:
|
| 2063 |
ostreambuf_iterator(ostream_type& s) noexcept;
|
| 2064 |
ostreambuf_iterator(streambuf_type* s) noexcept;
|
| 2065 |
ostreambuf_iterator& operator=(charT c);
|
| 2066 |
|
| 2067 |
ostreambuf_iterator& operator*();
|
|
@@ -2098,28 +2141,27 @@ ostreambuf_iterator(streambuf_type* s) noexcept;
|
|
| 2098 |
*Effects:* Initializes `sbuf_` with `s`.
|
| 2099 |
|
| 2100 |
#### `ostreambuf_iterator` operations <a id="ostreambuf.iter.ops">[[ostreambuf.iter.ops]]</a>
|
| 2101 |
|
| 2102 |
``` cpp
|
| 2103 |
-
ostreambuf_iterator
|
| 2104 |
-
operator=(charT c);
|
| 2105 |
```
|
| 2106 |
|
| 2107 |
*Effects:* If `failed()` yields `false`, calls `sbuf_->sputc(c)`;
|
| 2108 |
otherwise has no effect.
|
| 2109 |
|
| 2110 |
*Returns:* `*this`.
|
| 2111 |
|
| 2112 |
``` cpp
|
| 2113 |
-
ostreambuf_iterator
|
| 2114 |
```
|
| 2115 |
|
| 2116 |
*Returns:* `*this`.
|
| 2117 |
|
| 2118 |
``` cpp
|
| 2119 |
-
ostreambuf_iterator
|
| 2120 |
-
ostreambuf_iterator
|
| 2121 |
```
|
| 2122 |
|
| 2123 |
*Returns:* `*this`.
|
| 2124 |
|
| 2125 |
``` cpp
|
|
@@ -2127,28 +2169,28 @@ bool failed() const noexcept;
|
|
| 2127 |
```
|
| 2128 |
|
| 2129 |
*Returns:* `true` if in any prior use of member `operator=`, the call to
|
| 2130 |
`sbuf_->sputc()` returned `traits::eof()`; or `false` otherwise.
|
| 2131 |
|
| 2132 |
-
##
|
| 2133 |
|
| 2134 |
In addition to being available via inclusion of the `<iterator>` header,
|
| 2135 |
the function templates in [[iterator.range]] are available when any of
|
| 2136 |
the following headers are included: `<array>`, `<deque>`,
|
| 2137 |
`<forward_list>`, `<list>`, `<map>`, `<regex>`, `<set>`, `<string>`,
|
| 2138 |
-
`<unordered_map>`, `<unordered_set>`, and `<vector>`.
|
| 2139 |
|
| 2140 |
``` cpp
|
| 2141 |
-
template <class C> auto begin(C& c) -> decltype(c.begin());
|
| 2142 |
-
template <class C> auto begin(const C& c) -> decltype(c.begin());
|
| 2143 |
```
|
| 2144 |
|
| 2145 |
*Returns:* `c.begin()`.
|
| 2146 |
|
| 2147 |
``` cpp
|
| 2148 |
-
template <class C> auto end(C& c) -> decltype(c.end());
|
| 2149 |
-
template <class C> auto end(const C& c) -> decltype(c.end());
|
| 2150 |
```
|
| 2151 |
|
| 2152 |
*Returns:* `c.end()`.
|
| 2153 |
|
| 2154 |
``` cpp
|
|
@@ -2176,71 +2218,126 @@ template <class C> constexpr auto cend(const C& c) noexcept(noexcept(std::end(c)
|
|
| 2176 |
```
|
| 2177 |
|
| 2178 |
*Returns:* `std::end(c)`.
|
| 2179 |
|
| 2180 |
``` cpp
|
| 2181 |
-
template <class C> auto rbegin(C& c) -> decltype(c.rbegin());
|
| 2182 |
-
template <class C> auto rbegin(const C& c) -> decltype(c.rbegin());
|
| 2183 |
```
|
| 2184 |
|
| 2185 |
*Returns:* `c.rbegin()`.
|
| 2186 |
|
| 2187 |
``` cpp
|
| 2188 |
-
template <class C> auto rend(C& c) -> decltype(c.rend());
|
| 2189 |
-
template <class C> auto rend(const C& c) -> decltype(c.rend());
|
| 2190 |
```
|
| 2191 |
|
| 2192 |
*Returns:* `c.rend()`.
|
| 2193 |
|
| 2194 |
``` cpp
|
| 2195 |
-
template <class T, size_t N> reverse_iterator<T*> rbegin(T (&array)[N]);
|
| 2196 |
```
|
| 2197 |
|
| 2198 |
*Returns:* `reverse_iterator<T*>(array + N)`.
|
| 2199 |
|
| 2200 |
``` cpp
|
| 2201 |
-
template <class T, size_t N> reverse_iterator<T*> rend(T (&array)[N]);
|
| 2202 |
```
|
| 2203 |
|
| 2204 |
*Returns:* `reverse_iterator<T*>(array)`.
|
| 2205 |
|
| 2206 |
``` cpp
|
| 2207 |
-
template <class E> reverse_iterator<const E*> rbegin(initializer_list<E> il);
|
| 2208 |
```
|
| 2209 |
|
| 2210 |
*Returns:* `reverse_iterator<const E*>(il.end())`.
|
| 2211 |
|
| 2212 |
``` cpp
|
| 2213 |
-
template <class E> reverse_iterator<const E*> rend(initializer_list<E> il);
|
| 2214 |
```
|
| 2215 |
|
| 2216 |
*Returns:* `reverse_iterator<const E*>(il.begin())`.
|
| 2217 |
|
| 2218 |
``` cpp
|
| 2219 |
-
template <class C> auto crbegin(const C& c) -> decltype(std::rbegin(c));
|
| 2220 |
```
|
| 2221 |
|
| 2222 |
*Returns:* `std::rbegin(c)`.
|
| 2223 |
|
| 2224 |
``` cpp
|
| 2225 |
-
template <class C> auto crend(const C& c) -> decltype(std::rend(c));
|
| 2226 |
```
|
| 2227 |
|
| 2228 |
*Returns:* `std::rend(c)`.
|
| 2229 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 2230 |
<!-- Link reference definitions -->
|
| 2231 |
[back.insert.iter.cons]: #back.insert.iter.cons
|
| 2232 |
[back.insert.iter.op*]: #back.insert.iter.op*
|
| 2233 |
[back.insert.iter.op++]: #back.insert.iter.op++
|
| 2234 |
[back.insert.iter.op=]: #back.insert.iter.op=
|
| 2235 |
[back.insert.iter.ops]: #back.insert.iter.ops
|
| 2236 |
[back.insert.iterator]: #back.insert.iterator
|
| 2237 |
[back.inserter]: #back.inserter
|
| 2238 |
[bidirectional.iterators]: #bidirectional.iterators
|
| 2239 |
[containers]: containers.md#containers
|
| 2240 |
-
[copyassignable]: #copyassignable
|
| 2241 |
-
[equalitycomparable]: #equalitycomparable
|
| 2242 |
[forward.iterators]: #forward.iterators
|
| 2243 |
[front.insert.iter.cons]: #front.insert.iter.cons
|
| 2244 |
[front.insert.iter.op*]: #front.insert.iter.op*
|
| 2245 |
[front.insert.iter.op++]: #front.insert.iter.op++
|
| 2246 |
[front.insert.iter.op=]: #front.insert.iter.op=
|
|
@@ -2260,17 +2357,13 @@ template <class C> auto crend(const C& c) -> decltype(std::rend(c));
|
|
| 2260 |
[istream.iterator]: #istream.iterator
|
| 2261 |
[istream.iterator.cons]: #istream.iterator.cons
|
| 2262 |
[istream.iterator.ops]: #istream.iterator.ops
|
| 2263 |
[istreambuf.iterator]: #istreambuf.iterator
|
| 2264 |
[istreambuf.iterator.cons]: #istreambuf.iterator.cons
|
| 2265 |
-
[istreambuf.iterator
|
| 2266 |
-
[istreambuf.iterator
|
| 2267 |
-
[
|
| 2268 |
-
[istreambuf.iterator::op++]: #istreambuf.iterator::op++
|
| 2269 |
-
[istreambuf.iterator::op==]: #istreambuf.iterator::op==
|
| 2270 |
-
[istreambuf.iterator::proxy]: #istreambuf.iterator::proxy
|
| 2271 |
-
[iterator.basic]: #iterator.basic
|
| 2272 |
[iterator.iterators]: #iterator.iterators
|
| 2273 |
[iterator.operations]: #iterator.operations
|
| 2274 |
[iterator.primitives]: #iterator.primitives
|
| 2275 |
[iterator.range]: #iterator.range
|
| 2276 |
[iterator.requirements]: #iterator.requirements
|
|
@@ -2332,18 +2425,21 @@ template <class C> auto crend(const C& c) -> decltype(std::rend(c));
|
|
| 2332 |
[reverse.iterators]: #reverse.iterators
|
| 2333 |
[std.iterator.tags]: #std.iterator.tags
|
| 2334 |
[stream.buffers]: input.md#stream.buffers
|
| 2335 |
[stream.iterators]: #stream.iterators
|
| 2336 |
[swappable.requirements]: library.md#swappable.requirements
|
|
|
|
|
|
|
| 2337 |
[tab:iterator.bidirectional.requirements]: #tab:iterator.bidirectional.requirements
|
| 2338 |
[tab:iterator.forward.requirements]: #tab:iterator.forward.requirements
|
| 2339 |
[tab:iterator.input.requirements]: #tab:iterator.input.requirements
|
| 2340 |
[tab:iterator.output.requirements]: #tab:iterator.output.requirements
|
| 2341 |
[tab:iterator.random.access.requirements]: #tab:iterator.random.access.requirements
|
| 2342 |
[tab:iterator.requirements]: #tab:iterator.requirements
|
| 2343 |
[tab:iterators.lib.summary]: #tab:iterators.lib.summary
|
| 2344 |
[tab:iterators.relations]: #tab:iterators.relations
|
|
|
|
| 2345 |
[temp.inst]: temp.md#temp.inst
|
| 2346 |
[utility.arg.requirements]: library.md#utility.arg.requirements
|
| 2347 |
|
| 2348 |
[^1]: This definition applies to pointers, since pointers are iterators.
|
| 2349 |
The effect of dereferencing an iterator that has been invalidated is
|
|
|
|
| 27 |
Iterators are a generalization of pointers that allow a C++program to
|
| 28 |
work with different data structures (containers) in a uniform manner. To
|
| 29 |
be able to construct template algorithms that work correctly and
|
| 30 |
efficiently on different types of data structures, the library
|
| 31 |
formalizes not just the interfaces but also the semantics and complexity
|
| 32 |
+
assumptions of iterators. An input iterator `i` supports the expression
|
| 33 |
`*i`, resulting in a value of some object type `T`, called the *value
|
| 34 |
+
type* of the iterator. An output iterator `i` has a non-empty set of
|
| 35 |
+
types that are *writable* to the iterator; for each such type `T`, the
|
| 36 |
+
expression `*i = o` is valid where `o` is a value of type `T`. An
|
| 37 |
+
iterator `i` for which the expression `(*i).m` is well-defined supports
|
| 38 |
the expression `i->m` with the same semantics as `(*i).m`. For every
|
| 39 |
iterator type `X` for which equality is defined, there is a
|
| 40 |
corresponding signed integer type called the *difference type* of the
|
| 41 |
iterator.
|
| 42 |
|
|
|
|
| 63 |
be used whenever a forward iterator is specified; Random access
|
| 64 |
iterators also satisfy all the requirements of bidirectional iterators
|
| 65 |
and can be used whenever a bidirectional iterator is specified.
|
| 66 |
|
| 67 |
Iterators that further satisfy the requirements of output iterators are
|
| 68 |
+
called *mutable iterators*. Nonmutable iterators are referred to as
|
| 69 |
+
*constant iterators*.
|
| 70 |
+
|
| 71 |
+
In addition to the requirements in this subclause, the nested
|
| 72 |
+
*typedef-name*s specified in [[iterator.traits]] shall be provided for
|
| 73 |
+
the iterator type.
|
| 74 |
+
|
| 75 |
+
[*Note 1*: Either the iterator type must provide the *typedef-name*s
|
| 76 |
+
directly (in which case `iterator_traits` pick them up automatically),
|
| 77 |
+
or an `iterator_traits` specialization must provide them. — *end note*]
|
| 78 |
+
|
| 79 |
+
Iterators that further satisfy the requirement that, for integral values
|
| 80 |
+
`n` and dereferenceable iterator values `a` and `(a + n)`, `*(a + n)` is
|
| 81 |
+
equivalent to `*(addressof(*a) + n)`, are called *contiguous iterators*.
|
| 82 |
+
|
| 83 |
+
[*Note 2*: For example, the type “pointer to `int`” is a contiguous
|
| 84 |
+
iterator, but `reverse_iterator<int *>` is not. For a valid iterator
|
| 85 |
+
range [`a`,`b`) with dereferenceable `a`, the corresponding range
|
| 86 |
+
denoted by pointers is [`addressof(*a)`,`addressof(*a) + (b - a)`); `b`
|
| 87 |
+
might not be dereferenceable. — *end note*]
|
| 88 |
|
| 89 |
Just as a regular pointer to an array guarantees that there is a pointer
|
| 90 |
value pointing past the last element of the array, so for any iterator
|
| 91 |
type there is an iterator value that points past the last element of a
|
| 92 |
corresponding sequence. These values are called *past-the-end* values.
|
| 93 |
Values of an iterator `i` for which the expression `*i` is defined are
|
| 94 |
called *dereferenceable*. The library never assumes that past-the-end
|
| 95 |
values are dereferenceable. Iterators can also have singular values that
|
| 96 |
+
are not associated with any sequence.
|
| 97 |
+
|
| 98 |
+
[*Example 1*: After the declaration of an uninitialized pointer `x` (as
|
| 99 |
+
with `int* x;`), `x` must always be assumed to have a singular value of
|
| 100 |
+
a pointer. — *end example*]
|
| 101 |
+
|
| 102 |
+
Results of most expressions are undefined for singular values; the only
|
| 103 |
+
exceptions are destroying an iterator that holds a singular value, the
|
| 104 |
+
assignment of a non-singular value to an iterator that holds a singular
|
| 105 |
+
value, and, for iterators that satisfy the `DefaultConstructible`
|
| 106 |
+
requirements, using a value-initialized iterator as the source of a copy
|
| 107 |
+
or move operation.
|
| 108 |
+
|
| 109 |
+
[*Note 3*: This guarantee is not offered for default-initialization,
|
| 110 |
+
although the distinction only matters for types with trivial default
|
| 111 |
+
constructors such as pointers or aggregates holding
|
| 112 |
+
pointers. — *end note*]
|
| 113 |
+
|
| 114 |
+
In these cases the singular value is overwritten the same way as any
|
| 115 |
+
other value. Dereferenceable values are always non-singular.
|
| 116 |
|
| 117 |
An iterator `j` is called *reachable* from an iterator `i` if and only
|
| 118 |
if there is a finite sequence of applications of the expression `++i`
|
| 119 |
that makes `i == j`. If `j` is reachable from `i`, they refer to
|
| 120 |
elements of the same sequence.
|
|
|
|
| 142 |
`const X`, `difference_type` and `reference` refer to the types
|
| 143 |
`iterator_traits<X>::difference_type` and
|
| 144 |
`iterator_traits<X>::reference`, respectively, `n` denotes a value of
|
| 145 |
`difference_type`, `u`, `tmp`, and `m` denote identifiers, `r` denotes a
|
| 146 |
value of `X&`, `t` denotes a value of value type `T`, `o` denotes a
|
| 147 |
+
value of some type that is writable to the output iterator.
|
| 148 |
+
|
| 149 |
+
[*Note 4*: For an iterator type `X` there must be an instantiation of
|
| 150 |
+
`iterator_traits<X>` ([[iterator.traits]]). — *end note*]
|
| 151 |
|
| 152 |
### Iterator <a id="iterator.iterators">[[iterator.iterators]]</a>
|
| 153 |
|
| 154 |
The `Iterator` requirements form the basis of the iterator concept
|
| 155 |
taxonomy; every iterator satisfies the `Iterator` requirements. This set
|
| 156 |
of requirements specifies operations for dereferencing and incrementing
|
| 157 |
an iterator. Most algorithms will require additional operations to
|
| 158 |
read ([[input.iterators]]) or write ([[output.iterators]]) values, or
|
| 159 |
to provide a richer set of iterator movements ([[forward.iterators]],
|
| 160 |
+
[[bidirectional.iterators]], [[random.access.iterators]]).
|
| 161 |
|
| 162 |
A type `X` satisfies the `Iterator` requirements if:
|
| 163 |
|
| 164 |
- `X` satisfies the `CopyConstructible`, `CopyAssignable`, and
|
| 165 |
`Destructible` requirements ([[utility.arg.requirements]]) and
|
|
|
|
| 168 |
have the indicated semantics.
|
| 169 |
|
| 170 |
### Input iterators <a id="input.iterators">[[input.iterators]]</a>
|
| 171 |
|
| 172 |
A class or pointer type `X` satisfies the requirements of an input
|
| 173 |
+
iterator for the value type `T` if `X` satisfies the `Iterator` (
|
| 174 |
[[iterator.iterators]]) and `EqualityComparable` (Table
|
| 175 |
+
[[tab:equalitycomparable]]) requirements and the expressions in Table
|
| 176 |
[[tab:iterator.input.requirements]] are valid and have the indicated
|
| 177 |
semantics.
|
| 178 |
|
| 179 |
In Table [[tab:iterator.input.requirements]], the term *the domain of
|
| 180 |
`==`* is used in the ordinary mathematical sense to denote the set of
|
| 181 |
values over which `==` is (required to be) defined. This set can change
|
| 182 |
over time. Each algorithm places additional requirements on the domain
|
| 183 |
of `==` for the iterator values it uses. These requirements can be
|
| 184 |
+
inferred from the uses that algorithm makes of `==` and `!=`.
|
|
|
|
|
|
|
|
|
|
| 185 |
|
| 186 |
+
[*Example 1*: The call `find(a,b,x)` is defined only if the value of
|
| 187 |
+
`a` has the property *p* defined as follows: `b` has property *p* and a
|
| 188 |
+
value `i` has property *p* if (`*i==x`) or if (`*i!=x` and `++i` has
|
| 189 |
+
property *p*). — *end example*]
|
| 190 |
+
|
| 191 |
+
[*Note 1*: For input iterators, `a == b` does not imply `++a == ++b`.
|
| 192 |
+
(Equality does not guarantee the substitution property or referential
|
| 193 |
transparency.) Algorithms on input iterators should never attempt to
|
| 194 |
pass through the same iterator twice. They should be *single pass*
|
| 195 |
+
algorithms. Value type `T` is not required to be a `CopyAssignable` type
|
| 196 |
+
(Table [[tab:copyassignable]]). These algorithms can be used with
|
| 197 |
+
istreams as the source of the input data through the `istream_iterator`
|
| 198 |
+
class template. — *end note*]
|
| 199 |
|
| 200 |
### Output iterators <a id="output.iterators">[[output.iterators]]</a>
|
| 201 |
|
| 202 |
A class or pointer type `X` satisfies the requirements of an output
|
| 203 |
iterator if `X` satisfies the `Iterator` requirements (
|
| 204 |
[[iterator.iterators]]) and the expressions in Table
|
| 205 |
[[tab:iterator.output.requirements]] are valid and have the indicated
|
| 206 |
semantics.
|
| 207 |
|
| 208 |
+
[*Note 1*: The only valid use of an `operator*` is on the left side of
|
| 209 |
+
the assignment statement. *Assignment through the same value of the
|
| 210 |
+
iterator happens only once.* Algorithms on output iterators should never
|
| 211 |
+
attempt to pass through the same iterator twice. They should be *single
|
| 212 |
+
pass* algorithms. Equality and inequality might not be defined.
|
| 213 |
+
Algorithms that take output iterators can be used with ostreams as the
|
| 214 |
+
destination for placing data through the `ostream_iterator` class as
|
| 215 |
+
well as with insert iterators and insert pointers. — *end note*]
|
| 216 |
|
| 217 |
### Forward iterators <a id="forward.iterators">[[forward.iterators]]</a>
|
| 218 |
|
| 219 |
A class or pointer type `X` satisfies the requirements of a forward
|
| 220 |
iterator if
|
| 221 |
|
| 222 |
- `X` satisfies the requirements of an input iterator (
|
| 223 |
[[input.iterators]]),
|
| 224 |
+
- `X` satisfies the `DefaultConstructible` requirements (
|
| 225 |
[[utility.arg.requirements]]),
|
| 226 |
- if `X` is a mutable iterator, `reference` is a reference to `T`; if
|
| 227 |
+
`X` is a constant iterator, `reference` is a reference to `const T`,
|
| 228 |
- the expressions in Table [[tab:iterator.forward.requirements]] are
|
| 229 |
valid and have the indicated semantics, and
|
| 230 |
- objects of type `X` offer the multi-pass guarantee, described below.
|
| 231 |
|
| 232 |
+
The domain of `==` for forward iterators is that of iterators over the
|
| 233 |
same underlying sequence. However, value-initialized iterators may be
|
| 234 |
compared and shall compare equal to other value-initialized iterators of
|
| 235 |
+
the same type.
|
| 236 |
+
|
| 237 |
+
[*Note 1*: Value-initialized iterators behave as if they refer past the
|
| 238 |
+
end of the same empty sequence. — *end note*]
|
| 239 |
|
| 240 |
Two dereferenceable iterators `a` and `b` of type `X` offer the
|
| 241 |
*multi-pass guarantee* if:
|
| 242 |
|
| 243 |
- `a == b` implies `++a == ++b` and
|
| 244 |
- `X` is a pointer type or the expression `(void)++X(a), *a` is
|
| 245 |
equivalent to the expression `*a`.
|
| 246 |
|
| 247 |
+
[*Note 2*: The requirement that `a == b` implies `++a == ++b` (which is
|
| 248 |
+
not true for input and output iterators) and the removal of the
|
| 249 |
+
restrictions on the number of the assignments through a mutable iterator
|
| 250 |
+
(which applies to output iterators) allows the use of multi-pass
|
| 251 |
+
one-directional algorithms with forward iterators. — *end note*]
|
| 252 |
|
| 253 |
If `a` and `b` are equal, then either `a` and `b` are both
|
| 254 |
dereferenceable or else neither is dereferenceable.
|
| 255 |
|
| 256 |
If `a` and `b` are both dereferenceable, then `a == b` if and only if
|
|
|
|
| 261 |
A class or pointer type `X` satisfies the requirements of a
|
| 262 |
bidirectional iterator if, in addition to satisfying the requirements
|
| 263 |
for forward iterators, the following expressions are valid as shown in
|
| 264 |
Table [[tab:iterator.bidirectional.requirements]].
|
| 265 |
|
| 266 |
+
[*Note 1*: Bidirectional iterators allow algorithms to move iterators
|
| 267 |
+
backward as well as forward. — *end note*]
|
| 268 |
|
| 269 |
### Random access iterators <a id="random.access.iterators">[[random.access.iterators]]</a>
|
| 270 |
|
| 271 |
A class or pointer type `X` satisfies the requirements of a random
|
| 272 |
access iterator if, in addition to satisfying the requirements for
|
|
|
|
| 275 |
|
| 276 |
## Header `<iterator>` synopsis <a id="iterator.synopsis">[[iterator.synopsis]]</a>
|
| 277 |
|
| 278 |
``` cpp
|
| 279 |
namespace std {
|
| 280 |
+
// [iterator.primitives], primitives
|
| 281 |
template<class Iterator> struct iterator_traits;
|
| 282 |
template<class T> struct iterator_traits<T*>;
|
| 283 |
+
template<class T> struct iterator_traits<const T*>;
|
|
|
|
|
|
|
| 284 |
|
| 285 |
struct input_iterator_tag { };
|
| 286 |
struct output_iterator_tag { };
|
| 287 |
struct forward_iterator_tag: public input_iterator_tag { };
|
| 288 |
struct bidirectional_iterator_tag: public forward_iterator_tag { };
|
| 289 |
struct random_access_iterator_tag: public bidirectional_iterator_tag { };
|
| 290 |
|
| 291 |
+
// [iterator.operations], iterator operations
|
| 292 |
template <class InputIterator, class Distance>
|
| 293 |
+
constexpr void advance(InputIterator& i, Distance n);
|
| 294 |
template <class InputIterator>
|
| 295 |
+
constexpr typename iterator_traits<InputIterator>::difference_type
|
| 296 |
distance(InputIterator first, InputIterator last);
|
| 297 |
+
template <class InputIterator>
|
| 298 |
+
constexpr InputIterator next(InputIterator x,
|
| 299 |
+
typename iterator_traits<InputIterator>::difference_type n = 1);
|
| 300 |
template <class BidirectionalIterator>
|
| 301 |
+
constexpr BidirectionalIterator prev(BidirectionalIterator x,
|
| 302 |
+
typename iterator_traits<BidirectionalIterator>::difference_type n = 1);
|
| 303 |
|
| 304 |
+
// [predef.iterators], predefined iterators
|
| 305 |
template <class Iterator> class reverse_iterator;
|
| 306 |
|
| 307 |
template <class Iterator1, class Iterator2>
|
| 308 |
+
constexpr bool operator==(
|
| 309 |
const reverse_iterator<Iterator1>& x,
|
| 310 |
const reverse_iterator<Iterator2>& y);
|
| 311 |
template <class Iterator1, class Iterator2>
|
| 312 |
+
constexpr bool operator<(
|
| 313 |
const reverse_iterator<Iterator1>& x,
|
| 314 |
const reverse_iterator<Iterator2>& y);
|
| 315 |
template <class Iterator1, class Iterator2>
|
| 316 |
+
constexpr bool operator!=(
|
| 317 |
const reverse_iterator<Iterator1>& x,
|
| 318 |
const reverse_iterator<Iterator2>& y);
|
| 319 |
template <class Iterator1, class Iterator2>
|
| 320 |
+
constexpr bool operator>(
|
| 321 |
const reverse_iterator<Iterator1>& x,
|
| 322 |
const reverse_iterator<Iterator2>& y);
|
| 323 |
template <class Iterator1, class Iterator2>
|
| 324 |
+
constexpr bool operator>=(
|
| 325 |
const reverse_iterator<Iterator1>& x,
|
| 326 |
const reverse_iterator<Iterator2>& y);
|
| 327 |
template <class Iterator1, class Iterator2>
|
| 328 |
+
constexpr bool operator<=(
|
| 329 |
const reverse_iterator<Iterator1>& x,
|
| 330 |
const reverse_iterator<Iterator2>& y);
|
| 331 |
|
| 332 |
template <class Iterator1, class Iterator2>
|
| 333 |
+
constexpr auto operator-(
|
| 334 |
const reverse_iterator<Iterator1>& x,
|
| 335 |
const reverse_iterator<Iterator2>& y) ->decltype(y.base() - x.base());
|
| 336 |
template <class Iterator>
|
| 337 |
+
constexpr reverse_iterator<Iterator>
|
| 338 |
operator+(
|
| 339 |
typename reverse_iterator<Iterator>::difference_type n,
|
| 340 |
const reverse_iterator<Iterator>& x);
|
| 341 |
|
| 342 |
template <class Iterator>
|
| 343 |
+
constexpr reverse_iterator<Iterator> make_reverse_iterator(Iterator i);
|
| 344 |
|
| 345 |
template <class Container> class back_insert_iterator;
|
| 346 |
template <class Container>
|
| 347 |
back_insert_iterator<Container> back_inserter(Container& x);
|
| 348 |
|
|
|
|
| 354 |
template <class Container>
|
| 355 |
insert_iterator<Container> inserter(Container& x, typename Container::iterator i);
|
| 356 |
|
| 357 |
template <class Iterator> class move_iterator;
|
| 358 |
template <class Iterator1, class Iterator2>
|
| 359 |
+
constexpr bool operator==(
|
| 360 |
const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 361 |
template <class Iterator1, class Iterator2>
|
| 362 |
+
constexpr bool operator!=(
|
| 363 |
const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 364 |
template <class Iterator1, class Iterator2>
|
| 365 |
+
constexpr bool operator<(
|
| 366 |
const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 367 |
template <class Iterator1, class Iterator2>
|
| 368 |
+
constexpr bool operator<=(
|
| 369 |
const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 370 |
template <class Iterator1, class Iterator2>
|
| 371 |
+
constexpr bool operator>(
|
| 372 |
const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 373 |
template <class Iterator1, class Iterator2>
|
| 374 |
+
constexpr bool operator>=(
|
| 375 |
const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 376 |
|
| 377 |
template <class Iterator1, class Iterator2>
|
| 378 |
+
constexpr auto operator-(
|
| 379 |
const move_iterator<Iterator1>& x,
|
| 380 |
const move_iterator<Iterator2>& y) -> decltype(x.base() - y.base());
|
| 381 |
template <class Iterator>
|
| 382 |
+
constexpr move_iterator<Iterator> operator+(
|
| 383 |
typename move_iterator<Iterator>::difference_type n, const move_iterator<Iterator>& x);
|
| 384 |
template <class Iterator>
|
| 385 |
+
constexpr move_iterator<Iterator> make_move_iterator(Iterator i);
|
| 386 |
|
| 387 |
+
// [stream.iterators], stream iterators
|
| 388 |
template <class T, class charT = char, class traits = char_traits<charT>,
|
| 389 |
class Distance = ptrdiff_t>
|
| 390 |
class istream_iterator;
|
| 391 |
template <class T, class charT, class traits, class Distance>
|
| 392 |
bool operator==(const istream_iterator<T,charT,traits,Distance>& x,
|
|
|
|
| 408 |
const istreambuf_iterator<charT,traits>& b);
|
| 409 |
|
| 410 |
template <class charT, class traits = char_traits<charT>>
|
| 411 |
class ostreambuf_iterator;
|
| 412 |
|
| 413 |
+
// [iterator.range], range access
|
| 414 |
+
template <class C> constexpr auto begin(C& c) -> decltype(c.begin());
|
| 415 |
+
template <class C> constexpr auto begin(const C& c) -> decltype(c.begin());
|
| 416 |
+
template <class C> constexpr auto end(C& c) -> decltype(c.end());
|
| 417 |
+
template <class C> constexpr auto end(const C& c) -> decltype(c.end());
|
| 418 |
template <class T, size_t N> constexpr T* begin(T (&array)[N]) noexcept;
|
| 419 |
template <class T, size_t N> constexpr T* end(T (&array)[N]) noexcept;
|
| 420 |
template <class C> constexpr auto cbegin(const C& c) noexcept(noexcept(std::begin(c)))
|
| 421 |
-> decltype(std::begin(c));
|
| 422 |
template <class C> constexpr auto cend(const C& c) noexcept(noexcept(std::end(c)))
|
| 423 |
-> decltype(std::end(c));
|
| 424 |
+
template <class C> constexpr auto rbegin(C& c) -> decltype(c.rbegin());
|
| 425 |
+
template <class C> constexpr auto rbegin(const C& c) -> decltype(c.rbegin());
|
| 426 |
+
template <class C> constexpr auto rend(C& c) -> decltype(c.rend());
|
| 427 |
+
template <class C> constexpr auto rend(const C& c) -> decltype(c.rend());
|
| 428 |
+
template <class T, size_t N> constexpr reverse_iterator<T*> rbegin(T (&array)[N]);
|
| 429 |
+
template <class T, size_t N> constexpr reverse_iterator<T*> rend(T (&array)[N]);
|
| 430 |
+
template <class E> constexpr reverse_iterator<const E*> rbegin(initializer_list<E> il);
|
| 431 |
+
template <class E> constexpr reverse_iterator<const E*> rend(initializer_list<E> il);
|
| 432 |
+
template <class C> constexpr auto crbegin(const C& c) -> decltype(std::rbegin(c));
|
| 433 |
+
template <class C> constexpr auto crend(const C& c) -> decltype(std::rend(c));
|
| 434 |
+
|
| 435 |
+
// [iterator.container], container access
|
| 436 |
+
template <class C> constexpr auto size(const C& c) -> decltype(c.size());
|
| 437 |
+
template <class T, size_t N> constexpr size_t size(const T (&array)[N]) noexcept;
|
| 438 |
+
template <class C> constexpr auto empty(const C& c) -> decltype(c.empty());
|
| 439 |
+
template <class T, size_t N> constexpr bool empty(const T (&array)[N]) noexcept;
|
| 440 |
+
template <class E> constexpr bool empty(initializer_list<E> il) noexcept;
|
| 441 |
+
template <class C> constexpr auto data(C& c) -> decltype(c.data());
|
| 442 |
+
template <class C> constexpr auto data(const C& c) -> decltype(c.data());
|
| 443 |
+
template <class T, size_t N> constexpr T* data(T (&array)[N]) noexcept;
|
| 444 |
+
template <class E> constexpr const E* data(initializer_list<E> il) noexcept;
|
| 445 |
}
|
| 446 |
```
|
| 447 |
|
| 448 |
## Iterator primitives <a id="iterator.primitives">[[iterator.primitives]]</a>
|
| 449 |
|
|
|
|
| 482 |
iterator_traits<Iterator>::pointer
|
| 483 |
```
|
| 484 |
|
| 485 |
may be defined as `void`.
|
| 486 |
|
| 487 |
+
If `Iterator` has valid ([[temp.deduct]]) member types
|
| 488 |
+
`difference_type`, `value_type`, `pointer`, `reference`, and
|
| 489 |
+
`iterator_category`, `iterator_traits<Iterator>` shall have the
|
| 490 |
+
following as publicly accessible members:
|
| 491 |
|
| 492 |
``` cpp
|
| 493 |
+
using difference_type = typename Iterator::difference_type;
|
| 494 |
+
using value_type = typename Iterator::value_type;
|
| 495 |
+
using pointer = typename Iterator::pointer;
|
| 496 |
+
using reference = typename Iterator::reference;
|
| 497 |
+
using iterator_category = typename Iterator::iterator_category;
|
|
|
|
|
|
|
|
|
|
|
|
|
| 498 |
```
|
| 499 |
|
| 500 |
+
Otherwise, `iterator_traits<Iterator>` shall have no members by any of
|
| 501 |
+
the above names.
|
| 502 |
+
|
| 503 |
It is specialized for pointers as
|
| 504 |
|
| 505 |
``` cpp
|
| 506 |
namespace std {
|
| 507 |
template<class T> struct iterator_traits<T*> {
|
| 508 |
+
using difference_type = ptrdiff_t;
|
| 509 |
+
using value_type = T;
|
| 510 |
+
using pointer = T*;
|
| 511 |
+
using reference = T&;
|
| 512 |
+
using iterator_category = random_access_iterator_tag;
|
| 513 |
};
|
| 514 |
}
|
| 515 |
```
|
| 516 |
|
| 517 |
and for pointers to const as
|
| 518 |
|
| 519 |
``` cpp
|
| 520 |
namespace std {
|
| 521 |
template<class T> struct iterator_traits<const T*> {
|
| 522 |
+
using difference_type = ptrdiff_t;
|
| 523 |
+
using value_type = T;
|
| 524 |
+
using pointer = const T*;
|
| 525 |
+
using reference = const T&;
|
| 526 |
+
using iterator_category = random_access_iterator_tag;
|
| 527 |
};
|
| 528 |
}
|
| 529 |
```
|
| 530 |
|
| 531 |
+
[*Example 1*:
|
| 532 |
+
|
| 533 |
To implement a generic `reverse` function, a C++program can do the
|
| 534 |
following:
|
| 535 |
|
| 536 |
``` cpp
|
| 537 |
template <class BidirectionalIterator>
|
|
|
|
| 547 |
n -= 2;
|
| 548 |
}
|
| 549 |
}
|
| 550 |
```
|
| 551 |
|
| 552 |
+
— *end example*]
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 553 |
|
| 554 |
### Standard iterator tags <a id="std.iterator.tags">[[std.iterator.tags]]</a>
|
| 555 |
|
| 556 |
It is often desirable for a function template specialization to find out
|
| 557 |
what is the most specific category of its iterator argument, so that the
|
|
|
|
| 572 |
struct bidirectional_iterator_tag: public forward_iterator_tag { };
|
| 573 |
struct random_access_iterator_tag: public bidirectional_iterator_tag { };
|
| 574 |
}
|
| 575 |
```
|
| 576 |
|
| 577 |
+
[*Example 1*:
|
| 578 |
+
|
| 579 |
For a program-defined iterator `BinaryTreeIterator`, it could be
|
| 580 |
included into the bidirectional iterator category by specializing the
|
| 581 |
`iterator_traits` template:
|
| 582 |
|
| 583 |
``` cpp
|
| 584 |
template<class T> struct iterator_traits<BinaryTreeIterator<T>> {
|
| 585 |
+
using iterator_category = bidirectional_iterator_tag;
|
| 586 |
+
using difference_type = ptrdiff_t;
|
| 587 |
+
using value_type = T;
|
| 588 |
+
using pointer = T*;
|
| 589 |
+
using reference = T&;
|
| 590 |
};
|
| 591 |
```
|
| 592 |
|
| 593 |
+
— *end example*]
|
| 594 |
+
|
| 595 |
+
[*Example 2*:
|
| 596 |
|
| 597 |
If `evolve()` is well defined for bidirectional iterators, but can be
|
| 598 |
implemented more efficiently for random access iterators, then the
|
| 599 |
implementation is as follows:
|
| 600 |
|
|
|
|
| 617 |
random_access_iterator_tag) {
|
| 618 |
// more efficient, but less generic algorithm
|
| 619 |
}
|
| 620 |
```
|
| 621 |
|
| 622 |
+
— *end example*]
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 623 |
|
| 624 |
### Iterator operations <a id="iterator.operations">[[iterator.operations]]</a>
|
| 625 |
|
| 626 |
Since only random access iterators provide `+` and `-` operators, the
|
| 627 |
library provides two function templates `advance` and `distance`. These
|
|
|
|
| 629 |
therefore, constant time for them); for input, forward and bidirectional
|
| 630 |
iterators they use `++` to provide linear time implementations.
|
| 631 |
|
| 632 |
``` cpp
|
| 633 |
template <class InputIterator, class Distance>
|
| 634 |
+
constexpr void advance(InputIterator& i, Distance n);
|
| 635 |
```
|
| 636 |
|
| 637 |
*Requires:* `n` shall be negative only for bidirectional and random
|
| 638 |
access iterators.
|
| 639 |
|
| 640 |
*Effects:* Increments (or decrements for negative `n`) iterator
|
| 641 |
reference `i` by `n`.
|
| 642 |
|
| 643 |
``` cpp
|
| 644 |
template <class InputIterator>
|
| 645 |
+
constexpr typename iterator_traits<InputIterator>::difference_type
|
| 646 |
distance(InputIterator first, InputIterator last);
|
| 647 |
```
|
| 648 |
|
| 649 |
*Effects:* If `InputIterator` meets the requirements of random access
|
| 650 |
iterator, returns `(last - first)`; otherwise, returns the number of
|
|
|
|
| 654 |
iterator, `last` shall be reachable from `first` or `first` shall be
|
| 655 |
reachable from `last`; otherwise, `last` shall be reachable from
|
| 656 |
`first`.
|
| 657 |
|
| 658 |
``` cpp
|
| 659 |
+
template <class InputIterator>
|
| 660 |
+
constexpr InputIterator next(InputIterator x,
|
| 661 |
+
typename iterator_traits<InputIterator>::difference_type n = 1);
|
| 662 |
```
|
| 663 |
|
| 664 |
+
*Effects:* Equivalent to: `advance(x, n); return x;`
|
| 665 |
|
| 666 |
``` cpp
|
| 667 |
template <class BidirectionalIterator>
|
| 668 |
+
constexpr BidirectionalIterator prev(BidirectionalIterator x,
|
| 669 |
+
typename iterator_traits<BidirectionalIterator>::difference_type n = 1);
|
| 670 |
```
|
| 671 |
|
| 672 |
+
*Effects:* Equivalent to: `advance(x, -n); return x;`
|
| 673 |
|
| 674 |
## Iterator adaptors <a id="predef.iterators">[[predef.iterators]]</a>
|
| 675 |
|
| 676 |
### Reverse iterators <a id="reverse.iterators">[[reverse.iterators]]</a>
|
| 677 |
|
|
|
|
| 684 |
#### Class template `reverse_iterator` <a id="reverse.iterator">[[reverse.iterator]]</a>
|
| 685 |
|
| 686 |
``` cpp
|
| 687 |
namespace std {
|
| 688 |
template <class Iterator>
|
| 689 |
+
class reverse_iterator {
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 690 |
public:
|
| 691 |
+
using iterator_type = Iterator;
|
| 692 |
+
using iterator_category = typename iterator_traits<Iterator>::iterator_category;
|
| 693 |
+
using value_type = typename iterator_traits<Iterator>::value_type;
|
| 694 |
+
using difference_type = typename iterator_traits<Iterator>::difference_type;
|
| 695 |
+
using pointer = typename iterator_traits<Iterator>::pointer;
|
| 696 |
+
using reference = typename iterator_traits<Iterator>::reference;
|
| 697 |
|
| 698 |
+
constexpr reverse_iterator();
|
| 699 |
+
constexpr explicit reverse_iterator(Iterator x);
|
| 700 |
+
template <class U> constexpr reverse_iterator(const reverse_iterator<U>& u);
|
| 701 |
+
template <class U> constexpr reverse_iterator& operator=(const reverse_iterator<U>& u);
|
| 702 |
|
| 703 |
+
constexpr Iterator base() const; // explicit
|
| 704 |
+
constexpr reference operator*() const;
|
| 705 |
+
constexpr pointer operator->() const;
|
| 706 |
|
| 707 |
+
constexpr reverse_iterator& operator++();
|
| 708 |
+
constexpr reverse_iterator operator++(int);
|
| 709 |
+
constexpr reverse_iterator& operator--();
|
| 710 |
+
constexpr reverse_iterator operator--(int);
|
| 711 |
|
| 712 |
+
constexpr reverse_iterator operator+ (difference_type n) const;
|
| 713 |
+
constexpr reverse_iterator& operator+=(difference_type n);
|
| 714 |
+
constexpr reverse_iterator operator- (difference_type n) const;
|
| 715 |
+
constexpr reverse_iterator& operator-=(difference_type n);
|
| 716 |
+
constexpr unspecified operator[](difference_type n) const;
|
| 717 |
protected:
|
| 718 |
Iterator current;
|
| 719 |
};
|
| 720 |
|
| 721 |
template <class Iterator1, class Iterator2>
|
| 722 |
+
constexpr bool operator==(
|
| 723 |
const reverse_iterator<Iterator1>& x,
|
| 724 |
const reverse_iterator<Iterator2>& y);
|
| 725 |
template <class Iterator1, class Iterator2>
|
| 726 |
+
constexpr bool operator<(
|
| 727 |
const reverse_iterator<Iterator1>& x,
|
| 728 |
const reverse_iterator<Iterator2>& y);
|
| 729 |
template <class Iterator1, class Iterator2>
|
| 730 |
+
constexpr bool operator!=(
|
| 731 |
const reverse_iterator<Iterator1>& x,
|
| 732 |
const reverse_iterator<Iterator2>& y);
|
| 733 |
template <class Iterator1, class Iterator2>
|
| 734 |
+
constexpr bool operator>(
|
| 735 |
const reverse_iterator<Iterator1>& x,
|
| 736 |
const reverse_iterator<Iterator2>& y);
|
| 737 |
template <class Iterator1, class Iterator2>
|
| 738 |
+
constexpr bool operator>=(
|
| 739 |
const reverse_iterator<Iterator1>& x,
|
| 740 |
const reverse_iterator<Iterator2>& y);
|
| 741 |
template <class Iterator1, class Iterator2>
|
| 742 |
+
constexpr bool operator<=(
|
| 743 |
const reverse_iterator<Iterator1>& x,
|
| 744 |
const reverse_iterator<Iterator2>& y);
|
| 745 |
template <class Iterator1, class Iterator2>
|
| 746 |
+
constexpr auto operator-(
|
| 747 |
const reverse_iterator<Iterator1>& x,
|
| 748 |
const reverse_iterator<Iterator2>& y) -> decltype(y.base() - x.base());
|
| 749 |
template <class Iterator>
|
| 750 |
+
constexpr reverse_iterator<Iterator> operator+(
|
| 751 |
typename reverse_iterator<Iterator>::difference_type n,
|
| 752 |
const reverse_iterator<Iterator>& x);
|
| 753 |
|
| 754 |
template <class Iterator>
|
| 755 |
+
constexpr reverse_iterator<Iterator> make_reverse_iterator(Iterator i);
|
| 756 |
}
|
| 757 |
```
|
| 758 |
|
| 759 |
#### `reverse_iterator` requirements <a id="reverse.iter.requirements">[[reverse.iter.requirements]]</a>
|
| 760 |
|
| 761 |
The template parameter `Iterator` shall meet all the requirements of a
|
| 762 |
Bidirectional Iterator ([[bidirectional.iterators]]).
|
| 763 |
|
| 764 |
+
Additionally, `Iterator` shall meet the requirements of a random access
|
| 765 |
+
iterator ([[random.access.iterators]]) if any of the members
|
| 766 |
`operator+` ([[reverse.iter.op+]]), `operator-` (
|
| 767 |
[[reverse.iter.op-]]), `operator+=` ([[reverse.iter.op+=]]),
|
| 768 |
`operator-=` ([[reverse.iter.op-=]]), `operator[]` (
|
| 769 |
+
[[reverse.iter.opindex]]), or the non-member operators `operator<` (
|
| 770 |
[[reverse.iter.op<]]), `operator>` ([[reverse.iter.op>]]),
|
| 771 |
`operator<=` ([[reverse.iter.op<=]]), `operator>=` (
|
| 772 |
[[reverse.iter.op>=]]), `operator-` ([[reverse.iter.opdiff]]) or
|
| 773 |
`operator+` ([[reverse.iter.opsum]]) are referenced in a way that
|
| 774 |
requires instantiation ([[temp.inst]]).
|
|
|
|
| 776 |
#### `reverse_iterator` operations <a id="reverse.iter.ops">[[reverse.iter.ops]]</a>
|
| 777 |
|
| 778 |
##### `reverse_iterator` constructor <a id="reverse.iter.cons">[[reverse.iter.cons]]</a>
|
| 779 |
|
| 780 |
``` cpp
|
| 781 |
+
constexpr reverse_iterator();
|
| 782 |
```
|
| 783 |
|
| 784 |
+
*Effects:* Value-initializes `current`. Iterator operations applied to
|
| 785 |
the resulting iterator have defined behavior if and only if the
|
| 786 |
corresponding operations are defined on a value-initialized iterator of
|
| 787 |
type `Iterator`.
|
| 788 |
|
| 789 |
``` cpp
|
| 790 |
+
constexpr explicit reverse_iterator(Iterator x);
|
| 791 |
```
|
| 792 |
|
| 793 |
*Effects:* Initializes `current` with `x`.
|
| 794 |
|
| 795 |
``` cpp
|
| 796 |
+
template <class U> constexpr reverse_iterator(const reverse_iterator<U>& u);
|
| 797 |
```
|
| 798 |
|
| 799 |
*Effects:* Initializes `current` with `u.current`.
|
| 800 |
|
| 801 |
##### `reverse_iterator::operator=` <a id="reverse.iter.op=">[[reverse.iter.op=]]</a>
|
| 802 |
|
| 803 |
``` cpp
|
| 804 |
template <class U>
|
| 805 |
+
constexpr reverse_iterator&
|
| 806 |
operator=(const reverse_iterator<U>& u);
|
| 807 |
```
|
| 808 |
|
| 809 |
*Effects:* Assigns `u.base()` to current.
|
| 810 |
|
| 811 |
*Returns:* `*this`.
|
| 812 |
|
| 813 |
##### Conversion <a id="reverse.iter.conv">[[reverse.iter.conv]]</a>
|
| 814 |
|
| 815 |
``` cpp
|
| 816 |
+
constexpr Iterator base() const; // explicit
|
| 817 |
```
|
| 818 |
|
| 819 |
*Returns:* `current`.
|
| 820 |
|
| 821 |
##### `operator*` <a id="reverse.iter.op.star">[[reverse.iter.op.star]]</a>
|
| 822 |
|
| 823 |
``` cpp
|
| 824 |
+
constexpr reference operator*() const;
|
| 825 |
```
|
| 826 |
|
| 827 |
+
*Effects:* As if by:
|
| 828 |
|
| 829 |
``` cpp
|
| 830 |
Iterator tmp = current;
|
| 831 |
return *--tmp;
|
| 832 |
```
|
| 833 |
|
| 834 |
##### `operator->` <a id="reverse.iter.opref">[[reverse.iter.opref]]</a>
|
| 835 |
|
| 836 |
``` cpp
|
| 837 |
+
constexpr pointer operator->() const;
|
| 838 |
```
|
| 839 |
|
| 840 |
+
*Returns:* `addressof(operator*())`.
|
| 841 |
|
| 842 |
##### `operator++` <a id="reverse.iter.op++">[[reverse.iter.op++]]</a>
|
| 843 |
|
| 844 |
``` cpp
|
| 845 |
+
constexpr reverse_iterator& operator++();
|
| 846 |
```
|
| 847 |
|
| 848 |
+
*Effects:* As if by: `current;`
|
| 849 |
|
| 850 |
*Returns:* `*this`.
|
| 851 |
|
| 852 |
``` cpp
|
| 853 |
+
constexpr reverse_iterator operator++(int);
|
| 854 |
```
|
| 855 |
|
| 856 |
+
*Effects:* As if by:
|
| 857 |
|
| 858 |
``` cpp
|
| 859 |
reverse_iterator tmp = *this;
|
| 860 |
--current;
|
| 861 |
return tmp;
|
| 862 |
```
|
| 863 |
|
| 864 |
\[reverse.iter.op\]`operator\dcr`
|
| 865 |
|
| 866 |
``` cpp
|
| 867 |
+
constexpr reverse_iterator& operator--();
|
| 868 |
```
|
| 869 |
|
| 870 |
+
*Effects:* As if by `++current`.
|
| 871 |
|
| 872 |
*Returns:* `*this`.
|
| 873 |
|
| 874 |
``` cpp
|
| 875 |
+
constexpr reverse_iterator operator--(int);
|
| 876 |
```
|
| 877 |
|
| 878 |
+
*Effects:* As if by:
|
| 879 |
|
| 880 |
``` cpp
|
| 881 |
reverse_iterator tmp = *this;
|
| 882 |
++current;
|
| 883 |
return tmp;
|
| 884 |
```
|
| 885 |
|
| 886 |
##### `operator+` <a id="reverse.iter.op+">[[reverse.iter.op+]]</a>
|
| 887 |
|
| 888 |
``` cpp
|
| 889 |
+
constexpr reverse_iterator operator+(difference_type n) const;
|
|
|
|
| 890 |
```
|
| 891 |
|
| 892 |
*Returns:* `reverse_iterator(current-n)`.
|
| 893 |
|
| 894 |
##### `operator+=` <a id="reverse.iter.op+=">[[reverse.iter.op+=]]</a>
|
| 895 |
|
| 896 |
``` cpp
|
| 897 |
+
constexpr reverse_iterator& operator+=(difference_type n);
|
|
|
|
| 898 |
```
|
| 899 |
|
| 900 |
+
*Effects:* As if by: `current -= n;`
|
| 901 |
|
| 902 |
*Returns:* `*this`.
|
| 903 |
|
| 904 |
##### `operator-` <a id="reverse.iter.op-">[[reverse.iter.op-]]</a>
|
| 905 |
|
| 906 |
``` cpp
|
| 907 |
+
constexpr reverse_iterator operator-(difference_type n) const;
|
|
|
|
| 908 |
```
|
| 909 |
|
| 910 |
*Returns:* `reverse_iterator(current+n)`.
|
| 911 |
|
| 912 |
##### `operator-=` <a id="reverse.iter.op-=">[[reverse.iter.op-=]]</a>
|
| 913 |
|
| 914 |
``` cpp
|
| 915 |
+
constexpr reverse_iterator& operator-=(difference_type n);
|
|
|
|
| 916 |
```
|
| 917 |
|
| 918 |
+
*Effects:* As if by: `current += n;`
|
| 919 |
|
| 920 |
*Returns:* `*this`.
|
| 921 |
|
| 922 |
##### `operator[]` <a id="reverse.iter.opindex">[[reverse.iter.opindex]]</a>
|
| 923 |
|
| 924 |
``` cpp
|
| 925 |
+
constexpr unspecified operator[](difference_type n) const;
|
|
|
|
| 926 |
```
|
| 927 |
|
| 928 |
*Returns:* `current[-n-1]`.
|
| 929 |
|
| 930 |
##### `operator==` <a id="reverse.iter.op==">[[reverse.iter.op==]]</a>
|
| 931 |
|
| 932 |
``` cpp
|
| 933 |
template <class Iterator1, class Iterator2>
|
| 934 |
+
constexpr bool operator==(
|
| 935 |
const reverse_iterator<Iterator1>& x,
|
| 936 |
const reverse_iterator<Iterator2>& y);
|
| 937 |
```
|
| 938 |
|
| 939 |
*Returns:* `x.current == y.current`.
|
| 940 |
|
| 941 |
##### `operator<` <a id="reverse.iter.op<">[[reverse.iter.op<]]</a>
|
| 942 |
|
| 943 |
``` cpp
|
| 944 |
template <class Iterator1, class Iterator2>
|
| 945 |
+
constexpr bool operator<(
|
| 946 |
const reverse_iterator<Iterator1>& x,
|
| 947 |
const reverse_iterator<Iterator2>& y);
|
| 948 |
```
|
| 949 |
|
| 950 |
*Returns:* `x.current > y.current`.
|
| 951 |
|
| 952 |
##### `operator!=` <a id="reverse.iter.op!=">[[reverse.iter.op!=]]</a>
|
| 953 |
|
| 954 |
``` cpp
|
| 955 |
template <class Iterator1, class Iterator2>
|
| 956 |
+
constexpr bool operator!=(
|
| 957 |
const reverse_iterator<Iterator1>& x,
|
| 958 |
const reverse_iterator<Iterator2>& y);
|
| 959 |
```
|
| 960 |
|
| 961 |
*Returns:* `x.current != y.current`.
|
| 962 |
|
| 963 |
##### `operator>` <a id="reverse.iter.op>">[[reverse.iter.op>]]</a>
|
| 964 |
|
| 965 |
``` cpp
|
| 966 |
template <class Iterator1, class Iterator2>
|
| 967 |
+
constexpr bool operator>(
|
| 968 |
const reverse_iterator<Iterator1>& x,
|
| 969 |
const reverse_iterator<Iterator2>& y);
|
| 970 |
```
|
| 971 |
|
| 972 |
*Returns:* `x.current < y.current`.
|
| 973 |
|
| 974 |
##### `operator>=` <a id="reverse.iter.op>=">[[reverse.iter.op>=]]</a>
|
| 975 |
|
| 976 |
``` cpp
|
| 977 |
template <class Iterator1, class Iterator2>
|
| 978 |
+
constexpr bool operator>=(
|
| 979 |
const reverse_iterator<Iterator1>& x,
|
| 980 |
const reverse_iterator<Iterator2>& y);
|
| 981 |
```
|
| 982 |
|
| 983 |
*Returns:* `x.current <= y.current`.
|
| 984 |
|
| 985 |
##### `operator<=` <a id="reverse.iter.op<=">[[reverse.iter.op<=]]</a>
|
| 986 |
|
| 987 |
``` cpp
|
| 988 |
template <class Iterator1, class Iterator2>
|
| 989 |
+
constexpr bool operator<=(
|
| 990 |
const reverse_iterator<Iterator1>& x,
|
| 991 |
const reverse_iterator<Iterator2>& y);
|
| 992 |
```
|
| 993 |
|
| 994 |
*Returns:* `x.current >= y.current`.
|
| 995 |
|
| 996 |
##### `operator-` <a id="reverse.iter.opdiff">[[reverse.iter.opdiff]]</a>
|
| 997 |
|
| 998 |
``` cpp
|
| 999 |
template <class Iterator1, class Iterator2>
|
| 1000 |
+
constexpr auto operator-(
|
| 1001 |
const reverse_iterator<Iterator1>& x,
|
| 1002 |
const reverse_iterator<Iterator2>& y) -> decltype(y.base() - x.base());
|
| 1003 |
```
|
| 1004 |
|
| 1005 |
*Returns:* `y.current - x.current`.
|
| 1006 |
|
| 1007 |
##### `operator+` <a id="reverse.iter.opsum">[[reverse.iter.opsum]]</a>
|
| 1008 |
|
| 1009 |
``` cpp
|
| 1010 |
template <class Iterator>
|
| 1011 |
+
constexpr reverse_iterator<Iterator> operator+(
|
| 1012 |
typename reverse_iterator<Iterator>::difference_type n,
|
| 1013 |
const reverse_iterator<Iterator>& x);
|
| 1014 |
```
|
| 1015 |
|
| 1016 |
*Returns:* `reverse_iterator<Iterator> (x.current - n)`.
|
| 1017 |
|
| 1018 |
##### Non-member function `make_reverse_iterator()` <a id="reverse.iter.make">[[reverse.iter.make]]</a>
|
| 1019 |
|
| 1020 |
``` cpp
|
| 1021 |
template <class Iterator>
|
| 1022 |
+
constexpr reverse_iterator<Iterator> make_reverse_iterator(Iterator i);
|
| 1023 |
```
|
| 1024 |
|
| 1025 |
*Returns:* `reverse_iterator<Iterator>(i)`.
|
| 1026 |
|
| 1027 |
### Insert iterators <a id="insert.iterators">[[insert.iterators]]</a>
|
|
|
|
| 1058 |
#### Class template `back_insert_iterator` <a id="back.insert.iterator">[[back.insert.iterator]]</a>
|
| 1059 |
|
| 1060 |
``` cpp
|
| 1061 |
namespace std {
|
| 1062 |
template <class Container>
|
| 1063 |
+
class back_insert_iterator {
|
|
|
|
| 1064 |
protected:
|
| 1065 |
Container* container;
|
| 1066 |
|
| 1067 |
public:
|
| 1068 |
+
using iterator_category = output_iterator_tag;
|
| 1069 |
+
using value_type = void;
|
| 1070 |
+
using difference_type = void;
|
| 1071 |
+
using pointer = void;
|
| 1072 |
+
using reference = void;
|
| 1073 |
+
using container_type = Container;
|
| 1074 |
+
|
| 1075 |
explicit back_insert_iterator(Container& x);
|
| 1076 |
+
back_insert_iterator& operator=(const typename Container::value_type& value);
|
| 1077 |
+
back_insert_iterator& operator=(typename Container::value_type&& value);
|
|
|
|
|
|
|
| 1078 |
|
| 1079 |
+
back_insert_iterator& operator*();
|
| 1080 |
+
back_insert_iterator& operator++();
|
| 1081 |
+
back_insert_iterator operator++(int);
|
| 1082 |
};
|
| 1083 |
|
| 1084 |
template <class Container>
|
| 1085 |
back_insert_iterator<Container> back_inserter(Container& x);
|
| 1086 |
}
|
|
|
|
| 1092 |
|
| 1093 |
``` cpp
|
| 1094 |
explicit back_insert_iterator(Container& x);
|
| 1095 |
```
|
| 1096 |
|
| 1097 |
+
*Effects:* Initializes `container` with `addressof(x)`.
|
| 1098 |
|
| 1099 |
##### `back_insert_iterator::operator=` <a id="back.insert.iter.op=">[[back.insert.iter.op=]]</a>
|
| 1100 |
|
| 1101 |
``` cpp
|
| 1102 |
+
back_insert_iterator& operator=(const typename Container::value_type& value);
|
|
|
|
| 1103 |
```
|
| 1104 |
|
| 1105 |
+
*Effects:* As if by: `container->push_back(value);`
|
| 1106 |
|
| 1107 |
*Returns:* `*this`.
|
| 1108 |
|
| 1109 |
``` cpp
|
| 1110 |
+
back_insert_iterator& operator=(typename Container::value_type&& value);
|
|
|
|
| 1111 |
```
|
| 1112 |
|
| 1113 |
+
*Effects:* As if by: `container->push_back(std::move(value));`
|
| 1114 |
|
| 1115 |
*Returns:* `*this`.
|
| 1116 |
|
| 1117 |
##### `back_insert_iterator::operator*` <a id="back.insert.iter.op*">[[back.insert.iter.op*]]</a>
|
| 1118 |
|
| 1119 |
``` cpp
|
| 1120 |
+
back_insert_iterator& operator*();
|
| 1121 |
```
|
| 1122 |
|
| 1123 |
*Returns:* `*this`.
|
| 1124 |
|
| 1125 |
##### `back_insert_iterator::operator++` <a id="back.insert.iter.op++">[[back.insert.iter.op++]]</a>
|
| 1126 |
|
| 1127 |
``` cpp
|
| 1128 |
+
back_insert_iterator& operator++();
|
| 1129 |
+
back_insert_iterator operator++(int);
|
| 1130 |
```
|
| 1131 |
|
| 1132 |
*Returns:* `*this`.
|
| 1133 |
|
| 1134 |
##### `back_inserter` <a id="back.inserter">[[back.inserter]]</a>
|
|
|
|
| 1143 |
#### Class template `front_insert_iterator` <a id="front.insert.iterator">[[front.insert.iterator]]</a>
|
| 1144 |
|
| 1145 |
``` cpp
|
| 1146 |
namespace std {
|
| 1147 |
template <class Container>
|
| 1148 |
+
class front_insert_iterator {
|
|
|
|
| 1149 |
protected:
|
| 1150 |
Container* container;
|
| 1151 |
|
| 1152 |
public:
|
| 1153 |
+
using iterator_category = output_iterator_tag;
|
| 1154 |
+
using value_type = void;
|
| 1155 |
+
using difference_type = void;
|
| 1156 |
+
using pointer = void;
|
| 1157 |
+
using reference = void;
|
| 1158 |
+
using container_type = Container;
|
| 1159 |
+
|
| 1160 |
explicit front_insert_iterator(Container& x);
|
| 1161 |
+
front_insert_iterator& operator=(const typename Container::value_type& value);
|
| 1162 |
+
front_insert_iterator& operator=(typename Container::value_type&& value);
|
|
|
|
|
|
|
| 1163 |
|
| 1164 |
+
front_insert_iterator& operator*();
|
| 1165 |
+
front_insert_iterator& operator++();
|
| 1166 |
+
front_insert_iterator operator++(int);
|
| 1167 |
};
|
| 1168 |
|
| 1169 |
template <class Container>
|
| 1170 |
front_insert_iterator<Container> front_inserter(Container& x);
|
| 1171 |
}
|
|
|
|
| 1177 |
|
| 1178 |
``` cpp
|
| 1179 |
explicit front_insert_iterator(Container& x);
|
| 1180 |
```
|
| 1181 |
|
| 1182 |
+
*Effects:* Initializes `container` with `addressof(x)`.
|
| 1183 |
|
| 1184 |
##### `front_insert_iterator::operator=` <a id="front.insert.iter.op=">[[front.insert.iter.op=]]</a>
|
| 1185 |
|
| 1186 |
``` cpp
|
| 1187 |
+
front_insert_iterator& operator=(const typename Container::value_type& value);
|
|
|
|
| 1188 |
```
|
| 1189 |
|
| 1190 |
+
*Effects:* As if by: `container->push_front(value);`
|
| 1191 |
|
| 1192 |
*Returns:* `*this`.
|
| 1193 |
|
| 1194 |
``` cpp
|
| 1195 |
+
front_insert_iterator& operator=(typename Container::value_type&& value);
|
|
|
|
| 1196 |
```
|
| 1197 |
|
| 1198 |
+
*Effects:* As if by: `container->push_front(std::move(value));`
|
| 1199 |
|
| 1200 |
*Returns:* `*this`.
|
| 1201 |
|
| 1202 |
##### `front_insert_iterator::operator*` <a id="front.insert.iter.op*">[[front.insert.iter.op*]]</a>
|
| 1203 |
|
| 1204 |
``` cpp
|
| 1205 |
+
front_insert_iterator& operator*();
|
| 1206 |
```
|
| 1207 |
|
| 1208 |
*Returns:* `*this`.
|
| 1209 |
|
| 1210 |
##### `front_insert_iterator::operator++` <a id="front.insert.iter.op++">[[front.insert.iter.op++]]</a>
|
| 1211 |
|
| 1212 |
``` cpp
|
| 1213 |
+
front_insert_iterator& operator++();
|
| 1214 |
+
front_insert_iterator operator++(int);
|
| 1215 |
```
|
| 1216 |
|
| 1217 |
*Returns:* `*this`.
|
| 1218 |
|
| 1219 |
##### `front_inserter` <a id="front.inserter">[[front.inserter]]</a>
|
|
|
|
| 1228 |
#### Class template `insert_iterator` <a id="insert.iterator">[[insert.iterator]]</a>
|
| 1229 |
|
| 1230 |
``` cpp
|
| 1231 |
namespace std {
|
| 1232 |
template <class Container>
|
| 1233 |
+
class insert_iterator {
|
|
|
|
| 1234 |
protected:
|
| 1235 |
Container* container;
|
| 1236 |
typename Container::iterator iter;
|
| 1237 |
|
| 1238 |
public:
|
| 1239 |
+
using iterator_category = output_iterator_tag;
|
| 1240 |
+
using value_type = void;
|
| 1241 |
+
using difference_type = void;
|
| 1242 |
+
using pointer = void;
|
| 1243 |
+
using reference = void;
|
| 1244 |
+
using container_type = Container;
|
| 1245 |
+
|
| 1246 |
insert_iterator(Container& x, typename Container::iterator i);
|
| 1247 |
+
insert_iterator& operator=(const typename Container::value_type& value);
|
| 1248 |
+
insert_iterator& operator=(typename Container::value_type&& value);
|
|
|
|
|
|
|
| 1249 |
|
| 1250 |
+
insert_iterator& operator*();
|
| 1251 |
+
insert_iterator& operator++();
|
| 1252 |
+
insert_iterator& operator++(int);
|
| 1253 |
};
|
| 1254 |
|
| 1255 |
template <class Container>
|
| 1256 |
insert_iterator<Container> inserter(Container& x, typename Container::iterator i);
|
| 1257 |
}
|
|
|
|
| 1263 |
|
| 1264 |
``` cpp
|
| 1265 |
insert_iterator(Container& x, typename Container::iterator i);
|
| 1266 |
```
|
| 1267 |
|
| 1268 |
+
*Effects:* Initializes `container` with `addressof(x)` and `iter` with
|
| 1269 |
+
`i`.
|
| 1270 |
|
| 1271 |
##### `insert_iterator::operator=` <a id="insert.iter.op=">[[insert.iter.op=]]</a>
|
| 1272 |
|
| 1273 |
``` cpp
|
| 1274 |
+
insert_iterator& operator=(const typename Container::value_type& value);
|
|
|
|
| 1275 |
```
|
| 1276 |
|
| 1277 |
+
*Effects:* As if by:
|
| 1278 |
|
| 1279 |
``` cpp
|
| 1280 |
iter = container->insert(iter, value);
|
| 1281 |
++iter;
|
| 1282 |
```
|
| 1283 |
|
| 1284 |
*Returns:* `*this`.
|
| 1285 |
|
| 1286 |
``` cpp
|
| 1287 |
+
insert_iterator& operator=(typename Container::value_type&& value);
|
|
|
|
| 1288 |
```
|
| 1289 |
|
| 1290 |
+
*Effects:* As if by:
|
| 1291 |
|
| 1292 |
``` cpp
|
| 1293 |
iter = container->insert(iter, std::move(value));
|
| 1294 |
++iter;
|
| 1295 |
```
|
|
|
|
| 1297 |
*Returns:* `*this`.
|
| 1298 |
|
| 1299 |
##### `insert_iterator::operator*` <a id="insert.iter.op*">[[insert.iter.op*]]</a>
|
| 1300 |
|
| 1301 |
``` cpp
|
| 1302 |
+
insert_iterator& operator*();
|
| 1303 |
```
|
| 1304 |
|
| 1305 |
*Returns:* `*this`.
|
| 1306 |
|
| 1307 |
##### `insert_iterator::operator++` <a id="insert.iter.op++">[[insert.iter.op++]]</a>
|
| 1308 |
|
| 1309 |
``` cpp
|
| 1310 |
+
insert_iterator& operator++();
|
| 1311 |
+
insert_iterator& operator++(int);
|
| 1312 |
```
|
| 1313 |
|
| 1314 |
*Returns:* `*this`.
|
| 1315 |
|
| 1316 |
##### `inserter` <a id="inserter">[[inserter]]</a>
|
|
|
|
| 1325 |
### Move iterators <a id="move.iterators">[[move.iterators]]</a>
|
| 1326 |
|
| 1327 |
Class template `move_iterator` is an iterator adaptor with the same
|
| 1328 |
behavior as the underlying iterator except that its indirection operator
|
| 1329 |
implicitly converts the value returned by the underlying iterator’s
|
| 1330 |
+
indirection operator to an rvalue. Some generic algorithms can be called
|
| 1331 |
+
with move iterators to replace copying with moving.
|
| 1332 |
+
|
| 1333 |
+
[*Example 1*:
|
| 1334 |
|
| 1335 |
``` cpp
|
| 1336 |
list<string> s;
|
| 1337 |
// populate the list s
|
| 1338 |
vector<string> v1(s.begin(), s.end()); // copies strings into v1
|
| 1339 |
vector<string> v2(make_move_iterator(s.begin()),
|
| 1340 |
make_move_iterator(s.end())); // moves strings into v2
|
| 1341 |
```
|
| 1342 |
|
| 1343 |
+
— *end example*]
|
| 1344 |
+
|
| 1345 |
#### Class template `move_iterator` <a id="move.iterator">[[move.iterator]]</a>
|
| 1346 |
|
| 1347 |
``` cpp
|
| 1348 |
namespace std {
|
| 1349 |
template <class Iterator>
|
| 1350 |
class move_iterator {
|
| 1351 |
public:
|
| 1352 |
+
using iterator_type = Iterator;
|
| 1353 |
+
using iterator_category = typename iterator_traits<Iterator>::iterator_category;
|
| 1354 |
+
using value_type = typename iterator_traits<Iterator>::value_type;
|
| 1355 |
+
using difference_type = typename iterator_traits<Iterator>::difference_type;
|
| 1356 |
+
using pointer = Iterator;
|
| 1357 |
+
using reference = see below;
|
| 1358 |
|
| 1359 |
+
constexpr move_iterator();
|
| 1360 |
+
constexpr explicit move_iterator(Iterator i);
|
| 1361 |
+
template <class U> constexpr move_iterator(const move_iterator<U>& u);
|
| 1362 |
+
template <class U> constexpr move_iterator& operator=(const move_iterator<U>& u);
|
| 1363 |
|
| 1364 |
+
constexpr iterator_type base() const;
|
| 1365 |
+
constexpr reference operator*() const;
|
| 1366 |
+
constexpr pointer operator->() const;
|
| 1367 |
|
| 1368 |
+
constexpr move_iterator& operator++();
|
| 1369 |
+
constexpr move_iterator operator++(int);
|
| 1370 |
+
constexpr move_iterator& operator--();
|
| 1371 |
+
constexpr move_iterator operator--(int);
|
| 1372 |
|
| 1373 |
+
constexpr move_iterator operator+(difference_type n) const;
|
| 1374 |
+
constexpr move_iterator& operator+=(difference_type n);
|
| 1375 |
+
constexpr move_iterator operator-(difference_type n) const;
|
| 1376 |
+
constexpr move_iterator& operator-=(difference_type n);
|
| 1377 |
+
constexpr unspecified operator[](difference_type n) const;
|
| 1378 |
|
| 1379 |
private:
|
| 1380 |
Iterator current; // exposition only
|
| 1381 |
};
|
| 1382 |
|
| 1383 |
template <class Iterator1, class Iterator2>
|
| 1384 |
+
constexpr bool operator==(
|
| 1385 |
const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 1386 |
template <class Iterator1, class Iterator2>
|
| 1387 |
+
constexpr bool operator!=(
|
| 1388 |
const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 1389 |
template <class Iterator1, class Iterator2>
|
| 1390 |
+
constexpr bool operator<(
|
| 1391 |
const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 1392 |
template <class Iterator1, class Iterator2>
|
| 1393 |
+
constexpr bool operator<=(
|
| 1394 |
const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 1395 |
template <class Iterator1, class Iterator2>
|
| 1396 |
+
constexpr bool operator>(
|
| 1397 |
const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 1398 |
template <class Iterator1, class Iterator2>
|
| 1399 |
+
constexpr bool operator>=(
|
| 1400 |
const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 1401 |
|
| 1402 |
template <class Iterator1, class Iterator2>
|
| 1403 |
+
constexpr auto operator-(
|
| 1404 |
const move_iterator<Iterator1>& x,
|
| 1405 |
const move_iterator<Iterator2>& y) -> decltype(x.base() - y.base());
|
| 1406 |
template <class Iterator>
|
| 1407 |
+
constexpr move_iterator<Iterator> operator+(
|
| 1408 |
typename move_iterator<Iterator>::difference_type n, const move_iterator<Iterator>& x);
|
| 1409 |
template <class Iterator>
|
| 1410 |
+
constexpr move_iterator<Iterator> make_move_iterator(Iterator i);
|
| 1411 |
}
|
| 1412 |
```
|
| 1413 |
|
| 1414 |
+
Let `R` denote `iterator_traits<Iterator>::reference`. If
|
| 1415 |
+
`is_reference_v<R>` is `true`, the template specialization
|
| 1416 |
+
`move_iterator<Iterator>` shall define the nested type named `reference`
|
| 1417 |
+
as a synonym for `remove_reference_t<R>&&`, otherwise as a synonym for
|
| 1418 |
+
`R`.
|
| 1419 |
+
|
| 1420 |
#### `move_iterator` requirements <a id="move.iter.requirements">[[move.iter.requirements]]</a>
|
| 1421 |
|
| 1422 |
+
The template parameter `Iterator` shall meet the requirements of an
|
| 1423 |
+
input iterator ([[input.iterators]]). Additionally, if any of the
|
| 1424 |
bidirectional or random access traversal functions are instantiated, the
|
| 1425 |
template parameter shall meet the requirements for a Bidirectional
|
| 1426 |
Iterator ([[bidirectional.iterators]]) or a Random Access Iterator (
|
| 1427 |
[[random.access.iterators]]), respectively.
|
| 1428 |
|
| 1429 |
#### `move_iterator` operations <a id="move.iter.ops">[[move.iter.ops]]</a>
|
| 1430 |
|
| 1431 |
##### `move_iterator` constructors <a id="move.iter.op.const">[[move.iter.op.const]]</a>
|
| 1432 |
|
| 1433 |
``` cpp
|
| 1434 |
+
constexpr move_iterator();
|
| 1435 |
```
|
| 1436 |
|
| 1437 |
+
*Effects:* Constructs a `move_iterator`, value-initializing `current`.
|
| 1438 |
Iterator operations applied to the resulting iterator have defined
|
| 1439 |
behavior if and only if the corresponding operations are defined on a
|
| 1440 |
value-initialized iterator of type `Iterator`.
|
| 1441 |
|
| 1442 |
``` cpp
|
| 1443 |
+
constexpr explicit move_iterator(Iterator i);
|
| 1444 |
```
|
| 1445 |
|
| 1446 |
*Effects:* Constructs a `move_iterator`, initializing `current` with
|
| 1447 |
`i`.
|
| 1448 |
|
| 1449 |
``` cpp
|
| 1450 |
+
template <class U> constexpr move_iterator(const move_iterator<U>& u);
|
| 1451 |
```
|
| 1452 |
|
| 1453 |
*Effects:* Constructs a `move_iterator`, initializing `current` with
|
| 1454 |
`u.base()`.
|
| 1455 |
|
| 1456 |
*Requires:* `U` shall be convertible to `Iterator`.
|
| 1457 |
|
| 1458 |
##### `move_iterator::operator=` <a id="move.iter.op=">[[move.iter.op=]]</a>
|
| 1459 |
|
| 1460 |
``` cpp
|
| 1461 |
+
template <class U> constexpr move_iterator& operator=(const move_iterator<U>& u);
|
| 1462 |
```
|
| 1463 |
|
| 1464 |
*Effects:* Assigns `u.base()` to `current`.
|
| 1465 |
|
| 1466 |
*Requires:* `U` shall be convertible to `Iterator`.
|
| 1467 |
|
| 1468 |
##### `move_iterator` conversion <a id="move.iter.op.conv">[[move.iter.op.conv]]</a>
|
| 1469 |
|
| 1470 |
``` cpp
|
| 1471 |
+
constexpr Iterator base() const;
|
| 1472 |
```
|
| 1473 |
|
| 1474 |
*Returns:* `current`.
|
| 1475 |
|
| 1476 |
##### `move_iterator::operator*` <a id="move.iter.op.star">[[move.iter.op.star]]</a>
|
| 1477 |
|
| 1478 |
``` cpp
|
| 1479 |
+
constexpr reference operator*() const;
|
| 1480 |
```
|
| 1481 |
|
| 1482 |
+
*Returns:* `static_cast<reference>(*current)`.
|
| 1483 |
|
| 1484 |
##### `move_iterator::operator->` <a id="move.iter.op.ref">[[move.iter.op.ref]]</a>
|
| 1485 |
|
| 1486 |
``` cpp
|
| 1487 |
+
constexpr pointer operator->() const;
|
| 1488 |
```
|
| 1489 |
|
| 1490 |
*Returns:* `current`.
|
| 1491 |
|
| 1492 |
##### `move_iterator::operator++` <a id="move.iter.op.incr">[[move.iter.op.incr]]</a>
|
| 1493 |
|
| 1494 |
``` cpp
|
| 1495 |
+
constexpr move_iterator& operator++();
|
| 1496 |
```
|
| 1497 |
|
| 1498 |
+
*Effects:* As if by `++current`.
|
| 1499 |
|
| 1500 |
*Returns:* `*this`.
|
| 1501 |
|
| 1502 |
``` cpp
|
| 1503 |
+
constexpr move_iterator operator++(int);
|
| 1504 |
```
|
| 1505 |
|
| 1506 |
+
*Effects:* As if by:
|
| 1507 |
|
| 1508 |
``` cpp
|
| 1509 |
move_iterator tmp = *this;
|
| 1510 |
++current;
|
| 1511 |
return tmp;
|
| 1512 |
```
|
| 1513 |
|
| 1514 |
##### `move_iterator::operator-{-}` <a id="move.iter.op.decr">[[move.iter.op.decr]]</a>
|
| 1515 |
|
| 1516 |
``` cpp
|
| 1517 |
+
constexpr move_iterator& operator--();
|
| 1518 |
```
|
| 1519 |
|
| 1520 |
+
*Effects:* As if by `current`.
|
| 1521 |
|
| 1522 |
*Returns:* `*this`.
|
| 1523 |
|
| 1524 |
``` cpp
|
| 1525 |
+
constexpr move_iterator operator--(int);
|
| 1526 |
```
|
| 1527 |
|
| 1528 |
+
*Effects:* As if by:
|
| 1529 |
|
| 1530 |
``` cpp
|
| 1531 |
move_iterator tmp = *this;
|
| 1532 |
--current;
|
| 1533 |
return tmp;
|
| 1534 |
```
|
| 1535 |
|
| 1536 |
##### `move_iterator::operator+` <a id="move.iter.op.+">[[move.iter.op.+]]</a>
|
| 1537 |
|
| 1538 |
``` cpp
|
| 1539 |
+
constexpr move_iterator operator+(difference_type n) const;
|
| 1540 |
```
|
| 1541 |
|
| 1542 |
*Returns:* `move_iterator(current + n)`.
|
| 1543 |
|
| 1544 |
##### `move_iterator::operator+=` <a id="move.iter.op.+=">[[move.iter.op.+=]]</a>
|
| 1545 |
|
| 1546 |
``` cpp
|
| 1547 |
+
constexpr move_iterator& operator+=(difference_type n);
|
| 1548 |
```
|
| 1549 |
|
| 1550 |
+
*Effects:* As if by: `current += n;`
|
| 1551 |
|
| 1552 |
*Returns:* `*this`.
|
| 1553 |
|
| 1554 |
##### `move_iterator::operator-` <a id="move.iter.op.-">[[move.iter.op.-]]</a>
|
| 1555 |
|
| 1556 |
``` cpp
|
| 1557 |
+
constexpr move_iterator operator-(difference_type n) const;
|
| 1558 |
```
|
| 1559 |
|
| 1560 |
*Returns:* `move_iterator(current - n)`.
|
| 1561 |
|
| 1562 |
##### `move_iterator::operator-=` <a id="move.iter.op.-=">[[move.iter.op.-=]]</a>
|
| 1563 |
|
| 1564 |
``` cpp
|
| 1565 |
+
constexpr move_iterator& operator-=(difference_type n);
|
| 1566 |
```
|
| 1567 |
|
| 1568 |
+
*Effects:* As if by: `current -= n;`
|
| 1569 |
|
| 1570 |
*Returns:* `*this`.
|
| 1571 |
|
| 1572 |
##### `move_iterator::operator[]` <a id="move.iter.op.index">[[move.iter.op.index]]</a>
|
| 1573 |
|
| 1574 |
``` cpp
|
| 1575 |
+
constexpr unspecified operator[](difference_type n) const;
|
| 1576 |
```
|
| 1577 |
|
| 1578 |
+
*Returns:* `std::move(current[n])`.
|
| 1579 |
|
| 1580 |
##### `move_iterator` comparisons <a id="move.iter.op.comp">[[move.iter.op.comp]]</a>
|
| 1581 |
|
| 1582 |
``` cpp
|
| 1583 |
template <class Iterator1, class Iterator2>
|
| 1584 |
+
constexpr bool operator==(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 1585 |
```
|
| 1586 |
|
| 1587 |
*Returns:* `x.base() == y.base()`.
|
| 1588 |
|
| 1589 |
``` cpp
|
| 1590 |
template <class Iterator1, class Iterator2>
|
| 1591 |
+
constexpr bool operator!=(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 1592 |
```
|
| 1593 |
|
| 1594 |
*Returns:* `!(x == y)`.
|
| 1595 |
|
| 1596 |
``` cpp
|
| 1597 |
template <class Iterator1, class Iterator2>
|
| 1598 |
+
constexpr bool operator<(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 1599 |
```
|
| 1600 |
|
| 1601 |
*Returns:* `x.base() < y.base()`.
|
| 1602 |
|
| 1603 |
``` cpp
|
| 1604 |
template <class Iterator1, class Iterator2>
|
| 1605 |
+
constexpr bool operator<=(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 1606 |
```
|
| 1607 |
|
| 1608 |
*Returns:* `!(y < x)`.
|
| 1609 |
|
| 1610 |
``` cpp
|
| 1611 |
template <class Iterator1, class Iterator2>
|
| 1612 |
+
constexpr bool operator>(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 1613 |
```
|
| 1614 |
|
| 1615 |
*Returns:* `y < x`.
|
| 1616 |
|
| 1617 |
``` cpp
|
| 1618 |
template <class Iterator1, class Iterator2>
|
| 1619 |
+
constexpr bool operator>=(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 1620 |
```
|
| 1621 |
|
| 1622 |
*Returns:* `!(x < y)`.
|
| 1623 |
|
| 1624 |
##### `move_iterator` non-member functions <a id="move.iter.nonmember">[[move.iter.nonmember]]</a>
|
| 1625 |
|
| 1626 |
``` cpp
|
| 1627 |
template <class Iterator1, class Iterator2>
|
| 1628 |
+
constexpr auto operator-(
|
| 1629 |
const move_iterator<Iterator1>& x,
|
| 1630 |
const move_iterator<Iterator2>& y) -> decltype(x.base() - y.base());
|
| 1631 |
```
|
| 1632 |
|
| 1633 |
*Returns:* `x.base() - y.base()`.
|
| 1634 |
|
| 1635 |
``` cpp
|
| 1636 |
template <class Iterator>
|
| 1637 |
+
constexpr move_iterator<Iterator> operator+(
|
| 1638 |
typename move_iterator<Iterator>::difference_type n, const move_iterator<Iterator>& x);
|
| 1639 |
```
|
| 1640 |
|
| 1641 |
*Returns:* `x + n`.
|
| 1642 |
|
| 1643 |
``` cpp
|
| 1644 |
template <class Iterator>
|
| 1645 |
+
constexpr move_iterator<Iterator> make_move_iterator(Iterator i);
|
| 1646 |
```
|
| 1647 |
|
| 1648 |
*Returns:* `move_iterator<Iterator>(i)`.
|
| 1649 |
|
| 1650 |
## Stream iterators <a id="stream.iterators">[[stream.iterators]]</a>
|
| 1651 |
|
| 1652 |
To make it possible for algorithmic templates to work directly with
|
| 1653 |
input/output streams, appropriate iterator-like class templates are
|
| 1654 |
provided.
|
| 1655 |
|
| 1656 |
+
[*Example 1*:
|
| 1657 |
+
|
| 1658 |
``` cpp
|
| 1659 |
partial_sum(istream_iterator<double, char>(cin),
|
| 1660 |
istream_iterator<double, char>(),
|
| 1661 |
ostream_iterator<double, char>(cout, "\n"));
|
| 1662 |
```
|
| 1663 |
|
| 1664 |
+
reads a file containing floating-point numbers from `cin`, and prints
|
| 1665 |
the partial sums onto `cout`.
|
| 1666 |
|
| 1667 |
+
— *end example*]
|
| 1668 |
+
|
| 1669 |
### Class template `istream_iterator` <a id="istream.iterator">[[istream.iterator]]</a>
|
| 1670 |
|
| 1671 |
The class template `istream_iterator` is an input iterator (
|
| 1672 |
[[input.iterators]]) that reads (using `operator>>`) successive elements
|
| 1673 |
from the input stream for which it was constructed. After it is
|
|
|
|
| 1680 |
condition. The result of `operator*` on an end-of-stream iterator is not
|
| 1681 |
defined. For any other iterator value a `const T&` is returned. The
|
| 1682 |
result of `operator->` on an end-of-stream iterator is not defined. For
|
| 1683 |
any other iterator value a `const T*` is returned. The behavior of a
|
| 1684 |
program that applies `operator++()` to an end-of-stream iterator is
|
| 1685 |
+
undefined. It is impossible to store things into istream iterators. The
|
| 1686 |
+
type `T` shall meet the `DefaultConstructible`, `CopyConstructible`, and
|
| 1687 |
+
`CopyAssignable` requirements.
|
| 1688 |
|
| 1689 |
Two end-of-stream iterators are always equal. An end-of-stream iterator
|
| 1690 |
is not equal to a non-end-of-stream iterator. Two non-end-of-stream
|
| 1691 |
iterators are equal when they are constructed from the same stream.
|
| 1692 |
|
| 1693 |
``` cpp
|
| 1694 |
namespace std {
|
| 1695 |
template <class T, class charT = char, class traits = char_traits<charT>,
|
| 1696 |
class Distance = ptrdiff_t>
|
| 1697 |
+
class istream_iterator {
|
|
|
|
| 1698 |
public:
|
| 1699 |
+
using iterator_category = input_iterator_tag;
|
| 1700 |
+
using value_type = T;
|
| 1701 |
+
using difference_type = Distance;
|
| 1702 |
+
using pointer = const T*;
|
| 1703 |
+
using reference = const T&;
|
| 1704 |
+
using char_type = charT;
|
| 1705 |
+
using traits_type = traits;
|
| 1706 |
+
using istream_type = basic_istream<charT,traits>;
|
| 1707 |
+
|
| 1708 |
+
constexpr istream_iterator();
|
| 1709 |
istream_iterator(istream_type& s);
|
| 1710 |
istream_iterator(const istream_iterator& x) = default;
|
| 1711 |
~istream_iterator() = default;
|
| 1712 |
|
| 1713 |
const T& operator*() const;
|
| 1714 |
const T* operator->() const;
|
| 1715 |
+
istream_iterator& operator++();
|
| 1716 |
+
istream_iterator operator++(int);
|
| 1717 |
private:
|
| 1718 |
basic_istream<charT,traits>* in_stream; // exposition only
|
| 1719 |
T value; // exposition only
|
| 1720 |
};
|
| 1721 |
|
|
|
|
| 1729 |
```
|
| 1730 |
|
| 1731 |
#### `istream_iterator` constructors and destructor <a id="istream.iterator.cons">[[istream.iterator.cons]]</a>
|
| 1732 |
|
| 1733 |
``` cpp
|
| 1734 |
+
constexpr istream_iterator();
|
| 1735 |
```
|
| 1736 |
|
| 1737 |
+
*Effects:* Constructs the end-of-stream iterator. If
|
| 1738 |
+
`is_trivially_default_constructible_v<T>` is `true`, then this
|
| 1739 |
+
constructor is a constexpr constructor.
|
| 1740 |
|
| 1741 |
+
*Postconditions:* `in_stream == 0`.
|
| 1742 |
|
| 1743 |
``` cpp
|
| 1744 |
istream_iterator(istream_type& s);
|
| 1745 |
```
|
| 1746 |
|
| 1747 |
+
*Effects:* Initializes `in_stream` with `addressof(s)`. `value` may be
|
| 1748 |
+
initialized during construction or the first time it is referenced.
|
| 1749 |
|
| 1750 |
+
*Postconditions:* `in_stream == addressof(s)`.
|
| 1751 |
|
| 1752 |
``` cpp
|
| 1753 |
istream_iterator(const istream_iterator& x) = default;
|
| 1754 |
```
|
| 1755 |
|
| 1756 |
+
*Effects:* Constructs a copy of `x`. If
|
| 1757 |
+
`is_trivially_copy_constructible_v<T>` is `true`, then this constructor
|
| 1758 |
+
is a trivial copy constructor.
|
| 1759 |
|
| 1760 |
+
*Postconditions:* `in_stream == x.in_stream`.
|
| 1761 |
|
| 1762 |
``` cpp
|
| 1763 |
~istream_iterator() = default;
|
| 1764 |
```
|
| 1765 |
|
| 1766 |
+
*Effects:* The iterator is destroyed. If
|
| 1767 |
+
`is_trivially_destructible_v<T>` is `true`, then this destructor is a
|
| 1768 |
+
trivial destructor.
|
| 1769 |
|
| 1770 |
#### `istream_iterator` operations <a id="istream.iterator.ops">[[istream.iterator.ops]]</a>
|
| 1771 |
|
| 1772 |
``` cpp
|
| 1773 |
const T& operator*() const;
|
| 1774 |
```
|
| 1775 |
|
| 1776 |
+
*Returns:* `value`.
|
| 1777 |
|
| 1778 |
``` cpp
|
| 1779 |
const T* operator->() const;
|
| 1780 |
```
|
| 1781 |
|
| 1782 |
+
*Returns:* `addressof(operator*())`.
|
| 1783 |
|
| 1784 |
``` cpp
|
| 1785 |
+
istream_iterator& operator++();
|
| 1786 |
```
|
| 1787 |
|
| 1788 |
*Requires:* `in_stream != 0`.
|
| 1789 |
|
| 1790 |
+
*Effects:* As if by: `*in_stream >> value;`
|
| 1791 |
|
| 1792 |
*Returns:* `*this`.
|
| 1793 |
|
| 1794 |
``` cpp
|
| 1795 |
+
istream_iterator operator++(int);
|
| 1796 |
```
|
| 1797 |
|
| 1798 |
*Requires:* `in_stream != 0`.
|
| 1799 |
|
| 1800 |
+
*Effects:* As if by:
|
| 1801 |
|
| 1802 |
``` cpp
|
| 1803 |
+
istream_iterator tmp = *this;
|
| 1804 |
*in_stream >> value;
|
| 1805 |
return (tmp);
|
| 1806 |
```
|
| 1807 |
|
| 1808 |
``` cpp
|
|
|
|
| 1840 |
is defined as:
|
| 1841 |
|
| 1842 |
``` cpp
|
| 1843 |
namespace std {
|
| 1844 |
template <class T, class charT = char, class traits = char_traits<charT>>
|
| 1845 |
+
class ostream_iterator {
|
|
|
|
| 1846 |
public:
|
| 1847 |
+
using iterator_category = output_iterator_tag;
|
| 1848 |
+
using value_type = void;
|
| 1849 |
+
using difference_type = void;
|
| 1850 |
+
using pointer = void;
|
| 1851 |
+
using reference = void;
|
| 1852 |
+
using char_type = charT;
|
| 1853 |
+
using traits_type = traits;
|
| 1854 |
+
using ostream_type = basic_ostream<charT,traits>;
|
| 1855 |
+
|
| 1856 |
ostream_iterator(ostream_type& s);
|
| 1857 |
ostream_iterator(ostream_type& s, const charT* delimiter);
|
| 1858 |
+
ostream_iterator(const ostream_iterator& x);
|
| 1859 |
~ostream_iterator();
|
| 1860 |
+
ostream_iterator& operator=(const T& value);
|
| 1861 |
|
| 1862 |
+
ostream_iterator& operator*();
|
| 1863 |
+
ostream_iterator& operator++();
|
| 1864 |
+
ostream_iterator& operator++(int);
|
| 1865 |
private:
|
| 1866 |
basic_ostream<charT,traits>* out_stream; // exposition only
|
| 1867 |
const charT* delim; // exposition only
|
| 1868 |
};
|
| 1869 |
}
|
|
|
|
| 1873 |
|
| 1874 |
``` cpp
|
| 1875 |
ostream_iterator(ostream_type& s);
|
| 1876 |
```
|
| 1877 |
|
| 1878 |
+
*Effects:* Initializes `out_stream` with `addressof(s)` and `delim` with
|
| 1879 |
+
null.
|
| 1880 |
|
| 1881 |
``` cpp
|
| 1882 |
ostream_iterator(ostream_type& s, const charT* delimiter);
|
| 1883 |
```
|
| 1884 |
|
| 1885 |
+
*Effects:* Initializes `out_stream` with `addressof(s)` and `delim` with
|
| 1886 |
`delimiter`.
|
| 1887 |
|
| 1888 |
``` cpp
|
| 1889 |
ostream_iterator(const ostream_iterator& x);
|
| 1890 |
```
|
|
|
|
| 1901 |
|
| 1902 |
``` cpp
|
| 1903 |
ostream_iterator& operator=(const T& value);
|
| 1904 |
```
|
| 1905 |
|
| 1906 |
+
*Effects:* As if by:
|
| 1907 |
|
| 1908 |
``` cpp
|
| 1909 |
*out_stream << value;
|
| 1910 |
if (delim != 0)
|
| 1911 |
*out_stream << delim;
|
|
|
|
| 1928 |
### Class template `istreambuf_iterator` <a id="istreambuf.iterator">[[istreambuf.iterator]]</a>
|
| 1929 |
|
| 1930 |
The class template `istreambuf_iterator` defines an input iterator (
|
| 1931 |
[[input.iterators]]) that reads successive *characters* from the
|
| 1932 |
streambuf for which it was constructed. `operator*` provides access to
|
| 1933 |
+
the current input character, if any. Each time `operator++` is
|
| 1934 |
+
evaluated, the iterator advances to the next input character. If the end
|
| 1935 |
+
of stream is reached (`streambuf_type::sgetc()` returns
|
| 1936 |
+
`traits::eof()`), the iterator becomes equal to the *end-of-stream*
|
| 1937 |
+
iterator value. The default constructor `istreambuf_iterator()` and the
|
| 1938 |
+
constructor `istreambuf_iterator(0)` both construct an end-of-stream
|
| 1939 |
+
iterator object suitable for use as an end-of-range. All specializations
|
| 1940 |
+
of `istreambuf_iterator` shall have a trivial copy constructor, a
|
|
|
|
| 1941 |
`constexpr` default constructor, and a trivial destructor.
|
| 1942 |
|
| 1943 |
The result of `operator*()` on an end-of-stream iterator is undefined.
|
| 1944 |
For any other iterator value a `char_type` value is returned. It is
|
| 1945 |
impossible to assign a character via an input iterator.
|
| 1946 |
|
| 1947 |
``` cpp
|
| 1948 |
namespace std {
|
| 1949 |
template<class charT, class traits = char_traits<charT>>
|
| 1950 |
+
class istreambuf_iterator {
|
|
|
|
|
|
|
| 1951 |
public:
|
| 1952 |
+
using iterator_category = input_iterator_tag;
|
| 1953 |
+
using value_type = charT;
|
| 1954 |
+
using difference_type = typename traits::off_type;
|
| 1955 |
+
using pointer = unspecified;
|
| 1956 |
+
using reference = charT;
|
| 1957 |
+
using char_type = charT;
|
| 1958 |
+
using traits_type = traits;
|
| 1959 |
+
using int_type = typename traits::int_type;
|
| 1960 |
+
using streambuf_type = basic_streambuf<charT,traits>;
|
| 1961 |
+
using istream_type = basic_istream<charT,traits>;
|
| 1962 |
|
| 1963 |
class proxy; // exposition only
|
| 1964 |
|
| 1965 |
constexpr istreambuf_iterator() noexcept;
|
| 1966 |
istreambuf_iterator(const istreambuf_iterator&) noexcept = default;
|
| 1967 |
~istreambuf_iterator() = default;
|
| 1968 |
istreambuf_iterator(istream_type& s) noexcept;
|
| 1969 |
istreambuf_iterator(streambuf_type* s) noexcept;
|
| 1970 |
istreambuf_iterator(const proxy& p) noexcept;
|
| 1971 |
charT operator*() const;
|
| 1972 |
+
istreambuf_iterator& operator++();
|
|
|
|
| 1973 |
proxy operator++(int);
|
| 1974 |
bool equal(const istreambuf_iterator& b) const;
|
| 1975 |
private:
|
| 1976 |
streambuf_type* sbuf_; // exposition only
|
| 1977 |
};
|
|
|
|
| 1983 |
bool operator!=(const istreambuf_iterator<charT,traits>& a,
|
| 1984 |
const istreambuf_iterator<charT,traits>& b);
|
| 1985 |
}
|
| 1986 |
```
|
| 1987 |
|
| 1988 |
+
#### Class template `istreambuf_iterator::proxy` <a id="istreambuf.iterator.proxy">[[istreambuf.iterator.proxy]]</a>
|
| 1989 |
|
| 1990 |
``` cpp
|
| 1991 |
namespace std {
|
| 1992 |
template <class charT, class traits = char_traits<charT>>
|
| 1993 |
class istreambuf_iterator<charT, traits>::proxy { // exposition only
|
|
|
|
| 2009 |
(`operator++`). It keeps the character pointed to by the previous value
|
| 2010 |
of the iterator for some possible future access to get the character.
|
| 2011 |
|
| 2012 |
#### `istreambuf_iterator` constructors <a id="istreambuf.iterator.cons">[[istreambuf.iterator.cons]]</a>
|
| 2013 |
|
| 2014 |
+
For each `istreambuf_iterator` constructor in this section, an
|
| 2015 |
+
end-of-stream iterator is constructed if and only if the exposition-only
|
| 2016 |
+
member `sbuf_` is initialized with a null pointer value.
|
| 2017 |
+
|
| 2018 |
``` cpp
|
| 2019 |
constexpr istreambuf_iterator() noexcept;
|
| 2020 |
```
|
| 2021 |
|
| 2022 |
+
*Effects:* Initializes `sbuf_` with `nullptr`.
|
| 2023 |
|
| 2024 |
``` cpp
|
| 2025 |
+
istreambuf_iterator(istream_type& s) noexcept;
|
|
|
|
| 2026 |
```
|
| 2027 |
|
| 2028 |
+
*Effects:* Initializes `sbuf_` with `s.rdbuf()`.
|
| 2029 |
+
|
| 2030 |
+
``` cpp
|
| 2031 |
+
istreambuf_iterator(streambuf_type* s) noexcept;
|
| 2032 |
+
```
|
| 2033 |
+
|
| 2034 |
+
*Effects:* Initializes `sbuf_` with `s`.
|
| 2035 |
|
| 2036 |
``` cpp
|
| 2037 |
istreambuf_iterator(const proxy& p) noexcept;
|
| 2038 |
```
|
| 2039 |
|
| 2040 |
+
*Effects:* Initializes `sbuf_` with `p.sbuf_`.
|
|
|
|
|
|
|
| 2041 |
|
| 2042 |
+
#### `istreambuf_iterator` operations <a id="istreambuf.iterator.ops">[[istreambuf.iterator.ops]]</a>
|
| 2043 |
|
| 2044 |
``` cpp
|
| 2045 |
charT operator*() const
|
| 2046 |
```
|
| 2047 |
|
| 2048 |
*Returns:* The character obtained via the `streambuf` member
|
| 2049 |
`sbuf_->sgetc()`.
|
| 2050 |
|
|
|
|
|
|
|
| 2051 |
``` cpp
|
| 2052 |
+
istreambuf_iterator& operator++();
|
|
|
|
| 2053 |
```
|
| 2054 |
|
| 2055 |
+
*Effects:* As if by `sbuf_->sbumpc()`.
|
| 2056 |
|
| 2057 |
*Returns:* `*this`.
|
| 2058 |
|
| 2059 |
``` cpp
|
| 2060 |
+
proxy operator++(int);
|
| 2061 |
```
|
| 2062 |
|
| 2063 |
*Returns:* `proxy(sbuf_->sbumpc(), sbuf_)`.
|
| 2064 |
|
|
|
|
|
|
|
| 2065 |
``` cpp
|
| 2066 |
+
bool equal(const istreambuf_iterator& b) const;
|
| 2067 |
```
|
| 2068 |
|
| 2069 |
*Returns:* `true` if and only if both iterators are at end-of-stream, or
|
| 2070 |
neither is at end-of-stream, regardless of what `streambuf` object they
|
| 2071 |
use.
|
| 2072 |
|
|
|
|
|
|
|
| 2073 |
``` cpp
|
| 2074 |
template <class charT, class traits>
|
| 2075 |
bool operator==(const istreambuf_iterator<charT,traits>& a,
|
| 2076 |
const istreambuf_iterator<charT,traits>& b);
|
| 2077 |
```
|
| 2078 |
|
| 2079 |
*Returns:* `a.equal(b)`.
|
| 2080 |
|
|
|
|
|
|
|
| 2081 |
``` cpp
|
| 2082 |
template <class charT, class traits>
|
| 2083 |
bool operator!=(const istreambuf_iterator<charT,traits>& a,
|
| 2084 |
const istreambuf_iterator<charT,traits>& b);
|
| 2085 |
```
|
|
|
|
| 2089 |
### Class template `ostreambuf_iterator` <a id="ostreambuf.iterator">[[ostreambuf.iterator]]</a>
|
| 2090 |
|
| 2091 |
``` cpp
|
| 2092 |
namespace std {
|
| 2093 |
template <class charT, class traits = char_traits<charT>>
|
| 2094 |
+
class ostreambuf_iterator {
|
|
|
|
| 2095 |
public:
|
| 2096 |
+
using iterator_category = output_iterator_tag;
|
| 2097 |
+
using value_type = void;
|
| 2098 |
+
using difference_type = void;
|
| 2099 |
+
using pointer = void;
|
| 2100 |
+
using reference = void;
|
| 2101 |
+
using char_type = charT;
|
| 2102 |
+
using traits_type = traits;
|
| 2103 |
+
using streambuf_type = basic_streambuf<charT,traits>;
|
| 2104 |
+
using ostream_type = basic_ostream<charT,traits>;
|
| 2105 |
|
|
|
|
| 2106 |
ostreambuf_iterator(ostream_type& s) noexcept;
|
| 2107 |
ostreambuf_iterator(streambuf_type* s) noexcept;
|
| 2108 |
ostreambuf_iterator& operator=(charT c);
|
| 2109 |
|
| 2110 |
ostreambuf_iterator& operator*();
|
|
|
|
| 2141 |
*Effects:* Initializes `sbuf_` with `s`.
|
| 2142 |
|
| 2143 |
#### `ostreambuf_iterator` operations <a id="ostreambuf.iter.ops">[[ostreambuf.iter.ops]]</a>
|
| 2144 |
|
| 2145 |
``` cpp
|
| 2146 |
+
ostreambuf_iterator& operator=(charT c);
|
|
|
|
| 2147 |
```
|
| 2148 |
|
| 2149 |
*Effects:* If `failed()` yields `false`, calls `sbuf_->sputc(c)`;
|
| 2150 |
otherwise has no effect.
|
| 2151 |
|
| 2152 |
*Returns:* `*this`.
|
| 2153 |
|
| 2154 |
``` cpp
|
| 2155 |
+
ostreambuf_iterator& operator*();
|
| 2156 |
```
|
| 2157 |
|
| 2158 |
*Returns:* `*this`.
|
| 2159 |
|
| 2160 |
``` cpp
|
| 2161 |
+
ostreambuf_iterator& operator++();
|
| 2162 |
+
ostreambuf_iterator& operator++(int);
|
| 2163 |
```
|
| 2164 |
|
| 2165 |
*Returns:* `*this`.
|
| 2166 |
|
| 2167 |
``` cpp
|
|
|
|
| 2169 |
```
|
| 2170 |
|
| 2171 |
*Returns:* `true` if in any prior use of member `operator=`, the call to
|
| 2172 |
`sbuf_->sputc()` returned `traits::eof()`; or `false` otherwise.
|
| 2173 |
|
| 2174 |
+
## Range access <a id="iterator.range">[[iterator.range]]</a>
|
| 2175 |
|
| 2176 |
In addition to being available via inclusion of the `<iterator>` header,
|
| 2177 |
the function templates in [[iterator.range]] are available when any of
|
| 2178 |
the following headers are included: `<array>`, `<deque>`,
|
| 2179 |
`<forward_list>`, `<list>`, `<map>`, `<regex>`, `<set>`, `<string>`,
|
| 2180 |
+
`<string_view>`, `<unordered_map>`, `<unordered_set>`, and `<vector>`.
|
| 2181 |
|
| 2182 |
``` cpp
|
| 2183 |
+
template <class C> constexpr auto begin(C& c) -> decltype(c.begin());
|
| 2184 |
+
template <class C> constexpr auto begin(const C& c) -> decltype(c.begin());
|
| 2185 |
```
|
| 2186 |
|
| 2187 |
*Returns:* `c.begin()`.
|
| 2188 |
|
| 2189 |
``` cpp
|
| 2190 |
+
template <class C> constexpr auto end(C& c) -> decltype(c.end());
|
| 2191 |
+
template <class C> constexpr auto end(const C& c) -> decltype(c.end());
|
| 2192 |
```
|
| 2193 |
|
| 2194 |
*Returns:* `c.end()`.
|
| 2195 |
|
| 2196 |
``` cpp
|
|
|
|
| 2218 |
```
|
| 2219 |
|
| 2220 |
*Returns:* `std::end(c)`.
|
| 2221 |
|
| 2222 |
``` cpp
|
| 2223 |
+
template <class C> constexpr auto rbegin(C& c) -> decltype(c.rbegin());
|
| 2224 |
+
template <class C> constexpr auto rbegin(const C& c) -> decltype(c.rbegin());
|
| 2225 |
```
|
| 2226 |
|
| 2227 |
*Returns:* `c.rbegin()`.
|
| 2228 |
|
| 2229 |
``` cpp
|
| 2230 |
+
template <class C> constexpr auto rend(C& c) -> decltype(c.rend());
|
| 2231 |
+
template <class C> constexpr auto rend(const C& c) -> decltype(c.rend());
|
| 2232 |
```
|
| 2233 |
|
| 2234 |
*Returns:* `c.rend()`.
|
| 2235 |
|
| 2236 |
``` cpp
|
| 2237 |
+
template <class T, size_t N> constexpr reverse_iterator<T*> rbegin(T (&array)[N]);
|
| 2238 |
```
|
| 2239 |
|
| 2240 |
*Returns:* `reverse_iterator<T*>(array + N)`.
|
| 2241 |
|
| 2242 |
``` cpp
|
| 2243 |
+
template <class T, size_t N> constexpr reverse_iterator<T*> rend(T (&array)[N]);
|
| 2244 |
```
|
| 2245 |
|
| 2246 |
*Returns:* `reverse_iterator<T*>(array)`.
|
| 2247 |
|
| 2248 |
``` cpp
|
| 2249 |
+
template <class E> constexpr reverse_iterator<const E*> rbegin(initializer_list<E> il);
|
| 2250 |
```
|
| 2251 |
|
| 2252 |
*Returns:* `reverse_iterator<const E*>(il.end())`.
|
| 2253 |
|
| 2254 |
``` cpp
|
| 2255 |
+
template <class E> constexpr reverse_iterator<const E*> rend(initializer_list<E> il);
|
| 2256 |
```
|
| 2257 |
|
| 2258 |
*Returns:* `reverse_iterator<const E*>(il.begin())`.
|
| 2259 |
|
| 2260 |
``` cpp
|
| 2261 |
+
template <class C> constexpr auto crbegin(const C& c) -> decltype(std::rbegin(c));
|
| 2262 |
```
|
| 2263 |
|
| 2264 |
*Returns:* `std::rbegin(c)`.
|
| 2265 |
|
| 2266 |
``` cpp
|
| 2267 |
+
template <class C> constexpr auto crend(const C& c) -> decltype(std::rend(c));
|
| 2268 |
```
|
| 2269 |
|
| 2270 |
*Returns:* `std::rend(c)`.
|
| 2271 |
|
| 2272 |
+
## Container access <a id="iterator.container">[[iterator.container]]</a>
|
| 2273 |
+
|
| 2274 |
+
In addition to being available via inclusion of the `<iterator>` header,
|
| 2275 |
+
the function templates in [[iterator.container]] are available when any
|
| 2276 |
+
of the following headers are included: `<array>`, `<deque>`,
|
| 2277 |
+
`<forward_list>`, `<list>`, `<map>`, `<regex>`, `<set>`, `<string>`,
|
| 2278 |
+
`<unordered_map>`, `<unordered_set>`, and `<vector>`.
|
| 2279 |
+
|
| 2280 |
+
``` cpp
|
| 2281 |
+
template <class C> constexpr auto size(const C& c) -> decltype(c.size());
|
| 2282 |
+
```
|
| 2283 |
+
|
| 2284 |
+
*Returns:* `c.size()`.
|
| 2285 |
+
|
| 2286 |
+
``` cpp
|
| 2287 |
+
template <class T, size_t N> constexpr size_t size(const T (&array)[N]) noexcept;
|
| 2288 |
+
```
|
| 2289 |
+
|
| 2290 |
+
*Returns:* `N`.
|
| 2291 |
+
|
| 2292 |
+
``` cpp
|
| 2293 |
+
template <class C> constexpr auto empty(const C& c) -> decltype(c.empty());
|
| 2294 |
+
```
|
| 2295 |
+
|
| 2296 |
+
*Returns:* `c.empty()`.
|
| 2297 |
+
|
| 2298 |
+
``` cpp
|
| 2299 |
+
template <class T, size_t N> constexpr bool empty(const T (&array)[N]) noexcept;
|
| 2300 |
+
```
|
| 2301 |
+
|
| 2302 |
+
*Returns:* `false`.
|
| 2303 |
+
|
| 2304 |
+
``` cpp
|
| 2305 |
+
template <class E> constexpr bool empty(initializer_list<E> il) noexcept;
|
| 2306 |
+
```
|
| 2307 |
+
|
| 2308 |
+
*Returns:* `il.size() == 0`.
|
| 2309 |
+
|
| 2310 |
+
``` cpp
|
| 2311 |
+
template <class C> constexpr auto data(C& c) -> decltype(c.data());
|
| 2312 |
+
template <class C> constexpr auto data(const C& c) -> decltype(c.data());
|
| 2313 |
+
```
|
| 2314 |
+
|
| 2315 |
+
*Returns:* `c.data()`.
|
| 2316 |
+
|
| 2317 |
+
``` cpp
|
| 2318 |
+
template <class T, size_t N> constexpr T* data(T (&array)[N]) noexcept;
|
| 2319 |
+
```
|
| 2320 |
+
|
| 2321 |
+
*Returns:* `array`.
|
| 2322 |
+
|
| 2323 |
+
``` cpp
|
| 2324 |
+
template <class E> constexpr const E* data(initializer_list<E> il) noexcept;
|
| 2325 |
+
```
|
| 2326 |
+
|
| 2327 |
+
*Returns:* `il.begin()`.
|
| 2328 |
+
|
| 2329 |
<!-- Link reference definitions -->
|
| 2330 |
[back.insert.iter.cons]: #back.insert.iter.cons
|
| 2331 |
[back.insert.iter.op*]: #back.insert.iter.op*
|
| 2332 |
[back.insert.iter.op++]: #back.insert.iter.op++
|
| 2333 |
[back.insert.iter.op=]: #back.insert.iter.op=
|
| 2334 |
[back.insert.iter.ops]: #back.insert.iter.ops
|
| 2335 |
[back.insert.iterator]: #back.insert.iterator
|
| 2336 |
[back.inserter]: #back.inserter
|
| 2337 |
[bidirectional.iterators]: #bidirectional.iterators
|
| 2338 |
[containers]: containers.md#containers
|
|
|
|
|
|
|
| 2339 |
[forward.iterators]: #forward.iterators
|
| 2340 |
[front.insert.iter.cons]: #front.insert.iter.cons
|
| 2341 |
[front.insert.iter.op*]: #front.insert.iter.op*
|
| 2342 |
[front.insert.iter.op++]: #front.insert.iter.op++
|
| 2343 |
[front.insert.iter.op=]: #front.insert.iter.op=
|
|
|
|
| 2357 |
[istream.iterator]: #istream.iterator
|
| 2358 |
[istream.iterator.cons]: #istream.iterator.cons
|
| 2359 |
[istream.iterator.ops]: #istream.iterator.ops
|
| 2360 |
[istreambuf.iterator]: #istreambuf.iterator
|
| 2361 |
[istreambuf.iterator.cons]: #istreambuf.iterator.cons
|
| 2362 |
+
[istreambuf.iterator.ops]: #istreambuf.iterator.ops
|
| 2363 |
+
[istreambuf.iterator.proxy]: #istreambuf.iterator.proxy
|
| 2364 |
+
[iterator.container]: #iterator.container
|
|
|
|
|
|
|
|
|
|
|
|
|
| 2365 |
[iterator.iterators]: #iterator.iterators
|
| 2366 |
[iterator.operations]: #iterator.operations
|
| 2367 |
[iterator.primitives]: #iterator.primitives
|
| 2368 |
[iterator.range]: #iterator.range
|
| 2369 |
[iterator.requirements]: #iterator.requirements
|
|
|
|
| 2425 |
[reverse.iterators]: #reverse.iterators
|
| 2426 |
[std.iterator.tags]: #std.iterator.tags
|
| 2427 |
[stream.buffers]: input.md#stream.buffers
|
| 2428 |
[stream.iterators]: #stream.iterators
|
| 2429 |
[swappable.requirements]: library.md#swappable.requirements
|
| 2430 |
+
[tab:copyassignable]: #tab:copyassignable
|
| 2431 |
+
[tab:equalitycomparable]: #tab:equalitycomparable
|
| 2432 |
[tab:iterator.bidirectional.requirements]: #tab:iterator.bidirectional.requirements
|
| 2433 |
[tab:iterator.forward.requirements]: #tab:iterator.forward.requirements
|
| 2434 |
[tab:iterator.input.requirements]: #tab:iterator.input.requirements
|
| 2435 |
[tab:iterator.output.requirements]: #tab:iterator.output.requirements
|
| 2436 |
[tab:iterator.random.access.requirements]: #tab:iterator.random.access.requirements
|
| 2437 |
[tab:iterator.requirements]: #tab:iterator.requirements
|
| 2438 |
[tab:iterators.lib.summary]: #tab:iterators.lib.summary
|
| 2439 |
[tab:iterators.relations]: #tab:iterators.relations
|
| 2440 |
+
[temp.deduct]: temp.md#temp.deduct
|
| 2441 |
[temp.inst]: temp.md#temp.inst
|
| 2442 |
[utility.arg.requirements]: library.md#utility.arg.requirements
|
| 2443 |
|
| 2444 |
[^1]: This definition applies to pointers, since pointers are iterators.
|
| 2445 |
The effect of dereferencing an iterator that has been invalidated is
|