Debian Codegraph @

include/deal.II/base/ndarray.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2021 - 2023 by the deal.II authors
5 //
6 // This file is part of the deal.II library.
7 //
8 // Part of the source code is dual licensed under Apache-2.0 WITH
9 // LLVM-exception OR LGPL-2.1-or-later. Detailed license information
10 // governing the source code and code contributions can be found in
11 // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II.
12 //
13 // ------------------------------------------------------------------------
14
15 #ifndef dealii_ndarray_h
16 #define dealii_ndarray_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/exceptions.h>
21
22 #include <array>
23
24 DEAL_II_NAMESPACE_OPEN
25
26 #ifndef DOXYGEN
27 namespace internal
28 {
29 namespace ndarray
30 {
31 // clang-format off
32 /**
33 * A variadic template helper class to recursively "unroll" the size
34 * information of the ndarray. This is best explained on an example:
35 * @code
36 * HelperArray<double, 1, 2, 3, 4>::type
37 * == std::array<HelperArray<double, 2, 3, 4>::type, 1>
38 * == std::array<std::array<HelperArray<double, 3, 4>::type, 2>, 1>
39 * == std::array<std::array<std::array<HelperArray<double, 4>::type, 3>, 2>, 1>
40 * == std::array<std::array<std::array<std::array<HelperArray<double>::type, 4>, 3>, 2>, 1>
41 * == std::array<std::array<std::array<std::array<double, 4>, 3>, 2>, 1>
42 * @endcode
43 */
44 template <typename T, std::size_t... Ns>
45 struct HelperArray;
46 // clang-format on
47
48 /**
49 * Recursively define the type alias "type" of HelperArray<T, N, ...Ns>
50 * by wrapping a std::array around HelperArray<T, Ns...>::type
51 */
52 template <typename T, std::size_t N, std::size_t... Ns>
53 struct HelperArray<T, N, Ns...>
54 {
55 using type = std::array<typename HelperArray<T, Ns...>::type, N>;
56 };
57
58 /**
59 * End recursion once no std::size_t template parameters are left and
60 * simply set the type alias to type T
61 */
62 template <typename T>
63 struct HelperArray<T>
64 {
65 using type = T;
66 };
67 } // namespace ndarray
68 } // namespace internal
69 #endif // DOXYGEN
70
71 /**
72 * A (variadic template) type alias for conveniently defining multidimensional
73 * <a href="https://en.cppreference.com/w/cpp/container/array">std::array</a>s.
74 *
75 * The problem we try to address with the type alias is the following.
76 * Suppose you want to create a multdimensional array of doubles of, for
77 * example, rank 3, with sizes 2, 3, 4 for the first, middle, and last
78 * index. Then using C-style arrays you could simply write
79 * @code
80 * double my_array[2][3][4] = { ... };
81 * @endcode
82 * There are a number of good reasons why using C-style arrays is
83 * generally discouraged (ranging from incompatibilities with STL functions
84 * requiring awkward wrappers, surprises when comparing for equality, etc.).
85 * If you want to do the same, however, using the more modern (and
86 * encouraged) `std::array` class, then you would have to declare
87 * @code
88 * std::array<std::array<std::array<double, 4>, 3>, 2> = { ... };
89 * @endcode
90 * The repetitions of `std::array` look awkward and, worse, the index
91 * ranges have reversed: the leftmost index has range [0,2), the middle
92 * index has range [0,3) and the rightmost index has range [0,4).
93 * We address this issue by providing a class ndarray that allows to you
94 * declare the above stacked `std::array` type by simply writing:
95 * @code
96 * dealii::ndarray<double, 2, 3, 4> my_array = { ... };
97 * @endcode
98 *
99 * @note dealii::ndarray is merely syntactic sugar in the form of a
100 * <a href="https://en.cppreference.com/w/cpp/language/type_alias">type
101 * alias</a>
102 * (`using` declaration). It is not a deal.II specific class, but merely a
103 * helper to cleanly define multidimensional arrays realized by "stacked"
104 * `std::array` classes.
105 */
106 template <typename T, std::size_t... Ns>
107 using ndarray = typename internal::ndarray::HelperArray<T, Ns...>::type;
108
109 DEAL_II_NAMESPACE_CLOSE
110
111 #endif