1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Macro BOOST_VMD_ELEM</title> 5<link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="index.html" title="Chapter 1. The Variadic Macro Data Library 1.9"> 8<link rel="up" href="header/boost/vmd/elem_hpp.html" title="Header <boost/vmd/elem.hpp>"> 9<link rel="prev" href="header/boost/vmd/elem_hpp.html" title="Header <boost/vmd/elem.hpp>"> 10<link rel="next" href="BOOST_VMD_ELEM_D.html" title="Macro BOOST_VMD_ELEM_D"> 11</head> 12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 13<table cellpadding="2" width="100%"><tr> 14<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td> 15<td align="center"><a href="../../../../index.html">Home</a></td> 16<td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td> 17<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> 18<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> 19<td align="center"><a href="../../../../more/index.htm">More</a></td> 20</tr></table> 21<hr> 22<div class="spirit-nav"> 23<a accesskey="p" href="header/boost/vmd/elem_hpp.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="header/boost/vmd/elem_hpp.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="BOOST_VMD_ELEM_D.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a> 24</div> 25<div class="refentry"> 26<a name="BOOST_VMD_ELEM"></a><div class="titlepage"></div> 27<div class="refnamediv"> 28<h2><span class="refentrytitle">Macro BOOST_VMD_ELEM</span></h2> 29<p>BOOST_VMD_ELEM — Accesses an element of a sequence. </p> 30</div> 31<h2 xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="refsynopsisdiv-title">Synopsis</h2> 32<div xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="refsynopsisdiv"><pre class="synopsis"><span class="comment">// In header: <<a class="link" href="header/boost/vmd/elem_hpp.html" title="Header <boost/vmd/elem.hpp>">boost/vmd/elem.hpp</a>> 33 34</span>BOOST_VMD_ELEM(elem, ...)</pre></div> 35<div class="refsect1"> 36<a name="idm46219108672208"></a><h2>Description</h2> 37<p>elem = A sequence element number. From 0 to sequence size - 1. <br> 38 ... = Variadic parameters.</p> 39<p>The first variadic parameter is required and is the sequence to access. Further variadic parameters are all optional.</p> 40<p>With no further variadic parameters the macro returns the particular element in the sequence. If the element number is outside the bounds of the sequence macro access fails and the macro turns emptiness.</p> 41<p>Optional parameters determine what it means that an element is successfully accessed as well as what data is returned by the macro.</p> 42<p>Filters: specifying a VMD type tells the macro to return the element only if it is of the VMD type specified, else macro access fails. If more than one VMD type is specified as an optional parameter the last one specified is the filter.</p> 43<p>Matching Identifiers: If the filter is specified as the identifier type, BOOST_VMD_TYPE_IDENTIFIER, optional parameters which are identifiers specify that the element accessed must match one of the identifiers else access fails. The identifiers may be specified multiple times as single optional parameters or once as a tuple of identifier parameters. If the identifiers are specified as single optional parameters they cannot be any of the specific BOOST_VMD_ optional parameters in order to be recognized as matching identifiers. Normally this should never be the case. The only situation where this could occur is if the VMD types, which are filters, are used as matching identifiers; in this case the matching identifiers need to be passed as a tuple of identifier parameters so they are not treated as filters.</p> 44<p>Filters and matching identifiers change what it means that an element is successfully accessed. They do not change what data is returned by the macro. The remaining optional parameters do not change what it means that an element is successfully accessed but they do change what data is returned by the macro.</p> 45<pre class="programlisting"><span class="identifier">Splitting</span><span class="special">:</span> <span class="identifier">Splitting</span> <span class="identifier">allows</span> <span class="identifier">the</span> <span class="identifier">macro</span> <span class="identifier">to</span> <span class="keyword">return</span> <span class="identifier">the</span> <span class="identifier">rest</span> <span class="identifier">of</span> <span class="identifier">the</span> <span class="identifier">sequence</span> 46 <span class="identifier">after</span> <span class="identifier">the</span> <span class="identifier">element</span> <span class="identifier">accessed</span><span class="special">.</span> 47 48 <span class="identifier">If</span> <span class="identifier">BOOST_VMD_RETURN_AFTER</span> <span class="identifier">is</span> <span class="identifier">specified</span> <span class="identifier">the</span> <span class="keyword">return</span> <span class="identifier">is</span> <span class="identifier">a</span> <span class="identifier">tuple</span> 49 <span class="identifier">with</span> <span class="identifier">the</span> <span class="identifier">element</span> <span class="identifier">accessed</span> <span class="identifier">as</span> <span class="identifier">the</span> <span class="identifier">first</span> <span class="identifier">tuple</span> <span class="identifier">parameter</span> <span class="identifier">and</span> <span class="identifier">the</span> <span class="identifier">rest</span> <span class="identifier">of</span> 50 <span class="identifier">the</span> <span class="identifier">sequence</span> <span class="identifier">as</span> <span class="identifier">the</span> <span class="identifier">second</span> <span class="identifier">tuple</span> <span class="identifier">parameter</span><span class="special">.</span> <span class="identifier">If</span> <span class="identifier">element</span> <span class="identifier">access</span> <span class="identifier">fails</span> 51 <span class="identifier">both</span> <span class="identifier">tuple</span> <span class="identifier">parameters</span> <span class="identifier">are</span> <span class="identifier">empty</span><span class="special">.</span> 52 53 <span class="identifier">If</span> <span class="identifier">BOOST_VMD_RETURN_ONLY_AFTER</span> 54 <span class="identifier">is</span> <span class="identifier">specified</span> <span class="identifier">the</span> <span class="keyword">return</span> <span class="identifier">is</span> <span class="identifier">the</span> <span class="identifier">rest</span> <span class="identifier">of</span> <span class="identifier">the</span> <span class="identifier">sequence</span> <span class="identifier">after</span> <span class="identifier">the</span> <span class="identifier">element</span> <span class="identifier">accessed</span> 55 <span class="identifier">found</span><span class="special">.</span> <span class="identifier">If</span> <span class="identifier">the</span> <span class="identifier">element</span> <span class="identifier">access</span> <span class="identifier">fails</span> <span class="identifier">the</span> <span class="keyword">return</span> <span class="identifier">is</span> <span class="identifier">emptiness</span><span class="special">.</span> 56 57 <span class="identifier">If</span> <span class="identifier">BOOST_VMD_RETURN_NO_AFTER</span><span class="special">,</span> <span class="identifier">the</span> <span class="keyword">default</span><span class="special">,</span> <span class="identifier">is</span> <span class="identifier">specified</span> <span class="identifier">no</span> <span class="identifier">splitting</span> 58 <span class="identifier">occurs</span><span class="special">.</span> 59 60 <span class="identifier">If</span> <span class="identifier">more</span> <span class="identifier">than</span> <span class="identifier">one</span> <span class="identifier">of</span> <span class="identifier">the</span> <span class="identifier">splitting</span> <span class="identifier">identifiers</span> <span class="identifier">are</span> <span class="identifier">specified</span> 61 <span class="identifier">the</span> <span class="identifier">last</span> <span class="identifier">one</span> <span class="identifier">specified</span> <span class="identifier">determines</span> <span class="identifier">the</span> <span class="identifier">splitting</span><span class="special">.</span> 62 63 <span class="identifier">Return</span> <span class="identifier">Type</span><span class="special">:</span> <span class="identifier">The</span> <span class="identifier">element</span> <span class="identifier">accessed</span> <span class="identifier">can</span> <span class="identifier">be</span> <span class="identifier">changed</span> <span class="identifier">to</span> <span class="keyword">return</span> <span class="identifier">both</span> <span class="identifier">the</span> <span class="identifier">type</span> 64 <span class="identifier">of</span> <span class="identifier">the</span> <span class="identifier">element</span> <span class="identifier">as</span> <span class="identifier">well</span> <span class="identifier">as</span> <span class="identifier">the</span> <span class="identifier">element</span> <span class="identifier">data</span> <span class="identifier">with</span> <span class="identifier">optional</span> <span class="keyword">return</span> <span class="identifier">type</span> 65 <span class="identifier">parameters</span><span class="special">.</span> <span class="identifier">When</span> <span class="identifier">a</span> <span class="identifier">type</span> <span class="identifier">is</span> <span class="identifier">returned</span><span class="special">,</span> <span class="identifier">the</span> <span class="identifier">element</span> <span class="identifier">accessed</span> <span class="identifier">which</span> <span class="identifier">is</span> <span class="identifier">returned</span> <span class="identifier">becomes</span> <span class="identifier">a</span> 66 <span class="identifier">two</span><span class="special">-</span><span class="identifier">element</span> <span class="identifier">tuple</span> <span class="identifier">where</span> <span class="identifier">the</span> <span class="identifier">type</span> <span class="identifier">of</span> <span class="identifier">the</span> <span class="identifier">element</span> <span class="identifier">accessed</span> <span class="identifier">is</span> <span class="identifier">the</span> <span class="identifier">first</span> <span class="identifier">tuple</span> <span class="identifier">element</span> <span class="identifier">and</span> <span class="identifier">the</span> <span class="identifier">element</span> 67 <span class="identifier">data</span> <span class="identifier">itself</span> <span class="identifier">is</span> <span class="identifier">the</span> <span class="identifier">second</span> <span class="identifier">tuple</span> <span class="identifier">element</span><span class="special">.</span> <span class="identifier">If</span> <span class="identifier">the</span> <span class="identifier">macro</span> <span class="identifier">fails</span> <span class="identifier">to</span> <span class="identifier">access</span> <span class="identifier">the</span> 68 <span class="identifier">element</span> <span class="identifier">the</span> <span class="identifier">element</span> <span class="identifier">access</span> <span class="identifier">returned</span> <span class="identifier">is</span> <span class="identifier">emptiness</span> <span class="identifier">and</span> <span class="identifier">not</span> <span class="identifier">a</span> <span class="identifier">tuple</span><span class="special">.</span> 69 70 <span class="identifier">If</span> <span class="identifier">BOOST_VMD_RETURN_NO_TYPE</span><span class="special">,</span> <span class="identifier">the</span> <span class="keyword">default</span><span class="special">,</span> <span class="identifier">is</span> <span class="identifier">specified</span> <span class="identifier">no</span> <span class="identifier">type</span> <span class="identifier">is</span> <span class="identifier">returned</span> 71 <span class="identifier">as</span> <span class="identifier">part</span> <span class="identifier">of</span> <span class="identifier">the</span> <span class="identifier">element</span> <span class="identifier">accessed</span><span class="special">.</span> 72 73 <span class="identifier">If</span> <span class="identifier">BOOST_VMD_RETURN_TYPE</span> <span class="identifier">is</span> <span class="identifier">specified</span> <span class="identifier">the</span> <span class="identifier">specific</span> <span class="identifier">type</span> <span class="identifier">of</span> <span class="identifier">the</span> <span class="identifier">element</span> 74 <span class="identifier">is</span> <span class="identifier">returned</span> <span class="identifier">in</span> <span class="identifier">the</span> <span class="identifier">tuple</span><span class="special">.</span> 75 76 <span class="identifier">If</span> <span class="identifier">BOOST_VMD_RETURN_TYPE_ARRAY</span> <span class="identifier">is</span> <span class="identifier">specified</span> 77 <span class="identifier">an</span> <span class="identifier">array</span> <span class="identifier">type</span> <span class="identifier">is</span> <span class="identifier">returned</span> <span class="keyword">if</span> <span class="identifier">the</span> <span class="identifier">element</span> <span class="identifier">is</span> <span class="identifier">an</span> <span class="identifier">array</span><span class="special">,</span> <span class="keyword">else</span> <span class="identifier">a</span> <span class="identifier">tuple</span> 78 <span class="identifier">type</span> <span class="identifier">is</span> <span class="identifier">returned</span> <span class="keyword">if</span> <span class="identifier">the</span> <span class="identifier">element</span> <span class="identifier">is</span> <span class="identifier">a</span> <span class="identifier">tuple</span><span class="special">,</span> <span class="keyword">else</span> <span class="identifier">the</span> <span class="identifier">actual</span> <span class="identifier">type</span> 79 <span class="identifier">is</span> <span class="identifier">returned</span> <span class="keyword">for</span> <span class="identifier">non</span><span class="special">-</span><span class="identifier">tuple</span> <span class="identifier">data</span><span class="special">.</span> 80 81 <span class="identifier">If</span> <span class="identifier">BOOST_VMD_RETURN_TYPE_LIST</span> <span class="identifier">is</span> <span class="identifier">specified</span> 82 <span class="identifier">a</span> <span class="identifier">list</span> <span class="identifier">type</span> <span class="identifier">is</span> <span class="identifier">returned</span> <span class="keyword">if</span> <span class="identifier">the</span> <span class="identifier">element</span> <span class="identifier">is</span> <span class="identifier">a</span> <span class="identifier">list</span><span class="special">,</span> <span class="keyword">else</span> <span class="identifier">a</span> <span class="identifier">tuple</span> 83 <span class="identifier">type</span> <span class="identifier">is</span> <span class="identifier">returned</span> <span class="keyword">if</span> <span class="identifier">the</span> <span class="identifier">element</span> <span class="identifier">is</span> <span class="identifier">a</span> <span class="identifier">tuple</span><span class="special">,</span> <span class="keyword">else</span> <span class="identifier">the</span> <span class="identifier">actual</span> <span class="identifier">type</span> 84 <span class="identifier">is</span> <span class="identifier">returned</span> <span class="keyword">for</span> <span class="identifier">non</span><span class="special">-</span><span class="identifier">tuple</span> <span class="identifier">data</span><span class="special">.</span> 85 86 <span class="identifier">If</span> <span class="identifier">BOOST_VMD_RETURN_TYPE_TUPLE</span> <span class="identifier">is</span> <span class="identifier">specified</span> 87 <span class="identifier">a</span> <span class="identifier">tuple</span> <span class="identifier">type</span> <span class="identifier">is</span> <span class="identifier">returned</span> <span class="keyword">for</span> <span class="identifier">all</span> <span class="identifier">tuple</span><span class="special">-</span><span class="identifier">like</span> <span class="identifier">data</span><span class="special">,</span> <span class="keyword">else</span> <span class="identifier">the</span> <span class="identifier">actual</span> <span class="identifier">type</span> 88 <span class="identifier">is</span> <span class="identifier">returned</span> <span class="keyword">for</span> <span class="identifier">non</span><span class="special">-</span><span class="identifier">tuple</span> <span class="identifier">data</span><span class="special">.</span> 89 90 <span class="identifier">If</span> <span class="identifier">more</span> <span class="identifier">than</span> <span class="identifier">one</span> <span class="keyword">return</span> <span class="identifier">type</span> <span class="identifier">optional</span> 91 <span class="identifier">parameter</span> <span class="identifier">is</span> <span class="identifier">specified</span> <span class="identifier">the</span> <span class="identifier">last</span> <span class="identifier">one</span> <span class="identifier">specified</span> <span class="identifier">determines</span> <span class="identifier">the</span> <span class="keyword">return</span> <span class="identifier">type</span><span class="special">.</span> 92 93 <span class="identifier">If</span> <span class="identifier">a</span> <span class="identifier">filter</span> <span class="identifier">is</span> <span class="identifier">specified</span> <span class="identifier">optional</span> <span class="keyword">return</span> <span class="identifier">type</span> <span class="identifier">parameters</span> <span class="identifier">are</span> <span class="identifier">ignored</span> <span class="identifier">and</span> 94 <span class="identifier">the</span> <span class="keyword">default</span> <span class="identifier">BOOST_VMD_RETURN_NO_TYPE</span> <span class="identifier">is</span> <span class="identifier">in</span> <span class="identifier">effect</span><span class="special">.</span> 95 96 <span class="identifier">Index</span><span class="special">:</span> <span class="identifier">If</span> <span class="identifier">the</span> <span class="identifier">filter</span> <span class="identifier">is</span> <span class="identifier">specified</span> <span class="identifier">as</span> <span class="identifier">the</span> <span class="identifier">identifier</span> <span class="identifier">type</span><span class="special">,</span> <span class="identifier">BOOST_VMD_TYPE_IDENTIFIER</span><span class="special">,</span> 97 <span class="identifier">and</span> <span class="identifier">matching</span> <span class="identifier">identifiers</span> <span class="identifier">are</span> <span class="identifier">specified</span><span class="special">,</span> <span class="identifier">an</span> <span class="identifier">index</span> <span class="identifier">parameter</span> <span class="identifier">specifies</span> <span class="identifier">that</span> <span class="identifier">the</span> 98 <span class="identifier">numeric</span> <span class="identifier">index</span><span class="special">,</span> <span class="identifier">starting</span> <span class="identifier">with</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">of</span> <span class="identifier">the</span> <span class="identifier">matching</span> <span class="identifier">identifier</span> <span class="identifier">found</span><span class="special">,</span> <span class="identifier">be</span> <span class="identifier">returned</span> 99 <span class="identifier">as</span> <span class="identifier">part</span> <span class="identifier">of</span> <span class="identifier">the</span> <span class="identifier">result</span><span class="special">.</span> 100 101 <span class="identifier">If</span> <span class="identifier">BOOST_VMD_RETURN_INDEX</span> <span class="identifier">is</span> <span class="identifier">specified</span> <span class="identifier">an</span> <span class="identifier">index</span> <span class="identifier">is</span> <span class="identifier">returned</span> 102 <span class="identifier">as</span> <span class="identifier">part</span> <span class="identifier">of</span> <span class="identifier">the</span> <span class="identifier">result</span><span class="special">.</span> 103 104 <span class="identifier">If</span> <span class="identifier">BOOST_VMD_RETURN_NO_INDEX</span><span class="special">,</span> <span class="identifier">the</span> <span class="keyword">default</span><span class="special">,</span> <span class="identifier">is</span> <span class="identifier">specified</span> 105 <span class="identifier">no</span> <span class="identifier">index</span> <span class="identifier">is</span> <span class="identifier">returned</span> <span class="identifier">as</span> <span class="identifier">part</span> <span class="identifier">of</span> <span class="identifier">the</span> <span class="identifier">result</span><span class="special">.</span> 106 107 <span class="identifier">If</span> <span class="identifier">both</span> <span class="identifier">are</span> <span class="identifier">specified</span> <span class="identifier">the</span> <span class="identifier">last</span> <span class="identifier">one</span> <span class="identifier">specified</span> <span class="identifier">determines</span> <span class="identifier">the</span> <span class="identifier">index</span> <span class="identifier">parameter</span><span class="special">.</span> 108 109 <span class="identifier">When</span> <span class="identifier">an</span> <span class="identifier">index</span> <span class="identifier">is</span> <span class="identifier">returned</span> <span class="identifier">as</span> <span class="identifier">part</span> <span class="identifier">of</span> <span class="identifier">the</span> <span class="identifier">result</span><span class="special">,</span> <span class="identifier">the</span> <span class="identifier">result</span> <span class="identifier">is</span> <span class="identifier">a</span> <span class="identifier">tuple</span> <span class="identifier">where</span> <span class="identifier">the</span> 110 <span class="identifier">element</span> <span class="identifier">accessed</span> <span class="identifier">is</span> <span class="identifier">the</span> <span class="identifier">first</span> <span class="identifier">tuple</span> <span class="identifier">parameter</span> <span class="identifier">and</span> <span class="identifier">the</span> <span class="identifier">index</span> <span class="identifier">is</span> <span class="identifier">the</span> <span class="identifier">last</span> <span class="identifier">tuple</span> <span class="identifier">parameter</span><span class="special">.</span> 111 <span class="identifier">If</span> <span class="identifier">element</span> <span class="identifier">access</span> <span class="identifier">fails</span> <span class="identifier">the</span> <span class="identifier">index</span> <span class="identifier">is</span> <span class="identifier">empty</span><span class="special">.</span> <span class="identifier">If</span> <span class="identifier">there</span> <span class="identifier">is</span> <span class="identifier">no</span> <span class="identifier">BOOST_VMD_TYPE_IDENTIFIER</span> 112 <span class="identifier">filter</span> <span class="identifier">or</span> <span class="keyword">if</span> <span class="identifier">there</span> <span class="identifier">are</span> <span class="identifier">no</span> <span class="identifier">matching</span> <span class="identifier">identifiers</span> <span class="identifier">the</span> <span class="identifier">BOOST_VMD_RETURN_INDEX</span> <span class="identifier">is</span> <span class="identifier">ignored</span> 113 <span class="identifier">and</span> <span class="identifier">no</span> <span class="identifier">index</span> <span class="identifier">is</span> <span class="identifier">returned</span> <span class="identifier">as</span> <span class="identifier">part</span> <span class="identifier">of</span> <span class="identifier">the</span> <span class="identifier">result</span><span class="special">.</span> 114</pre> 115<p>returns = With no optional parameters the element accessed is returned, or emptiness if element is outside the bounds of the sequence. Filters and matching identifiers can change the meaning of whether the element accessed is returned or failure occurs, but whenever failure occurs emptiness is returned as the element access part of that failure, else the element accessed is returned. Return type optional parameters, when filters are not used, return the element accessed as a two-element tuple where the first tuple element is the type and the second tuple element is the data; if the element is not accessed then emptiness is returned as the element access and not a tuple. Splitting with BOOST_VMD_RETURN_AFTER returns a tuple where the element accessed is the first tuple element and the rest of the sequence is the second tuple element. Splitting with BOOST_VMD_RETURN_ONLY_AFTER returns the rest of the sequence after the element accessed or emptiness if the element can not be accessed. Indexing returns the index as part of the output only if filtering with BOOST_VMD_TYPE_IDENTIFIER is specified and matching identifiers are specified. When the index is returned with BOOST_VMD_RETURN_AFTER it is the third element of the tuple returned, else it is the second element of a tuple where the element accessed is the first element of the tuple. </p> 116</div> 117</div> 118<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 119<td align="left"></td> 120<td align="right"><div class="copyright-footer">Copyright © 2010-2017 Tropic Software 121 East Inc</div></td> 122</tr></table> 123<hr> 124<div class="spirit-nav"> 125<a accesskey="p" href="header/boost/vmd/elem_hpp.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="header/boost/vmd/elem_hpp.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="BOOST_VMD_ELEM_D.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a> 126</div> 127</body> 128</html> 129
