The Eigen2 intrusive std::vector hack really can't be supported in eigen3 (bug #215)

doc/A05_PortingFrom2To3.dox

@@ -21,6 +21,7 @@ and gives tips to help porting your application from Eigen2 to Eigen3.
   - \ref LazyVsNoalias
   - \ref AlignMacros
   - \ref AlignedMap
+  - \ref StdContainers
   - \ref eiPrefix
 
 \section CompatibilitySupport Eigen2 compatibility support
@@ -295,6 +296,18 @@ There also are related convenience static methods, which actually are the prefer
 result = Vector4f::MapAligned(some_aligned_array);
 \endcode
 
+\section StdContainers STL Containers
+
+In Eigen2, #include<Eigen/StdVector> tweaked std::vector to automatically align elements. The problem was that that was quite invasive. In Eigen3, we only override standard behavior if you use Eigen::aligned_allocator<T> as your allocator type. So for example, if you use std::vector<Matrix4f>, you need to do the following change (note that aligned_allocator is under namespace Eigen):
+
+<table class="manual">
+<tr><th>Eigen 2</th><th>Eigen 3</th></tr>
+<tr>
+  <td> \code std::vector<Matrix4f> \endcode </td>
+  <td> \code std::vector<Matrix4f, aligned_allocator<Matrix4f> > \endcode </td>
+</tr>
+</table>
+
 \section eiPrefix Internal ei_ prefix
 
 In Eigen2, global internal functions and structures were prefixed by \c ei_. In Eigen3, they all have been moved into the more explicit \c internal namespace. So, e.g., \c ei_sqrt(x) now becomes \c internal::sqrt(x). Of course it is not recommended to rely on Eigen's internal features.

doc/A10_Eigen2SupportModes.dox

@@ -47,6 +47,7 @@ The parts of the API that are still not 100% Eigen 2 compatible in this mode are
 \li Dot products over complex numbers. Eigen 2's dot product was linear in the first variable. Eigen 3's dot product is linear in the second variable. In other words, the Eigen 2 code \code x.dot(y) \endcode is equivalent to the Eigen 3 code \code y.dot(x) \endcode In yet other words, dot products are complex-conjugated in Eigen 3 compared to Eigen 2. The switch to the new convention was commanded by common usage, especially with the notation \f$ x^Ty \f$ for dot products of column-vectors.
 \li The Sparse module.
 \li Certain fine details of linear algebraic decompositions. For example, LDLT decomposition is now pivoting in Eigen 3 whereas it wasn't in Eigen 2, so code that was relying on its underlying matrix structure will break.
+\li Usage of Eigen types in STL containers, \ref Eigen2ToEigen3 "as explained on this page".
 
 \section Stage20 Stage 20: define EIGEN2_SUPPORT_STAGE20_RESOLVE_API_CONFLICTS
 

test/eigen2/eigen2_stdvector.cpp

@@ -32,7 +32,7 @@ void check_stdvector_matrix(const MatrixType& m)
   int rows = m.rows();
   int cols = m.cols();
   MatrixType x = MatrixType::Random(rows,cols), y = MatrixType::Random(rows,cols);
-  std::vector<MatrixType> v(10, MatrixType(rows,cols)), w(20, y);
+  std::vector<MatrixType, aligned_allocator<MatrixType> > v(10, MatrixType(rows,cols)), w(20, y);
   v[5] = x;
   w[6] = v[5];
   VERIFY_IS_APPROX(w[6], v[5]);
@@ -67,7 +67,7 @@ void check_stdvector_transform(const TransformType&)
 {
   typedef typename TransformType::MatrixType MatrixType;
   TransformType x(MatrixType::Random()), y(MatrixType::Random());
-  std::vector<TransformType> v(10), w(20, y);
+  std::vector<TransformType, aligned_allocator<TransformType> > v(10), w(20, y);
   v[5] = x;
   w[6] = v[5];
   VERIFY_IS_APPROX(w[6], v[5]);
@@ -102,7 +102,7 @@ void check_stdvector_quaternion(const QuaternionType&)
 {
   typedef typename QuaternionType::Coefficients Coefficients;
   QuaternionType x(Coefficients::Random()), y(Coefficients::Random());
-  std::vector<QuaternionType> v(10), w(20, y);
+  std::vector<QuaternionType, aligned_allocator<QuaternionType> > v(10), w(20, y);
   v[5] = x;
   w[6] = v[5];
   VERIFY_IS_APPROX(w[6], v[5]);