Detailed Description

template<typename PlainObjectType>
class drake::EigenPtr< PlainObjectType >

This wrapper class provides a way to write non-template functions taking raw pointers to Eigen objects as parameters while limiting the number of copies, similar to Eigen::Ref.

Internally, it keeps an instance of Eigen::Ref<T> and provides access to it via operator* and operator->. As with ordinary pointers, these operators do not perform nullptr checks in Release builds. User-facing APIs should check for nullptr explicitly.

The primary motivation of this class is to follow GSG's "output arguments should be pointers" convention while taking advantage of using Eigen::Ref. It can also be used to pass optional Eigen objects since EigenPtr, unlike Eigen::Ref, can be null.

Some examples:

// This function is taking an Eigen::Ref of a matrix and modifies it in
// the body. This violates GSG's pointer convention for output parameters.
void foo(Eigen::Ref<Eigen::MatrixXd> M) {
   M(0, 0) = 0;
}
// At Call-site, we have:
foo(M);
foo(M.block(0, 0, 2, 2));
 
// We can rewrite the above function into the following using EigenPtr.
void foo(EigenPtr<Eigen::MatrixXd> M) {
   DRAKE_THROW_UNLESS(M != nullptr);  // If you want a Release-build check.
   (*M)(0, 0) = 0;
}
// Note that, call sites should be changed to:
foo(&M);
 
// We need tmp to avoid taking the address of a temporary object such as the
// return value of .block().
auto tmp = M.block(0, 0, 2, 2);
foo(&tmp);

Notice that methods taking an EigenPtr can mutate the entries of a matrix as in method foo() in the example code above, but cannot change its size. This is because operator* and operator-> return an Eigen::Ref<T> object and only plain matrices/arrays can be resized and not expressions. This is the desired behavior, since resizing the block of a matrix or even a more general expression should not be allowed. If you do want to be able to resize a mutable matrix argument, then you must pass it as a Matrix<T>*, like so:

void bar(Eigen::MatrixXd* M) {
  DRAKE_THROW_UNLESS(M != nullptr);
  // In this case this method only works with 4x3 matrices.
  if (M->rows() != 4 && M->cols() != 3) {
    M->resize(4, 3);
  }
  (*M)(0, 0) = 0;
}

Note: This class provides a way to avoid the const_cast hack introduced in Eigen's documentation.

#include <drake/common/eigen_types.h>

Public Types
typedef Eigen::Ref< PlainObjectType >	RefType

Public Member Functions
	EigenPtr ()
	EigenPtr (std::nullptr_t)
	Overload for nullptr.
	EigenPtr (const EigenPtr &other)
	Copy constructor results in a reference to the given matrix type.
template<typename PlainObjectTypeIn>
	EigenPtr (PlainObjectTypeIn *m)
	Constructs with a reference to another matrix type.
template<typename PlainObjectTypeIn>
	EigenPtr (const EigenPtr< PlainObjectTypeIn > &other)
	Constructs from another EigenPtr.
EigenPtr &	operator= (const EigenPtr &other)
	Copy assignment results in a reference to the given matrix type.
template<typename PlainObjectTypeIn>
EigenPtr &	operator= (const EigenPtr< PlainObjectTypeIn > &other)
RefType &	operator* () const
RefType *	operator-> () const
	operator bool () const
	Returns whether or not this contains a valid reference.
bool	operator== (std::nullptr_t) const
bool	operator!= (std::nullptr_t) const