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