// ------------------------------------------------------------------------ // // SPDX-License-Identifier: LGPL-2.1-or-later // Copyright (C) 2015 - 2025 by the deal.II authors // // This file is part of the deal.II library. // // Part of the source code is dual licensed under Apache-2.0 WITH // LLVM-exception OR LGPL-2.1-or-later. Detailed license information // governing the source code and code contributions can be found in // LICENSE.md and CONTRIBUTING.md at the top level directory of deal.II. // // ------------------------------------------------------------------------ #ifndef dealii_array_view_h #define dealii_array_view_h #include #include #include #include #include #include #include #include #include #include DEAL_II_NAMESPACE_OPEN // Forward declaration template class AlignedVector; template class Table; template class LAPACKFullMatrix; /** * A class that represents a window of memory locations of type @p ElementType * and presents it as if it was an array. In essence, this class is nothing more * than just a pointer to the first location and an integer that represents the * length of the array in elements. The memory remains owned by whoever * allocated it, as this class does not take over ownership. * * The advantage of using this class is that you don't have to pass around * pairs of pointers and that operator[] checks for the validity * of the index with which you subscript this array view. Note that accessing * elements is only allowed if the underlying data is stored in CPU memory. * * This class can handle views to both non-constant and constant memory * locations. If you want to represent a view of a constant array, then the * template argument type of this class needs to be @p const as well. The * following code snippet gives an example: * @code * std::vector array = get_data(); // a writable array * ArrayView view (&array[5], 5); // a view of elements 5..9 (inclusive) * view[2] = 42; // array[7] is set to 42 * ArrayView const_view (&array[5], 5); // same view, but read-only * int element_7 = const_view[2]; // set element_7 to 42 * const_view[2] = 42; // this line won't compile; can't write into this view * @endcode * In either case, accessing an element of a view does not change the * ArrayView object itself, and consequently ArrayView::operator[] is a @p * const function. This corresponds to the notion that a view simply * represents a, well, "view" of memory that is owned by someone else. Thus, * accessing elements of the view changes the memory managed by some other * object, but not the view itself, allowing us to make ArrayView::operator[] * a @p const member function. This is in contrast to, say, std::vector, which * manages the memory it points to and changing an element of the std::vector * therefore changes the std::vector object itself -- consequently, the * std::vector::operator[] is non-@p const. * * @note This class is similar to * [`std::span`](https://en.cppreference.com/w/cpp/container/span), but the * latter is only available starting in C++20. * * @ingroup data */ template class ArrayView { public: /** * An alias that denotes the "value_type" of this container-like class, * i.e., the type of the element it "stores" or points to. */ using value_type = ElementType; /** * An alias for iterators pointing into the array. */ using iterator = value_type *; /** * An alias for const iterators pointing into the array. */ using const_iterator = const ElementType *; /** * Default constructor. */ ArrayView(); /** * Constructor. * * @param[in] starting_element A pointer to the first element of the array * this object should represent. The value of this argument is only evaluated * if `n_elements` is larger than zero. Otherwise, the value of this * argument is ignored as if the ArrayView object used a `nullptr` * to point to the first element of the array. * @param[in] n_elements The length (in elements) of the chunk of memory * this object should represent. * * @note The object that is constructed from these arguments has no * knowledge how large the object into which it points really is. As a * consequence, whenever you call ArrayView::operator[], the array view can * check that the given index is within the range of the view, but it can't * check that the view is indeed a subset of the valid range of elements of * the underlying object that allocated that range. In other words, you need * to ensure that the range of the view specified by the two arguments to * this constructor is in fact a subset of the elements of the array into * which it points. The appropriate way to do this is to use the * make_array_view() functions. */ ArrayView(value_type *starting_element, const std::size_t n_elements); /** * Copy constructor from array views that point to non-@p const elements. If * the current object will point to non-@p const elements, then this is a * straight forward copy constructor. On the other hand, if the current * type's @p ElementType template argument is a @p const qualified type, * then the current constructor is a conversion constructor that converts a * non-@p const view to a @p const view, akin to converting a non-@p const * pointer to a @p const pointer. */ ArrayView( const ArrayView, MemorySpaceType> &view); /** * A constructor that automatically creates a view from a single value_type * object. The view so created then has length one. */ explicit ArrayView(value_type &element); #ifdef DEAL_II_HAVE_CXX20 /** * A constructor that automatically creates a view from a container * object that requires a contiguous array of elements (such as * `std::vector`, `std::array`, `boost::container::small_vector`, * and the like). The view encompasses all elements of the given * container. * * This implicit conversion constructor is particularly useful when calling * a function that takes an ArrayView object as argument, and passing in * a container. * * @note This constructor takes a reference to a @p const container as argument. * It can only be used to initialize ArrayView objects that point to * @p const memory locations, such as ArrayView@. * You cannot initialize ArrayView objects to non-@p const memory with * such arguments, such as ArrayView@. */ template ArrayView(const ContiguousContainer &container) requires(std::is_same_v< std::remove_cv_t, std::remove_cv_t> && std::is_const_v && concepts::is_contiguous_container); /** * A constructor that automatically creates a view from a container * object that requires a contiguous array of elements (such as * `std::vector`, `std::array`, `boost::container::small_vector`, * and the like). The view encompasses all elements of the given * container. * * This implicit conversion constructor is particularly useful when calling * a function that takes an ArrayView object as argument, and passing in * a container. * * @note This constructor takes a reference to a non-@p const container as * argument. It can be used to initialize ArrayView objects that point to * either @p const memory locations, such as * ArrayView@, or to non-@p const memory, * such as ArrayView@. */ template ArrayView(ContiguousContainer &container) requires(std::is_same_v< std::remove_cv_t, std::remove_cv_t> && concepts::is_contiguous_container); #else /** * A constructor that automatically creates a view from a container * object that requires a contiguous array of elements (such as * `std::vector`, `std::array`, `boost::container::small_vector`, * and the like). The view encompasses all elements of the given * container. * * This implicit conversion constructor is particularly useful when calling * a function that takes an ArrayView object as argument, and passing in * a container. * * @note This constructor takes a reference to a @p const container as argument. * It can only be used to initialize ArrayView objects that point to * @p const memory locations, such as ArrayView@. * You cannot initialize ArrayView objects to non-@p const memory with * such arguments, such as ArrayView@. */ template ())), typename = decltype(std::size(std::declval())), typename = std::enable_if_t< std::is_same_v< std::remove_cv_t, std::remove_cv_t> && std::is_const_v>> ArrayView(const ContiguousContainer &container); /** * A constructor that automatically creates a view from a container * object that requires a contiguous array of elements (such as * `std::vector`, `std::array`, `boost::container::small_vector`, * and the like). The view encompasses all elements of the given * container. * * This implicit conversion constructor is particularly useful when calling * a function that takes an ArrayView object as argument, and passing in * a container. * * @note This constructor takes a reference to a non-@p const container as * argument. It can be used to initialize ArrayView objects that point to * either @p const memory locations, such as * ArrayView@, or to non-@p const memory, * such as ArrayView@. */ template ())), typename = decltype(std::size(std::declval())), typename = std::enable_if_t, std::remove_cv_t>>> ArrayView(ContiguousContainer &container); #endif /** * A constructor that automatically creates a view for a given C-style array. * This constructor can be used as follows: * @code * ArrayView * get_data_table () * { * static const int my_data[7] = { 1, 1, 2, 3, 5, 8, 13 }; * return {my_data}; * } * @endcode * The object so returned is then a view of the array, with the size 7 * correctly deduced. */ template ArrayView(value_type (&array)[N]); /** * A constructor that creates a view of the array that underlies a * [std::initializer_list](https://en.cppreference.com/w/cpp/utility/initializer_list). * This constructor allows for cases such as where one has a function * that takes an ArrayView object: * @code * void f(const ArrayView &a); * @endcode * and then to call this function with a list of integers: * @code * f({1,2,3}); * @endcode * This also works with an empty list: * @code * f({}); * @encode * * @note This constructor only works if the template type is `const` * qualified. That is, you can initialize an `ArrayView` * object from a `std::initializer_list`, but not an * `ArrayView` object. This is because the elements of initializer * lists are `const`. * * @note `std::initializer_list` objects are temporary. They are constructed * where the compiler finds a brace-enclosed list, and so they only live * for at most the time it takes to execute the current statement. As a * consequence, creating an ArrayView object of such a `std::initializer_list` * also results in a view object that points to valid memory only for as long * as the current statement is executed. You shouldn't expect that the * resulting ArrayView can be used to point to useful memory content past * that point. In other words, while this code... * @code * std::vector v(10); * ArrayView a(v); * f(a); * @endcode * ...works because the array `v` pointed to exists until after the call to * `f()`, the following code will not likely work as expected: * @code * ArrayView a({1,2,3}); * f(a); * @endcode */ ArrayView( const std::initializer_list> &initializer_list) DEAL_II_CXX20_REQUIRES(std::is_const_v); /** * Reinitialize a view. * * @param[in] starting_element A pointer to the first element of the array * this object should represent. * @param[in] n_elements The length (in elements) of the chunk of memory * this object should represent. * * @note The object that is constructed from these arguments has no * knowledge how large the object into which it points really is. As a * consequence, whenever you call ArrayView::operator[], the array view can * check that the given index is within the range of the view, but it can't * check that the view is indeed a subset of the valid range of elements of * the underlying object that allocated that range. In other words, you need * to ensure that the range of the view specified by the two arguments to * this constructor is in fact a subset of the elements of the array into * which it points. The appropriate way to do this is to use the * make_array_view() functions. */ void reinit(value_type *starting_element, const std::size_t n_elements); /** * Compare two ArrayView objects of the same type. Two objects are considered * equal if they have the same size and the same starting pointer. * * Note that this means that the operation tests that the *views* are the * same. If they are, then of course the elements represented by the view * are also the same. But the converse is not true: Two ArrayView objects * may point to different parts of the memory space and in that case the * comparison for equality will return `false` even if the *elements* the * views point to are the same. * * This version always compares with the const value_type. */ bool operator==( const ArrayView &other_view) const; /** * Compare two ArrayView objects of the same type. Two objects are considered * equal if they have the same size and the same starting pointer. * * Note that this means that the operation tests that the *views* are the * same. If they are, then of course the elements represented by the view * are also the same. But the converse is not true: Two ArrayView objects * may point to different parts of the memory space and in that case the * comparison for equality will return `false` even if the *elements* the * views point to are the same. * * This version always compares with the non-const value_type. */ bool operator==(const ArrayView, MemorySpaceType> &other_view) const; /** * Compare two ArrayView objects of the same type. Two objects are considered * equal if they have the same size and the same starting pointer, and the * current operation therefore returns `true` if the two views being compared * point to different memory locations, or if they point to the same memory * location but represent different sizes. * * Note that this means that the operation tests that the *views* are the * not the same. But this does not mean that the elements pointed to by * the view are not equal: Two ArrayView objects * may point to different parts of the memory space and in that case the * comparison for inequality will return `true` even if the *elements* the * views point to are the same. * * This version always compares with the const value_type. */ bool operator!=( const ArrayView &other_view) const; /** * Compare two ArrayView objects of the same type. Two objects are considered * equal if they have the same size and the same starting pointer. * * Note that this means that the operation tests that the *views* are the * not the same. But this does not mean that the elements pointed to by * the view are not equal: Two ArrayView objects * may point to different parts of the memory space and in that case the * comparison for inequality will return `true` even if the *elements* the * views point to are the same. * * This version always compares with the non-const value_type. */ bool operator!=(const ArrayView, MemorySpaceType> &other_view) const; /** * Return the size (in elements) of the view of memory this object * represents. */ std::size_t size() const; /** * Return a bool whether the array view is empty. */ bool empty() const; /** * Return a pointer to the underlying array serving as element storage. * In case the container is empty a nullptr is returned. */ DEAL_II_HOST_DEVICE value_type * data() const noexcept; /** * Return an iterator pointing to the beginning of the array view. */ iterator begin() const; /** * Return an iterator pointing to one past the end of the array view. */ iterator end() const; /** * Return a constant iterator pointing to the beginning of the array view. */ const_iterator cbegin() const; /** * Return a constant iterator pointing to one past the end of the array view. */ const_iterator cend() const; /** * Return a reference to the $i$th element of the range represented by the * current object. * * This function is marked as @p const because it does not change the * view object. It may however return a reference to a non-@p const * memory location depending on whether the template type of the class is @p * const or not. * * This function is only allowed to be called if the underlying data is indeed * stored in CPU memory. */ value_type & operator[](const std::size_t i) const; private: /** * A pointer to the first element of the range of locations in memory that * this object represents. */ value_type *starting_element; /** * The length of the array this object represents. */ std::size_t n_elements; friend class ArrayView; }; //--------------------------------------------------------------------------- template inline ArrayView::ArrayView() : starting_element(nullptr) , n_elements(0) {} template inline ArrayView::ArrayView( value_type *starting_element, const std::size_t n_elements) : // In debug mode, make sure that n_elements>0 and if it is not, set // the pointer to a nullptr to trigger segfaults if anyone ever wanted // to access elements of the array. In release mode, just take the // pointer as given. starting_element((library_build_mode == LibraryBuildMode::release) || (n_elements > 0) ? starting_element : nullptr) , n_elements(n_elements) {} template inline void ArrayView::reinit(value_type *starting_element, const std::size_t n_elements) { if constexpr (running_in_debug_mode()) { if (n_elements > 0) this->starting_element = starting_element; else this->starting_element = nullptr; } else { this->starting_element = starting_element; } this->n_elements = n_elements; } template inline ArrayView::ArrayView(ElementType &element) : starting_element(&element) , n_elements(1) {} template inline ArrayView::ArrayView( const ArrayView, MemorySpaceType> &view) : starting_element(view.starting_element) , n_elements(view.n_elements) {} #ifdef DEAL_II_HAVE_CXX20 template template inline ArrayView::ArrayView( const ContiguousContainer &container) requires(std::is_same_v< std::remove_cv_t, std::remove_cv_t> && std::is_const_v && concepts::is_contiguous_container) : // use delegating constructor ArrayView(container.data(), container.size()) {} template template inline ArrayView::ArrayView( ContiguousContainer &container) requires(std::is_same_v< std::remove_cv_t, std::remove_cv_t> && concepts::is_contiguous_container) : // use delegating constructor ArrayView(std::data(container), std::size(container)) {} #else template template inline ArrayView::ArrayView( const ContiguousContainer &container) : // use delegating constructor ArrayView(container.data(), container.size()) {} template template inline ArrayView::ArrayView( ContiguousContainer &container) : // use delegating constructor ArrayView(std::data(container), std::size(container)) {} #endif template template inline ArrayView::ArrayView( ElementType (&array)[N]) : ArrayView(&array[0], N) {} template inline ArrayView::ArrayView( const std::initializer_list> &initializer) DEAL_II_CXX20_REQUIRES(std::is_const_v) : // use delegating constructor ArrayView(initializer.begin(), initializer.size()) {} template inline bool ArrayView::operator==( const ArrayView &other_view) const { return (other_view.data() == starting_element) && (other_view.size() == n_elements); } template inline bool ArrayView::operator==( const ArrayView, MemorySpaceType> &other_view) const { return (other_view.data() == starting_element) && (other_view.size() == n_elements); } template inline bool ArrayView::operator!=( const ArrayView &other_view) const { return !(*this == other_view); } template inline DEAL_II_HOST_DEVICE typename ArrayView::value_type * ArrayView::data() const noexcept { if (n_elements == 0) return nullptr; else return starting_element; } template inline bool ArrayView::operator!=( const ArrayView, MemorySpaceType> &other_view) const { return !(*this == other_view); } template inline std::size_t ArrayView::size() const { return n_elements; } template inline bool ArrayView::empty() const { return n_elements == 0; } template inline typename ArrayView::iterator ArrayView::begin() const { return starting_element; } template inline typename ArrayView::iterator ArrayView::end() const { return starting_element + n_elements; } template inline typename ArrayView::const_iterator ArrayView::cbegin() const { return starting_element; } template inline typename ArrayView::const_iterator ArrayView::cend() const { return starting_element + n_elements; } template inline typename ArrayView::value_type & ArrayView::operator[](const std::size_t i) const { AssertIndexRange(i, n_elements); return *(starting_element + i); } /** * A variation of @p ArrayView which allows strided access into the view. * This is particularly useful when you want to access only one lane of a * VectorizedArray. */ template class StridedArrayView { public: /** * An alias that denotes the "value_type" of this container-like class, * i.e., the type of the element it "stores" or points to. */ using value_type = ElementType; /** * Constructor. * * @param[in] starting_element A pointer to the first element of the array * this object should represent. * @param[in] n_elements The length (in elements) of the chunk of memory * this object should represent. * * @note The object that is constructed from these arguments has no * knowledge how large the object into which it points really is. As a * consequence, whenever you call ArrayView::operator[], the array view can * check that the given index is within the range of the view, but it can't * check that the view is indeed a subset of the valid range of elements of * the underlying object that allocated that range. In other words, you need * to ensure that the range of the view specified by the two arguments to * this constructor is in fact a subset of the elements of the array into * which it points. The appropriate way to do this is to use the * make_array_view() functions. */ StridedArrayView(value_type *starting_element, const std::size_t n_elements); /** * Return the size (in elements) of the view of memory this object * represents. */ std::size_t size() const; /** * Return a bool whether the array view is empty. */ bool empty() const; /** * Return a pointer to the underlying array serving as element storage. * In case the container is empty a nullptr is returned. */ value_type * data() const noexcept; /** * Return a reference to the $i$th element of the range represented by the * current object. * * This function is marked as @p const because it does not change the * view object. It may however return a reference to a non-@p const * memory location depending on whether the template type of the class is @p * const or not. * * This function is only allowed to be called if the underlying data is indeed * stored in CPU memory. */ value_type & operator[](const std::size_t i) const; protected: /** * A pointer to the first element of the range of locations in memory that * this object represents. */ value_type *starting_element; /** * The length of the array this object represents. */ std::size_t n_elements; }; template typename StridedArrayView::value_type & StridedArrayView::operator[](const std::size_t i) const { AssertIndexRange(i, this->n_elements); return *(this->starting_element + stride * i); } template typename StridedArrayView::value_type * StridedArrayView::data() const noexcept { if (this->n_elements == 0) return nullptr; else return this->starting_element; } template bool StridedArrayView::empty() const { return this->n_elements == 0; } template std::size_t StridedArrayView::size() const { return this->n_elements; } template StridedArrayView::StridedArrayView( value_type *starting_element, const std::size_t n_elements) : starting_element(starting_element) , n_elements(n_elements) {} #ifndef DOXYGEN namespace internal { namespace ArrayViewHelper { /** * Return whether the objects one gets by dereferencing the * iterators within the given iterator range form a contiguous * range in memory. */ template bool is_contiguous(const Iterator &first, const Iterator &last) { const auto n = std::distance(first, last); for (std::decay_t i = 0; i < n; ++i) if (std::addressof(*(std::next(first, i))) != std::next(std::addressof(*first), i)) return false; return true; } /** * Return whether the objects one gets by dereferencing the * iterators within the given iterator range form a contiguous * range in memory. * * This specialization for (@p const or non-@p const) pointers * returns @p true unconditionally since the fact that objects * pointed to by pointers are contiguous is embedded in the memory * model of C++. */ template constexpr bool is_contiguous(T *, T *) { return true; } } // namespace ArrayViewHelper } // namespace internal #endif /** * Create an ArrayView that takes a pair of iterators as arguments. The type * of the ArrayView is inferred from the value type of the iterator (e.g., the * view created from two const iterators will have a const type). * * @warning The iterators @p begin and @p end must bound (in the usual half-open * way) a contiguous in memory range of values. This function is intended for * use with iterators into containers like * boost::container::small_vector or std::vector and * will not work correctly with, e.g., * boost::container::stable_vector or std::deque. * In debug mode, we check that the provided iterators represent contiguous * memory indeed. * * @relatesalso ArrayView */ template ArrayView< std::remove_reference_t::reference>, MemorySpaceType> make_array_view(const Iterator begin, const Iterator end) { static_assert( std::is_same_v::iterator_category, typename std::random_access_iterator_tag> #ifdef DEAL_II_HAVE_CXX20 || std::is_same_v::iterator_category, typename std::contiguous_iterator_tag> #endif , "The provided iterator needs to be a random access iterator."); Assert(begin <= end, ExcMessage( "The beginning of the array view needs to be before the end.")); Assert(internal::ArrayViewHelper::is_contiguous(begin, end), ExcMessage("The provided range isn't contiguous in memory!")); // the reference type, not the value type, knows the constness of the iterator return ArrayView< std::remove_reference_t::reference>, MemorySpaceType>(std::addressof(*begin), end - begin); } /** * Create a view from a pair of pointers. ElementType may be * const-qualified. * * @warning The pointers @p begin and @p end must bound (in the usual * half-open way) a contiguous in memory range of values. * * @relatesalso ArrayView */ template ArrayView make_array_view(ElementType *const begin, ElementType *const end) { Assert(begin <= end, ExcMessage( "The beginning of the array view needs to be before the end.")); return ArrayView(begin, end - begin); } /** * Create a view from an ArrayView itself. * * This function is used for @p const references to objects of ArrayView type. * It only exists for compatibility purposes. * * @param[in] array_view The ArrayView that we wish to make a copy of. * * @relatesalso ArrayView */ template inline ArrayView make_array_view(const ArrayView &array_view) { return make_array_view(array_view.cbegin(), array_view.cend()); } /** * Create a view from an ArrayView itself. * * This function is used for non-@p const references to objects of ArrayView * type. It only exists for compatibility purposes. * * @param[in] array_view The ArrayView that we wish to make a copy of. * * @relatesalso ArrayView */ template inline ArrayView make_array_view(ArrayView &array_view) { return make_array_view(array_view.begin(), array_view.end()); } /** * Create a view to an entire C-style array. This is equivalent to * initializing an ArrayView object with a pointer to the first element and * the size of the given argument. * * Whether the resulting ArrayView is writable or not depends on the * ElementType being a const type or not. * * @param[in] array The C-style array for which we want to have an ArrayView * object. The ArrayView corresponds to the entire vector. * * @relatesalso ArrayView */ template inline ArrayView make_array_view(ElementType (&array)[N]) { return ArrayView(array, N); } /** * Create a view to an entire Vector object. This is equivalent to * initializing an ArrayView object with a pointer to the first element and * the size of the given argument. * * This function is used for non-@p const references to objects of Vector * type. Such objects contain elements that can be written to. Consequently, * the return type of this function is a view to a set of writable objects. * * @param[in] vector The Vector for which we want to have an array view * object. The array view corresponds to the entire Vector. * * @relatesalso ArrayView */ template inline ArrayView make_array_view(Vector &vector) { return ArrayView(vector.begin(), vector.size()); } /** * Create a view to an entire Vector object. This is equivalent to * initializing an ArrayView object with a pointer to the first element and * the size of the given argument. * * This function is used for @p const references to objects of Vector type * because they contain immutable elements. Consequently, the return type of * this function is a view to a set of @p const objects. * * @param[in] vector The Vector for which we want to have an array view * object. The array view corresponds to the entire Vector. * * @relatesalso ArrayView */ template inline ArrayView make_array_view(const Vector &vector) { return ArrayView(vector.begin(), vector.size()); } /** * Create a view to an entire std::vector object. This is equivalent to * initializing an ArrayView object with a pointer to the first element and * the size of the given argument. * * This function is used for non-@p const references to objects of vector * type. Such objects contain elements that can be written to. Consequently, * the return type of this function is a view to a set of writable objects. * * @param[in] vector The vector for which we want to have an array view * object. The array view corresponds to the entire vector. * * @relatesalso ArrayView */ template inline ArrayView make_array_view(std::vector &vector) { return ArrayView(vector.data(), vector.size()); } /** * Create a view to an entire std::vector object. This is equivalent to * initializing an ArrayView object with a pointer to the first element and * the size of the given argument. * * This function is used for @p const references to objects of vector type * because they contain immutable elements. Consequently, the return type of * this function is a view to a set of @p const objects. * * @param[in] vector The vector for which we want to have an array view * object. The array view corresponds to the entire vector. * * @relatesalso ArrayView */ template inline ArrayView make_array_view(const std::vector &vector) { return ArrayView(vector.data(), vector.size()); } /** * Create a view to a part of a std::vector object. This is equivalent to * initializing the ArrayView object with a pointer to the * @p starting_index-th element and the @p size_of_view as the length of the view. * * This function is used for non-@p const references to objects of vector * type. Such objects contain elements that can be written to. Consequently, * the return type of this function is a view to a set of writable objects. * * @param[in] vector The vector for which we want to have an array view * object. * @param[in] starting_index The index of the first element of the vector that * will be part of this view. * @param[in] size_of_view Number of elements in the new ArrayView. * * @pre starting_index + size_of_view <= vector.size() * * @relatesalso ArrayView */ template inline ArrayView make_array_view(std::vector &vector, const std::size_t starting_index, const std::size_t size_of_view) { Assert(starting_index + size_of_view <= vector.size(), ExcMessage("The starting index and size of the view you want to " "create would lead to a view that extends beyond the end " "of the given vector.")); return ArrayView(&vector[starting_index], size_of_view); } /** * Create a view to a part of a std::vector object. This is equivalent to * initializing the ArrayView object with a pointer to the @p starting_index-th * element and the @p size_of_view as the length of the view. * * This function is used for @p const references to objects of vector type * because they contain immutable elements. Consequently, the return type of * this function is a view to a set of @p const objects. * * @param[in] vector The vector for which we want to have an array view * object. * @param[in] starting_index The index of the first element of the vector that * will be part of this view. * @param[in] size_of_view Number of elements in the new ArrayView. * * @pre starting_index + size_of_view <= vector.size() * * @relatesalso ArrayView */ template inline ArrayView make_array_view(const std::vector &vector, const std::size_t starting_index, const std::size_t size_of_view) { Assert(starting_index + size_of_view <= vector.size(), ExcMessage("The starting index and size of the view you want to " "create would lead to a view that extends beyond the end " "of the given vector.")); return ArrayView(&vector[starting_index], size_of_view); } /** * Create a writable view to an entire AlignedVector object. See the * documentation of the corresponding overload for std::vector for more * information. * * @relatesalso ArrayView */ template inline ArrayView make_array_view(AlignedVector &vector) { return ArrayView(vector.data(), vector.size()); } /** * Create a read-only view to an entire AlignedVector object. See the * documentation of the corresponding overload for std::vector for more * information. * * @relatesalso ArrayView */ template inline ArrayView make_array_view(const AlignedVector &vector) { return ArrayView(vector.data(), vector.size()); } /** * Create a writable view to a part of an AlignedVector object. See the * documentation of the corresponding overload for std::vector for more * information. * * @relatesalso ArrayView */ template inline ArrayView make_array_view(AlignedVector &vector, const std::size_t starting_index, const std::size_t size_of_view) { Assert(starting_index + size_of_view <= vector.size(), ExcMessage("The starting index and size of the view you want to " "create would lead to a view that extends beyond the end " "of the given vector.")); return ArrayView(&vector[starting_index], size_of_view); } /** * Create a read-only view to a part of an AlignedVector object. See the * documentation of the corresponding overload for std::vector for more * information. * * @relatesalso ArrayView */ template inline ArrayView make_array_view(const AlignedVector &vector, const std::size_t starting_index, const std::size_t size_of_view) { Assert(starting_index + size_of_view <= vector.size(), ExcMessage("The starting index and size of the view you want to " "create would lead to a view that extends beyond the end " "of the given vector.")); return ArrayView(&vector[starting_index], size_of_view); } /** * Create a view to an entire std::array object. This is equivalent to * initializing an ArrayView object with a pointer to the first element and * the size of the given argument. * * This function is used for non-@p const references to objects of array * type. Such objects contain elements that can be written to. Consequently, * the return type of this function is a view to a set of writable objects. * * @param[in] array The std::array object for which we want to have an array * view object. The array view corresponds to the entire array. * * @relatesalso ArrayView */ template inline ArrayView make_array_view(std::array &array) { return ArrayView(array); } /** * Create a view to an entire std::array object. This is equivalent to * initializing an ArrayView object with a pointer to the first element and * the size of the given argument. * * This function is used for @p const references to objects of array type * because they contain immutable elements. Consequently, the return type of * this function is a view to a set of @p const objects. * * @param[in] array The std::array object for which we want to have an array * view object. The array view corresponds to the entire array. * * @relatesalso ArrayView */ template inline ArrayView make_array_view(const std::array &array) { return ArrayView(array); } /** * Create a view to an entire row of a Table<2> object. This is equivalent to * initializing an ArrayView object with a pointer to the first element of the * given row, and the length of the row as the length of the view. * * This function is used for non-@p const references to objects of Table type. * Such objects contain elements that can be written to. Consequently, the * return type of this function is a view to a set of writable objects. * * @param[in] table The Table for which we want to have an array view object. * The array view corresponds to an entire row. * @param[in] row The index of the row into the table to which this view * should correspond. * * @relatesalso ArrayView */ template inline ArrayView make_array_view(Table<2, ElementType> &table, const typename Table<2, ElementType>::size_type row) { AssertIndexRange(row, table.size()[0]); return ArrayView(&table[row][0], table.size()[1]); } /** * Create a view to an entire Table<2> object. This is equivalent to * initializing an ArrayView object with a pointer to the first element of the * given table, and the number of table entries as the length of the view. * * This function is used for non-@p const references to objects of Table type. * Such objects contain elements that can be written to. Consequently, the * return type of this function is a view to a set of writable objects. * * @param[in] table The Table for which we want to have an array view object. * The array view corresponds to the entire table but the order in * which the entries are presented in the array is an implementation detail * and should not be relied upon. * * @relatesalso ArrayView */ template inline ArrayView make_array_view(Table<2, ElementType> &table) { return ArrayView(&table[0][0], table.n_elements()); } /** * Create a view to an entire Table<2> object. This is equivalent to * initializing an ArrayView object with a pointer to the first element of the * given table, and the number of table entries as the length of the view. * * This function is used for @p const references to objects of Table type * because they contain immutable elements. Consequently, the return type of * this function is a view to a set of @p const objects. * * @param[in] table The Table for which we want to have an array view object. * The array view corresponds to the entire table but the order in * which the entries are presented in the array is an implementation detail * and should not be relied upon. * * @relatesalso ArrayView */ template inline ArrayView make_array_view(const Table<2, ElementType> &table) { return ArrayView(&table[0][0], table.n_elements()); } /** * Create a view to an entire LAPACKFullMatrix object. This is equivalent to * initializing an ArrayView object with a pointer to the first element of the * given object, and the number entries as the length of the view. * * This function is used for @p non-const references to objects of * LAPACKFullMatrix type. Such objects contain elements that can be written to. * Consequently, the return type of this function is a view to a set of * @p non-const objects. * * @param[in] matrix The LAPACKFullMatrix for which we want to have an array * view object. The array view corresponds to the entire object but * the order in which the entries are presented in the array is an * implementation detail and should not be relied upon. * * @relatesalso ArrayView */ template inline ArrayView make_array_view(LAPACKFullMatrix &matrix) { return ArrayView(&matrix(0, 0), matrix.n_elements()); } /** * Create a view to an entire LAPACKFullMatrix object. This is equivalent to * initializing an ArrayView object with a pointer to the first element of the * given object, and the number of entries as the length of the view. * * This function is used for @p const references to objects of LAPACKFullMatrix * type because they contain immutable elements. Consequently, the return type * of this function is a view to a set of @p const objects. * * @param[in] matrix The LAPACKFullMatrix for which we want to have an array * view object. The array view corresponds to the entire object but * the order in which the entries are presented in the array is an * implementation detail and should not be relied upon. * * @relatesalso ArrayView */ template inline ArrayView make_array_view(const LAPACKFullMatrix &matrix) { return ArrayView(&matrix(0, 0), matrix.n_elements()); } /** * Create a view to an entire row of a Table<2> object. This is equivalent to * initializing an ArrayView object with a pointer to the first element of the * given row, and the length of the row as the length of the view. * * This function is used for @p const references to objects of Table type * because they contain immutable elements. Consequently, the return type of * this function is a view to a set of @p const objects. * * @param[in] table The Table for which we want to have an array view object. * The array view corresponds to an entire row. * @param[in] row The index of the row into the table to which this view * should correspond. * * @relatesalso ArrayView */ template inline ArrayView make_array_view(const Table<2, ElementType> &table, const typename Table<2, ElementType>::size_type row) { AssertIndexRange(row, table.size()[0]); return ArrayView(&table[row][0], table.size()[1]); } /** * Create a view to (a part of) a row of a Table<2> object. * * This function is used for non-@p const references to objects of Table type. * Such objects contain elements that can be written to. Consequently, the * return type of this function is a view to a set of writable objects. * * @param[in] table The Table for which we want to have an array view object. * The array view corresponds to an entire row. * @param[in] row The index of the row into the table to which this view * should correspond. * @param[in] starting_column The index of the column into the given row of * the table that corresponds to the first element of this view. * @param[in] size_of_view The number of elements this view should have. This * corresponds to the number of columns in the current row to which the view * should correspond. * * @relatesalso ArrayView */ template inline ArrayView make_array_view(Table<2, ElementType> &table, const typename Table<2, ElementType>::size_type row, const typename Table<2, ElementType>::size_type starting_column, const std::size_t size_of_view) { AssertIndexRange(row, table.size()[0]); AssertIndexRange(starting_column, table.size()[1]); Assert(starting_column + size_of_view <= table.size()[1], ExcMessage("The starting index and size of the view you want to " "create would lead to a view that extends beyond the end " "of a column of the given table.")); return ArrayView(&table[row][starting_column], size_of_view); } /** * Create a view to (a part of) a row of a Table<2> object. * * This function is used for @p const references to objects of Table type * because they contain immutable elements. Consequently, the return type of * this function is a view to a set of @p const objects. * * @param[in] table The Table for which we want to have an array view object. * The array view corresponds to an entire row. * @param[in] row The index of the row into the table to which this view * should correspond. * @param[in] starting_column The index of the column into the given row of * the table that corresponds to the first element of this view. * @param[in] size_of_view The number of elements this view should have. This * corresponds to the number of columns in the current row to which the view * should correspond. * * @relatesalso ArrayView */ template inline ArrayView make_array_view(const Table<2, ElementType> &table, const typename Table<2, ElementType>::size_type row, const typename Table<2, ElementType>::size_type starting_column, const std::size_t size_of_view) { AssertIndexRange(row, table.size()[0]); AssertIndexRange(starting_column, table.size()[1]); Assert(starting_column + size_of_view <= table.size()[1], ExcMessage("The starting index and size of the view you want to " "create would lead to a view that extends beyond the end " "of a column of the given table.")); return ArrayView(&table[row][starting_column], size_of_view); } /* * Create a view that doesn't allow the container it points to to be modified. * This is useful if the object passed in is not `const` already and a function * requires a view to constant memory in its signature. * * This function returns an object of type `ArrayView` where `T` is the * element type of the container. * * @relatesalso ArrayView */ template inline auto make_const_array_view(const Container &container) -> decltype(make_array_view(container)) { return make_array_view(container); } DEAL_II_NAMESPACE_CLOSE #endif