blob: 9a825bc4885a2d0db802db59cd885a206ce77fb5 [file] [log] [blame]
Gael Guennebaud4759d9e2019-01-17 10:35:14 +01001namespace Eigen {
2
3/** \eigenManualPage TutorialSTL STL iterators and algorithms
4
5Since the version 3.4, %Eigen's dense matrices and arrays provide STL compatible iterators.
6As demonstrated below, this makes them naturally compatible with range-for-loops and STL's algorithms.
7
8\eigenAutoToc
9
10\section TutorialSTLVectors Iterating over 1D arrays and vectors
11
12Any dense 1D expressions exposes the pair of `begin()/end()` methods to iterate over them.
13
14This directly enables c++11 range for loops:
15<table class="example">
16<tr><th>Example:</th><th>Output:</th></tr>
17<tr><td>
18\include Tutorial_range_for_loop_1d_cxx11.cpp
19</td>
20<td>
21\verbinclude Tutorial_range_for_loop_1d_cxx11.out
22</td></tr></table>
23
24One dimensional expressions can also easily be passed to STL algorithms:
25<table class="example">
26<tr><th>Example:</th><th>Output:</th></tr>
27<tr><td>
28\include Tutorial_std_sort.cpp
29</td>
30<td>
31\verbinclude Tutorial_std_sort.out
32</td></tr></table>
33
34Similar to `std::vector`, 1D expressions also exposes the pair of `cbegin()/cend()` methods to conveniently get const iterators on non-const object.
35
36\section TutorialSTLMatrices Iterating over coefficients of 2D arrays and matrices
37
38STL iterators are intrinsically designed to iterate over 1D structures.
39This is why `begin()/end()` methods are disabled for 2D expressions.
40Iterating over all coefficients of a 2D expressions is still easily accomplished by creating a 1D linear view through `reshaped()`:
41<table class="example">
42<tr><th>Example:</th><th>Output:</th></tr>
43<tr><td>
44\include Tutorial_range_for_loop_2d_cxx11.cpp
45</td>
46<td>
47\verbinclude Tutorial_range_for_loop_2d_cxx11.out
48</td></tr></table>
49
50\section TutorialSTLRowsColumns Iterating over rows or columns of 2D arrays and matrices
51
52It is also possible to get iterators over rows or columns of 2D expressions.
53Those are available through the `rowwise()` and `colwise()` proxies.
54Here is an example sorting each row of a matrix:
55<table class="example">
56<tr><th>Example:</th><th>Output:</th></tr>
57<tr><td>
Christoph Hertzberge16913a2019-01-23 10:35:06 +010058\include Tutorial_std_sort_rows_cxx11.cpp
Gael Guennebaud4759d9e2019-01-17 10:35:14 +010059</td>
60<td>
Christoph Hertzberge16913a2019-01-23 10:35:06 +010061\verbinclude Tutorial_std_sort_rows_cxx11.out
Gael Guennebaud4759d9e2019-01-17 10:35:14 +010062</td></tr></table>
63
64*/
65
66}