Where Online Learning is simpler!
The C and C++ Include Header Files
cat -n /usr/include/c++/15/bits/stl_iterator_base_funcs.h
1 // Functions used by iterators -*- C++ -*- 2 3 // Copyright (C) 2001-2025 Free Software Foundation, Inc. 4 // 5 // This file is part of the GNU ISO C++ Library. This library is free 6 // software; you can redistribute it and/or modify it under the 7 // terms of the GNU General Public License as published by the 8 // Free Software Foundation; either version 3, or (at your option) 9 // any later version. 10 11 // This library is distributed in the hope that it will be useful, 12 // but WITHOUT ANY WARRANTY; without even the implied warranty of 13 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 14 // GNU General Public License for more details. 15 16 // Under Section 7 of GPL version 3, you are granted additional 17 // permissions described in the GCC Runtime Library Exception, version 18 // 3.1, as published by the Free Software Foundation. 19 20 // You should have received a copy of the GNU General Public License and 21 // a copy of the GCC Runtime Library Exception along with this program; 22 // see the files COPYING3 and COPYING.RUNTIME respectively. If not, see 23 // <http://www.gnu.org/licenses/>. 24 25 /* 26 * 27 * Copyright (c) 1994 28 * Hewlett-Packard Company 29 * 30 * Permission to use, copy, modify, distribute and sell this software 31 * and its documentation for any purpose is hereby granted without fee, 32 * provided that the above copyright notice appear in all copies and 33 * that both that copyright notice and this permission notice appear 34 * in supporting documentation. Hewlett-Packard Company makes no 35 * representations about the suitability of this software for any 36 * purpose. It is provided "as is" without express or implied warranty. 37 * 38 * 39 * Copyright (c) 1996-1998 40 * Silicon Graphics Computer Systems, Inc. 41 * 42 * Permission to use, copy, modify, distribute and sell this software 43 * and its documentation for any purpose is hereby granted without fee, 44 * provided that the above copyright notice appear in all copies and 45 * that both that copyright notice and this permission notice appear 46 * in supporting documentation. Silicon Graphics makes no 47 * representations about the suitability of this software for any 48 * purpose. It is provided "as is" without express or implied warranty. 49 */ 50 51 /** @file bits/stl_iterator_base_funcs.h 52 * This is an internal header file, included by other library headers. 53 * Do not attempt to use it directly. @headername{iterator} 54 * 55 * This file contains all of the general iterator-related utility 56 * functions, such as distance() and advance(). 57 */ 58 59 #ifndef _STL_ITERATOR_BASE_FUNCS_H 60 #define _STL_ITERATOR_BASE_FUNCS_H 1 61 62 #ifdef _GLIBCXX_SYSHDR 63 #pragma GCC system_header 64 #endif 65 66 #include <bits/concept_check.h> 67 #include <debug/assertions.h> 68 #include <bits/stl_iterator_base_types.h> 69 70 namespace std _GLIBCXX_VISIBILITY(default) 71 { 72 _GLIBCXX_BEGIN_NAMESPACE_VERSION 73 74 _GLIBCXX_BEGIN_NAMESPACE_CONTAINER 75 // Forward declaration for the overloads of __distance. 76 template <typename> struct _List_iterator; 77 template <typename> struct _List_const_iterator; 78 _GLIBCXX_END_NAMESPACE_CONTAINER 79 80 template<typename _InputIterator> 81 inline _GLIBCXX14_CONSTEXPR 82 typename iterator_traits<_InputIterator>::difference_type 83 __distance(_InputIterator __first, _InputIterator __last, 84 input_iterator_tag) 85 { 86 // concept requirements 87 __glibcxx_function_requires(_InputIteratorConcept<_InputIterator>) 88 89 typename iterator_traits<_InputIterator>::difference_type __n = 0; 90 while (__first != __last) 91 { 92 ++__first; 93 ++__n; 94 } 95 return __n; 96 } 97 98 template<typename _RandomAccessIterator> 99 __attribute__((__always_inline__)) 100 inline _GLIBCXX14_CONSTEXPR 101 typename iterator_traits<_RandomAccessIterator>::difference_type 102 __distance(_RandomAccessIterator __first, _RandomAccessIterator __last, 103 random_access_iterator_tag) 104 { 105 // concept requirements 106 __glibcxx_function_requires(_RandomAccessIteratorConcept< 107 _RandomAccessIterator>) 108 return __last - __first; 109 } 110 111 #if _GLIBCXX_USE_CXX11_ABI 112 // Forward declaration because of the qualified call in distance. 113 template<typename _Tp> 114 ptrdiff_t 115 __distance(_GLIBCXX_STD_C::_List_iterator<_Tp>, 116 _GLIBCXX_STD_C::_List_iterator<_Tp>, 117 input_iterator_tag); 118 119 template<typename _Tp> 120 ptrdiff_t 121 __distance(_GLIBCXX_STD_C::_List_const_iterator<_Tp>, 122 _GLIBCXX_STD_C::_List_const_iterator<_Tp>, 123 input_iterator_tag); 124 #endif 125 126 #if __cplusplus >= 201103L 127 // Give better error if std::distance called with a non-Cpp17InputIterator. 128 template<typename _OutputIterator> 129 void 130 __distance(_OutputIterator, _OutputIterator, output_iterator_tag) = delete; 131 #endif 132 133 /** 134 * @brief A generalization of pointer arithmetic. 135 * @param __first An input iterator. 136 * @param __last An input iterator. 137 * @return The distance between them. 138 * 139 * Returns @c n such that __first + n == __last. This requires 140 * that @p __last must be reachable from @p __first. Note that @c 141 * n may be negative. 142 * 143 * For random access iterators, this uses their @c + and @c - operations 144 * and are constant time. For other %iterator classes they are linear time. 145 */ 146 template<typename _InputIterator> 147 _GLIBCXX_NODISCARD __attribute__((__always_inline__)) 148 inline _GLIBCXX17_CONSTEXPR 149 typename iterator_traits<_InputIterator>::difference_type 150 distance(_InputIterator __first, _InputIterator __last) 151 { 152 // concept requirements -- taken care of in __distance 153 return std::__distance(__first, __last, 154 std::__iterator_category(__first)); 155 } 156 157 template<typename _InputIterator, typename _Distance> 158 inline _GLIBCXX14_CONSTEXPR void 159 __advance(_InputIterator& __i, _Distance __n, input_iterator_tag) 160 { 161 // concept requirements 162 __glibcxx_function_requires(_InputIteratorConcept<_InputIterator>) 163 __glibcxx_assert(__n >= 0); 164 while (__n--) 165 ++__i; 166 } 167 168 template<typename _BidirectionalIterator, typename _Distance> 169 inline _GLIBCXX14_CONSTEXPR void 170 __advance(_BidirectionalIterator& __i, _Distance __n, 171 bidirectional_iterator_tag) 172 { 173 // concept requirements 174 __glibcxx_function_requires(_BidirectionalIteratorConcept< 175 _BidirectionalIterator>) 176 if (__n > 0) 177 while (__n--) 178 ++__i; 179 else 180 while (__n++) 181 --__i; 182 } 183 184 template<typename _RandomAccessIterator, typename _Distance> 185 inline _GLIBCXX14_CONSTEXPR void 186 __advance(_RandomAccessIterator& __i, _Distance __n, 187 random_access_iterator_tag) 188 { 189 // concept requirements 190 __glibcxx_function_requires(_RandomAccessIteratorConcept< 191 _RandomAccessIterator>) 192 if (__builtin_constant_p(__n) && __n == 1) 193 ++__i; 194 else if (__builtin_constant_p(__n) && __n == -1) 195 --__i; 196 else 197 __i += __n; 198 } 199 200 #if __cplusplus >= 201103L 201 // Give better error if std::advance called with a non-Cpp17InputIterator. 202 template<typename _OutputIterator, typename _Distance> 203 void 204 __advance(_OutputIterator&, _Distance, output_iterator_tag) = delete; 205 #endif 206 207 /** 208 * @brief A generalization of pointer arithmetic. 209 * @param __i An input iterator. 210 * @param __n The @a delta by which to change @p __i. 211 * @return Nothing. 212 * 213 * This increments @p i by @p n. For bidirectional and random access 214 * iterators, @p __n may be negative, in which case @p __i is decremented. 215 * 216 * For random access iterators, this uses their @c + and @c - operations 217 * and are constant time. For other %iterator classes they are linear time. 218 */ 219 template<typename _InputIterator, typename _Distance> 220 __attribute__((__always_inline__)) 221 inline _GLIBCXX17_CONSTEXPR void 222 advance(_InputIterator& __i, _Distance __n) 223 { 224 // concept requirements -- taken care of in __advance 225 typename iterator_traits<_InputIterator>::difference_type __d = __n; 226 std::__advance(__i, __d, std::__iterator_category(__i)); 227 } 228 229 #if __cplusplus >= 201103L 230 231 template<typename _InputIterator> 232 _GLIBCXX_NODISCARD [[__gnu__::__always_inline__]] 233 inline _GLIBCXX17_CONSTEXPR _InputIterator 234 next(_InputIterator __x, typename 235 iterator_traits<_InputIterator>::difference_type __n = 1) 236 { 237 // concept requirements 238 __glibcxx_function_requires(_InputIteratorConcept<_InputIterator>) 239 std::advance(__x, __n); 240 return __x; 241 } 242 243 template<typename _BidirectionalIterator> 244 _GLIBCXX_NODISCARD [[__gnu__::__always_inline__]] 245 inline _GLIBCXX17_CONSTEXPR _BidirectionalIterator 246 prev(_BidirectionalIterator __x, typename 247 iterator_traits<_BidirectionalIterator>::difference_type __n = 1) 248 { 249 // concept requirements 250 __glibcxx_function_requires(_BidirectionalIteratorConcept< 251 _BidirectionalIterator>) 252 std::advance(__x, -__n); 253 return __x; 254 } 255 256 #endif // C++11 257 258 _GLIBCXX_END_NAMESPACE_VERSION 259 } // namespace 260 261 #endif /* _STL_ITERATOR_BASE_FUNCS_H */
