template<typename PlainObjectType, int Options, typename StrideType>
class Eigen::Ref< PlainObjectType, Options, StrideType >
A matrix or vector expression mapping an existing expression.
- Template Parameters
-
| PlainObjectType | the equivalent matrix type of the mapped data |
| Options | specifies the pointer alignment in bytes. It can be: Aligned128, , Aligned64, Aligned32, Aligned16, Aligned8 or Unaligned. The default is Unaligned. |
| StrideType | optionally specifies strides. By default, Ref implies a contiguous storage along the inner dimension (inner stride==1), but accepts a variable outer stride (leading dimension). This can be overridden by specifying strides. The type passed here must be a specialization of the Stride template, see examples below. |
This class provides a way to write non-template functions taking Eigen objects as parameters while limiting the number of copies. A Ref<> object can represent either a const expression or a l-value:
void foo1(Ref<VectorXf>
x);
void foo2(
const Ref<const VectorXf>&
x);
In the in-out case, the input argument must satisfy the constraints of the actual Ref<> type, otherwise a compilation issue will be triggered. By default, a Ref<VectorXf> can reference any dense vector expression of float having a contiguous memory layout. Likewise, a Ref<MatrixXf> can reference any column-major dense matrix expression of float whose column's elements are contiguously stored with the possibility to have a constant space in-between each column, i.e. the inner stride must be equal to 1, but the outer stride (or leading dimension) can be greater than the number of rows.
In the const case, if the input expression does not match the above requirement, then it is evaluated into a temporary before being passed to the function. Here are some examples:
foo2(
A.row().transpose());
foo2(
A.col().segment(2,4));
Matrix< float, Dynamic, Dynamic > MatrixXf
Dynamic×Dynamic matrix of type float.
Matrix< float, Dynamic, 1 > VectorXf
Dynamic×1 vector of type float.
The range of inputs that can be referenced without temporary can be enlarged using the last two template parameters. Here is an example accepting an innerstride!=1:
Ref(const PlainObjectBase< Derived > &expr, std::enable_if_t< bool(Traits::template match< Derived >::MatchAtCompileTime), Derived > *=0)
The downside here is that the function foo3 might be significantly slower than foo1 because it won't be able to exploit vectorization, and will involve more expensive address computations even if the input is contiguously stored in memory. To overcome this issue, one might propose to overload internally calling a template function, e.g.:
void foo(
const Ref<MatrixXf>&
A);
template<
typename TypeOfA>
void foo_impl(
const TypeOfA&
A) {
...
}
void foo(
const Ref<MatrixXf>&
A) { foo_impl(
A); }
See also the following stackoverflow questions for further references:
- See also
- PlainObjectBase::Map(), Storage orders
Definition at line 283 of file Ref.h.
Inheritance diagram for Eigen::Ref< PlainObjectType, Options, StrideType >: