| <html> | |
| <head> | |
| <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> | |
| <title>Chapter 6. Boost.Foreach</title> | |
| <link rel="stylesheet" href="../../doc/src/boostbook.css" type="text/css"> | |
| <meta name="generator" content="DocBook XSL Stylesheets V1.75.2"> | |
| <link rel="home" href="index.html" title="The Boost C++ Libraries BoostBook Documentation Subset"> | |
| <link rel="up" href="libraries.html" title="Part I. The Boost C++ Libraries (BoostBook Subset)"> | |
| <link rel="prev" href="boost/local_time/tz_database.html" title="Type definition tz_database"> | |
| <link rel="next" href="foreach/extensibility.html" title="Extensibility"> | |
| </head> | |
| <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> | |
| <table cellpadding="2" width="100%"><tr> | |
| <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../boost.png"></td> | |
| <td align="center"><a href="../../index.html">Home</a></td> | |
| <td align="center"><a href="../../libs/libraries.htm">Libraries</a></td> | |
| <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> | |
| <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> | |
| <td align="center"><a href="../../more/index.htm">More</a></td> | |
| </tr></table> | |
| <hr> | |
| <div class="spirit-nav"> | |
| <a accesskey="p" href="boost/local_time/tz_database.html"><img src="../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="libraries.html"><img src="../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="foreach/extensibility.html"><img src="../../doc/src/images/next.png" alt="Next"></a> | |
| </div> | |
| <div class="chapter"> | |
| <div class="titlepage"><div> | |
| <div><h2 class="title"> | |
| <a name="foreach"></a>Chapter 6. Boost.Foreach</h2></div> | |
| <div><div class="author"><h3 class="author"> | |
| <span class="firstname">Eric</span> <span class="surname">Niebler</span> | |
| </h3></div></div> | |
| <div><p class="copyright">Copyright © 2004 Eric Niebler</p></div> | |
| <div><div class="legalnotice"> | |
| <a name="id1257431"></a><p> | |
| Distributed under the Boost Software License, Version 1.0. (See accompanying | |
| file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) | |
| </p> | |
| </div></div> | |
| </div></div> | |
| <div class="toc"> | |
| <p><b>Table of Contents</b></p> | |
| <dl> | |
| <dt><span class="section"><a href="foreach.html#foreach.introduction">Introduction</a></span></dt> | |
| <dt><span class="section"><a href="foreach/extensibility.html">Extensibility</a></span></dt> | |
| <dt><span class="section"><a href="foreach/portability.html">Portability</a></span></dt> | |
| <dt><span class="section"><a href="foreach/pitfalls.html">Pitfalls</a></span></dt> | |
| <dt><span class="section"><a href="foreach/history_and_acknowledgements.html">History and Acknowledgements</a></span></dt> | |
| </dl> | |
| </div> | |
| <div class="section"> | |
| <div class="titlepage"><div><div><h2 class="title" style="clear: both"> | |
| <a name="foreach.introduction"></a><a class="link" href="foreach.html#foreach.introduction" title="Introduction">Introduction</a> | |
| </h2></div></div></div> | |
| <div class="blockquote"><blockquote class="blockquote"><p> | |
| <span class="quote">“<span class="quote">Make simple things easy.</span>”</span><br> <span class="bold"><strong><span class="emphasis"><em>-- | |
| Larry Wall</em></span></strong></span> | |
| </p></blockquote></div> | |
| <a name="foreach.introduction.what_is__literal_boost_foreach__literal__"></a><h3> | |
| <a name="id1257492"></a> | |
| <a class="link" href="foreach.html#foreach.introduction.what_is__literal_boost_foreach__literal__">What | |
| is <code class="literal">BOOST_FOREACH</code>?</a> | |
| </h3> | |
| <p> | |
| In C++, writing a loop that iterates over a sequence is tedious. We can either | |
| use iterators, which requires a considerable amount of boiler-plate, or we | |
| can use the <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">for_each</span><span class="special">()</span></code> | |
| algorithm and move our loop body into a predicate, which requires no less boiler-plate | |
| and forces us to move our logic far from where it will be used. In contrast, | |
| some other languages, like Perl, provide a dedicated "foreach" construct | |
| that automates this process. <code class="literal">BOOST_FOREACH</code> is just such | |
| a construct for C++. It iterates over sequences for us, freeing us from having | |
| to deal directly with iterators or write predicates. | |
| </p> | |
| <p> | |
| <code class="literal">BOOST_FOREACH</code> is designed for ease-of-use and efficiency. | |
| It does no dynamic allocations, makes no virtual function calls or calls through | |
| function pointers, and makes no calls that are not transparent to the compiler's | |
| optimizer. This results in near-optimal code generation; the performance of | |
| <code class="literal">BOOST_FOREACH</code> is usually within a few percent of the equivalent | |
| hand-coded loop. And although <code class="literal">BOOST_FOREACH</code> is a macro, | |
| it is a remarkably well-behaved one. It evaluates its arguments exactly once, | |
| leading to no nasty surprises. | |
| </p> | |
| <a name="foreach.introduction.hello__world_"></a><h3> | |
| <a name="id1257591"></a> | |
| <a class="link" href="foreach.html#foreach.introduction.hello__world_">Hello, world!</a> | |
| </h3> | |
| <p> | |
| Below is a sample program that uses <code class="literal">BOOST_FOREACH</code> to loop | |
| over the contents of a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></code>. | |
| </p> | |
| <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">string</span><span class="special">></span> | |
| <span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span> | |
| <span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">foreach</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> | |
| <span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> | |
| <span class="special">{</span> | |
| <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">hello</span><span class="special">(</span> <span class="string">"Hello, world!"</span> <span class="special">);</span> | |
| <span class="identifier">BOOST_FOREACH</span><span class="special">(</span> <span class="keyword">char</span> <span class="identifier">ch</span><span class="special">,</span> <span class="identifier">hello</span> <span class="special">)</span> | |
| <span class="special">{</span> | |
| <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">ch</span><span class="special">;</span> | |
| <span class="special">}</span> | |
| <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> | |
| <span class="special">}</span> | |
| </pre> | |
| <p> | |
| This program outputs the following: | |
| </p> | |
| <pre class="programlisting">Hello, world! | |
| </pre> | |
| <a name="foreach.introduction.supported_sequence_types"></a><h3> | |
| <a name="id1257885"></a> | |
| <a class="link" href="foreach.html#foreach.introduction.supported_sequence_types">Supported Sequence | |
| Types</a> | |
| </h3> | |
| <p> | |
| <code class="literal">BOOST_FOREACH</code> iterates over sequences. But what qualifies | |
| as a sequence, exactly? Since <code class="literal">BOOST_FOREACH</code> is built on | |
| top of <a href="../../libs/range/index.html" target="_top">Boost.Range</a>, it automatically | |
| supports those types which <a href="../../libs/range/index.html" target="_top">Boost.Range</a> | |
| recognizes as sequences. Specifically, <code class="literal">BOOST_FOREACH</code> works | |
| with types that satisfy the <a href="../../libs/range/doc/html/range/concepts/single_pass_range.html" target="_top">Single | |
| Pass Range Concept</a>. For example, we can use <code class="literal">BOOST_FOREACH</code> | |
| with: | |
| </p> | |
| <div class="itemizedlist"><ul class="itemizedlist" type="disc"> | |
| <li class="listitem"> | |
| STL containers | |
| </li> | |
| <li class="listitem"> | |
| arrays | |
| </li> | |
| <li class="listitem"> | |
| Null-terminated strings (<code class="computeroutput"><span class="keyword">char</span></code> | |
| and <code class="computeroutput"><span class="keyword">wchar_t</span></code>) | |
| </li> | |
| <li class="listitem"> | |
| std::pair of iterators | |
| </li> | |
| </ul></div> | |
| <div class="note"><table border="0" summary="Note"> | |
| <tr> | |
| <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../doc/src/images/note.png"></td> | |
| <th align="left">Note</th> | |
| </tr> | |
| <tr><td align="left" valign="top"><p> | |
| The support for STL containers is very general; anything that looks like | |
| an STL container counts. If it has nested <code class="computeroutput"><span class="identifier">iterator</span></code> | |
| and <code class="computeroutput"><span class="identifier">const_iterator</span></code> types | |
| and <code class="computeroutput"><span class="identifier">begin</span><span class="special">()</span></code> | |
| and <code class="computeroutput"><span class="identifier">end</span><span class="special">()</span></code> | |
| member functions, <code class="literal">BOOST_FOREACH</code> will automatically know | |
| how to iterate over it. It is in this way that <a href="../../libs/range/doc/html/range/reference/utilities/iterator_range.html" target="_top"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">iterator_range</span><span class="special"><></span></code></a> | |
| and <a href="../../libs/range/doc/html/range/reference/utilities/sub_range.html" target="_top"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">sub_range</span><span class="special"><></span></code></a> | |
| work with <code class="literal">BOOST_FOREACH</code>. | |
| </p></td></tr> | |
| </table></div> | |
| <p> | |
| See the section on <a class="link" href="foreach/extensibility.html" title="Extensibility">Extensibility</a> | |
| to find out how to make <code class="literal">BOOST_FOREACH</code> work with other types. | |
| </p> | |
| <a name="foreach.introduction.examples"></a><h3> | |
| <a name="id1258416"></a> | |
| <a class="link" href="foreach.html#foreach.introduction.examples">Examples</a> | |
| </h3> | |
| <p> | |
| Below are some examples that demonstrate all the different ways we can use | |
| <code class="literal">BOOST_FOREACH</code>. | |
| </p> | |
| <p> | |
| Iterate over an STL container: | |
| </p> | |
| <pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">list</span><span class="special"><</span><span class="keyword">int</span><span class="special">></span> <span class="identifier">list_int</span><span class="special">(</span> <span class="comment">/*...*/</span> <span class="special">);</span> | |
| <span class="identifier">BOOST_FOREACH</span><span class="special">(</span> <span class="keyword">int</span> <span class="identifier">i</span><span class="special">,</span> <span class="identifier">list_int</span> <span class="special">)</span> | |
| <span class="special">{</span> | |
| <span class="comment">// do something with i | |
| </span><span class="special">}</span> | |
| </pre> | |
| <p> | |
| Iterate over an array, with covariance (i.e., the type of the iteration variable | |
| is not exactly the same as the element type of the container): | |
| </p> | |
| <pre class="programlisting"><span class="keyword">short</span> <span class="identifier">array_short</span><span class="special">[]</span> <span class="special">=</span> <span class="special">{</span><span class="number">1</span><span class="special">,</span><span class="number">2</span><span class="special">,</span><span class="number">3</span><span class="special">};</span> | |
| <span class="identifier">BOOST_FOREACH</span><span class="special">(</span> <span class="keyword">int</span> <span class="identifier">i</span><span class="special">,</span> <span class="identifier">array_short</span> <span class="special">)</span> | |
| <span class="special">{</span> | |
| <span class="comment">// The short was implicitly converted to an int | |
| </span><span class="special">}</span> | |
| </pre> | |
| <p> | |
| Predeclare the loop variable, and use <code class="computeroutput"><span class="keyword">break</span></code>, | |
| <code class="computeroutput"><span class="keyword">continue</span></code>, and <code class="computeroutput"><span class="keyword">return</span></code> | |
| in the loop body: | |
| </p> | |
| <pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">deque</span><span class="special"><</span><span class="keyword">int</span><span class="special">></span> <span class="identifier">deque_int</span><span class="special">(</span> <span class="comment">/*...*/</span> <span class="special">);</span> | |
| <span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> | |
| <span class="identifier">BOOST_FOREACH</span><span class="special">(</span> <span class="identifier">i</span><span class="special">,</span> <span class="identifier">deque_int</span> <span class="special">)</span> | |
| <span class="special">{</span> | |
| <span class="keyword">if</span><span class="special">(</span> <span class="identifier">i</span> <span class="special">==</span> <span class="number">0</span> <span class="special">)</span> <span class="keyword">return</span><span class="special">;</span> | |
| <span class="keyword">if</span><span class="special">(</span> <span class="identifier">i</span> <span class="special">==</span> <span class="number">1</span> <span class="special">)</span> <span class="keyword">continue</span><span class="special">;</span> | |
| <span class="keyword">if</span><span class="special">(</span> <span class="identifier">i</span> <span class="special">==</span> <span class="number">2</span> <span class="special">)</span> <span class="keyword">break</span><span class="special">;</span> | |
| <span class="special">}</span> | |
| </pre> | |
| <p> | |
| Iterate over a sequence by reference, and modify the underlying sequence: | |
| </p> | |
| <pre class="programlisting"><span class="keyword">short</span> <span class="identifier">array_short</span><span class="special">[]</span> <span class="special">=</span> <span class="special">{</span> <span class="number">1</span><span class="special">,</span> <span class="number">2</span><span class="special">,</span> <span class="number">3</span> <span class="special">};</span> | |
| <span class="identifier">BOOST_FOREACH</span><span class="special">(</span> <span class="keyword">short</span> <span class="special">&</span> <span class="identifier">i</span><span class="special">,</span> <span class="identifier">array_short</span> <span class="special">)</span> | |
| <span class="special">{</span> | |
| <span class="special">++</span><span class="identifier">i</span><span class="special">;</span> | |
| <span class="special">}</span> | |
| <span class="comment">// array_short contains {2,3,4} here | |
| </span></pre> | |
| <p> | |
| Iterate over a vector of vectors with nested <code class="literal">BOOST_FOREACH</code> | |
| loops. In this example, notice that braces around the loop body are not necessary: | |
| </p> | |
| <pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="keyword">int</span><span class="special">></span> <span class="special">></span> <span class="identifier">matrix_int</span><span class="special">;</span> | |
| <span class="identifier">BOOST_FOREACH</span><span class="special">(</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="keyword">int</span><span class="special">></span> <span class="special">&</span> <span class="identifier">row</span><span class="special">,</span> <span class="identifier">matrix_int</span> <span class="special">)</span> | |
| <span class="identifier">BOOST_FOREACH</span><span class="special">(</span> <span class="keyword">int</span> <span class="special">&</span> <span class="identifier">i</span><span class="special">,</span> <span class="identifier">row</span> <span class="special">)</span> | |
| <span class="special">++</span><span class="identifier">i</span><span class="special">;</span> | |
| </pre> | |
| <p> | |
| Iterate over an expression that returns a sequence by value (i.e. an rvalue): | |
| </p> | |
| <pre class="programlisting"><span class="keyword">extern</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">vector</span><span class="special"><</span><span class="keyword">float</span><span class="special">></span> <span class="identifier">get_vector_float</span><span class="special">();</span> | |
| <span class="identifier">BOOST_FOREACH</span><span class="special">(</span> <span class="keyword">float</span> <span class="identifier">f</span><span class="special">,</span> <span class="identifier">get_vector_float</span><span class="special">()</span> <span class="special">)</span> | |
| <span class="special">{</span> | |
| <span class="comment">// Note: get_vector_float() will be called exactly once | |
| </span><span class="special">}</span> | |
| </pre> | |
| <p> | |
| Iterate in reverse: | |
| </p> | |
| <pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">list</span><span class="special"><</span><span class="keyword">int</span><span class="special">></span> <span class="identifier">list_int</span><span class="special">(</span> <span class="comment">/*...*/</span> <span class="special">);</span> | |
| <span class="identifier">BOOST_REVERSE_FOREACH</span><span class="special">(</span> <span class="keyword">int</span> <span class="identifier">i</span><span class="special">,</span> <span class="identifier">list_int</span> <span class="special">)</span> | |
| <span class="special">{</span> | |
| <span class="comment">// do something with i | |
| </span><span class="special">}</span> | |
| </pre> | |
| <p> | |
| Iterating over rvalues doesn't work on some older compilers. Check the <a class="link" href="foreach/portability.html" title="Portability">Portability</a> section to see whether your | |
| compiler supports this. | |
| </p> | |
| <a name="foreach.introduction.making__literal_boost_foreach__literal__prettier"></a><h3> | |
| <a name="id1259504"></a> | |
| <a class="link" href="foreach.html#foreach.introduction.making__literal_boost_foreach__literal__prettier">Making | |
| <code class="literal">BOOST_FOREACH</code> Prettier</a> | |
| </h3> | |
| <p> | |
| People have complained about the name <code class="literal">BOOST_FOREACH</code>. It's | |
| too long. <code class="computeroutput"><span class="identifier">ALL</span> <span class="identifier">CAPS</span></code> | |
| can get tiresome to look at. That may be true, but <code class="literal">BOOST_FOREACH</code> | |
| is merely following the <a href="http://www.boost.org/more/lib_guide.htm" target="_top">Boost | |
| Naming Convention</a>. That doesn't mean you're stuck with it, though. | |
| If you would like to use a different identifier (<code class="computeroutput"><span class="identifier">foreach</span></code>, | |
| perhaps), you can simply do: | |
| </p> | |
| <pre class="programlisting"><span class="preprocessor">#define</span> <span class="identifier">foreach</span> <span class="identifier">BOOST_FOREACH</span> | |
| <span class="preprocessor">#define</span> <span class="identifier">reverse_foreach</span> <span class="identifier">BOOST_REVERSE_FOREACH</span> | |
| </pre> | |
| <p> | |
| Only do this if you are sure that the identifier you choose will not cause | |
| name conflicts in your code. | |
| </p> | |
| <div class="note"><table border="0" summary="Note"> | |
| <tr> | |
| <td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../doc/src/images/note.png"></td> | |
| <th align="left">Note</th> | |
| </tr> | |
| <tr><td align="left" valign="top"><p> | |
| Do not use <code class="computeroutput"><span class="preprocessor">#define</span> <span class="identifier">foreach</span><span class="special">(</span><span class="identifier">x</span><span class="special">,</span><span class="identifier">y</span><span class="special">)</span> <span class="identifier">BOOST_FOREACH</span><span class="special">(</span><span class="identifier">x</span><span class="special">,</span><span class="identifier">y</span><span class="special">)</span></code>. This | |
| can be problematic if the arguments are macros themselves. This would result | |
| in an additional expansion of these macros. Instead, use the form shown above. | |
| </p></td></tr> | |
| </table></div> | |
| </div> | |
| </div> | |
| <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> | |
| <td align="left"><p><small>Last revised: November 10, 2010 at 00:44:25 GMT</small></p></td> | |
| <td align="right"><div class="copyright-footer"></div></td> | |
| </tr></table> | |
| <hr> | |
| <div class="spirit-nav"> | |
| <a accesskey="p" href="boost/local_time/tz_database.html"><img src="../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="libraries.html"><img src="../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="foreach/extensibility.html"><img src="../../doc/src/images/next.png" alt="Next"></a> | |
| </div> | |
| </body> | |
| </html> |