array_view.h

Go to the documentation of this file.

// ------------------------------------------------------------------------
//
// SPDX-License-Identifier: LGPL-2.1-or-later
// Copyright (C) 2015 - 2024 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 <deal.II/base/config.h>
 
#include <deal.II/base/exceptions.h>
#include <deal.II/base/memory_space.h>
#include <deal.II/base/symmetric_tensor.h>
#include <deal.II/base/template_constraints.h>
#include <deal.II/base/tensor.h>
 
#include <boost/container/small_vector.hpp>
 
#include <array>
#include <type_traits>
#include <vector>
 
DEAL_II_NAMESPACE_OPEN
 
// Forward declaration
template <class T>
class AlignedVector;
 
template <int N, typename T>
class Table;
 
template <typename number>
class LAPACKFullMatrix;
 
 
template <typename ElementType, typename MemorySpaceType = MemorySpace::Host>
class ArrayView
{
public:
  using value_type = ElementType;
 
  using iterator = value_type *;
 
  using const_iterator = const ElementType *;
 
  ArrayView();
 
  ArrayView(value_type *starting_element, const std::size_t n_elements);
 
  ArrayView(
    const ArrayView<std::remove_cv_t<value_type>, MemorySpaceType> &view);
 
  explicit ArrayView(value_type &element);
 
#ifdef DEAL_II_HAVE_CXX20
  template <typename ContiguousContainer>
  ArrayView(const ContiguousContainer &container)
    requires(std::is_same_v<
               std::remove_cv_t<ElementType>,
               std::remove_cv_t<typename ContiguousContainer::value_type>> &&
             std::is_const_v<ElementType> &&
             concepts::is_contiguous_container<ContiguousContainer>);
 
  template <typename ContiguousContainer>
  ArrayView(ContiguousContainer &container)
    requires(std::is_same_v<
               std::remove_cv_t<ElementType>,
               std::remove_cv_t<typename ContiguousContainer::value_type>> &&
             concepts::is_contiguous_container<ContiguousContainer>);
 
#else
 
 
  template <typename ContiguousContainer,
            typename = decltype(std::data(std::declval<ContiguousContainer>())),
            typename = decltype(std::size(std::declval<ContiguousContainer>())),
            typename = std::enable_if_t<
              std::is_same_v<
                std::remove_cv_t<ElementType>,
                std::remove_cv_t<typename ContiguousContainer::value_type>> &&
              std::is_const_v<ElementType>>>
  ArrayView(const ContiguousContainer &container);
 
  template <typename ContiguousContainer,
            typename = decltype(std::data(std::declval<ContiguousContainer>())),
            typename = decltype(std::size(std::declval<ContiguousContainer>())),
            typename = std::enable_if_t<std::is_same_v<
              std::remove_cv_t<ElementType>,
              std::remove_cv_t<typename ContiguousContainer::value_type>>>>
  ArrayView(ContiguousContainer &container);
 
#endif
 
  template <std::size_t N>
  ArrayView(value_type (&array)[N]);
 
  ArrayView(
    const std::initializer_list<std::remove_cv_t<value_type>> &initializer_list)
    DEAL_II_CXX20_REQUIRES(std::is_const_v<ElementType>);
 
  void
  reinit(value_type *starting_element, const std::size_t n_elements);
 
  bool
  operator==(
    const ArrayView<const value_type, MemorySpaceType> &other_view) const;
 
  bool
  operator==(const ArrayView<std::remove_cv_t<value_type>, MemorySpaceType>
               &other_view) const;
 
  bool
  operator!=(
    const ArrayView<const value_type, MemorySpaceType> &other_view) const;
 
  bool
  operator!=(const ArrayView<std::remove_cv_t<value_type>, MemorySpaceType>
               &other_view) const;
 
  std::size_t
  size() const;
 
  bool
  empty() const;
 
  DEAL_II_HOST_DEVICE value_type *
  data() const noexcept;
 
  iterator
  begin() const;
 
  iterator
  end() const;
 
  const_iterator
  cbegin() const;
 
  const_iterator
  cend() const;
 
  value_type &
  operator[](const std::size_t i) const;
 
private:
  value_type *starting_element;
 
  std::size_t n_elements;
 
  friend class ArrayView<const ElementType, MemorySpaceType>;
};
 
 
 
//---------------------------------------------------------------------------
 
 
template <typename ElementType, typename MemorySpaceType>
inline ArrayView<ElementType, MemorySpaceType>::ArrayView()
  : starting_element(nullptr)
  , n_elements(0)
{}
 
 
 
template <typename ElementType, typename MemorySpaceType>
inline ArrayView<ElementType, MemorySpaceType>::ArrayView(
  value_type       *starting_element,
  const std::size_t n_elements)
  :
#ifdef DEBUG
  starting_element(n_elements > 0 ? starting_element : nullptr)
#else
  starting_element(starting_element)
#endif
  , n_elements(n_elements)
{}
 
 
 
template <typename ElementType, typename MemorySpaceType>
inline void
ArrayView<ElementType, MemorySpaceType>::reinit(value_type *starting_element,
                                                const std::size_t n_elements)
{
#ifdef DEBUG
  if (n_elements > 0)
    this->starting_element = starting_element;
  else
    this->starting_element = nullptr;
#else
  this->starting_element = starting_element;
#endif
  this->n_elements = n_elements;
}
 
 
 
template <typename ElementType, typename MemorySpaceType>
inline ArrayView<ElementType, MemorySpaceType>::ArrayView(ElementType &element)
  : starting_element(&element)
  , n_elements(1)
{}
 
 
 
template <typename ElementType, typename MemorySpaceType>
inline ArrayView<ElementType, MemorySpaceType>::ArrayView(
  const ArrayView<std::remove_cv_t<value_type>, MemorySpaceType> &view)
  : starting_element(view.starting_element)
  , n_elements(view.n_elements)
{}
 
 
#ifdef DEAL_II_HAVE_CXX20
 
template <typename ElementType, typename MemorySpaceType>
template <typename ContiguousContainer>
inline ArrayView<ElementType, MemorySpaceType>::ArrayView(
  const ContiguousContainer &container)
  requires(std::is_same_v<
             std::remove_cv_t<ElementType>,
             std::remove_cv_t<typename ContiguousContainer::value_type>> &&
           std::is_const_v<ElementType> &&
           concepts::is_contiguous_container<ContiguousContainer>)
  : // use delegating constructor
  ArrayView(container.data(), container.size())
{}
 
 
 
template <typename ElementType, typename MemorySpaceType>
template <typename ContiguousContainer>
inline ArrayView<ElementType, MemorySpaceType>::ArrayView(
  ContiguousContainer &container)
  requires(std::is_same_v<
             std::remove_cv_t<ElementType>,
             std::remove_cv_t<typename ContiguousContainer::value_type>> &&
           concepts::is_contiguous_container<ContiguousContainer>)
  : // use delegating constructor
  ArrayView(std::data(container), std::size(container))
{}
 
 
#else
 
template <typename ElementType, typename MemorySpaceType>
template <typename ContiguousContainer, typename, typename, typename>
inline ArrayView<ElementType, MemorySpaceType>::ArrayView(
  const ContiguousContainer &container)
  : // use delegating constructor
  ArrayView(container.data(), container.size())
{}
 
 
 
template <typename ElementType, typename MemorySpaceType>
template <typename ContiguousContainer, typename, typename, typename>
inline ArrayView<ElementType, MemorySpaceType>::ArrayView(
  ContiguousContainer &container)
  : // use delegating constructor
  ArrayView(std::data(container), std::size(container))
{}
 
#endif
 
 
 
template <typename ElementType, typename MemorySpaceType>
template <std::size_t N>
inline ArrayView<ElementType, MemorySpaceType>::ArrayView(
  ElementType (&array)[N])
  : ArrayView(&array[0], N)
{}
 
 
template <typename ElementType, typename MemorySpaceType>
inline ArrayView<ElementType, MemorySpaceType>::ArrayView(
  const std::initializer_list<std::remove_cv_t<value_type>> &initializer)
  DEAL_II_CXX20_REQUIRES(std::is_const_v<ElementType>)
  : // use delegating constructor
  ArrayView(initializer.begin(), initializer.size())
{}
 
 
 
template <typename ElementType, typename MemorySpaceType>
inline bool
ArrayView<ElementType, MemorySpaceType>::operator==(
  const ArrayView<const value_type, MemorySpaceType> &other_view) const
{
  return (other_view.data() == starting_element) &&
         (other_view.size() == n_elements);
}
 
 
 
template <typename ElementType, typename MemorySpaceType>
inline bool
ArrayView<ElementType, MemorySpaceType>::operator==(
  const ArrayView<std::remove_cv_t<value_type>, MemorySpaceType> &other_view)
  const
{
  return (other_view.data() == starting_element) &&
         (other_view.size() == n_elements);
}
 
 
 
template <typename ElementType, typename MemorySpaceType>
inline bool
ArrayView<ElementType, MemorySpaceType>::operator!=(
  const ArrayView<const value_type, MemorySpaceType> &other_view) const
{
  return !(*this == other_view);
}
 
 
 
template <typename ElementType, typename MemorySpaceType>
inline DEAL_II_HOST_DEVICE
  typename ArrayView<ElementType, MemorySpaceType>::value_type *
  ArrayView<ElementType, MemorySpaceType>::data() const noexcept
{
  if (n_elements == 0)
    return nullptr;
  else
    return starting_element;
}
 
 
 
template <typename ElementType, typename MemorySpaceType>
inline bool
ArrayView<ElementType, MemorySpaceType>::operator!=(
  const ArrayView<std::remove_cv_t<value_type>, MemorySpaceType> &other_view)
  const
{
  return !(*this == other_view);
}
 
 
 
template <typename ElementType, typename MemorySpaceType>
inline std::size_t
ArrayView<ElementType, MemorySpaceType>::size() const
{
  return n_elements;
}
 
 
 
template <typename ElementType, typename MemorySpaceType>
inline bool
ArrayView<ElementType, MemorySpaceType>::empty() const
{
  return n_elements == 0;
}
 
 
 
template <typename ElementType, typename MemorySpaceType>
inline typename ArrayView<ElementType, MemorySpaceType>::iterator
ArrayView<ElementType, MemorySpaceType>::begin() const
{
  return starting_element;
}
 
 
 
template <typename ElementType, typename MemorySpaceType>
inline typename ArrayView<ElementType, MemorySpaceType>::iterator
ArrayView<ElementType, MemorySpaceType>::end() const
{
  return starting_element + n_elements;
}
 
 
 
template <typename ElementType, typename MemorySpaceType>
inline typename ArrayView<ElementType, MemorySpaceType>::const_iterator
ArrayView<ElementType, MemorySpaceType>::cbegin() const
{
  return starting_element;
}
 
 
 
template <typename ElementType, typename MemorySpaceType>
inline typename ArrayView<ElementType, MemorySpaceType>::const_iterator
ArrayView<ElementType, MemorySpaceType>::cend() const
{
  return starting_element + n_elements;
}
 
 
 
template <typename ElementType, typename MemorySpaceType>
inline typename ArrayView<ElementType, MemorySpaceType>::value_type &
ArrayView<ElementType, MemorySpaceType>::operator[](const std::size_t i) const
{
  AssertIndexRange(i, n_elements);
 
  return *(starting_element + i);
}
 
 
 
template <typename ElementType, std::size_t stride = 1>
class StridedArrayView
{
public:
  using value_type = ElementType;
 
  StridedArrayView(value_type *starting_element, const std::size_t n_elements);
 
  std::size_t
  size() const;
 
  bool
  empty() const;
 
  value_type *
  data() const noexcept;
 
  value_type &
  operator[](const std::size_t i) const;
 
protected:
  value_type *starting_element;
 
  std::size_t n_elements;
};
 
 
 
template <typename ElementType, std::size_t stride>
typename StridedArrayView<ElementType, stride>::value_type &
StridedArrayView<ElementType, stride>::operator[](const std::size_t i) const
{
  AssertIndexRange(i, this->n_elements);
 
  return *(this->starting_element + stride * i);
}
 
 
 
template <typename ElementType, std::size_t stride>
typename StridedArrayView<ElementType, stride>::value_type *
StridedArrayView<ElementType, stride>::data() const noexcept
{
  if (this->n_elements == 0)
    return nullptr;
  else
    return this->starting_element;
}
 
 
 
template <typename ElementType, std::size_t stride>
bool
StridedArrayView<ElementType, stride>::empty() const
{
  return this->n_elements == 0;
}
 
 
 
template <typename ElementType, std::size_t stride>
std::size_t
StridedArrayView<ElementType, stride>::size() const
{
  return this->n_elements;
}
 
 
 
template <typename ElementType, std::size_t stride>
StridedArrayView<ElementType, stride>::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
  {
    template <class Iterator>
    bool
    is_contiguous(const Iterator &first, const Iterator &last)
    {
      const auto n = std::distance(first, last);
      for (std::decay_t<decltype(n)> i = 0; i < n; ++i)
        if (std::addressof(*(std::next(first, i))) !=
            std::next(std::addressof(*first), i))
          return false;
      return true;
    }
 
 
    template <class T>
    constexpr bool
    is_contiguous(T *, T *)
    {
      return true;
    }
  } // namespace ArrayViewHelper
} // namespace internal
#endif
 
 
 
template <typename Iterator, typename MemorySpaceType = MemorySpace::Host>
ArrayView<
  std::remove_reference_t<typename std::iterator_traits<Iterator>::reference>,
  MemorySpaceType>
make_array_view(const Iterator begin, const Iterator end)
{
  static_assert(
    std::is_same_v<typename std::iterator_traits<Iterator>::iterator_category,
                   typename std::random_access_iterator_tag>
#ifdef DEAL_II_HAVE_CXX20
      ||
      std::is_same_v<typename std::iterator_traits<Iterator>::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<typename std::iterator_traits<Iterator>::reference>,
    MemorySpaceType>(std::addressof(*begin), end - begin);
}
 
 
 
template <typename ElementType, typename MemorySpaceType = MemorySpace::Host>
ArrayView<ElementType, MemorySpaceType>
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<ElementType, MemorySpaceType>(begin, end - begin);
}
 
 
 
template <typename Number, typename MemorySpaceType>
inline ArrayView<const Number, MemorySpaceType>
make_array_view(const ArrayView<Number, MemorySpaceType> &array_view)
{
  return make_array_view(array_view.cbegin(), array_view.cend());
}
 
 
 
template <typename Number, typename MemorySpaceType>
inline ArrayView<Number, MemorySpaceType>
make_array_view(ArrayView<Number, MemorySpaceType> &array_view)
{
  return make_array_view(array_view.begin(), array_view.end());
}
 
 
 
template <int rank, int dim, typename Number>
DEAL_II_DEPRECATED inline ArrayView<const Number>
make_array_view(const Tensor<rank, dim, Number> &tensor)
{
  static_assert(rank == 1,
                "This function is only available for rank-1 tensors "
                "because higher-rank tensors may not store their elements "
                "in a contiguous array.");
 
  return make_array_view(tensor.begin_raw(), tensor.end_raw());
}
 
 
 
template <int rank, int dim, typename Number>
DEAL_II_DEPRECATED inline ArrayView<Number>
make_array_view(Tensor<rank, dim, Number> &tensor)
{
  static_assert(rank == 1,
                "This function is only available for rank-1 tensors "
                "because higher-rank tensors may not store their elements "
                "in a contiguous array.");
 
  return make_array_view(tensor.begin_raw(), tensor.end_raw());
}
 
 
 
template <int rank, int dim, typename Number>
DEAL_II_DEPRECATED inline ArrayView<const Number>
make_array_view(const SymmetricTensor<rank, dim, Number> &tensor)
{
  return make_array_view(tensor.begin_raw(), tensor.end_raw());
}
 
 
 
template <int rank, int dim, typename Number>
DEAL_II_DEPRECATED inline ArrayView<Number>
make_array_view(SymmetricTensor<rank, dim, Number> &tensor)
{
  return make_array_view(tensor.begin_raw(), tensor.end_raw());
}
 
 
 
template <typename ElementType, int N>
inline ArrayView<ElementType>
make_array_view(ElementType (&array)[N])
{
  return ArrayView<ElementType>(array, N);
}
 
 
 
template <typename ElementType>
inline ArrayView<ElementType>
make_array_view(Vector<ElementType> &vector)
{
  return ArrayView<ElementType>(vector.begin(), vector.size());
}
 
 
 
template <typename ElementType>
inline ArrayView<const ElementType>
make_array_view(const Vector<ElementType> &vector)
{
  return ArrayView<const ElementType>(vector.begin(), vector.size());
}
 
 
 
template <typename ElementType>
inline ArrayView<ElementType>
make_array_view(std::vector<ElementType> &vector)
{
  return ArrayView<ElementType>(vector.data(), vector.size());
}
 
 
 
template <typename ElementType>
inline ArrayView<const ElementType>
make_array_view(const std::vector<ElementType> &vector)
{
  return ArrayView<const ElementType>(vector.data(), vector.size());
}
 
 
 
template <typename ElementType>
inline ArrayView<ElementType>
make_array_view(std::vector<ElementType> &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<ElementType>(&vector[starting_index], size_of_view);
}
 
 
 
template <typename ElementType>
inline ArrayView<const ElementType>
make_array_view(const std::vector<ElementType> &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<const ElementType>(&vector[starting_index], size_of_view);
}
 
 
 
template <typename ElementType>
inline ArrayView<ElementType>
make_array_view(AlignedVector<ElementType> &vector)
{
  return ArrayView<ElementType>(vector.data(), vector.size());
}
 
 
 
template <typename ElementType>
inline ArrayView<const ElementType>
make_array_view(const AlignedVector<ElementType> &vector)
{
  return ArrayView<const ElementType>(vector.data(), vector.size());
}
 
 
 
template <typename ElementType>
inline ArrayView<ElementType>
make_array_view(AlignedVector<ElementType> &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<ElementType>(&vector[starting_index], size_of_view);
}
 
 
 
template <typename ElementType>
inline ArrayView<const ElementType>
make_array_view(const AlignedVector<ElementType> &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<const ElementType>(&vector[starting_index], size_of_view);
}
 
 
 
template <typename ElementType, std::size_t N>
inline ArrayView<ElementType>
make_array_view(std::array<ElementType, N> &array)
{
  return ArrayView<ElementType>(array);
}
 
 
 
template <typename ElementType, std::size_t N>
inline ArrayView<const ElementType>
make_array_view(const std::array<ElementType, N> &array)
{
  return ArrayView<const ElementType>(array);
}
 
 
 
template <typename ElementType>
inline ArrayView<ElementType>
make_array_view(Table<2, ElementType>                          &table,
                const typename Table<2, ElementType>::size_type row)
{
  AssertIndexRange(row, table.size()[0]);
  return ArrayView<ElementType>(&table[row][0], table.size()[1]);
}
 
 
 
template <typename ElementType>
inline ArrayView<ElementType>
make_array_view(Table<2, ElementType> &table)
{
  return ArrayView<ElementType>(&table[0][0], table.n_elements());
}
 
 
 
template <typename ElementType>
inline ArrayView<const ElementType>
make_array_view(const Table<2, ElementType> &table)
{
  return ArrayView<const ElementType>(&table[0][0], table.n_elements());
}
 
 
template <typename ElementType>
inline ArrayView<ElementType>
make_array_view(LAPACKFullMatrix<ElementType> &matrix)
{
  return ArrayView<ElementType>(&matrix(0, 0), matrix.n_elements());
}
 
 
 
template <typename ElementType>
inline ArrayView<const ElementType>
make_array_view(const LAPACKFullMatrix<ElementType> &matrix)
{
  return ArrayView<const ElementType>(&matrix(0, 0), matrix.n_elements());
}
 
 
 
template <typename ElementType>
inline ArrayView<const ElementType>
make_array_view(const Table<2, ElementType>                    &table,
                const typename Table<2, ElementType>::size_type row)
{
  AssertIndexRange(row, table.size()[0]);
  return ArrayView<const ElementType>(&table[row][0], table.size()[1]);
}
 
 
 
template <typename ElementType>
inline ArrayView<ElementType>
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<ElementType>(&table[row][starting_column], size_of_view);
}
 
 
 
template <typename ElementType>
inline ArrayView<const ElementType>
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<const ElementType>(&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<const T>` where `T` is the
 * element type of the container.
 *
 * @relatesalso ArrayView
 */
template <typename Container>
inline auto
make_const_array_view(const Container &container)
  -> decltype(make_array_view(container))
{
  return make_array_view(container);
}
 
 
DEAL_II_NAMESPACE_CLOSE
 
#endif