libs/vmd/doc/html/variadic_macro_data/vmd_modifiers/vmd_modifiers_identifier.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Identifier modifiers</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&#160;1.&#160;The Variadic Macro Data Library 1.9">
   8 <link rel="up" href="../vmd_modifiers.html" title="Macros with modifiers">
   9 <link rel="prev" href="vmd_modifiers_filter.html" title="Filtering modifiers">
  10 <link rel="next" href="vmd_modifiers_splitting.html" title="Splitting modifiers">
  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="vmd_modifiers_filter.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../vmd_modifiers.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="vmd_modifiers_splitting.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h3 class="title">
  27 <a name="variadic_macro_data.vmd_modifiers.vmd_modifiers_identifier"></a><a class="link" href="vmd_modifiers_identifier.html" title="Identifier modifiers">Identifier
  28       modifiers</a>
  29 </h3></div></div></div>
  30 <p>
  31         Identifier modifiers are optional parameters which specify a set of identifiers
  32         to search in order to look for a particular identifier match rather than
  33         just any identifier.
  34       </p>
  35 <h5>
  36 <a name="variadic_macro_data.vmd_modifiers.vmd_modifiers_identifier.h0"></a>
  37         <span class="phrase"><a name="variadic_macro_data.vmd_modifiers.vmd_modifiers_identifier.usage_with_boost_vmd_is_identifi"></a></span><a class="link" href="vmd_modifiers_identifier.html#variadic_macro_data.vmd_modifiers.vmd_modifiers_identifier.usage_with_boost_vmd_is_identifi">Usage
  38         with BOOST_VMD_IS_IDENTIFIER</a>
  39       </h5>
  40 <p>
  41         Once we have both registered and pre-detected an identifier we can test whether
  42         an identifier is a particular identifier using BOOST_VMD_IS_IDENTIFER and
  43         identifier modifiers. We do this by passing optional parameter(s) to BOOST_VMD_IS_IDENTIFER.
  44         The optional parameter(s) are either a single tuple of possible identifiers
  45         we are trying to match, or the individual identifiers themselves as separate
  46         parameters.
  47       </p>
  48 <p>
  49         Using the optional parameter(s) with BOOST_VMD_IS_IDENTIFER we are asking
  50         not only if our input is any of the registered identifiers but also if it
  51         is one of a number of pre-detected identifiers.
  52       </p>
  53 <p>
  54         As an example:
  55       </p>
  56 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">vmd</span><span class="special">/</span><span class="identifier">is_identifier</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
  57
  58 <span class="preprocessor">#define</span> <span class="identifier">BOOST_VMD_REGISTER_yellow</span> <span class="special">(</span><span class="identifier">yellow</span><span class="special">)</span>
  59 <span class="preprocessor">#define</span> <span class="identifier">BOOST_VMD_REGISTER_green</span> <span class="special">(</span><span class="identifier">green</span><span class="special">)</span>
  60 <span class="preprocessor">#define</span> <span class="identifier">BOOST_VMD_REGISTER_blue</span> <span class="special">(</span><span class="identifier">blue</span><span class="special">)</span>
  61 <span class="preprocessor">#define</span> <span class="identifier">BOOST_VMD_REGISTER_red</span> <span class="special">(</span><span class="identifier">red</span><span class="special">)</span>
  62
  63 <span class="preprocessor">#define</span> <span class="identifier">BOOST_VMD_DETECT_yellow_yellow</span>
  64 <span class="preprocessor">#define</span> <span class="identifier">BOOST_VMD_DETECT_green_green</span>
  65 <span class="preprocessor">#define</span> <span class="identifier">BOOST_VMD_DETECT_blue_blue</span>
  66
  67 <span class="identifier">BOOST_VMD_IS_IDENTIFIER</span><span class="special">(</span><span class="identifier">some_input</span><span class="special">,</span><span class="identifier">yellow</span><span class="special">)</span> <span class="comment">// returns 1 only if 'some_input is 'yellow', else returns 0</span>
  68 <span class="identifier">BOOST_VMD_IS_IDENTIFIER</span><span class="special">(</span><span class="identifier">some_input</span><span class="special">,</span><span class="identifier">yellow</span><span class="special">,</span><span class="identifier">blue</span><span class="special">)</span> <span class="comment">// returns 1 only if 'some_input is 'yellow' or 'blue', else returns 0</span>
  69 <span class="identifier">BOOST_VMD_IS_IDENTIFIER</span><span class="special">(</span><span class="identifier">some_input</span><span class="special">,(</span><span class="identifier">yellow</span><span class="special">,</span><span class="identifier">green</span><span class="special">))</span> <span class="comment">// returns 1 if 'some_input' is 'yellow' or 'green', else returns 0</span>
  70
  71 <span class="identifier">BOOST_VMD_IS_IDENTIFIER</span><span class="special">(</span><span class="identifier">some_input</span><span class="special">,</span><span class="identifier">red</span><span class="special">)</span>
  72    <span class="comment">// always returns 0, even if 'some_input' is 'red' since 'red' has not been pre-detected</span>
  73 </pre>
  74 <p>
  75         whereas
  76       </p>
  77 <pre class="programlisting"><span class="identifier">BOOST_VMD_IS_IDENTIFIER</span><span class="special">(</span><span class="identifier">some_input</span><span class="special">)</span> <span class="comment">// returns 1 if 'some_input' is 'red' since 'red' has been registered</span>
  78 </pre>
  79 <p>
  80         If you invoke BOOST_VMD_IS_IDENTIFIER with the optional parameter(s), the
  81         invocation will only return 1 if the input matches one the identifier(s)
  82         of the optional parameters and the identifier it matches has been registered
  83         and pre-detected.
  84       </p>
  85 <p>
  86         Both VMD numbers and v-types are identifier subtypes so you can also use
  87         them as identifier modifiers. You do not have to register or pre-detect VMD
  88         numbers or v-types since VMD has already done that for you.
  89       </p>
  90 <p>
  91         As an example of using VMD numbers or v-types as identifier modifiers with
  92         BOOST_VMD_IS_IDENTIFIER:
  93       </p>
  94 <pre class="programlisting"><span class="identifier">BOOST_VMD_IS_IDENTIFIER</span><span class="special">(</span><span class="identifier">some_input</span><span class="special">,</span><span class="number">1</span><span class="special">,</span><span class="number">3</span><span class="special">,</span><span class="number">5</span><span class="special">)</span> <span class="comment">// returns 1 only if 'some_input' is 1 or 3 or 5, else returns 0</span>
  95 <span class="identifier">BOOST_VMD_IS_IDENTIFIER</span><span class="special">(</span><span class="identifier">some_input</span><span class="special">,</span><span class="identifier">BOOST_VMD_TYPE_TUPLE</span><span class="special">,</span><span class="identifier">BOOST_VMD_TYPE_LIST</span><span class="special">,</span><span class="number">59</span><span class="special">)</span>
  96    <span class="comment">// returns 1 only if 'some_input is the v-type BOOST_VMD_TYPE_TUPLE or the v-type BOOST_VMD_TYPE_LIST or 59, else returns 0</span>
  97 </pre>
  98 <h5>
  99 <a name="variadic_macro_data.vmd_modifiers.vmd_modifiers_identifier.h1"></a>
 100         <span class="phrase"><a name="variadic_macro_data.vmd_modifiers.vmd_modifiers_identifier.usage_with_boost_vmd_elem"></a></span><a class="link" href="vmd_modifiers_identifier.html#variadic_macro_data.vmd_modifiers.vmd_modifiers_identifier.usage_with_boost_vmd_elem">Usage
 101         with BOOST_VMD_ELEM</a>
 102       </h5>
 103 <p>
 104         When we use the specific filter modifier BOOST_VMD_TYPE_IDENTIFIER as an
 105         optional parameter of BOOST_VMD_ELEM we are asking for a particular element
 106         of a sequence as long as it is a VMD identifier. With that specific filter
 107         modifier BOOST_VMD_TYPE_IDENTIFIER we can use identifier modifiers to ask
 108         for a particular element of a sequence as long as it matches one of our identifier
 109         modifiers. If the specific filter modifier BOOST_VMD_TYPE_IDENTIFIER is not
 110         being used then all identifier modifiers are ignored.
 111       </p>
 112 <p>
 113         The syntax for specifying identifier modifiers using BOOST_VMD_ELEM is exactly
 114         the same as the equivalent feature of the BOOST_VMD_IS_IDENTIFIER macro explained
 115         just previously. Optional parameters in the form of identifiers can be specified
 116         either singly any number of times or once as part of a tuple. For an identifier
 117         found as a sequence element to match against one of these possible identifiers,
 118         the possible identifiers must be both registered and pre-detected.
 119       </p>
 120 <p>
 121         Since filter modifiers, which are v-types, are also identifiers, if you want
 122         to use v-types as identifier modifiers you must use the form which places
 123         all identifier modifiers as part of a tuple. Otherwise any v-types specified
 124         singly as optional parameters are seen as filter modifiers and never as identifier
 125         modifiers. VMD numbers are also identifiers and may be used as identifier
 126         modifiers, but in this case VMD numbers as identifier modifiers do not need
 127         to be part of a tuple to be detected.
 128       </p>
 129 <p>
 130         Let's see how this works:
 131       </p>
 132 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">vmd</span><span class="special">/</span><span class="identifier">elem</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 133
 134 <span class="preprocessor">#define</span> <span class="identifier">BOOST_VMD_REGISTER_ANAME</span> <span class="special">(</span><span class="identifier">ANAME</span><span class="special">)</span>
 135 <span class="preprocessor">#define</span> <span class="identifier">BOOST_VMD_REGISTER_APLACE</span> <span class="special">(</span><span class="identifier">APLACE</span><span class="special">)</span>
 136 <span class="preprocessor">#define</span> <span class="identifier">BOOST_VMD_REGISTER_ACOUNTRY</span> <span class="special">(</span><span class="identifier">ACOUNTRY</span><span class="special">)</span>
 137
 138 <span class="preprocessor">#define</span> <span class="identifier">BOOST_VMD_DETECT_ANAME_ANAME</span>
 139 <span class="preprocessor">#define</span> <span class="identifier">BOOST_VMD_DETECT_APLACE_APLACE</span>
 140
 141 <span class="preprocessor">#define</span> <span class="identifier">A_SEQUENCE</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">ANAME</span> <span class="number">46</span> <span class="identifier">BOOST_VMD_TYPE_SEQ</span> <span class="identifier">ACOUNTRY</span>
 142
 143 <span class="identifier">BOOST_VMD_ELEM</span><span class="special">(</span><span class="number">1</span><span class="special">,</span><span class="identifier">A_SEQUENCE</span><span class="special">)</span> <span class="identifier">will</span> <span class="keyword">return</span> <span class="char">'ANAME'</span>
 144 <span class="identifier">BOOST_VMD_ELEM</span><span class="special">(</span><span class="number">1</span><span class="special">,</span><span class="identifier">A_SEQUENCE</span><span class="special">,</span><span class="identifier">BOOST_VMD_TYPE_IDENTIFIER</span><span class="special">)</span> <span class="identifier">will</span> <span class="keyword">return</span> <span class="char">'ANAME'</span>
 145 <span class="identifier">BOOST_VMD_ELEM</span><span class="special">(</span><span class="number">1</span><span class="special">,</span><span class="identifier">A_SEQUENCE</span><span class="special">,</span><span class="identifier">BOOST_VMD_TYPE_IDENTIFIER</span><span class="special">,</span><span class="identifier">APLACE</span><span class="special">,</span><span class="identifier">ACOUNTRY</span><span class="special">)</span> <span class="identifier">will</span> <span class="keyword">return</span> <span class="identifier">emptiness</span>
 146 <span class="identifier">BOOST_VMD_ELEM</span><span class="special">(</span><span class="number">1</span><span class="special">,</span><span class="identifier">A_SEQUENCE</span><span class="special">,</span><span class="identifier">BOOST_VMD_TYPE_IDENTIFIER</span><span class="special">,</span><span class="identifier">ANAME</span><span class="special">,</span><span class="identifier">APLACE</span><span class="special">,</span><span class="identifier">ACOUNTRY</span><span class="special">)</span> <span class="identifier">will</span> <span class="keyword">return</span> <span class="char">'ANAME'</span>
 147 <span class="identifier">BOOST_VMD_ELEM</span><span class="special">(</span><span class="number">1</span><span class="special">,</span><span class="identifier">A_SEQUENCE</span><span class="special">,</span><span class="identifier">BOOST_VMD_TYPE_IDENTIFIER</span><span class="special">,(</span><span class="identifier">APLACE</span><span class="special">,</span><span class="identifier">ACOUNTRY</span><span class="special">,</span><span class="identifier">ANAME</span><span class="special">))</span> <span class="identifier">will</span> <span class="keyword">return</span> <span class="char">'ANAME'</span>
 148
 149 <span class="identifier">BOOST_VMD_ELEM</span><span class="special">(</span><span class="number">4</span><span class="special">,</span><span class="identifier">A_SEQUENCE</span><span class="special">)</span> <span class="identifier">will</span> <span class="keyword">return</span> <span class="char">'ACOUNTRY'</span>
 150 <span class="identifier">BOOST_VMD_ELEM</span><span class="special">(</span><span class="number">4</span><span class="special">,</span><span class="identifier">A_SEQUENCE</span><span class="special">,</span><span class="identifier">BOOST_VMD_TYPE_IDENTIFIER</span><span class="special">)</span> <span class="identifier">will</span> <span class="keyword">return</span> <span class="char">'ACOUNTRY'</span>
 151 <span class="identifier">BOOST_VMD_ELEM</span><span class="special">(</span><span class="number">4</span><span class="special">,</span><span class="identifier">A_SEQUENCE</span><span class="special">,</span><span class="identifier">BOOST_VMD_TYPE_IDENTIFIER</span><span class="special">,</span><span class="identifier">ACOUNTRY</span><span class="special">,</span><span class="identifier">ANAME</span><span class="special">)</span>
 152    <span class="identifier">will</span> <span class="keyword">return</span> <span class="identifier">emptiness</span> <span class="identifier">since</span> <span class="identifier">ACOUNTRY</span> <span class="identifier">is</span> <span class="keyword">not</span> <span class="identifier">pre</span><span class="special">-</span><span class="identifier">detected</span>
 153 </pre>
 154 <p>
 155         Let us illustrate the case where VMD identifiers can be represented as either
 156         filter modifiers or identifier modifiers.
 157       </p>
 158 <p>
 159         Using the sequence above:
 160       </p>
 161 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">vmd</span><span class="special">/</span><span class="identifier">elem</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 162
 163 <span class="identifier">BOOST_VMD_ELEM</span><span class="special">(</span><span class="number">3</span><span class="special">,</span><span class="identifier">A_SEQUENCE</span><span class="special">)</span> <span class="identifier">will</span> <span class="keyword">return</span> <span class="identifier">the</span> <span class="identifier">BOOST_VMD_TYPE_SEQ</span> <span class="identifier">type</span>
 164 <span class="identifier">BOOST_VMD_ELEM</span><span class="special">(</span><span class="number">3</span><span class="special">,</span><span class="identifier">A_SEQUENCE</span><span class="special">,</span><span class="identifier">BOOST_VMD_TYPE_IDENTIFIER</span><span class="special">)</span>
 165    <span class="identifier">will</span> <span class="keyword">return</span> <span class="identifier">the</span> <span class="identifier">BOOST_VMD_TYPE_SEQ</span> <span class="identifier">type</span> <span class="identifier">since</span> <span class="identifier">a</span> <span class="identifier">type</span> <span class="identifier">is</span> <span class="identifier">an</span> <span class="identifier">identifier</span>
 166 <span class="identifier">BOOST_VMD_ELEM</span><span class="special">(</span><span class="number">3</span><span class="special">,</span><span class="identifier">A_SEQUENCE</span><span class="special">,</span><span class="identifier">BOOST_VMD_TYPE_IDENTIFIER</span><span class="special">,</span><span class="identifier">BOOST_VMD_TYPE_SEQ</span><span class="special">,</span><span class="identifier">BOOST_VMD_TYPE_TUPLE</span><span class="special">)</span> <span class="identifier">will</span> <span class="keyword">return</span> <span class="identifier">emptiness</span>
 167 </pre>
 168 <p>
 169         The last use of our macro returns emptiness because if there is more than
 170         one type specified as an optional parameter the last type is chosen for filtering.
 171         Since the last type for type filtering is BOOST_VMD_TYPE_TUPLE and our fourth
 172         element is a v-type and not a tuple, emptiness is returned. The syntax does
 173         not specifying filtering with identifiers as might be supposed since BOOST_VMD_TYPE_SEQ
 174         and BOOST_VMD_TYPE_TUPLE are not treated as identifier modifiers but rather
 175         as additional filter modifiers.
 176       </p>
 177 <p>
 178         In order to do filtering with an identifier and do it against various types
 179         themselves, since v-types are identifiers, we must use the tuple form to
 180         specify our identifier modifiers:
 181       </p>
 182 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">vmd</span><span class="special">/</span><span class="identifier">elem</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
 183
 184 <span class="identifier">BOOST_VMD_ELEM</span><span class="special">(</span><span class="number">3</span><span class="special">,</span><span class="identifier">A_SEQUENCE</span><span class="special">,</span><span class="identifier">BOOST_VMD_TYPE_IDENTIFIER</span><span class="special">,(</span><span class="identifier">BOOST_VMD_TYPE_SEQ</span><span class="special">,</span><span class="identifier">BOOST_VMD_TYPE_TUPLE</span><span class="special">))</span>
 185    <span class="identifier">will</span> <span class="keyword">return</span> <span class="identifier">BOOST_VMD_TYPE_SEQ</span>
 186 </pre>
 187 <p>
 188         Now BOOST_VMD_TYPE_SEQ and BOOST_VMD_TYPE_TUPLE are treated as identifiers
 189         modifiers to match against.
 190       </p>
 191 </div>
 192 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 193 <td align="left"></td>
 194 <td align="right"><div class="copyright-footer">Copyright &#169; 2010-2017 Tropic Software
 195       East Inc</div></td>
 196 </tr></table>
 197 <hr>
 198 <div class="spirit-nav">
 199 <a accesskey="p" href="vmd_modifiers_filter.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../vmd_modifiers.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="vmd_modifiers_splitting.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
 200 </div>
 201 </body>
 202 </html>