- tmp/tmpazswxqeu/{from.md → to.md} +1070 -426
tmp/tmpazswxqeu/{from.md → to.md}
RENAMED
|
@@ -36,359 +36,405 @@ namespace std {
|
|
| 36 |
{ *t } -> can-reference; // not required to be equality-preserving
|
| 37 |
};
|
| 38 |
|
| 39 |
// [iterator.assoc.types], associated types
|
| 40 |
// [incrementable.traits], incrementable traits
|
| 41 |
-
template<class> struct incrementable_traits;
|
| 42 |
template<class T>
|
| 43 |
-
using iter_difference_t = see below;
|
| 44 |
|
| 45 |
// [readable.traits], indirectly readable traits
|
| 46 |
-
template<class> struct indirectly_readable_traits;
|
| 47 |
template<class T>
|
| 48 |
-
using iter_value_t = see below;
|
| 49 |
|
| 50 |
// [iterator.traits], iterator traits
|
| 51 |
-
template<class I> struct iterator_traits;
|
| 52 |
-
template<class T> requires is_object_v<T> struct iterator_traits<T*>;
|
| 53 |
|
| 54 |
template<dereferenceable T>
|
| 55 |
-
using iter_reference_t = decltype(*declval<T&>());
|
| 56 |
|
| 57 |
namespace ranges {
|
| 58 |
-
// [iterator.cust], customization
|
| 59 |
inline namespace unspecified {
|
| 60 |
// [iterator.cust.move], ranges::iter_move
|
| 61 |
-
inline constexpr unspecified iter_move = unspecified;
|
| 62 |
|
| 63 |
// [iterator.cust.swap], ranges::iter_swap
|
| 64 |
-
inline constexpr unspecified iter_swap = unspecified;
|
| 65 |
}
|
| 66 |
}
|
| 67 |
|
| 68 |
template<dereferenceable T>
|
| 69 |
requires requires(T& t) {
|
| 70 |
{ ranges::iter_move(t) } -> can-reference;
|
| 71 |
}
|
| 72 |
-
using iter_rvalue_reference_t
|
| 73 |
= decltype(ranges::iter_move(declval<T&>()));
|
| 74 |
|
| 75 |
// [iterator.concepts], iterator concepts
|
| 76 |
// [iterator.concept.readable], concept indirectly_readable
|
| 77 |
template<class In>
|
| 78 |
-
concept indirectly_readable = see below;
|
| 79 |
|
| 80 |
template<indirectly_readable T>
|
| 81 |
-
using
|
| 82 |
-
|
|
|
|
|
|
|
|
|
|
| 83 |
|
| 84 |
// [iterator.concept.writable], concept indirectly_writable
|
| 85 |
template<class Out, class T>
|
| 86 |
-
concept indirectly_writable = see below;
|
| 87 |
|
| 88 |
// [iterator.concept.winc], concept weakly_incrementable
|
| 89 |
template<class I>
|
| 90 |
-
concept weakly_incrementable = see below;
|
| 91 |
|
| 92 |
// [iterator.concept.inc], concept incrementable
|
| 93 |
template<class I>
|
| 94 |
-
concept incrementable = see below;
|
| 95 |
|
| 96 |
// [iterator.concept.iterator], concept input_or_output_iterator
|
| 97 |
template<class I>
|
| 98 |
-
concept input_or_output_iterator = see below;
|
| 99 |
|
| 100 |
// [iterator.concept.sentinel], concept sentinel_for
|
| 101 |
template<class S, class I>
|
| 102 |
-
concept sentinel_for = see below;
|
| 103 |
|
| 104 |
// [iterator.concept.sizedsentinel], concept sized_sentinel_for
|
| 105 |
template<class S, class I>
|
| 106 |
-
|
| 107 |
|
| 108 |
template<class S, class I>
|
| 109 |
-
concept sized_sentinel_for = see below;
|
| 110 |
|
| 111 |
// [iterator.concept.input], concept input_iterator
|
| 112 |
template<class I>
|
| 113 |
-
concept input_iterator = see below;
|
| 114 |
|
| 115 |
// [iterator.concept.output], concept output_iterator
|
| 116 |
template<class I, class T>
|
| 117 |
-
concept output_iterator = see below;
|
| 118 |
|
| 119 |
// [iterator.concept.forward], concept forward_iterator
|
| 120 |
template<class I>
|
| 121 |
-
concept forward_iterator = see below;
|
| 122 |
|
| 123 |
// [iterator.concept.bidir], concept bidirectional_iterator
|
| 124 |
template<class I>
|
| 125 |
-
concept bidirectional_iterator = see below;
|
| 126 |
|
| 127 |
// [iterator.concept.random.access], concept random_access_iterator
|
| 128 |
template<class I>
|
| 129 |
-
concept random_access_iterator = see below;
|
| 130 |
|
| 131 |
// [iterator.concept.contiguous], concept contiguous_iterator
|
| 132 |
template<class I>
|
| 133 |
-
concept contiguous_iterator = see below;
|
| 134 |
|
| 135 |
// [indirectcallable], indirect callable requirements
|
| 136 |
// [indirectcallable.indirectinvocable], indirect callables
|
| 137 |
template<class F, class I>
|
| 138 |
-
concept indirectly_unary_invocable = see below;
|
| 139 |
|
| 140 |
template<class F, class I>
|
| 141 |
-
concept indirectly_regular_unary_invocable = see below;
|
| 142 |
|
| 143 |
template<class F, class I>
|
| 144 |
-
concept indirect_unary_predicate = see below;
|
| 145 |
|
| 146 |
template<class F, class I1, class I2>
|
| 147 |
-
concept indirect_binary_predicate = see below;
|
| 148 |
|
| 149 |
template<class F, class I1, class I2 = I1>
|
| 150 |
-
concept indirect_equivalence_relation = see below;
|
| 151 |
|
| 152 |
template<class F, class I1, class I2 = I1>
|
| 153 |
-
concept indirect_strict_weak_order = see below;
|
| 154 |
|
| 155 |
template<class F, class... Is>
|
| 156 |
requires (indirectly_readable<Is> && ...) && invocable<F, iter_reference_t<Is>...>
|
| 157 |
-
using indirect_result_t = invoke_result_t<F, iter_reference_t<Is>...>;
|
| 158 |
|
| 159 |
// [projected], projected
|
| 160 |
template<indirectly_readable I, indirectly_regular_unary_invocable<I> Proj>
|
| 161 |
-
struct projected;
|
| 162 |
|
| 163 |
template<weakly_incrementable I, class Proj>
|
| 164 |
-
struct incrementable_traits<projected<I, Proj>>;
|
| 165 |
|
| 166 |
// [alg.req], common algorithm requirements
|
| 167 |
// [alg.req.ind.move], concept indirectly_movable
|
| 168 |
template<class In, class Out>
|
| 169 |
-
concept indirectly_movable = see below;
|
| 170 |
|
| 171 |
template<class In, class Out>
|
| 172 |
-
concept indirectly_movable_storable = see below;
|
| 173 |
|
| 174 |
// [alg.req.ind.copy], concept indirectly_copyable
|
| 175 |
template<class In, class Out>
|
| 176 |
-
concept indirectly_copyable = see below;
|
| 177 |
|
| 178 |
template<class In, class Out>
|
| 179 |
-
concept indirectly_copyable_storable = see below;
|
| 180 |
|
| 181 |
// [alg.req.ind.swap], concept indirectly_swappable
|
| 182 |
template<class I1, class I2 = I1>
|
| 183 |
-
concept indirectly_swappable = see below;
|
| 184 |
|
| 185 |
// [alg.req.ind.cmp], concept indirectly_comparable
|
| 186 |
template<class I1, class I2, class R, class P1 = identity, class P2 = identity>
|
| 187 |
-
concept indirectly_comparable = see below;
|
| 188 |
|
| 189 |
// [alg.req.permutable], concept permutable
|
| 190 |
template<class I>
|
| 191 |
-
concept permutable = see below;
|
| 192 |
|
| 193 |
// [alg.req.mergeable], concept mergeable
|
| 194 |
template<class I1, class I2, class Out,
|
| 195 |
class R = ranges::less, class P1 = identity, class P2 = identity>
|
| 196 |
-
concept mergeable = see below;
|
| 197 |
|
| 198 |
// [alg.req.sortable], concept sortable
|
| 199 |
template<class I, class R = ranges::less, class P = identity>
|
| 200 |
-
concept sortable = see below;
|
| 201 |
|
| 202 |
// [iterator.primitives], primitives
|
| 203 |
// [std.iterator.tags], iterator tags
|
| 204 |
-
struct input_iterator_tag { };
|
| 205 |
-
struct output_iterator_tag { };
|
| 206 |
-
struct forward_iterator_tag: public input_iterator_tag { };
|
| 207 |
-
struct bidirectional_iterator_tag: public forward_iterator_tag { };
|
| 208 |
-
struct random_access_iterator_tag: public bidirectional_iterator_tag { };
|
| 209 |
-
struct contiguous_iterator_tag: public random_access_iterator_tag { };
|
| 210 |
|
| 211 |
// [iterator.operations], iterator operations
|
| 212 |
template<class InputIterator, class Distance>
|
| 213 |
constexpr void
|
| 214 |
-
advance(InputIterator& i, Distance n);
|
| 215 |
template<class InputIterator>
|
| 216 |
constexpr typename iterator_traits<InputIterator>::difference_type
|
| 217 |
-
distance(InputIterator first, InputIterator last);
|
| 218 |
template<class InputIterator>
|
| 219 |
constexpr InputIterator
|
| 220 |
-
next(InputIterator x,
|
| 221 |
typename iterator_traits<InputIterator>::difference_type n = 1);
|
| 222 |
template<class BidirectionalIterator>
|
| 223 |
constexpr BidirectionalIterator
|
| 224 |
-
prev(BidirectionalIterator x,
|
| 225 |
typename iterator_traits<BidirectionalIterator>::difference_type n = 1);
|
| 226 |
|
| 227 |
// [range.iter.ops], range iterator operations
|
| 228 |
namespace ranges {
|
| 229 |
// [range.iter.op.advance], ranges::advance
|
| 230 |
template<input_or_output_iterator I>
|
| 231 |
-
constexpr void advance(I& i, iter_difference_t<I> n);
|
| 232 |
template<input_or_output_iterator I, sentinel_for<I> S>
|
| 233 |
-
constexpr void advance(I& i, S bound);
|
| 234 |
template<input_or_output_iterator I, sentinel_for<I> S>
|
| 235 |
-
constexpr iter_difference_t<I> advance(I& i, iter_difference_t<I> n,
|
|
|
|
| 236 |
|
| 237 |
// [range.iter.op.distance], ranges::distance
|
| 238 |
-
template<
|
| 239 |
-
|
|
|
|
|
|
|
|
|
|
| 240 |
template<range R>
|
| 241 |
-
constexpr range_difference_t<R> distance(R&& r);
|
| 242 |
|
| 243 |
// [range.iter.op.next], ranges::next
|
| 244 |
template<input_or_output_iterator I>
|
| 245 |
-
constexpr I next(I x);
|
| 246 |
template<input_or_output_iterator I>
|
| 247 |
-
constexpr I next(I x, iter_difference_t<I> n);
|
| 248 |
template<input_or_output_iterator I, sentinel_for<I> S>
|
| 249 |
-
constexpr I next(I x, S bound);
|
| 250 |
template<input_or_output_iterator I, sentinel_for<I> S>
|
| 251 |
-
constexpr I next(I x, iter_difference_t<I> n, S bound);
|
| 252 |
|
| 253 |
// [range.iter.op.prev], ranges::prev
|
| 254 |
template<bidirectional_iterator I>
|
| 255 |
-
constexpr I prev(I x);
|
| 256 |
template<bidirectional_iterator I>
|
| 257 |
-
constexpr I prev(I x, iter_difference_t<I> n);
|
| 258 |
template<bidirectional_iterator I>
|
| 259 |
-
constexpr I prev(I x, iter_difference_t<I> n, I bound);
|
| 260 |
}
|
| 261 |
|
| 262 |
// [predef.iterators], predefined iterators and sentinels
|
| 263 |
// [reverse.iterators], reverse iterators
|
| 264 |
-
template<class Iterator> class reverse_iterator;
|
| 265 |
|
| 266 |
template<class Iterator1, class Iterator2>
|
| 267 |
-
constexpr bool operator==(
|
| 268 |
const reverse_iterator<Iterator1>& x,
|
| 269 |
const reverse_iterator<Iterator2>& y);
|
| 270 |
template<class Iterator1, class Iterator2>
|
| 271 |
-
constexpr bool operator!=(
|
| 272 |
const reverse_iterator<Iterator1>& x,
|
| 273 |
const reverse_iterator<Iterator2>& y);
|
| 274 |
template<class Iterator1, class Iterator2>
|
| 275 |
-
constexpr bool operator<(
|
| 276 |
const reverse_iterator<Iterator1>& x,
|
| 277 |
const reverse_iterator<Iterator2>& y);
|
| 278 |
template<class Iterator1, class Iterator2>
|
| 279 |
-
constexpr bool operator>(
|
| 280 |
const reverse_iterator<Iterator1>& x,
|
| 281 |
const reverse_iterator<Iterator2>& y);
|
| 282 |
template<class Iterator1, class Iterator2>
|
| 283 |
-
constexpr bool operator<=(
|
| 284 |
const reverse_iterator<Iterator1>& x,
|
| 285 |
const reverse_iterator<Iterator2>& y);
|
| 286 |
template<class Iterator1, class Iterator2>
|
| 287 |
-
constexpr bool operator>=(
|
| 288 |
const reverse_iterator<Iterator1>& x,
|
| 289 |
const reverse_iterator<Iterator2>& y);
|
| 290 |
template<class Iterator1, three_way_comparable_with<Iterator1> Iterator2>
|
| 291 |
constexpr compare_three_way_result_t<Iterator1, Iterator2>
|
| 292 |
-
operator<=>(const reverse_iterator<Iterator1>& x,
|
| 293 |
const reverse_iterator<Iterator2>& y);
|
| 294 |
|
| 295 |
template<class Iterator1, class Iterator2>
|
| 296 |
-
constexpr auto operator-(
|
| 297 |
const reverse_iterator<Iterator1>& x,
|
| 298 |
const reverse_iterator<Iterator2>& y) -> decltype(y.base() - x.base());
|
| 299 |
template<class Iterator>
|
| 300 |
-
constexpr reverse_iterator<Iterator>
|
| 301 |
-
|
| 302 |
-
typename reverse_iterator<Iterator>::difference_type n,
|
| 303 |
const reverse_iterator<Iterator>& x);
|
| 304 |
|
| 305 |
template<class Iterator>
|
| 306 |
-
constexpr reverse_iterator<Iterator> make_reverse_iterator(Iterator i);
|
| 307 |
|
| 308 |
template<class Iterator1, class Iterator2>
|
| 309 |
requires (!sized_sentinel_for<Iterator1, Iterator2>)
|
| 310 |
-
|
| 311 |
reverse_iterator<Iterator2>> = true;
|
| 312 |
|
| 313 |
// [insert.iterators], insert iterators
|
| 314 |
-
template<class Container> class back_insert_iterator;
|
| 315 |
template<class Container>
|
| 316 |
-
constexpr back_insert_iterator<Container> back_inserter(Container& x);
|
| 317 |
|
| 318 |
-
template<class Container> class front_insert_iterator;
|
| 319 |
template<class Container>
|
| 320 |
-
constexpr front_insert_iterator<Container> front_inserter(Container& x);
|
| 321 |
|
| 322 |
-
template<class Container> class insert_iterator;
|
| 323 |
template<class Container>
|
| 324 |
constexpr insert_iterator<Container>
|
| 325 |
-
inserter(Container& x, ranges::iterator_t<Container> i);
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 326 |
|
| 327 |
// [move.iterators], move iterators and sentinels
|
| 328 |
-
template<class Iterator> class move_iterator;
|
| 329 |
|
| 330 |
template<class Iterator1, class Iterator2>
|
| 331 |
-
constexpr bool operator==(
|
| 332 |
const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 333 |
template<class Iterator1, class Iterator2>
|
| 334 |
-
constexpr bool operator<(
|
| 335 |
const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 336 |
template<class Iterator1, class Iterator2>
|
| 337 |
-
constexpr bool operator>(
|
| 338 |
const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 339 |
template<class Iterator1, class Iterator2>
|
| 340 |
-
constexpr bool operator<=(
|
| 341 |
const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 342 |
template<class Iterator1, class Iterator2>
|
| 343 |
-
constexpr bool operator>=(
|
| 344 |
const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 345 |
template<class Iterator1, three_way_comparable_with<Iterator1> Iterator2>
|
| 346 |
constexpr compare_three_way_result_t<Iterator1, Iterator2>
|
| 347 |
-
operator<=>(const move_iterator<Iterator1>& x,
|
| 348 |
const move_iterator<Iterator2>& y);
|
| 349 |
|
| 350 |
template<class Iterator1, class Iterator2>
|
| 351 |
-
constexpr auto operator-(
|
| 352 |
-
|
| 353 |
-
|
| 354 |
template<class Iterator>
|
| 355 |
-
constexpr move_iterator<Iterator>
|
| 356 |
-
|
| 357 |
|
| 358 |
template<class Iterator>
|
| 359 |
-
constexpr move_iterator<Iterator> make_move_iterator(Iterator i);
|
| 360 |
|
| 361 |
-
template<
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 362 |
|
| 363 |
// [iterators.common], common iterators
|
| 364 |
template<input_or_output_iterator I, sentinel_for<I> S>
|
| 365 |
requires (!same_as<I, S> && copyable<I>)
|
| 366 |
-
class common_iterator;
|
| 367 |
|
| 368 |
template<class I, class S>
|
| 369 |
-
struct incrementable_traits<common_iterator<I, S>>;
|
| 370 |
|
| 371 |
template<input_iterator I, class S>
|
| 372 |
-
struct iterator_traits<common_iterator<I, S>>;
|
| 373 |
|
| 374 |
-
// [default.
|
| 375 |
-
struct default_sentinel_t;
|
| 376 |
-
inline constexpr default_sentinel_t default_sentinel{};
|
| 377 |
|
| 378 |
// [iterators.counted], counted iterators
|
| 379 |
-
template<input_or_output_iterator I> class counted_iterator;
|
| 380 |
-
|
| 381 |
-
template<class I>
|
| 382 |
-
struct incrementable_traits<counted_iterator<I>>;
|
| 383 |
|
| 384 |
template<input_iterator I>
|
| 385 |
-
|
|
|
|
| 386 |
|
| 387 |
-
// [unreachable.
|
| 388 |
-
struct unreachable_sentinel_t;
|
| 389 |
-
inline constexpr unreachable_sentinel_t unreachable_sentinel{};
|
| 390 |
|
| 391 |
// [stream.iterators], stream iterators
|
| 392 |
template<class T, class charT = char, class traits = char_traits<charT>,
|
| 393 |
class Distance = ptrdiff_t>
|
| 394 |
class istream_iterator;
|
|
@@ -407,43 +453,57 @@ namespace std {
|
|
| 407 |
|
| 408 |
template<class charT, class traits = char_traits<charT>>
|
| 409 |
class ostreambuf_iterator;
|
| 410 |
|
| 411 |
// [iterator.range], range access
|
| 412 |
-
template<class C> constexpr auto begin(C& c) -> decltype(c.begin());
|
| 413 |
-
template<class C> constexpr auto begin(const C& c) -> decltype(c.begin());
|
| 414 |
-
template<class C> constexpr auto end(C& c) -> decltype(c.end());
|
| 415 |
-
template<class C> constexpr auto end(const C& c) -> decltype(c.end());
|
| 416 |
-
template<class T, size_t N> constexpr T* begin(T (&array)[N]) noexcept;
|
| 417 |
-
template<class T, size_t N> constexpr T* end(T (&array)[N]) noexcept;
|
| 418 |
-
template<class C> constexpr auto cbegin(const C& c)
|
| 419 |
-
-> decltype(std::begin(c));
|
| 420 |
-
template<class C> constexpr auto cend(const C& c)
|
| 421 |
-
-> decltype(std::end(c));
|
| 422 |
-
template<class C> constexpr auto rbegin(C& c) -> decltype(c.rbegin());
|
| 423 |
-
template<class C> constexpr auto rbegin(const C& c) -> decltype(c.rbegin());
|
| 424 |
-
template<class C> constexpr auto rend(C& c) -> decltype(c.rend());
|
| 425 |
-
template<class C> constexpr auto rend(const C& c) -> decltype(c.rend());
|
| 426 |
-
template<class T, size_t N> constexpr reverse_iterator<T*> rbegin(T (&array)[N])
|
| 427 |
-
template<class T, size_t N> constexpr reverse_iterator<T*> rend(T (&array)[N]);
|
| 428 |
-
template<class E> constexpr reverse_iterator<const E*>
|
| 429 |
-
|
| 430 |
-
template<class
|
| 431 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
| 432 |
|
| 433 |
-
template<class C> constexpr auto
|
| 434 |
-
|
| 435 |
-
template<class
|
| 436 |
-
|
| 437 |
-
|
| 438 |
-
template<class C>
|
| 439 |
-
|
| 440 |
-
|
| 441 |
-
template<class
|
| 442 |
-
|
| 443 |
-
|
| 444 |
-
template<class
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 445 |
}
|
| 446 |
```
|
| 447 |
|
| 448 |
## Iterator requirements <a id="iterator.requirements">[[iterator.requirements]]</a>
|
| 449 |
|
|
@@ -483,11 +543,11 @@ access iterators*, and *contiguous iterators*, as shown in
|
|
| 483 |
The six categories of iterators correspond to the iterator concepts
|
| 484 |
|
| 485 |
- `input_iterator` [[iterator.concept.input]],
|
| 486 |
- `output_iterator` [[iterator.concept.output]],
|
| 487 |
- `forward_iterator` [[iterator.concept.forward]],
|
| 488 |
-
- `bidirectional_iterator` [[iterator.concept.bidir]]
|
| 489 |
- `random_access_iterator` [[iterator.concept.random.access]], and
|
| 490 |
- `contiguous_iterator` [[iterator.concept.contiguous]],
|
| 491 |
|
| 492 |
respectively. The generic term *iterator* refers to any type that models
|
| 493 |
the `input_or_output_iterator` concept [[iterator.concept.iterator]].
|
|
@@ -518,22 +578,16 @@ value pointing past the last element of the array, so for any iterator
|
|
| 518 |
type there is an iterator value that points past the last element of a
|
| 519 |
corresponding sequence. Such a value is called a *past-the-end value*.
|
| 520 |
Values of an iterator `i` for which the expression `*i` is defined are
|
| 521 |
called *dereferenceable*. The library never assumes that past-the-end
|
| 522 |
values are dereferenceable. Iterators can also have singular values that
|
| 523 |
-
are not associated with any sequence.
|
| 524 |
-
|
| 525 |
-
|
| 526 |
-
|
| 527 |
-
|
| 528 |
-
|
| 529 |
-
Results of most expressions are undefined for singular values; the only
|
| 530 |
-
exceptions are destroying an iterator that holds a singular value, the
|
| 531 |
-
assignment of a non-singular value to an iterator that holds a singular
|
| 532 |
-
value, and, for iterators that meet the *Cpp17DefaultConstructible*
|
| 533 |
-
requirements, using a value-initialized iterator as the source of a copy
|
| 534 |
-
or move operation.
|
| 535 |
|
| 536 |
[*Note 2*: This guarantee is not offered for default-initialization,
|
| 537 |
although the distinction only matters for types with trivial default
|
| 538 |
constructors such as pointers or aggregates holding
|
| 539 |
pointers. — *end note*]
|
|
@@ -554,18 +608,18 @@ elements in the data structure starting with the element pointed to by
|
|
| 554 |
first iterator `j` such that `j == s`.
|
| 555 |
|
| 556 |
A sentinel `s` is called *reachable from* an iterator `i` if and only if
|
| 557 |
there is a finite sequence of applications of the expression `++i` that
|
| 558 |
makes `i == s`. If `s` is reachable from `i`, \[`i`, `s`) denotes a
|
| 559 |
-
valid range.
|
| 560 |
|
| 561 |
A *counted range* `i`+\[0, `n`) is empty if `n == 0`; otherwise,
|
| 562 |
`i`+\[0, `n`) refers to the `n` elements in the data structure starting
|
| 563 |
with the element pointed to by `i` and up to but not including the
|
| 564 |
element, if any, pointed to by the result of `n` applications of `++i`.
|
| 565 |
-
A counted range `i`+\[0, `n`) is valid if and only if `n == 0`; or `n`
|
| 566 |
-
is positive, `i` is dereferenceable, and `++i`+\[0, `
|
| 567 |
|
| 568 |
The result of the application of library functions to invalid ranges is
|
| 569 |
undefined.
|
| 570 |
|
| 571 |
All the categories of iterators require only those functions that are
|
|
@@ -661,10 +715,16 @@ template<class T>
|
|
| 661 |
requires is_object_v<T>
|
| 662 |
struct cond-value-type<T> {
|
| 663 |
using value_type = remove_cv_t<T>;
|
| 664 |
};
|
| 665 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 666 |
template<class> struct indirectly_readable_traits { };
|
| 667 |
|
| 668 |
template<class T>
|
| 669 |
struct indirectly_readable_traits<T*>
|
| 670 |
: cond-value-type<T> { };
|
|
@@ -677,20 +737,28 @@ struct indirectly_readable_traits<I> {
|
|
| 677 |
|
| 678 |
template<class I>
|
| 679 |
struct indirectly_readable_traits<const I>
|
| 680 |
: indirectly_readable_traits<I> { };
|
| 681 |
|
| 682 |
-
template<
|
| 683 |
-
requires requires { typename T::value_type; }
|
| 684 |
struct indirectly_readable_traits<T>
|
| 685 |
: cond-value-type<typename T::value_type> { };
|
| 686 |
|
| 687 |
-
template<
|
| 688 |
-
requires requires { typename T::element_type; }
|
| 689 |
struct indirectly_readable_traits<T>
|
| 690 |
: cond-value-type<typename T::element_type> { };
|
| 691 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 692 |
template<class T> using iter_value_t = see below;
|
| 693 |
```
|
| 694 |
|
| 695 |
Let R_`I` be `remove_cvref_t<I>`. The type `iter_value_t<I>` denotes
|
| 696 |
|
|
@@ -748,15 +816,15 @@ The definitions in this subclause make use of the following
|
|
| 748 |
exposition-only concepts:
|
| 749 |
|
| 750 |
``` cpp
|
| 751 |
template<class I>
|
| 752 |
concept cpp17-iterator =
|
| 753 |
-
|
| 754 |
{ *i } -> can-reference;
|
| 755 |
{ ++i } -> same_as<I&>;
|
| 756 |
{ *i++ } -> can-reference;
|
| 757 |
-
};
|
| 758 |
|
| 759 |
template<class I>
|
| 760 |
concept cpp17-input-iterator =
|
| 761 |
cpp17-iterator<I> && equality_comparable<I> && requires(I i) {
|
| 762 |
typename incrementable_traits<I>::difference_type;
|
|
@@ -769,11 +837,11 @@ concept cpp17-input-iterator =
|
|
| 769 |
};
|
| 770 |
|
| 771 |
template<class I>
|
| 772 |
concept cpp17-forward-iterator =
|
| 773 |
cpp17-input-iterator<I> && constructible_from<I> &&
|
| 774 |
-
|
| 775 |
same_as<remove_cvref_t<iter_reference_t<I>>,
|
| 776 |
typename indirectly_readable_traits<I>::value_type> &&
|
| 777 |
requires(I i) {
|
| 778 |
{ i++ } -> convertible_to<const I&>;
|
| 779 |
{ *i++ } -> same_as<iter_reference_t<I>>;
|
|
@@ -865,10 +933,16 @@ The members of a specialization `iterator_traits<I>` generated from the
|
|
| 865 |
|
| 866 |
Explicit or partial specializations of `iterator_traits` may have a
|
| 867 |
member type `iterator_concept` that is used to indicate conformance to
|
| 868 |
the iterator concepts [[iterator.concepts]].
|
| 869 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 870 |
`iterator_traits` is specialized for pointers as
|
| 871 |
|
| 872 |
``` cpp
|
| 873 |
namespace std {
|
| 874 |
template<class T>
|
|
@@ -882,11 +956,11 @@ namespace std {
|
|
| 882 |
using reference = T&;
|
| 883 |
};
|
| 884 |
}
|
| 885 |
```
|
| 886 |
|
| 887 |
-
[*Example
|
| 888 |
|
| 889 |
To implement a generic `reverse` function, a C++ program can do the
|
| 890 |
following:
|
| 891 |
|
| 892 |
``` cpp
|
|
@@ -905,26 +979,23 @@ void reverse(BI first, BI last) {
|
|
| 905 |
}
|
| 906 |
```
|
| 907 |
|
| 908 |
— *end example*]
|
| 909 |
|
| 910 |
-
### Customization
|
| 911 |
|
| 912 |
#### `ranges::iter_move` <a id="iterator.cust.move">[[iterator.cust.move]]</a>
|
| 913 |
|
| 914 |
The name `ranges::iter_move` denotes a customization point object
|
| 915 |
[[customization.point.object]]. The expression `ranges::iter_move(E)`
|
| 916 |
for a subexpression `E` is expression-equivalent to:
|
| 917 |
|
| 918 |
- `iter_move(E)`, if `E` has class or enumeration type and
|
| 919 |
`iter_move(E)` is a well-formed expression when treated as an
|
| 920 |
-
unevaluated operand,
|
| 921 |
-
|
| 922 |
-
|
| 923 |
-
``` cpp
|
| 924 |
-
void iter_move();
|
| 925 |
-
```
|
| 926 |
- Otherwise, if the expression `*E` is well-formed:
|
| 927 |
- if `*E` is an lvalue, `std::move(*E)`;
|
| 928 |
- otherwise, `*E`.
|
| 929 |
- Otherwise, `ranges::iter_move(E)` is ill-formed. \[*Note 1*: This case
|
| 930 |
can result in substitution failure when `ranges::iter_move(E)` appears
|
|
@@ -970,20 +1041,23 @@ The expression `ranges::iter_swap(E1, E2)` for subexpressions `E1` and
|
|
| 970 |
|
| 971 |
and does not include a declaration of `ranges::iter_swap`. If the
|
| 972 |
function selected by overload resolution does not exchange the values
|
| 973 |
denoted by `E1` and `E2`, the program is ill-formed, no diagnostic
|
| 974 |
required.
|
|
|
|
|
|
|
|
|
|
| 975 |
- Otherwise, if the types of `E1` and `E2` each model
|
| 976 |
`indirectly_readable`, and if the reference types of `E1` and `E2`
|
| 977 |
model `swappable_with` [[concept.swappable]], then
|
| 978 |
`ranges::swap(*E1, *E2)`.
|
| 979 |
- Otherwise, if the types `T1` and `T2` of `E1` and `E2` model
|
| 980 |
`indirectly_movable_storable<T1, T2>` and
|
| 981 |
`indirectly_movable_storable<T2, T1>`, then
|
| 982 |
`(void)(*E1 = iter-exchange-move(E2, E1))`, except that `E1` is
|
| 983 |
evaluated only once.
|
| 984 |
-
- Otherwise, `ranges::iter_swap(E1, E2)` is ill-formed. \[*Note
|
| 985 |
case can result in substitution failure when
|
| 986 |
`ranges::iter_swap(E1, E2)` appears in the immediate context of a
|
| 987 |
template instantiation. — *end note*]
|
| 988 |
|
| 989 |
### Iterator concepts <a id="iterator.concepts">[[iterator.concepts]]</a>
|
|
@@ -1018,11 +1092,10 @@ struct I {
|
|
| 1018 |
I operator++(int);
|
| 1019 |
I& operator--();
|
| 1020 |
I operator--(int);
|
| 1021 |
|
| 1022 |
bool operator==(I) const;
|
| 1023 |
-
bool operator!=(I) const;
|
| 1024 |
};
|
| 1025 |
```
|
| 1026 |
|
| 1027 |
`iterator_traits<I>::iterator_category` denotes `input_iterator_tag`,
|
| 1028 |
and `ITER_CONCEPT(I)` denotes `random_access_iterator_tag`.
|
|
@@ -1057,14 +1130,10 @@ template<class In>
|
|
| 1057 |
```
|
| 1058 |
|
| 1059 |
Given a value `i` of type `I`, `I` models `indirectly_readable` only if
|
| 1060 |
the expression `*i` is equality-preserving.
|
| 1061 |
|
| 1062 |
-
[*Note 1*: The expression `*i` is indirectly required to be valid via
|
| 1063 |
-
the exposition-only `dereferenceable` concept
|
| 1064 |
-
[[iterator.synopsis]]. — *end note*]
|
| 1065 |
-
|
| 1066 |
#### Concept <a id="iterator.concept.writable">[[iterator.concept.writable]]</a>
|
| 1067 |
|
| 1068 |
The `indirectly_writable` concept specifies the requirements for writing
|
| 1069 |
a value into an iterator’s referenced object.
|
| 1070 |
|
|
@@ -1084,11 +1153,11 @@ template<class Out, class T>
|
|
| 1084 |
Let `E` be an expression such that `decltype((E))` is `T`, and let `o`
|
| 1085 |
be a dereferenceable object of type `Out`. `Out` and `T` model
|
| 1086 |
`indirectly_writable<Out, T>` only if
|
| 1087 |
|
| 1088 |
- If `Out` and `T` model
|
| 1089 |
-
`indirectly_readable<Out> && same_as<iter_value_t<Out>, decay_t<T>
|
| 1090 |
then `*o` after any above assignment is equal to the value of `E`
|
| 1091 |
before the assignment.
|
| 1092 |
|
| 1093 |
After evaluating any above assignment expression, `o` is not required to
|
| 1094 |
be dereferenceable.
|
|
@@ -1114,99 +1183,126 @@ that can be incremented with the pre- and post-increment operators. The
|
|
| 1114 |
increment operations are not required to be equality-preserving, nor is
|
| 1115 |
the type required to be `equality_comparable`.
|
| 1116 |
|
| 1117 |
``` cpp
|
| 1118 |
template<class T>
|
| 1119 |
-
|
| 1120 |
|
| 1121 |
template<class T>
|
| 1122 |
-
|
| 1123 |
|
| 1124 |
template<class I>
|
| 1125 |
concept weakly_incrementable =
|
| 1126 |
-
|
| 1127 |
requires(I i) {
|
| 1128 |
typename iter_difference_t<I>;
|
| 1129 |
requires is-signed-integer-like<iter_difference_t<I>>;
|
| 1130 |
{ ++i } -> same_as<I&>; // not required to be equality-preserving
|
| 1131 |
i++; // not required to be equality-preserving
|
| 1132 |
};
|
| 1133 |
```
|
| 1134 |
|
| 1135 |
A type `I` is an *integer-class type* if it is in a set of
|
| 1136 |
-
implementation-defined
|
| 1137 |
-
defined
|
|
|
|
|
|
|
|
|
|
| 1138 |
|
| 1139 |
The range of representable values of an integer-class type is the
|
| 1140 |
-
continuous set of values over which it is defined.
|
| 1141 |
-
|
| 1142 |
-
|
| 1143 |
-
*signed-integer-class type*
|
| 1144 |
-
*unsigned-integer-class type*.
|
|
|
|
|
|
|
|
|
|
| 1145 |
|
| 1146 |
-
|
| 1147 |
-
|
| 1148 |
-
|
| 1149 |
-
|
|
|
|
|
|
|
| 1150 |
|
| 1151 |
-
|
| 1152 |
-
|
| 1153 |
-
as `
|
| 1154 |
-
type.
|
| 1155 |
|
| 1156 |
-
|
| 1157 |
-
|
| 1158 |
-
|
| 1159 |
-
|
| 1160 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1161 |
- For every assignment operator `@=` for which `c @= x` is well-formed,
|
| 1162 |
`c @= a` shall also be well-formed and shall have the same value and
|
| 1163 |
effects as `c @= x`. The expression `c @= a` shall be an lvalue
|
| 1164 |
referring to `c`.
|
| 1165 |
-
- For every
|
| 1166 |
-
`a @ b` shall also be well-formed and shall have the same
|
| 1167 |
-
|
| 1168 |
-
|
| 1169 |
-
|
| 1170 |
-
|
| 1171 |
-
|
| 1172 |
-
|
| 1173 |
-
|
| 1174 |
-
|
|
|
|
|
|
|
|
|
|
| 1175 |
|
| 1176 |
An expression `E` of integer-class type `I` is contextually convertible
|
| 1177 |
to `bool` as if by `bool(E != I(0))`.
|
| 1178 |
|
| 1179 |
All integer-class types model `regular` [[concepts.object]] and
|
| 1180 |
-
`
|
| 1181 |
|
| 1182 |
A value-initialized object of integer-class type has value 0.
|
| 1183 |
|
| 1184 |
For every (possibly cv-qualified) integer-class type `I`,
|
| 1185 |
-
`numeric_limits<I>` is specialized such that
|
|
|
|
|
|
|
| 1186 |
|
| 1187 |
-
- `
|
| 1188 |
-
- `
|
| 1189 |
-
|
| 1190 |
-
- `
|
| 1191 |
-
-
|
| 1192 |
-
- `numeric_limits<I>::digits` is equal to the width of the integer-class
|
| 1193 |
-
type,
|
| 1194 |
-
- `numeric_limits<I>::digits10` is equal to
|
| 1195 |
-
`static_cast<int>(digits * log10(2))`, and
|
| 1196 |
-
- `numeric_limits<I>::min()` and `numeric_limits<I>::max()` return the
|
| 1197 |
-
lowest and highest representable values of `I`, respectively, and
|
| 1198 |
-
`numeric_limits<I>::lowest()` returns `numeric_limits<I>::{}min()`.
|
| 1199 |
-
|
| 1200 |
-
A type `I` is *integer-like* if it models `integral<I>` or if it is an
|
| 1201 |
-
integer-class type. A type `I` is *signed-integer-like* if it models
|
| 1202 |
-
`signed_integral<I>` or if it is a signed-integer-class type. A type `I`
|
| 1203 |
-
is *unsigned-integer-like* if it models `unsigned_integral<I>` or if it
|
| 1204 |
-
is an unsigned-integer-class type.
|
| 1205 |
|
| 1206 |
`is-integer-like<I>` is `true` if and only if `I` is an integer-like
|
| 1207 |
-
type. `is-signed-integer-like<I>` is `true` if and only if I is a
|
| 1208 |
signed-integer-like type.
|
| 1209 |
|
| 1210 |
Let `i` be an object of type `I`. When `i` is in the domain of both pre-
|
| 1211 |
and post-increment, `i` is said to be *incrementable*. `I` models
|
| 1212 |
`weakly_incrementable<I>` only if
|
|
@@ -1215,17 +1311,20 @@ and post-increment, `i` is said to be *incrementable*. `I` models
|
|
| 1215 |
- If `i` is incrementable, then both `++i` and `i++` advance `i` to the
|
| 1216 |
next element.
|
| 1217 |
- If `i` is incrementable, then `addressof(++i)` is equal to
|
| 1218 |
`addressof(i)`.
|
| 1219 |
|
| 1220 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1221 |
imply that `++a` equals `++b`. (Equality does not guarantee the
|
| 1222 |
-
substitution property or referential transparency.)
|
| 1223 |
-
|
| 1224 |
-
|
| 1225 |
-
algorithms can be used with istreams as the source of the input data
|
| 1226 |
-
through the `istream_iterator` class template. — *end note*]
|
| 1227 |
|
| 1228 |
#### Concept <a id="iterator.concept.inc">[[iterator.concept.inc]]</a>
|
| 1229 |
|
| 1230 |
The `incrementable` concept specifies requirements on types that can be
|
| 1231 |
incremented with the pre- and post-increment operators. The increment
|
|
@@ -1262,13 +1361,12 @@ The `input_or_output_iterator` concept forms the basis of the iterator
|
|
| 1262 |
concept taxonomy; every iterator models `input_or_output_iterator`. This
|
| 1263 |
concept specifies operations for dereferencing and incrementing an
|
| 1264 |
iterator. Most algorithms will require additional operations to compare
|
| 1265 |
iterators with sentinels [[iterator.concept.sentinel]], to read
|
| 1266 |
[[iterator.concept.input]] or write [[iterator.concept.output]] values,
|
| 1267 |
-
or to provide a richer set of iterator movements
|
| 1268 |
-
[[iterator.concept.forward]], [[iterator.concept.bidir]],
|
| 1269 |
-
[[iterator.concept.random.access]]).
|
| 1270 |
|
| 1271 |
``` cpp
|
| 1272 |
template<class I>
|
| 1273 |
concept input_or_output_iterator =
|
| 1274 |
requires(I i) {
|
|
@@ -1290,19 +1388,20 @@ denote a range.
|
|
| 1290 |
``` cpp
|
| 1291 |
template<class S, class I>
|
| 1292 |
concept sentinel_for =
|
| 1293 |
semiregular<S> &&
|
| 1294 |
input_or_output_iterator<I> &&
|
| 1295 |
-
weakly-equality-comparable-with<S, I>;
|
| 1296 |
```
|
| 1297 |
|
| 1298 |
Let `s` and `i` be values of type `S` and `I` such that \[`i`, `s`)
|
| 1299 |
denotes a range. Types `S` and `I` model `sentinel_for<S, I>` only if
|
| 1300 |
|
| 1301 |
- `i == s` is well-defined.
|
| 1302 |
- If `bool(i != s)` then `i` is dereferenceable and \[`++i`, `s`)
|
| 1303 |
denotes a range.
|
|
|
|
| 1304 |
|
| 1305 |
The domain of `==` is not static. Given an iterator `i` and sentinel `s`
|
| 1306 |
such that \[`i`, `s`) denotes a range and `i != s`, `i` and `s` are not
|
| 1307 |
required to continue to denote a range after incrementing any other
|
| 1308 |
iterator equal to `i`. Consequently, `i == s` is no longer required to
|
|
@@ -1336,11 +1435,11 @@ and `I` model `sized_sentinel_for<S, I>` only if
|
|
| 1336 |
- If -N is representable by `iter_difference_t<I>`, then `i - s` is
|
| 1337 |
well-defined and equals -N.
|
| 1338 |
|
| 1339 |
``` cpp
|
| 1340 |
template<class S, class I>
|
| 1341 |
-
|
| 1342 |
```
|
| 1343 |
|
| 1344 |
*Remarks:* Pursuant to [[namespace.std]], users may specialize
|
| 1345 |
`disable_sized_sentinel_for` for cv-unqualified non-array object types
|
| 1346 |
`S` and `I` if `S` and/or `I` is a program-defined type. Such
|
|
@@ -1404,13 +1503,13 @@ be a dereferenceable object of type `I`. `I` and `T` model
|
|
| 1404 |
``` cpp
|
| 1405 |
*i = E;
|
| 1406 |
++i;
|
| 1407 |
```
|
| 1408 |
|
| 1409 |
-
|
| 1410 |
-
through the same iterator twice
|
| 1411 |
-
|
| 1412 |
|
| 1413 |
#### Concept <a id="iterator.concept.forward">[[iterator.concept.forward]]</a>
|
| 1414 |
|
| 1415 |
The `forward_iterator` concept adds copyability, equality comparison,
|
| 1416 |
and the multi-pass guarantee, specified below.
|
|
@@ -1438,11 +1537,11 @@ range.
|
|
| 1438 |
|
| 1439 |
Two dereferenceable iterators `a` and `b` of type `X` offer the
|
| 1440 |
*multi-pass guarantee* if:
|
| 1441 |
|
| 1442 |
- `a == b` implies `++a == ++b` and
|
| 1443 |
-
-
|
| 1444 |
expression `*a`.
|
| 1445 |
|
| 1446 |
[*Note 2*: The requirement that `a == b` implies `++a == ++b` and the
|
| 1447 |
removal of the restrictions on the number of assignments through a
|
| 1448 |
mutable iterator (which applies to output iterators) allow the use of
|
|
@@ -1548,15 +1647,21 @@ non-dereferenceable iterator of type `I` such that `b` is reachable from
|
|
| 1548 |
`a` and `c` is reachable from `b`, and let `D` be
|
| 1549 |
`iter_difference_t<I>`. The type `I` models `contiguous_iterator` only
|
| 1550 |
if
|
| 1551 |
|
| 1552 |
- `to_address(a) == addressof(*a)`,
|
| 1553 |
-
- `to_address(b) == to_address(a) + D(b - a)`,
|
| 1554 |
-
- `to_address(c) == to_address(a) + D(c - a)`
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1555 |
|
| 1556 |
### C++17 iterator requirements <a id="iterator.cpp17">[[iterator.cpp17]]</a>
|
| 1557 |
|
|
|
|
|
|
|
| 1558 |
In the following sections, `a` and `b` denote values of type `X` or
|
| 1559 |
`const X`, `difference_type` and `reference` refer to the types
|
| 1560 |
`iterator_traits<X>::difference_type` and
|
| 1561 |
`iterator_traits<X>::reference`, respectively, `n` denotes a value of
|
| 1562 |
`difference_type`, `u`, `tmp`, and `m` denote identifiers, `r` denotes a
|
|
@@ -1571,19 +1676,18 @@ value of some type that is writable to the output iterator.
|
|
| 1571 |
The *Cpp17Iterator* requirements form the basis of the iterator
|
| 1572 |
taxonomy; every iterator meets the *Cpp17Iterator* requirements. This
|
| 1573 |
set of requirements specifies operations for dereferencing and
|
| 1574 |
incrementing an iterator. Most algorithms will require additional
|
| 1575 |
operations to read [[input.iterators]] or write [[output.iterators]]
|
| 1576 |
-
values, or to provide a richer set of iterator movements
|
| 1577 |
-
[[forward.iterators]], [[bidirectional.iterators]],
|
| 1578 |
-
[[random.access.iterators]]).
|
| 1579 |
|
| 1580 |
-
A type `X` meets the
|
| 1581 |
|
| 1582 |
-
- `X` meets the *Cpp17CopyConstructible*, *Cpp17CopyAssignable*,
|
| 1583 |
-
*
|
| 1584 |
-
|
| 1585 |
- `iterator_traits<X>::difference_type` is a signed integer type or
|
| 1586 |
`void`, and
|
| 1587 |
- the expressions in [[iterator]] are valid and have the indicated
|
| 1588 |
semantics.
|
| 1589 |
|
|
@@ -1605,31 +1709,35 @@ uses that algorithm makes of `==` and `!=`.
|
|
| 1605 |
[*Example 1*: The call `find(a,b,x)` is defined only if the value of
|
| 1606 |
`a` has the property *p* defined as follows: `b` has property *p* and a
|
| 1607 |
value `i` has property *p* if (`*i==x`) or if (`*i!=x` and `++i` has
|
| 1608 |
property *p*). — *end example*]
|
| 1609 |
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1610 |
[*Note 1*: For input iterators, `a == b` does not imply `++a == ++b`.
|
| 1611 |
(Equality does not guarantee the substitution property or referential
|
| 1612 |
-
transparency.)
|
| 1613 |
-
|
| 1614 |
-
|
| 1615 |
-
|
| 1616 |
-
istreams as the source of the input data through the `istream_iterator`
|
| 1617 |
-
class template. — *end note*]
|
| 1618 |
|
| 1619 |
#### Output iterators <a id="output.iterators">[[output.iterators]]</a>
|
| 1620 |
|
| 1621 |
A class or pointer type `X` meets the requirements of an output iterator
|
| 1622 |
if `X` meets the *Cpp17Iterator* requirements [[iterator.iterators]] and
|
| 1623 |
the expressions in [[outputiterator]] are valid and have the indicated
|
| 1624 |
semantics.
|
| 1625 |
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1626 |
[*Note 1*: The only valid use of an `operator*` is on the left side of
|
| 1627 |
the assignment statement. Assignment through the same value of the
|
| 1628 |
-
iterator happens only once.
|
| 1629 |
-
attempt to pass through the same iterator twice. They should be
|
| 1630 |
-
single-pass algorithms. Equality and inequality might not be
|
| 1631 |
defined. — *end note*]
|
| 1632 |
|
| 1633 |
#### Forward iterators <a id="forward.iterators">[[forward.iterators]]</a>
|
| 1634 |
|
| 1635 |
A class or pointer type `X` meets the requirements of a forward iterator
|
|
@@ -1691,85 +1799,95 @@ requirements, the following expressions are valid as shown in
|
|
| 1691 |
### Indirect callable requirements <a id="indirectcallable">[[indirectcallable]]</a>
|
| 1692 |
|
| 1693 |
#### General <a id="indirectcallable.general">[[indirectcallable.general]]</a>
|
| 1694 |
|
| 1695 |
There are several concepts that group requirements of algorithms that
|
| 1696 |
-
take callable objects
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1697 |
|
| 1698 |
#### Indirect callables <a id="indirectcallable.indirectinvocable">[[indirectcallable.indirectinvocable]]</a>
|
| 1699 |
|
| 1700 |
The indirect callable concepts are used to constrain those algorithms
|
| 1701 |
-
that accept callable objects
|
| 1702 |
|
| 1703 |
``` cpp
|
| 1704 |
namespace std {
|
| 1705 |
template<class F, class I>
|
| 1706 |
concept indirectly_unary_invocable =
|
| 1707 |
indirectly_readable<I> &&
|
| 1708 |
copy_constructible<F> &&
|
| 1709 |
-
invocable<F&,
|
| 1710 |
invocable<F&, iter_reference_t<I>> &&
|
| 1711 |
invocable<F&, iter_common_reference_t<I>> &&
|
| 1712 |
common_reference_with<
|
| 1713 |
-
invoke_result_t<F&,
|
| 1714 |
invoke_result_t<F&, iter_reference_t<I>>>;
|
| 1715 |
|
| 1716 |
template<class F, class I>
|
| 1717 |
concept indirectly_regular_unary_invocable =
|
| 1718 |
indirectly_readable<I> &&
|
| 1719 |
copy_constructible<F> &&
|
| 1720 |
-
regular_invocable<F&,
|
| 1721 |
regular_invocable<F&, iter_reference_t<I>> &&
|
| 1722 |
regular_invocable<F&, iter_common_reference_t<I>> &&
|
| 1723 |
common_reference_with<
|
| 1724 |
-
invoke_result_t<F&,
|
| 1725 |
invoke_result_t<F&, iter_reference_t<I>>>;
|
| 1726 |
|
| 1727 |
template<class F, class I>
|
| 1728 |
concept indirect_unary_predicate =
|
| 1729 |
indirectly_readable<I> &&
|
| 1730 |
copy_constructible<F> &&
|
| 1731 |
-
predicate<F&,
|
| 1732 |
predicate<F&, iter_reference_t<I>> &&
|
| 1733 |
predicate<F&, iter_common_reference_t<I>>;
|
| 1734 |
|
| 1735 |
template<class F, class I1, class I2>
|
| 1736 |
concept indirect_binary_predicate =
|
| 1737 |
indirectly_readable<I1> && indirectly_readable<I2> &&
|
| 1738 |
copy_constructible<F> &&
|
| 1739 |
-
predicate<F&,
|
| 1740 |
-
predicate<F&,
|
| 1741 |
-
predicate<F&, iter_reference_t<I1>,
|
| 1742 |
predicate<F&, iter_reference_t<I1>, iter_reference_t<I2>> &&
|
| 1743 |
predicate<F&, iter_common_reference_t<I1>, iter_common_reference_t<I2>>;
|
| 1744 |
|
| 1745 |
template<class F, class I1, class I2 = I1>
|
| 1746 |
concept indirect_equivalence_relation =
|
| 1747 |
indirectly_readable<I1> && indirectly_readable<I2> &&
|
| 1748 |
copy_constructible<F> &&
|
| 1749 |
-
equivalence_relation<F&,
|
| 1750 |
-
equivalence_relation<F&,
|
| 1751 |
-
equivalence_relation<F&, iter_reference_t<I1>,
|
| 1752 |
equivalence_relation<F&, iter_reference_t<I1>, iter_reference_t<I2>> &&
|
| 1753 |
equivalence_relation<F&, iter_common_reference_t<I1>, iter_common_reference_t<I2>>;
|
| 1754 |
|
| 1755 |
template<class F, class I1, class I2 = I1>
|
| 1756 |
concept indirect_strict_weak_order =
|
| 1757 |
indirectly_readable<I1> && indirectly_readable<I2> &&
|
| 1758 |
copy_constructible<F> &&
|
| 1759 |
-
strict_weak_order<F&,
|
| 1760 |
-
strict_weak_order<F&,
|
| 1761 |
-
strict_weak_order<F&, iter_reference_t<I1>,
|
| 1762 |
strict_weak_order<F&, iter_reference_t<I1>, iter_reference_t<I2>> &&
|
| 1763 |
strict_weak_order<F&, iter_common_reference_t<I1>, iter_common_reference_t<I2>>;
|
| 1764 |
}
|
| 1765 |
```
|
| 1766 |
|
| 1767 |
#### Class template `projected` <a id="projected">[[projected]]</a>
|
| 1768 |
|
| 1769 |
Class template `projected` is used to constrain algorithms that accept
|
| 1770 |
-
callable objects and projections [[defns.projection]]. It combines
|
| 1771 |
`indirectly_readable` type `I` and a callable object type `Proj` into a
|
| 1772 |
new `indirectly_readable` type whose `reference` type is the result of
|
| 1773 |
applying `Proj` to the `iter_reference_t` of `I`.
|
| 1774 |
|
| 1775 |
``` cpp
|
|
@@ -1805,12 +1923,12 @@ different sequences: `indirectly_comparable`.
|
|
| 1805 |
below imposes constraints on the concepts’ arguments in addition to
|
| 1806 |
those that appear in the concepts’ bodies [[range.cmp]]. — *end note*]
|
| 1807 |
|
| 1808 |
#### Concept <a id="alg.req.ind.move">[[alg.req.ind.move]]</a>
|
| 1809 |
|
| 1810 |
-
The `indirectly_movable` concept specifies the relationship between
|
| 1811 |
-
`indirectly_readable` type and
|
| 1812 |
which values may be moved.
|
| 1813 |
|
| 1814 |
``` cpp
|
| 1815 |
template<class In, class Out>
|
| 1816 |
concept indirectly_movable =
|
|
@@ -1846,12 +1964,12 @@ iter_value_t<In> obj(ranges::iter_move(i));
|
|
| 1846 |
state of the value denoted by `*i` is valid but unspecified
|
| 1847 |
[[lib.types.movedfrom]].
|
| 1848 |
|
| 1849 |
#### Concept <a id="alg.req.ind.copy">[[alg.req.ind.copy]]</a>
|
| 1850 |
|
| 1851 |
-
The `indirectly_copyable` concept specifies the relationship between
|
| 1852 |
-
`indirectly_readable` type and
|
| 1853 |
which values may be copied.
|
| 1854 |
|
| 1855 |
``` cpp
|
| 1856 |
template<class In, class Out>
|
| 1857 |
concept indirectly_copyable =
|
|
@@ -1962,10 +2080,12 @@ template<class I, class R = ranges::less, class P = identity>
|
|
| 1962 |
indirect_strict_weak_order<R, projected<I, P>>;
|
| 1963 |
```
|
| 1964 |
|
| 1965 |
## Iterator primitives <a id="iterator.primitives">[[iterator.primitives]]</a>
|
| 1966 |
|
|
|
|
|
|
|
| 1967 |
To simplify the use of iterators, the library provides several classes
|
| 1968 |
and functions.
|
| 1969 |
|
| 1970 |
### Standard iterator tags <a id="std.iterator.tags">[[std.iterator.tags]]</a>
|
| 1971 |
|
|
@@ -1993,13 +2113,13 @@ namespace std {
|
|
| 1993 |
}
|
| 1994 |
```
|
| 1995 |
|
| 1996 |
[*Example 1*:
|
| 1997 |
|
| 1998 |
-
|
| 1999 |
-
|
| 2000 |
-
|
| 2001 |
|
| 2002 |
``` cpp
|
| 2003 |
template<class T> struct iterator_traits<BinaryTreeIterator<T>> {
|
| 2004 |
using iterator_category = bidirectional_iterator_tag;
|
| 2005 |
using difference_type = ptrdiff_t;
|
|
@@ -2067,12 +2187,12 @@ template<class InputIterator>
|
|
| 2067 |
*Preconditions:* `last` is reachable from `first`, or `InputIterator`
|
| 2068 |
meets the *Cpp17RandomAccessIterator* requirements and `first` is
|
| 2069 |
reachable from `last`.
|
| 2070 |
|
| 2071 |
*Effects:* If `InputIterator` meets the *Cpp17RandomAccessIterator*
|
| 2072 |
-
requirements, returns `(last - first)`; otherwise,
|
| 2073 |
-
|
| 2074 |
|
| 2075 |
``` cpp
|
| 2076 |
template<class InputIterator>
|
| 2077 |
constexpr InputIterator next(InputIterator x,
|
| 2078 |
typename iterator_traits<InputIterator>::difference_type n = 1);
|
|
@@ -2088,10 +2208,12 @@ template<class BidirectionalIterator>
|
|
| 2088 |
|
| 2089 |
*Effects:* Equivalent to: `advance(x, -n); return x;`
|
| 2090 |
|
| 2091 |
### Range iterator operations <a id="range.iter.ops">[[range.iter.ops]]</a>
|
| 2092 |
|
|
|
|
|
|
|
| 2093 |
The library includes the function templates `ranges::advance`,
|
| 2094 |
`ranges::distance`, `ranges::next`, and `ranges::prev` to manipulate
|
| 2095 |
iterators. These operations adapt to the set of operators provided by
|
| 2096 |
each iterator category to provide the most efficient implementation
|
| 2097 |
possible for a concrete iterator type.
|
|
@@ -2100,11 +2222,11 @@ possible for a concrete iterator type.
|
|
| 2100 |
`random_access_iterator` forward `n` steps in constant time. For an
|
| 2101 |
iterator type that does not model `random_access_iterator`,
|
| 2102 |
`ranges::advance` instead performs `n` individual increments with the
|
| 2103 |
`++` operator. — *end example*]
|
| 2104 |
|
| 2105 |
-
The function templates defined in
|
| 2106 |
argument-dependent name lookup [[basic.lookup.argdep]]. When found by
|
| 2107 |
unqualified [[basic.lookup.unqual]] name lookup for the
|
| 2108 |
*postfix-expression* in a function call [[expr.call]], they inhibit
|
| 2109 |
argument-dependent name lookup.
|
| 2110 |
|
|
@@ -2119,18 +2241,18 @@ void foo() {
|
|
| 2119 |
```
|
| 2120 |
|
| 2121 |
The function call expression at `#1` invokes `std::ranges::distance`,
|
| 2122 |
not `std::distance`, despite that (a) the iterator type returned from
|
| 2123 |
`begin(vec)` and `end(vec)` may be associated with namespace `std` and
|
| 2124 |
-
(b) `std::distance` is more specialized
|
| 2125 |
`std::ranges::distance` since the former requires its first two
|
| 2126 |
parameters to have the same type.
|
| 2127 |
|
| 2128 |
— *end example*]
|
| 2129 |
|
| 2130 |
The number and order of deducible template parameters for the function
|
| 2131 |
-
templates defined in
|
| 2132 |
explicitly stated otherwise.
|
| 2133 |
|
| 2134 |
#### `ranges::advance` <a id="range.iter.op.advance">[[range.iter.op.advance]]</a>
|
| 2135 |
|
| 2136 |
``` cpp
|
|
@@ -2150,11 +2272,13 @@ not negative.
|
|
| 2150 |
``` cpp
|
| 2151 |
template<input_or_output_iterator I, sentinel_for<I> S>
|
| 2152 |
constexpr void ranges::advance(I& i, S bound);
|
| 2153 |
```
|
| 2154 |
|
| 2155 |
-
*Preconditions:*
|
|
|
|
|
|
|
| 2156 |
|
| 2157 |
*Effects:*
|
| 2158 |
|
| 2159 |
- If `I` and `S` model `assignable_from<I&, S>`, equivalent to
|
| 2160 |
`i = std::move(bound)`.
|
|
@@ -2187,21 +2311,27 @@ template<input_or_output_iterator I, sentinel_for<I> S>
|
|
| 2187 |
starting positions of `i`.
|
| 2188 |
|
| 2189 |
#### `ranges::distance` <a id="range.iter.op.distance">[[range.iter.op.distance]]</a>
|
| 2190 |
|
| 2191 |
``` cpp
|
| 2192 |
-
template<
|
|
|
|
| 2193 |
constexpr iter_difference_t<I> ranges::distance(I first, S last);
|
| 2194 |
```
|
| 2195 |
|
| 2196 |
-
*Preconditions:* \[`first`, `last`) denotes a range
|
| 2197 |
-
`first`) denotes a range and `S` and `I` model
|
| 2198 |
-
`same_as<S, I> && sized_sentinel_for<S, I>`.
|
| 2199 |
|
| 2200 |
-
*Effects:*
|
| 2201 |
-
|
| 2202 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 2203 |
|
| 2204 |
``` cpp
|
| 2205 |
template<range R>
|
| 2206 |
constexpr range_difference_t<R> ranges::distance(R&& r);
|
| 2207 |
```
|
|
@@ -2253,11 +2383,11 @@ template<input_or_output_iterator I, sentinel_for<I> S>
|
|
| 2253 |
``` cpp
|
| 2254 |
template<bidirectional_iterator I>
|
| 2255 |
constexpr I ranges::prev(I x);
|
| 2256 |
```
|
| 2257 |
|
| 2258 |
-
*Effects:* Equivalent to: `
|
| 2259 |
|
| 2260 |
``` cpp
|
| 2261 |
template<bidirectional_iterator I>
|
| 2262 |
constexpr I ranges::prev(I x, iter_difference_t<I> n);
|
| 2263 |
```
|
|
@@ -2273,10 +2403,12 @@ template<bidirectional_iterator I>
|
|
| 2273 |
|
| 2274 |
## Iterator adaptors <a id="predef.iterators">[[predef.iterators]]</a>
|
| 2275 |
|
| 2276 |
### Reverse iterators <a id="reverse.iterators">[[reverse.iterators]]</a>
|
| 2277 |
|
|
|
|
|
|
|
| 2278 |
Class template `reverse_iterator` is an iterator adaptor that iterates
|
| 2279 |
from the end of the sequence defined by its underlying iterator to the
|
| 2280 |
beginning of that sequence.
|
| 2281 |
|
| 2282 |
#### Class template `reverse_iterator` <a id="reverse.iterator">[[reverse.iterator]]</a>
|
|
@@ -2381,26 +2513,33 @@ constexpr explicit reverse_iterator(Iterator x);
|
|
| 2381 |
|
| 2382 |
``` cpp
|
| 2383 |
template<class U> constexpr reverse_iterator(const reverse_iterator<U>& u);
|
| 2384 |
```
|
| 2385 |
|
|
|
|
|
|
|
|
|
|
| 2386 |
*Effects:* Initializes `current` with `u.current`.
|
| 2387 |
|
| 2388 |
``` cpp
|
| 2389 |
template<class U>
|
| 2390 |
constexpr reverse_iterator&
|
| 2391 |
operator=(const reverse_iterator<U>& u);
|
| 2392 |
```
|
| 2393 |
|
| 2394 |
-
*
|
|
|
|
|
|
|
|
|
|
|
|
|
| 2395 |
|
| 2396 |
*Returns:* `*this`.
|
| 2397 |
|
| 2398 |
#### Conversion <a id="reverse.iter.conv">[[reverse.iter.conv]]</a>
|
| 2399 |
|
| 2400 |
``` cpp
|
| 2401 |
-
constexpr Iterator base() const;
|
| 2402 |
```
|
| 2403 |
|
| 2404 |
*Returns:* `current`.
|
| 2405 |
|
| 2406 |
#### Element access <a id="reverse.iter.elem">[[reverse.iter.elem]]</a>
|
|
@@ -2450,11 +2589,11 @@ constexpr reverse_iterator operator-(difference_type n) const;
|
|
| 2450 |
|
| 2451 |
``` cpp
|
| 2452 |
constexpr reverse_iterator& operator++();
|
| 2453 |
```
|
| 2454 |
|
| 2455 |
-
*Effects:* As if by: `current;`
|
| 2456 |
|
| 2457 |
*Returns:* `*this`.
|
| 2458 |
|
| 2459 |
``` cpp
|
| 2460 |
constexpr reverse_iterator operator++(int);
|
|
@@ -2602,11 +2741,11 @@ template<class Iterator1, class Iterator2>
|
|
| 2602 |
*Returns:* `y.base() - x.base()`.
|
| 2603 |
|
| 2604 |
``` cpp
|
| 2605 |
template<class Iterator>
|
| 2606 |
constexpr reverse_iterator<Iterator> operator+(
|
| 2607 |
-
|
| 2608 |
const reverse_iterator<Iterator>& x);
|
| 2609 |
```
|
| 2610 |
|
| 2611 |
*Returns:* `reverse_iterator<Iterator>(x.base() - n)`.
|
| 2612 |
|
|
@@ -2620,11 +2759,11 @@ friend constexpr iter_rvalue_reference_t<Iterator>
|
|
| 2620 |
``` cpp
|
| 2621 |
auto tmp = i.base();
|
| 2622 |
return ranges::iter_move(--tmp);
|
| 2623 |
```
|
| 2624 |
|
| 2625 |
-
*Remarks:* The
|
| 2626 |
|
| 2627 |
``` cpp
|
| 2628 |
is_nothrow_copy_constructible_v<Iterator> &&
|
| 2629 |
noexcept(ranges::iter_move(--declval<Iterator&>()))
|
| 2630 |
```
|
|
@@ -2642,11 +2781,11 @@ template<indirectly_swappable<Iterator> Iterator2>
|
|
| 2642 |
auto xtmp = x.base();
|
| 2643 |
auto ytmp = y.base();
|
| 2644 |
ranges::iter_swap(--xtmp, --ytmp);
|
| 2645 |
```
|
| 2646 |
|
| 2647 |
-
*Remarks:* The
|
| 2648 |
|
| 2649 |
``` cpp
|
| 2650 |
is_nothrow_copy_constructible_v<Iterator> &&
|
| 2651 |
is_nothrow_copy_constructible_v<Iterator2> &&
|
| 2652 |
noexcept(ranges::iter_swap(--declval<Iterator&>(), --declval<Iterator2&>()))
|
|
@@ -2659,10 +2798,12 @@ template<class Iterator>
|
|
| 2659 |
|
| 2660 |
*Returns:* `reverse_iterator<Iterator>(i)`.
|
| 2661 |
|
| 2662 |
### Insert iterators <a id="insert.iterators">[[insert.iterators]]</a>
|
| 2663 |
|
|
|
|
|
|
|
| 2664 |
To make it possible to deal with insertion in the same way as writing
|
| 2665 |
into an array, a special kind of iterator adaptors, called *insert
|
| 2666 |
iterators*, are provided in the library. With regular iterator classes,
|
| 2667 |
|
| 2668 |
``` cpp
|
|
@@ -2695,21 +2836,20 @@ iterators out of a container.
|
|
| 2695 |
``` cpp
|
| 2696 |
namespace std {
|
| 2697 |
template<class Container>
|
| 2698 |
class back_insert_iterator {
|
| 2699 |
protected:
|
| 2700 |
-
Container* container
|
| 2701 |
|
| 2702 |
public:
|
| 2703 |
using iterator_category = output_iterator_tag;
|
| 2704 |
using value_type = void;
|
| 2705 |
using difference_type = ptrdiff_t;
|
| 2706 |
using pointer = void;
|
| 2707 |
using reference = void;
|
| 2708 |
using container_type = Container;
|
| 2709 |
|
| 2710 |
-
constexpr back_insert_iterator() noexcept = default;
|
| 2711 |
constexpr explicit back_insert_iterator(Container& x);
|
| 2712 |
constexpr back_insert_iterator& operator=(const typename Container::value_type& value);
|
| 2713 |
constexpr back_insert_iterator& operator=(typename Container::value_type&& value);
|
| 2714 |
|
| 2715 |
constexpr back_insert_iterator& operator*();
|
|
@@ -2770,21 +2910,20 @@ template<class Container>
|
|
| 2770 |
``` cpp
|
| 2771 |
namespace std {
|
| 2772 |
template<class Container>
|
| 2773 |
class front_insert_iterator {
|
| 2774 |
protected:
|
| 2775 |
-
Container* container
|
| 2776 |
|
| 2777 |
public:
|
| 2778 |
using iterator_category = output_iterator_tag;
|
| 2779 |
using value_type = void;
|
| 2780 |
using difference_type = ptrdiff_t;
|
| 2781 |
using pointer = void;
|
| 2782 |
using reference = void;
|
| 2783 |
using container_type = Container;
|
| 2784 |
|
| 2785 |
-
constexpr front_insert_iterator() noexcept = default;
|
| 2786 |
constexpr explicit front_insert_iterator(Container& x);
|
| 2787 |
constexpr front_insert_iterator& operator=(const typename Container::value_type& value);
|
| 2788 |
constexpr front_insert_iterator& operator=(typename Container::value_type&& value);
|
| 2789 |
|
| 2790 |
constexpr front_insert_iterator& operator*();
|
|
@@ -2845,22 +2984,21 @@ template<class Container>
|
|
| 2845 |
``` cpp
|
| 2846 |
namespace std {
|
| 2847 |
template<class Container>
|
| 2848 |
class insert_iterator {
|
| 2849 |
protected:
|
| 2850 |
-
Container* container
|
| 2851 |
-
ranges::iterator_t<Container> iter
|
| 2852 |
|
| 2853 |
public:
|
| 2854 |
using iterator_category = output_iterator_tag;
|
| 2855 |
using value_type = void;
|
| 2856 |
using difference_type = ptrdiff_t;
|
| 2857 |
using pointer = void;
|
| 2858 |
using reference = void;
|
| 2859 |
using container_type = Container;
|
| 2860 |
|
| 2861 |
-
insert_iterator() = default;
|
| 2862 |
constexpr insert_iterator(Container& x, ranges::iterator_t<Container> i);
|
| 2863 |
constexpr insert_iterator& operator=(const typename Container::value_type& value);
|
| 2864 |
constexpr insert_iterator& operator=(typename Container::value_type&& value);
|
| 2865 |
|
| 2866 |
constexpr insert_iterator& operator*();
|
|
@@ -2926,12 +3064,425 @@ template<class Container>
|
|
| 2926 |
inserter(Container& x, ranges::iterator_t<Container> i);
|
| 2927 |
```
|
| 2928 |
|
| 2929 |
*Returns:* `insert_iterator<Container>(x, i)`.
|
| 2930 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 2931 |
### Move iterators and sentinels <a id="move.iterators">[[move.iterators]]</a>
|
| 2932 |
|
|
|
|
|
|
|
| 2933 |
Class template `move_iterator` is an iterator adaptor with the same
|
| 2934 |
behavior as the underlying iterator except that its indirection operator
|
| 2935 |
implicitly converts the value returned by the underlying iterator’s
|
| 2936 |
indirection operator to an rvalue. Some generic algorithms can be called
|
| 2937 |
with move iterators to replace copying with moving.
|
|
@@ -2954,24 +3505,24 @@ vector<string> v2(make_move_iterator(s.begin()),
|
|
| 2954 |
namespace std {
|
| 2955 |
template<class Iterator>
|
| 2956 |
class move_iterator {
|
| 2957 |
public:
|
| 2958 |
using iterator_type = Iterator;
|
| 2959 |
-
using iterator_concept =
|
| 2960 |
-
using iterator_category = see below;
|
| 2961 |
using value_type = iter_value_t<Iterator>;
|
| 2962 |
using difference_type = iter_difference_t<Iterator>;
|
| 2963 |
using pointer = Iterator;
|
| 2964 |
using reference = iter_rvalue_reference_t<Iterator>;
|
| 2965 |
|
| 2966 |
constexpr move_iterator();
|
| 2967 |
constexpr explicit move_iterator(Iterator i);
|
| 2968 |
template<class U> constexpr move_iterator(const move_iterator<U>& u);
|
| 2969 |
template<class U> constexpr move_iterator& operator=(const move_iterator<U>& u);
|
| 2970 |
|
| 2971 |
-
constexpr
|
| 2972 |
-
constexpr
|
| 2973 |
constexpr reference operator*() const;
|
| 2974 |
|
| 2975 |
constexpr move_iterator& operator++();
|
| 2976 |
constexpr auto operator++(int);
|
| 2977 |
constexpr move_iterator& operator--();
|
|
@@ -3004,11 +3555,23 @@ namespace std {
|
|
| 3004 |
Iterator current; // exposition only
|
| 3005 |
};
|
| 3006 |
}
|
| 3007 |
```
|
| 3008 |
|
| 3009 |
-
The member *typedef-name* `
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 3010 |
|
| 3011 |
- `random_access_iterator_tag` if the type
|
| 3012 |
`iterator_traits<{}Iterator>::iterator_category` models
|
| 3013 |
`derived_from<random_access_iterator_tag>`, and
|
| 3014 |
- `iterator_traits<{}Iterator>::iterator_category` otherwise.
|
|
@@ -3031,49 +3594,45 @@ parameter shall either meet the *Cpp17RandomAccessIterator* requirements
|
|
| 3031 |
|
| 3032 |
``` cpp
|
| 3033 |
constexpr move_iterator();
|
| 3034 |
```
|
| 3035 |
|
| 3036 |
-
*Effects:*
|
| 3037 |
-
Iterator operations applied to the resulting iterator have defined
|
| 3038 |
-
behavior if and only if the corresponding operations are defined on a
|
| 3039 |
-
value-initialized iterator of type `Iterator`.
|
| 3040 |
|
| 3041 |
``` cpp
|
| 3042 |
constexpr explicit move_iterator(Iterator i);
|
| 3043 |
```
|
| 3044 |
|
| 3045 |
-
*Effects:*
|
| 3046 |
-
`std::move(i)`.
|
| 3047 |
|
| 3048 |
``` cpp
|
| 3049 |
template<class U> constexpr move_iterator(const move_iterator<U>& u);
|
| 3050 |
```
|
| 3051 |
|
| 3052 |
-
*
|
|
|
|
| 3053 |
|
| 3054 |
-
*Effects:*
|
| 3055 |
-
`u.base()`.
|
| 3056 |
|
| 3057 |
``` cpp
|
| 3058 |
template<class U> constexpr move_iterator& operator=(const move_iterator<U>& u);
|
| 3059 |
```
|
| 3060 |
|
| 3061 |
-
*
|
|
|
|
|
|
|
| 3062 |
|
| 3063 |
-
*Effects:* Assigns `u.
|
|
|
|
|
|
|
| 3064 |
|
| 3065 |
#### Conversion <a id="move.iter.op.conv">[[move.iter.op.conv]]</a>
|
| 3066 |
|
| 3067 |
``` cpp
|
| 3068 |
-
constexpr Iterator base() const &;
|
| 3069 |
```
|
| 3070 |
|
| 3071 |
-
*Constraints:* `Iterator` satisfies `copy_constructible`.
|
| 3072 |
-
|
| 3073 |
-
*Preconditions:* `Iterator` models `copy_constructible`.
|
| 3074 |
-
|
| 3075 |
*Returns:* `current`.
|
| 3076 |
|
| 3077 |
``` cpp
|
| 3078 |
constexpr Iterator base() &&;
|
| 3079 |
```
|
|
@@ -3090,11 +3649,11 @@ constexpr reference operator*() const;
|
|
| 3090 |
|
| 3091 |
``` cpp
|
| 3092 |
constexpr reference operator[](difference_type n) const;
|
| 3093 |
```
|
| 3094 |
|
| 3095 |
-
*Effects:* Equivalent to: `ranges::iter_move(current + n);`
|
| 3096 |
|
| 3097 |
#### Navigation <a id="move.iter.nav">[[move.iter.nav]]</a>
|
| 3098 |
|
| 3099 |
``` cpp
|
| 3100 |
constexpr move_iterator& operator++();
|
|
@@ -3120,11 +3679,11 @@ Otherwise, equivalent to `++current`.
|
|
| 3120 |
|
| 3121 |
``` cpp
|
| 3122 |
constexpr move_iterator& operator--();
|
| 3123 |
```
|
| 3124 |
|
| 3125 |
-
*Effects:* As if by `current`.
|
| 3126 |
|
| 3127 |
*Returns:* `*this`.
|
| 3128 |
|
| 3129 |
``` cpp
|
| 3130 |
constexpr move_iterator operator--(int);
|
|
@@ -3233,12 +3792,12 @@ template<class Iterator1, three_way_comparable_with<Iterator1> Iterator2>
|
|
| 3233 |
|
| 3234 |
#### Non-member functions <a id="move.iter.nonmember">[[move.iter.nonmember]]</a>
|
| 3235 |
|
| 3236 |
``` cpp
|
| 3237 |
template<class Iterator1, class Iterator2>
|
| 3238 |
-
constexpr auto operator-(
|
| 3239 |
-
|
| 3240 |
-> decltype(x.base() - y.base());
|
| 3241 |
template<sized_sentinel_for<Iterator> S>
|
| 3242 |
friend constexpr iter_difference_t<Iterator>
|
| 3243 |
operator-(const move_sentinel<S>& x, const move_iterator& y);
|
| 3244 |
template<sized_sentinel_for<Iterator> S>
|
|
@@ -3252,11 +3811,11 @@ template<sized_sentinel_for<Iterator> S>
|
|
| 3252 |
template<class Iterator>
|
| 3253 |
constexpr move_iterator<Iterator>
|
| 3254 |
operator+(iter_difference_t<Iterator> n, const move_iterator<Iterator>& x);
|
| 3255 |
```
|
| 3256 |
|
| 3257 |
-
*Constraints:* `x + n` is well-formed and has type `Iterator`.
|
| 3258 |
|
| 3259 |
*Returns:* `x + n`.
|
| 3260 |
|
| 3261 |
``` cpp
|
| 3262 |
friend constexpr iter_rvalue_reference_t<Iterator>
|
|
@@ -3286,11 +3845,11 @@ constexpr move_iterator<Iterator> make_move_iterator(Iterator i);
|
|
| 3286 |
|
| 3287 |
Class template `move_sentinel` is a sentinel adaptor useful for denoting
|
| 3288 |
ranges together with `move_iterator`. When an input iterator type `I`
|
| 3289 |
and sentinel type `S` model `sentinel_for<S, I>`, `move_sentinel<S>` and
|
| 3290 |
`move_iterator<I>` model
|
| 3291 |
-
`sentinel_for<move_sentinel<S>, move_iterator<I>
|
| 3292 |
|
| 3293 |
[*Example 1*:
|
| 3294 |
|
| 3295 |
A `move_if` algorithm is easily implemented with `copy_if` using
|
| 3296 |
`move_iterator` and `move_sentinel`:
|
|
@@ -3298,11 +3857,12 @@ A `move_if` algorithm is easily implemented with `copy_if` using
|
|
| 3298 |
``` cpp
|
| 3299 |
template<input_iterator I, sentinel_for<I> S, weakly_incrementable O,
|
| 3300 |
indirect_unary_predicate<I> Pred>
|
| 3301 |
requires indirectly_movable<I, O>
|
| 3302 |
void move_if(I first, S last, O out, Pred pred) {
|
| 3303 |
-
|
|
|
|
| 3304 |
}
|
| 3305 |
```
|
| 3306 |
|
| 3307 |
— *end example*]
|
| 3308 |
|
|
@@ -3319,10 +3879,11 @@ namespace std {
|
|
| 3319 |
template<class S2>
|
| 3320 |
requires assignable_from<S&, const S2&>
|
| 3321 |
constexpr move_sentinel& operator=(const move_sentinel<S2>& s);
|
| 3322 |
|
| 3323 |
constexpr S base() const;
|
|
|
|
| 3324 |
private:
|
| 3325 |
S last; // exposition only
|
| 3326 |
};
|
| 3327 |
}
|
| 3328 |
```
|
|
@@ -3398,50 +3959,50 @@ fun(CI(counted_iterator(s.begin(), 10)), CI(default_sentinel));
|
|
| 3398 |
namespace std {
|
| 3399 |
template<input_or_output_iterator I, sentinel_for<I> S>
|
| 3400 |
requires (!same_as<I, S> && copyable<I>)
|
| 3401 |
class common_iterator {
|
| 3402 |
public:
|
| 3403 |
-
constexpr common_iterator() = default;
|
| 3404 |
constexpr common_iterator(I i);
|
| 3405 |
constexpr common_iterator(S s);
|
| 3406 |
template<class I2, class S2>
|
| 3407 |
requires convertible_to<const I2&, I> && convertible_to<const S2&, S>
|
| 3408 |
constexpr common_iterator(const common_iterator<I2, S2>& x);
|
| 3409 |
|
| 3410 |
template<class I2, class S2>
|
| 3411 |
requires convertible_to<const I2&, I> && convertible_to<const S2&, S> &&
|
| 3412 |
assignable_from<I&, const I2&> && assignable_from<S&, const S2&>
|
| 3413 |
-
common_iterator& operator=(const common_iterator<I2, S2>& x);
|
| 3414 |
|
| 3415 |
-
decltype(auto) operator*();
|
| 3416 |
-
decltype(auto) operator*() const
|
| 3417 |
requires dereferenceable<const I>;
|
| 3418 |
-
|
| 3419 |
requires see below;
|
| 3420 |
|
| 3421 |
-
common_iterator& operator++();
|
| 3422 |
-
decltype(auto) operator++(int);
|
| 3423 |
|
| 3424 |
template<class I2, sentinel_for<I> S2>
|
| 3425 |
requires sentinel_for<S, I2>
|
| 3426 |
-
friend bool operator==(
|
| 3427 |
const common_iterator& x, const common_iterator<I2, S2>& y);
|
| 3428 |
template<class I2, sentinel_for<I> S2>
|
| 3429 |
requires sentinel_for<S, I2> && equality_comparable_with<I, I2>
|
| 3430 |
-
friend bool operator==(
|
| 3431 |
const common_iterator& x, const common_iterator<I2, S2>& y);
|
| 3432 |
|
| 3433 |
template<sized_sentinel_for<I> I2, sized_sentinel_for<I> S2>
|
| 3434 |
requires sized_sentinel_for<S, I2>
|
| 3435 |
-
friend iter_difference_t<I2> operator-(
|
| 3436 |
const common_iterator& x, const common_iterator<I2, S2>& y);
|
| 3437 |
|
| 3438 |
-
friend iter_rvalue_reference_t<I> iter_move(const common_iterator& i)
|
| 3439 |
noexcept(noexcept(ranges::iter_move(declval<const I&>())))
|
| 3440 |
requires input_iterator<I>;
|
| 3441 |
template<indirectly_swappable<I> I2, class S2>
|
| 3442 |
-
friend void iter_swap(const common_iterator& x, const common_iterator<I2, S2>& y)
|
| 3443 |
noexcept(noexcept(ranges::iter_swap(declval<const I&>(), declval<const I2&>())));
|
| 3444 |
|
| 3445 |
private:
|
| 3446 |
variant<I, S> v_; // exposition only
|
| 3447 |
};
|
|
@@ -3468,17 +4029,17 @@ namespace std {
|
|
| 3468 |
The nested *typedef-name*s of the specialization of `iterator_traits`
|
| 3469 |
for `common_iterator<I, S>` are defined as follows.
|
| 3470 |
|
| 3471 |
- `iterator_concept` denotes `forward_iterator_tag` if `I` models
|
| 3472 |
`forward_iterator`; otherwise it denotes `input_iterator_tag`.
|
| 3473 |
-
- `iterator_category` denotes `forward_iterator_tag` if
|
| 3474 |
-
`iterator_traits<I>::iterator_category`
|
| 3475 |
-
`derived_from<forward_iterator_tag>`;
|
| 3476 |
-
`input_iterator_tag`.
|
| 3477 |
-
-
|
| 3478 |
-
|
| 3479 |
-
|
| 3480 |
|
| 3481 |
#### Constructors and conversions <a id="common.iter.const">[[common.iter.const]]</a>
|
| 3482 |
|
| 3483 |
``` cpp
|
| 3484 |
constexpr common_iterator(I i);
|
|
@@ -3507,11 +4068,11 @@ template<class I2, class S2>
|
|
| 3507 |
|
| 3508 |
``` cpp
|
| 3509 |
template<class I2, class S2>
|
| 3510 |
requires convertible_to<const I2&, I> && convertible_to<const S2&, S> &&
|
| 3511 |
assignable_from<I&, const I2&> && assignable_from<S&, const S2&>
|
| 3512 |
-
common_iterator& operator=(const common_iterator<I2, S2>& x);
|
| 3513 |
```
|
| 3514 |
|
| 3515 |
*Preconditions:* `x.v_.valueless_by_exception()` is `false`.
|
| 3516 |
|
| 3517 |
*Effects:* Equivalent to:
|
|
@@ -3524,34 +4085,34 @@ where i is `x.v_.index()`.
|
|
| 3524 |
*Returns:* `*this`
|
| 3525 |
|
| 3526 |
#### Accessors <a id="common.iter.access">[[common.iter.access]]</a>
|
| 3527 |
|
| 3528 |
``` cpp
|
| 3529 |
-
decltype(auto) operator*();
|
| 3530 |
-
decltype(auto) operator*() const
|
| 3531 |
requires dereferenceable<const I>;
|
| 3532 |
```
|
| 3533 |
|
| 3534 |
-
*Preconditions:* `holds_alternative<I>(v_)`.
|
| 3535 |
|
| 3536 |
*Effects:* Equivalent to: `return *get<I>(v_);`
|
| 3537 |
|
| 3538 |
``` cpp
|
| 3539 |
-
|
| 3540 |
requires see below;
|
| 3541 |
```
|
| 3542 |
|
| 3543 |
-
The expression in the requires
|
| 3544 |
|
| 3545 |
``` cpp
|
| 3546 |
indirectly_readable<const I> &&
|
| 3547 |
(requires(const I& i) { i.operator->(); } ||
|
| 3548 |
is_reference_v<iter_reference_t<I>> ||
|
| 3549 |
constructible_from<iter_value_t<I>, iter_reference_t<I>>)
|
| 3550 |
```
|
| 3551 |
|
| 3552 |
-
*Preconditions:* `holds_alternative<I>(v_)`.
|
| 3553 |
|
| 3554 |
*Effects:*
|
| 3555 |
|
| 3556 |
- If `I` is a pointer type or if the expression
|
| 3557 |
`get<I>(v_).operator->()` is well-formed, equivalent to:
|
|
@@ -3565,53 +4126,87 @@ indirectly_readable<const I> &&
|
|
| 3565 |
- Otherwise, equivalent to: `return `*`proxy`*`(*get<I>(v_));` where
|
| 3566 |
*proxy* is the exposition-only class:
|
| 3567 |
``` cpp
|
| 3568 |
class proxy {
|
| 3569 |
iter_value_t<I> keep_;
|
| 3570 |
-
proxy(iter_reference_t<I>&& x)
|
| 3571 |
: keep_(std::move(x)) {}
|
| 3572 |
public:
|
| 3573 |
-
const iter_value_t<I>* operator->() const {
|
| 3574 |
return addressof(keep_);
|
| 3575 |
}
|
| 3576 |
};
|
| 3577 |
```
|
| 3578 |
|
| 3579 |
#### Navigation <a id="common.iter.nav">[[common.iter.nav]]</a>
|
| 3580 |
|
| 3581 |
``` cpp
|
| 3582 |
-
common_iterator& operator++();
|
| 3583 |
```
|
| 3584 |
|
| 3585 |
-
*Preconditions:* `holds_alternative<I>(v_)`.
|
| 3586 |
|
| 3587 |
*Effects:* Equivalent to `++get<I>(v_)`.
|
| 3588 |
|
| 3589 |
*Returns:* `*this`.
|
| 3590 |
|
| 3591 |
``` cpp
|
| 3592 |
-
decltype(auto) operator++(int);
|
| 3593 |
```
|
| 3594 |
|
| 3595 |
-
*Preconditions:* `holds_alternative<I>(v_)`.
|
| 3596 |
|
| 3597 |
*Effects:* If `I` models `forward_iterator`, equivalent to:
|
| 3598 |
|
| 3599 |
``` cpp
|
| 3600 |
common_iterator tmp = *this;
|
| 3601 |
++*this;
|
| 3602 |
return tmp;
|
| 3603 |
```
|
| 3604 |
|
| 3605 |
-
Otherwise,
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 3606 |
|
| 3607 |
#### Comparisons <a id="common.iter.cmp">[[common.iter.cmp]]</a>
|
| 3608 |
|
| 3609 |
``` cpp
|
| 3610 |
template<class I2, sentinel_for<I> S2>
|
| 3611 |
requires sentinel_for<S, I2>
|
| 3612 |
-
friend bool operator==(
|
| 3613 |
const common_iterator& x, const common_iterator<I2, S2>& y);
|
| 3614 |
```
|
| 3615 |
|
| 3616 |
*Preconditions:* `x.v_.valueless_by_exception()` and
|
| 3617 |
`y.v_.valueless_by_exception()` are each `false`.
|
|
@@ -3621,11 +4216,11 @@ friend bool operator==(
|
|
| 3621 |
`y.v_.index()`.
|
| 3622 |
|
| 3623 |
``` cpp
|
| 3624 |
template<class I2, sentinel_for<I> S2>
|
| 3625 |
requires sentinel_for<S, I2> && equality_comparable_with<I, I2>
|
| 3626 |
-
friend bool operator==(
|
| 3627 |
const common_iterator& x, const common_iterator<I2, S2>& y);
|
| 3628 |
```
|
| 3629 |
|
| 3630 |
*Preconditions:* `x.v_.valueless_by_exception()` and
|
| 3631 |
`y.v_.valueless_by_exception()` are each `false`.
|
|
@@ -3635,46 +4230,46 @@ friend bool operator==(
|
|
| 3635 |
`y.v_.index()`.
|
| 3636 |
|
| 3637 |
``` cpp
|
| 3638 |
template<sized_sentinel_for<I> I2, sized_sentinel_for<I> S2>
|
| 3639 |
requires sized_sentinel_for<S, I2>
|
| 3640 |
-
friend iter_difference_t<I2> operator-(
|
| 3641 |
const common_iterator& x, const common_iterator<I2, S2>& y);
|
| 3642 |
```
|
| 3643 |
|
| 3644 |
*Preconditions:* `x.v_.valueless_by_exception()` and
|
| 3645 |
`y.v_.valueless_by_exception()` are each `false`.
|
| 3646 |
|
| 3647 |
*Returns:* `0` if i and j are each `1`, and otherwise
|
| 3648 |
`get<`i`>(x.v_) - get<`j`>(y.v_)`, where i is `x.v_.index()` and j is
|
| 3649 |
`y.v_.index()`.
|
| 3650 |
|
| 3651 |
-
####
|
| 3652 |
|
| 3653 |
``` cpp
|
| 3654 |
-
friend iter_rvalue_reference_t<I> iter_move(const common_iterator& i)
|
| 3655 |
noexcept(noexcept(ranges::iter_move(declval<const I&>())))
|
| 3656 |
requires input_iterator<I>;
|
| 3657 |
```
|
| 3658 |
|
| 3659 |
-
*Preconditions:* `holds_alternative<I>(v_)`.
|
| 3660 |
|
| 3661 |
*Effects:* Equivalent to: `return ranges::iter_move(get<I>(i.v_));`
|
| 3662 |
|
| 3663 |
``` cpp
|
| 3664 |
template<indirectly_swappable<I> I2, class S2>
|
| 3665 |
-
friend void iter_swap(const common_iterator& x, const common_iterator<I2, S2>& y)
|
| 3666 |
noexcept(noexcept(ranges::iter_swap(declval<const I&>(), declval<const I2&>())));
|
| 3667 |
```
|
| 3668 |
|
| 3669 |
*Preconditions:* `holds_alternative<I>(x.v_)` and
|
| 3670 |
`holds_alternative<I2>(y.v_)` are each `true`.
|
| 3671 |
|
| 3672 |
*Effects:* Equivalent to
|
| 3673 |
`ranges::iter_swap(get<I>(x.v_), get<I2>(y.v_))`.
|
| 3674 |
|
| 3675 |
-
### Default
|
| 3676 |
|
| 3677 |
``` cpp
|
| 3678 |
namespace std {
|
| 3679 |
struct default_sentinel_t { };
|
| 3680 |
}
|
|
@@ -3707,39 +4302,49 @@ ranges::copy(counted_iterator(s.begin(), 10), default_sentinel, back_inserter(v)
|
|
| 3707 |
|
| 3708 |
— *end example*]
|
| 3709 |
|
| 3710 |
Two values `i1` and `i2` of types `counted_iterator<I1>` and
|
| 3711 |
`counted_iterator<I2>` refer to elements of the same sequence if and
|
| 3712 |
-
only if
|
|
|
|
| 3713 |
refer to the same (possibly past-the-end) element.
|
| 3714 |
|
| 3715 |
``` cpp
|
| 3716 |
namespace std {
|
| 3717 |
template<input_or_output_iterator I>
|
| 3718 |
class counted_iterator {
|
| 3719 |
public:
|
| 3720 |
using iterator_type = I;
|
| 3721 |
-
|
| 3722 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 3723 |
constexpr counted_iterator(I x, iter_difference_t<I> n);
|
| 3724 |
template<class I2>
|
| 3725 |
requires convertible_to<const I2&, I>
|
| 3726 |
constexpr counted_iterator(const counted_iterator<I2>& x);
|
| 3727 |
|
| 3728 |
template<class I2>
|
| 3729 |
requires assignable_from<I&, const I2&>
|
| 3730 |
constexpr counted_iterator& operator=(const counted_iterator<I2>& x);
|
| 3731 |
|
| 3732 |
-
constexpr I base() const &
|
| 3733 |
constexpr I base() &&;
|
| 3734 |
constexpr iter_difference_t<I> count() const noexcept;
|
| 3735 |
constexpr decltype(auto) operator*();
|
| 3736 |
constexpr decltype(auto) operator*() const
|
| 3737 |
requires dereferenceable<const I>;
|
| 3738 |
|
|
|
|
|
|
|
|
|
|
| 3739 |
constexpr counted_iterator& operator++();
|
| 3740 |
-
decltype(auto) operator++(int);
|
| 3741 |
constexpr counted_iterator operator++(int)
|
| 3742 |
requires forward_iterator<I>;
|
| 3743 |
constexpr counted_iterator& operator--()
|
| 3744 |
requires bidirectional_iterator<I>;
|
| 3745 |
constexpr counted_iterator operator--(int)
|
|
@@ -3788,18 +4393,15 @@ namespace std {
|
|
| 3788 |
private:
|
| 3789 |
I current = I(); // exposition only
|
| 3790 |
iter_difference_t<I> length = 0; // exposition only
|
| 3791 |
};
|
| 3792 |
|
| 3793 |
-
template<class I>
|
| 3794 |
-
struct incrementable_traits<counted_iterator<I>> {
|
| 3795 |
-
using difference_type = iter_difference_t<I>;
|
| 3796 |
-
};
|
| 3797 |
-
|
| 3798 |
template<input_iterator I>
|
|
|
|
| 3799 |
struct iterator_traits<counted_iterator<I>> : iterator_traits<I> {
|
| 3800 |
-
using pointer =
|
|
|
|
| 3801 |
};
|
| 3802 |
}
|
| 3803 |
```
|
| 3804 |
|
| 3805 |
#### Constructors and conversions <a id="counted.iter.const">[[counted.iter.const]]</a>
|
|
@@ -3833,11 +4435,11 @@ template<class I2>
|
|
| 3833 |
*Returns:* `*this`.
|
| 3834 |
|
| 3835 |
#### Accessors <a id="counted.iter.access">[[counted.iter.access]]</a>
|
| 3836 |
|
| 3837 |
``` cpp
|
| 3838 |
-
constexpr I base() const &
|
| 3839 |
```
|
| 3840 |
|
| 3841 |
*Effects:* Equivalent to: `return current;`
|
| 3842 |
|
| 3843 |
``` cpp
|
|
@@ -3858,12 +4460,21 @@ constexpr iter_difference_t<I> count() const noexcept;
|
|
| 3858 |
constexpr decltype(auto) operator*();
|
| 3859 |
constexpr decltype(auto) operator*() const
|
| 3860 |
requires dereferenceable<const I>;
|
| 3861 |
```
|
| 3862 |
|
|
|
|
|
|
|
| 3863 |
*Effects:* Equivalent to: `return *current;`
|
| 3864 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 3865 |
``` cpp
|
| 3866 |
constexpr decltype(auto) operator[](iter_difference_t<I> n) const
|
| 3867 |
requires random_access_iterator<I>;
|
| 3868 |
```
|
| 3869 |
|
|
@@ -3886,11 +4497,11 @@ constexpr counted_iterator& operator++();
|
|
| 3886 |
--length;
|
| 3887 |
return *this;
|
| 3888 |
```
|
| 3889 |
|
| 3890 |
``` cpp
|
| 3891 |
-
decltype(auto) operator++(int);
|
| 3892 |
```
|
| 3893 |
|
| 3894 |
*Preconditions:* `length > 0`.
|
| 3895 |
|
| 3896 |
*Effects:* Equivalent to:
|
|
@@ -4060,24 +4671,26 @@ friend constexpr iter_rvalue_reference_t<I>
|
|
| 4060 |
iter_move(const counted_iterator& i)
|
| 4061 |
noexcept(noexcept(ranges::iter_move(i.current)))
|
| 4062 |
requires input_iterator<I>;
|
| 4063 |
```
|
| 4064 |
|
|
|
|
|
|
|
| 4065 |
*Effects:* Equivalent to: `return ranges::iter_move(i.current);`
|
| 4066 |
|
| 4067 |
``` cpp
|
| 4068 |
template<indirectly_swappable<I> I2>
|
| 4069 |
friend constexpr void
|
| 4070 |
iter_swap(const counted_iterator& x, const counted_iterator<I2>& y)
|
| 4071 |
noexcept(noexcept(ranges::iter_swap(x.current, y.current)));
|
| 4072 |
```
|
| 4073 |
|
|
|
|
|
|
|
| 4074 |
*Effects:* Equivalent to `ranges::iter_swap(x.current, y.current)`.
|
| 4075 |
|
| 4076 |
-
### Unreachable sentinel <a id="unreachable.
|
| 4077 |
-
|
| 4078 |
-
#### Class `unreachable_sentinel_t` <a id="unreachable.sentinel">[[unreachable.sentinel]]</a>
|
| 4079 |
|
| 4080 |
Class `unreachable_sentinel_t` can be used with any
|
| 4081 |
`weakly_incrementable` type to denote the “upper bound” of an unbounded
|
| 4082 |
interval.
|
| 4083 |
|
|
@@ -4106,10 +4719,12 @@ namespace std {
|
|
| 4106 |
}
|
| 4107 |
```
|
| 4108 |
|
| 4109 |
## Stream iterators <a id="stream.iterators">[[stream.iterators]]</a>
|
| 4110 |
|
|
|
|
|
|
|
| 4111 |
To make it possible for algorithmic templates to work directly with
|
| 4112 |
input/output streams, appropriate iterator-like class templates are
|
| 4113 |
provided.
|
| 4114 |
|
| 4115 |
[*Example 1*:
|
|
@@ -4125,10 +4740,12 @@ the partial sums onto `cout`.
|
|
| 4125 |
|
| 4126 |
— *end example*]
|
| 4127 |
|
| 4128 |
### Class template `istream_iterator` <a id="istream.iterator">[[istream.iterator]]</a>
|
| 4129 |
|
|
|
|
|
|
|
| 4130 |
The class template `istream_iterator` is an input iterator
|
| 4131 |
[[input.iterators]] that reads successive elements from the input stream
|
| 4132 |
for which it was constructed.
|
| 4133 |
|
| 4134 |
``` cpp
|
|
@@ -4147,11 +4764,11 @@ namespace std {
|
|
| 4147 |
using istream_type = basic_istream<charT,traits>;
|
| 4148 |
|
| 4149 |
constexpr istream_iterator();
|
| 4150 |
constexpr istream_iterator(default_sentinel_t);
|
| 4151 |
istream_iterator(istream_type& s);
|
| 4152 |
-
istream_iterator(const istream_iterator& x)
|
| 4153 |
~istream_iterator() = default;
|
| 4154 |
istream_iterator& operator=(const istream_iterator&) = default;
|
| 4155 |
|
| 4156 |
const T& operator*() const;
|
| 4157 |
const T* operator->() const;
|
|
@@ -4192,17 +4809,21 @@ istream_iterator(istream_type& s);
|
|
| 4192 |
|
| 4193 |
*Effects:* Initializes `in_stream` with `addressof(s)`,
|
| 4194 |
value-initializes `value`, and then calls `operator++()`.
|
| 4195 |
|
| 4196 |
``` cpp
|
| 4197 |
-
istream_iterator(const istream_iterator& x)
|
| 4198 |
```
|
| 4199 |
|
| 4200 |
-
*
|
|
|
|
| 4201 |
|
| 4202 |
-
*Remarks:*
|
| 4203 |
-
|
|
|
|
|
|
|
|
|
|
| 4204 |
|
| 4205 |
``` cpp
|
| 4206 |
~istream_iterator() = default;
|
| 4207 |
```
|
| 4208 |
|
|
@@ -4270,10 +4891,12 @@ friend bool operator==(const istream_iterator& i, default_sentinel_t);
|
|
| 4270 |
|
| 4271 |
*Returns:* `!i.in_stream`.
|
| 4272 |
|
| 4273 |
### Class template `ostream_iterator` <a id="ostream.iterator">[[ostream.iterator]]</a>
|
| 4274 |
|
|
|
|
|
|
|
| 4275 |
`ostream_iterator` writes (using `operator<<`) successive elements onto
|
| 4276 |
the output stream from which it was constructed. If it was constructed
|
| 4277 |
with `charT*` as a constructor argument, this string, called a
|
| 4278 |
*delimiter string*, is written to the stream after every `T` is written.
|
| 4279 |
|
|
@@ -4289,11 +4912,10 @@ namespace std {
|
|
| 4289 |
using reference = void;
|
| 4290 |
using char_type = charT;
|
| 4291 |
using traits_type = traits;
|
| 4292 |
using ostream_type = basic_ostream<charT,traits>;
|
| 4293 |
|
| 4294 |
-
constexpr ostream_iterator() noexcept = default;
|
| 4295 |
ostream_iterator(ostream_type& s);
|
| 4296 |
ostream_iterator(ostream_type& s, const charT* delimiter);
|
| 4297 |
ostream_iterator(const ostream_iterator& x);
|
| 4298 |
~ostream_iterator();
|
| 4299 |
ostream_iterator& operator=(const ostream_iterator&) = default;
|
|
@@ -4302,12 +4924,12 @@ namespace std {
|
|
| 4302 |
ostream_iterator& operator*();
|
| 4303 |
ostream_iterator& operator++();
|
| 4304 |
ostream_iterator& operator++(int);
|
| 4305 |
|
| 4306 |
private:
|
| 4307 |
-
basic_ostream<charT,traits>* out_stream
|
| 4308 |
-
const charT* delim
|
| 4309 |
};
|
| 4310 |
}
|
| 4311 |
```
|
| 4312 |
|
| 4313 |
#### Constructors and destructor <a id="ostream.iterator.cons.des">[[ostream.iterator.cons.des]]</a>
|
|
@@ -4354,10 +4976,12 @@ ostream_iterator& operator++(int);
|
|
| 4354 |
|
| 4355 |
*Returns:* `*this`.
|
| 4356 |
|
| 4357 |
### Class template `istreambuf_iterator` <a id="istreambuf.iterator">[[istreambuf.iterator]]</a>
|
| 4358 |
|
|
|
|
|
|
|
| 4359 |
The class template `istreambuf_iterator` defines an input iterator
|
| 4360 |
[[input.iterators]] that reads successive *characters* from the
|
| 4361 |
streambuf for which it was constructed. `operator*` provides access to
|
| 4362 |
the current input character, if any. Each time `operator++` is
|
| 4363 |
evaluated, the iterator advances to the next input character. If the end
|
|
@@ -4388,10 +5012,11 @@ namespace std {
|
|
| 4388 |
using traits_type = traits;
|
| 4389 |
using int_type = typename traits::int_type;
|
| 4390 |
using streambuf_type = basic_streambuf<charT,traits>;
|
| 4391 |
using istream_type = basic_istream<charT,traits>;
|
| 4392 |
|
|
|
|
| 4393 |
class proxy; // exposition only
|
| 4394 |
|
| 4395 |
constexpr istreambuf_iterator() noexcept;
|
| 4396 |
constexpr istreambuf_iterator(default_sentinel_t) noexcept;
|
| 4397 |
istreambuf_iterator(const istreambuf_iterator&) noexcept = default;
|
|
@@ -4513,10 +5138,12 @@ friend bool operator==(const istreambuf_iterator& i, default_sentinel_t s);
|
|
| 4513 |
|
| 4514 |
*Returns:* `i.equal(s)`.
|
| 4515 |
|
| 4516 |
### Class template `ostreambuf_iterator` <a id="ostreambuf.iterator">[[ostreambuf.iterator]]</a>
|
| 4517 |
|
|
|
|
|
|
|
| 4518 |
The class template `ostreambuf_iterator` writes successive *characters*
|
| 4519 |
onto the output stream from which it was constructed.
|
| 4520 |
|
| 4521 |
``` cpp
|
| 4522 |
namespace std {
|
|
@@ -4531,22 +5158,21 @@ namespace std {
|
|
| 4531 |
using char_type = charT;
|
| 4532 |
using traits_type = traits;
|
| 4533 |
using streambuf_type = basic_streambuf<charT,traits>;
|
| 4534 |
using ostream_type = basic_ostream<charT,traits>;
|
| 4535 |
|
| 4536 |
-
constexpr ostreambuf_iterator() noexcept = default;
|
| 4537 |
ostreambuf_iterator(ostream_type& s) noexcept;
|
| 4538 |
ostreambuf_iterator(streambuf_type* s) noexcept;
|
| 4539 |
ostreambuf_iterator& operator=(charT c);
|
| 4540 |
|
| 4541 |
ostreambuf_iterator& operator*();
|
| 4542 |
ostreambuf_iterator& operator++();
|
| 4543 |
ostreambuf_iterator& operator++(int);
|
| 4544 |
bool failed() const noexcept;
|
| 4545 |
|
| 4546 |
private:
|
| 4547 |
-
streambuf_type* sbuf_
|
| 4548 |
};
|
| 4549 |
}
|
| 4550 |
```
|
| 4551 |
|
| 4552 |
#### Constructors <a id="ostreambuf.iter.cons">[[ostreambuf.iter.cons]]</a>
|
|
@@ -4603,12 +5229,11 @@ bool failed() const noexcept;
|
|
| 4603 |
In addition to being available via inclusion of the `<iterator>` header,
|
| 4604 |
the function templates in [[iterator.range]] are available when any of
|
| 4605 |
the following headers are included: `<array>`, `<deque>`,
|
| 4606 |
`<forward_list>`, `<list>`, `<map>`, `<regex>`, `<set>`, `<span>`,
|
| 4607 |
`<string>`, `<string_view>`, `<unordered_map>`, `<unordered_set>`, and
|
| 4608 |
-
`<vector>`.
|
| 4609 |
-
[[namespace.std]].
|
| 4610 |
|
| 4611 |
``` cpp
|
| 4612 |
template<class C> constexpr auto begin(C& c) -> decltype(c.begin());
|
| 4613 |
template<class C> constexpr auto begin(const C& c) -> decltype(c.begin());
|
| 4614 |
```
|
|
@@ -4781,20 +5406,26 @@ template<class E> constexpr const E* data(initializer_list<E> il) noexcept;
|
|
| 4781 |
[basic.lookup.argdep]: basic.md#basic.lookup.argdep
|
| 4782 |
[basic.lookup.unqual]: basic.md#basic.lookup.unqual
|
| 4783 |
[basic.lval]: expr.md#basic.lval
|
| 4784 |
[bidirectional.iterators]: #bidirectional.iterators
|
| 4785 |
[bidirectionaliterator]: #bidirectionaliterator
|
|
|
|
| 4786 |
[common.iter.access]: #common.iter.access
|
| 4787 |
[common.iter.cmp]: #common.iter.cmp
|
| 4788 |
[common.iter.const]: #common.iter.const
|
| 4789 |
[common.iter.cust]: #common.iter.cust
|
| 4790 |
[common.iter.nav]: #common.iter.nav
|
| 4791 |
[common.iter.types]: #common.iter.types
|
| 4792 |
[common.iterator]: #common.iterator
|
| 4793 |
[concept.swappable]: concepts.md#concept.swappable
|
| 4794 |
-
[concept.totallyordered]: concepts.md#concept.totallyordered
|
| 4795 |
[concepts.object]: concepts.md#concepts.object
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4796 |
[containers]: containers.md#containers
|
| 4797 |
[counted.iter.access]: #counted.iter.access
|
| 4798 |
[counted.iter.cmp]: #counted.iter.cmp
|
| 4799 |
[counted.iter.const]: #counted.iter.const
|
| 4800 |
[counted.iter.cust]: #counted.iter.cust
|
|
@@ -4802,12 +5433,13 @@ template<class E> constexpr const E* data(initializer_list<E> il) noexcept;
|
|
| 4802 |
[counted.iter.nav]: #counted.iter.nav
|
| 4803 |
[counted.iterator]: #counted.iterator
|
| 4804 |
[cpp17.copyassignable]: #cpp17.copyassignable
|
| 4805 |
[cpp17.equalitycomparable]: #cpp17.equalitycomparable
|
| 4806 |
[customization.point.object]: library.md#customization.point.object
|
| 4807 |
-
[default.
|
| 4808 |
-
[defns.
|
|
|
|
| 4809 |
[expr.call]: expr.md#expr.call
|
| 4810 |
[expr.const]: expr.md#expr.const
|
| 4811 |
[forward.iterators]: #forward.iterators
|
| 4812 |
[forwarditerator]: #forwarditerator
|
| 4813 |
[front.insert.iter.ops]: #front.insert.iter.ops
|
|
@@ -4816,22 +5448,26 @@ template<class E> constexpr const E* data(initializer_list<E> il) noexcept;
|
|
| 4816 |
[func.def]: utilities.md#func.def
|
| 4817 |
[incrementable.traits]: #incrementable.traits
|
| 4818 |
[indirectcallable]: #indirectcallable
|
| 4819 |
[indirectcallable.general]: #indirectcallable.general
|
| 4820 |
[indirectcallable.indirectinvocable]: #indirectcallable.indirectinvocable
|
|
|
|
| 4821 |
[input.iterators]: #input.iterators
|
| 4822 |
[inputiterator]: #inputiterator
|
| 4823 |
[insert.iter.ops]: #insert.iter.ops
|
| 4824 |
[insert.iterator]: #insert.iterator
|
| 4825 |
[insert.iterators]: #insert.iterators
|
|
|
|
| 4826 |
[inserter]: #inserter
|
| 4827 |
[iostream.format]: input.md#iostream.format
|
| 4828 |
[istream.iterator]: #istream.iterator
|
| 4829 |
[istream.iterator.cons]: #istream.iterator.cons
|
|
|
|
| 4830 |
[istream.iterator.ops]: #istream.iterator.ops
|
| 4831 |
[istreambuf.iterator]: #istreambuf.iterator
|
| 4832 |
[istreambuf.iterator.cons]: #istreambuf.iterator.cons
|
|
|
|
| 4833 |
[istreambuf.iterator.ops]: #istreambuf.iterator.ops
|
| 4834 |
[istreambuf.iterator.proxy]: #istreambuf.iterator.proxy
|
| 4835 |
[iterator]: #iterator
|
| 4836 |
[iterator.assoc.types]: #iterator.assoc.types
|
| 4837 |
[iterator.concept.bidir]: #iterator.concept.bidir
|
|
@@ -4848,16 +5484,18 @@ template<class E> constexpr const E* data(initializer_list<E> il) noexcept;
|
|
| 4848 |
[iterator.concept.winc]: #iterator.concept.winc
|
| 4849 |
[iterator.concept.writable]: #iterator.concept.writable
|
| 4850 |
[iterator.concepts]: #iterator.concepts
|
| 4851 |
[iterator.concepts.general]: #iterator.concepts.general
|
| 4852 |
[iterator.cpp17]: #iterator.cpp17
|
|
|
|
| 4853 |
[iterator.cust]: #iterator.cust
|
| 4854 |
[iterator.cust.move]: #iterator.cust.move
|
| 4855 |
[iterator.cust.swap]: #iterator.cust.swap
|
| 4856 |
[iterator.iterators]: #iterator.iterators
|
| 4857 |
[iterator.operations]: #iterator.operations
|
| 4858 |
[iterator.primitives]: #iterator.primitives
|
|
|
|
| 4859 |
[iterator.range]: #iterator.range
|
| 4860 |
[iterator.requirements]: #iterator.requirements
|
| 4861 |
[iterator.requirements.general]: #iterator.requirements.general
|
| 4862 |
[iterator.synopsis]: #iterator.synopsis
|
| 4863 |
[iterator.traits]: #iterator.traits
|
|
@@ -4875,19 +5513,23 @@ template<class E> constexpr const E* data(initializer_list<E> il) noexcept;
|
|
| 4875 |
[move.iter.op.comp]: #move.iter.op.comp
|
| 4876 |
[move.iter.op.conv]: #move.iter.op.conv
|
| 4877 |
[move.iter.requirements]: #move.iter.requirements
|
| 4878 |
[move.iterator]: #move.iterator
|
| 4879 |
[move.iterators]: #move.iterators
|
|
|
|
| 4880 |
[move.sent.ops]: #move.sent.ops
|
| 4881 |
[move.sentinel]: #move.sentinel
|
| 4882 |
[namespace.std]: library.md#namespace.std
|
|
|
|
| 4883 |
[ostream.iterator]: #ostream.iterator
|
| 4884 |
[ostream.iterator.cons.des]: #ostream.iterator.cons.des
|
|
|
|
| 4885 |
[ostream.iterator.ops]: #ostream.iterator.ops
|
| 4886 |
[ostreambuf.iter.cons]: #ostreambuf.iter.cons
|
| 4887 |
[ostreambuf.iter.ops]: #ostreambuf.iter.ops
|
| 4888 |
[ostreambuf.iterator]: #ostreambuf.iterator
|
|
|
|
| 4889 |
[output.iterators]: #output.iterators
|
| 4890 |
[outputiterator]: #outputiterator
|
| 4891 |
[predef.iterators]: #predef.iterators
|
| 4892 |
[projected]: #projected
|
| 4893 |
[random.access.iterators]: #random.access.iterators
|
|
@@ -4896,10 +5538,11 @@ template<class E> constexpr const E* data(initializer_list<E> il) noexcept;
|
|
| 4896 |
[range.iter.op.advance]: #range.iter.op.advance
|
| 4897 |
[range.iter.op.distance]: #range.iter.op.distance
|
| 4898 |
[range.iter.op.next]: #range.iter.op.next
|
| 4899 |
[range.iter.op.prev]: #range.iter.op.prev
|
| 4900 |
[range.iter.ops]: #range.iter.ops
|
|
|
|
| 4901 |
[ranges]: ranges.md#ranges
|
| 4902 |
[readable.traits]: #readable.traits
|
| 4903 |
[reverse.iter.cmp]: #reverse.iter.cmp
|
| 4904 |
[reverse.iter.cons]: #reverse.iter.cons
|
| 4905 |
[reverse.iter.conv]: #reverse.iter.conv
|
|
@@ -4907,22 +5550,23 @@ template<class E> constexpr const E* data(initializer_list<E> il) noexcept;
|
|
| 4907 |
[reverse.iter.nav]: #reverse.iter.nav
|
| 4908 |
[reverse.iter.nonmember]: #reverse.iter.nonmember
|
| 4909 |
[reverse.iter.requirements]: #reverse.iter.requirements
|
| 4910 |
[reverse.iterator]: #reverse.iterator
|
| 4911 |
[reverse.iterators]: #reverse.iterators
|
|
|
|
| 4912 |
[std.iterator.tags]: #std.iterator.tags
|
| 4913 |
[stream.buffers]: input.md#stream.buffers
|
| 4914 |
[stream.iterators]: #stream.iterators
|
|
|
|
| 4915 |
[swappable.requirements]: library.md#swappable.requirements
|
| 4916 |
[temp.deduct]: temp.md#temp.deduct
|
| 4917 |
[temp.func.order]: temp.md#temp.func.order
|
| 4918 |
[temp.inst]: temp.md#temp.inst
|
| 4919 |
[unreachable.sentinel]: #unreachable.sentinel
|
| 4920 |
-
[unreachable.sentinels]: #unreachable.sentinels
|
| 4921 |
[utility.arg.requirements]: library.md#utility.arg.requirements
|
| 4922 |
|
| 4923 |
-
[^1]: The sentinel denoting the end of a range
|
| 4924 |
the iterator denoting the beginning of the range, or a different
|
| 4925 |
type.
|
| 4926 |
|
| 4927 |
[^2]: This definition applies to pointers, since pointers are iterators.
|
| 4928 |
The effect of dereferencing an iterator that has been invalidated is
|
|
|
|
| 36 |
{ *t } -> can-reference; // not required to be equality-preserving
|
| 37 |
};
|
| 38 |
|
| 39 |
// [iterator.assoc.types], associated types
|
| 40 |
// [incrementable.traits], incrementable traits
|
| 41 |
+
template<class> struct incrementable_traits; // freestanding
|
| 42 |
template<class T>
|
| 43 |
+
using iter_difference_t = see below; // freestanding
|
| 44 |
|
| 45 |
// [readable.traits], indirectly readable traits
|
| 46 |
+
template<class> struct indirectly_readable_traits; // freestanding
|
| 47 |
template<class T>
|
| 48 |
+
using iter_value_t = see below; // freestanding
|
| 49 |
|
| 50 |
// [iterator.traits], iterator traits
|
| 51 |
+
template<class I> struct iterator_traits; // freestanding
|
| 52 |
+
template<class T> requires is_object_v<T> struct iterator_traits<T*>; // freestanding
|
| 53 |
|
| 54 |
template<dereferenceable T>
|
| 55 |
+
using iter_reference_t = decltype(*declval<T&>()); // freestanding
|
| 56 |
|
| 57 |
namespace ranges {
|
| 58 |
+
// [iterator.cust], customization point objects
|
| 59 |
inline namespace unspecified {
|
| 60 |
// [iterator.cust.move], ranges::iter_move
|
| 61 |
+
inline constexpr unspecified iter_move = unspecified; // freestanding
|
| 62 |
|
| 63 |
// [iterator.cust.swap], ranges::iter_swap
|
| 64 |
+
inline constexpr unspecified iter_swap = unspecified; // freestanding
|
| 65 |
}
|
| 66 |
}
|
| 67 |
|
| 68 |
template<dereferenceable T>
|
| 69 |
requires requires(T& t) {
|
| 70 |
{ ranges::iter_move(t) } -> can-reference;
|
| 71 |
}
|
| 72 |
+
using iter_rvalue_reference_t // freestanding
|
| 73 |
= decltype(ranges::iter_move(declval<T&>()));
|
| 74 |
|
| 75 |
// [iterator.concepts], iterator concepts
|
| 76 |
// [iterator.concept.readable], concept indirectly_readable
|
| 77 |
template<class In>
|
| 78 |
+
concept indirectly_readable = see below; // freestanding
|
| 79 |
|
| 80 |
template<indirectly_readable T>
|
| 81 |
+
using indirect-value-t = see below; // exposition only
|
| 82 |
+
|
| 83 |
+
template<indirectly_readable T>
|
| 84 |
+
using iter_common_reference_t = // freestanding
|
| 85 |
+
common_reference_t<iter_reference_t<T>, indirect-value-t<T>>;
|
| 86 |
|
| 87 |
// [iterator.concept.writable], concept indirectly_writable
|
| 88 |
template<class Out, class T>
|
| 89 |
+
concept indirectly_writable = see below; // freestanding
|
| 90 |
|
| 91 |
// [iterator.concept.winc], concept weakly_incrementable
|
| 92 |
template<class I>
|
| 93 |
+
concept weakly_incrementable = see below; // freestanding
|
| 94 |
|
| 95 |
// [iterator.concept.inc], concept incrementable
|
| 96 |
template<class I>
|
| 97 |
+
concept incrementable = see below; // freestanding
|
| 98 |
|
| 99 |
// [iterator.concept.iterator], concept input_or_output_iterator
|
| 100 |
template<class I>
|
| 101 |
+
concept input_or_output_iterator = see below; // freestanding
|
| 102 |
|
| 103 |
// [iterator.concept.sentinel], concept sentinel_for
|
| 104 |
template<class S, class I>
|
| 105 |
+
concept sentinel_for = see below; // freestanding
|
| 106 |
|
| 107 |
// [iterator.concept.sizedsentinel], concept sized_sentinel_for
|
| 108 |
template<class S, class I>
|
| 109 |
+
constexpr bool disable_sized_sentinel_for = false; // freestanding
|
| 110 |
|
| 111 |
template<class S, class I>
|
| 112 |
+
concept sized_sentinel_for = see below; // freestanding
|
| 113 |
|
| 114 |
// [iterator.concept.input], concept input_iterator
|
| 115 |
template<class I>
|
| 116 |
+
concept input_iterator = see below; // freestanding
|
| 117 |
|
| 118 |
// [iterator.concept.output], concept output_iterator
|
| 119 |
template<class I, class T>
|
| 120 |
+
concept output_iterator = see below; // freestanding
|
| 121 |
|
| 122 |
// [iterator.concept.forward], concept forward_iterator
|
| 123 |
template<class I>
|
| 124 |
+
concept forward_iterator = see below; // freestanding
|
| 125 |
|
| 126 |
// [iterator.concept.bidir], concept bidirectional_iterator
|
| 127 |
template<class I>
|
| 128 |
+
concept bidirectional_iterator = see below; // freestanding
|
| 129 |
|
| 130 |
// [iterator.concept.random.access], concept random_access_iterator
|
| 131 |
template<class I>
|
| 132 |
+
concept random_access_iterator = see below; // freestanding
|
| 133 |
|
| 134 |
// [iterator.concept.contiguous], concept contiguous_iterator
|
| 135 |
template<class I>
|
| 136 |
+
concept contiguous_iterator = see below; // freestanding
|
| 137 |
|
| 138 |
// [indirectcallable], indirect callable requirements
|
| 139 |
// [indirectcallable.indirectinvocable], indirect callables
|
| 140 |
template<class F, class I>
|
| 141 |
+
concept indirectly_unary_invocable = see below; // freestanding
|
| 142 |
|
| 143 |
template<class F, class I>
|
| 144 |
+
concept indirectly_regular_unary_invocable = see below; // freestanding
|
| 145 |
|
| 146 |
template<class F, class I>
|
| 147 |
+
concept indirect_unary_predicate = see below; // freestanding
|
| 148 |
|
| 149 |
template<class F, class I1, class I2>
|
| 150 |
+
concept indirect_binary_predicate = see below; // freestanding
|
| 151 |
|
| 152 |
template<class F, class I1, class I2 = I1>
|
| 153 |
+
concept indirect_equivalence_relation = see below; // freestanding
|
| 154 |
|
| 155 |
template<class F, class I1, class I2 = I1>
|
| 156 |
+
concept indirect_strict_weak_order = see below; // freestanding
|
| 157 |
|
| 158 |
template<class F, class... Is>
|
| 159 |
requires (indirectly_readable<Is> && ...) && invocable<F, iter_reference_t<Is>...>
|
| 160 |
+
using indirect_result_t = invoke_result_t<F, iter_reference_t<Is>...>; // freestanding
|
| 161 |
|
| 162 |
// [projected], projected
|
| 163 |
template<indirectly_readable I, indirectly_regular_unary_invocable<I> Proj>
|
| 164 |
+
struct projected; // freestanding
|
| 165 |
|
| 166 |
template<weakly_incrementable I, class Proj>
|
| 167 |
+
struct incrementable_traits<projected<I, Proj>>; // freestanding
|
| 168 |
|
| 169 |
// [alg.req], common algorithm requirements
|
| 170 |
// [alg.req.ind.move], concept indirectly_movable
|
| 171 |
template<class In, class Out>
|
| 172 |
+
concept indirectly_movable = see below; // freestanding
|
| 173 |
|
| 174 |
template<class In, class Out>
|
| 175 |
+
concept indirectly_movable_storable = see below; // freestanding
|
| 176 |
|
| 177 |
// [alg.req.ind.copy], concept indirectly_copyable
|
| 178 |
template<class In, class Out>
|
| 179 |
+
concept indirectly_copyable = see below; // freestanding
|
| 180 |
|
| 181 |
template<class In, class Out>
|
| 182 |
+
concept indirectly_copyable_storable = see below; // freestanding
|
| 183 |
|
| 184 |
// [alg.req.ind.swap], concept indirectly_swappable
|
| 185 |
template<class I1, class I2 = I1>
|
| 186 |
+
concept indirectly_swappable = see below; // freestanding
|
| 187 |
|
| 188 |
// [alg.req.ind.cmp], concept indirectly_comparable
|
| 189 |
template<class I1, class I2, class R, class P1 = identity, class P2 = identity>
|
| 190 |
+
concept indirectly_comparable = see below; // freestanding
|
| 191 |
|
| 192 |
// [alg.req.permutable], concept permutable
|
| 193 |
template<class I>
|
| 194 |
+
concept permutable = see below; // freestanding
|
| 195 |
|
| 196 |
// [alg.req.mergeable], concept mergeable
|
| 197 |
template<class I1, class I2, class Out,
|
| 198 |
class R = ranges::less, class P1 = identity, class P2 = identity>
|
| 199 |
+
concept mergeable = see below; // freestanding
|
| 200 |
|
| 201 |
// [alg.req.sortable], concept sortable
|
| 202 |
template<class I, class R = ranges::less, class P = identity>
|
| 203 |
+
concept sortable = see below; // freestanding
|
| 204 |
|
| 205 |
// [iterator.primitives], primitives
|
| 206 |
// [std.iterator.tags], iterator tags
|
| 207 |
+
struct input_iterator_tag { }; // freestanding
|
| 208 |
+
struct output_iterator_tag { }; // freestanding
|
| 209 |
+
struct forward_iterator_tag: public input_iterator_tag { }; // freestanding
|
| 210 |
+
struct bidirectional_iterator_tag: public forward_iterator_tag { }; // freestanding
|
| 211 |
+
struct random_access_iterator_tag: public bidirectional_iterator_tag { }; // freestanding
|
| 212 |
+
struct contiguous_iterator_tag: public random_access_iterator_tag { }; // freestanding
|
| 213 |
|
| 214 |
// [iterator.operations], iterator operations
|
| 215 |
template<class InputIterator, class Distance>
|
| 216 |
constexpr void
|
| 217 |
+
advance(InputIterator& i, Distance n); // freestanding
|
| 218 |
template<class InputIterator>
|
| 219 |
constexpr typename iterator_traits<InputIterator>::difference_type
|
| 220 |
+
distance(InputIterator first, InputIterator last); // freestanding
|
| 221 |
template<class InputIterator>
|
| 222 |
constexpr InputIterator
|
| 223 |
+
next(InputIterator x, // freestanding
|
| 224 |
typename iterator_traits<InputIterator>::difference_type n = 1);
|
| 225 |
template<class BidirectionalIterator>
|
| 226 |
constexpr BidirectionalIterator
|
| 227 |
+
prev(BidirectionalIterator x, // freestanding
|
| 228 |
typename iterator_traits<BidirectionalIterator>::difference_type n = 1);
|
| 229 |
|
| 230 |
// [range.iter.ops], range iterator operations
|
| 231 |
namespace ranges {
|
| 232 |
// [range.iter.op.advance], ranges::advance
|
| 233 |
template<input_or_output_iterator I>
|
| 234 |
+
constexpr void advance(I& i, iter_difference_t<I> n); // freestanding
|
| 235 |
template<input_or_output_iterator I, sentinel_for<I> S>
|
| 236 |
+
constexpr void advance(I& i, S bound); // freestanding
|
| 237 |
template<input_or_output_iterator I, sentinel_for<I> S>
|
| 238 |
+
constexpr iter_difference_t<I> advance(I& i, iter_difference_t<I> n, // freestanding
|
| 239 |
+
S bound);
|
| 240 |
|
| 241 |
// [range.iter.op.distance], ranges::distance
|
| 242 |
+
template<class I, sentinel_for<I> S>
|
| 243 |
+
requires (!sized_sentinel_for<S, I>)
|
| 244 |
+
constexpr iter_difference_t<I> distance(I first, S last); // freestanding
|
| 245 |
+
template<class I, sized_sentinel_for<decay_t<I>> S>
|
| 246 |
+
constexpr iter_difference_t<decay_t<I>> distance(I&& first, S last); // freestanding
|
| 247 |
template<range R>
|
| 248 |
+
constexpr range_difference_t<R> distance(R&& r); // freestanding
|
| 249 |
|
| 250 |
// [range.iter.op.next], ranges::next
|
| 251 |
template<input_or_output_iterator I>
|
| 252 |
+
constexpr I next(I x); // freestanding
|
| 253 |
template<input_or_output_iterator I>
|
| 254 |
+
constexpr I next(I x, iter_difference_t<I> n); // freestanding
|
| 255 |
template<input_or_output_iterator I, sentinel_for<I> S>
|
| 256 |
+
constexpr I next(I x, S bound); // freestanding
|
| 257 |
template<input_or_output_iterator I, sentinel_for<I> S>
|
| 258 |
+
constexpr I next(I x, iter_difference_t<I> n, S bound); // freestanding
|
| 259 |
|
| 260 |
// [range.iter.op.prev], ranges::prev
|
| 261 |
template<bidirectional_iterator I>
|
| 262 |
+
constexpr I prev(I x); // freestanding
|
| 263 |
template<bidirectional_iterator I>
|
| 264 |
+
constexpr I prev(I x, iter_difference_t<I> n); // freestanding
|
| 265 |
template<bidirectional_iterator I>
|
| 266 |
+
constexpr I prev(I x, iter_difference_t<I> n, I bound); // freestanding
|
| 267 |
}
|
| 268 |
|
| 269 |
// [predef.iterators], predefined iterators and sentinels
|
| 270 |
// [reverse.iterators], reverse iterators
|
| 271 |
+
template<class Iterator> class reverse_iterator; // freestanding
|
| 272 |
|
| 273 |
template<class Iterator1, class Iterator2>
|
| 274 |
+
constexpr bool operator==( // freestanding
|
| 275 |
const reverse_iterator<Iterator1>& x,
|
| 276 |
const reverse_iterator<Iterator2>& y);
|
| 277 |
template<class Iterator1, class Iterator2>
|
| 278 |
+
constexpr bool operator!=( // freestanding
|
| 279 |
const reverse_iterator<Iterator1>& x,
|
| 280 |
const reverse_iterator<Iterator2>& y);
|
| 281 |
template<class Iterator1, class Iterator2>
|
| 282 |
+
constexpr bool operator<( // freestanding
|
| 283 |
const reverse_iterator<Iterator1>& x,
|
| 284 |
const reverse_iterator<Iterator2>& y);
|
| 285 |
template<class Iterator1, class Iterator2>
|
| 286 |
+
constexpr bool operator>( // freestanding
|
| 287 |
const reverse_iterator<Iterator1>& x,
|
| 288 |
const reverse_iterator<Iterator2>& y);
|
| 289 |
template<class Iterator1, class Iterator2>
|
| 290 |
+
constexpr bool operator<=( // freestanding
|
| 291 |
const reverse_iterator<Iterator1>& x,
|
| 292 |
const reverse_iterator<Iterator2>& y);
|
| 293 |
template<class Iterator1, class Iterator2>
|
| 294 |
+
constexpr bool operator>=( // freestanding
|
| 295 |
const reverse_iterator<Iterator1>& x,
|
| 296 |
const reverse_iterator<Iterator2>& y);
|
| 297 |
template<class Iterator1, three_way_comparable_with<Iterator1> Iterator2>
|
| 298 |
constexpr compare_three_way_result_t<Iterator1, Iterator2>
|
| 299 |
+
operator<=>(const reverse_iterator<Iterator1>& x, // freestanding
|
| 300 |
const reverse_iterator<Iterator2>& y);
|
| 301 |
|
| 302 |
template<class Iterator1, class Iterator2>
|
| 303 |
+
constexpr auto operator-( // freestanding
|
| 304 |
const reverse_iterator<Iterator1>& x,
|
| 305 |
const reverse_iterator<Iterator2>& y) -> decltype(y.base() - x.base());
|
| 306 |
template<class Iterator>
|
| 307 |
+
constexpr reverse_iterator<Iterator> operator+( // freestanding
|
| 308 |
+
iter_difference_t<Iterator> n,
|
|
|
|
| 309 |
const reverse_iterator<Iterator>& x);
|
| 310 |
|
| 311 |
template<class Iterator>
|
| 312 |
+
constexpr reverse_iterator<Iterator> make_reverse_iterator(Iterator i); // freestanding
|
| 313 |
|
| 314 |
template<class Iterator1, class Iterator2>
|
| 315 |
requires (!sized_sentinel_for<Iterator1, Iterator2>)
|
| 316 |
+
constexpr bool disable_sized_sentinel_for<reverse_iterator<Iterator1>, // freestanding
|
| 317 |
reverse_iterator<Iterator2>> = true;
|
| 318 |
|
| 319 |
// [insert.iterators], insert iterators
|
| 320 |
+
template<class Container> class back_insert_iterator; // freestanding
|
| 321 |
template<class Container>
|
| 322 |
+
constexpr back_insert_iterator<Container> back_inserter(Container& x); // freestanding
|
| 323 |
|
| 324 |
+
template<class Container> class front_insert_iterator; // freestanding
|
| 325 |
template<class Container>
|
| 326 |
+
constexpr front_insert_iterator<Container> front_inserter(Container& x); // freestanding
|
| 327 |
|
| 328 |
+
template<class Container> class insert_iterator; // freestanding
|
| 329 |
template<class Container>
|
| 330 |
constexpr insert_iterator<Container>
|
| 331 |
+
inserter(Container& x, ranges::iterator_t<Container> i); // freestanding
|
| 332 |
+
|
| 333 |
+
// [const.iterators], constant iterators and sentinels
|
| 334 |
+
// [const.iterators.alias], alias templates
|
| 335 |
+
template<indirectly_readable I>
|
| 336 |
+
using iter_const_reference_t = see below; // freestanding
|
| 337 |
+
template<class Iterator>
|
| 338 |
+
concept constant-iterator = see below; // exposition only
|
| 339 |
+
template<input_iterator I>
|
| 340 |
+
using const_iterator = see below; // freestanding
|
| 341 |
+
template<semiregular S>
|
| 342 |
+
using const_sentinel = see below; // freestanding
|
| 343 |
+
|
| 344 |
+
// [const.iterators.iterator], class template basic_const_iterator
|
| 345 |
+
template<input_iterator Iterator>
|
| 346 |
+
class basic_const_iterator; // freestanding
|
| 347 |
+
|
| 348 |
+
template<class T, common_with<T> U>
|
| 349 |
+
requires input_iterator<common_type_t<T, U>>
|
| 350 |
+
struct common_type<basic_const_iterator<T>, U> { // freestanding
|
| 351 |
+
using type = basic_const_iterator<common_type_t<T, U>>;
|
| 352 |
+
};
|
| 353 |
+
template<class T, common_with<T> U>
|
| 354 |
+
requires input_iterator<common_type_t<T, U>>
|
| 355 |
+
struct common_type<U, basic_const_iterator<T>> { // freestanding
|
| 356 |
+
using type = basic_const_iterator<common_type_t<T, U>>;
|
| 357 |
+
};
|
| 358 |
+
template<class T, common_with<T> U>
|
| 359 |
+
requires input_iterator<common_type_t<T, U>>
|
| 360 |
+
struct common_type<basic_const_iterator<T>, basic_const_iterator<U>> { // freestanding
|
| 361 |
+
using type = basic_const_iterator<common_type_t<T, U>>;
|
| 362 |
+
};
|
| 363 |
+
|
| 364 |
+
template<input_iterator I>
|
| 365 |
+
constexpr const_iterator<I> make_const_iterator(I it) { return it; } // freestanding
|
| 366 |
+
|
| 367 |
+
template<semiregular S>
|
| 368 |
+
constexpr const_sentinel<S> make_const_sentinel(S s) { return s; } // freestanding
|
| 369 |
|
| 370 |
// [move.iterators], move iterators and sentinels
|
| 371 |
+
template<class Iterator> class move_iterator; // freestanding
|
| 372 |
|
| 373 |
template<class Iterator1, class Iterator2>
|
| 374 |
+
constexpr bool operator==( // freestanding
|
| 375 |
const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 376 |
template<class Iterator1, class Iterator2>
|
| 377 |
+
constexpr bool operator<( // freestanding
|
| 378 |
const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 379 |
template<class Iterator1, class Iterator2>
|
| 380 |
+
constexpr bool operator>( // freestanding
|
| 381 |
const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 382 |
template<class Iterator1, class Iterator2>
|
| 383 |
+
constexpr bool operator<=( // freestanding
|
| 384 |
const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 385 |
template<class Iterator1, class Iterator2>
|
| 386 |
+
constexpr bool operator>=( // freestanding
|
| 387 |
const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y);
|
| 388 |
template<class Iterator1, three_way_comparable_with<Iterator1> Iterator2>
|
| 389 |
constexpr compare_three_way_result_t<Iterator1, Iterator2>
|
| 390 |
+
operator<=>(const move_iterator<Iterator1>& x, // freestanding
|
| 391 |
const move_iterator<Iterator2>& y);
|
| 392 |
|
| 393 |
template<class Iterator1, class Iterator2>
|
| 394 |
+
constexpr auto operator-( // freestanding
|
| 395 |
+
const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y)
|
| 396 |
+
-> decltype(x.base() - y.base());
|
| 397 |
template<class Iterator>
|
| 398 |
+
constexpr move_iterator<Iterator>
|
| 399 |
+
operator+(iter_difference_t<Iterator> n, const move_iterator<Iterator>& x); // freestanding
|
| 400 |
|
| 401 |
template<class Iterator>
|
| 402 |
+
constexpr move_iterator<Iterator> make_move_iterator(Iterator i); // freestanding
|
| 403 |
|
| 404 |
+
template<class Iterator1, class Iterator2>
|
| 405 |
+
requires (!sized_sentinel_for<Iterator1, Iterator2>)
|
| 406 |
+
constexpr bool disable_sized_sentinel_for<move_iterator<Iterator1>, // freestanding
|
| 407 |
+
move_iterator<Iterator2>> = true;
|
| 408 |
+
|
| 409 |
+
template<semiregular S> class move_sentinel; // freestanding
|
| 410 |
|
| 411 |
// [iterators.common], common iterators
|
| 412 |
template<input_or_output_iterator I, sentinel_for<I> S>
|
| 413 |
requires (!same_as<I, S> && copyable<I>)
|
| 414 |
+
class common_iterator; // freestanding
|
| 415 |
|
| 416 |
template<class I, class S>
|
| 417 |
+
struct incrementable_traits<common_iterator<I, S>>; // freestanding
|
| 418 |
|
| 419 |
template<input_iterator I, class S>
|
| 420 |
+
struct iterator_traits<common_iterator<I, S>>; // freestanding
|
| 421 |
|
| 422 |
+
// [default.sentinel], default sentinel
|
| 423 |
+
struct default_sentinel_t; // freestanding
|
| 424 |
+
inline constexpr default_sentinel_t default_sentinel{}; // freestanding
|
| 425 |
|
| 426 |
// [iterators.counted], counted iterators
|
| 427 |
+
template<input_or_output_iterator I> class counted_iterator; // freestanding
|
|
|
|
|
|
|
|
|
|
| 428 |
|
| 429 |
template<input_iterator I>
|
| 430 |
+
requires see below
|
| 431 |
+
struct iterator_traits<counted_iterator<I>>; // freestanding
|
| 432 |
|
| 433 |
+
// [unreachable.sentinel], unreachable sentinel
|
| 434 |
+
struct unreachable_sentinel_t; // freestanding
|
| 435 |
+
inline constexpr unreachable_sentinel_t unreachable_sentinel{}; // freestanding
|
| 436 |
|
| 437 |
// [stream.iterators], stream iterators
|
| 438 |
template<class T, class charT = char, class traits = char_traits<charT>,
|
| 439 |
class Distance = ptrdiff_t>
|
| 440 |
class istream_iterator;
|
|
|
|
| 453 |
|
| 454 |
template<class charT, class traits = char_traits<charT>>
|
| 455 |
class ostreambuf_iterator;
|
| 456 |
|
| 457 |
// [iterator.range], range access
|
| 458 |
+
template<class C> constexpr auto begin(C& c) -> decltype(c.begin()); // freestanding
|
| 459 |
+
template<class C> constexpr auto begin(const C& c) -> decltype(c.begin()); // freestanding
|
| 460 |
+
template<class C> constexpr auto end(C& c) -> decltype(c.end()); // freestanding
|
| 461 |
+
template<class C> constexpr auto end(const C& c) -> decltype(c.end()); // freestanding
|
| 462 |
+
template<class T, size_t N> constexpr T* begin(T (&array)[N]) noexcept; // freestanding
|
| 463 |
+
template<class T, size_t N> constexpr T* end(T (&array)[N]) noexcept; // freestanding
|
| 464 |
+
template<class C> constexpr auto cbegin(const C& c) // freestanding
|
| 465 |
+
noexcept(noexcept(std::begin(c))) -> decltype(std::begin(c));
|
| 466 |
+
template<class C> constexpr auto cend(const C& c) // freestanding
|
| 467 |
+
noexcept(noexcept(std::end(c))) -> decltype(std::end(c));
|
| 468 |
+
template<class C> constexpr auto rbegin(C& c) -> decltype(c.rbegin()); // freestanding
|
| 469 |
+
template<class C> constexpr auto rbegin(const C& c) -> decltype(c.rbegin()); // freestanding
|
| 470 |
+
template<class C> constexpr auto rend(C& c) -> decltype(c.rend()); // freestanding
|
| 471 |
+
template<class C> constexpr auto rend(const C& c) -> decltype(c.rend()); // freestanding
|
| 472 |
+
template<class T, size_t N> constexpr reverse_iterator<T*> rbegin(T (&array)[N]) // freestanding
|
| 473 |
+
template<class T, size_t N> constexpr reverse_iterator<T*> rend(T (&array)[N]); // freestanding
|
| 474 |
+
template<class E> constexpr reverse_iterator<const E*>
|
| 475 |
+
rbegin(initializer_list<E> il); // freestanding
|
| 476 |
+
template<class E> constexpr reverse_iterator<const E*>
|
| 477 |
+
rend(initializer_list<E> il); // freestanding
|
| 478 |
+
template<class C> constexpr auto
|
| 479 |
+
crbegin(const C& c) -> decltype(std::rbegin(c)); // freestanding
|
| 480 |
+
template<class C> constexpr auto
|
| 481 |
+
crend(const C& c) -> decltype(std::rend(c)); // freestanding
|
| 482 |
|
| 483 |
+
template<class C> constexpr auto
|
| 484 |
+
size(const C& c) -> decltype(c.size()); // freestanding
|
| 485 |
+
template<class T, size_t N> constexpr size_t
|
| 486 |
+
size(const T (&array)[N]) noexcept; // freestanding
|
| 487 |
+
|
| 488 |
+
template<class C> constexpr auto
|
| 489 |
+
ssize(const C& c)
|
| 490 |
+
-> common_type_t<ptrdiff_t, make_signed_t<decltype(c.size())>>; // freestanding
|
| 491 |
+
template<class T, ptrdiff_t N> constexpr ptrdiff_t
|
| 492 |
+
ssize(const T (&array)[N]) noexcept; // freestanding
|
| 493 |
+
|
| 494 |
+
template<class C> [[nodiscard]] constexpr auto
|
| 495 |
+
empty(const C& c) -> decltype(c.empty()); // freestanding
|
| 496 |
+
template<class T, size_t N> [[nodiscard]] constexpr bool
|
| 497 |
+
empty(const T (&array)[N]) noexcept; // freestanding
|
| 498 |
+
template<class E> [[nodiscard]] constexpr bool
|
| 499 |
+
empty(initializer_list<E> il) noexcept; // freestanding
|
| 500 |
+
|
| 501 |
+
template<class C> constexpr auto data(C& c) -> decltype(c.data()); // freestanding
|
| 502 |
+
template<class C> constexpr auto data(const C& c) -> decltype(c.data()); // freestanding
|
| 503 |
+
template<class T, size_t N> constexpr T* data(T (&array)[N]) noexcept; // freestanding
|
| 504 |
+
template<class E> constexpr const E* data(initializer_list<E> il) noexcept; // freestanding
|
| 505 |
}
|
| 506 |
```
|
| 507 |
|
| 508 |
## Iterator requirements <a id="iterator.requirements">[[iterator.requirements]]</a>
|
| 509 |
|
|
|
|
| 543 |
The six categories of iterators correspond to the iterator concepts
|
| 544 |
|
| 545 |
- `input_iterator` [[iterator.concept.input]],
|
| 546 |
- `output_iterator` [[iterator.concept.output]],
|
| 547 |
- `forward_iterator` [[iterator.concept.forward]],
|
| 548 |
+
- `bidirectional_iterator` [[iterator.concept.bidir]],
|
| 549 |
- `random_access_iterator` [[iterator.concept.random.access]], and
|
| 550 |
- `contiguous_iterator` [[iterator.concept.contiguous]],
|
| 551 |
|
| 552 |
respectively. The generic term *iterator* refers to any type that models
|
| 553 |
the `input_or_output_iterator` concept [[iterator.concept.iterator]].
|
|
|
|
| 578 |
type there is an iterator value that points past the last element of a
|
| 579 |
corresponding sequence. Such a value is called a *past-the-end value*.
|
| 580 |
Values of an iterator `i` for which the expression `*i` is defined are
|
| 581 |
called *dereferenceable*. The library never assumes that past-the-end
|
| 582 |
values are dereferenceable. Iterators can also have singular values that
|
| 583 |
+
are not associated with any sequence. Results of most expressions are
|
| 584 |
+
undefined for singular values; the only exceptions are destroying an
|
| 585 |
+
iterator that holds a singular value, the assignment of a non-singular
|
| 586 |
+
value to an iterator that holds a singular value, and, for iterators
|
| 587 |
+
that meet the *Cpp17DefaultConstructible* requirements, using a
|
| 588 |
+
value-initialized iterator as the source of a copy or move operation.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 589 |
|
| 590 |
[*Note 2*: This guarantee is not offered for default-initialization,
|
| 591 |
although the distinction only matters for types with trivial default
|
| 592 |
constructors such as pointers or aggregates holding
|
| 593 |
pointers. — *end note*]
|
|
|
|
| 608 |
first iterator `j` such that `j == s`.
|
| 609 |
|
| 610 |
A sentinel `s` is called *reachable from* an iterator `i` if and only if
|
| 611 |
there is a finite sequence of applications of the expression `++i` that
|
| 612 |
makes `i == s`. If `s` is reachable from `i`, \[`i`, `s`) denotes a
|
| 613 |
+
*valid range*.
|
| 614 |
|
| 615 |
A *counted range* `i`+\[0, `n`) is empty if `n == 0`; otherwise,
|
| 616 |
`i`+\[0, `n`) refers to the `n` elements in the data structure starting
|
| 617 |
with the element pointed to by `i` and up to but not including the
|
| 618 |
element, if any, pointed to by the result of `n` applications of `++i`.
|
| 619 |
+
A counted range `i`+\[0, `n`) is *valid* if and only if `n == 0`; or `n`
|
| 620 |
+
is positive, `i` is dereferenceable, and `++i`+\[0, `–n`) is valid.
|
| 621 |
|
| 622 |
The result of the application of library functions to invalid ranges is
|
| 623 |
undefined.
|
| 624 |
|
| 625 |
All the categories of iterators require only those functions that are
|
|
|
|
| 715 |
requires is_object_v<T>
|
| 716 |
struct cond-value-type<T> {
|
| 717 |
using value_type = remove_cv_t<T>;
|
| 718 |
};
|
| 719 |
|
| 720 |
+
template<class T>
|
| 721 |
+
concept has-member-value-type = requires { typename T::value_type; }; // exposition only
|
| 722 |
+
|
| 723 |
+
template<class T>
|
| 724 |
+
concept has-member-element-type = requires { typename T::element_type; }; // exposition only
|
| 725 |
+
|
| 726 |
template<class> struct indirectly_readable_traits { };
|
| 727 |
|
| 728 |
template<class T>
|
| 729 |
struct indirectly_readable_traits<T*>
|
| 730 |
: cond-value-type<T> { };
|
|
|
|
| 737 |
|
| 738 |
template<class I>
|
| 739 |
struct indirectly_readable_traits<const I>
|
| 740 |
: indirectly_readable_traits<I> { };
|
| 741 |
|
| 742 |
+
template<has-member-value-type T>
|
|
|
|
| 743 |
struct indirectly_readable_traits<T>
|
| 744 |
: cond-value-type<typename T::value_type> { };
|
| 745 |
|
| 746 |
+
template<has-member-element-type T>
|
|
|
|
| 747 |
struct indirectly_readable_traits<T>
|
| 748 |
: cond-value-type<typename T::element_type> { };
|
| 749 |
|
| 750 |
+
template<has-member-value-type T>
|
| 751 |
+
requires has-member-element-type<T>
|
| 752 |
+
struct indirectly_readable_traits<T> { };
|
| 753 |
+
|
| 754 |
+
template<has-member-value-type T>
|
| 755 |
+
requires has-member-element-type<T> &&
|
| 756 |
+
same_as<remove_cv_t<typename T::element_type>, remove_cv_t<typename T::value_type>>
|
| 757 |
+
struct indirectly_readable_traits<T>
|
| 758 |
+
: cond-value-type<typename T::value_type> { };
|
| 759 |
+
|
| 760 |
template<class T> using iter_value_t = see below;
|
| 761 |
```
|
| 762 |
|
| 763 |
Let R_`I` be `remove_cvref_t<I>`. The type `iter_value_t<I>` denotes
|
| 764 |
|
|
|
|
| 816 |
exposition-only concepts:
|
| 817 |
|
| 818 |
``` cpp
|
| 819 |
template<class I>
|
| 820 |
concept cpp17-iterator =
|
| 821 |
+
requires(I i) {
|
| 822 |
{ *i } -> can-reference;
|
| 823 |
{ ++i } -> same_as<I&>;
|
| 824 |
{ *i++ } -> can-reference;
|
| 825 |
+
} && copyable<I>;
|
| 826 |
|
| 827 |
template<class I>
|
| 828 |
concept cpp17-input-iterator =
|
| 829 |
cpp17-iterator<I> && equality_comparable<I> && requires(I i) {
|
| 830 |
typename incrementable_traits<I>::difference_type;
|
|
|
|
| 837 |
};
|
| 838 |
|
| 839 |
template<class I>
|
| 840 |
concept cpp17-forward-iterator =
|
| 841 |
cpp17-input-iterator<I> && constructible_from<I> &&
|
| 842 |
+
is_reference_v<iter_reference_t<I>> &&
|
| 843 |
same_as<remove_cvref_t<iter_reference_t<I>>,
|
| 844 |
typename indirectly_readable_traits<I>::value_type> &&
|
| 845 |
requires(I i) {
|
| 846 |
{ i++ } -> convertible_to<const I&>;
|
| 847 |
{ *i++ } -> same_as<iter_reference_t<I>>;
|
|
|
|
| 933 |
|
| 934 |
Explicit or partial specializations of `iterator_traits` may have a
|
| 935 |
member type `iterator_concept` that is used to indicate conformance to
|
| 936 |
the iterator concepts [[iterator.concepts]].
|
| 937 |
|
| 938 |
+
[*Example 1*: To indicate conformance to the `input_iterator` concept
|
| 939 |
+
but a lack of conformance to the *Cpp17InputIterator* requirements
|
| 940 |
+
[[input.iterators]], an `iterator_traits` specialization might have
|
| 941 |
+
`iterator_concept` denote `input_iterator_tag` but not define
|
| 942 |
+
`iterator_category`. — *end example*]
|
| 943 |
+
|
| 944 |
`iterator_traits` is specialized for pointers as
|
| 945 |
|
| 946 |
``` cpp
|
| 947 |
namespace std {
|
| 948 |
template<class T>
|
|
|
|
| 956 |
using reference = T&;
|
| 957 |
};
|
| 958 |
}
|
| 959 |
```
|
| 960 |
|
| 961 |
+
[*Example 2*:
|
| 962 |
|
| 963 |
To implement a generic `reverse` function, a C++ program can do the
|
| 964 |
following:
|
| 965 |
|
| 966 |
``` cpp
|
|
|
|
| 979 |
}
|
| 980 |
```
|
| 981 |
|
| 982 |
— *end example*]
|
| 983 |
|
| 984 |
+
### Customization point objects <a id="iterator.cust">[[iterator.cust]]</a>
|
| 985 |
|
| 986 |
#### `ranges::iter_move` <a id="iterator.cust.move">[[iterator.cust.move]]</a>
|
| 987 |
|
| 988 |
The name `ranges::iter_move` denotes a customization point object
|
| 989 |
[[customization.point.object]]. The expression `ranges::iter_move(E)`
|
| 990 |
for a subexpression `E` is expression-equivalent to:
|
| 991 |
|
| 992 |
- `iter_move(E)`, if `E` has class or enumeration type and
|
| 993 |
`iter_move(E)` is a well-formed expression when treated as an
|
| 994 |
+
unevaluated operand, where the meaning of `iter_move` is established
|
| 995 |
+
as-if by performing argument-dependent lookup only
|
| 996 |
+
[[basic.lookup.argdep]].
|
|
|
|
|
|
|
|
|
|
| 997 |
- Otherwise, if the expression `*E` is well-formed:
|
| 998 |
- if `*E` is an lvalue, `std::move(*E)`;
|
| 999 |
- otherwise, `*E`.
|
| 1000 |
- Otherwise, `ranges::iter_move(E)` is ill-formed. \[*Note 1*: This case
|
| 1001 |
can result in substitution failure when `ranges::iter_move(E)` appears
|
|
|
|
| 1041 |
|
| 1042 |
and does not include a declaration of `ranges::iter_swap`. If the
|
| 1043 |
function selected by overload resolution does not exchange the values
|
| 1044 |
denoted by `E1` and `E2`, the program is ill-formed, no diagnostic
|
| 1045 |
required.
|
| 1046 |
+
\[*Note 1*: This precludes calling unconstrained `std::iter_swap`.
|
| 1047 |
+
When the deleted overload is viable, program-defined overloads need to
|
| 1048 |
+
be more specialized [[temp.func.order]] to be selected. — *end note*]
|
| 1049 |
- Otherwise, if the types of `E1` and `E2` each model
|
| 1050 |
`indirectly_readable`, and if the reference types of `E1` and `E2`
|
| 1051 |
model `swappable_with` [[concept.swappable]], then
|
| 1052 |
`ranges::swap(*E1, *E2)`.
|
| 1053 |
- Otherwise, if the types `T1` and `T2` of `E1` and `E2` model
|
| 1054 |
`indirectly_movable_storable<T1, T2>` and
|
| 1055 |
`indirectly_movable_storable<T2, T1>`, then
|
| 1056 |
`(void)(*E1 = iter-exchange-move(E2, E1))`, except that `E1` is
|
| 1057 |
evaluated only once.
|
| 1058 |
+
- Otherwise, `ranges::iter_swap(E1, E2)` is ill-formed. \[*Note 2*: This
|
| 1059 |
case can result in substitution failure when
|
| 1060 |
`ranges::iter_swap(E1, E2)` appears in the immediate context of a
|
| 1061 |
template instantiation. — *end note*]
|
| 1062 |
|
| 1063 |
### Iterator concepts <a id="iterator.concepts">[[iterator.concepts]]</a>
|
|
|
|
| 1092 |
I operator++(int);
|
| 1093 |
I& operator--();
|
| 1094 |
I operator--(int);
|
| 1095 |
|
| 1096 |
bool operator==(I) const;
|
|
|
|
| 1097 |
};
|
| 1098 |
```
|
| 1099 |
|
| 1100 |
`iterator_traits<I>::iterator_category` denotes `input_iterator_tag`,
|
| 1101 |
and `ITER_CONCEPT(I)` denotes `random_access_iterator_tag`.
|
|
|
|
| 1130 |
```
|
| 1131 |
|
| 1132 |
Given a value `i` of type `I`, `I` models `indirectly_readable` only if
|
| 1133 |
the expression `*i` is equality-preserving.
|
| 1134 |
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1135 |
#### Concept <a id="iterator.concept.writable">[[iterator.concept.writable]]</a>
|
| 1136 |
|
| 1137 |
The `indirectly_writable` concept specifies the requirements for writing
|
| 1138 |
a value into an iterator’s referenced object.
|
| 1139 |
|
|
|
|
| 1153 |
Let `E` be an expression such that `decltype((E))` is `T`, and let `o`
|
| 1154 |
be a dereferenceable object of type `Out`. `Out` and `T` model
|
| 1155 |
`indirectly_writable<Out, T>` only if
|
| 1156 |
|
| 1157 |
- If `Out` and `T` model
|
| 1158 |
+
`indirectly_readable<Out> && same_as<iter_value_t<Out>, decay_t<T>>`,
|
| 1159 |
then `*o` after any above assignment is equal to the value of `E`
|
| 1160 |
before the assignment.
|
| 1161 |
|
| 1162 |
After evaluating any above assignment expression, `o` is not required to
|
| 1163 |
be dereferenceable.
|
|
|
|
| 1183 |
increment operations are not required to be equality-preserving, nor is
|
| 1184 |
the type required to be `equality_comparable`.
|
| 1185 |
|
| 1186 |
``` cpp
|
| 1187 |
template<class T>
|
| 1188 |
+
constexpr bool is-integer-like = see below; // exposition only
|
| 1189 |
|
| 1190 |
template<class T>
|
| 1191 |
+
constexpr bool is-signed-integer-like = see below; // exposition only
|
| 1192 |
|
| 1193 |
template<class I>
|
| 1194 |
concept weakly_incrementable =
|
| 1195 |
+
movable<I> &&
|
| 1196 |
requires(I i) {
|
| 1197 |
typename iter_difference_t<I>;
|
| 1198 |
requires is-signed-integer-like<iter_difference_t<I>>;
|
| 1199 |
{ ++i } -> same_as<I&>; // not required to be equality-preserving
|
| 1200 |
i++; // not required to be equality-preserving
|
| 1201 |
};
|
| 1202 |
```
|
| 1203 |
|
| 1204 |
A type `I` is an *integer-class type* if it is in a set of
|
| 1205 |
+
*implementation-defined* types that behave as integer types do, as
|
| 1206 |
+
defined below.
|
| 1207 |
+
|
| 1208 |
+
[*Note 1*: An integer-class type is not necessarily a class
|
| 1209 |
+
type. — *end note*]
|
| 1210 |
|
| 1211 |
The range of representable values of an integer-class type is the
|
| 1212 |
+
continuous set of values over which it is defined. For any integer-class
|
| 1213 |
+
type, its range of representable values is either -2ᴺ⁻¹ to 2ᴺ⁻¹-1
|
| 1214 |
+
(inclusive) for some integer N, in which case it is a
|
| 1215 |
+
*signed-integer-class type*, or 0 to 2ᴺ-1 (inclusive) for some integer
|
| 1216 |
+
N, in which case it is an *unsigned-integer-class type*. In both cases,
|
| 1217 |
+
N is called the *width* of the integer-class type. The width of an
|
| 1218 |
+
integer-class type is greater than that of every integral type of the
|
| 1219 |
+
same signedness.
|
| 1220 |
|
| 1221 |
+
A type `I` other than cv `bool` is *integer-like* if it models
|
| 1222 |
+
`integral<I>` or if it is an integer-class type. An integer-like type
|
| 1223 |
+
`I` is *signed-integer-like* if it models `signed_integral<I>` or if it
|
| 1224 |
+
is a signed-integer-class type. An integer-like type `I` is
|
| 1225 |
+
*unsigned-integer-like* if it models `unsigned_integral<I>` or if it is
|
| 1226 |
+
an unsigned-integer-class type.
|
| 1227 |
|
| 1228 |
+
For every integer-class type `I`, let `B(I)` be a unique hypothetical
|
| 1229 |
+
extended integer type of the same signedness with the same width
|
| 1230 |
+
[[basic.fundamental]] as `I`.
|
|
|
|
| 1231 |
|
| 1232 |
+
[*Note 2*: The corresponding hypothetical specialization
|
| 1233 |
+
`numeric_limits<B(I)>` meets the requirements on `numeric_limits`
|
| 1234 |
+
specializations for integral types [[numeric.limits]]. — *end note*]
|
| 1235 |
+
|
| 1236 |
+
For every integral type `J`, let `B(J)` be the same type as `J`.
|
| 1237 |
+
|
| 1238 |
+
Expressions of integer-class type are explicitly convertible to any
|
| 1239 |
+
integer-like type, and implicitly convertible to any integer-class type
|
| 1240 |
+
of equal or greater width and the same signedness. Expressions of
|
| 1241 |
+
integral type are both implicitly and explicitly convertible to any
|
| 1242 |
+
integer-class type. Conversions between integral and integer-class types
|
| 1243 |
+
and between two integer-class types do not exit via an exception. The
|
| 1244 |
+
result of such a conversion is the unique value of the destination type
|
| 1245 |
+
that is congruent to the source modulo 2ᴺ, where N is the width of the
|
| 1246 |
+
destination type.
|
| 1247 |
+
|
| 1248 |
+
Let `a` be an object of integer-class type `I`, let `b` be an object of
|
| 1249 |
+
integer-like type `I2` such that the expression `b` is implicitly
|
| 1250 |
+
convertible to `I`, let `x` and `y` be, respectively, objects of type
|
| 1251 |
+
`B(I)` and `B(I2)` as described above that represent the same values as
|
| 1252 |
+
`a` and `b`, and let `c` be an lvalue of any integral type.
|
| 1253 |
+
|
| 1254 |
+
- The expressions `a++` and `a--` shall be prvalues of type `I` whose
|
| 1255 |
+
values are equal to that of `a` prior to the evaluation of the
|
| 1256 |
+
expressions. The expression `a++` shall modify the value of `a` by
|
| 1257 |
+
adding `1` to it. The expression `a--` shall modify the value of `a`
|
| 1258 |
+
by subtracting `1` from it.
|
| 1259 |
+
- The expressions `++a`, `--a`, and `&a` shall be expression-equivalent
|
| 1260 |
+
to `a += 1`, `a -= 1`, and `addressof(a)`, respectively.
|
| 1261 |
+
- For every *unary-operator* `@` other than `&` for which the expression
|
| 1262 |
+
`@x` is well-formed, `@a` shall also be well-formed and have the same
|
| 1263 |
+
value, effects, and value category as `@x`. If `@x` has type `bool`,
|
| 1264 |
+
so too does `@a`; if `@x` has type `B(I)`, then `@a` has type `I`.
|
| 1265 |
- For every assignment operator `@=` for which `c @= x` is well-formed,
|
| 1266 |
`c @= a` shall also be well-formed and shall have the same value and
|
| 1267 |
effects as `c @= x`. The expression `c @= a` shall be an lvalue
|
| 1268 |
referring to `c`.
|
| 1269 |
+
- For every assignment operator `@=` for which `x @= y` is well-formed,
|
| 1270 |
+
`a @= b` shall also be well-formed and shall have the same effects as
|
| 1271 |
+
`x @= y`, except that the value that would be stored into `x` is
|
| 1272 |
+
stored into `a`. The expression `a @= b` shall be an lvalue referring
|
| 1273 |
+
to `a`.
|
| 1274 |
+
- For every non-assignment binary operator `@` for which `x @ y` and
|
| 1275 |
+
`y @ x` are well-formed, `a @ b` and `b @ a` shall also be well-formed
|
| 1276 |
+
and shall have the same value, effects, and value category as `x @ y`
|
| 1277 |
+
and `y @ x`, respectively. If `x @ y` or `y @ x` has type `B(I)`, then
|
| 1278 |
+
`a @ b` or `b @ a`, respectively, has type `I`; if `x @ y` or `y @ x`
|
| 1279 |
+
has type `B(I2)`, then `a @ b` or `b @ a`, respectively, has type
|
| 1280 |
+
`I2`; if `x @ y` or `y @ x` has any other type, then `a @ b` or
|
| 1281 |
+
`b @ a`, respectively, has that type.
|
| 1282 |
|
| 1283 |
An expression `E` of integer-class type `I` is contextually convertible
|
| 1284 |
to `bool` as if by `bool(E != I(0))`.
|
| 1285 |
|
| 1286 |
All integer-class types model `regular` [[concepts.object]] and
|
| 1287 |
+
`three_way_comparable<strong_ordering>` [[cmp.concept]].
|
| 1288 |
|
| 1289 |
A value-initialized object of integer-class type has value 0.
|
| 1290 |
|
| 1291 |
For every (possibly cv-qualified) integer-class type `I`,
|
| 1292 |
+
`numeric_limits<I>` is specialized such that each static data member `m`
|
| 1293 |
+
has the same value as `numeric_limits<B(I)>::m`, and each static member
|
| 1294 |
+
function `f` returns `I(numeric_limits<B(I)>::f())`.
|
| 1295 |
|
| 1296 |
+
For any two integer-like types `I1` and `I2`, at least one of which is
|
| 1297 |
+
an integer-class type, `common_type_t<I1, I2>` denotes an integer-class
|
| 1298 |
+
type whose width is not less than that of `I1` or `I2`. If both `I1` and
|
| 1299 |
+
`I2` are signed-integer-like types, then `common_type_t<I1, I2>` is also
|
| 1300 |
+
a signed-integer-like type.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1301 |
|
| 1302 |
`is-integer-like<I>` is `true` if and only if `I` is an integer-like
|
| 1303 |
+
type. `is-signed-integer-like<I>` is `true` if and only if `I` is a
|
| 1304 |
signed-integer-like type.
|
| 1305 |
|
| 1306 |
Let `i` be an object of type `I`. When `i` is in the domain of both pre-
|
| 1307 |
and post-increment, `i` is said to be *incrementable*. `I` models
|
| 1308 |
`weakly_incrementable<I>` only if
|
|
|
|
| 1311 |
- If `i` is incrementable, then both `++i` and `i++` advance `i` to the
|
| 1312 |
next element.
|
| 1313 |
- If `i` is incrementable, then `addressof(++i)` is equal to
|
| 1314 |
`addressof(i)`.
|
| 1315 |
|
| 1316 |
+
*Recommended practice:* The implementaton of an algorithm on a weakly
|
| 1317 |
+
incrementable type should never attempt to pass through the same
|
| 1318 |
+
incrementable value twice; such an algorithm should be a single-pass
|
| 1319 |
+
algorithm.
|
| 1320 |
+
|
| 1321 |
+
[*Note 3*: For `weakly_incrementable` types, `a` equals `b` does not
|
| 1322 |
imply that `++a` equals `++b`. (Equality does not guarantee the
|
| 1323 |
+
substitution property or referential transparency.) Such algorithms can
|
| 1324 |
+
be used with istreams as the source of the input data through the
|
| 1325 |
+
`istream_iterator` class template. — *end note*]
|
|
|
|
|
|
|
| 1326 |
|
| 1327 |
#### Concept <a id="iterator.concept.inc">[[iterator.concept.inc]]</a>
|
| 1328 |
|
| 1329 |
The `incrementable` concept specifies requirements on types that can be
|
| 1330 |
incremented with the pre- and post-increment operators. The increment
|
|
|
|
| 1361 |
concept taxonomy; every iterator models `input_or_output_iterator`. This
|
| 1362 |
concept specifies operations for dereferencing and incrementing an
|
| 1363 |
iterator. Most algorithms will require additional operations to compare
|
| 1364 |
iterators with sentinels [[iterator.concept.sentinel]], to read
|
| 1365 |
[[iterator.concept.input]] or write [[iterator.concept.output]] values,
|
| 1366 |
+
or to provide a richer set of iterator movements
|
| 1367 |
+
[[iterator.concept.forward]], [[iterator.concept.bidir]], [[iterator.concept.random.access]].
|
|
|
|
| 1368 |
|
| 1369 |
``` cpp
|
| 1370 |
template<class I>
|
| 1371 |
concept input_or_output_iterator =
|
| 1372 |
requires(I i) {
|
|
|
|
| 1388 |
``` cpp
|
| 1389 |
template<class S, class I>
|
| 1390 |
concept sentinel_for =
|
| 1391 |
semiregular<S> &&
|
| 1392 |
input_or_output_iterator<I> &&
|
| 1393 |
+
weakly-equality-comparable-with<S, I>; // see [concept.equalitycomparable]
|
| 1394 |
```
|
| 1395 |
|
| 1396 |
Let `s` and `i` be values of type `S` and `I` such that \[`i`, `s`)
|
| 1397 |
denotes a range. Types `S` and `I` model `sentinel_for<S, I>` only if
|
| 1398 |
|
| 1399 |
- `i == s` is well-defined.
|
| 1400 |
- If `bool(i != s)` then `i` is dereferenceable and \[`++i`, `s`)
|
| 1401 |
denotes a range.
|
| 1402 |
+
- `assignable_from<I&, S>` is either modeled or not satisfied.
|
| 1403 |
|
| 1404 |
The domain of `==` is not static. Given an iterator `i` and sentinel `s`
|
| 1405 |
such that \[`i`, `s`) denotes a range and `i != s`, `i` and `s` are not
|
| 1406 |
required to continue to denote a range after incrementing any other
|
| 1407 |
iterator equal to `i`. Consequently, `i == s` is no longer required to
|
|
|
|
| 1435 |
- If -N is representable by `iter_difference_t<I>`, then `i - s` is
|
| 1436 |
well-defined and equals -N.
|
| 1437 |
|
| 1438 |
``` cpp
|
| 1439 |
template<class S, class I>
|
| 1440 |
+
constexpr bool disable_sized_sentinel_for = false;
|
| 1441 |
```
|
| 1442 |
|
| 1443 |
*Remarks:* Pursuant to [[namespace.std]], users may specialize
|
| 1444 |
`disable_sized_sentinel_for` for cv-unqualified non-array object types
|
| 1445 |
`S` and `I` if `S` and/or `I` is a program-defined type. Such
|
|
|
|
| 1503 |
``` cpp
|
| 1504 |
*i = E;
|
| 1505 |
++i;
|
| 1506 |
```
|
| 1507 |
|
| 1508 |
+
*Recommended practice:* The implementation of an algorithm on output
|
| 1509 |
+
iterators should never attempt to pass through the same iterator twice;
|
| 1510 |
+
such an algorithm should be a single-pass algorithm.
|
| 1511 |
|
| 1512 |
#### Concept <a id="iterator.concept.forward">[[iterator.concept.forward]]</a>
|
| 1513 |
|
| 1514 |
The `forward_iterator` concept adds copyability, equality comparison,
|
| 1515 |
and the multi-pass guarantee, specified below.
|
|
|
|
| 1537 |
|
| 1538 |
Two dereferenceable iterators `a` and `b` of type `X` offer the
|
| 1539 |
*multi-pass guarantee* if:
|
| 1540 |
|
| 1541 |
- `a == b` implies `++a == ++b` and
|
| 1542 |
+
- the expression `((void)[](X x){++x;}(a), *a)` is equivalent to the
|
| 1543 |
expression `*a`.
|
| 1544 |
|
| 1545 |
[*Note 2*: The requirement that `a == b` implies `++a == ++b` and the
|
| 1546 |
removal of the restrictions on the number of assignments through a
|
| 1547 |
mutable iterator (which applies to output iterators) allow the use of
|
|
|
|
| 1647 |
`a` and `c` is reachable from `b`, and let `D` be
|
| 1648 |
`iter_difference_t<I>`. The type `I` models `contiguous_iterator` only
|
| 1649 |
if
|
| 1650 |
|
| 1651 |
- `to_address(a) == addressof(*a)`,
|
| 1652 |
+
- `to_address(b) == to_address(a) + D(b - a)`,
|
| 1653 |
+
- `to_address(c) == to_address(a) + D(c - a)`,
|
| 1654 |
+
- `ranges::iter_move(a)` has the same type, value category, and effects
|
| 1655 |
+
as `std::move(*a)`, and
|
| 1656 |
+
- if `ranges::iter_swap(a, b)` is well-formed, it has effects equivalent
|
| 1657 |
+
to `ranges::swap(*a, *b)`.
|
| 1658 |
|
| 1659 |
### C++17 iterator requirements <a id="iterator.cpp17">[[iterator.cpp17]]</a>
|
| 1660 |
|
| 1661 |
+
#### General <a id="iterator.cpp17.general">[[iterator.cpp17.general]]</a>
|
| 1662 |
+
|
| 1663 |
In the following sections, `a` and `b` denote values of type `X` or
|
| 1664 |
`const X`, `difference_type` and `reference` refer to the types
|
| 1665 |
`iterator_traits<X>::difference_type` and
|
| 1666 |
`iterator_traits<X>::reference`, respectively, `n` denotes a value of
|
| 1667 |
`difference_type`, `u`, `tmp`, and `m` denote identifiers, `r` denotes a
|
|
|
|
| 1676 |
The *Cpp17Iterator* requirements form the basis of the iterator
|
| 1677 |
taxonomy; every iterator meets the *Cpp17Iterator* requirements. This
|
| 1678 |
set of requirements specifies operations for dereferencing and
|
| 1679 |
incrementing an iterator. Most algorithms will require additional
|
| 1680 |
operations to read [[input.iterators]] or write [[output.iterators]]
|
| 1681 |
+
values, or to provide a richer set of iterator movements
|
| 1682 |
+
[[forward.iterators]], [[bidirectional.iterators]], [[random.access.iterators]].
|
|
|
|
| 1683 |
|
| 1684 |
+
A type `X` meets the requirements if:
|
| 1685 |
|
| 1686 |
+
- `X` meets the *Cpp17CopyConstructible*, *Cpp17CopyAssignable*,
|
| 1687 |
+
*Cpp17Swappable*, and *Cpp17Destructible* requirements
|
| 1688 |
+
[[utility.arg.requirements]], [[swappable.requirements]], and
|
| 1689 |
- `iterator_traits<X>::difference_type` is a signed integer type or
|
| 1690 |
`void`, and
|
| 1691 |
- the expressions in [[iterator]] are valid and have the indicated
|
| 1692 |
semantics.
|
| 1693 |
|
|
|
|
| 1709 |
[*Example 1*: The call `find(a,b,x)` is defined only if the value of
|
| 1710 |
`a` has the property *p* defined as follows: `b` has property *p* and a
|
| 1711 |
value `i` has property *p* if (`*i==x`) or if (`*i!=x` and `++i` has
|
| 1712 |
property *p*). — *end example*]
|
| 1713 |
|
| 1714 |
+
*Recommended practice:* The implementation of an algorithm on input
|
| 1715 |
+
iterators should never attempt to pass through the same iterator twice;
|
| 1716 |
+
such an algorithm should be a single pass algorithm.
|
| 1717 |
+
|
| 1718 |
[*Note 1*: For input iterators, `a == b` does not imply `++a == ++b`.
|
| 1719 |
(Equality does not guarantee the substitution property or referential
|
| 1720 |
+
transparency.) Value type `T` is not required to be a
|
| 1721 |
+
*Cpp17CopyAssignable* type ([[cpp17.copyassignable]]). Such an
|
| 1722 |
+
algorithm can be used with istreams as the source of the input data
|
| 1723 |
+
through the `istream_iterator` class template. — *end note*]
|
|
|
|
|
|
|
| 1724 |
|
| 1725 |
#### Output iterators <a id="output.iterators">[[output.iterators]]</a>
|
| 1726 |
|
| 1727 |
A class or pointer type `X` meets the requirements of an output iterator
|
| 1728 |
if `X` meets the *Cpp17Iterator* requirements [[iterator.iterators]] and
|
| 1729 |
the expressions in [[outputiterator]] are valid and have the indicated
|
| 1730 |
semantics.
|
| 1731 |
|
| 1732 |
+
*Recommended practice:* The implementation of an algorithm on output
|
| 1733 |
+
iterators should never attempt to pass through the same iterator twice;
|
| 1734 |
+
such an algorithm should be a single-pass algorithm.
|
| 1735 |
+
|
| 1736 |
[*Note 1*: The only valid use of an `operator*` is on the left side of
|
| 1737 |
the assignment statement. Assignment through the same value of the
|
| 1738 |
+
iterator happens only once. Equality and inequality are not necessarily
|
|
|
|
|
|
|
| 1739 |
defined. — *end note*]
|
| 1740 |
|
| 1741 |
#### Forward iterators <a id="forward.iterators">[[forward.iterators]]</a>
|
| 1742 |
|
| 1743 |
A class or pointer type `X` meets the requirements of a forward iterator
|
|
|
|
| 1799 |
### Indirect callable requirements <a id="indirectcallable">[[indirectcallable]]</a>
|
| 1800 |
|
| 1801 |
#### General <a id="indirectcallable.general">[[indirectcallable.general]]</a>
|
| 1802 |
|
| 1803 |
There are several concepts that group requirements of algorithms that
|
| 1804 |
+
take callable objects [[func.def]] as arguments.
|
| 1805 |
+
|
| 1806 |
+
#### Indirect callable traits <a id="indirectcallable.traits">[[indirectcallable.traits]]</a>
|
| 1807 |
+
|
| 1808 |
+
To implement algorithms taking projections, it is necessary to determine
|
| 1809 |
+
the projected type of an iterator’s value type. For the exposition-only
|
| 1810 |
+
alias template *`indirect-value-t`*, `indirect-value-t<T>` denotes
|
| 1811 |
+
|
| 1812 |
+
- `invoke_result_t<Proj&, indirect-value-t<I>>` if `T` names
|
| 1813 |
+
`projected<I, Proj>`, and
|
| 1814 |
+
- `iter_value_t<T>&` otherwise.
|
| 1815 |
|
| 1816 |
#### Indirect callables <a id="indirectcallable.indirectinvocable">[[indirectcallable.indirectinvocable]]</a>
|
| 1817 |
|
| 1818 |
The indirect callable concepts are used to constrain those algorithms
|
| 1819 |
+
that accept callable objects [[func.def]] as arguments.
|
| 1820 |
|
| 1821 |
``` cpp
|
| 1822 |
namespace std {
|
| 1823 |
template<class F, class I>
|
| 1824 |
concept indirectly_unary_invocable =
|
| 1825 |
indirectly_readable<I> &&
|
| 1826 |
copy_constructible<F> &&
|
| 1827 |
+
invocable<F&, indirect-value-t<I>> &&
|
| 1828 |
invocable<F&, iter_reference_t<I>> &&
|
| 1829 |
invocable<F&, iter_common_reference_t<I>> &&
|
| 1830 |
common_reference_with<
|
| 1831 |
+
invoke_result_t<F&, indirect-value-t<I>>,
|
| 1832 |
invoke_result_t<F&, iter_reference_t<I>>>;
|
| 1833 |
|
| 1834 |
template<class F, class I>
|
| 1835 |
concept indirectly_regular_unary_invocable =
|
| 1836 |
indirectly_readable<I> &&
|
| 1837 |
copy_constructible<F> &&
|
| 1838 |
+
regular_invocable<F&, indirect-value-t<I>> &&
|
| 1839 |
regular_invocable<F&, iter_reference_t<I>> &&
|
| 1840 |
regular_invocable<F&, iter_common_reference_t<I>> &&
|
| 1841 |
common_reference_with<
|
| 1842 |
+
invoke_result_t<F&, indirect-value-t<I>>,
|
| 1843 |
invoke_result_t<F&, iter_reference_t<I>>>;
|
| 1844 |
|
| 1845 |
template<class F, class I>
|
| 1846 |
concept indirect_unary_predicate =
|
| 1847 |
indirectly_readable<I> &&
|
| 1848 |
copy_constructible<F> &&
|
| 1849 |
+
predicate<F&, indirect-value-t<I>> &&
|
| 1850 |
predicate<F&, iter_reference_t<I>> &&
|
| 1851 |
predicate<F&, iter_common_reference_t<I>>;
|
| 1852 |
|
| 1853 |
template<class F, class I1, class I2>
|
| 1854 |
concept indirect_binary_predicate =
|
| 1855 |
indirectly_readable<I1> && indirectly_readable<I2> &&
|
| 1856 |
copy_constructible<F> &&
|
| 1857 |
+
predicate<F&, indirect-value-t<I1>, indirect-value-t<I2>> &&
|
| 1858 |
+
predicate<F&, indirect-value-t<I1>, iter_reference_t<I2>> &&
|
| 1859 |
+
predicate<F&, iter_reference_t<I1>, indirect-value-t<I2>> &&
|
| 1860 |
predicate<F&, iter_reference_t<I1>, iter_reference_t<I2>> &&
|
| 1861 |
predicate<F&, iter_common_reference_t<I1>, iter_common_reference_t<I2>>;
|
| 1862 |
|
| 1863 |
template<class F, class I1, class I2 = I1>
|
| 1864 |
concept indirect_equivalence_relation =
|
| 1865 |
indirectly_readable<I1> && indirectly_readable<I2> &&
|
| 1866 |
copy_constructible<F> &&
|
| 1867 |
+
equivalence_relation<F&, indirect-value-t<I1>, indirect-value-t<I2>> &&
|
| 1868 |
+
equivalence_relation<F&, indirect-value-t<I1>, iter_reference_t<I2>> &&
|
| 1869 |
+
equivalence_relation<F&, iter_reference_t<I1>, indirect-value-t<I2>> &&
|
| 1870 |
equivalence_relation<F&, iter_reference_t<I1>, iter_reference_t<I2>> &&
|
| 1871 |
equivalence_relation<F&, iter_common_reference_t<I1>, iter_common_reference_t<I2>>;
|
| 1872 |
|
| 1873 |
template<class F, class I1, class I2 = I1>
|
| 1874 |
concept indirect_strict_weak_order =
|
| 1875 |
indirectly_readable<I1> && indirectly_readable<I2> &&
|
| 1876 |
copy_constructible<F> &&
|
| 1877 |
+
strict_weak_order<F&, indirect-value-t<I1>, indirect-value-t<I2>> &&
|
| 1878 |
+
strict_weak_order<F&, indirect-value-t<I1>, iter_reference_t<I2>> &&
|
| 1879 |
+
strict_weak_order<F&, iter_reference_t<I1>, indirect-value-t<I2>> &&
|
| 1880 |
strict_weak_order<F&, iter_reference_t<I1>, iter_reference_t<I2>> &&
|
| 1881 |
strict_weak_order<F&, iter_common_reference_t<I1>, iter_common_reference_t<I2>>;
|
| 1882 |
}
|
| 1883 |
```
|
| 1884 |
|
| 1885 |
#### Class template `projected` <a id="projected">[[projected]]</a>
|
| 1886 |
|
| 1887 |
Class template `projected` is used to constrain algorithms that accept
|
| 1888 |
+
callable objects and projections [[defns.projection]]. It combines an
|
| 1889 |
`indirectly_readable` type `I` and a callable object type `Proj` into a
|
| 1890 |
new `indirectly_readable` type whose `reference` type is the result of
|
| 1891 |
applying `Proj` to the `iter_reference_t` of `I`.
|
| 1892 |
|
| 1893 |
``` cpp
|
|
|
|
| 1923 |
below imposes constraints on the concepts’ arguments in addition to
|
| 1924 |
those that appear in the concepts’ bodies [[range.cmp]]. — *end note*]
|
| 1925 |
|
| 1926 |
#### Concept <a id="alg.req.ind.move">[[alg.req.ind.move]]</a>
|
| 1927 |
|
| 1928 |
+
The `indirectly_movable` concept specifies the relationship between an
|
| 1929 |
+
`indirectly_readable` type and an `indirectly_writable` type between
|
| 1930 |
which values may be moved.
|
| 1931 |
|
| 1932 |
``` cpp
|
| 1933 |
template<class In, class Out>
|
| 1934 |
concept indirectly_movable =
|
|
|
|
| 1964 |
state of the value denoted by `*i` is valid but unspecified
|
| 1965 |
[[lib.types.movedfrom]].
|
| 1966 |
|
| 1967 |
#### Concept <a id="alg.req.ind.copy">[[alg.req.ind.copy]]</a>
|
| 1968 |
|
| 1969 |
+
The `indirectly_copyable` concept specifies the relationship between an
|
| 1970 |
+
`indirectly_readable` type and an `indirectly_writable` type between
|
| 1971 |
which values may be copied.
|
| 1972 |
|
| 1973 |
``` cpp
|
| 1974 |
template<class In, class Out>
|
| 1975 |
concept indirectly_copyable =
|
|
|
|
| 2080 |
indirect_strict_weak_order<R, projected<I, P>>;
|
| 2081 |
```
|
| 2082 |
|
| 2083 |
## Iterator primitives <a id="iterator.primitives">[[iterator.primitives]]</a>
|
| 2084 |
|
| 2085 |
+
### General <a id="iterator.primitives.general">[[iterator.primitives.general]]</a>
|
| 2086 |
+
|
| 2087 |
To simplify the use of iterators, the library provides several classes
|
| 2088 |
and functions.
|
| 2089 |
|
| 2090 |
### Standard iterator tags <a id="std.iterator.tags">[[std.iterator.tags]]</a>
|
| 2091 |
|
|
|
|
| 2113 |
}
|
| 2114 |
```
|
| 2115 |
|
| 2116 |
[*Example 1*:
|
| 2117 |
|
| 2118 |
+
A program-defined iterator `BinaryTreeIterator` can be included into the
|
| 2119 |
+
bidirectional iterator category by specializing the `iterator_traits`
|
| 2120 |
+
template:
|
| 2121 |
|
| 2122 |
``` cpp
|
| 2123 |
template<class T> struct iterator_traits<BinaryTreeIterator<T>> {
|
| 2124 |
using iterator_category = bidirectional_iterator_tag;
|
| 2125 |
using difference_type = ptrdiff_t;
|
|
|
|
| 2187 |
*Preconditions:* `last` is reachable from `first`, or `InputIterator`
|
| 2188 |
meets the *Cpp17RandomAccessIterator* requirements and `first` is
|
| 2189 |
reachable from `last`.
|
| 2190 |
|
| 2191 |
*Effects:* If `InputIterator` meets the *Cpp17RandomAccessIterator*
|
| 2192 |
+
requirements, returns `(last - first)`; otherwise, increments `first`
|
| 2193 |
+
until `last` is reached and returns the number of increments.
|
| 2194 |
|
| 2195 |
``` cpp
|
| 2196 |
template<class InputIterator>
|
| 2197 |
constexpr InputIterator next(InputIterator x,
|
| 2198 |
typename iterator_traits<InputIterator>::difference_type n = 1);
|
|
|
|
| 2208 |
|
| 2209 |
*Effects:* Equivalent to: `advance(x, -n); return x;`
|
| 2210 |
|
| 2211 |
### Range iterator operations <a id="range.iter.ops">[[range.iter.ops]]</a>
|
| 2212 |
|
| 2213 |
+
#### General <a id="range.iter.ops.general">[[range.iter.ops.general]]</a>
|
| 2214 |
+
|
| 2215 |
The library includes the function templates `ranges::advance`,
|
| 2216 |
`ranges::distance`, `ranges::next`, and `ranges::prev` to manipulate
|
| 2217 |
iterators. These operations adapt to the set of operators provided by
|
| 2218 |
each iterator category to provide the most efficient implementation
|
| 2219 |
possible for a concrete iterator type.
|
|
|
|
| 2222 |
`random_access_iterator` forward `n` steps in constant time. For an
|
| 2223 |
iterator type that does not model `random_access_iterator`,
|
| 2224 |
`ranges::advance` instead performs `n` individual increments with the
|
| 2225 |
`++` operator. — *end example*]
|
| 2226 |
|
| 2227 |
+
The function templates defined in [[range.iter.ops]] are not found by
|
| 2228 |
argument-dependent name lookup [[basic.lookup.argdep]]. When found by
|
| 2229 |
unqualified [[basic.lookup.unqual]] name lookup for the
|
| 2230 |
*postfix-expression* in a function call [[expr.call]], they inhibit
|
| 2231 |
argument-dependent name lookup.
|
| 2232 |
|
|
|
|
| 2241 |
```
|
| 2242 |
|
| 2243 |
The function call expression at `#1` invokes `std::ranges::distance`,
|
| 2244 |
not `std::distance`, despite that (a) the iterator type returned from
|
| 2245 |
`begin(vec)` and `end(vec)` may be associated with namespace `std` and
|
| 2246 |
+
(b) `std::distance` is more specialized [[temp.func.order]] than
|
| 2247 |
`std::ranges::distance` since the former requires its first two
|
| 2248 |
parameters to have the same type.
|
| 2249 |
|
| 2250 |
— *end example*]
|
| 2251 |
|
| 2252 |
The number and order of deducible template parameters for the function
|
| 2253 |
+
templates defined in [[range.iter.ops]] is unspecified, except where
|
| 2254 |
explicitly stated otherwise.
|
| 2255 |
|
| 2256 |
#### `ranges::advance` <a id="range.iter.op.advance">[[range.iter.op.advance]]</a>
|
| 2257 |
|
| 2258 |
``` cpp
|
|
|
|
| 2272 |
``` cpp
|
| 2273 |
template<input_or_output_iterator I, sentinel_for<I> S>
|
| 2274 |
constexpr void ranges::advance(I& i, S bound);
|
| 2275 |
```
|
| 2276 |
|
| 2277 |
+
*Preconditions:* Either
|
| 2278 |
+
`assignable_from<I&, S> || sized_sentinel_for<S, I>` is modeled, or
|
| 2279 |
+
\[`i`, `bound`) denotes a range.
|
| 2280 |
|
| 2281 |
*Effects:*
|
| 2282 |
|
| 2283 |
- If `I` and `S` model `assignable_from<I&, S>`, equivalent to
|
| 2284 |
`i = std::move(bound)`.
|
|
|
|
| 2311 |
starting positions of `i`.
|
| 2312 |
|
| 2313 |
#### `ranges::distance` <a id="range.iter.op.distance">[[range.iter.op.distance]]</a>
|
| 2314 |
|
| 2315 |
``` cpp
|
| 2316 |
+
template<class I, sentinel_for<I> S>
|
| 2317 |
+
requires (!sized_sentinel_for<S, I>)
|
| 2318 |
constexpr iter_difference_t<I> ranges::distance(I first, S last);
|
| 2319 |
```
|
| 2320 |
|
| 2321 |
+
*Preconditions:* \[`first`, `last`) denotes a range.
|
|
|
|
|
|
|
| 2322 |
|
| 2323 |
+
*Effects:* Increments `first` until `last` is reached and returns the
|
| 2324 |
+
number of increments.
|
| 2325 |
+
|
| 2326 |
+
``` cpp
|
| 2327 |
+
template<class I, sized_sentinel_for<decay_t<I>> S>
|
| 2328 |
+
constexpr iter_difference_t<decay_t<I>> ranges::distance(I&& first, S last);
|
| 2329 |
+
```
|
| 2330 |
+
|
| 2331 |
+
*Effects:* Equivalent to:
|
| 2332 |
+
`return last - static_cast<const decay_t<I>&>(first);`
|
| 2333 |
|
| 2334 |
``` cpp
|
| 2335 |
template<range R>
|
| 2336 |
constexpr range_difference_t<R> ranges::distance(R&& r);
|
| 2337 |
```
|
|
|
|
| 2383 |
``` cpp
|
| 2384 |
template<bidirectional_iterator I>
|
| 2385 |
constexpr I ranges::prev(I x);
|
| 2386 |
```
|
| 2387 |
|
| 2388 |
+
*Effects:* Equivalent to: `–x; return x;`
|
| 2389 |
|
| 2390 |
``` cpp
|
| 2391 |
template<bidirectional_iterator I>
|
| 2392 |
constexpr I ranges::prev(I x, iter_difference_t<I> n);
|
| 2393 |
```
|
|
|
|
| 2403 |
|
| 2404 |
## Iterator adaptors <a id="predef.iterators">[[predef.iterators]]</a>
|
| 2405 |
|
| 2406 |
### Reverse iterators <a id="reverse.iterators">[[reverse.iterators]]</a>
|
| 2407 |
|
| 2408 |
+
#### General <a id="reverse.iterators.general">[[reverse.iterators.general]]</a>
|
| 2409 |
+
|
| 2410 |
Class template `reverse_iterator` is an iterator adaptor that iterates
|
| 2411 |
from the end of the sequence defined by its underlying iterator to the
|
| 2412 |
beginning of that sequence.
|
| 2413 |
|
| 2414 |
#### Class template `reverse_iterator` <a id="reverse.iterator">[[reverse.iterator]]</a>
|
|
|
|
| 2513 |
|
| 2514 |
``` cpp
|
| 2515 |
template<class U> constexpr reverse_iterator(const reverse_iterator<U>& u);
|
| 2516 |
```
|
| 2517 |
|
| 2518 |
+
*Constraints:* `is_same_v<U, Iterator>` is `false` and `const U&` models
|
| 2519 |
+
`convertible_to<Iterator>`.
|
| 2520 |
+
|
| 2521 |
*Effects:* Initializes `current` with `u.current`.
|
| 2522 |
|
| 2523 |
``` cpp
|
| 2524 |
template<class U>
|
| 2525 |
constexpr reverse_iterator&
|
| 2526 |
operator=(const reverse_iterator<U>& u);
|
| 2527 |
```
|
| 2528 |
|
| 2529 |
+
*Constraints:* `is_same_v<U, Iterator>` is `false`, `const U&` models
|
| 2530 |
+
`convertible_to<Iterator>`, and `assignable_from<Iterator&, const U&>`
|
| 2531 |
+
is modeled.
|
| 2532 |
+
|
| 2533 |
+
*Effects:* Assigns `u.current` to `current`.
|
| 2534 |
|
| 2535 |
*Returns:* `*this`.
|
| 2536 |
|
| 2537 |
#### Conversion <a id="reverse.iter.conv">[[reverse.iter.conv]]</a>
|
| 2538 |
|
| 2539 |
``` cpp
|
| 2540 |
+
constexpr Iterator base() const;
|
| 2541 |
```
|
| 2542 |
|
| 2543 |
*Returns:* `current`.
|
| 2544 |
|
| 2545 |
#### Element access <a id="reverse.iter.elem">[[reverse.iter.elem]]</a>
|
|
|
|
| 2589 |
|
| 2590 |
``` cpp
|
| 2591 |
constexpr reverse_iterator& operator++();
|
| 2592 |
```
|
| 2593 |
|
| 2594 |
+
*Effects:* As if by: `–current;`
|
| 2595 |
|
| 2596 |
*Returns:* `*this`.
|
| 2597 |
|
| 2598 |
``` cpp
|
| 2599 |
constexpr reverse_iterator operator++(int);
|
|
|
|
| 2741 |
*Returns:* `y.base() - x.base()`.
|
| 2742 |
|
| 2743 |
``` cpp
|
| 2744 |
template<class Iterator>
|
| 2745 |
constexpr reverse_iterator<Iterator> operator+(
|
| 2746 |
+
iter_difference_t<Iterator> n,
|
| 2747 |
const reverse_iterator<Iterator>& x);
|
| 2748 |
```
|
| 2749 |
|
| 2750 |
*Returns:* `reverse_iterator<Iterator>(x.base() - n)`.
|
| 2751 |
|
|
|
|
| 2759 |
``` cpp
|
| 2760 |
auto tmp = i.base();
|
| 2761 |
return ranges::iter_move(--tmp);
|
| 2762 |
```
|
| 2763 |
|
| 2764 |
+
*Remarks:* The exception specification is equivalent to:
|
| 2765 |
|
| 2766 |
``` cpp
|
| 2767 |
is_nothrow_copy_constructible_v<Iterator> &&
|
| 2768 |
noexcept(ranges::iter_move(--declval<Iterator&>()))
|
| 2769 |
```
|
|
|
|
| 2781 |
auto xtmp = x.base();
|
| 2782 |
auto ytmp = y.base();
|
| 2783 |
ranges::iter_swap(--xtmp, --ytmp);
|
| 2784 |
```
|
| 2785 |
|
| 2786 |
+
*Remarks:* The exception specification is equivalent to:
|
| 2787 |
|
| 2788 |
``` cpp
|
| 2789 |
is_nothrow_copy_constructible_v<Iterator> &&
|
| 2790 |
is_nothrow_copy_constructible_v<Iterator2> &&
|
| 2791 |
noexcept(ranges::iter_swap(--declval<Iterator&>(), --declval<Iterator2&>()))
|
|
|
|
| 2798 |
|
| 2799 |
*Returns:* `reverse_iterator<Iterator>(i)`.
|
| 2800 |
|
| 2801 |
### Insert iterators <a id="insert.iterators">[[insert.iterators]]</a>
|
| 2802 |
|
| 2803 |
+
#### General <a id="insert.iterators.general">[[insert.iterators.general]]</a>
|
| 2804 |
+
|
| 2805 |
To make it possible to deal with insertion in the same way as writing
|
| 2806 |
into an array, a special kind of iterator adaptors, called *insert
|
| 2807 |
iterators*, are provided in the library. With regular iterator classes,
|
| 2808 |
|
| 2809 |
``` cpp
|
|
|
|
| 2836 |
``` cpp
|
| 2837 |
namespace std {
|
| 2838 |
template<class Container>
|
| 2839 |
class back_insert_iterator {
|
| 2840 |
protected:
|
| 2841 |
+
Container* container;
|
| 2842 |
|
| 2843 |
public:
|
| 2844 |
using iterator_category = output_iterator_tag;
|
| 2845 |
using value_type = void;
|
| 2846 |
using difference_type = ptrdiff_t;
|
| 2847 |
using pointer = void;
|
| 2848 |
using reference = void;
|
| 2849 |
using container_type = Container;
|
| 2850 |
|
|
|
|
| 2851 |
constexpr explicit back_insert_iterator(Container& x);
|
| 2852 |
constexpr back_insert_iterator& operator=(const typename Container::value_type& value);
|
| 2853 |
constexpr back_insert_iterator& operator=(typename Container::value_type&& value);
|
| 2854 |
|
| 2855 |
constexpr back_insert_iterator& operator*();
|
|
|
|
| 2910 |
``` cpp
|
| 2911 |
namespace std {
|
| 2912 |
template<class Container>
|
| 2913 |
class front_insert_iterator {
|
| 2914 |
protected:
|
| 2915 |
+
Container* container;
|
| 2916 |
|
| 2917 |
public:
|
| 2918 |
using iterator_category = output_iterator_tag;
|
| 2919 |
using value_type = void;
|
| 2920 |
using difference_type = ptrdiff_t;
|
| 2921 |
using pointer = void;
|
| 2922 |
using reference = void;
|
| 2923 |
using container_type = Container;
|
| 2924 |
|
|
|
|
| 2925 |
constexpr explicit front_insert_iterator(Container& x);
|
| 2926 |
constexpr front_insert_iterator& operator=(const typename Container::value_type& value);
|
| 2927 |
constexpr front_insert_iterator& operator=(typename Container::value_type&& value);
|
| 2928 |
|
| 2929 |
constexpr front_insert_iterator& operator*();
|
|
|
|
| 2984 |
``` cpp
|
| 2985 |
namespace std {
|
| 2986 |
template<class Container>
|
| 2987 |
class insert_iterator {
|
| 2988 |
protected:
|
| 2989 |
+
Container* container;
|
| 2990 |
+
ranges::iterator_t<Container> iter;
|
| 2991 |
|
| 2992 |
public:
|
| 2993 |
using iterator_category = output_iterator_tag;
|
| 2994 |
using value_type = void;
|
| 2995 |
using difference_type = ptrdiff_t;
|
| 2996 |
using pointer = void;
|
| 2997 |
using reference = void;
|
| 2998 |
using container_type = Container;
|
| 2999 |
|
|
|
|
| 3000 |
constexpr insert_iterator(Container& x, ranges::iterator_t<Container> i);
|
| 3001 |
constexpr insert_iterator& operator=(const typename Container::value_type& value);
|
| 3002 |
constexpr insert_iterator& operator=(typename Container::value_type&& value);
|
| 3003 |
|
| 3004 |
constexpr insert_iterator& operator*();
|
|
|
|
| 3064 |
inserter(Container& x, ranges::iterator_t<Container> i);
|
| 3065 |
```
|
| 3066 |
|
| 3067 |
*Returns:* `insert_iterator<Container>(x, i)`.
|
| 3068 |
|
| 3069 |
+
### Constant iterators and sentinels <a id="const.iterators">[[const.iterators]]</a>
|
| 3070 |
+
|
| 3071 |
+
#### General <a id="const.iterators.general">[[const.iterators.general]]</a>
|
| 3072 |
+
|
| 3073 |
+
Class template `basic_const_iterator` is an iterator adaptor with the
|
| 3074 |
+
same behavior as the underlying iterator except that its indirection
|
| 3075 |
+
operator implicitly converts the value returned by the underlying
|
| 3076 |
+
iterator’s indirection operator to a type such that the adapted iterator
|
| 3077 |
+
is a constant iterator [[iterator.requirements]]. Some generic
|
| 3078 |
+
algorithms can be called with constant iterators to avoid mutation.
|
| 3079 |
+
|
| 3080 |
+
Specializations of `basic_const_iterator` are constant iterators.
|
| 3081 |
+
|
| 3082 |
+
#### Alias templates <a id="const.iterators.alias">[[const.iterators.alias]]</a>
|
| 3083 |
+
|
| 3084 |
+
``` cpp
|
| 3085 |
+
template<indirectly_readable It>
|
| 3086 |
+
using iter_const_reference_t =
|
| 3087 |
+
common_reference_t<const iter_value_t<It>&&, iter_reference_t<It>>;
|
| 3088 |
+
|
| 3089 |
+
template<class It>
|
| 3090 |
+
concept constant-iterator = // exposition only
|
| 3091 |
+
input_iterator<It> && same_as<iter_const_reference_t<It>, iter_reference_t<It>>;
|
| 3092 |
+
|
| 3093 |
+
template<input_iterator I>
|
| 3094 |
+
using const_iterator = see below;
|
| 3095 |
+
```
|
| 3096 |
+
|
| 3097 |
+
*Result:* If `I` models `constant-iterator`, `I`. Otherwise,
|
| 3098 |
+
`basic_const_iterator<I>`.
|
| 3099 |
+
|
| 3100 |
+
``` cpp
|
| 3101 |
+
template<semiregular S>
|
| 3102 |
+
using const_sentinel = see below;
|
| 3103 |
+
```
|
| 3104 |
+
|
| 3105 |
+
*Result:* If `S` models `input_iterator`, `const_iterator<S>`.
|
| 3106 |
+
Otherwise, `S`.
|
| 3107 |
+
|
| 3108 |
+
#### Class template `basic_const_iterator` <a id="const.iterators.iterator">[[const.iterators.iterator]]</a>
|
| 3109 |
+
|
| 3110 |
+
``` cpp
|
| 3111 |
+
namespace std {
|
| 3112 |
+
template<class I>
|
| 3113 |
+
concept not-a-const-iterator = see below; // exposition only
|
| 3114 |
+
|
| 3115 |
+
template<indirectly_readable I>
|
| 3116 |
+
using iter-const-rvalue-reference-t = // exposition only
|
| 3117 |
+
common_reference_t<const iter_value_t<I>&&, iter_rvalue_reference_t<I>>;
|
| 3118 |
+
|
| 3119 |
+
template<input_iterator Iterator>
|
| 3120 |
+
class basic_const_iterator {
|
| 3121 |
+
Iterator current_ = Iterator(); // exposition only
|
| 3122 |
+
using reference = iter_const_reference_t<Iterator>; // exposition only
|
| 3123 |
+
using rvalue-reference = // exposition only
|
| 3124 |
+
iter-const-rvalue-reference-t<Iterator>;
|
| 3125 |
+
|
| 3126 |
+
public:
|
| 3127 |
+
using iterator_concept = see below;
|
| 3128 |
+
using iterator_category = see below; // not always present
|
| 3129 |
+
using value_type = iter_value_t<Iterator>;
|
| 3130 |
+
using difference_type = iter_difference_t<Iterator>;
|
| 3131 |
+
|
| 3132 |
+
basic_const_iterator() requires default_initializable<Iterator> = default;
|
| 3133 |
+
constexpr basic_const_iterator(Iterator current);
|
| 3134 |
+
template<convertible_to<Iterator> U>
|
| 3135 |
+
constexpr basic_const_iterator(basic_const_iterator<U> current);
|
| 3136 |
+
template<different-from<basic_const_iterator> T>
|
| 3137 |
+
requires convertible_to<T, Iterator>
|
| 3138 |
+
constexpr basic_const_iterator(T&& current);
|
| 3139 |
+
|
| 3140 |
+
constexpr const Iterator& base() const & noexcept;
|
| 3141 |
+
constexpr Iterator base() &&;
|
| 3142 |
+
|
| 3143 |
+
constexpr reference operator*() const;
|
| 3144 |
+
constexpr const auto* operator->() const
|
| 3145 |
+
requires is_lvalue_reference_v<iter_reference_t<Iterator>> &&
|
| 3146 |
+
same_as<remove_cvref_t<iter_reference_t<Iterator>>, value_type>;
|
| 3147 |
+
|
| 3148 |
+
constexpr basic_const_iterator& operator++();
|
| 3149 |
+
constexpr void operator++(int);
|
| 3150 |
+
constexpr basic_const_iterator operator++(int) requires forward_iterator<Iterator>;
|
| 3151 |
+
|
| 3152 |
+
constexpr basic_const_iterator& operator--() requires bidirectional_iterator<Iterator>;
|
| 3153 |
+
constexpr basic_const_iterator operator--(int) requires bidirectional_iterator<Iterator>;
|
| 3154 |
+
|
| 3155 |
+
constexpr basic_const_iterator& operator+=(difference_type n)
|
| 3156 |
+
requires random_access_iterator<Iterator>;
|
| 3157 |
+
constexpr basic_const_iterator& operator-=(difference_type n)
|
| 3158 |
+
requires random_access_iterator<Iterator>;
|
| 3159 |
+
|
| 3160 |
+
constexpr reference operator[](difference_type n) const
|
| 3161 |
+
requires random_access_iterator<Iterator>;
|
| 3162 |
+
|
| 3163 |
+
template<sentinel_for<Iterator> S>
|
| 3164 |
+
constexpr bool operator==(const S& s) const;
|
| 3165 |
+
|
| 3166 |
+
constexpr bool operator<(const basic_const_iterator& y) const
|
| 3167 |
+
requires random_access_iterator<Iterator>;
|
| 3168 |
+
constexpr bool operator>(const basic_const_iterator& y) const
|
| 3169 |
+
requires random_access_iterator<Iterator>;
|
| 3170 |
+
constexpr bool operator<=(const basic_const_iterator& y) const
|
| 3171 |
+
requires random_access_iterator<Iterator>;
|
| 3172 |
+
constexpr bool operator>=(const basic_const_iterator& y) const
|
| 3173 |
+
requires random_access_iterator<Iterator>;
|
| 3174 |
+
constexpr auto operator<=>(const basic_const_iterator& y) const
|
| 3175 |
+
requires random_access_iterator<Iterator> && three_way_comparable<Iterator>;
|
| 3176 |
+
|
| 3177 |
+
template<different-from<basic_const_iterator> I>
|
| 3178 |
+
constexpr bool operator<(const I& y) const
|
| 3179 |
+
requires random_access_iterator<Iterator> && totally_ordered_with<Iterator, I>;
|
| 3180 |
+
template<different-from<basic_const_iterator> I>
|
| 3181 |
+
constexpr bool operator>(const I& y) const
|
| 3182 |
+
requires random_access_iterator<Iterator> && totally_ordered_with<Iterator, I>;
|
| 3183 |
+
template<different-from<basic_const_iterator> I>
|
| 3184 |
+
constexpr bool operator<=(const I& y) const
|
| 3185 |
+
requires random_access_iterator<Iterator> && totally_ordered_with<Iterator, I>;
|
| 3186 |
+
template<different-from<basic_const_iterator> I>
|
| 3187 |
+
constexpr bool operator>=(const I& y) const
|
| 3188 |
+
requires random_access_iterator<Iterator> && totally_ordered_with<Iterator, I>;
|
| 3189 |
+
template<different-from<basic_const_iterator> I>
|
| 3190 |
+
constexpr auto operator<=>(const I& y) const
|
| 3191 |
+
requires random_access_iterator<Iterator> && totally_ordered_with<Iterator, I> &&
|
| 3192 |
+
three_way_comparable_with<Iterator, I>;
|
| 3193 |
+
template<not-a-const-iterator I>
|
| 3194 |
+
friend constexpr bool operator<(const I& x, const basic_const_iterator& y)
|
| 3195 |
+
requires random_access_iterator<Iterator> && totally_ordered_with<Iterator, I>;
|
| 3196 |
+
template<not-a-const-iterator I>
|
| 3197 |
+
friend constexpr bool operator>(const I& x, const basic_const_iterator& y)
|
| 3198 |
+
requires random_access_iterator<Iterator> && totally_ordered_with<Iterator, I>;
|
| 3199 |
+
template<not-a-const-iterator I>
|
| 3200 |
+
friend constexpr bool operator<=(const I& x, const basic_const_iterator& y)
|
| 3201 |
+
requires random_access_iterator<Iterator> && totally_ordered_with<Iterator, I>;
|
| 3202 |
+
template<not-a-const-iterator I>
|
| 3203 |
+
friend constexpr bool operator>=(const I& x, const basic_const_iterator& y)
|
| 3204 |
+
requires random_access_iterator<Iterator> && totally_ordered_with<Iterator, I>;
|
| 3205 |
+
|
| 3206 |
+
friend constexpr basic_const_iterator operator+(const basic_const_iterator& i,
|
| 3207 |
+
difference_type n)
|
| 3208 |
+
requires random_access_iterator<Iterator>;
|
| 3209 |
+
friend constexpr basic_const_iterator operator+(difference_type n,
|
| 3210 |
+
const basic_const_iterator& i)
|
| 3211 |
+
requires random_access_iterator<Iterator>;
|
| 3212 |
+
friend constexpr basic_const_iterator operator-(const basic_const_iterator& i,
|
| 3213 |
+
difference_type n)
|
| 3214 |
+
requires random_access_iterator<Iterator>;
|
| 3215 |
+
template<sized_sentinel_for<Iterator> S>
|
| 3216 |
+
constexpr difference_type operator-(const S& y) const;
|
| 3217 |
+
template<not-a-const-iterator S>
|
| 3218 |
+
requires sized_sentinel_for<S, Iterator>
|
| 3219 |
+
friend constexpr difference_type operator-(const S& x, const basic_const_iterator& y);
|
| 3220 |
+
friend constexpr rvalue-reference iter_move(const basic_const_iterator& i)
|
| 3221 |
+
noexcept(noexcept(static_cast<rvalue-reference>(ranges::iter_move(i.current_))))
|
| 3222 |
+
{
|
| 3223 |
+
return static_cast<rvalue-reference>(ranges::iter_move(i.current_));
|
| 3224 |
+
}
|
| 3225 |
+
};
|
| 3226 |
+
}
|
| 3227 |
+
```
|
| 3228 |
+
|
| 3229 |
+
Given some type `I`, the concept *not-a-const-iterator* is defined as
|
| 3230 |
+
`false` if `I` is a specialization of `basic_const_iterator` and `true`
|
| 3231 |
+
otherwise.
|
| 3232 |
+
|
| 3233 |
+
#### Member types <a id="const.iterators.types">[[const.iterators.types]]</a>
|
| 3234 |
+
|
| 3235 |
+
`basic_const_iterator<Iterator>::iterator_concept` is defined as
|
| 3236 |
+
follows:
|
| 3237 |
+
|
| 3238 |
+
- If `Iterator` models `contiguous_iterator`, then `iterator_concept`
|
| 3239 |
+
denotes `contiguous_iterator_tag`.
|
| 3240 |
+
- Otherwise, if `Iterator` models `random_access_iterator`, then
|
| 3241 |
+
`iterator_concept` denotes `random_access_iterator_tag`.
|
| 3242 |
+
- Otherwise, if `Iterator` models `bidirectional_iterator`, then
|
| 3243 |
+
`iterator_concept` denotes `bidirectional_iterator_tag`.
|
| 3244 |
+
- Otherwise, if `Iterator` models `forward_iterator`, then
|
| 3245 |
+
`iterator_concept` denotes `forward_iterator_tag`.
|
| 3246 |
+
- Otherwise, `iterator_concept` denotes `input_iterator_tag`.
|
| 3247 |
+
|
| 3248 |
+
The member *typedef-name* `iterator_category` is defined if and only if
|
| 3249 |
+
`Iterator` models `forward_iterator`. In that case,
|
| 3250 |
+
`basic_const_iterator<Iterator>::iterator_category` denotes the type
|
| 3251 |
+
`iterator_traits<{}Iterator>::iterator_category`.
|
| 3252 |
+
|
| 3253 |
+
#### Operations <a id="const.iterators.ops">[[const.iterators.ops]]</a>
|
| 3254 |
+
|
| 3255 |
+
``` cpp
|
| 3256 |
+
constexpr basic_const_iterator(Iterator current);
|
| 3257 |
+
```
|
| 3258 |
+
|
| 3259 |
+
*Effects:* Initializes *current\_* with `std::move(current)`.
|
| 3260 |
+
|
| 3261 |
+
``` cpp
|
| 3262 |
+
template<convertible_to<Iterator> U>
|
| 3263 |
+
constexpr basic_const_iterator(basic_const_iterator<U> current);
|
| 3264 |
+
```
|
| 3265 |
+
|
| 3266 |
+
*Effects:* Initializes *current\_* with
|
| 3267 |
+
`std::move(current.`*`current_`*`)`.
|
| 3268 |
+
|
| 3269 |
+
``` cpp
|
| 3270 |
+
template<different-from<basic_const_iterator> T>
|
| 3271 |
+
requires convertible_to<T, Iterator>
|
| 3272 |
+
constexpr basic_const_iterator(T&& current);
|
| 3273 |
+
```
|
| 3274 |
+
|
| 3275 |
+
*Effects:* Initializes *current\_* with `std::forward<T>(current)`.
|
| 3276 |
+
|
| 3277 |
+
``` cpp
|
| 3278 |
+
constexpr const Iterator& base() const & noexcept;
|
| 3279 |
+
```
|
| 3280 |
+
|
| 3281 |
+
*Effects:* Equivalent to: `return `*`current_`*`;`
|
| 3282 |
+
|
| 3283 |
+
``` cpp
|
| 3284 |
+
constexpr Iterator base() &&;
|
| 3285 |
+
```
|
| 3286 |
+
|
| 3287 |
+
*Effects:* Equivalent to: `return std::move(`*`current_`*`);`
|
| 3288 |
+
|
| 3289 |
+
``` cpp
|
| 3290 |
+
constexpr reference operator*() const;
|
| 3291 |
+
```
|
| 3292 |
+
|
| 3293 |
+
*Effects:* Equivalent to:
|
| 3294 |
+
`return static_cast<`*`reference`*`>(*`*`current_`*`);`
|
| 3295 |
+
|
| 3296 |
+
``` cpp
|
| 3297 |
+
constexpr const auto* operator->() const
|
| 3298 |
+
requires is_lvalue_reference_v<iter_reference_t<Iterator>> &&
|
| 3299 |
+
same_as<remove_cvref_t<iter_reference_t<Iterator>>, value_type>;
|
| 3300 |
+
```
|
| 3301 |
+
|
| 3302 |
+
*Returns:* If `Iterator` models `contiguous_iterator`,
|
| 3303 |
+
`to_address(`*`current_`*`)`; otherwise, `addressof(*`*`current_`*`)`.
|
| 3304 |
+
|
| 3305 |
+
``` cpp
|
| 3306 |
+
constexpr basic_const_iterator& operator++();
|
| 3307 |
+
```
|
| 3308 |
+
|
| 3309 |
+
*Effects:* Equivalent to:
|
| 3310 |
+
|
| 3311 |
+
``` cpp
|
| 3312 |
+
++current_;
|
| 3313 |
+
return *this;
|
| 3314 |
+
```
|
| 3315 |
+
|
| 3316 |
+
``` cpp
|
| 3317 |
+
constexpr void operator++(int);
|
| 3318 |
+
```
|
| 3319 |
+
|
| 3320 |
+
*Effects:* Equivalent to: `++`*`current_`*`;`
|
| 3321 |
+
|
| 3322 |
+
``` cpp
|
| 3323 |
+
constexpr basic_const_iterator operator++(int) requires forward_iterator<Iterator>;
|
| 3324 |
+
```
|
| 3325 |
+
|
| 3326 |
+
*Effects:* Equivalent to:
|
| 3327 |
+
|
| 3328 |
+
``` cpp
|
| 3329 |
+
auto tmp = *this;
|
| 3330 |
+
++*this;
|
| 3331 |
+
return tmp;
|
| 3332 |
+
```
|
| 3333 |
+
|
| 3334 |
+
``` cpp
|
| 3335 |
+
constexpr basic_const_iterator& operator--() requires bidirectional_iterator<Iterator>;
|
| 3336 |
+
```
|
| 3337 |
+
|
| 3338 |
+
*Effects:* Equivalent to:
|
| 3339 |
+
|
| 3340 |
+
``` cpp
|
| 3341 |
+
--current_;
|
| 3342 |
+
return *this;
|
| 3343 |
+
```
|
| 3344 |
+
|
| 3345 |
+
``` cpp
|
| 3346 |
+
constexpr basic_const_iterator operator--(int) requires bidirectional_iterator<Iterator>;
|
| 3347 |
+
```
|
| 3348 |
+
|
| 3349 |
+
*Effects:* Equivalent to:
|
| 3350 |
+
|
| 3351 |
+
``` cpp
|
| 3352 |
+
auto tmp = *this;
|
| 3353 |
+
--*this;
|
| 3354 |
+
return tmp;
|
| 3355 |
+
```
|
| 3356 |
+
|
| 3357 |
+
``` cpp
|
| 3358 |
+
constexpr basic_const_iterator& operator+=(difference_type n)
|
| 3359 |
+
requires random_access_iterator<Iterator>;
|
| 3360 |
+
constexpr basic_const_iterator& operator-=(difference_type n)
|
| 3361 |
+
requires random_access_iterator<Iterator>;
|
| 3362 |
+
```
|
| 3363 |
+
|
| 3364 |
+
Let *`op`* be the operator.
|
| 3365 |
+
|
| 3366 |
+
*Effects:* Equivalent to:
|
| 3367 |
+
|
| 3368 |
+
``` cpp
|
| 3369 |
+
current_ op n;
|
| 3370 |
+
return *this;
|
| 3371 |
+
```
|
| 3372 |
+
|
| 3373 |
+
``` cpp
|
| 3374 |
+
constexpr reference operator[](difference_type n) const requires random_access_iterator<Iterator>
|
| 3375 |
+
```
|
| 3376 |
+
|
| 3377 |
+
*Effects:* Equivalent to:
|
| 3378 |
+
`return static_cast<`*`reference`*`>(`*`current_`*`[n]);`
|
| 3379 |
+
|
| 3380 |
+
``` cpp
|
| 3381 |
+
template<sentinel_for<Iterator> S>
|
| 3382 |
+
constexpr bool operator==(const S& s) const;
|
| 3383 |
+
```
|
| 3384 |
+
|
| 3385 |
+
*Effects:* Equivalent to: `return `*`current_`*` == s;`
|
| 3386 |
+
|
| 3387 |
+
``` cpp
|
| 3388 |
+
constexpr bool operator<(const basic_const_iterator& y) const
|
| 3389 |
+
requires random_access_iterator<Iterator>;
|
| 3390 |
+
constexpr bool operator>(const basic_const_iterator& y) const
|
| 3391 |
+
requires random_access_iterator<Iterator>;
|
| 3392 |
+
constexpr bool operator<=(const basic_const_iterator& y) const
|
| 3393 |
+
requires random_access_iterator<Iterator>;
|
| 3394 |
+
constexpr bool operator>=(const basic_const_iterator& y) const
|
| 3395 |
+
requires random_access_iterator<Iterator>;
|
| 3396 |
+
constexpr auto operator<=>(const basic_const_iterator& y) const
|
| 3397 |
+
requires random_access_iterator<Iterator> && three_way_comparable<Iterator>;
|
| 3398 |
+
```
|
| 3399 |
+
|
| 3400 |
+
Let *`op`* be the operator.
|
| 3401 |
+
|
| 3402 |
+
*Effects:* Equivalent to:
|
| 3403 |
+
`return `*`current_`*` `*`op`*` `*`y.current_`*`;`
|
| 3404 |
+
|
| 3405 |
+
``` cpp
|
| 3406 |
+
template<different-from<basic_const_iterator> I>
|
| 3407 |
+
constexpr bool operator<(const I& y) const
|
| 3408 |
+
requires random_access_iterator<Iterator> && totally_ordered_with<Iterator, I>;
|
| 3409 |
+
template<different-from<basic_const_iterator> I>
|
| 3410 |
+
constexpr bool operator>(const I& y) const
|
| 3411 |
+
requires random_access_iterator<Iterator> && totally_ordered_with<Iterator, I>;
|
| 3412 |
+
template<different-from<basic_const_iterator> I>
|
| 3413 |
+
constexpr bool operator<=(const I& y) const
|
| 3414 |
+
requires random_access_iterator<Iterator> && totally_ordered_with<Iterator, I>;
|
| 3415 |
+
template<different-from<basic_const_iterator> I>
|
| 3416 |
+
constexpr bool operator>=(const I& y) const
|
| 3417 |
+
requires random_access_iterator<Iterator> && totally_ordered_with<Iterator, I>;
|
| 3418 |
+
template<different-from<basic_const_iterator> I>
|
| 3419 |
+
constexpr auto operator<=>(const I& y) const
|
| 3420 |
+
requires random_access_iterator<Iterator> && totally_ordered_with<Iterator, I> &&
|
| 3421 |
+
three_way_comparable_with<Iterator, I>;
|
| 3422 |
+
```
|
| 3423 |
+
|
| 3424 |
+
Let *`op`* be the operator.
|
| 3425 |
+
|
| 3426 |
+
*Effects:* Equivalent to: `return `*`current_`*` `*`op`*` y;`
|
| 3427 |
+
|
| 3428 |
+
``` cpp
|
| 3429 |
+
template<not-a-const-iterator I>
|
| 3430 |
+
friend constexpr bool operator<(const I& x, const basic_const_iterator& y)
|
| 3431 |
+
requires random_access_iterator<Iterator> && totally_ordered_with<Iterator, I>;
|
| 3432 |
+
template<not-a-const-iterator I>
|
| 3433 |
+
friend constexpr bool operator>(const I& x, const basic_const_iterator& y)
|
| 3434 |
+
requires random_access_iterator<Iterator> && totally_ordered_with<Iterator, I>;
|
| 3435 |
+
template<not-a-const-iterator I>
|
| 3436 |
+
friend constexpr bool operator<=(const I& x, const basic_const_iterator& y)
|
| 3437 |
+
requires random_access_iterator<Iterator> && totally_ordered_with<Iterator, I>;
|
| 3438 |
+
template<not-a-const-iterator I>
|
| 3439 |
+
friend constexpr bool operator>=(const I& x, const basic_const_iterator& y)
|
| 3440 |
+
requires random_access_iterator<Iterator> && totally_ordered_with<Iterator, I>;
|
| 3441 |
+
```
|
| 3442 |
+
|
| 3443 |
+
Let *`op`* be the operator.
|
| 3444 |
+
|
| 3445 |
+
*Returns:* Equivalent to: `return x `*`op`*` y.`*`current_`*`;`
|
| 3446 |
+
|
| 3447 |
+
``` cpp
|
| 3448 |
+
friend constexpr basic_const_iterator operator+(const basic_const_iterator& i, difference_type n)
|
| 3449 |
+
requires random_access_iterator<Iterator>;
|
| 3450 |
+
friend constexpr basic_const_iterator operator+(difference_type n, const basic_const_iterator& i)
|
| 3451 |
+
requires random_access_iterator<Iterator>;
|
| 3452 |
+
```
|
| 3453 |
+
|
| 3454 |
+
*Effects:* Equivalent to:
|
| 3455 |
+
`return basic_const_iterator(i.`*`current_`*` + n);`
|
| 3456 |
+
|
| 3457 |
+
``` cpp
|
| 3458 |
+
friend constexpr basic_const_iterator operator-(const basic_const_iterator& i, difference_type n)
|
| 3459 |
+
requires random_access_iterator<Iterator>;
|
| 3460 |
+
```
|
| 3461 |
+
|
| 3462 |
+
*Effects:* Equivalent to:
|
| 3463 |
+
`return basic_const_iterator(i.`*`current_`*` - n);`
|
| 3464 |
+
|
| 3465 |
+
``` cpp
|
| 3466 |
+
template<sized_sentinel_for<Iterator> S>
|
| 3467 |
+
constexpr difference_type operator-(const S& y) const;
|
| 3468 |
+
```
|
| 3469 |
+
|
| 3470 |
+
*Effects:* Equivalent to: `return `*`current_`*` - y;`
|
| 3471 |
+
|
| 3472 |
+
``` cpp
|
| 3473 |
+
template<not-a-const-iterator S>
|
| 3474 |
+
requires sized_sentinel_for<S, Iterator>
|
| 3475 |
+
friend constexpr difference_type operator-(const S& x, const basic_const_iterator& y);
|
| 3476 |
+
```
|
| 3477 |
+
|
| 3478 |
+
*Effects:* Equivalent to: `return x - y.`*`current_`*`;`
|
| 3479 |
+
|
| 3480 |
### Move iterators and sentinels <a id="move.iterators">[[move.iterators]]</a>
|
| 3481 |
|
| 3482 |
+
#### General <a id="move.iterators.general">[[move.iterators.general]]</a>
|
| 3483 |
+
|
| 3484 |
Class template `move_iterator` is an iterator adaptor with the same
|
| 3485 |
behavior as the underlying iterator except that its indirection operator
|
| 3486 |
implicitly converts the value returned by the underlying iterator’s
|
| 3487 |
indirection operator to an rvalue. Some generic algorithms can be called
|
| 3488 |
with move iterators to replace copying with moving.
|
|
|
|
| 3505 |
namespace std {
|
| 3506 |
template<class Iterator>
|
| 3507 |
class move_iterator {
|
| 3508 |
public:
|
| 3509 |
using iterator_type = Iterator;
|
| 3510 |
+
using iterator_concept = see below;
|
| 3511 |
+
using iterator_category = see below; // not always present
|
| 3512 |
using value_type = iter_value_t<Iterator>;
|
| 3513 |
using difference_type = iter_difference_t<Iterator>;
|
| 3514 |
using pointer = Iterator;
|
| 3515 |
using reference = iter_rvalue_reference_t<Iterator>;
|
| 3516 |
|
| 3517 |
constexpr move_iterator();
|
| 3518 |
constexpr explicit move_iterator(Iterator i);
|
| 3519 |
template<class U> constexpr move_iterator(const move_iterator<U>& u);
|
| 3520 |
template<class U> constexpr move_iterator& operator=(const move_iterator<U>& u);
|
| 3521 |
|
| 3522 |
+
constexpr const Iterator& base() const & noexcept;
|
| 3523 |
+
constexpr Iterator base() &&;
|
| 3524 |
constexpr reference operator*() const;
|
| 3525 |
|
| 3526 |
constexpr move_iterator& operator++();
|
| 3527 |
constexpr auto operator++(int);
|
| 3528 |
constexpr move_iterator& operator--();
|
|
|
|
| 3555 |
Iterator current; // exposition only
|
| 3556 |
};
|
| 3557 |
}
|
| 3558 |
```
|
| 3559 |
|
| 3560 |
+
The member *typedef-name* `iterator_concept` is defined as follows:
|
| 3561 |
+
|
| 3562 |
+
- If `Iterator` models `random_access_iterator`, then `iterator_concept`
|
| 3563 |
+
denotes `random_access_iterator_tag`.
|
| 3564 |
+
- Otherwise, if `Iterator` models `bidirectional_iterator`, then
|
| 3565 |
+
`iterator_concept` denotes `bidirectional_iterator_tag`.
|
| 3566 |
+
- Otherwise, if `Iterator` models `forward_iterator`, then
|
| 3567 |
+
`iterator_concept` denotes `forward_iterator_tag`.
|
| 3568 |
+
- Otherwise, `iterator_concept` denotes `input_iterator_tag`.
|
| 3569 |
+
|
| 3570 |
+
The member *typedef-name* `iterator_category` is defined if and only if
|
| 3571 |
+
the *qualified-id* `iterator_traits<Iterator>::iterator_category` is
|
| 3572 |
+
valid and denotes a type. In that case, `iterator_category` denotes
|
| 3573 |
|
| 3574 |
- `random_access_iterator_tag` if the type
|
| 3575 |
`iterator_traits<{}Iterator>::iterator_category` models
|
| 3576 |
`derived_from<random_access_iterator_tag>`, and
|
| 3577 |
- `iterator_traits<{}Iterator>::iterator_category` otherwise.
|
|
|
|
| 3594 |
|
| 3595 |
``` cpp
|
| 3596 |
constexpr move_iterator();
|
| 3597 |
```
|
| 3598 |
|
| 3599 |
+
*Effects:* Value-initializes `current`.
|
|
|
|
|
|
|
|
|
|
| 3600 |
|
| 3601 |
``` cpp
|
| 3602 |
constexpr explicit move_iterator(Iterator i);
|
| 3603 |
```
|
| 3604 |
|
| 3605 |
+
*Effects:* Initializes `current` with `std::move(i)`.
|
|
|
|
| 3606 |
|
| 3607 |
``` cpp
|
| 3608 |
template<class U> constexpr move_iterator(const move_iterator<U>& u);
|
| 3609 |
```
|
| 3610 |
|
| 3611 |
+
*Constraints:* `is_same_v<U, Iterator>` is `false` and `const U&` models
|
| 3612 |
+
`convertible_to<Iterator>`.
|
| 3613 |
|
| 3614 |
+
*Effects:* Initializes `current` with `u.current`.
|
|
|
|
| 3615 |
|
| 3616 |
``` cpp
|
| 3617 |
template<class U> constexpr move_iterator& operator=(const move_iterator<U>& u);
|
| 3618 |
```
|
| 3619 |
|
| 3620 |
+
*Constraints:* `is_same_v<U, Iterator>` is `false`, `const U&` models
|
| 3621 |
+
`convertible_to<Iterator>`, and `assignable_from<Iterator&, const U&>`
|
| 3622 |
+
is modeled.
|
| 3623 |
|
| 3624 |
+
*Effects:* Assigns `u.current` to `current`.
|
| 3625 |
+
|
| 3626 |
+
*Returns:* `*this`.
|
| 3627 |
|
| 3628 |
#### Conversion <a id="move.iter.op.conv">[[move.iter.op.conv]]</a>
|
| 3629 |
|
| 3630 |
``` cpp
|
| 3631 |
+
constexpr const Iterator& base() const & noexcept;
|
| 3632 |
```
|
| 3633 |
|
|
|
|
|
|
|
|
|
|
|
|
|
| 3634 |
*Returns:* `current`.
|
| 3635 |
|
| 3636 |
``` cpp
|
| 3637 |
constexpr Iterator base() &&;
|
| 3638 |
```
|
|
|
|
| 3649 |
|
| 3650 |
``` cpp
|
| 3651 |
constexpr reference operator[](difference_type n) const;
|
| 3652 |
```
|
| 3653 |
|
| 3654 |
+
*Effects:* Equivalent to: `return ranges::iter_move(current + n);`
|
| 3655 |
|
| 3656 |
#### Navigation <a id="move.iter.nav">[[move.iter.nav]]</a>
|
| 3657 |
|
| 3658 |
``` cpp
|
| 3659 |
constexpr move_iterator& operator++();
|
|
|
|
| 3679 |
|
| 3680 |
``` cpp
|
| 3681 |
constexpr move_iterator& operator--();
|
| 3682 |
```
|
| 3683 |
|
| 3684 |
+
*Effects:* As if by `–current`.
|
| 3685 |
|
| 3686 |
*Returns:* `*this`.
|
| 3687 |
|
| 3688 |
``` cpp
|
| 3689 |
constexpr move_iterator operator--(int);
|
|
|
|
| 3792 |
|
| 3793 |
#### Non-member functions <a id="move.iter.nonmember">[[move.iter.nonmember]]</a>
|
| 3794 |
|
| 3795 |
``` cpp
|
| 3796 |
template<class Iterator1, class Iterator2>
|
| 3797 |
+
constexpr auto operator-(
|
| 3798 |
+
const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y)
|
| 3799 |
-> decltype(x.base() - y.base());
|
| 3800 |
template<sized_sentinel_for<Iterator> S>
|
| 3801 |
friend constexpr iter_difference_t<Iterator>
|
| 3802 |
operator-(const move_sentinel<S>& x, const move_iterator& y);
|
| 3803 |
template<sized_sentinel_for<Iterator> S>
|
|
|
|
| 3811 |
template<class Iterator>
|
| 3812 |
constexpr move_iterator<Iterator>
|
| 3813 |
operator+(iter_difference_t<Iterator> n, const move_iterator<Iterator>& x);
|
| 3814 |
```
|
| 3815 |
|
| 3816 |
+
*Constraints:* `x.base() + n` is well-formed and has type `Iterator`.
|
| 3817 |
|
| 3818 |
*Returns:* `x + n`.
|
| 3819 |
|
| 3820 |
``` cpp
|
| 3821 |
friend constexpr iter_rvalue_reference_t<Iterator>
|
|
|
|
| 3845 |
|
| 3846 |
Class template `move_sentinel` is a sentinel adaptor useful for denoting
|
| 3847 |
ranges together with `move_iterator`. When an input iterator type `I`
|
| 3848 |
and sentinel type `S` model `sentinel_for<S, I>`, `move_sentinel<S>` and
|
| 3849 |
`move_iterator<I>` model
|
| 3850 |
+
`sentinel_for<move_sentinel<S>, move_iterator<I>>` as well.
|
| 3851 |
|
| 3852 |
[*Example 1*:
|
| 3853 |
|
| 3854 |
A `move_if` algorithm is easily implemented with `copy_if` using
|
| 3855 |
`move_iterator` and `move_sentinel`:
|
|
|
|
| 3857 |
``` cpp
|
| 3858 |
template<input_iterator I, sentinel_for<I> S, weakly_incrementable O,
|
| 3859 |
indirect_unary_predicate<I> Pred>
|
| 3860 |
requires indirectly_movable<I, O>
|
| 3861 |
void move_if(I first, S last, O out, Pred pred) {
|
| 3862 |
+
ranges::copy_if(move_iterator<I>{std::move(first)}, move_sentinel<S>{last},
|
| 3863 |
+
std::move(out), pred);
|
| 3864 |
}
|
| 3865 |
```
|
| 3866 |
|
| 3867 |
— *end example*]
|
| 3868 |
|
|
|
|
| 3879 |
template<class S2>
|
| 3880 |
requires assignable_from<S&, const S2&>
|
| 3881 |
constexpr move_sentinel& operator=(const move_sentinel<S2>& s);
|
| 3882 |
|
| 3883 |
constexpr S base() const;
|
| 3884 |
+
|
| 3885 |
private:
|
| 3886 |
S last; // exposition only
|
| 3887 |
};
|
| 3888 |
}
|
| 3889 |
```
|
|
|
|
| 3959 |
namespace std {
|
| 3960 |
template<input_or_output_iterator I, sentinel_for<I> S>
|
| 3961 |
requires (!same_as<I, S> && copyable<I>)
|
| 3962 |
class common_iterator {
|
| 3963 |
public:
|
| 3964 |
+
constexpr common_iterator() requires default_initializable<I> = default;
|
| 3965 |
constexpr common_iterator(I i);
|
| 3966 |
constexpr common_iterator(S s);
|
| 3967 |
template<class I2, class S2>
|
| 3968 |
requires convertible_to<const I2&, I> && convertible_to<const S2&, S>
|
| 3969 |
constexpr common_iterator(const common_iterator<I2, S2>& x);
|
| 3970 |
|
| 3971 |
template<class I2, class S2>
|
| 3972 |
requires convertible_to<const I2&, I> && convertible_to<const S2&, S> &&
|
| 3973 |
assignable_from<I&, const I2&> && assignable_from<S&, const S2&>
|
| 3974 |
+
constexpr common_iterator& operator=(const common_iterator<I2, S2>& x);
|
| 3975 |
|
| 3976 |
+
constexpr decltype(auto) operator*();
|
| 3977 |
+
constexpr decltype(auto) operator*() const
|
| 3978 |
requires dereferenceable<const I>;
|
| 3979 |
+
constexpr auto operator->() const
|
| 3980 |
requires see below;
|
| 3981 |
|
| 3982 |
+
constexpr common_iterator& operator++();
|
| 3983 |
+
constexpr decltype(auto) operator++(int);
|
| 3984 |
|
| 3985 |
template<class I2, sentinel_for<I> S2>
|
| 3986 |
requires sentinel_for<S, I2>
|
| 3987 |
+
friend constexpr bool operator==(
|
| 3988 |
const common_iterator& x, const common_iterator<I2, S2>& y);
|
| 3989 |
template<class I2, sentinel_for<I> S2>
|
| 3990 |
requires sentinel_for<S, I2> && equality_comparable_with<I, I2>
|
| 3991 |
+
friend constexpr bool operator==(
|
| 3992 |
const common_iterator& x, const common_iterator<I2, S2>& y);
|
| 3993 |
|
| 3994 |
template<sized_sentinel_for<I> I2, sized_sentinel_for<I> S2>
|
| 3995 |
requires sized_sentinel_for<S, I2>
|
| 3996 |
+
friend constexpr iter_difference_t<I2> operator-(
|
| 3997 |
const common_iterator& x, const common_iterator<I2, S2>& y);
|
| 3998 |
|
| 3999 |
+
friend constexpr iter_rvalue_reference_t<I> iter_move(const common_iterator& i)
|
| 4000 |
noexcept(noexcept(ranges::iter_move(declval<const I&>())))
|
| 4001 |
requires input_iterator<I>;
|
| 4002 |
template<indirectly_swappable<I> I2, class S2>
|
| 4003 |
+
friend constexpr void iter_swap(const common_iterator& x, const common_iterator<I2, S2>& y)
|
| 4004 |
noexcept(noexcept(ranges::iter_swap(declval<const I&>(), declval<const I2&>())));
|
| 4005 |
|
| 4006 |
private:
|
| 4007 |
variant<I, S> v_; // exposition only
|
| 4008 |
};
|
|
|
|
| 4029 |
The nested *typedef-name*s of the specialization of `iterator_traits`
|
| 4030 |
for `common_iterator<I, S>` are defined as follows.
|
| 4031 |
|
| 4032 |
- `iterator_concept` denotes `forward_iterator_tag` if `I` models
|
| 4033 |
`forward_iterator`; otherwise it denotes `input_iterator_tag`.
|
| 4034 |
+
- `iterator_category` denotes `forward_iterator_tag` if the
|
| 4035 |
+
*qualified-id* `iterator_traits<I>::iterator_category` is valid and
|
| 4036 |
+
denotes a type that models `derived_from<forward_iterator_tag>`;
|
| 4037 |
+
otherwise it denotes `input_iterator_tag`.
|
| 4038 |
+
- Let `a` denote an lvalue of type `const common_iterator<I, S>`. If the
|
| 4039 |
+
expression `a.operator->()` is well-formed, then `pointer` denotes
|
| 4040 |
+
`decltype(a.operator->())`. Otherwise, `pointer` denotes `void`.
|
| 4041 |
|
| 4042 |
#### Constructors and conversions <a id="common.iter.const">[[common.iter.const]]</a>
|
| 4043 |
|
| 4044 |
``` cpp
|
| 4045 |
constexpr common_iterator(I i);
|
|
|
|
| 4068 |
|
| 4069 |
``` cpp
|
| 4070 |
template<class I2, class S2>
|
| 4071 |
requires convertible_to<const I2&, I> && convertible_to<const S2&, S> &&
|
| 4072 |
assignable_from<I&, const I2&> && assignable_from<S&, const S2&>
|
| 4073 |
+
constexpr common_iterator& operator=(const common_iterator<I2, S2>& x);
|
| 4074 |
```
|
| 4075 |
|
| 4076 |
*Preconditions:* `x.v_.valueless_by_exception()` is `false`.
|
| 4077 |
|
| 4078 |
*Effects:* Equivalent to:
|
|
|
|
| 4085 |
*Returns:* `*this`
|
| 4086 |
|
| 4087 |
#### Accessors <a id="common.iter.access">[[common.iter.access]]</a>
|
| 4088 |
|
| 4089 |
``` cpp
|
| 4090 |
+
constexpr decltype(auto) operator*();
|
| 4091 |
+
constexpr decltype(auto) operator*() const
|
| 4092 |
requires dereferenceable<const I>;
|
| 4093 |
```
|
| 4094 |
|
| 4095 |
+
*Preconditions:* `holds_alternative<I>(v_)` is `true`.
|
| 4096 |
|
| 4097 |
*Effects:* Equivalent to: `return *get<I>(v_);`
|
| 4098 |
|
| 4099 |
``` cpp
|
| 4100 |
+
constexpr auto operator->() const
|
| 4101 |
requires see below;
|
| 4102 |
```
|
| 4103 |
|
| 4104 |
+
The expression in the *requires-clause* is equivalent to:
|
| 4105 |
|
| 4106 |
``` cpp
|
| 4107 |
indirectly_readable<const I> &&
|
| 4108 |
(requires(const I& i) { i.operator->(); } ||
|
| 4109 |
is_reference_v<iter_reference_t<I>> ||
|
| 4110 |
constructible_from<iter_value_t<I>, iter_reference_t<I>>)
|
| 4111 |
```
|
| 4112 |
|
| 4113 |
+
*Preconditions:* `holds_alternative<I>(v_)` is `true`.
|
| 4114 |
|
| 4115 |
*Effects:*
|
| 4116 |
|
| 4117 |
- If `I` is a pointer type or if the expression
|
| 4118 |
`get<I>(v_).operator->()` is well-formed, equivalent to:
|
|
|
|
| 4126 |
- Otherwise, equivalent to: `return `*`proxy`*`(*get<I>(v_));` where
|
| 4127 |
*proxy* is the exposition-only class:
|
| 4128 |
``` cpp
|
| 4129 |
class proxy {
|
| 4130 |
iter_value_t<I> keep_;
|
| 4131 |
+
constexpr proxy(iter_reference_t<I>&& x)
|
| 4132 |
: keep_(std::move(x)) {}
|
| 4133 |
public:
|
| 4134 |
+
constexpr const iter_value_t<I>* operator->() const noexcept {
|
| 4135 |
return addressof(keep_);
|
| 4136 |
}
|
| 4137 |
};
|
| 4138 |
```
|
| 4139 |
|
| 4140 |
#### Navigation <a id="common.iter.nav">[[common.iter.nav]]</a>
|
| 4141 |
|
| 4142 |
``` cpp
|
| 4143 |
+
constexpr common_iterator& operator++();
|
| 4144 |
```
|
| 4145 |
|
| 4146 |
+
*Preconditions:* `holds_alternative<I>(v_)` is `true`.
|
| 4147 |
|
| 4148 |
*Effects:* Equivalent to `++get<I>(v_)`.
|
| 4149 |
|
| 4150 |
*Returns:* `*this`.
|
| 4151 |
|
| 4152 |
``` cpp
|
| 4153 |
+
constexpr decltype(auto) operator++(int);
|
| 4154 |
```
|
| 4155 |
|
| 4156 |
+
*Preconditions:* `holds_alternative<I>(v_)` is `true`.
|
| 4157 |
|
| 4158 |
*Effects:* If `I` models `forward_iterator`, equivalent to:
|
| 4159 |
|
| 4160 |
``` cpp
|
| 4161 |
common_iterator tmp = *this;
|
| 4162 |
++*this;
|
| 4163 |
return tmp;
|
| 4164 |
```
|
| 4165 |
|
| 4166 |
+
Otherwise, if `requires(I& i) { { *i++ } -> `*`can-reference`*`; }` is
|
| 4167 |
+
`true` or
|
| 4168 |
+
|
| 4169 |
+
``` cpp
|
| 4170 |
+
indirectly_readable<I> && constructible_from<iter_value_t<I>, iter_reference_t<I>> &&
|
| 4171 |
+
move_constructible<iter_value_t<I>>
|
| 4172 |
+
```
|
| 4173 |
+
|
| 4174 |
+
is `false`, equivalent to:
|
| 4175 |
+
|
| 4176 |
+
``` cpp
|
| 4177 |
+
return get<I>(v_)++;
|
| 4178 |
+
```
|
| 4179 |
+
|
| 4180 |
+
Otherwise, equivalent to:
|
| 4181 |
+
|
| 4182 |
+
``` cpp
|
| 4183 |
+
postfix-proxy p(**this);
|
| 4184 |
+
++*this;
|
| 4185 |
+
return p;
|
| 4186 |
+
```
|
| 4187 |
+
|
| 4188 |
+
where *postfix-proxy* is the exposition-only class:
|
| 4189 |
+
|
| 4190 |
+
``` cpp
|
| 4191 |
+
class postfix-proxy {
|
| 4192 |
+
iter_value_t<I> keep_;
|
| 4193 |
+
constexpr postfix-proxy(iter_reference_t<I>&& x)
|
| 4194 |
+
: keep_(std::forward<iter_reference_t<I>>(x)) {}
|
| 4195 |
+
public:
|
| 4196 |
+
constexpr const iter_value_t<I>& operator*() const noexcept {
|
| 4197 |
+
return keep_;
|
| 4198 |
+
}
|
| 4199 |
+
};
|
| 4200 |
+
```
|
| 4201 |
|
| 4202 |
#### Comparisons <a id="common.iter.cmp">[[common.iter.cmp]]</a>
|
| 4203 |
|
| 4204 |
``` cpp
|
| 4205 |
template<class I2, sentinel_for<I> S2>
|
| 4206 |
requires sentinel_for<S, I2>
|
| 4207 |
+
friend constexpr bool operator==(
|
| 4208 |
const common_iterator& x, const common_iterator<I2, S2>& y);
|
| 4209 |
```
|
| 4210 |
|
| 4211 |
*Preconditions:* `x.v_.valueless_by_exception()` and
|
| 4212 |
`y.v_.valueless_by_exception()` are each `false`.
|
|
|
|
| 4216 |
`y.v_.index()`.
|
| 4217 |
|
| 4218 |
``` cpp
|
| 4219 |
template<class I2, sentinel_for<I> S2>
|
| 4220 |
requires sentinel_for<S, I2> && equality_comparable_with<I, I2>
|
| 4221 |
+
friend constexpr bool operator==(
|
| 4222 |
const common_iterator& x, const common_iterator<I2, S2>& y);
|
| 4223 |
```
|
| 4224 |
|
| 4225 |
*Preconditions:* `x.v_.valueless_by_exception()` and
|
| 4226 |
`y.v_.valueless_by_exception()` are each `false`.
|
|
|
|
| 4230 |
`y.v_.index()`.
|
| 4231 |
|
| 4232 |
``` cpp
|
| 4233 |
template<sized_sentinel_for<I> I2, sized_sentinel_for<I> S2>
|
| 4234 |
requires sized_sentinel_for<S, I2>
|
| 4235 |
+
friend constexpr iter_difference_t<I2> operator-(
|
| 4236 |
const common_iterator& x, const common_iterator<I2, S2>& y);
|
| 4237 |
```
|
| 4238 |
|
| 4239 |
*Preconditions:* `x.v_.valueless_by_exception()` and
|
| 4240 |
`y.v_.valueless_by_exception()` are each `false`.
|
| 4241 |
|
| 4242 |
*Returns:* `0` if i and j are each `1`, and otherwise
|
| 4243 |
`get<`i`>(x.v_) - get<`j`>(y.v_)`, where i is `x.v_.index()` and j is
|
| 4244 |
`y.v_.index()`.
|
| 4245 |
|
| 4246 |
+
#### Customizations <a id="common.iter.cust">[[common.iter.cust]]</a>
|
| 4247 |
|
| 4248 |
``` cpp
|
| 4249 |
+
friend constexpr iter_rvalue_reference_t<I> iter_move(const common_iterator& i)
|
| 4250 |
noexcept(noexcept(ranges::iter_move(declval<const I&>())))
|
| 4251 |
requires input_iterator<I>;
|
| 4252 |
```
|
| 4253 |
|
| 4254 |
+
*Preconditions:* `holds_alternative<I>(i.v_)` is `true`.
|
| 4255 |
|
| 4256 |
*Effects:* Equivalent to: `return ranges::iter_move(get<I>(i.v_));`
|
| 4257 |
|
| 4258 |
``` cpp
|
| 4259 |
template<indirectly_swappable<I> I2, class S2>
|
| 4260 |
+
friend constexpr void iter_swap(const common_iterator& x, const common_iterator<I2, S2>& y)
|
| 4261 |
noexcept(noexcept(ranges::iter_swap(declval<const I&>(), declval<const I2&>())));
|
| 4262 |
```
|
| 4263 |
|
| 4264 |
*Preconditions:* `holds_alternative<I>(x.v_)` and
|
| 4265 |
`holds_alternative<I2>(y.v_)` are each `true`.
|
| 4266 |
|
| 4267 |
*Effects:* Equivalent to
|
| 4268 |
`ranges::iter_swap(get<I>(x.v_), get<I2>(y.v_))`.
|
| 4269 |
|
| 4270 |
+
### Default sentinel <a id="default.sentinel">[[default.sentinel]]</a>
|
| 4271 |
|
| 4272 |
``` cpp
|
| 4273 |
namespace std {
|
| 4274 |
struct default_sentinel_t { };
|
| 4275 |
}
|
|
|
|
| 4302 |
|
| 4303 |
— *end example*]
|
| 4304 |
|
| 4305 |
Two values `i1` and `i2` of types `counted_iterator<I1>` and
|
| 4306 |
`counted_iterator<I2>` refer to elements of the same sequence if and
|
| 4307 |
+
only if there exists some integer n such that
|
| 4308 |
+
`next(i1.base(), i1.count() + n)` and `next(i2.base(), i2.count() + n)`
|
| 4309 |
refer to the same (possibly past-the-end) element.
|
| 4310 |
|
| 4311 |
``` cpp
|
| 4312 |
namespace std {
|
| 4313 |
template<input_or_output_iterator I>
|
| 4314 |
class counted_iterator {
|
| 4315 |
public:
|
| 4316 |
using iterator_type = I;
|
| 4317 |
+
using value_type = iter_value_t<I>; // present only
|
| 4318 |
+
// if I models indirectly_readable
|
| 4319 |
+
using difference_type = iter_difference_t<I>;
|
| 4320 |
+
using iterator_concept = typename I::iterator_concept; // present only
|
| 4321 |
+
// if the qualified-id I::iterator_concept is valid and denotes a type
|
| 4322 |
+
using iterator_category = typename I::iterator_category; // present only
|
| 4323 |
+
// if the qualified-id I::iterator_category is valid and denotes a type
|
| 4324 |
+
constexpr counted_iterator() requires default_initializable<I> = default;
|
| 4325 |
constexpr counted_iterator(I x, iter_difference_t<I> n);
|
| 4326 |
template<class I2>
|
| 4327 |
requires convertible_to<const I2&, I>
|
| 4328 |
constexpr counted_iterator(const counted_iterator<I2>& x);
|
| 4329 |
|
| 4330 |
template<class I2>
|
| 4331 |
requires assignable_from<I&, const I2&>
|
| 4332 |
constexpr counted_iterator& operator=(const counted_iterator<I2>& x);
|
| 4333 |
|
| 4334 |
+
constexpr const I& base() const & noexcept;
|
| 4335 |
constexpr I base() &&;
|
| 4336 |
constexpr iter_difference_t<I> count() const noexcept;
|
| 4337 |
constexpr decltype(auto) operator*();
|
| 4338 |
constexpr decltype(auto) operator*() const
|
| 4339 |
requires dereferenceable<const I>;
|
| 4340 |
|
| 4341 |
+
constexpr auto operator->() const noexcept
|
| 4342 |
+
requires contiguous_iterator<I>;
|
| 4343 |
+
|
| 4344 |
constexpr counted_iterator& operator++();
|
| 4345 |
+
constexpr decltype(auto) operator++(int);
|
| 4346 |
constexpr counted_iterator operator++(int)
|
| 4347 |
requires forward_iterator<I>;
|
| 4348 |
constexpr counted_iterator& operator--()
|
| 4349 |
requires bidirectional_iterator<I>;
|
| 4350 |
constexpr counted_iterator operator--(int)
|
|
|
|
| 4393 |
private:
|
| 4394 |
I current = I(); // exposition only
|
| 4395 |
iter_difference_t<I> length = 0; // exposition only
|
| 4396 |
};
|
| 4397 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4398 |
template<input_iterator I>
|
| 4399 |
+
requires same_as<ITER_TRAITS(I), iterator_traits<I>> // see [iterator.concepts.general]
|
| 4400 |
struct iterator_traits<counted_iterator<I>> : iterator_traits<I> {
|
| 4401 |
+
using pointer = conditional_t<contiguous_iterator<I>,
|
| 4402 |
+
add_pointer_t<iter_reference_t<I>>, void>;
|
| 4403 |
};
|
| 4404 |
}
|
| 4405 |
```
|
| 4406 |
|
| 4407 |
#### Constructors and conversions <a id="counted.iter.const">[[counted.iter.const]]</a>
|
|
|
|
| 4435 |
*Returns:* `*this`.
|
| 4436 |
|
| 4437 |
#### Accessors <a id="counted.iter.access">[[counted.iter.access]]</a>
|
| 4438 |
|
| 4439 |
``` cpp
|
| 4440 |
+
constexpr const I& base() const & noexcept;
|
| 4441 |
```
|
| 4442 |
|
| 4443 |
*Effects:* Equivalent to: `return current;`
|
| 4444 |
|
| 4445 |
``` cpp
|
|
|
|
| 4460 |
constexpr decltype(auto) operator*();
|
| 4461 |
constexpr decltype(auto) operator*() const
|
| 4462 |
requires dereferenceable<const I>;
|
| 4463 |
```
|
| 4464 |
|
| 4465 |
+
*Preconditions:* `length > 0` is `true`.
|
| 4466 |
+
|
| 4467 |
*Effects:* Equivalent to: `return *current;`
|
| 4468 |
|
| 4469 |
+
``` cpp
|
| 4470 |
+
constexpr auto operator->() const noexcept
|
| 4471 |
+
requires contiguous_iterator<I>;
|
| 4472 |
+
```
|
| 4473 |
+
|
| 4474 |
+
*Effects:* Equivalent to: `return to_address(current);`
|
| 4475 |
+
|
| 4476 |
``` cpp
|
| 4477 |
constexpr decltype(auto) operator[](iter_difference_t<I> n) const
|
| 4478 |
requires random_access_iterator<I>;
|
| 4479 |
```
|
| 4480 |
|
|
|
|
| 4497 |
--length;
|
| 4498 |
return *this;
|
| 4499 |
```
|
| 4500 |
|
| 4501 |
``` cpp
|
| 4502 |
+
constexpr decltype(auto) operator++(int);
|
| 4503 |
```
|
| 4504 |
|
| 4505 |
*Preconditions:* `length > 0`.
|
| 4506 |
|
| 4507 |
*Effects:* Equivalent to:
|
|
|
|
| 4671 |
iter_move(const counted_iterator& i)
|
| 4672 |
noexcept(noexcept(ranges::iter_move(i.current)))
|
| 4673 |
requires input_iterator<I>;
|
| 4674 |
```
|
| 4675 |
|
| 4676 |
+
*Preconditions:* `i.length > 0` is `true`.
|
| 4677 |
+
|
| 4678 |
*Effects:* Equivalent to: `return ranges::iter_move(i.current);`
|
| 4679 |
|
| 4680 |
``` cpp
|
| 4681 |
template<indirectly_swappable<I> I2>
|
| 4682 |
friend constexpr void
|
| 4683 |
iter_swap(const counted_iterator& x, const counted_iterator<I2>& y)
|
| 4684 |
noexcept(noexcept(ranges::iter_swap(x.current, y.current)));
|
| 4685 |
```
|
| 4686 |
|
| 4687 |
+
*Preconditions:* Both `x.length > 0` and `y.length > 0` are `true`.
|
| 4688 |
+
|
| 4689 |
*Effects:* Equivalent to `ranges::iter_swap(x.current, y.current)`.
|
| 4690 |
|
| 4691 |
+
### Unreachable sentinel <a id="unreachable.sentinel">[[unreachable.sentinel]]</a>
|
|
|
|
|
|
|
| 4692 |
|
| 4693 |
Class `unreachable_sentinel_t` can be used with any
|
| 4694 |
`weakly_incrementable` type to denote the “upper bound” of an unbounded
|
| 4695 |
interval.
|
| 4696 |
|
|
|
|
| 4719 |
}
|
| 4720 |
```
|
| 4721 |
|
| 4722 |
## Stream iterators <a id="stream.iterators">[[stream.iterators]]</a>
|
| 4723 |
|
| 4724 |
+
### General <a id="stream.iterators.general">[[stream.iterators.general]]</a>
|
| 4725 |
+
|
| 4726 |
To make it possible for algorithmic templates to work directly with
|
| 4727 |
input/output streams, appropriate iterator-like class templates are
|
| 4728 |
provided.
|
| 4729 |
|
| 4730 |
[*Example 1*:
|
|
|
|
| 4740 |
|
| 4741 |
— *end example*]
|
| 4742 |
|
| 4743 |
### Class template `istream_iterator` <a id="istream.iterator">[[istream.iterator]]</a>
|
| 4744 |
|
| 4745 |
+
#### General <a id="istream.iterator.general">[[istream.iterator.general]]</a>
|
| 4746 |
+
|
| 4747 |
The class template `istream_iterator` is an input iterator
|
| 4748 |
[[input.iterators]] that reads successive elements from the input stream
|
| 4749 |
for which it was constructed.
|
| 4750 |
|
| 4751 |
``` cpp
|
|
|
|
| 4764 |
using istream_type = basic_istream<charT,traits>;
|
| 4765 |
|
| 4766 |
constexpr istream_iterator();
|
| 4767 |
constexpr istream_iterator(default_sentinel_t);
|
| 4768 |
istream_iterator(istream_type& s);
|
| 4769 |
+
constexpr istream_iterator(const istream_iterator& x) noexcept(see below);
|
| 4770 |
~istream_iterator() = default;
|
| 4771 |
istream_iterator& operator=(const istream_iterator&) = default;
|
| 4772 |
|
| 4773 |
const T& operator*() const;
|
| 4774 |
const T* operator->() const;
|
|
|
|
| 4809 |
|
| 4810 |
*Effects:* Initializes `in_stream` with `addressof(s)`,
|
| 4811 |
value-initializes `value`, and then calls `operator++()`.
|
| 4812 |
|
| 4813 |
``` cpp
|
| 4814 |
+
constexpr istream_iterator(const istream_iterator& x) noexcept(see below);
|
| 4815 |
```
|
| 4816 |
|
| 4817 |
+
*Effects:* Initializes `in_stream` with `x.in_stream` and initializes
|
| 4818 |
+
`value` with `x.value`.
|
| 4819 |
|
| 4820 |
+
*Remarks:* An invocation of this constructor may be used in a core
|
| 4821 |
+
constant expression if and only if the initialization of `value` from
|
| 4822 |
+
`x.value` is a constant subexpression [[defns.const.subexpr]]. The
|
| 4823 |
+
exception specification is equivalent to
|
| 4824 |
+
`is_nothrow_copy_constructible_v<T>`.
|
| 4825 |
|
| 4826 |
``` cpp
|
| 4827 |
~istream_iterator() = default;
|
| 4828 |
```
|
| 4829 |
|
|
|
|
| 4891 |
|
| 4892 |
*Returns:* `!i.in_stream`.
|
| 4893 |
|
| 4894 |
### Class template `ostream_iterator` <a id="ostream.iterator">[[ostream.iterator]]</a>
|
| 4895 |
|
| 4896 |
+
#### General <a id="ostream.iterator.general">[[ostream.iterator.general]]</a>
|
| 4897 |
+
|
| 4898 |
`ostream_iterator` writes (using `operator<<`) successive elements onto
|
| 4899 |
the output stream from which it was constructed. If it was constructed
|
| 4900 |
with `charT*` as a constructor argument, this string, called a
|
| 4901 |
*delimiter string*, is written to the stream after every `T` is written.
|
| 4902 |
|
|
|
|
| 4912 |
using reference = void;
|
| 4913 |
using char_type = charT;
|
| 4914 |
using traits_type = traits;
|
| 4915 |
using ostream_type = basic_ostream<charT,traits>;
|
| 4916 |
|
|
|
|
| 4917 |
ostream_iterator(ostream_type& s);
|
| 4918 |
ostream_iterator(ostream_type& s, const charT* delimiter);
|
| 4919 |
ostream_iterator(const ostream_iterator& x);
|
| 4920 |
~ostream_iterator();
|
| 4921 |
ostream_iterator& operator=(const ostream_iterator&) = default;
|
|
|
|
| 4924 |
ostream_iterator& operator*();
|
| 4925 |
ostream_iterator& operator++();
|
| 4926 |
ostream_iterator& operator++(int);
|
| 4927 |
|
| 4928 |
private:
|
| 4929 |
+
basic_ostream<charT,traits>* out_stream; // exposition only
|
| 4930 |
+
const charT* delim; // exposition only
|
| 4931 |
};
|
| 4932 |
}
|
| 4933 |
```
|
| 4934 |
|
| 4935 |
#### Constructors and destructor <a id="ostream.iterator.cons.des">[[ostream.iterator.cons.des]]</a>
|
|
|
|
| 4976 |
|
| 4977 |
*Returns:* `*this`.
|
| 4978 |
|
| 4979 |
### Class template `istreambuf_iterator` <a id="istreambuf.iterator">[[istreambuf.iterator]]</a>
|
| 4980 |
|
| 4981 |
+
#### General <a id="istreambuf.iterator.general">[[istreambuf.iterator.general]]</a>
|
| 4982 |
+
|
| 4983 |
The class template `istreambuf_iterator` defines an input iterator
|
| 4984 |
[[input.iterators]] that reads successive *characters* from the
|
| 4985 |
streambuf for which it was constructed. `operator*` provides access to
|
| 4986 |
the current input character, if any. Each time `operator++` is
|
| 4987 |
evaluated, the iterator advances to the next input character. If the end
|
|
|
|
| 5012 |
using traits_type = traits;
|
| 5013 |
using int_type = typename traits::int_type;
|
| 5014 |
using streambuf_type = basic_streambuf<charT,traits>;
|
| 5015 |
using istream_type = basic_istream<charT,traits>;
|
| 5016 |
|
| 5017 |
+
// [istreambuf.iterator.proxy], class istreambuf_iterator::proxy
|
| 5018 |
class proxy; // exposition only
|
| 5019 |
|
| 5020 |
constexpr istreambuf_iterator() noexcept;
|
| 5021 |
constexpr istreambuf_iterator(default_sentinel_t) noexcept;
|
| 5022 |
istreambuf_iterator(const istreambuf_iterator&) noexcept = default;
|
|
|
|
| 5138 |
|
| 5139 |
*Returns:* `i.equal(s)`.
|
| 5140 |
|
| 5141 |
### Class template `ostreambuf_iterator` <a id="ostreambuf.iterator">[[ostreambuf.iterator]]</a>
|
| 5142 |
|
| 5143 |
+
#### General <a id="ostreambuf.iterator.general">[[ostreambuf.iterator.general]]</a>
|
| 5144 |
+
|
| 5145 |
The class template `ostreambuf_iterator` writes successive *characters*
|
| 5146 |
onto the output stream from which it was constructed.
|
| 5147 |
|
| 5148 |
``` cpp
|
| 5149 |
namespace std {
|
|
|
|
| 5158 |
using char_type = charT;
|
| 5159 |
using traits_type = traits;
|
| 5160 |
using streambuf_type = basic_streambuf<charT,traits>;
|
| 5161 |
using ostream_type = basic_ostream<charT,traits>;
|
| 5162 |
|
|
|
|
| 5163 |
ostreambuf_iterator(ostream_type& s) noexcept;
|
| 5164 |
ostreambuf_iterator(streambuf_type* s) noexcept;
|
| 5165 |
ostreambuf_iterator& operator=(charT c);
|
| 5166 |
|
| 5167 |
ostreambuf_iterator& operator*();
|
| 5168 |
ostreambuf_iterator& operator++();
|
| 5169 |
ostreambuf_iterator& operator++(int);
|
| 5170 |
bool failed() const noexcept;
|
| 5171 |
|
| 5172 |
private:
|
| 5173 |
+
streambuf_type* sbuf_; // exposition only
|
| 5174 |
};
|
| 5175 |
}
|
| 5176 |
```
|
| 5177 |
|
| 5178 |
#### Constructors <a id="ostreambuf.iter.cons">[[ostreambuf.iter.cons]]</a>
|
|
|
|
| 5229 |
In addition to being available via inclusion of the `<iterator>` header,
|
| 5230 |
the function templates in [[iterator.range]] are available when any of
|
| 5231 |
the following headers are included: `<array>`, `<deque>`,
|
| 5232 |
`<forward_list>`, `<list>`, `<map>`, `<regex>`, `<set>`, `<span>`,
|
| 5233 |
`<string>`, `<string_view>`, `<unordered_map>`, `<unordered_set>`, and
|
| 5234 |
+
`<vector>`.
|
|
|
|
| 5235 |
|
| 5236 |
``` cpp
|
| 5237 |
template<class C> constexpr auto begin(C& c) -> decltype(c.begin());
|
| 5238 |
template<class C> constexpr auto begin(const C& c) -> decltype(c.begin());
|
| 5239 |
```
|
|
|
|
| 5406 |
[basic.lookup.argdep]: basic.md#basic.lookup.argdep
|
| 5407 |
[basic.lookup.unqual]: basic.md#basic.lookup.unqual
|
| 5408 |
[basic.lval]: expr.md#basic.lval
|
| 5409 |
[bidirectional.iterators]: #bidirectional.iterators
|
| 5410 |
[bidirectionaliterator]: #bidirectionaliterator
|
| 5411 |
+
[cmp.concept]: support.md#cmp.concept
|
| 5412 |
[common.iter.access]: #common.iter.access
|
| 5413 |
[common.iter.cmp]: #common.iter.cmp
|
| 5414 |
[common.iter.const]: #common.iter.const
|
| 5415 |
[common.iter.cust]: #common.iter.cust
|
| 5416 |
[common.iter.nav]: #common.iter.nav
|
| 5417 |
[common.iter.types]: #common.iter.types
|
| 5418 |
[common.iterator]: #common.iterator
|
| 5419 |
[concept.swappable]: concepts.md#concept.swappable
|
|
|
|
| 5420 |
[concepts.object]: concepts.md#concepts.object
|
| 5421 |
+
[const.iterators]: #const.iterators
|
| 5422 |
+
[const.iterators.alias]: #const.iterators.alias
|
| 5423 |
+
[const.iterators.general]: #const.iterators.general
|
| 5424 |
+
[const.iterators.iterator]: #const.iterators.iterator
|
| 5425 |
+
[const.iterators.ops]: #const.iterators.ops
|
| 5426 |
+
[const.iterators.types]: #const.iterators.types
|
| 5427 |
[containers]: containers.md#containers
|
| 5428 |
[counted.iter.access]: #counted.iter.access
|
| 5429 |
[counted.iter.cmp]: #counted.iter.cmp
|
| 5430 |
[counted.iter.const]: #counted.iter.const
|
| 5431 |
[counted.iter.cust]: #counted.iter.cust
|
|
|
|
| 5433 |
[counted.iter.nav]: #counted.iter.nav
|
| 5434 |
[counted.iterator]: #counted.iterator
|
| 5435 |
[cpp17.copyassignable]: #cpp17.copyassignable
|
| 5436 |
[cpp17.equalitycomparable]: #cpp17.equalitycomparable
|
| 5437 |
[customization.point.object]: library.md#customization.point.object
|
| 5438 |
+
[default.sentinel]: #default.sentinel
|
| 5439 |
+
[defns.const.subexpr]: intro.md#defns.const.subexpr
|
| 5440 |
+
[defns.projection]: intro.md#defns.projection
|
| 5441 |
[expr.call]: expr.md#expr.call
|
| 5442 |
[expr.const]: expr.md#expr.const
|
| 5443 |
[forward.iterators]: #forward.iterators
|
| 5444 |
[forwarditerator]: #forwarditerator
|
| 5445 |
[front.insert.iter.ops]: #front.insert.iter.ops
|
|
|
|
| 5448 |
[func.def]: utilities.md#func.def
|
| 5449 |
[incrementable.traits]: #incrementable.traits
|
| 5450 |
[indirectcallable]: #indirectcallable
|
| 5451 |
[indirectcallable.general]: #indirectcallable.general
|
| 5452 |
[indirectcallable.indirectinvocable]: #indirectcallable.indirectinvocable
|
| 5453 |
+
[indirectcallable.traits]: #indirectcallable.traits
|
| 5454 |
[input.iterators]: #input.iterators
|
| 5455 |
[inputiterator]: #inputiterator
|
| 5456 |
[insert.iter.ops]: #insert.iter.ops
|
| 5457 |
[insert.iterator]: #insert.iterator
|
| 5458 |
[insert.iterators]: #insert.iterators
|
| 5459 |
+
[insert.iterators.general]: #insert.iterators.general
|
| 5460 |
[inserter]: #inserter
|
| 5461 |
[iostream.format]: input.md#iostream.format
|
| 5462 |
[istream.iterator]: #istream.iterator
|
| 5463 |
[istream.iterator.cons]: #istream.iterator.cons
|
| 5464 |
+
[istream.iterator.general]: #istream.iterator.general
|
| 5465 |
[istream.iterator.ops]: #istream.iterator.ops
|
| 5466 |
[istreambuf.iterator]: #istreambuf.iterator
|
| 5467 |
[istreambuf.iterator.cons]: #istreambuf.iterator.cons
|
| 5468 |
+
[istreambuf.iterator.general]: #istreambuf.iterator.general
|
| 5469 |
[istreambuf.iterator.ops]: #istreambuf.iterator.ops
|
| 5470 |
[istreambuf.iterator.proxy]: #istreambuf.iterator.proxy
|
| 5471 |
[iterator]: #iterator
|
| 5472 |
[iterator.assoc.types]: #iterator.assoc.types
|
| 5473 |
[iterator.concept.bidir]: #iterator.concept.bidir
|
|
|
|
| 5484 |
[iterator.concept.winc]: #iterator.concept.winc
|
| 5485 |
[iterator.concept.writable]: #iterator.concept.writable
|
| 5486 |
[iterator.concepts]: #iterator.concepts
|
| 5487 |
[iterator.concepts.general]: #iterator.concepts.general
|
| 5488 |
[iterator.cpp17]: #iterator.cpp17
|
| 5489 |
+
[iterator.cpp17.general]: #iterator.cpp17.general
|
| 5490 |
[iterator.cust]: #iterator.cust
|
| 5491 |
[iterator.cust.move]: #iterator.cust.move
|
| 5492 |
[iterator.cust.swap]: #iterator.cust.swap
|
| 5493 |
[iterator.iterators]: #iterator.iterators
|
| 5494 |
[iterator.operations]: #iterator.operations
|
| 5495 |
[iterator.primitives]: #iterator.primitives
|
| 5496 |
+
[iterator.primitives.general]: #iterator.primitives.general
|
| 5497 |
[iterator.range]: #iterator.range
|
| 5498 |
[iterator.requirements]: #iterator.requirements
|
| 5499 |
[iterator.requirements.general]: #iterator.requirements.general
|
| 5500 |
[iterator.synopsis]: #iterator.synopsis
|
| 5501 |
[iterator.traits]: #iterator.traits
|
|
|
|
| 5513 |
[move.iter.op.comp]: #move.iter.op.comp
|
| 5514 |
[move.iter.op.conv]: #move.iter.op.conv
|
| 5515 |
[move.iter.requirements]: #move.iter.requirements
|
| 5516 |
[move.iterator]: #move.iterator
|
| 5517 |
[move.iterators]: #move.iterators
|
| 5518 |
+
[move.iterators.general]: #move.iterators.general
|
| 5519 |
[move.sent.ops]: #move.sent.ops
|
| 5520 |
[move.sentinel]: #move.sentinel
|
| 5521 |
[namespace.std]: library.md#namespace.std
|
| 5522 |
+
[numeric.limits]: support.md#numeric.limits
|
| 5523 |
[ostream.iterator]: #ostream.iterator
|
| 5524 |
[ostream.iterator.cons.des]: #ostream.iterator.cons.des
|
| 5525 |
+
[ostream.iterator.general]: #ostream.iterator.general
|
| 5526 |
[ostream.iterator.ops]: #ostream.iterator.ops
|
| 5527 |
[ostreambuf.iter.cons]: #ostreambuf.iter.cons
|
| 5528 |
[ostreambuf.iter.ops]: #ostreambuf.iter.ops
|
| 5529 |
[ostreambuf.iterator]: #ostreambuf.iterator
|
| 5530 |
+
[ostreambuf.iterator.general]: #ostreambuf.iterator.general
|
| 5531 |
[output.iterators]: #output.iterators
|
| 5532 |
[outputiterator]: #outputiterator
|
| 5533 |
[predef.iterators]: #predef.iterators
|
| 5534 |
[projected]: #projected
|
| 5535 |
[random.access.iterators]: #random.access.iterators
|
|
|
|
| 5538 |
[range.iter.op.advance]: #range.iter.op.advance
|
| 5539 |
[range.iter.op.distance]: #range.iter.op.distance
|
| 5540 |
[range.iter.op.next]: #range.iter.op.next
|
| 5541 |
[range.iter.op.prev]: #range.iter.op.prev
|
| 5542 |
[range.iter.ops]: #range.iter.ops
|
| 5543 |
+
[range.iter.ops.general]: #range.iter.ops.general
|
| 5544 |
[ranges]: ranges.md#ranges
|
| 5545 |
[readable.traits]: #readable.traits
|
| 5546 |
[reverse.iter.cmp]: #reverse.iter.cmp
|
| 5547 |
[reverse.iter.cons]: #reverse.iter.cons
|
| 5548 |
[reverse.iter.conv]: #reverse.iter.conv
|
|
|
|
| 5550 |
[reverse.iter.nav]: #reverse.iter.nav
|
| 5551 |
[reverse.iter.nonmember]: #reverse.iter.nonmember
|
| 5552 |
[reverse.iter.requirements]: #reverse.iter.requirements
|
| 5553 |
[reverse.iterator]: #reverse.iterator
|
| 5554 |
[reverse.iterators]: #reverse.iterators
|
| 5555 |
+
[reverse.iterators.general]: #reverse.iterators.general
|
| 5556 |
[std.iterator.tags]: #std.iterator.tags
|
| 5557 |
[stream.buffers]: input.md#stream.buffers
|
| 5558 |
[stream.iterators]: #stream.iterators
|
| 5559 |
+
[stream.iterators.general]: #stream.iterators.general
|
| 5560 |
[swappable.requirements]: library.md#swappable.requirements
|
| 5561 |
[temp.deduct]: temp.md#temp.deduct
|
| 5562 |
[temp.func.order]: temp.md#temp.func.order
|
| 5563 |
[temp.inst]: temp.md#temp.inst
|
| 5564 |
[unreachable.sentinel]: #unreachable.sentinel
|
|
|
|
| 5565 |
[utility.arg.requirements]: library.md#utility.arg.requirements
|
| 5566 |
|
| 5567 |
+
[^1]: The sentinel denoting the end of a range can have the same type as
|
| 5568 |
the iterator denoting the beginning of the range, or a different
|
| 5569 |
type.
|
| 5570 |
|
| 5571 |
[^2]: This definition applies to pointers, since pointers are iterators.
|
| 5572 |
The effect of dereferencing an iterator that has been invalidated is
|