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   [[nodiscard]]
 189   constexpr array_view<T> slice (size_type start, size_type size) const noexcept
 190   {
 191 #if defined(_GLIBCXX_DEBUG) && __cplusplus >= 201402L
 192     gdb_assert (start + size <= m_size);
 193 #endif
 194     return {m_array + start, size};
 195   }
 196
 197   /* Return a new array view over all the elements after START,
 198      inclusive.  */
 199   [[nodiscard]]
 200   constexpr array_view<T> slice (size_type start) const noexcept
 201   {
 202 #if defined(_GLIBCXX_DEBUG) && __cplusplus >= 201402L
 203     gdb_assert (start <= m_size);
 204 #endif
 205     return {m_array + start, size () - start};
 206   }
 207
 208 private:
 209   T *m_array;
 210   size_type m_size;
 211 };
 212
 213 /* Copy the contents referenced by the array view SRC to the array view DEST.
 214
 215    The two array views must have the same length.  */
 216
 217 template <typename U, typename T>
 218 void copy (gdb::array_view<U> src, gdb::array_view<T> dest)
 219 {
 220   gdb_assert (dest.size () == src.size ());
 221   if (dest.data () < src.data ())
 222     std::copy (src.begin (), src.end (), dest.begin ());
 223   else if (dest.data () > src.data ())
 224     std::copy_backward (src.begin (), src.end (), dest.end ());
 225 }
 226
 227 /* Compare LHS and RHS for (deep) equality.  That is, whether LHS and
 228    RHS have the same sizes, and whether each pair of elements of LHS
 229    and RHS at the same position compares equal.  */
 230
 231 template <typename T>
 232 bool
 233 operator== (const gdb::array_view<T> &lhs, const gdb::array_view<T> &rhs)
 234 {
 235   if (lhs.size () != rhs.size ())
 236     return false;
 237
 238   for (size_t i = 0; i < lhs.size (); i++)
 239     if (!(lhs[i] == rhs[i]))
 240       return false;
 241
 242   return true;
 243 }
 244
 245 /* Compare two array_views for inequality.  */
 246
 247 template <typename T>
 248 bool
 249 operator!= (const gdb::array_view<T> &lhs, const gdb::array_view<T> &rhs)
 250 {
 251   return !(lhs == rhs);
 252 }
 253
 254 /* Create an array view from a pointer to an array and an element
 255    count.
 256
 257    This is useful as alternative to constructing an array_view using
 258    brace initialization when the size variable you have handy is of
 259    signed type, since otherwise without an explicit cast the code
 260    would be ill-formed.
 261
 262    For example, with:
 263
 264      extern void foo (int, int, gdb::array_view<value *>);
 265
 266      value *args[2];
 267      int nargs;
 268      foo (1, 2, {values, nargs});
 269
 270    You'd get:
 271
 272      source.c:10: error: narrowing conversion of ‘nargs’ from ‘int’ to
 273      ‘size_t {aka long unsigned int}’ inside { } [-Werror=narrowing]
 274
 275    You could fix it by writing the somewhat distracting explicit cast:
 276
 277      foo (1, 2, {values, (size_t) nargs});
 278
 279    Or by instantiating an array_view explicitly:
 280
 281      foo (1, 2, gdb::array_view<value *>(values, nargs));
 282
 283    Or, better, using make_array_view, which has the advantage of
 284    inferring the array_view element's type:
 285
 286      foo (1, 2, gdb::make_array_view (values, nargs));
 287 */
 288
 289 template<typename U>
 290 constexpr inline array_view<U>
 291 make_array_view (U *array, size_t size) noexcept
 292 {
 293   return {array, size};
 294 }
 295
 296 } /* namespace gdb */
 297
 298 #endif