Debian Codegraph @

include/deal.II/base/array_view.h

raw
1 // ------------------------------------------------------------------------
2 //
3 // SPDX-License-Identifier: LGPL-2.1-or-later
4 // Copyright (C) 2015 - 2025 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_array_view_h
16 #define dealii_array_view_h
17
18 #include <deal.II/base/config.h>
19
20 #include <deal.II/base/exceptions.h>
21 #include <deal.II/base/memory_space.h>
22 #include <deal.II/base/symmetric_tensor.h>
23 #include <deal.II/base/template_constraints.h>
24 #include <deal.II/base/tensor.h>
25
26 #include <boost/container/small_vector.hpp>
27
28 #include <array>
29 #include <type_traits>
30 #include <vector>
31
32 DEAL_II_NAMESPACE_OPEN
33
34 // Forward declaration
35 template <class T>
36 class AlignedVector;
37
38 template <int N, typename T>
39 class Table;
40
41 template <typename number>
42 class LAPACKFullMatrix;
43
44
45 /**
46 * A class that represents a window of memory locations of type @p ElementType
47 * and presents it as if it was an array. In essence, this class is nothing more
48 * than just a pointer to the first location and an integer that represents the
49 * length of the array in elements. The memory remains owned by whoever
50 * allocated it, as this class does not take over ownership.
51 *
52 * The advantage of using this class is that you don't have to pass around
53 * pairs of pointers and that <code>operator[]</code> checks for the validity
54 * of the index with which you subscript this array view. Note that accessing
55 * elements is only allowed if the underlying data is stored in CPU memory.
56 *
57 * This class can handle views to both non-constant and constant memory
58 * locations. If you want to represent a view of a constant array, then the
59 * template argument type of this class needs to be @p const as well. The
60 * following code snippet gives an example:
61 * @code
62 * std::vector<int> array = get_data(); // a writable array
63 * ArrayView<int> view (&array[5], 5); // a view of elements 5..9 (inclusive)
64 * view[2] = 42; // array[7] is set to 42
65 * ArrayView<const int> const_view (&array[5], 5); // same view, but read-only
66 * int element_7 = const_view[2]; // set element_7 to 42
67 * const_view[2] = 42; // this line won't compile; can't write into this view
68 * @endcode
69 * In either case, accessing an element of a view does not change the
70 * ArrayView object itself, and consequently ArrayView::operator[] is a @p
71 * const function. This corresponds to the notion that a view simply
72 * represents a, well, "view" of memory that is owned by someone else. Thus,
73 * accessing elements of the view changes the memory managed by some other
74 * object, but not the view itself, allowing us to make ArrayView::operator[]
75 * a @p const member function. This is in contrast to, say, std::vector, which
76 * manages the memory it points to and changing an element of the std::vector
77 * therefore changes the std::vector object itself -- consequently, the
78 * std::vector::operator[] is non-@p const.
79 *
80 * @note This class is similar to
81 * [`std::span`](https://en.cppreference.com/w/cpp/container/span), but the
82 * latter is only available starting in C++20.
83 *
84 * @ingroup data
85 */
86 template <typename ElementType, typename MemorySpaceType = MemorySpace::Host>
87 class ArrayView
88 {
89 public:
90 /**
91 * An alias that denotes the "value_type" of this container-like class,
92 * i.e., the type of the element it "stores" or points to.
93 */
94 using value_type = ElementType;
95
96 /**
97 * An alias for iterators pointing into the array.
98 */
99 using iterator = value_type *;
100
101 /**
102 * An alias for const iterators pointing into the array.
103 */
104 using const_iterator = const ElementType *;
105
106 /**
107 * Default constructor.
108 */
109 ArrayView();
110
111 /**
112 * Constructor.
113 *
114 * @param[in] starting_element A pointer to the first element of the array
115 * this object should represent. The value of this argument is only evaluated
116 * if `n_elements` is larger than zero. Otherwise, the value of this
117 * argument is ignored as if the ArrayView object used a `nullptr`
118 * to point to the first element of the array.
119 * @param[in] n_elements The length (in elements) of the chunk of memory
120 * this object should represent.
121 *
122 * @note The object that is constructed from these arguments has no
123 * knowledge how large the object into which it points really is. As a
124 * consequence, whenever you call ArrayView::operator[], the array view can
125 * check that the given index is within the range of the view, but it can't
126 * check that the view is indeed a subset of the valid range of elements of
127 * the underlying object that allocated that range. In other words, you need
128 * to ensure that the range of the view specified by the two arguments to
129 * this constructor is in fact a subset of the elements of the array into
130 * which it points. The appropriate way to do this is to use the
131 * make_array_view() functions.
132 */
133 ArrayView(value_type *starting_element, const std::size_t n_elements);
134
135 /**
136 * Copy constructor from array views that point to non-@p const elements. If
137 * the current object will point to non-@p const elements, then this is a
138 * straight forward copy constructor. On the other hand, if the current
139 * type's @p ElementType template argument is a @p const qualified type,
140 * then the current constructor is a conversion constructor that converts a
141 * non-@p const view to a @p const view, akin to converting a non-@p const
142 * pointer to a @p const pointer.
143 */
144 ArrayView(
145 const ArrayView<std::remove_cv_t<value_type>, MemorySpaceType> &view);
146
147 /**
148 * A constructor that automatically creates a view from a single value_type
149 * object. The view so created then has length one.
150 */
151 explicit ArrayView(value_type &element);
152
153 #ifdef DEAL_II_HAVE_CXX20
154 /**
155 * A constructor that automatically creates a view from a container
156 * object that requires a contiguous array of elements (such as
157 * `std::vector`, `std::array`, `boost::container::small_vector`,
158 * and the like). The view encompasses all elements of the given
159 * container.
160 *
161 * This implicit conversion constructor is particularly useful when calling
162 * a function that takes an ArrayView object as argument, and passing in
163 * a container.
164 *
165 * @note This constructor takes a reference to a @p const container as argument.
166 * It can only be used to initialize ArrayView objects that point to
167 * @p const memory locations, such as <code>ArrayView@<const double@></code>.
168 * You cannot initialize ArrayView objects to non-@p const memory with
169 * such arguments, such as <code>ArrayView@<double@></code>.
170 */
171 template <typename ContiguousContainer>
172 ArrayView(const ContiguousContainer &container)
173 requires(std::is_same_v<
174 std::remove_cv_t<ElementType>,
175 std::remove_cv_t<typename ContiguousContainer::value_type>> &&
176 std::is_const_v<ElementType> &&
177 concepts::is_contiguous_container<ContiguousContainer>);
178
179 /**
180 * A constructor that automatically creates a view from a container
181 * object that requires a contiguous array of elements (such as
182 * `std::vector`, `std::array`, `boost::container::small_vector`,
183 * and the like). The view encompasses all elements of the given
184 * container.
185 *
186 * This implicit conversion constructor is particularly useful when calling
187 * a function that takes an ArrayView object as argument, and passing in
188 * a container.
189 *
190 * @note This constructor takes a reference to a non-@p const container as
191 * argument. It can be used to initialize ArrayView objects that point to
192 * either @p const memory locations, such as
193 * <code>ArrayView@<const double@></code>, or to non-@p const memory,
194 * such as <code>ArrayView@<double@></code>.
195 */
196 template <typename ContiguousContainer>
197 ArrayView(ContiguousContainer &container)
198 requires(std::is_same_v<
199 std::remove_cv_t<ElementType>,
200 std::remove_cv_t<typename ContiguousContainer::value_type>> &&
201 concepts::is_contiguous_container<ContiguousContainer>);
202
203 #else
204
205
206 /**
207 * A constructor that automatically creates a view from a container
208 * object that requires a contiguous array of elements (such as
209 * `std::vector`, `std::array`, `boost::container::small_vector`,
210 * and the like). The view encompasses all elements of the given
211 * container.
212 *
213 * This implicit conversion constructor is particularly useful when calling
214 * a function that takes an ArrayView object as argument, and passing in
215 * a container.
216 *
217 * @note This constructor takes a reference to a @p const container as argument.
218 * It can only be used to initialize ArrayView objects that point to
219 * @p const memory locations, such as <code>ArrayView@<const double@></code>.
220 * You cannot initialize ArrayView objects to non-@p const memory with
221 * such arguments, such as <code>ArrayView@<double@></code>.
222 */
223 template <typename ContiguousContainer,
224 typename = decltype(std::data(std::declval<ContiguousContainer>())),
225 typename = decltype(std::size(std::declval<ContiguousContainer>())),
226 typename = std::enable_if_t<
227 std::is_same_v<
228 std::remove_cv_t<ElementType>,
229 std::remove_cv_t<typename ContiguousContainer::value_type>> &&
230 std::is_const_v<ElementType>>>
231 ArrayView(const ContiguousContainer &container);
232
233 /**
234 * A constructor that automatically creates a view from a container
235 * object that requires a contiguous array of elements (such as
236 * `std::vector`, `std::array`, `boost::container::small_vector`,
237 * and the like). The view encompasses all elements of the given
238 * container.
239 *
240 * This implicit conversion constructor is particularly useful when calling
241 * a function that takes an ArrayView object as argument, and passing in
242 * a container.
243 *
244 * @note This constructor takes a reference to a non-@p const container as
245 * argument. It can be used to initialize ArrayView objects that point to
246 * either @p const memory locations, such as
247 * <code>ArrayView@<const double@></code>, or to non-@p const memory,
248 * such as <code>ArrayView@<double@></code>.
249 */
250 template <typename ContiguousContainer,
251 typename = decltype(std::data(std::declval<ContiguousContainer>())),
252 typename = decltype(std::size(std::declval<ContiguousContainer>())),
253 typename = std::enable_if_t<std::is_same_v<
254 std::remove_cv_t<ElementType>,
255 std::remove_cv_t<typename ContiguousContainer::value_type>>>>
256 ArrayView(ContiguousContainer &container);
257
258 #endif
259
260 /**
261 * A constructor that automatically creates a view for a given C-style array.
262 * This constructor can be used as follows:
263 * @code
264 * ArrayView<const int>
265 * get_data_table ()
266 * {
267 * static const int my_data[7] = { 1, 1, 2, 3, 5, 8, 13 };
268 * return {my_data};
269 * }
270 * @endcode
271 * The object so returned is then a view of the array, with the size 7
272 * correctly deduced.
273 */
274 template <std::size_t N>
275 ArrayView(value_type (&array)[N]);
276
277 /**
278 * A constructor that creates a view of the array that underlies a
279 * [std::initializer_list](https://en.cppreference.com/w/cpp/utility/initializer_list).
280 * This constructor allows for cases such as where one has a function
281 * that takes an ArrayView object:
282 * @code
283 * void f(const ArrayView<const int> &a);
284 * @endcode
285 * and then to call this function with a list of integers:
286 * @code
287 * f({1,2,3});
288 * @endcode
289 * This also works with an empty list:
290 * @code
291 * f({});
292 * @encode
293 *
294 * @note This constructor only works if the template type is `const`
295 * qualified. That is, you can initialize an `ArrayView<const int>`
296 * object from a `std::initializer_list<int>`, but not an
297 * `ArrayView<int>` object. This is because the elements of initializer
298 * lists are `const`.
299 *
300 * @note `std::initializer_list` objects are temporary. They are constructed
301 * where the compiler finds a brace-enclosed list, and so they only live
302 * for at most the time it takes to execute the current statement. As a
303 * consequence, creating an ArrayView object of such a `std::initializer_list`
304 * also results in a view object that points to valid memory only for as long
305 * as the current statement is executed. You shouldn't expect that the
306 * resulting ArrayView can be used to point to useful memory content past
307 * that point. In other words, while this code...
308 * @code
309 * std::vector<int> v(10);
310 * ArrayView<int> a(v);
311 * f(a);
312 * @endcode
313 * ...works because the array `v` pointed to exists until after the call to
314 * `f()`, the following code will not likely work as expected:
315 * @code
316 * ArrayView<int> a({1,2,3});
317 * f(a);
318 * @endcode
319 */
320 ArrayView(
321 const std::initializer_list<std::remove_cv_t<value_type>> &initializer_list)
322 DEAL_II_CXX20_REQUIRES(std::is_const_v<ElementType>);
323
324 /**
325 * Reinitialize a view.
326 *
327 * @param[in] starting_element A pointer to the first element of the array
328 * this object should represent.
329 * @param[in] n_elements The length (in elements) of the chunk of memory
330 * this object should represent.
331 *
332 * @note The object that is constructed from these arguments has no
333 * knowledge how large the object into which it points really is. As a
334 * consequence, whenever you call ArrayView::operator[], the array view can
335 * check that the given index is within the range of the view, but it can't
336 * check that the view is indeed a subset of the valid range of elements of
337 * the underlying object that allocated that range. In other words, you need
338 * to ensure that the range of the view specified by the two arguments to
339 * this constructor is in fact a subset of the elements of the array into
340 * which it points. The appropriate way to do this is to use the
341 * make_array_view() functions.
342 */
343 void
344 reinit(value_type *starting_element, const std::size_t n_elements);
345
346 /**
347 * Compare two ArrayView objects of the same type. Two objects are considered
348 * equal if they have the same size and the same starting pointer.
349 *
350 * Note that this means that the operation tests that the *views* are the
351 * same. If they are, then of course the elements represented by the view
352 * are also the same. But the converse is not true: Two ArrayView objects
353 * may point to different parts of the memory space and in that case the
354 * comparison for equality will return `false` even if the *elements* the
355 * views point to are the same.
356 *
357 * This version always compares with the const value_type.
358 */
359 bool
360 operator==(
361 const ArrayView<const value_type, MemorySpaceType> &other_view) const;
362
363 /**
364 * Compare two ArrayView objects of the same type. Two objects are considered
365 * equal if they have the same size and the same starting pointer.
366 *
367 * Note that this means that the operation tests that the *views* are the
368 * same. If they are, then of course the elements represented by the view
369 * are also the same. But the converse is not true: Two ArrayView objects
370 * may point to different parts of the memory space and in that case the
371 * comparison for equality will return `false` even if the *elements* the
372 * views point to are the same.
373 *
374 * This version always compares with the non-const value_type.
375 */
376 bool
377 operator==(const ArrayView<std::remove_cv_t<value_type>, MemorySpaceType>
378 &other_view) const;
379
380 /**
381 * Compare two ArrayView objects of the same type. Two objects are considered
382 * equal if they have the same size and the same starting pointer, and the
383 * current operation therefore returns `true` if the two views being compared
384 * point to different memory locations, or if they point to the same memory
385 * location but represent different sizes.
386 *
387 * Note that this means that the operation tests that the *views* are the
388 * not the same. But this does not mean that the elements pointed to by
389 * the view are not equal: Two ArrayView objects
390 * may point to different parts of the memory space and in that case the
391 * comparison for inequality will return `true` even if the *elements* the
392 * views point to are the same.
393 *
394 * This version always compares with the const value_type.
395 */
396 bool
397 operator!=(
398 const ArrayView<const value_type, MemorySpaceType> &other_view) const;
399
400 /**
401 * Compare two ArrayView objects of the same type. Two objects are considered
402 * equal if they have the same size and the same starting pointer.
403 *
404 * Note that this means that the operation tests that the *views* are the
405 * not the same. But this does not mean that the elements pointed to by
406 * the view are not equal: Two ArrayView objects
407 * may point to different parts of the memory space and in that case the
408 * comparison for inequality will return `true` even if the *elements* the
409 * views point to are the same.
410 *
411 * This version always compares with the non-const value_type.
412 */
413 bool
414 operator!=(const ArrayView<std::remove_cv_t<value_type>, MemorySpaceType>
415 &other_view) const;
416
417 /**
418 * Return the size (in elements) of the view of memory this object
419 * represents.
420 */
421 std::size_t
422 size() const;
423
424 /**
425 * Return a bool whether the array view is empty.
426 */
427 bool
428 empty() const;
429
430 /**
431 * Return a pointer to the underlying array serving as element storage.
432 * In case the container is empty a nullptr is returned.
433 */
434 DEAL_II_HOST_DEVICE value_type *
435 data() const noexcept;
436
437 /**
438 * Return an iterator pointing to the beginning of the array view.
439 */
440 iterator
441 begin() const;
442
443 /**
444 * Return an iterator pointing to one past the end of the array view.
445 */
446 iterator
447 end() const;
448
449 /**
450 * Return a constant iterator pointing to the beginning of the array view.
451 */
452 const_iterator
453 cbegin() const;
454
455 /**
456 * Return a constant iterator pointing to one past the end of the array view.
457 */
458 const_iterator
459 cend() const;
460
461 /**
462 * Return a reference to the $i$th element of the range represented by the
463 * current object.
464 *
465 * This function is marked as @p const because it does not change the
466 * <em>view object</em>. It may however return a reference to a non-@p const
467 * memory location depending on whether the template type of the class is @p
468 * const or not.
469 *
470 * This function is only allowed to be called if the underlying data is indeed
471 * stored in CPU memory.
472 */
473 value_type &
474 operator[](const std::size_t i) const;
475
476 private:
477 /**
478 * A pointer to the first element of the range of locations in memory that
479 * this object represents.
480 */
481 value_type *starting_element;
482
483 /**
484 * The length of the array this object represents.
485 */
486 std::size_t n_elements;
487
488 friend class ArrayView<const ElementType, MemorySpaceType>;
489 };
490
491
492
493 //---------------------------------------------------------------------------
494
495
496 template <typename ElementType, typename MemorySpaceType>
497 inline ArrayView<ElementType, MemorySpaceType>::ArrayView()
498 : starting_element(nullptr)
499 , n_elements(0)
500 {}
501
502
503
504 template <typename ElementType, typename MemorySpaceType>
505 inline ArrayView<ElementType, MemorySpaceType>::ArrayView(
506 value_type *starting_element,
507 const std::size_t n_elements)
508 : // In debug mode, make sure that n_elements>0 and if it is not, set
509 // the pointer to a nullptr to trigger segfaults if anyone ever wanted
510 // to access elements of the array. In release mode, just take the
511 // pointer as given.
512 starting_element((library_build_mode == LibraryBuildMode::release) ||
513 (n_elements > 0) ?
514 starting_element :
515 nullptr)
516 , n_elements(n_elements)
517 {}
518
519
520
521 template <typename ElementType, typename MemorySpaceType>
522 inline void
523 ArrayView<ElementType, MemorySpaceType>::reinit(value_type *starting_element,
524 const std::size_t n_elements)
525 {
526 if constexpr (running_in_debug_mode())
527 {
528 if (n_elements > 0)
529 this->starting_element = starting_element;
530 else
531 this->starting_element = nullptr;
532 }
533 else
534 {
535 this->starting_element = starting_element;
536 }
537 this->n_elements = n_elements;
538 }
539
540
541
542 template <typename ElementType, typename MemorySpaceType>
543 inline ArrayView<ElementType, MemorySpaceType>::ArrayView(ElementType &element)
544 : starting_element(&element)
545 , n_elements(1)
546 {}
547
548
549
550 template <typename ElementType, typename MemorySpaceType>
551 inline ArrayView<ElementType, MemorySpaceType>::ArrayView(
552 const ArrayView<std::remove_cv_t<value_type>, MemorySpaceType> &view)
553 : starting_element(view.starting_element)
554 , n_elements(view.n_elements)
555 {}
556
557
558 #ifdef DEAL_II_HAVE_CXX20
559
560 template <typename ElementType, typename MemorySpaceType>
561 template <typename ContiguousContainer>
562 inline ArrayView<ElementType, MemorySpaceType>::ArrayView(
563 const ContiguousContainer &container)
564 requires(std::is_same_v<
565 std::remove_cv_t<ElementType>,
566 std::remove_cv_t<typename ContiguousContainer::value_type>> &&
567 std::is_const_v<ElementType> &&
568 concepts::is_contiguous_container<ContiguousContainer>)
569 : // use delegating constructor
570 ArrayView(container.data(), container.size())
571 {}
572
573
574
575 template <typename ElementType, typename MemorySpaceType>
576 template <typename ContiguousContainer>
577 inline ArrayView<ElementType, MemorySpaceType>::ArrayView(
578 ContiguousContainer &container)
579 requires(std::is_same_v<
580 std::remove_cv_t<ElementType>,
581 std::remove_cv_t<typename ContiguousContainer::value_type>> &&
582 concepts::is_contiguous_container<ContiguousContainer>)
583 : // use delegating constructor
584 ArrayView(std::data(container), std::size(container))
585 {}
586
587
588 #else
589
590 template <typename ElementType, typename MemorySpaceType>
591 template <typename ContiguousContainer, typename, typename, typename>
592 inline ArrayView<ElementType, MemorySpaceType>::ArrayView(
593 const ContiguousContainer &container)
594 : // use delegating constructor
595 ArrayView(container.data(), container.size())
596 {}
597
598
599
600 template <typename ElementType, typename MemorySpaceType>
601 template <typename ContiguousContainer, typename, typename, typename>
602 inline ArrayView<ElementType, MemorySpaceType>::ArrayView(
603 ContiguousContainer &container)
604 : // use delegating constructor
605 ArrayView(std::data(container), std::size(container))
606 {}
607
608 #endif
609
610
611
612 template <typename ElementType, typename MemorySpaceType>
613 template <std::size_t N>
614 inline ArrayView<ElementType, MemorySpaceType>::ArrayView(
615 ElementType (&array)[N])
616 : ArrayView(&array[0], N)
617 {}
618
619
620 template <typename ElementType, typename MemorySpaceType>
621 inline ArrayView<ElementType, MemorySpaceType>::ArrayView(
622 const std::initializer_list<std::remove_cv_t<value_type>> &initializer)
623 DEAL_II_CXX20_REQUIRES(std::is_const_v<ElementType>)
624 : // use delegating constructor
625 ArrayView(initializer.begin(), initializer.size())
626 {}
627
628
629
630 template <typename ElementType, typename MemorySpaceType>
631 inline bool
632 ArrayView<ElementType, MemorySpaceType>::operator==(
633 const ArrayView<const value_type, MemorySpaceType> &other_view) const
634 {
635 return (other_view.data() == starting_element) &&
636 (other_view.size() == n_elements);
637 }
638
639
640
641 template <typename ElementType, typename MemorySpaceType>
642 inline bool
643 ArrayView<ElementType, MemorySpaceType>::operator==(
644 const ArrayView<std::remove_cv_t<value_type>, MemorySpaceType> &other_view)
645 const
646 {
647 return (other_view.data() == starting_element) &&
648 (other_view.size() == n_elements);
649 }
650
651
652
653 template <typename ElementType, typename MemorySpaceType>
654 inline bool
655 ArrayView<ElementType, MemorySpaceType>::operator!=(
656 const ArrayView<const value_type, MemorySpaceType> &other_view) const
657 {
658 return !(*this == other_view);
659 }
660
661
662
663 template <typename ElementType, typename MemorySpaceType>
664 inline DEAL_II_HOST_DEVICE
665 typename ArrayView<ElementType, MemorySpaceType>::value_type *
666 ArrayView<ElementType, MemorySpaceType>::data() const noexcept
667 {
668 if (n_elements == 0)
669 return nullptr;
670 else
671 return starting_element;
672 }
673
674
675
676 template <typename ElementType, typename MemorySpaceType>
677 inline bool
678 ArrayView<ElementType, MemorySpaceType>::operator!=(
679 const ArrayView<std::remove_cv_t<value_type>, MemorySpaceType> &other_view)
680 const
681 {
682 return !(*this == other_view);
683 }
684
685
686
687 template <typename ElementType, typename MemorySpaceType>
688 inline std::size_t
689 ArrayView<ElementType, MemorySpaceType>::size() const
690 {
691 return n_elements;
692 }
693
694
695
696 template <typename ElementType, typename MemorySpaceType>
697 inline bool
698 ArrayView<ElementType, MemorySpaceType>::empty() const
699 {
700 return n_elements == 0;
701 }
702
703
704
705 template <typename ElementType, typename MemorySpaceType>
706 inline typename ArrayView<ElementType, MemorySpaceType>::iterator
707 ArrayView<ElementType, MemorySpaceType>::begin() const
708 {
709 return starting_element;
710 }
711
712
713
714 template <typename ElementType, typename MemorySpaceType>
715 inline typename ArrayView<ElementType, MemorySpaceType>::iterator
716 ArrayView<ElementType, MemorySpaceType>::end() const
717 {
718 return starting_element + n_elements;
719 }
720
721
722
723 template <typename ElementType, typename MemorySpaceType>
724 inline typename ArrayView<ElementType, MemorySpaceType>::const_iterator
725 ArrayView<ElementType, MemorySpaceType>::cbegin() const
726 {
727 return starting_element;
728 }
729
730
731
732 template <typename ElementType, typename MemorySpaceType>
733 inline typename ArrayView<ElementType, MemorySpaceType>::const_iterator
734 ArrayView<ElementType, MemorySpaceType>::cend() const
735 {
736 return starting_element + n_elements;
737 }
738
739
740
741 template <typename ElementType, typename MemorySpaceType>
742 inline typename ArrayView<ElementType, MemorySpaceType>::value_type &
743 ArrayView<ElementType, MemorySpaceType>::operator[](const std::size_t i) const
744 {
745 AssertIndexRange(i, n_elements);
746
747 return *(starting_element + i);
748 }
749
750
751
752 /**
753 * A variation of @p ArrayView which allows strided access into the view.
754 * This is particularly useful when you want to access only one lane of a
755 * VectorizedArray.
756 */
757 template <typename ElementType, std::size_t stride = 1>
758 class StridedArrayView
759 {
760 public:
761 /**
762 * An alias that denotes the "value_type" of this container-like class,
763 * i.e., the type of the element it "stores" or points to.
764 */
765 using value_type = ElementType;
766
767 /**
768 * Constructor.
769 *
770 * @param[in] starting_element A pointer to the first element of the array
771 * this object should represent.
772 * @param[in] n_elements The length (in elements) of the chunk of memory
773 * this object should represent.
774 *
775 * @note The object that is constructed from these arguments has no
776 * knowledge how large the object into which it points really is. As a
777 * consequence, whenever you call ArrayView::operator[], the array view can
778 * check that the given index is within the range of the view, but it can't
779 * check that the view is indeed a subset of the valid range of elements of
780 * the underlying object that allocated that range. In other words, you need
781 * to ensure that the range of the view specified by the two arguments to
782 * this constructor is in fact a subset of the elements of the array into
783 * which it points. The appropriate way to do this is to use the
784 * make_array_view() functions.
785 */
786 StridedArrayView(value_type *starting_element, const std::size_t n_elements);
787
788 /**
789 * Return the size (in elements) of the view of memory this object
790 * represents.
791 */
792 std::size_t
793 size() const;
794
795 /**
796 * Return a bool whether the array view is empty.
797 */
798 bool
799 empty() const;
800
801 /**
802 * Return a pointer to the underlying array serving as element storage.
803 * In case the container is empty a nullptr is returned.
804 */
805 value_type *
806 data() const noexcept;
807
808 /**
809 * Return a reference to the $i$th element of the range represented by the
810 * current object.
811 *
812 * This function is marked as @p const because it does not change the
813 * <em>view object</em>. It may however return a reference to a non-@p const
814 * memory location depending on whether the template type of the class is @p
815 * const or not.
816 *
817 * This function is only allowed to be called if the underlying data is indeed
818 * stored in CPU memory.
819 */
820 value_type &
821 operator[](const std::size_t i) const;
822
823 protected:
824 /**
825 * A pointer to the first element of the range of locations in memory that
826 * this object represents.
827 */
828 value_type *starting_element;
829
830 /**
831 * The length of the array this object represents.
832 */
833 std::size_t n_elements;
834 };
835
836
837
838 template <typename ElementType, std::size_t stride>
839 typename StridedArrayView<ElementType, stride>::value_type &
840 StridedArrayView<ElementType, stride>::operator[](const std::size_t i) const
841 {
842 AssertIndexRange(i, this->n_elements);
843
844 return *(this->starting_element + stride * i);
845 }
846
847
848
849 template <typename ElementType, std::size_t stride>
850 typename StridedArrayView<ElementType, stride>::value_type *
851 StridedArrayView<ElementType, stride>::data() const noexcept
852 {
853 if (this->n_elements == 0)
854 return nullptr;
855 else
856 return this->starting_element;
857 }
858
859
860
861 template <typename ElementType, std::size_t stride>
862 bool
863 StridedArrayView<ElementType, stride>::empty() const
864 {
865 return this->n_elements == 0;
866 }
867
868
869
870 template <typename ElementType, std::size_t stride>
871 std::size_t
872 StridedArrayView<ElementType, stride>::size() const
873 {
874 return this->n_elements;
875 }
876
877
878
879 template <typename ElementType, std::size_t stride>
880 StridedArrayView<ElementType, stride>::StridedArrayView(
881 value_type *starting_element,
882 const std::size_t n_elements)
883 : starting_element(starting_element)
884 , n_elements(n_elements)
885 {}
886
887
888
889 #ifndef DOXYGEN
890 namespace internal
891 {
892 namespace ArrayViewHelper
893 {
894 /**
895 * Return whether the objects one gets by dereferencing the
896 * iterators within the given iterator range form a contiguous
897 * range in memory.
898 */
899 template <class Iterator>
900 bool
901 is_contiguous(const Iterator &first, const Iterator &last)
902 {
903 const auto n = std::distance(first, last);
904 for (std::decay_t<decltype(n)> i = 0; i < n; ++i)
905 if (std::addressof(*(std::next(first, i))) !=
906 std::next(std::addressof(*first), i))
907 return false;
908 return true;
909 }
910
911
912 /**
913 * Return whether the objects one gets by dereferencing the
914 * iterators within the given iterator range form a contiguous
915 * range in memory.
916 *
917 * This specialization for (@p const or non-@p const) pointers
918 * returns @p true unconditionally since the fact that objects
919 * pointed to by pointers are contiguous is embedded in the memory
920 * model of C++.
921 */
922 template <class T>
923 constexpr bool
924 is_contiguous(T *, T *)
925 {
926 return true;
927 }
928 } // namespace ArrayViewHelper
929 } // namespace internal
930 #endif
931
932
933
934 /**
935 * Create an ArrayView that takes a pair of iterators as arguments. The type
936 * of the ArrayView is inferred from the value type of the iterator (e.g., the
937 * view created from two const iterators will have a const type).
938 *
939 * @warning The iterators @p begin and @p end must bound (in the usual half-open
940 * way) a contiguous in memory range of values. This function is intended for
941 * use with iterators into containers like
942 * <code>boost::container::small_vector</code> or <code>std::vector</code> and
943 * will not work correctly with, e.g.,
944 * <code>boost::container::stable_vector</code> or <code>std::deque</code>.
945 * In debug mode, we check that the provided iterators represent contiguous
946 * memory indeed.
947 *
948 * @relatesalso ArrayView
949 */
950 template <typename Iterator, typename MemorySpaceType = MemorySpace::Host>
951 ArrayView<
952 std::remove_reference_t<typename std::iterator_traits<Iterator>::reference>,
953 MemorySpaceType>
954 make_array_view(const Iterator begin, const Iterator end)
955 {
956 static_assert(
957 std::is_same_v<typename std::iterator_traits<Iterator>::iterator_category,
958 typename std::random_access_iterator_tag>
959 #ifdef DEAL_II_HAVE_CXX20
960 ||
961 std::is_same_v<typename std::iterator_traits<Iterator>::iterator_category,
962 typename std::contiguous_iterator_tag>
963 #endif
964 ,
965 "The provided iterator needs to be a random access iterator.");
966 Assert(begin <= end,
967 ExcMessage(
968 "The beginning of the array view needs to be before the end."));
969 Assert(internal::ArrayViewHelper::is_contiguous(begin, end),
970 ExcMessage("The provided range isn't contiguous in memory!"));
971 // the reference type, not the value type, knows the constness of the iterator
972 return ArrayView<
973 std::remove_reference_t<typename std::iterator_traits<Iterator>::reference>,
974 MemorySpaceType>(std::addressof(*begin), end - begin);
975 }
976
977
978
979 /**
980 * Create a view from a pair of pointers. <code>ElementType</code> may be
981 * const-qualified.
982 *
983 * @warning The pointers @p begin and @p end must bound (in the usual
984 * half-open way) a contiguous in memory range of values.
985 *
986 * @relatesalso ArrayView
987 */
988 template <typename ElementType, typename MemorySpaceType = MemorySpace::Host>
989 ArrayView<ElementType, MemorySpaceType>
990 make_array_view(ElementType *const begin, ElementType *const end)
991 {
992 Assert(begin <= end,
993 ExcMessage(
994 "The beginning of the array view needs to be before the end."));
995 return ArrayView<ElementType, MemorySpaceType>(begin, end - begin);
996 }
997
998
999
1000 /**
1001 * Create a view from an ArrayView itself.
1002 *
1003 * This function is used for @p const references to objects of ArrayView type.
1004 * It only exists for compatibility purposes.
1005 *
1006 * @param[in] array_view The ArrayView that we wish to make a copy of.
1007 *
1008 * @relatesalso ArrayView
1009 */
1010 template <typename Number, typename MemorySpaceType>
1011 inline ArrayView<const Number, MemorySpaceType>
1012 make_array_view(const ArrayView<Number, MemorySpaceType> &array_view)
1013 {
1014 return make_array_view(array_view.cbegin(), array_view.cend());
1015 }
1016
1017
1018
1019 /**
1020 * Create a view from an ArrayView itself.
1021 *
1022 * This function is used for non-@p const references to objects of ArrayView
1023 * type. It only exists for compatibility purposes.
1024 *
1025 * @param[in] array_view The ArrayView that we wish to make a copy of.
1026 *
1027 * @relatesalso ArrayView
1028 */
1029 template <typename Number, typename MemorySpaceType>
1030 inline ArrayView<Number, MemorySpaceType>
1031 make_array_view(ArrayView<Number, MemorySpaceType> &array_view)
1032 {
1033 return make_array_view(array_view.begin(), array_view.end());
1034 }
1035
1036
1037
1038 /**
1039 * Create a view to an entire C-style array. This is equivalent to
1040 * initializing an ArrayView object with a pointer to the first element and
1041 * the size of the given argument.
1042 *
1043 * Whether the resulting ArrayView is writable or not depends on the
1044 * ElementType being a const type or not.
1045 *
1046 * @param[in] array The C-style array for which we want to have an ArrayView
1047 * object. The ArrayView corresponds to the <em>entire</em> vector.
1048 *
1049 * @relatesalso ArrayView
1050 */
1051 template <typename ElementType, int N>
1052 inline ArrayView<ElementType>
1053 make_array_view(ElementType (&array)[N])
1054 {
1055 return ArrayView<ElementType>(array, N);
1056 }
1057
1058
1059
1060 /**
1061 * Create a view to an entire Vector object. This is equivalent to
1062 * initializing an ArrayView object with a pointer to the first element and
1063 * the size of the given argument.
1064 *
1065 * This function is used for non-@p const references to objects of Vector
1066 * type. Such objects contain elements that can be written to. Consequently,
1067 * the return type of this function is a view to a set of writable objects.
1068 *
1069 * @param[in] vector The Vector for which we want to have an array view
1070 * object. The array view corresponds to the <em>entire</em> Vector.
1071 *
1072 * @relatesalso ArrayView
1073 */
1074 template <typename ElementType>
1075 inline ArrayView<ElementType>
1076 make_array_view(Vector<ElementType> &vector)
1077 {
1078 return ArrayView<ElementType>(vector.begin(), vector.size());
1079 }
1080
1081
1082
1083 /**
1084 * Create a view to an entire Vector object. This is equivalent to
1085 * initializing an ArrayView object with a pointer to the first element and
1086 * the size of the given argument.
1087 *
1088 * This function is used for @p const references to objects of Vector type
1089 * because they contain immutable elements. Consequently, the return type of
1090 * this function is a view to a set of @p const objects.
1091 *
1092 * @param[in] vector The Vector for which we want to have an array view
1093 * object. The array view corresponds to the <em>entire</em> Vector.
1094 *
1095 * @relatesalso ArrayView
1096 */
1097 template <typename ElementType>
1098 inline ArrayView<const ElementType>
1099 make_array_view(const Vector<ElementType> &vector)
1100 {
1101 return ArrayView<const ElementType>(vector.begin(), vector.size());
1102 }
1103
1104
1105
1106 /**
1107 * Create a view to an entire std::vector object. This is equivalent to
1108 * initializing an ArrayView object with a pointer to the first element and
1109 * the size of the given argument.
1110 *
1111 * This function is used for non-@p const references to objects of vector
1112 * type. Such objects contain elements that can be written to. Consequently,
1113 * the return type of this function is a view to a set of writable objects.
1114 *
1115 * @param[in] vector The vector for which we want to have an array view
1116 * object. The array view corresponds to the <em>entire</em> vector.
1117 *
1118 * @relatesalso ArrayView
1119 */
1120 template <typename ElementType>
1121 inline ArrayView<ElementType>
1122 make_array_view(std::vector<ElementType> &vector)
1123 {
1124 return ArrayView<ElementType>(vector.data(), vector.size());
1125 }
1126
1127
1128
1129 /**
1130 * Create a view to an entire std::vector object. This is equivalent to
1131 * initializing an ArrayView object with a pointer to the first element and
1132 * the size of the given argument.
1133 *
1134 * This function is used for @p const references to objects of vector type
1135 * because they contain immutable elements. Consequently, the return type of
1136 * this function is a view to a set of @p const objects.
1137 *
1138 * @param[in] vector The vector for which we want to have an array view
1139 * object. The array view corresponds to the <em>entire</em> vector.
1140 *
1141 * @relatesalso ArrayView
1142 */
1143 template <typename ElementType>
1144 inline ArrayView<const ElementType>
1145 make_array_view(const std::vector<ElementType> &vector)
1146 {
1147 return ArrayView<const ElementType>(vector.data(), vector.size());
1148 }
1149
1150
1151
1152 /**
1153 * Create a view to a part of a std::vector object. This is equivalent to
1154 * initializing the ArrayView object with a pointer to the
1155 * @p starting_index-th element and the @p size_of_view as the length of the view.
1156 *
1157 * This function is used for non-@p const references to objects of vector
1158 * type. Such objects contain elements that can be written to. Consequently,
1159 * the return type of this function is a view to a set of writable objects.
1160 *
1161 * @param[in] vector The vector for which we want to have an array view
1162 * object.
1163 * @param[in] starting_index The index of the first element of the vector that
1164 * will be part of this view.
1165 * @param[in] size_of_view Number of elements in the new ArrayView.
1166 *
1167 * @pre <code>starting_index + size_of_view <= vector.size()</code>
1168 *
1169 * @relatesalso ArrayView
1170 */
1171 template <typename ElementType>
1172 inline ArrayView<ElementType>
1173 make_array_view(std::vector<ElementType> &vector,
1174 const std::size_t starting_index,
1175 const std::size_t size_of_view)
1176 {
1177 Assert(starting_index + size_of_view <= vector.size(),
1178 ExcMessage("The starting index and size of the view you want to "
1179 "create would lead to a view that extends beyond the end "
1180 "of the given vector."));
1181 return ArrayView<ElementType>(&vector[starting_index], size_of_view);
1182 }
1183
1184
1185
1186 /**
1187 * Create a view to a part of a std::vector object. This is equivalent to
1188 * initializing the ArrayView object with a pointer to the @p starting_index-th
1189 * element and the @p size_of_view as the length of the view.
1190 *
1191 * This function is used for @p const references to objects of vector type
1192 * because they contain immutable elements. Consequently, the return type of
1193 * this function is a view to a set of @p const objects.
1194 *
1195 * @param[in] vector The vector for which we want to have an array view
1196 * object.
1197 * @param[in] starting_index The index of the first element of the vector that
1198 * will be part of this view.
1199 * @param[in] size_of_view Number of elements in the new ArrayView.
1200 *
1201 * @pre <code>starting_index + size_of_view <= vector.size()</code>
1202 *
1203 * @relatesalso ArrayView
1204 */
1205 template <typename ElementType>
1206 inline ArrayView<const ElementType>
1207 make_array_view(const std::vector<ElementType> &vector,
1208 const std::size_t starting_index,
1209 const std::size_t size_of_view)
1210 {
1211 Assert(starting_index + size_of_view <= vector.size(),
1212 ExcMessage("The starting index and size of the view you want to "
1213 "create would lead to a view that extends beyond the end "
1214 "of the given vector."));
1215 return ArrayView<const ElementType>(&vector[starting_index], size_of_view);
1216 }
1217
1218
1219
1220 /**
1221 * Create a writable view to an entire AlignedVector object. See the
1222 * documentation of the corresponding overload for std::vector for more
1223 * information.
1224 *
1225 * @relatesalso ArrayView
1226 */
1227 template <typename ElementType>
1228 inline ArrayView<ElementType>
1229 make_array_view(AlignedVector<ElementType> &vector)
1230 {
1231 return ArrayView<ElementType>(vector.data(), vector.size());
1232 }
1233
1234
1235
1236 /**
1237 * Create a read-only view to an entire AlignedVector object. See the
1238 * documentation of the corresponding overload for std::vector for more
1239 * information.
1240 *
1241 * @relatesalso ArrayView
1242 */
1243 template <typename ElementType>
1244 inline ArrayView<const ElementType>
1245 make_array_view(const AlignedVector<ElementType> &vector)
1246 {
1247 return ArrayView<const ElementType>(vector.data(), vector.size());
1248 }
1249
1250
1251
1252 /**
1253 * Create a writable view to a part of an AlignedVector object. See the
1254 * documentation of the corresponding overload for std::vector for more
1255 * information.
1256 *
1257 * @relatesalso ArrayView
1258 */
1259 template <typename ElementType>
1260 inline ArrayView<ElementType>
1261 make_array_view(AlignedVector<ElementType> &vector,
1262 const std::size_t starting_index,
1263 const std::size_t size_of_view)
1264 {
1265 Assert(starting_index + size_of_view <= vector.size(),
1266 ExcMessage("The starting index and size of the view you want to "
1267 "create would lead to a view that extends beyond the end "
1268 "of the given vector."));
1269 return ArrayView<ElementType>(&vector[starting_index], size_of_view);
1270 }
1271
1272
1273
1274 /**
1275 * Create a read-only view to a part of an AlignedVector object. See the
1276 * documentation of the corresponding overload for std::vector for more
1277 * information.
1278 *
1279 * @relatesalso ArrayView
1280 */
1281 template <typename ElementType>
1282 inline ArrayView<const ElementType>
1283 make_array_view(const AlignedVector<ElementType> &vector,
1284 const std::size_t starting_index,
1285 const std::size_t size_of_view)
1286 {
1287 Assert(starting_index + size_of_view <= vector.size(),
1288 ExcMessage("The starting index and size of the view you want to "
1289 "create would lead to a view that extends beyond the end "
1290 "of the given vector."));
1291 return ArrayView<const ElementType>(&vector[starting_index], size_of_view);
1292 }
1293
1294
1295
1296 /**
1297 * Create a view to an entire std::array object. This is equivalent to
1298 * initializing an ArrayView object with a pointer to the first element and
1299 * the size of the given argument.
1300 *
1301 * This function is used for non-@p const references to objects of array
1302 * type. Such objects contain elements that can be written to. Consequently,
1303 * the return type of this function is a view to a set of writable objects.
1304 *
1305 * @param[in] array The std::array object for which we want to have an array
1306 * view object. The array view corresponds to the <em>entire</em> array.
1307 *
1308 * @relatesalso ArrayView
1309 */
1310 template <typename ElementType, std::size_t N>
1311 inline ArrayView<ElementType>
1312 make_array_view(std::array<ElementType, N> &array)
1313 {
1314 return ArrayView<ElementType>(array);
1315 }
1316
1317
1318
1319 /**
1320 * Create a view to an entire std::array object. This is equivalent to
1321 * initializing an ArrayView object with a pointer to the first element and
1322 * the size of the given argument.
1323 *
1324 * This function is used for @p const references to objects of array type
1325 * because they contain immutable elements. Consequently, the return type of
1326 * this function is a view to a set of @p const objects.
1327 *
1328 * @param[in] array The std::array object for which we want to have an array
1329 * view object. The array view corresponds to the <em>entire</em> array.
1330 *
1331 * @relatesalso ArrayView
1332 */
1333 template <typename ElementType, std::size_t N>
1334 inline ArrayView<const ElementType>
1335 make_array_view(const std::array<ElementType, N> &array)
1336 {
1337 return ArrayView<const ElementType>(array);
1338 }
1339
1340
1341
1342 /**
1343 * Create a view to an entire row of a Table<2> object. This is equivalent to
1344 * initializing an ArrayView object with a pointer to the first element of the
1345 * given row, and the length of the row as the length of the view.
1346 *
1347 * This function is used for non-@p const references to objects of Table type.
1348 * Such objects contain elements that can be written to. Consequently, the
1349 * return type of this function is a view to a set of writable objects.
1350 *
1351 * @param[in] table The Table for which we want to have an array view object.
1352 * The array view corresponds to an <em>entire</em> row.
1353 * @param[in] row The index of the row into the table to which this view
1354 * should correspond.
1355 *
1356 * @relatesalso ArrayView
1357 */
1358 template <typename ElementType>
1359 inline ArrayView<ElementType>
1360 make_array_view(Table<2, ElementType> &table,
1361 const typename Table<2, ElementType>::size_type row)
1362 {
1363 AssertIndexRange(row, table.size()[0]);
1364 return ArrayView<ElementType>(&table[row][0], table.size()[1]);
1365 }
1366
1367
1368
1369 /**
1370 * Create a view to an entire Table<2> object. This is equivalent to
1371 * initializing an ArrayView object with a pointer to the first element of the
1372 * given table, and the number of table entries as the length of the view.
1373 *
1374 * This function is used for non-@p const references to objects of Table type.
1375 * Such objects contain elements that can be written to. Consequently, the
1376 * return type of this function is a view to a set of writable objects.
1377 *
1378 * @param[in] table The Table for which we want to have an array view object.
1379 * The array view corresponds to the <em>entire</em> table but the order in
1380 * which the entries are presented in the array is an implementation detail
1381 * and should not be relied upon.
1382 *
1383 * @relatesalso ArrayView
1384 */
1385 template <typename ElementType>
1386 inline ArrayView<ElementType>
1387 make_array_view(Table<2, ElementType> &table)
1388 {
1389 return ArrayView<ElementType>(&table[0][0], table.n_elements());
1390 }
1391
1392
1393
1394 /**
1395 * Create a view to an entire Table<2> object. This is equivalent to
1396 * initializing an ArrayView object with a pointer to the first element of the
1397 * given table, and the number of table entries as the length of the view.
1398 *
1399 * This function is used for @p const references to objects of Table type
1400 * because they contain immutable elements. Consequently, the return type of
1401 * this function is a view to a set of @p const objects.
1402 *
1403 * @param[in] table The Table for which we want to have an array view object.
1404 * The array view corresponds to the <em>entire</em> table but the order in
1405 * which the entries are presented in the array is an implementation detail
1406 * and should not be relied upon.
1407 *
1408 * @relatesalso ArrayView
1409 */
1410 template <typename ElementType>
1411 inline ArrayView<const ElementType>
1412 make_array_view(const Table<2, ElementType> &table)
1413 {
1414 return ArrayView<const ElementType>(&table[0][0], table.n_elements());
1415 }
1416
1417
1418 /**
1419 * Create a view to an entire LAPACKFullMatrix object. This is equivalent to
1420 * initializing an ArrayView object with a pointer to the first element of the
1421 * given object, and the number entries as the length of the view.
1422 *
1423 * This function is used for @p non-const references to objects of
1424 * LAPACKFullMatrix type. Such objects contain elements that can be written to.
1425 * Consequently, the return type of this function is a view to a set of
1426 * @p non-const objects.
1427 *
1428 * @param[in] matrix The LAPACKFullMatrix for which we want to have an array
1429 * view object. The array view corresponds to the <em>entire</em> object but
1430 * the order in which the entries are presented in the array is an
1431 * implementation detail and should not be relied upon.
1432 *
1433 * @relatesalso ArrayView
1434 */
1435 template <typename ElementType>
1436 inline ArrayView<ElementType>
1437 make_array_view(LAPACKFullMatrix<ElementType> &matrix)
1438 {
1439 return ArrayView<ElementType>(&matrix(0, 0), matrix.n_elements());
1440 }
1441
1442
1443
1444 /**
1445 * Create a view to an entire LAPACKFullMatrix object. This is equivalent to
1446 * initializing an ArrayView object with a pointer to the first element of the
1447 * given object, and the number of entries as the length of the view.
1448 *
1449 * This function is used for @p const references to objects of LAPACKFullMatrix
1450 * type because they contain immutable elements. Consequently, the return type
1451 * of this function is a view to a set of @p const objects.
1452 *
1453 * @param[in] matrix The LAPACKFullMatrix for which we want to have an array
1454 * view object. The array view corresponds to the <em>entire</em> object but
1455 * the order in which the entries are presented in the array is an
1456 * implementation detail and should not be relied upon.
1457 *
1458 * @relatesalso ArrayView
1459 */
1460 template <typename ElementType>
1461 inline ArrayView<const ElementType>
1462 make_array_view(const LAPACKFullMatrix<ElementType> &matrix)
1463 {
1464 return ArrayView<const ElementType>(&matrix(0, 0), matrix.n_elements());
1465 }
1466
1467
1468
1469 /**
1470 * Create a view to an entire row of a Table<2> object. This is equivalent to
1471 * initializing an ArrayView object with a pointer to the first element of the
1472 * given row, and the length of the row as the length of the view.
1473 *
1474 * This function is used for @p const references to objects of Table type
1475 * because they contain immutable elements. Consequently, the return type of
1476 * this function is a view to a set of @p const objects.
1477 *
1478 * @param[in] table The Table for which we want to have an array view object.
1479 * The array view corresponds to an <em>entire</em> row.
1480 * @param[in] row The index of the row into the table to which this view
1481 * should correspond.
1482 *
1483 * @relatesalso ArrayView
1484 */
1485 template <typename ElementType>
1486 inline ArrayView<const ElementType>
1487 make_array_view(const Table<2, ElementType> &table,
1488 const typename Table<2, ElementType>::size_type row)
1489 {
1490 AssertIndexRange(row, table.size()[0]);
1491 return ArrayView<const ElementType>(&table[row][0], table.size()[1]);
1492 }
1493
1494
1495
1496 /**
1497 * Create a view to (a part of) a row of a Table<2> object.
1498 *
1499 * This function is used for non-@p const references to objects of Table type.
1500 * Such objects contain elements that can be written to. Consequently, the
1501 * return type of this function is a view to a set of writable objects.
1502 *
1503 * @param[in] table The Table for which we want to have an array view object.
1504 * The array view corresponds to an <em>entire</em> row.
1505 * @param[in] row The index of the row into the table to which this view
1506 * should correspond.
1507 * @param[in] starting_column The index of the column into the given row of
1508 * the table that corresponds to the first element of this view.
1509 * @param[in] size_of_view The number of elements this view should have. This
1510 * corresponds to the number of columns in the current row to which the view
1511 * should correspond.
1512 *
1513 * @relatesalso ArrayView
1514 */
1515 template <typename ElementType>
1516 inline ArrayView<ElementType>
1517 make_array_view(Table<2, ElementType> &table,
1518 const typename Table<2, ElementType>::size_type row,
1519 const typename Table<2, ElementType>::size_type starting_column,
1520 const std::size_t size_of_view)
1521 {
1522 AssertIndexRange(row, table.size()[0]);
1523 AssertIndexRange(starting_column, table.size()[1]);
1524 Assert(starting_column + size_of_view <= table.size()[1],
1525 ExcMessage("The starting index and size of the view you want to "
1526 "create would lead to a view that extends beyond the end "
1527 "of a column of the given table."));
1528 return ArrayView<ElementType>(&table[row][starting_column], size_of_view);
1529 }
1530
1531
1532
1533 /**
1534 * Create a view to (a part of) a row of a Table<2> object.
1535 *
1536 * This function is used for @p const references to objects of Table type
1537 * because they contain immutable elements. Consequently, the return type of
1538 * this function is a view to a set of @p const objects.
1539 *
1540 * @param[in] table The Table for which we want to have an array view object.
1541 * The array view corresponds to an <em>entire</em> row.
1542 * @param[in] row The index of the row into the table to which this view
1543 * should correspond.
1544 * @param[in] starting_column The index of the column into the given row of
1545 * the table that corresponds to the first element of this view.
1546 * @param[in] size_of_view The number of elements this view should have. This
1547 * corresponds to the number of columns in the current row to which the view
1548 * should correspond.
1549 *
1550 * @relatesalso ArrayView
1551 */
1552 template <typename ElementType>
1553 inline ArrayView<const ElementType>
1554 make_array_view(const Table<2, ElementType> &table,
1555 const typename Table<2, ElementType>::size_type row,
1556 const typename Table<2, ElementType>::size_type starting_column,
1557 const std::size_t size_of_view)
1558 {
1559 AssertIndexRange(row, table.size()[0]);
1560 AssertIndexRange(starting_column, table.size()[1]);
1561 Assert(starting_column + size_of_view <= table.size()[1],
1562 ExcMessage("The starting index and size of the view you want to "
1563 "create would lead to a view that extends beyond the end "
1564 "of a column of the given table."));
1565 return ArrayView<const ElementType>(&table[row][starting_column],
1566 size_of_view);
1567 }
1568
1569
1570
1571 /*
1572 * Create a view that doesn't allow the container it points to to be modified.
1573 * This is useful if the object passed in is not `const` already and a function
1574 * requires a view to constant memory in its signature.
1575 *
1576 * This function returns an object of type `ArrayView<const T>` where `T` is the
1577 * element type of the container.
1578 *
1579 * @relatesalso ArrayView
1580 */
1581 template <typename Container>
1582 inline auto
1583 make_const_array_view(const Container &container)
1584 -> decltype(make_array_view(container))
1585 {
1586 return make_array_view(container);
1587 }
1588
1589
1590 DEAL_II_NAMESPACE_CLOSE
1591
1592 #endif