Eigen/src/Core/Block.h

// This file is part of Eigen, a lightweight C++ template library
// for linear algebra.
//
// Copyright (C) 2008 Gael Guennebaud <gael.guennebaud@inria.fr>
// Copyright (C) 2006-2010 Benoit Jacob <jacob.benoit.1@gmail.com>
//
// This Source Code Form is subject to the terms of the Mozilla
// Public License v. 2.0. If a copy of the MPL was not distributed
// with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
// SPDX-License-Identifier: MPL-2.0

#ifndef EIGEN_BLOCK_H
#define EIGEN_BLOCK_H

// IWYU pragma: private
#include "./InternalHeaderCheck.h"

namespace Eigen {

namespace internal {
template <typename XprType_, int BlockRows, int BlockCols, bool InnerPanel_>
struct traits<Block<XprType_, BlockRows, BlockCols, InnerPanel_>> : traits<XprType_> {
  using Scalar = typename traits<XprType_>::Scalar;
  using StorageKind = typename traits<XprType_>::StorageKind;
  using XprKind = typename traits<XprType_>::XprKind;
  using XprTypeNested = typename ref_selector<XprType_>::type;
  using XprTypeNested_ = std::remove_reference_t<XprTypeNested>;
  enum {
    MatrixRows = traits<XprType_>::RowsAtCompileTime,
    MatrixCols = traits<XprType_>::ColsAtCompileTime,
    RowsAtCompileTime = MatrixRows == 0 ? 0 : BlockRows,
    ColsAtCompileTime = MatrixCols == 0 ? 0 : BlockCols,
    MaxRowsAtCompileTime = BlockRows == 0                 ? 0
                           : RowsAtCompileTime != Dynamic ? int(RowsAtCompileTime)
                                                          : int(traits<XprType_>::MaxRowsAtCompileTime),
    MaxColsAtCompileTime = BlockCols == 0                 ? 0
                           : ColsAtCompileTime != Dynamic ? int(ColsAtCompileTime)
                                                          : int(traits<XprType_>::MaxColsAtCompileTime),

    XprTypeIsRowMajor = (int(traits<XprType_>::Flags) & RowMajorBit) != 0,
    IsRowMajor = (MaxRowsAtCompileTime == 1 && MaxColsAtCompileTime != 1)   ? 1
                 : (MaxColsAtCompileTime == 1 && MaxRowsAtCompileTime != 1) ? 0
                                                                            : XprTypeIsRowMajor,
    HasSameStorageOrderAsXprType = (IsRowMajor == XprTypeIsRowMajor),
    InnerSize = IsRowMajor ? int(ColsAtCompileTime) : int(RowsAtCompileTime),
    InnerStrideAtCompileTime = HasSameStorageOrderAsXprType ? int(inner_stride_at_compile_time<XprType_>::value)
                                                            : int(outer_stride_at_compile_time<XprType_>::value),
    OuterStrideAtCompileTime = HasSameStorageOrderAsXprType ? int(outer_stride_at_compile_time<XprType_>::value)
                                                            : int(inner_stride_at_compile_time<XprType_>::value),

    // FIXME, this traits is rather specialized for dense object and it needs to be cleaned further
    FlagsLvalueBit = is_lvalue<XprType_>::value ? LvalueBit : 0,
    FlagsRowMajorBit = IsRowMajor ? RowMajorBit : 0,
    Flags = (traits<XprType_>::Flags & (DirectAccessBit | (InnerPanel_ ? CompressedAccessBit : 0))) | FlagsLvalueBit |
            FlagsRowMajorBit,
    // FIXME DirectAccessBit should not be handled by expressions
    //
    // Alignment is needed by MapBase's assertions
    // We can safely set it to false here. Internal alignment errors will be detected by an eigen_internal_assert in the
    // respective evaluator
    Alignment = 0,
    InnerPanel = InnerPanel_ ? 1 : 0
  };
};

template <typename XprType, int BlockRows = Dynamic, int BlockCols = Dynamic, bool InnerPanel = false,
          bool HasDirectAccess = internal::has_direct_access<XprType>::value>
class BlockImpl_dense;

}  // end namespace internal

template <typename XprType, int BlockRows, int BlockCols, bool InnerPanel, typename StorageKind>
class BlockImpl;

/** \class Block
 * \ingroup Core_Module
 *
 * \brief Expression of a fixed-size or dynamic-size block
 *
 * \tparam XprType the type of the expression in which we are taking a block
 * \tparam BlockRows the number of rows of the block we are taking at compile time (optional)
 * \tparam BlockCols the number of columns of the block we are taking at compile time (optional)
 * \tparam InnerPanel is true, if the block maps to a set of rows of a row major matrix or
 *         to set of columns of a column major matrix (optional). The parameter allows to determine
 *         at compile time whether aligned access is possible on the block expression.
 *
 * This class represents an expression of either a fixed-size or dynamic-size block. It is the return
 * type of DenseBase::block(Index,Index,Index,Index) and DenseBase::block<int,int>(Index,Index) and
 * most of the time this is the only way it is used.
 *
 * However, if you want to directly manipulate block expressions,
 * for instance if you want to write a function returning such an expression, you
 * will need to use this class.
 *
 * Here is an example illustrating the dynamic case:
 * \include class_Block.cpp
 * Output: \verbinclude class_Block.out
 *
 * \note Even though this expression has dynamic size, in the case where \a XprType
 * has fixed size, this expression inherits a fixed maximal size which means that evaluating
 * it does not cause a dynamic memory allocation.
 *
 * Here is an example illustrating the fixed-size case:
 * \include class_FixedBlock.cpp
 * Output: \verbinclude class_FixedBlock.out
 *
 * \sa DenseBase::block(Index,Index,Index,Index), DenseBase::block(Index,Index), class VectorBlock
 */
template <typename XprType, int BlockRows, int BlockCols, bool InnerPanel>
class Block
    : public BlockImpl<XprType, BlockRows, BlockCols, InnerPanel, typename internal::traits<XprType>::StorageKind> {
  using Impl = BlockImpl<XprType, BlockRows, BlockCols, InnerPanel, typename internal::traits<XprType>::StorageKind>;
  using BlockHelper = internal::block_xpr_helper<Block>;

 public:
  // typedef typename Impl::Base Base;
  using Base = Impl;
  EIGEN_GENERIC_PUBLIC_INTERFACE(Block)
  EIGEN_INHERIT_ASSIGNMENT_OPERATORS(Block)

  using NestedExpression = internal::remove_all_t<XprType>;

  /** Column or Row constructor
   */
  EIGEN_DEVICE_FUNC constexpr EIGEN_STRONG_INLINE Block(XprType& xpr, Index i) : Impl(xpr, i) {
    eigen_assert((i >= 0) && (((BlockRows == 1) && (BlockCols == XprType::ColsAtCompileTime) && i < xpr.rows()) ||
                              ((BlockRows == XprType::RowsAtCompileTime) && (BlockCols == 1) && i < xpr.cols())));
  }

  /** Fixed-size constructor
   */
  EIGEN_DEVICE_FUNC constexpr EIGEN_STRONG_INLINE Block(XprType& xpr, Index startRow, Index startCol)
      : Impl(xpr, startRow, startCol) {
    EIGEN_STATIC_ASSERT(RowsAtCompileTime != Dynamic && ColsAtCompileTime != Dynamic,
                        THIS_METHOD_IS_ONLY_FOR_FIXED_SIZE)
    eigen_assert(startRow >= 0 && BlockRows >= 0 && startRow + BlockRows <= xpr.rows() && startCol >= 0 &&
                 BlockCols >= 0 && startCol + BlockCols <= xpr.cols());
  }

  /** Dynamic-size constructor
   */
  EIGEN_DEVICE_FUNC constexpr EIGEN_STRONG_INLINE Block(XprType& xpr, Index startRow, Index startCol, Index blockRows,
                                                        Index blockCols)
      : Impl(xpr, startRow, startCol, blockRows, blockCols) {
    eigen_assert((RowsAtCompileTime == Dynamic || RowsAtCompileTime == blockRows) &&
                 (ColsAtCompileTime == Dynamic || ColsAtCompileTime == blockCols));
    eigen_assert(startRow >= 0 && blockRows >= 0 && startRow <= xpr.rows() - blockRows && startCol >= 0 &&
                 blockCols >= 0 && startCol <= xpr.cols() - blockCols);
  }

  // convert nested blocks (e.g. Block<Block<MatrixType>>) to a simple block expression (Block<MatrixType>)

  static constexpr bool UnwoundInnerPanel = BlockHelper::is_inner_panel(true);
  using ConstUnwindReturnType = Block<const typename BlockHelper::BaseType, BlockRows, BlockCols, UnwoundInnerPanel>;
  using UnwindReturnType = Block<typename BlockHelper::BaseType, BlockRows, BlockCols, UnwoundInnerPanel>;

  EIGEN_DEVICE_FUNC EIGEN_STRONG_INLINE ConstUnwindReturnType unwind() const {
    return ConstUnwindReturnType(BlockHelper::base(*this), BlockHelper::row(*this, 0), BlockHelper::col(*this, 0),
                                 this->rows(), this->cols());
  }

  template <typename T = Block, typename EnableIf = std::enable_if_t<!std::is_const<T>::value>>
  EIGEN_DEVICE_FUNC EIGEN_STRONG_INLINE UnwindReturnType unwind() {
    return UnwindReturnType(BlockHelper::base(*this), BlockHelper::row(*this, 0), BlockHelper::col(*this, 0),
                            this->rows(), this->cols());
  }
};

// The generic default implementation for dense block simply forward to the internal::BlockImpl_dense
// that must be specialized for direct and non-direct access...
template <typename XprType, int BlockRows, int BlockCols, bool InnerPanel>
class BlockImpl<XprType, BlockRows, BlockCols, InnerPanel, Dense>
    : public internal::BlockImpl_dense<XprType, BlockRows, BlockCols, InnerPanel> {
  using Impl = internal::BlockImpl_dense<XprType, BlockRows, BlockCols, InnerPanel>;
  using StorageIndex = typename XprType::StorageIndex;

 public:
  using Base = Impl;
  EIGEN_INHERIT_ASSIGNMENT_OPERATORS(BlockImpl)
  EIGEN_DEVICE_FUNC constexpr EIGEN_STRONG_INLINE BlockImpl(XprType& xpr, Index i) : Impl(xpr, i) {}
  EIGEN_DEVICE_FUNC constexpr EIGEN_STRONG_INLINE BlockImpl(XprType& xpr, Index startRow, Index startCol)
      : Impl(xpr, startRow, startCol) {}
  EIGEN_DEVICE_FUNC constexpr EIGEN_STRONG_INLINE BlockImpl(XprType& xpr, Index startRow, Index startCol,
                                                            Index blockRows, Index blockCols)
      : Impl(xpr, startRow, startCol, blockRows, blockCols) {}
};

namespace internal {

/** \internal Start of the row or column taken by the Block(xpr, i) constructor: a row if and only if BlockRows == 1
 * and BlockCols == XprType::ColsAtCompileTime, a column if and only if BlockRows == XprType::RowsAtCompileTime and
 * BlockCols == 1. A 1x1 xpr is both, with i == 0. */
template <typename XprType, int BlockRows, int BlockCols>
struct block_vector_start {
  static constexpr Index row(Index i) { return (BlockRows == 1) && (BlockCols == XprType::ColsAtCompileTime) ? i : 0; }
  static constexpr Index col(Index i) { return (BlockRows == XprType::RowsAtCompileTime) && (BlockCols == 1) ? i : 0; }
};

/** \internal Internal implementation of dense Blocks in the general case. Coefficient and packet access go through
 * DenseCoeffsBase and evaluator<Block>. */
template <typename XprType, int BlockRows, int BlockCols, bool InnerPanel, bool HasDirectAccess>
class BlockImpl_dense : public internal::dense_xpr_base<Block<XprType, BlockRows, BlockCols, InnerPanel>>::type {
  using BlockType = Block<XprType, BlockRows, BlockCols, InnerPanel>;
  using XprTypeNested = typename internal::ref_selector<XprType>::non_const_type;
  using VectorStart = block_vector_start<XprType, BlockRows, BlockCols>;

 public:
  using Base = typename internal::dense_xpr_base<BlockType>::type;
  EIGEN_DENSE_PUBLIC_INTERFACE(BlockType)
  EIGEN_INHERIT_ASSIGNMENT_OPERATORS(BlockImpl_dense)

  /** Column or Row constructor
   */
  EIGEN_DEVICE_FUNC constexpr BlockImpl_dense(XprType& xpr, Index i)
      : m_xpr(xpr),
        m_startRow(VectorStart::row(i)),
        m_startCol(VectorStart::col(i)),
        m_blockRows(BlockRows == 1 ? 1 : xpr.rows()),
        m_blockCols(BlockCols == 1 ? 1 : xpr.cols()) {}

  /** Fixed-size constructor
   */
  EIGEN_DEVICE_FUNC constexpr BlockImpl_dense(XprType& xpr, Index startRow, Index startCol)
      : m_xpr(xpr), m_startRow(startRow), m_startCol(startCol), m_blockRows(BlockRows), m_blockCols(BlockCols) {}

  /** Dynamic-size constructor
   */
  EIGEN_DEVICE_FUNC constexpr BlockImpl_dense(XprType& xpr, Index startRow, Index startCol, Index blockRows,
                                              Index blockCols)
      : m_xpr(xpr), m_startRow(startRow), m_startCol(startCol), m_blockRows(blockRows), m_blockCols(blockCols) {}

  EIGEN_DEVICE_FUNC constexpr Index rows() const { return m_blockRows.value(); }
  EIGEN_DEVICE_FUNC constexpr Index cols() const { return m_blockCols.value(); }

#ifdef EIGEN_PARSED_BY_DOXYGEN
  /** \sa MapBase::data() */
  EIGEN_DEVICE_FUNC constexpr const Scalar* data() const;
  EIGEN_DEVICE_FUNC inline Index innerStride() const;
  EIGEN_DEVICE_FUNC inline Index outerStride() const;
#endif

  EIGEN_DEVICE_FUNC EIGEN_STRONG_INLINE const internal::remove_all_t<XprTypeNested>& nestedExpression() const {
    return m_xpr;
  }

  EIGEN_DEVICE_FUNC EIGEN_STRONG_INLINE XprType& nestedExpression() { return m_xpr; }

  EIGEN_DEVICE_FUNC constexpr StorageIndex startRow() const noexcept { return m_startRow.value(); }

  EIGEN_DEVICE_FUNC constexpr StorageIndex startCol() const noexcept { return m_startCol.value(); }

 protected:
  XprTypeNested m_xpr;
  const internal::variable_if_dynamic<StorageIndex, (XprType::RowsAtCompileTime == 1 && BlockRows == 1) ? 0 : Dynamic>
      m_startRow;
  const internal::variable_if_dynamic<StorageIndex, (XprType::ColsAtCompileTime == 1 && BlockCols == 1) ? 0 : Dynamic>
      m_startCol;
  const internal::variable_if_dynamic<StorageIndex, RowsAtCompileTime> m_blockRows;
  const internal::variable_if_dynamic<StorageIndex, ColsAtCompileTime> m_blockCols;
};

/** \internal Internal implementation of dense Blocks in the direct access case.*/
template <typename XprType, int BlockRows, int BlockCols, bool InnerPanel>
class BlockImpl_dense<XprType, BlockRows, BlockCols, InnerPanel, true>
    : public MapBase<Block<XprType, BlockRows, BlockCols, InnerPanel>> {
  using BlockType = Block<XprType, BlockRows, BlockCols, InnerPanel>;
  using XprTypeNested = typename internal::ref_selector<XprType>::non_const_type;
  using VectorStart = block_vector_start<XprType, BlockRows, BlockCols>;

  /** \internal An empty block gets a null pointer: its start can lie past the end of xpr's storage. So does a block of
   * a null xpr, since offsetting nullptr is undefined behavior. */
  EIGEN_DEVICE_FUNC EIGEN_ALWAYS_INLINE static auto block_data(XprType& xpr, Index startRow, Index startCol,
                                                               Index blockRows, Index blockCols)
      -> decltype(xpr.data()) {
    return (blockRows == 0 || blockCols == 0 || xpr.data() == nullptr)
               ? nullptr
               : xpr.data() + startRow * xpr.rowStride() + startCol * xpr.colStride();
  }

 public:
  using Base = MapBase<BlockType>;
  EIGEN_DENSE_PUBLIC_INTERFACE(BlockType)
  EIGEN_INHERIT_ASSIGNMENT_OPERATORS(BlockImpl_dense)

  /** Column or Row constructor
   */
  EIGEN_DEVICE_FUNC EIGEN_STRONG_INLINE BlockImpl_dense(XprType& xpr, Index i)
      : Base(block_data(xpr, VectorStart::row(i), VectorStart::col(i), BlockRows == 1 ? 1 : xpr.rows(),
                        BlockCols == 1 ? 1 : xpr.cols()),
             BlockRows == 1 ? 1 : xpr.rows(), BlockCols == 1 ? 1 : xpr.cols()),
        m_xpr(xpr),
        m_startRow(VectorStart::row(i)),
        m_startCol(VectorStart::col(i)),
        m_outerStride(outer_stride(xpr)) {}

  /** Fixed-size constructor
   */
  EIGEN_DEVICE_FUNC EIGEN_STRONG_INLINE BlockImpl_dense(XprType& xpr, Index startRow, Index startCol)
      : Base(block_data(xpr, startRow, startCol, BlockRows, BlockCols)),
        m_xpr(xpr),
        m_startRow(startRow),
        m_startCol(startCol),
        m_outerStride(outer_stride(xpr)) {}

  /** Dynamic-size constructor
   */
  EIGEN_DEVICE_FUNC EIGEN_STRONG_INLINE BlockImpl_dense(XprType& xpr, Index startRow, Index startCol, Index blockRows,
                                                        Index blockCols)
      : Base(block_data(xpr, startRow, startCol, blockRows, blockCols), blockRows, blockCols),
        m_xpr(xpr),
        m_startRow(startRow),
        m_startCol(startCol),
        m_outerStride(outer_stride(xpr)) {}

  EIGEN_DEVICE_FUNC EIGEN_STRONG_INLINE const internal::remove_all_t<XprTypeNested>& nestedExpression() const noexcept {
    return m_xpr;
  }

  EIGEN_DEVICE_FUNC EIGEN_STRONG_INLINE XprType& nestedExpression() { return m_xpr; }

  /** \sa MapBase::innerStride() */
  EIGEN_DEVICE_FUNC constexpr Index innerStride() const noexcept {
    return internal::traits<BlockType>::HasSameStorageOrderAsXprType ? m_xpr.innerStride() : m_xpr.outerStride();
  }

  /** \sa MapBase::outerStride() */
  EIGEN_DEVICE_FUNC constexpr Index outerStride() const noexcept { return m_outerStride; }

  EIGEN_DEVICE_FUNC constexpr StorageIndex startRow() const noexcept { return m_startRow.value(); }

  EIGEN_DEVICE_FUNC constexpr StorageIndex startCol() const noexcept { return m_startCol.value(); }

 protected:
  EIGEN_DEVICE_FUNC static constexpr Index outer_stride(const XprType& xpr) {
    return internal::traits<BlockType>::HasSameStorageOrderAsXprType ? xpr.outerStride() : xpr.innerStride();
  }

  XprTypeNested m_xpr;
  const internal::variable_if_dynamic<StorageIndex, (XprType::RowsAtCompileTime == 1 && BlockRows == 1) ? 0 : Dynamic>
      m_startRow;
  const internal::variable_if_dynamic<StorageIndex, (XprType::ColsAtCompileTime == 1 && BlockCols == 1) ? 0 : Dynamic>
      m_startCol;
  Index m_outerStride;
};

}  // end namespace internal

}  // end namespace Eigen

#endif  // EIGEN_BLOCK_H