xref: /aosp_15_r20/external/eigen/doc/TutorialSTL.dox (revision bf2c37156dfe67e5dfebd6d394bad8b2ab5804d4)
1*bf2c3715SXin Linamespace Eigen {
2*bf2c3715SXin Li
3*bf2c3715SXin Li/** \eigenManualPage TutorialSTL STL iterators and algorithms
4*bf2c3715SXin Li
5*bf2c3715SXin LiSince the version 3.4, %Eigen's dense matrices and arrays provide STL compatible iterators.
6*bf2c3715SXin LiAs demonstrated below, this makes them naturally compatible with range-for-loops and STL's algorithms.
7*bf2c3715SXin Li
8*bf2c3715SXin Li\eigenAutoToc
9*bf2c3715SXin Li
10*bf2c3715SXin Li\section TutorialSTLVectors Iterating over 1D arrays and vectors
11*bf2c3715SXin Li
12*bf2c3715SXin LiAny dense 1D expressions exposes the pair of `begin()/end()` methods to iterate over them.
13*bf2c3715SXin Li
14*bf2c3715SXin LiThis directly enables c++11 range for loops:
15*bf2c3715SXin Li<table class="example">
16*bf2c3715SXin Li<tr><th>Example:</th><th>Output:</th></tr>
17*bf2c3715SXin Li<tr><td>
18*bf2c3715SXin Li\include Tutorial_range_for_loop_1d_cxx11.cpp
19*bf2c3715SXin Li</td>
20*bf2c3715SXin Li<td>
21*bf2c3715SXin Li\verbinclude Tutorial_range_for_loop_1d_cxx11.out
22*bf2c3715SXin Li</td></tr></table>
23*bf2c3715SXin Li
24*bf2c3715SXin LiOne dimensional expressions can also easily be passed to STL algorithms:
25*bf2c3715SXin Li<table class="example">
26*bf2c3715SXin Li<tr><th>Example:</th><th>Output:</th></tr>
27*bf2c3715SXin Li<tr><td>
28*bf2c3715SXin Li\include Tutorial_std_sort.cpp
29*bf2c3715SXin Li</td>
30*bf2c3715SXin Li<td>
31*bf2c3715SXin Li\verbinclude Tutorial_std_sort.out
32*bf2c3715SXin Li</td></tr></table>
33*bf2c3715SXin Li
34*bf2c3715SXin LiSimilar to `std::vector`, 1D expressions also exposes the pair of `cbegin()/cend()` methods to conveniently get const iterators on non-const object.
35*bf2c3715SXin Li
36*bf2c3715SXin Li\section TutorialSTLMatrices Iterating over coefficients of 2D arrays and matrices
37*bf2c3715SXin Li
38*bf2c3715SXin LiSTL iterators are intrinsically designed to iterate over 1D structures.
39*bf2c3715SXin LiThis is why `begin()/end()` methods are disabled for 2D expressions.
40*bf2c3715SXin LiIterating over all coefficients of a 2D expressions is still easily accomplished by creating a 1D linear view through `reshaped()`:
41*bf2c3715SXin Li<table class="example">
42*bf2c3715SXin Li<tr><th>Example:</th><th>Output:</th></tr>
43*bf2c3715SXin Li<tr><td>
44*bf2c3715SXin Li\include Tutorial_range_for_loop_2d_cxx11.cpp
45*bf2c3715SXin Li</td>
46*bf2c3715SXin Li<td>
47*bf2c3715SXin Li\verbinclude Tutorial_range_for_loop_2d_cxx11.out
48*bf2c3715SXin Li</td></tr></table>
49*bf2c3715SXin Li
50*bf2c3715SXin Li\section TutorialSTLRowsColumns Iterating over rows or columns of 2D arrays and matrices
51*bf2c3715SXin Li
52*bf2c3715SXin LiIt is also possible to get iterators over rows or columns of 2D expressions.
53*bf2c3715SXin LiThose are available through the `rowwise()` and `colwise()` proxies.
54*bf2c3715SXin LiHere is an example sorting each row of a matrix:
55*bf2c3715SXin Li<table class="example">
56*bf2c3715SXin Li<tr><th>Example:</th><th>Output:</th></tr>
57*bf2c3715SXin Li<tr><td>
58*bf2c3715SXin Li\include Tutorial_std_sort_rows_cxx11.cpp
59*bf2c3715SXin Li</td>
60*bf2c3715SXin Li<td>
61*bf2c3715SXin Li\verbinclude Tutorial_std_sort_rows_cxx11.out
62*bf2c3715SXin Li</td></tr></table>
63*bf2c3715SXin Li
64*bf2c3715SXin Li*/
65*bf2c3715SXin Li
66*bf2c3715SXin Li}
67