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