libcxx/include/__mdspan/mdspan.h

   1 // -*- C++ -*-
   2 //===----------------------------------------------------------------------===//
   3 //
   4 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   5 // See https://llvm.org/LICENSE.txt for license information.
   6 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   7 //
   8 //                        Kokkos v. 4.0
   9 //       Copyright (2022) National Technology & Engineering
  10 //               Solutions of Sandia, LLC (NTESS).
  11 //
  12 // Under the terms of Contract DE-NA0003525 with NTESS,
  13 // the U.S. Government retains certain rights in this software.
  14 //
  15 //===---------------------------------------------------------------------===//
  16
  17 #ifndef _LIBCPP___MDSPAN_MDSPAN_H
  18 #define _LIBCPP___MDSPAN_MDSPAN_H
  19
  20 #include <__assert>
  21 #include <__config>
  22 #include <__fwd/mdspan.h>
  23 #include <__mdspan/default_accessor.h>
  24 #include <__mdspan/extents.h>
  25 #include <__type_traits/extent.h>
  26 #include <__type_traits/is_abstract.h>
  27 #include <__type_traits/is_array.h>
  28 #include <__type_traits/is_constructible.h>
  29 #include <__type_traits/is_convertible.h>
  30 #include <__type_traits/is_nothrow_constructible.h>
  31 #include <__type_traits/is_pointer.h>
  32 #include <__type_traits/is_same.h>
  33 #include <__type_traits/rank.h>
  34 #include <__type_traits/remove_all_extents.h>
  35 #include <__type_traits/remove_cv.h>
  36 #include <__type_traits/remove_pointer.h>
  37 #include <__type_traits/remove_reference.h>
  38 #include <__utility/integer_sequence.h>
  39 #include <array>
  40 #include <span>
  41
  42 #if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)
  43 #  pragma GCC system_header
  44 #endif
  45
  46 _LIBCPP_PUSH_MACROS
  47 #include <__undef_macros>
  48
  49 _LIBCPP_BEGIN_NAMESPACE_STD
  50
  51 #if _LIBCPP_STD_VER >= 23
  52
  53 // Helper for lightweight test checking that one did pass a layout policy as LayoutPolicy template argument
  54 namespace __mdspan_detail {
  55 template <class _Layout, class _Extents>
  56 concept __has_invalid_mapping = !requires { typename _Layout::template mapping<_Extents>; };
  57 } // namespace __mdspan_detail
  58
  59 template <class _ElementType,
  60           class _Extents,
  61           class _LayoutPolicy   = layout_right,
  62           class _AccessorPolicy = default_accessor<_ElementType> >
  63 class mdspan {
  64 private:
  65   static_assert(__mdspan_detail::__is_extents_v<_Extents>,
  66                 "mdspan: Extents template parameter must be a specialization of extents.");
  67   static_assert(!is_array_v<_ElementType>, "mdspan: ElementType template parameter may not be an array type");
  68   static_assert(!is_abstract_v<_ElementType>, "mdspan: ElementType template parameter may not be an abstract class");
  69   static_assert(is_same_v<_ElementType, typename _AccessorPolicy::element_type>,
  70                 "mdspan: ElementType template parameter must match AccessorPolicy::element_type");
  71   static_assert(!__mdspan_detail::__has_invalid_mapping<_LayoutPolicy, _Extents>,
  72                 "mdspan: LayoutPolicy template parameter is invalid. A common mistake is to pass a layout mapping "
  73                 "instead of a layout policy");
  74
  75 public:
  76   using extents_type     = _Extents;
  77   using layout_type      = _LayoutPolicy;
  78   using accessor_type    = _AccessorPolicy;
  79   using mapping_type     = typename layout_type::template mapping<extents_type>;
  80   using element_type     = _ElementType;
  81   using value_type       = remove_cv_t<element_type>;
  82   using index_type       = typename extents_type::index_type;
  83   using size_type        = typename extents_type::size_type;
  84   using rank_type        = typename extents_type::rank_type;
  85   using data_handle_type = typename accessor_type::data_handle_type;
  86   using reference        = typename accessor_type::reference;
  87
  88   _LIBCPP_HIDE_FROM_ABI static constexpr rank_type rank() noexcept { return extents_type::rank(); }
  89   _LIBCPP_HIDE_FROM_ABI static constexpr rank_type rank_dynamic() noexcept { return extents_type::rank_dynamic(); }
  90   _LIBCPP_HIDE_FROM_ABI static constexpr size_t static_extent(rank_type __r) noexcept {
  91     return extents_type::static_extent(__r);
  92   }
  93   _LIBCPP_HIDE_FROM_ABI constexpr index_type extent(rank_type __r) const noexcept {
  94     return __map_.extents().extent(__r);
  95   };
  96
  97 public:
  98   //--------------------------------------------------------------------------------
  99   // [mdspan.mdspan.cons], mdspan constructors, assignment, and destructor
 100
 101   _LIBCPP_HIDE_FROM_ABI constexpr mdspan()
 102     requires((extents_type::rank_dynamic() > 0) && is_default_constructible_v<data_handle_type> &&
 103              is_default_constructible_v<mapping_type> && is_default_constructible_v<accessor_type>)
 104   = default;
 105   _LIBCPP_HIDE_FROM_ABI constexpr mdspan(const mdspan&) = default;
 106   _LIBCPP_HIDE_FROM_ABI constexpr mdspan(mdspan&&)      = default;
 107
 108   template <class... _OtherIndexTypes>
 109     requires((is_convertible_v<_OtherIndexTypes, index_type> && ...) &&
 110              (is_nothrow_constructible_v<index_type, _OtherIndexTypes> && ...) &&
 111              ((sizeof...(_OtherIndexTypes) == rank()) || (sizeof...(_OtherIndexTypes) == rank_dynamic())) &&
 112              is_constructible_v<mapping_type, extents_type> && is_default_constructible_v<accessor_type>)
 113   _LIBCPP_HIDE_FROM_ABI explicit constexpr mdspan(data_handle_type __p, _OtherIndexTypes... __exts)
 114       : __ptr_(std::move(__p)), __map_(extents_type(static_cast<index_type>(std::move(__exts))...)), __acc_{} {}
 115
 116   template <class _OtherIndexType, size_t _Size>
 117     requires(is_convertible_v<const _OtherIndexType&, index_type> &&
 118              is_nothrow_constructible_v<index_type, const _OtherIndexType&> &&
 119              ((_Size == rank()) || (_Size == rank_dynamic())) && is_constructible_v<mapping_type, extents_type> &&
 120              is_default_constructible_v<accessor_type>)
 121   explicit(_Size != rank_dynamic())
 122       _LIBCPP_HIDE_FROM_ABI constexpr mdspan(data_handle_type __p, const array<_OtherIndexType, _Size>& __exts)
 123       : __ptr_(std::move(__p)), __map_(extents_type(__exts)), __acc_{} {}
 124
 125   template <class _OtherIndexType, size_t _Size>
 126     requires(is_convertible_v<const _OtherIndexType&, index_type> &&
 127              is_nothrow_constructible_v<index_type, const _OtherIndexType&> &&
 128              ((_Size == rank()) || (_Size == rank_dynamic())) && is_constructible_v<mapping_type, extents_type> &&
 129              is_default_constructible_v<accessor_type>)
 130   explicit(_Size != rank_dynamic())
 131       _LIBCPP_HIDE_FROM_ABI constexpr mdspan(data_handle_type __p, span<_OtherIndexType, _Size> __exts)
 132       : __ptr_(std::move(__p)), __map_(extents_type(__exts)), __acc_{} {}
 133
 134   _LIBCPP_HIDE_FROM_ABI constexpr mdspan(data_handle_type __p, const extents_type& __exts)
 135     requires(is_default_constructible_v<accessor_type> && is_constructible_v<mapping_type, const extents_type&>)
 136       : __ptr_(std::move(__p)), __map_(__exts), __acc_{} {}
 137
 138   _LIBCPP_HIDE_FROM_ABI constexpr mdspan(data_handle_type __p, const mapping_type& __m)
 139     requires(is_default_constructible_v<accessor_type>)
 140       : __ptr_(std::move(__p)), __map_(__m), __acc_{} {}
 141
 142   _LIBCPP_HIDE_FROM_ABI constexpr mdspan(data_handle_type __p, const mapping_type& __m, const accessor_type& __a)
 143       : __ptr_(std::move(__p)), __map_(__m), __acc_(__a) {}
 144
 145   template <class _OtherElementType, class _OtherExtents, class _OtherLayoutPolicy, class _OtherAccessor>
 146     requires(is_constructible_v<mapping_type, const typename _OtherLayoutPolicy::template mapping<_OtherExtents>&> &&
 147              is_constructible_v<accessor_type, const _OtherAccessor&>)
 148   explicit(!is_convertible_v<const typename _OtherLayoutPolicy::template mapping<_OtherExtents>&, mapping_type> ||
 149            !is_convertible_v<const _OtherAccessor&, accessor_type>)
 150       _LIBCPP_HIDE_FROM_ABI constexpr mdspan(
 151           const mdspan<_OtherElementType, _OtherExtents, _OtherLayoutPolicy, _OtherAccessor>& __other)
 152       : __ptr_(__other.__ptr_), __map_(__other.__map_), __acc_(__other.__acc_) {
 153     static_assert(is_constructible_v<data_handle_type, const typename _OtherAccessor::data_handle_type&>,
 154                   "mdspan: incompatible data_handle_type for mdspan construction");
 155     static_assert(
 156         is_constructible_v<extents_type, _OtherExtents>, "mdspan: incompatible extents for mdspan construction");
 157
 158     // The following precondition is part of the standard, but is unlikely to be triggered.
 159     // The extents constructor checks this and the mapping must be storing the extents, since
 160     // its extents() function returns a const reference to extents_type.
 161     // The only way this can be triggered is if the mapping conversion constructor would for example
 162     // always construct its extents() only from the dynamic extents, instead of from the other extents.
 163     if constexpr (rank() > 0) {
 164       for (size_t __r = 0; __r < rank(); __r++) {
 165         // Not catching this could lead to out of bounds errors later
 166         // e.g. mdspan<int, dextents<char,1>, non_checking_layout> m =
 167         //        mdspan<int, dextents<unsigned, 1>, non_checking_layout>(ptr, 200); leads to an extent of -56 on m
 168         _LIBCPP_ASSERT_VALID_ELEMENT_ACCESS(
 169             (static_extent(__r) == dynamic_extent) ||
 170                 (static_cast<index_type>(__other.extent(__r)) == static_cast<index_type>(static_extent(__r))),
 171             "mdspan: conversion mismatch of source dynamic extents with static extents");
 172       }
 173     }
 174   }
 175
 176   _LIBCPP_HIDE_FROM_ABI constexpr mdspan& operator=(const mdspan&) = default;
 177   _LIBCPP_HIDE_FROM_ABI constexpr mdspan& operator=(mdspan&&)      = default;
 178
 179   //--------------------------------------------------------------------------------
 180   // [mdspan.mdspan.members], members
 181
 182   template <class... _OtherIndexTypes>
 183     requires((is_convertible_v<_OtherIndexTypes, index_type> && ...) &&
 184              (is_nothrow_constructible_v<index_type, _OtherIndexTypes> && ...) &&
 185              (sizeof...(_OtherIndexTypes) == rank()))
 186   _LIBCPP_HIDE_FROM_ABI constexpr reference operator[](_OtherIndexTypes... __indices) const {
 187     // Note the standard layouts would also check this, but user provided ones may not, so we
 188     // check the precondition here
 189     _LIBCPP_ASSERT_VALID_ELEMENT_ACCESS(__mdspan_detail::__is_multidimensional_index_in(extents(), __indices...),
 190                                         "mdspan: operator[] out of bounds access");
 191     return __acc_.access(__ptr_, __map_(static_cast<index_type>(std::move(__indices))...));
 192   }
 193
 194   template <class _OtherIndexType>
 195     requires(is_convertible_v<const _OtherIndexType&, index_type> &&
 196              is_nothrow_constructible_v<index_type, const _OtherIndexType&>)
 197   _LIBCPP_HIDE_FROM_ABI constexpr reference operator[](const array< _OtherIndexType, rank()>& __indices) const {
 198     return __acc_.access(__ptr_, [&]<size_t... _Idxs>(index_sequence<_Idxs...>) {
 199       return __map_(__indices[_Idxs]...);
 200     }(make_index_sequence<rank()>()));
 201   }
 202
 203   template <class _OtherIndexType>
 204     requires(is_convertible_v<const _OtherIndexType&, index_type> &&
 205              is_nothrow_constructible_v<index_type, const _OtherIndexType&>)
 206   _LIBCPP_HIDE_FROM_ABI constexpr reference operator[](span<_OtherIndexType, rank()> __indices) const {
 207     return __acc_.access(__ptr_, [&]<size_t... _Idxs>(index_sequence<_Idxs...>) {
 208       return __map_(__indices[_Idxs]...);
 209     }(make_index_sequence<rank()>()));
 210   }
 211
 212   _LIBCPP_HIDE_FROM_ABI constexpr size_type size() const noexcept {
 213     // Could leave this as only checked in debug mode: semantically size() is never
 214     // guaranteed to be related to any accessible range
 215     _LIBCPP_ASSERT_UNCATEGORIZED(
 216         false == ([&]<size_t... _Idxs>(index_sequence<_Idxs...>) {
 217           size_type __prod = 1;
 218           return (__builtin_mul_overflow(__prod, extent(_Idxs), &__prod) || ... || false);
 219         }(make_index_sequence<rank()>())),
 220         "mdspan: size() is not representable as size_type");
 221     return [&]<size_t... _Idxs>(index_sequence<_Idxs...>) {
 222       return ((static_cast<size_type>(__map_.extents().extent(_Idxs))) * ... * size_type(1));
 223     }(make_index_sequence<rank()>());
 224   }
 225
 226   [[nodiscard]] _LIBCPP_HIDE_FROM_ABI constexpr bool empty() const noexcept {
 227     return [&]<size_t... _Idxs>(index_sequence<_Idxs...>) {
 228       return (rank() > 0) && ((__map_.extents().extent(_Idxs) == index_type(0)) || ... || false);
 229     }(make_index_sequence<rank()>());
 230   }
 231
 232   _LIBCPP_HIDE_FROM_ABI friend constexpr void swap(mdspan& __x, mdspan& __y) noexcept {
 233     swap(__x.__ptr_, __y.__ptr_);
 234     swap(__x.__map_, __y.__map_);
 235     swap(__x.__acc_, __y.__acc_);
 236   }
 237
 238   _LIBCPP_HIDE_FROM_ABI constexpr const extents_type& extents() const noexcept { return __map_.extents(); };
 239   _LIBCPP_HIDE_FROM_ABI constexpr const data_handle_type& data_handle() const noexcept { return __ptr_; };
 240   _LIBCPP_HIDE_FROM_ABI constexpr const mapping_type& mapping() const noexcept { return __map_; };
 241   _LIBCPP_HIDE_FROM_ABI constexpr const accessor_type& accessor() const noexcept { return __acc_; };
 242
 243   // per LWG-4021 "mdspan::is_always_meow() should be noexcept"
 244   _LIBCPP_HIDE_FROM_ABI static constexpr bool is_always_unique() noexcept { return mapping_type::is_always_unique(); };
 245   _LIBCPP_HIDE_FROM_ABI static constexpr bool is_always_exhaustive() noexcept {
 246     return mapping_type::is_always_exhaustive();
 247   };
 248   _LIBCPP_HIDE_FROM_ABI static constexpr bool is_always_strided() noexcept {
 249     return mapping_type::is_always_strided();
 250   };
 251
 252   _LIBCPP_HIDE_FROM_ABI constexpr bool is_unique() const { return __map_.is_unique(); };
 253   _LIBCPP_HIDE_FROM_ABI constexpr bool is_exhaustive() const { return __map_.is_exhaustive(); };
 254   _LIBCPP_HIDE_FROM_ABI constexpr bool is_strided() const { return __map_.is_strided(); };
 255   _LIBCPP_HIDE_FROM_ABI constexpr index_type stride(rank_type __r) const { return __map_.stride(__r); };
 256
 257 private:
 258   _LIBCPP_NO_UNIQUE_ADDRESS data_handle_type __ptr_{};
 259   _LIBCPP_NO_UNIQUE_ADDRESS mapping_type __map_{};
 260   _LIBCPP_NO_UNIQUE_ADDRESS accessor_type __acc_{};
 261
 262   template <class, class, class, class>
 263   friend class mdspan;
 264 };
 265
 266 #  if _LIBCPP_STD_VER >= 26
 267 template <class _ElementType, class... _OtherIndexTypes>
 268   requires((is_convertible_v<_OtherIndexTypes, size_t> && ...) && (sizeof...(_OtherIndexTypes) > 0))
 269 explicit mdspan(_ElementType*,
 270                 _OtherIndexTypes...) -> mdspan<_ElementType, extents<size_t, __maybe_static_ext<_OtherIndexTypes>...>>;
 271 #  else
 272 template <class _ElementType, class... _OtherIndexTypes>
 273   requires((is_convertible_v<_OtherIndexTypes, size_t> && ...) && (sizeof...(_OtherIndexTypes) > 0))
 274 explicit mdspan(_ElementType*,
 275                 _OtherIndexTypes...) -> mdspan<_ElementType, dextents<size_t, sizeof...(_OtherIndexTypes)>>;
 276 #  endif
 277
 278 template <class _Pointer>
 279   requires(is_pointer_v<remove_reference_t<_Pointer>>)
 280 mdspan(_Pointer&&) -> mdspan<remove_pointer_t<remove_reference_t<_Pointer>>, extents<size_t>>;
 281
 282 template <class _CArray>
 283   requires(is_array_v<_CArray> && (rank_v<_CArray> == 1))
 284 mdspan(_CArray&) -> mdspan<remove_all_extents_t<_CArray>, extents<size_t, extent_v<_CArray, 0>>>;
 285
 286 template <class _ElementType, class _OtherIndexType, size_t _Size>
 287 mdspan(_ElementType*, const array<_OtherIndexType, _Size>&) -> mdspan<_ElementType, dextents<size_t, _Size>>;
 288
 289 template <class _ElementType, class _OtherIndexType, size_t _Size>
 290 mdspan(_ElementType*, span<_OtherIndexType, _Size>) -> mdspan<_ElementType, dextents<size_t, _Size>>;
 291
 292 // This one is necessary because all the constructors take `data_handle_type`s, not
 293 // `_ElementType*`s, and `data_handle_type` is taken from `accessor_type::data_handle_type`, which
 294 // seems to throw off automatic deduction guides.
 295 template <class _ElementType, class _OtherIndexType, size_t... _ExtentsPack>
 296 mdspan(_ElementType*, const extents<_OtherIndexType, _ExtentsPack...>&)
 297     -> mdspan<_ElementType, extents<_OtherIndexType, _ExtentsPack...>>;
 298
 299 template <class _ElementType, class _MappingType>
 300 mdspan(_ElementType*, const _MappingType&)
 301     -> mdspan<_ElementType, typename _MappingType::extents_type, typename _MappingType::layout_type>;
 302
 303 template <class _MappingType, class _AccessorType>
 304 mdspan(const typename _AccessorType::data_handle_type, const _MappingType&, const _AccessorType&)
 305     -> mdspan<typename _AccessorType::element_type,
 306               typename _MappingType::extents_type,
 307               typename _MappingType::layout_type,
 308               _AccessorType>;
 309
 310 #endif // _LIBCPP_STD_VER >= 23
 311
 312 _LIBCPP_END_NAMESPACE_STD
 313
 314 _LIBCPP_POP_MACROS
 315
 316 #endif // _LIBCPP___MDSPAN_MDSPAN_H