1namespace Eigen { 2 3/** \eigenManualPage TopicStlContainers Using STL Containers with Eigen 4 5\eigenAutoToc 6 7\section StlContainers_summary Executive summary 8 9If you're compiling in \cpp17 mode only with a sufficiently recent compiler (e.g., GCC>=7, clang>=5, MSVC>=19.12), then everything is taken care by the compiler and you can stop reading. 10 11Otherwise, using STL containers on \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types", or classes having members of such types, requires the use of an over-aligned allocator. 12That is, an allocator capable of allocating buffers with 16, 32, or even 64 bytes alignment. 13%Eigen does provide one ready for use: aligned_allocator. 14 15Prior to \cpp11, if you want to use the `std::vector` container, then you also have to <code> \#include <Eigen/StdVector> </code>. 16 17These issues arise only with \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types" and \ref TopicStructHavingEigenMembers "structures having such Eigen objects as member". 18For other %Eigen types, such as Vector3f or MatrixXd, no special care is needed when using STL containers. 19 20\section allocator Using an aligned allocator 21 22STL containers take an optional template parameter, the allocator type. When using STL containers on \ref TopicFixedSizeVectorizable "fixed-size vectorizable Eigen types", you need tell the container to use an allocator that will always allocate memory at 16-byte-aligned (or more) locations. Fortunately, %Eigen does provide such an allocator: Eigen::aligned_allocator. 23 24For example, instead of 25\code 26std::map<int, Eigen::Vector4d> 27\endcode 28you need to use 29\code 30std::map<int, Eigen::Vector4d, std::less<int>, 31 Eigen::aligned_allocator<std::pair<const int, Eigen::Vector4d> > > 32\endcode 33Note that the third parameter `std::less<int>` is just the default value, but we have to include it because we want to specify the fourth parameter, which is the allocator type. 34 35\section StlContainers_vector The case of std::vector 36 37This section is for c++98/03 users only. \cpp11 (or above) users can stop reading here. 38 39So in c++98/03, the situation with `std::vector` is more complicated because of a bug in the standard (explanation below). 40To workaround the issue, we had to specialize it for the Eigen::aligned_allocator type. 41In practice you \b must use the Eigen::aligned_allocator (not another aligned allocator), \b and \#include <Eigen/StdVector>. 42 43Here is an example: 44\code 45#include<Eigen/StdVector> 46/* ... */ 47std::vector<Eigen::Vector4f,Eigen::aligned_allocator<Eigen::Vector4f> > 48\endcode 49 50<span class="note">\b Explanation: The `resize()` method of `std::vector` takes a `value_type` argument (defaulting to `value_type()`). So with `std::vector<Eigen::Vector4d>`, some Eigen::Vector4d objects will be passed by value, which discards any alignment modifiers, so a Eigen::Vector4d can be created at an unaligned location. 51In order to avoid that, the only solution we saw was to specialize `std::vector` to make it work on a slight modification of, here, Eigen::Vector4d, that is able to deal properly with this situation. 52</span> 53 54\subsection vector_spec An alternative - specializing std::vector for Eigen types 55 56As an alternative to the recommended approach described above, you have the option to specialize std::vector for Eigen types requiring alignment. 57The advantage is that you won't need to declare std::vector all over with Eigen::aligned_allocator. One drawback on the other hand side is that 58the specialization needs to be defined before all code pieces in which e.g. `std::vector<Vector2d>` is used. Otherwise, without knowing the specialization 59the compiler will compile that particular instance with the default `std::allocator` and you program is most likely to crash. 60 61Here is an example: 62\code 63#include<Eigen/StdVector> 64/* ... */ 65EIGEN_DEFINE_STL_VECTOR_SPECIALIZATION(Matrix2d) 66std::vector<Eigen::Vector2d> 67\endcode 68 69 70 71*/ 72 73} 74