]>
Commit | Line | Data |
---|---|---|
1d506c26 | 1 | /* Copyright (C) 2017-2024 Free Software Foundation, Inc. |
7c44b49c PA |
2 | |
3 | This file is part of GDB. | |
4 | ||
5 | This program is free software; you can redistribute it and/or modify | |
6 | it under the terms of the GNU General Public License as published by | |
7 | the Free Software Foundation; either version 3 of the License, or | |
8 | (at your option) any later version. | |
9 | ||
10 | This program is distributed in the hope that it will be useful, | |
11 | but WITHOUT ANY WARRANTY; without even the implied warranty of | |
12 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
13 | GNU General Public License for more details. | |
14 | ||
15 | You should have received a copy of the GNU General Public License | |
16 | along with this program. If not, see <http://www.gnu.org/licenses/>. */ | |
17 | ||
18 | #ifndef COMMON_ARRAY_VIEW_H | |
19 | #define COMMON_ARRAY_VIEW_H | |
20 | ||
21 | #include "traits.h" | |
4bce7cda | 22 | #include <algorithm> |
7c44b49c | 23 | #include <type_traits> |
a6e5abae | 24 | #include "gdbsupport/gdb_assert.h" |
7c44b49c PA |
25 | |
26 | /* An array_view is an abstraction that provides a non-owning view | |
27 | over a sequence of contiguous objects. | |
28 | ||
29 | A way to put it is that array_view is to std::vector (and | |
30 | std::array and built-in arrays with rank==1) like std::string_view | |
31 | is to std::string. | |
32 | ||
33 | The main intent of array_view is to use it as function input | |
34 | parameter type, making it possible to pass in any sequence of | |
35 | contiguous objects, irrespective of whether the objects live on the | |
36 | stack or heap and what actual container owns them. Implicit | |
37 | construction from the element type is supported too, making it easy | |
38 | to call functions that expect an array of elements when you only | |
39 | have one element (usually on the stack). For example: | |
40 | ||
41 | struct A { .... }; | |
42 | void function (gdb::array_view<A> as); | |
43 | ||
44 | std::vector<A> std_vec = ...; | |
45 | std::array<A, N> std_array = ...; | |
46 | A array[] = {...}; | |
47 | A elem; | |
48 | ||
49 | function (std_vec); | |
50 | function (std_array); | |
51 | function (array); | |
52 | function (elem); | |
53 | ||
54 | Views can be either mutable or const. A const view is simply | |
55 | created by specifying a const T as array_view template parameter, | |
56 | in which case operator[] of non-const array_view objects ends up | |
57 | returning const references. Making the array_view itself const is | |
58 | analogous to making a pointer itself be const. I.e., disables | |
59 | re-seating the view/pointer. | |
60 | ||
61 | Since array_view objects are small (pointer plus size), and | |
62 | designed to be trivially copyable, they should generally be passed | |
63 | around by value. | |
64 | ||
65 | You can find unit tests covering the whole API in | |
66 | unittests/array-view-selftests.c. */ | |
67 | ||
68 | namespace gdb { | |
69 | ||
70 | template <typename T> | |
71 | class array_view | |
72 | { | |
73 | /* True iff decayed T is the same as decayed U. E.g., we want to | |
74 | say that 'T&' is the same as 'const T'. */ | |
75 | template <typename U> | |
76 | using IsDecayedT = typename std::is_same<typename std::decay<T>::type, | |
77 | typename std::decay<U>::type>; | |
78 | ||
79 | /* True iff decayed T is the same as decayed U, and 'U *' is | |
80 | implicitly convertible to 'T *'. This is a requirement for | |
81 | several methods. */ | |
82 | template <typename U> | |
83 | using DecayedConvertible = gdb::And<IsDecayedT<U>, | |
84 | std::is_convertible<U *, T *>>; | |
85 | ||
86 | public: | |
87 | using value_type = T; | |
88 | using reference = T &; | |
89 | using const_reference = const T &; | |
90 | using size_type = size_t; | |
91 | ||
92 | /* Default construction creates an empty view. */ | |
93 | constexpr array_view () noexcept | |
94 | : m_array (nullptr), m_size (0) | |
95 | {} | |
96 | ||
97 | /* Create an array view over a single object of the type of an | |
98 | array_view element. The created view as size==1. This is | |
99 | templated on U to allow constructing a array_view<const T> over a | |
100 | (non-const) T. The "convertible" requirement makes sure that you | |
101 | can't create an array_view<T> over a const T. */ | |
102 | template<typename U, | |
103 | typename = Requires<DecayedConvertible<U>>> | |
104 | constexpr array_view (U &elem) noexcept | |
105 | : m_array (&elem), m_size (1) | |
106 | {} | |
107 | ||
108 | /* Same as above, for rvalue references. */ | |
109 | template<typename U, | |
110 | typename = Requires<DecayedConvertible<U>>> | |
111 | constexpr array_view (U &&elem) noexcept | |
112 | : m_array (&elem), m_size (1) | |
113 | {} | |
114 | ||
115 | /* Create an array view from a pointer to an array and an element | |
116 | count. */ | |
117 | template<typename U, | |
118 | typename = Requires<DecayedConvertible<U>>> | |
119 | constexpr array_view (U *array, size_t size) noexcept | |
120 | : m_array (array), m_size (size) | |
121 | {} | |
122 | ||
123 | /* Create an array view from a range. This is templated on both U | |
124 | an V to allow passing in a mix of 'const T *' and 'T *'. */ | |
125 | template<typename U, typename V, | |
126 | typename = Requires<DecayedConvertible<U>>, | |
127 | typename = Requires<DecayedConvertible<V>>> | |
128 | constexpr array_view (U *begin, V *end) noexcept | |
129 | : m_array (begin), m_size (end - begin) | |
130 | {} | |
131 | ||
132 | /* Create an array view from an array. */ | |
133 | template<typename U, size_t Size, | |
134 | typename = Requires<DecayedConvertible<U>>> | |
135 | constexpr array_view (U (&array)[Size]) noexcept | |
136 | : m_array (array), m_size (Size) | |
137 | {} | |
138 | ||
139 | /* Create an array view from a contiguous container. E.g., | |
140 | std::vector and std::array. */ | |
141 | template<typename Container, | |
142 | typename = Requires<gdb::Not<IsDecayedT<Container>>>, | |
143 | typename | |
e92f2b5e LS |
144 | = Requires<DecayedConvertible |
145 | <typename std::remove_pointer | |
146 | <decltype (std::declval<Container> ().data ()) | |
147 | >::type>>, | |
7c44b49c PA |
148 | typename |
149 | = Requires<std::is_convertible | |
150 | <decltype (std::declval<Container> ().size ()), | |
151 | size_type>>> | |
152 | constexpr array_view (Container &&c) noexcept | |
153 | : m_array (c.data ()), m_size (c.size ()) | |
154 | {} | |
155 | ||
dead89d2 TT |
156 | /* Observer methods. */ |
157 | constexpr T *data () noexcept { return m_array; } | |
7c44b49c PA |
158 | constexpr const T *data () const noexcept { return m_array; } |
159 | ||
dead89d2 | 160 | constexpr T *begin () noexcept { return m_array; } |
7c44b49c PA |
161 | constexpr const T *begin () const noexcept { return m_array; } |
162 | ||
dead89d2 | 163 | constexpr T *end () noexcept { return m_array + m_size; } |
7c44b49c PA |
164 | constexpr const T *end () const noexcept { return m_array + m_size; } |
165 | ||
dead89d2 | 166 | constexpr reference operator[] (size_t index) noexcept |
d9f82e93 SM |
167 | { |
168 | #if defined(_GLIBCXX_DEBUG) | |
169 | gdb_assert (index < m_size); | |
170 | #endif | |
171 | return m_array[index]; | |
172 | } | |
7c44b49c | 173 | constexpr const_reference operator[] (size_t index) const noexcept |
d9f82e93 | 174 | { |
dead89d2 | 175 | #if defined(_GLIBCXX_DEBUG) |
d9f82e93 SM |
176 | gdb_assert (index < m_size); |
177 | #endif | |
178 | return m_array[index]; | |
179 | } | |
7c44b49c PA |
180 | |
181 | constexpr size_type size () const noexcept { return m_size; } | |
182 | constexpr bool empty () const noexcept { return m_size == 0; } | |
183 | ||
6b1747cd PA |
184 | /* Slice an array view. */ |
185 | ||
186 | /* Return a new array view over SIZE elements starting at START. */ | |
8cb2c7fc | 187 | [[nodiscard]] |
6b1747cd | 188 | constexpr array_view<T> slice (size_type start, size_type size) const noexcept |
d9f82e93 | 189 | { |
dead89d2 | 190 | #if defined(_GLIBCXX_DEBUG) |
d9f82e93 SM |
191 | gdb_assert (start + size <= m_size); |
192 | #endif | |
193 | return {m_array + start, size}; | |
194 | } | |
6b1747cd PA |
195 | |
196 | /* Return a new array view over all the elements after START, | |
197 | inclusive. */ | |
8cb2c7fc | 198 | [[nodiscard]] |
6b1747cd | 199 | constexpr array_view<T> slice (size_type start) const noexcept |
d9f82e93 | 200 | { |
dead89d2 | 201 | #if defined(_GLIBCXX_DEBUG) |
d9f82e93 SM |
202 | gdb_assert (start <= m_size); |
203 | #endif | |
204 | return {m_array + start, size () - start}; | |
205 | } | |
6b1747cd | 206 | |
7c44b49c PA |
207 | private: |
208 | T *m_array; | |
209 | size_type m_size; | |
210 | }; | |
211 | ||
4bce7cda SM |
212 | /* Copy the contents referenced by the array view SRC to the array view DEST. |
213 | ||
214 | The two array views must have the same length. */ | |
215 | ||
216 | template <typename U, typename T> | |
217 | void copy (gdb::array_view<U> src, gdb::array_view<T> dest) | |
218 | { | |
219 | gdb_assert (dest.size () == src.size ()); | |
220 | if (dest.data () < src.data ()) | |
221 | std::copy (src.begin (), src.end (), dest.begin ()); | |
222 | else if (dest.data () > src.data ()) | |
223 | std::copy_backward (src.begin (), src.end (), dest.end ()); | |
224 | } | |
225 | ||
d5f4488f SM |
226 | /* Compare LHS and RHS for (deep) equality. That is, whether LHS and |
227 | RHS have the same sizes, and whether each pair of elements of LHS | |
228 | and RHS at the same position compares equal. */ | |
229 | ||
230 | template <typename T> | |
231 | bool | |
232 | operator== (const gdb::array_view<T> &lhs, const gdb::array_view<T> &rhs) | |
233 | { | |
234 | if (lhs.size () != rhs.size ()) | |
235 | return false; | |
236 | ||
237 | for (size_t i = 0; i < lhs.size (); i++) | |
238 | if (!(lhs[i] == rhs[i])) | |
239 | return false; | |
240 | ||
241 | return true; | |
242 | } | |
243 | ||
244 | /* Compare two array_views for inequality. */ | |
245 | ||
246 | template <typename T> | |
247 | bool | |
248 | operator!= (const gdb::array_view<T> &lhs, const gdb::array_view<T> &rhs) | |
249 | { | |
250 | return !(lhs == rhs); | |
251 | } | |
252 | ||
e71585ff PA |
253 | /* Create an array view from a pointer to an array and an element |
254 | count. | |
255 | ||
256 | This is useful as alternative to constructing an array_view using | |
257 | brace initialization when the size variable you have handy is of | |
258 | signed type, since otherwise without an explicit cast the code | |
259 | would be ill-formed. | |
260 | ||
261 | For example, with: | |
262 | ||
263 | extern void foo (int, int, gdb::array_view<value *>); | |
264 | ||
265 | value *args[2]; | |
266 | int nargs; | |
267 | foo (1, 2, {values, nargs}); | |
268 | ||
269 | You'd get: | |
270 | ||
271 | source.c:10: error: narrowing conversion of ‘nargs’ from ‘int’ to | |
272 | ‘size_t {aka long unsigned int}’ inside { } [-Werror=narrowing] | |
273 | ||
274 | You could fix it by writing the somewhat distracting explicit cast: | |
275 | ||
276 | foo (1, 2, {values, (size_t) nargs}); | |
277 | ||
278 | Or by instantiating an array_view explicitly: | |
279 | ||
280 | foo (1, 2, gdb::array_view<value *>(values, nargs)); | |
281 | ||
282 | Or, better, using make_array_view, which has the advantage of | |
3bfdcabb | 283 | inferring the array_view element's type: |
e71585ff PA |
284 | |
285 | foo (1, 2, gdb::make_array_view (values, nargs)); | |
286 | */ | |
287 | ||
288 | template<typename U> | |
289 | constexpr inline array_view<U> | |
290 | make_array_view (U *array, size_t size) noexcept | |
291 | { | |
292 | return {array, size}; | |
293 | } | |
294 | ||
7c44b49c PA |
295 | } /* namespace gdb */ |
296 | ||
297 | #endif |