1 // Range access functions for containers -*- C++ -*-
3 // Copyright (C) 2010-2023 Free Software Foundation, Inc.
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)
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.
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.
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/>.
25 /** @file bits/range_access.h
26 * This is an internal header file, included by other library headers.
27 * Do not attempt to use it directly. @headername{iterator}
30 #ifndef _GLIBCXX_RANGE_ACCESS_H
31 #define _GLIBCXX_RANGE_ACCESS_H 1
33 #pragma GCC system_header
35 #if __cplusplus >= 201103L
36 #include <initializer_list>
37 #include <type_traits> // common_type_t, make_signed_t
38 #include <bits/stl_iterator.h> // reverse_iterator
40 namespace std
_GLIBCXX_VISIBILITY(default)
42 _GLIBCXX_BEGIN_NAMESPACE_VERSION
45 * @brief Return an iterator pointing to the first element of
47 * @param __cont Container.
49 template<typename _Container
>
50 [[__nodiscard__
, __gnu__::__always_inline__
]]
51 inline _GLIBCXX17_CONSTEXPR
auto
52 begin(_Container
& __cont
) -> decltype(__cont
.begin())
53 { return __cont
.begin(); }
56 * @brief Return an iterator pointing to the first element of
57 * the const container.
58 * @param __cont Container.
60 template<typename _Container
>
61 [[__nodiscard__
, __gnu__::__always_inline__
]]
62 inline _GLIBCXX17_CONSTEXPR
auto
63 begin(const _Container
& __cont
) -> decltype(__cont
.begin())
64 { return __cont
.begin(); }
67 * @brief Return an iterator pointing to one past the last element of
69 * @param __cont Container.
71 template<typename _Container
>
72 [[__nodiscard__
, __gnu__::__always_inline__
]]
73 inline _GLIBCXX17_CONSTEXPR
auto
74 end(_Container
& __cont
) -> decltype(__cont
.end())
75 { return __cont
.end(); }
78 * @brief Return an iterator pointing to one past the last element of
79 * the const container.
80 * @param __cont Container.
82 template<typename _Container
>
83 [[__nodiscard__
, __gnu__::__always_inline__
]]
84 inline _GLIBCXX17_CONSTEXPR
auto
85 end(const _Container
& __cont
) -> decltype(__cont
.end())
86 { return __cont
.end(); }
89 * @brief Return an iterator pointing to the first element of the array.
92 template<typename _Tp
, size_t _Nm
>
93 [[__nodiscard__
, __gnu__::__always_inline__
]]
94 inline _GLIBCXX14_CONSTEXPR _Tp
*
95 begin(_Tp (&__arr
)[_Nm
]) noexcept
99 * @brief Return an iterator pointing to one past the last element
101 * @param __arr Array.
103 template<typename _Tp
, size_t _Nm
>
104 [[__nodiscard__
, __gnu__::__always_inline__
]]
105 inline _GLIBCXX14_CONSTEXPR _Tp
*
106 end(_Tp (&__arr
)[_Nm
]) noexcept
107 { return __arr
+ _Nm
; }
109 #if __cplusplus >= 201402L
111 template<typename _Tp
> class valarray
;
112 // These overloads must be declared for cbegin and cend to use them.
113 template<typename _Tp
> _Tp
* begin(valarray
<_Tp
>&) noexcept
;
114 template<typename _Tp
> const _Tp
* begin(const valarray
<_Tp
>&) noexcept
;
115 template<typename _Tp
> _Tp
* end(valarray
<_Tp
>&) noexcept
;
116 template<typename _Tp
> const _Tp
* end(const valarray
<_Tp
>&) noexcept
;
119 * @brief Return an iterator pointing to the first element of
120 * the const container.
121 * @param __cont Container.
123 template<typename _Container
>
124 [[__nodiscard__
, __gnu__::__always_inline__
]]
126 cbegin(const _Container
& __cont
) noexcept(noexcept(std::begin(__cont
)))
127 -> decltype(std::begin(__cont
))
128 { return std::begin(__cont
); }
131 * @brief Return an iterator pointing to one past the last element of
132 * the const container.
133 * @param __cont Container.
135 template<typename _Container
>
136 [[__nodiscard__
, __gnu__::__always_inline__
]]
138 cend(const _Container
& __cont
) noexcept(noexcept(std::end(__cont
)))
139 -> decltype(std::end(__cont
))
140 { return std::end(__cont
); }
143 * @brief Return a reverse iterator pointing to the last element of
145 * @param __cont Container.
147 template<typename _Container
>
148 [[__nodiscard__
, __gnu__::__always_inline__
]]
149 inline _GLIBCXX17_CONSTEXPR
auto
150 rbegin(_Container
& __cont
) -> decltype(__cont
.rbegin())
151 { return __cont
.rbegin(); }
154 * @brief Return a reverse iterator pointing to the last element of
155 * the const container.
156 * @param __cont Container.
158 template<typename _Container
>
159 [[__nodiscard__
, __gnu__::__always_inline__
]]
160 inline _GLIBCXX17_CONSTEXPR
auto
161 rbegin(const _Container
& __cont
) -> decltype(__cont
.rbegin())
162 { return __cont
.rbegin(); }
165 * @brief Return a reverse iterator pointing one past the first element of
167 * @param __cont Container.
169 template<typename _Container
>
170 [[__nodiscard__
, __gnu__::__always_inline__
]]
171 inline _GLIBCXX17_CONSTEXPR
auto
172 rend(_Container
& __cont
) -> decltype(__cont
.rend())
173 { return __cont
.rend(); }
176 * @brief Return a reverse iterator pointing one past the first element of
177 * the const container.
178 * @param __cont Container.
180 template<typename _Container
>
181 [[__nodiscard__
, __gnu__::__always_inline__
]]
182 inline _GLIBCXX17_CONSTEXPR
auto
183 rend(const _Container
& __cont
) -> decltype(__cont
.rend())
184 { return __cont
.rend(); }
187 * @brief Return a reverse iterator pointing to the last element of
189 * @param __arr Array.
191 template<typename _Tp
, size_t _Nm
>
193 inline _GLIBCXX17_CONSTEXPR reverse_iterator
<_Tp
*>
194 rbegin(_Tp (&__arr
)[_Nm
]) noexcept
195 { return reverse_iterator
<_Tp
*>(__arr
+ _Nm
); }
198 * @brief Return a reverse iterator pointing one past the first element of
200 * @param __arr Array.
202 template<typename _Tp
, size_t _Nm
>
204 inline _GLIBCXX17_CONSTEXPR reverse_iterator
<_Tp
*>
205 rend(_Tp (&__arr
)[_Nm
]) noexcept
206 { return reverse_iterator
<_Tp
*>(__arr
); }
209 * @brief Return a reverse iterator pointing to the last element of
210 * the initializer_list.
211 * @param __il initializer_list.
213 template<typename _Tp
>
215 inline _GLIBCXX17_CONSTEXPR reverse_iterator
<const _Tp
*>
216 rbegin(initializer_list
<_Tp
> __il
) noexcept
217 { return reverse_iterator
<const _Tp
*>(__il
.end()); }
220 * @brief Return a reverse iterator pointing one past the first element of
221 * the initializer_list.
222 * @param __il initializer_list.
224 template<typename _Tp
>
226 inline _GLIBCXX17_CONSTEXPR reverse_iterator
<const _Tp
*>
227 rend(initializer_list
<_Tp
> __il
) noexcept
228 { return reverse_iterator
<const _Tp
*>(__il
.begin()); }
231 * @brief Return a reverse iterator pointing to the last element of
232 * the const container.
233 * @param __cont Container.
235 template<typename _Container
>
236 [[__nodiscard__
, __gnu__::__always_inline__
]]
237 inline _GLIBCXX17_CONSTEXPR
auto
238 crbegin(const _Container
& __cont
) -> decltype(std::rbegin(__cont
))
239 { return std::rbegin(__cont
); }
242 * @brief Return a reverse iterator pointing one past the first element of
243 * the const container.
244 * @param __cont Container.
246 template<typename _Container
>
247 [[__nodiscard__
, __gnu__::__always_inline__
]]
248 inline _GLIBCXX17_CONSTEXPR
auto
249 crend(const _Container
& __cont
) -> decltype(std::rend(__cont
))
250 { return std::rend(__cont
); }
254 #ifdef __glibcxx_nonmember_container_access // C++ >= 17
256 * @brief Return the size of a container.
257 * @param __cont Container.
259 template <typename _Container
>
260 [[nodiscard
, __gnu__::__always_inline__
]]
262 size(const _Container
& __cont
) noexcept(noexcept(__cont
.size()))
263 -> decltype(__cont
.size())
264 { return __cont
.size(); }
267 * @brief Return the size of an array.
269 template <typename _Tp
, size_t _Nm
>
270 [[nodiscard
, __gnu__::__always_inline__
]]
272 size(const _Tp (&)[_Nm
]) noexcept
276 * @brief Return whether a container is empty.
277 * @param __cont Container.
279 template <typename _Container
>
280 [[nodiscard
, __gnu__::__always_inline__
]]
282 empty(const _Container
& __cont
) noexcept(noexcept(__cont
.empty()))
283 -> decltype(__cont
.empty())
284 { return __cont
.empty(); }
287 * @brief Return whether an array is empty (always false).
289 template <typename _Tp
, size_t _Nm
>
290 [[nodiscard
, __gnu__::__always_inline__
]]
292 empty(const _Tp (&)[_Nm
]) noexcept
296 * @brief Return whether an initializer_list is empty.
297 * @param __il Initializer list.
299 template <typename _Tp
>
300 [[nodiscard
, __gnu__::__always_inline__
]]
302 empty(initializer_list
<_Tp
> __il
) noexcept
303 { return __il
.size() == 0;}
306 * @brief Return the data pointer of a container.
307 * @param __cont Container.
309 template <typename _Container
>
310 [[nodiscard
, __gnu__::__always_inline__
]]
312 data(_Container
& __cont
) noexcept(noexcept(__cont
.data()))
313 -> decltype(__cont
.data())
314 { return __cont
.data(); }
317 * @brief Return the data pointer of a const container.
318 * @param __cont Container.
320 template <typename _Container
>
321 [[nodiscard
, __gnu__::__always_inline__
]]
323 data(const _Container
& __cont
) noexcept(noexcept(__cont
.data()))
324 -> decltype(__cont
.data())
325 { return __cont
.data(); }
328 * @brief Return the data pointer of an array.
329 * @param __array Array.
331 template <typename _Tp
, size_t _Nm
>
332 [[nodiscard
, __gnu__::__always_inline__
]]
334 data(_Tp (&__array
)[_Nm
]) noexcept
338 * @brief Return the data pointer of an initializer list.
339 * @param __il Initializer list.
341 template <typename _Tp
>
342 [[nodiscard
, __gnu__::__always_inline__
]]
344 data(initializer_list
<_Tp
> __il
) noexcept
345 { return __il
.begin(); }
346 #endif // __glibcxx_nonmember_container_access
348 #ifdef __glibcxx_ssize // C++ >= 20
349 template<typename _Container
>
350 [[nodiscard
, __gnu__::__always_inline__
]]
352 ssize(const _Container
& __cont
)
353 noexcept(noexcept(__cont
.size()))
354 -> common_type_t
<ptrdiff_t, make_signed_t
<decltype(__cont
.size())>>
356 using type
= make_signed_t
<decltype(__cont
.size())>;
357 return static_cast<common_type_t
<ptrdiff_t, type
>>(__cont
.size());
360 template<typename _Tp
, ptrdiff_t _Num
>
361 [[nodiscard
, __gnu__::__always_inline__
]]
363 ssize(const _Tp (&)[_Num
]) noexcept
365 #endif // __glibcxx_ssize
366 _GLIBCXX_END_NAMESPACE_VERSION
370 #endif // _GLIBCXX_RANGE_ACCESS_H