EigenPtr< PlainObjectType > Class Template Reference

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. More...
	EigenPtr (const EigenPtr &other)
	Copy constructor results in a reference to the given matrix type. More...
template<typename PlainObjectTypeIn >
	EigenPtr (PlainObjectTypeIn *m)
	Constructs with a reference to another matrix type. More...
template<typename PlainObjectTypeIn >
	EigenPtr (const EigenPtr< PlainObjectTypeIn > &other)
	Constructs from another EigenPtr. More...
EigenPtr &	operator= (const EigenPtr &other)
	Copy assignment results in a reference to the given matrix type. More...
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. More...
bool	operator== (std::nullptr_t) const
bool	operator!= (std::nullptr_t) const

Member Typedef Documentation

RefType

typedef Eigen::Ref<PlainObjectType> RefType

Constructor & Destructor Documentation

EigenPtr() [1/5]

EigenPtr

(

)

EigenPtr() [2/5]

EigenPtr

(

std::nullptr_t

)

Overload for nullptr.

EigenPtr() [3/5]

EigenPtr

(

const EigenPtr< PlainObjectType > &

other

)

Copy constructor results in a reference to the given matrix type.

EigenPtr() [4/5]

EigenPtr

(

PlainObjectTypeIn *

m

)

Constructs with a reference to another matrix type.

May be nullptr.

EigenPtr() [5/5]

EigenPtr

(

const EigenPtr< PlainObjectTypeIn > &

other

)

Constructs from another EigenPtr.

Member Function Documentation

operator *()

RefType& operator *

(

)

const

Precondition

The pointer is not null (enforced in Debug builds only).

operator bool()

operator bool

(

)

const

Returns whether or not this contains a valid reference.

operator!=()

bool operator!=

(

std::nullptr_t

)

const

operator->()

RefType* operator->

(

)

const

Precondition

The pointer is not null (enforced in Debug builds only).

operator=() [1/2]

EigenPtr& operator=

(

const EigenPtr< PlainObjectType > &

other

)

Copy assignment results in a reference to the given matrix type.

operator=() [2/2]

EigenPtr& operator=

(

const EigenPtr< PlainObjectTypeIn > &

other

)

operator==()

bool operator==

(

std::nullptr_t

)

const

---

The documentation for this class was generated from the following file:

• drake/common/eigen_types.h