1 /* Copyright (C) 2017-2020 Free Software Foundation, Inc. 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" 22 #include <type_traits> 23 24 /* An array_view is an abstraction that provides a non-owning view 25 over a sequence of contiguous objects. 26 27 A way to put it is that array_view is to std::vector (and 28 std::array and built-in arrays with rank==1) like std::string_view 29 is to std::string. 30 31 The main intent of array_view is to use it as function input 32 parameter type, making it possible to pass in any sequence of 33 contiguous objects, irrespective of whether the objects live on the 34 stack or heap and what actual container owns them. Implicit 35 construction from the element type is supported too, making it easy 36 to call functions that expect an array of elements when you only 37 have one element (usually on the stack). For example: 38 39 struct A { .... }; 40 void function (gdb::array_view<A> as); 41 42 std::vector<A> std_vec = ...; 43 std::array<A, N> std_array = ...; 44 A array[] = {...}; 45 A elem; 46 47 function (std_vec); 48 function (std_array); 49 function (array); 50 function (elem); 51 52 Views can be either mutable or const. A const view is simply 53 created by specifying a const T as array_view template parameter, 54 in which case operator[] of non-const array_view objects ends up 55 returning const references. Making the array_view itself const is 56 analogous to making a pointer itself be const. I.e., disables 57 re-seating the view/pointer. 58 59 Since array_view objects are small (pointer plus size), and 60 designed to be trivially copyable, they should generally be passed 61 around by value. 62 63 You can find unit tests covering the whole API in 64 unittests/array-view-selftests.c. */ 65 66 namespace gdb { 67 68 template <typename T> 69 class array_view 70 { 71 /* True iff decayed T is the same as decayed U. E.g., we want to 72 say that 'T&' is the same as 'const T'. */ 73 template <typename U> 74 using IsDecayedT = typename std::is_same<typename std::decay<T>::type, 75 typename std::decay<U>::type>; 76 77 /* True iff decayed T is the same as decayed U, and 'U *' is 78 implicitly convertible to 'T *'. This is a requirement for 79 several methods. */ 80 template <typename U> 81 using DecayedConvertible = gdb::And<IsDecayedT<U>, 82 std::is_convertible<U *, T *>>; 83 84 public: 85 using value_type = T; 86 using reference = T &; 87 using const_reference = const T &; 88 using size_type = size_t; 89 90 /* Default construction creates an empty view. */ 91 constexpr array_view () noexcept 92 : m_array (nullptr), m_size (0) 93 {} 94 95 /* Create an array view over a single object of the type of an 96 array_view element. The created view as size==1. This is 97 templated on U to allow constructing a array_view<const T> over a 98 (non-const) T. The "convertible" requirement makes sure that you 99 can't create an array_view<T> over a const T. */ 100 template<typename U, 101 typename = Requires<DecayedConvertible<U>>> 102 constexpr array_view (U &elem) noexcept 103 : m_array (&elem), m_size (1) 104 {} 105 106 /* Same as above, for rvalue references. */ 107 template<typename U, 108 typename = Requires<DecayedConvertible<U>>> 109 constexpr array_view (U &&elem) noexcept 110 : m_array (&elem), m_size (1) 111 {} 112 113 /* Create an array view from a pointer to an array and an element 114 count. */ 115 template<typename U, 116 typename = Requires<DecayedConvertible<U>>> 117 constexpr array_view (U *array, size_t size) noexcept 118 : m_array (array), m_size (size) 119 {} 120 121 /* Create an array view from a range. This is templated on both U 122 an V to allow passing in a mix of 'const T *' and 'T *'. */ 123 template<typename U, typename V, 124 typename = Requires<DecayedConvertible<U>>, 125 typename = Requires<DecayedConvertible<V>>> 126 constexpr array_view (U *begin, V *end) noexcept 127 : m_array (begin), m_size (end - begin) 128 {} 129 130 /* Create an array view from an array. */ 131 template<typename U, size_t Size, 132 typename = Requires<DecayedConvertible<U>>> 133 constexpr array_view (U (&array)[Size]) noexcept 134 : m_array (array), m_size (Size) 135 {} 136 137 /* Create an array view from a contiguous container. E.g., 138 std::vector and std::array. */ 139 template<typename Container, 140 typename = Requires<gdb::Not<IsDecayedT<Container>>>, 141 typename 142 = Requires<std::is_convertible 143 <decltype (std::declval<Container> ().data ()), 144 T *>>, 145 typename 146 = Requires<std::is_convertible 147 <decltype (std::declval<Container> ().size ()), 148 size_type>>> 149 constexpr array_view (Container &&c) noexcept 150 : m_array (c.data ()), m_size (c.size ()) 151 {} 152 153 /* Observer methods. Some of these can't be constexpr until we 154 require C++14. */ 155 /*constexpr14*/ T *data () noexcept { return m_array; } 156 constexpr const T *data () const noexcept { return m_array; } 157 158 /*constexpr14*/ T *begin () noexcept { return m_array; } 159 constexpr const T *begin () const noexcept { return m_array; } 160 161 /*constexpr14*/ T *end () noexcept { return m_array + m_size; } 162 constexpr const T *end () const noexcept { return m_array + m_size; } 163 164 /*constexpr14*/ reference operator[] (size_t index) noexcept 165 { return m_array[index]; } 166 constexpr const_reference operator[] (size_t index) const noexcept 167 { return m_array[index]; } 168 169 constexpr size_type size () const noexcept { return m_size; } 170 constexpr bool empty () const noexcept { return m_size == 0; } 171 172 /* Slice an array view. */ 173 174 /* Return a new array view over SIZE elements starting at START. */ 175 constexpr array_view<T> slice (size_type start, size_type size) const noexcept 176 { return {m_array + start, size}; } 177 178 /* Return a new array view over all the elements after START, 179 inclusive. */ 180 constexpr array_view<T> slice (size_type start) const noexcept 181 { return {m_array + start, size () - start}; } 182 183 private: 184 T *m_array; 185 size_type m_size; 186 }; 187 188 /* Compare LHS and RHS for (deep) equality. That is, whether LHS and 189 RHS have the same sizes, and whether each pair of elements of LHS 190 and RHS at the same position compares equal. */ 191 192 template <typename T> 193 bool 194 operator== (const gdb::array_view<T> &lhs, const gdb::array_view<T> &rhs) 195 { 196 if (lhs.size () != rhs.size ()) 197 return false; 198 199 for (size_t i = 0; i < lhs.size (); i++) 200 if (!(lhs[i] == rhs[i])) 201 return false; 202 203 return true; 204 } 205 206 /* Compare two array_views for inequality. */ 207 208 template <typename T> 209 bool 210 operator!= (const gdb::array_view<T> &lhs, const gdb::array_view<T> &rhs) 211 { 212 return !(lhs == rhs); 213 } 214 215 /* Create an array view from a pointer to an array and an element 216 count. 217 218 This is useful as alternative to constructing an array_view using 219 brace initialization when the size variable you have handy is of 220 signed type, since otherwise without an explicit cast the code 221 would be ill-formed. 222 223 For example, with: 224 225 extern void foo (int, int, gdb::array_view<value *>); 226 227 value *args[2]; 228 int nargs; 229 foo (1, 2, {values, nargs}); 230 231 You'd get: 232 233 source.c:10: error: narrowing conversion of ‘nargs’ from ‘int’ to 234 ‘size_t {aka long unsigned int}’ inside { } [-Werror=narrowing] 235 236 You could fix it by writing the somewhat distracting explicit cast: 237 238 foo (1, 2, {values, (size_t) nargs}); 239 240 Or by instantiating an array_view explicitly: 241 242 foo (1, 2, gdb::array_view<value *>(values, nargs)); 243 244 Or, better, using make_array_view, which has the advantage of 245 inferring the arrav_view element's type: 246 247 foo (1, 2, gdb::make_array_view (values, nargs)); 248 */ 249 250 template<typename U> 251 constexpr inline array_view<U> 252 make_array_view (U *array, size_t size) noexcept 253 { 254 return {array, size}; 255 } 256 257 } /* namespace gdb */ 258 259 #endif 260