1// -*- C++ -*- 2//===-------------------------- iterator ----------------------------------===// 3// 4// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 5// See https://llvm.org/LICENSE.txt for license information. 6// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 7// 8//===----------------------------------------------------------------------===// 9 10#ifndef _LIBCPP_ITERATOR 11#define _LIBCPP_ITERATOR 12 13/* 14 iterator synopsis 15 16#include <concepts> 17 18namespace std 19{ 20template<class> struct incrementable_traits; // since C++20 21template<class T> 22 using iter_difference_t = see below; // since C++20 23 24template<class> struct indirectly_readable_traits; // since C++20 25template<class T> 26 using iter_value_t = see below; // since C++20 27 28template<class Iterator> 29struct iterator_traits; 30 31template<class T> 32 requires is_object_v<T> // since C++20 33struct iterator_traits<T*>; 34 35template<dereferenceable T> 36 using iter_reference_t = decltype(*declval<T&>()); 37 38namespace ranges::inline unspecified { 39 inline constexpr unspecified iter_move = unspecified; // since C++20, nodiscard as an extension 40}} 41 42template<dereferenceable T> 43 requires ... 44using iter_rvalue_reference_t = decltype(ranges::iter_move(declval<T&>())); // since C++20 45 46// [iterator.concepts], iterator concepts 47// [iterator.concept.readable], concept indirectly_readable 48template<class In> 49 concept indirectly_readable = see below; // since C++20 50 51template<indirectly_readable T> 52 using iter_common_reference_t = 53 common_reference_t<iter_reference_t<T>, iter_value_t<T>&>; // since C++20 54 55// [iterator.concept.writable], concept indirectly_writable 56template<class Out, class T> 57 concept indirectly_writable = see below; // since C++20 58 59// [iterator.concept.winc], concept weakly_incrementable 60template<class I> 61 concept weakly_incrementable = see below; // since C++20 62 63// [iterator.concept.inc], concept incrementable 64template<class I> 65 concept incrementable = see below; // since C++20 66 67// [iterator.concept.iterator], concept input_or_output_iterator 68 template<class I> 69 concept input_or_output_iterator = see below; // since C++20 70 71// [iterator.concept.sentinel], concept sentinel_for 72template<class S, class I> 73 concept sentinel_for = see below; // since C++20 74 75// [iterator.concept.sizedsentinel], concept sized_sentinel_for 76template<class S, class I> 77 inline constexpr bool disable_sized_sentinel_for = false; 78 79template<class S, class I> 80 concept sized_sentinel_for = see below; 81 82// [iterator.concept.input], concept input_iterator 83template<class I> 84 concept input_iterator = see below; // since C++20 85 86// [iterator.concept.forward], concept forward_iterator 87template<class I> 88 concept forward_iterator = see below; // since C++20 89 90// [iterator.concept.bidir], concept bidirectional_iterator 91template<class I> 92 concept bidirectional_iterator = see below; // since C++20 93 94// [iterator.concept.random.access], concept random_access_iterator 95template<class I> 96 concept random_access_iterator = see below; // since C++20 97 98// [indirectcallable] 99// [indirectcallable.indirectinvocable] 100template<class F, class I> 101 concept indirectly_unary_invocable = see below; // since C++20 102 103template<class F, class I> 104 concept indirectly_regular_unary_invocable = see below; // since C++20 105 106template<class F, class I> 107 concept indirect_unary_predicate = see below; // since C++20 108 109template<class F, class I1, class I2> 110 concept indirect_binary_predicate = see below; // since C++20 111 112template<class F, class I1, class I2 = I1> 113 concept indirect_equivalence_relation = see below; // since C++20 114 115template<class F, class I1, class I2 = I1> 116 concept indirect_strict_weak_order = see below; // since C++20 117 118template<class F, class... Is> 119 using indirect_result_t = see below; // since C++20 120 121// [projected], projected 122template<indirectly_readable I, indirectly_regular_unary_invocable<I> Proj> 123 struct projected; // since C++20 124 125template<weakly_incrementable I, indirectly_regular_unary_invocable<I> Proj> 126 struct incrementable_traits<projected<I, Proj>>; // since C++20 127 128// [alg.req.ind.move], concept indirectly_movable 129template<class In, class Out> 130 concept indirectly_movable = see below; // since C++20 131 132template<class In, class Out> 133 concept indirectly_movable_storable = see below; // since C++20 134 135// [alg.req.ind.swap], concept indirectly_swappable 136template<class I1, class I2 = I1> 137 concept indirectly_swappable = see below; // since C++20 138 139template<input_or_output_iterator I, sentinel_for<I> S> 140 requires (!same_as<I, S> && copyable<I>) 141class common_iterator; // since C++20 142 143template<class Category, class T, class Distance = ptrdiff_t, 144 class Pointer = T*, class Reference = T&> 145struct iterator // deprecated in C++17 146{ 147 typedef T value_type; 148 typedef Distance difference_type; 149 typedef Pointer pointer; 150 typedef Reference reference; 151 typedef Category iterator_category; 152}; 153 154struct input_iterator_tag {}; 155struct output_iterator_tag {}; 156struct forward_iterator_tag : public input_iterator_tag {}; 157struct bidirectional_iterator_tag : public forward_iterator_tag {}; 158struct random_access_iterator_tag : public bidirectional_iterator_tag {}; 159 160// 27.4.3, iterator operations 161template <class InputIterator, class Distance> // constexpr in C++17 162 constexpr void advance(InputIterator& i, Distance n); 163 164template <class InputIterator> // constexpr in C++17 165 constexpr typename iterator_traits<InputIterator>::difference_type 166 distance(InputIterator first, InputIterator last); 167 168template <class InputIterator> // constexpr in C++17 169 constexpr InputIterator next(InputIterator x, 170typename iterator_traits<InputIterator>::difference_type n = 1); 171 172template <class BidirectionalIterator> // constexpr in C++17 173 constexpr BidirectionalIterator prev(BidirectionalIterator x, 174 typename iterator_traits<BidirectionalIterator>::difference_type n = 1); 175 176// [range.iter.ops], range iterator operations 177namespace ranges { 178 // [range.iter.op.advance], ranges::advance 179 template<input_or_output_iterator I> 180 constexpr void advance(I& i, iter_difference_t<I> n); // since C++20 181 template<input_or_output_iterator I, sentinel_for<I> S> 182 constexpr void advance(I& i, S bound); // since C++20 183 template<input_or_output_iterator I, sentinel_for<I> S> 184 constexpr iter_difference_t<I> advance(I& i, iter_difference_t<I> n, S bound); // since C++20 185} 186 187template <class Iterator> 188class reverse_iterator 189 : public iterator<typename iterator_traits<Iterator>::iterator_category, // until C++17 190 typename iterator_traits<Iterator>::value_type, 191 typename iterator_traits<Iterator>::difference_type, 192 typename iterator_traits<Iterator>::pointer, 193 typename iterator_traits<Iterator>::reference> 194{ 195protected: 196 Iterator current; 197public: 198 typedef Iterator iterator_type; 199 typedef typename iterator_traits<Iterator>::difference_type difference_type; 200 typedef typename iterator_traits<Iterator>::reference reference; 201 typedef typename iterator_traits<Iterator>::pointer pointer; 202 203 constexpr reverse_iterator(); 204 constexpr explicit reverse_iterator(Iterator x); 205 template <class U> constexpr reverse_iterator(const reverse_iterator<U>& u); 206 template <class U> constexpr reverse_iterator& operator=(const reverse_iterator<U>& u); 207 constexpr Iterator base() const; 208 constexpr reference operator*() const; 209 constexpr pointer operator->() const; 210 constexpr reverse_iterator& operator++(); 211 constexpr reverse_iterator operator++(int); 212 constexpr reverse_iterator& operator--(); 213 constexpr reverse_iterator operator--(int); 214 constexpr reverse_iterator operator+ (difference_type n) const; 215 constexpr reverse_iterator& operator+=(difference_type n); 216 constexpr reverse_iterator operator- (difference_type n) const; 217 constexpr reverse_iterator& operator-=(difference_type n); 218 constexpr reference operator[](difference_type n) const; 219}; 220 221template <class Iterator1, class Iterator2> 222constexpr bool // constexpr in C++17 223operator==(const reverse_iterator<Iterator1>& x, const reverse_iterator<Iterator2>& y); 224 225template <class Iterator1, class Iterator2> 226constexpr bool // constexpr in C++17 227operator<(const reverse_iterator<Iterator1>& x, const reverse_iterator<Iterator2>& y); 228 229template <class Iterator1, class Iterator2> 230constexpr bool // constexpr in C++17 231operator!=(const reverse_iterator<Iterator1>& x, const reverse_iterator<Iterator2>& y); 232 233template <class Iterator1, class Iterator2> 234constexpr bool // constexpr in C++17 235operator>(const reverse_iterator<Iterator1>& x, const reverse_iterator<Iterator2>& y); 236 237template <class Iterator1, class Iterator2> 238constexpr bool // constexpr in C++17 239operator>=(const reverse_iterator<Iterator1>& x, const reverse_iterator<Iterator2>& y); 240 241template <class Iterator1, class Iterator2> 242constexpr bool // constexpr in C++17 243operator<=(const reverse_iterator<Iterator1>& x, const reverse_iterator<Iterator2>& y); 244 245template <class Iterator1, class Iterator2> 246constexpr auto 247operator-(const reverse_iterator<Iterator1>& x, const reverse_iterator<Iterator2>& y) 248-> decltype(__y.base() - __x.base()); // constexpr in C++17 249 250template <class Iterator> 251constexpr reverse_iterator<Iterator> 252operator+(typename reverse_iterator<Iterator>::difference_type n, 253 const reverse_iterator<Iterator>& x); // constexpr in C++17 254 255template <class Iterator> 256constexpr reverse_iterator<Iterator> make_reverse_iterator(Iterator i); // C++14, constexpr in C++17 257 258template <class Container> 259class back_insert_iterator 260 : public iterator<output_iterator_tag, void, void, void, void> // until C++17 261{ 262protected: 263 Container* container; 264public: 265 typedef Container container_type; 266 typedef void value_type; 267 typedef void difference_type; // until C++20 268 typedef ptrdiff_t difference_type; // since C++20 269 typedef void reference; 270 typedef void pointer; 271 272 explicit back_insert_iterator(Container& x); // constexpr in C++20 273 back_insert_iterator& operator=(const typename Container::value_type& value); // constexpr in C++20 274 back_insert_iterator& operator*(); // constexpr in C++20 275 back_insert_iterator& operator++(); // constexpr in C++20 276 back_insert_iterator operator++(int); // constexpr in C++20 277}; 278 279template <class Container> back_insert_iterator<Container> back_inserter(Container& x); // constexpr in C++20 280 281template <class Container> 282class front_insert_iterator 283 : public iterator<output_iterator_tag, void, void, void, void> // until C++17 284{ 285protected: 286 Container* container; 287public: 288 typedef Container container_type; 289 typedef void value_type; 290 typedef void difference_type; // until C++20 291 typedef ptrdiff_t difference_type; // since C++20 292 typedef void reference; 293 typedef void pointer; 294 295 explicit front_insert_iterator(Container& x); // constexpr in C++20 296 front_insert_iterator& operator=(const typename Container::value_type& value); // constexpr in C++20 297 front_insert_iterator& operator*(); // constexpr in C++20 298 front_insert_iterator& operator++(); // constexpr in C++20 299 front_insert_iterator operator++(int); // constexpr in C++20 300}; 301 302template <class Container> front_insert_iterator<Container> front_inserter(Container& x); // constexpr in C++20 303 304template <class Container> 305class insert_iterator 306 : public iterator<output_iterator_tag, void, void, void, void> // until C++17 307{ 308protected: 309 Container* container; 310 typename Container::iterator iter; 311public: 312 typedef Container container_type; 313 typedef void value_type; 314 typedef void difference_type; // until C++20 315 typedef ptrdiff_t difference_type; // since C++20 316 typedef void reference; 317 typedef void pointer; 318 319 insert_iterator(Container& x, typename Container::iterator i); // constexpr in C++20 320 insert_iterator& operator=(const typename Container::value_type& value); // constexpr in C++20 321 insert_iterator& operator*(); // constexpr in C++20 322 insert_iterator& operator++(); // constexpr in C++20 323 insert_iterator& operator++(int); // constexpr in C++20 324}; 325 326template <class Container, class Iterator> 327insert_iterator<Container> inserter(Container& x, Iterator i); // constexpr in C++20 328 329template <class Iterator> 330class move_iterator { 331public: 332 typedef Iterator iterator_type; 333 typedef typename iterator_traits<Iterator>::difference_type difference_type; 334 typedef Iterator pointer; 335 typedef typename iterator_traits<Iterator>::value_type value_type; 336 typedef typename iterator_traits<Iterator>::iterator_category iterator_category; 337 typedef value_type&& reference; 338 339 constexpr move_iterator(); // all the constexprs are in C++17 340 constexpr explicit move_iterator(Iterator i); 341 template <class U> 342 constexpr move_iterator(const move_iterator<U>& u); 343 template <class U> 344 constexpr move_iterator& operator=(const move_iterator<U>& u); 345 constexpr iterator_type base() const; 346 constexpr reference operator*() const; 347 constexpr pointer operator->() const; 348 constexpr move_iterator& operator++(); 349 constexpr move_iterator operator++(int); 350 constexpr move_iterator& operator--(); 351 constexpr move_iterator operator--(int); 352 constexpr move_iterator operator+(difference_type n) const; 353 constexpr move_iterator& operator+=(difference_type n); 354 constexpr move_iterator operator-(difference_type n) const; 355 constexpr move_iterator& operator-=(difference_type n); 356 constexpr unspecified operator[](difference_type n) const; 357private: 358 Iterator current; // exposition only 359}; 360 361template <class Iterator1, class Iterator2> 362constexpr bool // constexpr in C++17 363operator==(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y); 364 365template <class Iterator1, class Iterator2> 366constexpr bool // constexpr in C++17 367operator!=(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y); 368 369template <class Iterator1, class Iterator2> 370constexpr bool // constexpr in C++17 371operator<(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y); 372 373template <class Iterator1, class Iterator2> 374constexpr bool // constexpr in C++17 375operator<=(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y); 376 377template <class Iterator1, class Iterator2> 378constexpr bool // constexpr in C++17 379operator>(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y); 380 381template <class Iterator1, class Iterator2> 382constexpr bool // constexpr in C++17 383operator>=(const move_iterator<Iterator1>& x, const move_iterator<Iterator2>& y); 384 385template <class Iterator1, class Iterator2> 386constexpr auto // constexpr in C++17 387operator-(const move_iterator<Iterator1>& x, 388 const move_iterator<Iterator2>& y) -> decltype(x.base() - y.base()); 389 390template <class Iterator> 391constexpr move_iterator<Iterator> operator+( // constexpr in C++17 392 typename move_iterator<Iterator>::difference_type n, 393 const move_iterator<Iterator>& x); 394 395template <class Iterator> // constexpr in C++17 396constexpr move_iterator<Iterator> make_move_iterator(const Iterator& i); 397 398// [default.sentinel], default sentinel 399struct default_sentinel_t; 400inline constexpr default_sentinel_t default_sentinel{}; 401 402template <class T, class charT = char, class traits = char_traits<charT>, class Distance = ptrdiff_t> 403class istream_iterator 404 : public iterator<input_iterator_tag, T, Distance, const T*, const T&> // until C++17 405{ 406public: 407 typedef input_iterator_tag iterator_category; 408 typedef T value_type; 409 typedef Distance difference_type; 410 typedef const T* pointer; 411 typedef const T& reference; 412 413 typedef charT char_type; 414 typedef traits traits_type; 415 typedef basic_istream<charT, traits> istream_type; 416 417 constexpr istream_iterator(); 418 istream_iterator(istream_type& s); 419 istream_iterator(const istream_iterator& x); 420 ~istream_iterator(); 421 422 const T& operator*() const; 423 const T* operator->() const; 424 istream_iterator& operator++(); 425 istream_iterator operator++(int); 426}; 427 428template <class T, class charT, class traits, class Distance> 429bool operator==(const istream_iterator<T,charT,traits,Distance>& x, 430 const istream_iterator<T,charT,traits,Distance>& y); 431template <class T, class charT, class traits, class Distance> 432bool operator!=(const istream_iterator<T,charT,traits,Distance>& x, 433 const istream_iterator<T,charT,traits,Distance>& y); 434 435template <class T, class charT = char, class traits = char_traits<charT> > 436class ostream_iterator 437 : public iterator<output_iterator_tag, void, void, void, void> // until C++17 438{ 439public: 440 typedef output_iterator_tag iterator_category; 441 typedef void value_type; 442 typedef void difference_type; // until C++20 443 typedef ptrdiff_t difference_type; // since C++20 444 typedef void pointer; 445 typedef void reference; 446 447 typedef charT char_type; 448 typedef traits traits_type; 449 typedef basic_ostream<charT,traits> ostream_type; 450 451 ostream_iterator(ostream_type& s); 452 ostream_iterator(ostream_type& s, const charT* delimiter); 453 ostream_iterator(const ostream_iterator& x); 454 ~ostream_iterator(); 455 ostream_iterator& operator=(const T& value); 456 457 ostream_iterator& operator*(); 458 ostream_iterator& operator++(); 459 ostream_iterator& operator++(int); 460}; 461 462template<class charT, class traits = char_traits<charT> > 463class istreambuf_iterator 464 : public iterator<input_iterator_tag, charT, traits::off_type, unspecified, charT> // until C++17 465{ 466public: 467 typedef input_iterator_tag iterator_category; 468 typedef charT value_type; 469 typedef traits::off_type difference_type; 470 typedef unspecified pointer; 471 typedef charT reference; 472 473 typedef charT char_type; 474 typedef traits traits_type; 475 typedef traits::int_type int_type; 476 typedef basic_streambuf<charT, traits> streambuf_type; 477 typedef basic_istream<charT, traits> istream_type; 478 479 istreambuf_iterator() noexcept; 480 istreambuf_iterator(istream_type& s) noexcept; 481 istreambuf_iterator(streambuf_type* s) noexcept; 482 istreambuf_iterator(a-private-type) noexcept; 483 484 charT operator*() const; 485 pointer operator->() const; 486 istreambuf_iterator& operator++(); 487 a-private-type operator++(int); 488 489 bool equal(const istreambuf_iterator& b) const; 490}; 491 492template <class charT, class traits> 493bool operator==(const istreambuf_iterator<charT,traits>& a, 494 const istreambuf_iterator<charT,traits>& b); 495template <class charT, class traits> 496bool operator!=(const istreambuf_iterator<charT,traits>& a, 497 const istreambuf_iterator<charT,traits>& b); 498 499template <class charT, class traits = char_traits<charT> > 500class ostreambuf_iterator 501 : public iterator<output_iterator_tag, void, void, void, void> // until C++17 502{ 503public: 504 typedef output_iterator_tag iterator_category; 505 typedef void value_type; 506 typedef void difference_type; // until C++20 507 typedef ptrdiff_t difference_type; // since C++20 508 typedef void pointer; 509 typedef void reference; 510 511 typedef charT char_type; 512 typedef traits traits_type; 513 typedef basic_streambuf<charT, traits> streambuf_type; 514 typedef basic_ostream<charT, traits> ostream_type; 515 516 ostreambuf_iterator(ostream_type& s) noexcept; 517 ostreambuf_iterator(streambuf_type* s) noexcept; 518 ostreambuf_iterator& operator=(charT c); 519 ostreambuf_iterator& operator*(); 520 ostreambuf_iterator& operator++(); 521 ostreambuf_iterator& operator++(int); 522 bool failed() const noexcept; 523}; 524 525template <class C> constexpr auto begin(C& c) -> decltype(c.begin()); 526template <class C> constexpr auto begin(const C& c) -> decltype(c.begin()); 527template <class C> constexpr auto end(C& c) -> decltype(c.end()); 528template <class C> constexpr auto end(const C& c) -> decltype(c.end()); 529template <class T, size_t N> constexpr T* begin(T (&array)[N]); 530template <class T, size_t N> constexpr T* end(T (&array)[N]); 531 532template <class C> auto constexpr cbegin(const C& c) -> decltype(std::begin(c)); // C++14 533template <class C> auto constexpr cend(const C& c) -> decltype(std::end(c)); // C++14 534template <class C> auto constexpr rbegin(C& c) -> decltype(c.rbegin()); // C++14 535template <class C> auto constexpr rbegin(const C& c) -> decltype(c.rbegin()); // C++14 536template <class C> auto constexpr rend(C& c) -> decltype(c.rend()); // C++14 537template <class C> constexpr auto rend(const C& c) -> decltype(c.rend()); // C++14 538template <class E> reverse_iterator<const E*> constexpr rbegin(initializer_list<E> il); // C++14 539template <class E> reverse_iterator<const E*> constexpr rend(initializer_list<E> il); // C++14 540template <class T, size_t N> reverse_iterator<T*> constexpr rbegin(T (&array)[N]); // C++14 541template <class T, size_t N> reverse_iterator<T*> constexpr rend(T (&array)[N]); // C++14 542template <class C> constexpr auto crbegin(const C& c) -> decltype(std::rbegin(c)); // C++14 543template <class C> constexpr auto crend(const C& c) -> decltype(std::rend(c)); // C++14 544 545// 24.8, container access: 546template <class C> constexpr auto size(const C& c) -> decltype(c.size()); // C++17 547template <class T, size_t N> constexpr size_t size(const T (&array)[N]) noexcept; // C++17 548 549template <class C> constexpr auto ssize(const C& c) 550 -> common_type_t<ptrdiff_t, make_signed_t<decltype(c.size())>>; // C++20 551template <class T, ptrdiff_t> constexpr ptrdiff_t ssize(const T (&array)[N]) noexcept; // C++20 552 553template <class C> constexpr auto empty(const C& c) -> decltype(c.empty()); // C++17 554template <class T, size_t N> constexpr bool empty(const T (&array)[N]) noexcept; // C++17 555template <class E> constexpr bool empty(initializer_list<E> il) noexcept; // C++17 556template <class C> constexpr auto data(C& c) -> decltype(c.data()); // C++17 557template <class C> constexpr auto data(const C& c) -> decltype(c.data()); // C++17 558template <class T, size_t N> constexpr T* data(T (&array)[N]) noexcept; // C++17 559template <class E> constexpr const E* data(initializer_list<E> il) noexcept; // C++17 560 561} // std 562 563*/ 564 565#include <__config> 566#include <__debug> 567#include <__functional_base> 568#include <__iterator/access.h> 569#include <__iterator/advance.h> 570#include <__iterator/back_insert_iterator.h> 571#include <__iterator/common_iterator.h> 572#include <__iterator/concepts.h> 573#include <__iterator/data.h> 574#include <__iterator/default_sentinel.h> 575#include <__iterator/distance.h> 576#include <__iterator/empty.h> 577#include <__iterator/erase_if_container.h> 578#include <__iterator/front_insert_iterator.h> 579#include <__iterator/incrementable_traits.h> 580#include <__iterator/insert_iterator.h> 581#include <__iterator/istreambuf_iterator.h> 582#include <__iterator/istream_iterator.h> 583#include <__iterator/iterator.h> 584#include <__iterator/iterator_traits.h> 585#include <__iterator/iter_move.h> 586#include <__iterator/iter_swap.h> 587#include <__iterator/move_iterator.h> 588#include <__iterator/next.h> 589#include <__iterator/ostreambuf_iterator.h> 590#include <__iterator/ostream_iterator.h> 591#include <__iterator/prev.h> 592#include <__iterator/projected.h> 593#include <__iterator/readable_traits.h> 594#include <__iterator/reverse_access.h> 595#include <__iterator/reverse_iterator.h> 596#include <__iterator/size.h> 597#include <__iterator/wrap_iter.h> 598#include <__memory/addressof.h> 599#include <__memory/pointer_traits.h> 600#include <__utility/forward.h> 601#include <compare> 602#include <concepts> // Mandated by the Standard. 603#include <cstddef> 604#include <initializer_list> 605#include <type_traits> 606#include <version> 607 608#if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER) 609#pragma GCC system_header 610#endif 611 612#endif // _LIBCPP_ITERATOR 613