gdbsupport/array-view.h

   1 /* Copyright (C) 2017-2023 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 <algorithm>
  23 #include <type_traits>
  24 #include "gdbsupport/gdb_assert.h"
  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
 144              = Requires<DecayedConvertible
 145                         <typename std::remove_pointer
 146                          <decltype (std::declval<Container> ().data ())
 147                          >::type>>,
 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
 156   /* Observer methods.  Some of these can't be constexpr until we
 157      require C++14.  */
 158   /*constexpr14*/ T *data () noexcept { return m_array; }
 159   constexpr const T *data () const noexcept { return m_array; }
 160
 161   /*constexpr14*/ T *begin () noexcept { return m_array; }
 162   constexpr const T *begin () const noexcept { return m_array; }
 163
 164   /*constexpr14*/ T *end () noexcept { return m_array + m_size; }
 165   constexpr const T *end () const noexcept { return m_array + m_size; }
 166
 167   /*constexpr14*/ reference operator[] (size_t index) noexcept
 168   {
 169 #if defined(_GLIBCXX_DEBUG)
 170     gdb_assert (index < m_size);
 171 #endif
 172     return m_array[index];
 173   }
 174   constexpr const_reference operator[] (size_t index) const noexcept
 175   {
 176 #if defined(_GLIBCXX_DEBUG) && __cplusplus >= 201402L
 177     gdb_assert (index < m_size);
 178 #endif
 179     return m_array[index];
 180   }
 181
 182   constexpr size_type size () const noexcept { return m_size; }
 183   constexpr bool empty () const noexcept { return m_size == 0; }
 184
 185   /* Slice an array view.  */
 186
 187   /* Return a new array view over SIZE elements starting at START.  */
 188   constexpr array_view<T> slice (size_type start, size_type size) const noexcept
 189   {
 190 #if defined(_GLIBCXX_DEBUG) && __cplusplus >= 201402L
 191     gdb_assert (start + size <= m_size);
 192 #endif
 193     return {m_array + start, size};
 194   }
 195
 196   /* Return a new array view over all the elements after START,
 197      inclusive.  */
 198   constexpr array_view<T> slice (size_type start) const noexcept
 199   {
 200 #if defined(_GLIBCXX_DEBUG) && __cplusplus >= 201402L
 201     gdb_assert (start <= m_size);
 202 #endif
 203     return {m_array + start, size () - start};
 204   }
 205
 206 private:
 207   T *m_array;
 208   size_type m_size;
 209 };
 210
 211 /* Copy the contents referenced by the array view SRC to the array view DEST.
 212
 213    The two array views must have the same length.  */
 214
 215 template <typename U, typename T>
 216 void copy (gdb::array_view<U> src, gdb::array_view<T> dest)
 217 {
 218   gdb_assert (dest.size () == src.size ());
 219   if (dest.data () < src.data ())
 220     std::copy (src.begin (), src.end (), dest.begin ());
 221   else if (dest.data () > src.data ())
 222     std::copy_backward (src.begin (), src.end (), dest.end ());
 223 }
 224
 225 /* Compare LHS and RHS for (deep) equality.  That is, whether LHS and
 226    RHS have the same sizes, and whether each pair of elements of LHS
 227    and RHS at the same position compares equal.  */
 228
 229 template <typename T>
 230 bool
 231 operator== (const gdb::array_view<T> &lhs, const gdb::array_view<T> &rhs)
 232 {
 233   if (lhs.size () != rhs.size ())
 234     return false;
 235
 236   for (size_t i = 0; i < lhs.size (); i++)
 237     if (!(lhs[i] == rhs[i]))
 238       return false;
 239
 240   return true;
 241 }
 242
 243 /* Compare two array_views for inequality.  */
 244
 245 template <typename T>
 246 bool
 247 operator!= (const gdb::array_view<T> &lhs, const gdb::array_view<T> &rhs)
 248 {
 249   return !(lhs == rhs);
 250 }
 251
 252 /* Create an array view from a pointer to an array and an element
 253    count.
 254
 255    This is useful as alternative to constructing an array_view using
 256    brace initialization when the size variable you have handy is of
 257    signed type, since otherwise without an explicit cast the code
 258    would be ill-formed.
 259
 260    For example, with:
 261
 262      extern void foo (int, int, gdb::array_view<value *>);
 263
 264      value *args[2];
 265      int nargs;
 266      foo (1, 2, {values, nargs});
 267
 268    You'd get:
 269
 270      source.c:10: error: narrowing conversion of ‘nargs’ from ‘int’ to
 271      ‘size_t {aka long unsigned int}’ inside { } [-Werror=narrowing]
 272
 273    You could fix it by writing the somewhat distracting explicit cast:
 274
 275      foo (1, 2, {values, (size_t) nargs});
 276
 277    Or by instantiating an array_view explicitly:
 278
 279      foo (1, 2, gdb::array_view<value *>(values, nargs));
 280
 281    Or, better, using make_array_view, which has the advantage of
 282    inferring the array_view element's type:
 283
 284      foo (1, 2, gdb::make_array_view (values, nargs));
 285 */
 286
 287 template<typename U>
 288 constexpr inline array_view<U>
 289 make_array_view (U *array, size_t size) noexcept
 290 {
 291   return {array, size};
 292 }
 293
 294 } /* namespace gdb */
 295
 296 #endif