1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Increment the Iterator pointing into a Container Attribute</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="Spirit 2.5.8"> 8<link rel="up" href="../iterate.html" title="Extract Attribute Values to Generate Output from a Container (Karma)"> 9<link rel="prev" href="end_container.html" title="Get the Iterator pointing to the End of a Container Attribute"> 10<link rel="next" href="deref_iterator.html" title="Dereference the Iterator pointing into a Container Attribute"> 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="end_container.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../iterate.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="deref_iterator.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a> 24</div> 25<div class="section"> 26<div class="titlepage"><div><div><h5 class="title"> 27<a name="spirit.advanced.customize.iterate.next_iterator"></a><a class="link" href="next_iterator.html" title="Increment the Iterator pointing into a Container Attribute">Increment 28 the Iterator pointing into a Container Attribute</a> 29</h5></div></div></div> 30<h6> 31<a name="spirit.advanced.customize.iterate.next_iterator.h0"></a> 32 <span class="phrase"><a name="spirit.advanced.customize.iterate.next_iterator.next_iterator"></a></span><a class="link" href="next_iterator.html#spirit.advanced.customize.iterate.next_iterator.next_iterator">next_iterator</a> 33 </h6> 34<p> 35 The template <code class="computeroutput"><span class="identifier">next_iterator</span></code> 36 is a type used as an attribute customization point. It is invoked by 37 the <span class="emphasis"><em>Karma</em></span> repetitive generators (such as <a class="link" href="../../../karma/reference/operator/list.html" title="List Generator (a % b)">List 38 (<code class="computeroutput"><span class="special">%</span></code>)</a>, <a class="link" href="../../../karma/reference/operator/kleene.html" title="Kleene Star Generator (*a)">Kleene 39 (unary <code class="computeroutput"><span class="special">*</span></code>)</a>, <a class="link" href="../../../karma/reference/operator/plus.html" title="Plus Generator (+a)">Plus (unary <code class="computeroutput"><span class="special">+</span></code>)</a>, and <a class="link" href="../../../karma/reference/directive/repeat.html" title="Repetition Generator Directive (repeat[])">Repeat</a>) 40 in order to get an iterator pointing to the next element of a container 41 holding the attributes to generate output from. 42 </p> 43<h6> 44<a name="spirit.advanced.customize.iterate.next_iterator.h1"></a> 45 <span class="phrase"><a name="spirit.advanced.customize.iterate.next_iterator.module_headers"></a></span><a class="link" href="next_iterator.html#spirit.advanced.customize.iterate.next_iterator.module_headers">Module 46 Headers</a> 47 </h6> 48<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">home</span><span class="special">/</span><span class="identifier">support</span><span class="special">/</span><span class="identifier">container</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 49</pre> 50<p> 51 Also, see <a class="link" href="../../../structure/include.html" title="Include">Include Structure</a>. 52 </p> 53<div class="note"><table border="0" summary="Note"> 54<tr> 55<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../images/note.png"></td> 56<th align="left">Note</th> 57</tr> 58<tr><td align="left" valign="top"><p> 59 This header file does not need to be included directly by any user 60 program as it is normally included by other Spirit header files relying 61 on its content. 62 </p></td></tr> 63</table></div> 64<h6> 65<a name="spirit.advanced.customize.iterate.next_iterator.h2"></a> 66 <span class="phrase"><a name="spirit.advanced.customize.iterate.next_iterator.namespace"></a></span><a class="link" href="next_iterator.html#spirit.advanced.customize.iterate.next_iterator.namespace">Namespace</a> 67 </h6> 68<div class="informaltable"><table class="table"> 69<colgroup><col></colgroup> 70<thead><tr><th> 71 <p> 72 Name 73 </p> 74 </th></tr></thead> 75<tbody><tr><td> 76 <p> 77 <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">spirit</span><span class="special">::</span><span class="identifier">traits</span></code> 78 </p> 79 </td></tr></tbody> 80</table></div> 81<h6> 82<a name="spirit.advanced.customize.iterate.next_iterator.h3"></a> 83 <span class="phrase"><a name="spirit.advanced.customize.iterate.next_iterator.synopsis"></a></span><a class="link" href="next_iterator.html#spirit.advanced.customize.iterate.next_iterator.synopsis">Synopsis</a> 84 </h6> 85<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">typename</span> <span class="identifier">Iterator</span><span class="special">,</span> <span class="keyword">typename</span> <span class="identifier">Enable</span><span class="special">></span> 86<span class="keyword">struct</span> <span class="identifier">next_iterator</span> 87<span class="special">{</span> 88 <span class="keyword">static</span> <span class="keyword">void</span> <span class="identifier">call</span><span class="special">(</span><span class="identifier">Iterator</span><span class="special">&</span> <span class="identifier">it</span><span class="special">);</span> 89<span class="special">};</span> 90</pre> 91<h6> 92<a name="spirit.advanced.customize.iterate.next_iterator.h4"></a> 93 <span class="phrase"><a name="spirit.advanced.customize.iterate.next_iterator.template_parameters"></a></span><a class="link" href="next_iterator.html#spirit.advanced.customize.iterate.next_iterator.template_parameters">Template 94 parameters</a> 95 </h6> 96<div class="informaltable"><table class="table"> 97<colgroup> 98<col> 99<col> 100<col> 101</colgroup> 102<thead><tr> 103<th> 104 <p> 105 Parameter 106 </p> 107 </th> 108<th> 109 <p> 110 Description 111 </p> 112 </th> 113<th> 114 <p> 115 Default 116 </p> 117 </th> 118</tr></thead> 119<tbody> 120<tr> 121<td> 122 <p> 123 <code class="computeroutput"><span class="identifier">Iterator</span></code> 124 </p> 125 </td> 126<td> 127 <p> 128 The type, <code class="computeroutput"><span class="identifier">Iterator</span></code> 129 of the iterator to increment. This is the same as the type 130 returned by the customization point <a class="link" href="container_iterator.html" title="Determine the Type of the Iterator of a Container"><code class="computeroutput"><span class="identifier">traits</span><span class="special">::</span><span class="identifier">container_iterator</span></code></a>. 131 </p> 132 </td> 133<td> 134 <p> 135 none 136 </p> 137 </td> 138</tr> 139<tr> 140<td> 141 <p> 142 <code class="computeroutput"><span class="identifier">Enable</span></code> 143 </p> 144 </td> 145<td> 146 <p> 147 Helper template parameter usable to selectively enable or disable 148 certain specializations of <code class="computeroutput"><span class="identifier">next_iterator</span></code> 149 utilizing SFINAE (i.e. <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">enable_if</span></code> 150 or <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">disable_if</span></code>). 151 </p> 152 </td> 153<td> 154 <p> 155 <code class="computeroutput"><span class="keyword">void</span></code> 156 </p> 157 </td> 158</tr> 159</tbody> 160</table></div> 161<div class="variablelist"> 162<p class="title"><b>Notation</b></p> 163<dl class="variablelist"> 164<dt><span class="term"><code class="computeroutput"><span class="identifier">Iterator</span></code></span></dt> 165<dd><p> 166 An iterator type. 167 </p></dd> 168<dt><span class="term"><code class="computeroutput"><span class="identifier">it</span></code></span></dt> 169<dd><p> 170 An instance of an iterator of type <code class="computeroutput"><span class="identifier">Iterator</span></code>. 171 </p></dd> 172<dt><span class="term"><code class="computeroutput"><span class="identifier">C</span></code></span></dt> 173<dd><p> 174 A container type whose iterator type is <code class="computeroutput"><span class="identifier">Iterator</span></code>. 175 </p></dd> 176</dl> 177</div> 178<h6> 179<a name="spirit.advanced.customize.iterate.next_iterator.h5"></a> 180 <span class="phrase"><a name="spirit.advanced.customize.iterate.next_iterator.expression_semantics"></a></span><a class="link" href="next_iterator.html#spirit.advanced.customize.iterate.next_iterator.expression_semantics">Expression 181 Semantics</a> 182 </h6> 183<div class="informaltable"><table class="table"> 184<colgroup> 185<col> 186<col> 187</colgroup> 188<thead><tr> 189<th> 190 <p> 191 Expression 192 </p> 193 </th> 194<th> 195 <p> 196 Semantics 197 </p> 198 </th> 199</tr></thead> 200<tbody><tr> 201<td> 202 <p> 203 <code class="computeroutput"><span class="identifier">next_iterator</span><span class="special"><</span><span class="identifier">Iterator</span><span class="special">>::</span><span class="identifier">call</span><span class="special">(</span><span class="identifier">it</span><span class="special">)</span></code> 204 </p> 205 </td> 206<td> 207 <p> 208 Increment the iterator pointing so that it is pointing to the 209 next element. 210 </p> 211 </td> 212</tr></tbody> 213</table></div> 214<h6> 215<a name="spirit.advanced.customize.iterate.next_iterator.h6"></a> 216 <span class="phrase"><a name="spirit.advanced.customize.iterate.next_iterator.predefined_specializations"></a></span><a class="link" href="next_iterator.html#spirit.advanced.customize.iterate.next_iterator.predefined_specializations">Predefined 217 Specializations</a> 218 </h6> 219<p> 220 <a href="http://boost-spirit.com" target="_top">Spirit</a> predefines specializations 221 of this customization point for several types. The following table lists 222 those types together with the types returned by the embedded typedef 223 <code class="computeroutput"><span class="identifier">type</span></code>: 224 </p> 225<div class="informaltable"><table class="table"> 226<colgroup> 227<col> 228<col> 229</colgroup> 230<thead><tr> 231<th> 232 <p> 233 Template Parameters 234 </p> 235 </th> 236<th> 237 <p> 238 Semantics 239 </p> 240 </th> 241</tr></thead> 242<tbody> 243<tr> 244<td> 245 <p> 246 <code class="computeroutput"><span class="identifier">Iterator</span></code> 247 </p> 248 </td> 249<td> 250 <p> 251 Executes <code class="computeroutput"><span class="special">++</span><span class="identifier">it</span></code>. 252 </p> 253 </td> 254</tr> 255<tr> 256<td> 257 <p> 258 <code class="computeroutput"><span class="identifier">unused_type</span></code><code class="computeroutput"> 259 <span class="keyword">const</span><span class="special">*</span></code> 260 </p> 261 </td> 262<td> 263 <p> 264 Does nothing. 265 </p> 266 </td> 267</tr> 268</tbody> 269</table></div> 270<h6> 271<a name="spirit.advanced.customize.iterate.next_iterator.h7"></a> 272 <span class="phrase"><a name="spirit.advanced.customize.iterate.next_iterator.when_to_implement"></a></span><a class="link" href="next_iterator.html#spirit.advanced.customize.iterate.next_iterator.when_to_implement">When 273 to implement</a> 274 </h6> 275<p> 276 The customization point <code class="computeroutput"><span class="identifier">next_iterator</span></code> 277 needs to be implemented for a specific iterator type whenever the container 278 this iterator belongs to is to be used as an attribute in place of a 279 STL container. It is applicable for generators (<span class="emphasis"><em>Spirit.Karma</em></span>) 280 only. As a rule of thumb: it has to be implemented whenever a certain 281 iterator type belongs to a container which is to be passed as an attribute 282 to a generator normally exposing a STL container, <code class="computeroutput"><span class="identifier">C</span></code> 283 and if the container type does not expose the interface of a STL container 284 (i.e. <code class="computeroutput"><span class="identifier">is_container</span><span class="special"><</span><span class="identifier">C</span><span class="special">>::</span><span class="identifier">type</span></code> would normally return <code class="computeroutput"><span class="identifier">mpl</span><span class="special">::</span><span class="identifier">false_</span></code>). 285 </p> 286<h6> 287<a name="spirit.advanced.customize.iterate.next_iterator.h8"></a> 288 <span class="phrase"><a name="spirit.advanced.customize.iterate.next_iterator.related_attribute_customization_points"></a></span><a class="link" href="next_iterator.html#spirit.advanced.customize.iterate.next_iterator.related_attribute_customization_points">Related 289 Attribute Customization Points</a> 290 </h6> 291<p> 292 If this customization point is implemented, the following other customization 293 points might need to be implemented as well. 294 </p> 295<div class="informaltable"><table class="table"> 296<colgroup> 297<col> 298<col> 299</colgroup> 300<thead><tr> 301<th> 302 <p> 303 Name 304 </p> 305 </th> 306<th> 307 <p> 308 When to implement 309 </p> 310 </th> 311</tr></thead> 312<tbody> 313<tr> 314<td> 315 <p> 316 <a class="link" href="../is_container.html" title="Determine if a Type Should be Treated as a Container (Qi and Karma)"><code class="computeroutput"><span class="identifier">traits</span><span class="special">::</span><span class="identifier">is_container</span></code></a> 317 </p> 318 </td> 319<td> 320 <p> 321 Needs to be implemented whenever a type is to be used as a 322 container attribute in <span class="emphasis"><em>Karma</em></span>. 323 </p> 324 </td> 325</tr> 326<tr> 327<td> 328 <p> 329 <a class="link" href="container_iterator.html" title="Determine the Type of the Iterator of a Container"><code class="computeroutput"><span class="identifier">traits</span><span class="special">::</span><span class="identifier">container_iterator</span></code></a> 330 </p> 331 </td> 332<td> 333 <p> 334 Karma: <a class="link" href="../../../karma/reference/operator/list.html" title="List Generator (a % b)">List 335 (<code class="computeroutput"><span class="special">%</span></code>)</a>, <a class="link" href="../../../karma/reference/operator/kleene.html" title="Kleene Star Generator (*a)">Kleene (unary 336 <code class="computeroutput"><span class="special">*</span></code>)</a>, <a class="link" href="../../../karma/reference/operator/plus.html" title="Plus Generator (+a)">Plus (unary 337 <code class="computeroutput"><span class="special">+</span></code>)</a>, <a class="link" href="../../../karma/reference/directive/repeat.html" title="Repetition Generator Directive (repeat[])">Repeat</a>. 338 </p> 339 </td> 340</tr> 341<tr> 342<td> 343 <p> 344 <a class="link" href="begin_container.html" title="Get the Iterator pointing to the Begin of a Container Attribute"><code class="computeroutput"><span class="identifier">traits</span><span class="special">::</span><span class="identifier">begin_container</span></code></a> 345 </p> 346 </td> 347<td> 348 <p> 349 Karma: <a class="link" href="../../../karma/reference/operator/list.html" title="List Generator (a % b)">List 350 (<code class="computeroutput"><span class="special">%</span></code>)</a>, <a class="link" href="../../../karma/reference/operator/kleene.html" title="Kleene Star Generator (*a)">Kleene (unary 351 <code class="computeroutput"><span class="special">*</span></code>)</a>, <a class="link" href="../../../karma/reference/operator/plus.html" title="Plus Generator (+a)">Plus (unary 352 <code class="computeroutput"><span class="special">+</span></code>)</a>, <a class="link" href="../../../karma/reference/directive/repeat.html" title="Repetition Generator Directive (repeat[])">Repeat</a>. 353 </p> 354 </td> 355</tr> 356<tr> 357<td> 358 <p> 359 <a class="link" href="end_container.html" title="Get the Iterator pointing to the End of a Container Attribute"><code class="computeroutput"><span class="identifier">traits</span><span class="special">::</span><span class="identifier">end_container</span></code></a> 360 </p> 361 </td> 362<td> 363 <p> 364 Karma: <a class="link" href="../../../karma/reference/operator/list.html" title="List Generator (a % b)">List 365 (<code class="computeroutput"><span class="special">%</span></code>)</a>, <a class="link" href="../../../karma/reference/operator/kleene.html" title="Kleene Star Generator (*a)">Kleene (unary 366 <code class="computeroutput"><span class="special">*</span></code>)</a>, <a class="link" href="../../../karma/reference/operator/plus.html" title="Plus Generator (+a)">Plus (unary 367 <code class="computeroutput"><span class="special">+</span></code>)</a>, <a class="link" href="../../../karma/reference/directive/repeat.html" title="Repetition Generator Directive (repeat[])">Repeat</a>. 368 </p> 369 </td> 370</tr> 371<tr> 372<td> 373 <p> 374 <a class="link" href="deref_iterator.html" title="Dereference the Iterator pointing into a Container Attribute"><code class="computeroutput"><span class="identifier">traits</span><span class="special">::</span><span class="identifier">deref_iterator</span></code></a> 375 </p> 376 </td> 377<td> 378 <p> 379 Karma: <a class="link" href="../../../karma/reference/operator/list.html" title="List Generator (a % b)">List 380 (<code class="computeroutput"><span class="special">%</span></code>)</a>, <a class="link" href="../../../karma/reference/operator/kleene.html" title="Kleene Star Generator (*a)">Kleene (unary 381 <code class="computeroutput"><span class="special">*</span></code>)</a>, <a class="link" href="../../../karma/reference/operator/plus.html" title="Plus Generator (+a)">Plus (unary 382 <code class="computeroutput"><span class="special">+</span></code>)</a>, <a class="link" href="../../../karma/reference/directive/repeat.html" title="Repetition Generator Directive (repeat[])">Repeat</a>. 383 </p> 384 </td> 385</tr> 386<tr> 387<td> 388 <p> 389 <a class="link" href="next_iterator.html" title="Increment the Iterator pointing into a Container Attribute"><code class="computeroutput"><span class="identifier">traits</span><span class="special">::</span><span class="identifier">next_iterator</span></code></a> 390 </p> 391 </td> 392<td> 393 <p> 394 Karma: <a class="link" href="../../../karma/reference/operator/list.html" title="List Generator (a % b)">List 395 (<code class="computeroutput"><span class="special">%</span></code>)</a>, <a class="link" href="../../../karma/reference/operator/kleene.html" title="Kleene Star Generator (*a)">Kleene (unary 396 <code class="computeroutput"><span class="special">*</span></code>)</a>, <a class="link" href="../../../karma/reference/operator/plus.html" title="Plus Generator (+a)">Plus (unary 397 <code class="computeroutput"><span class="special">+</span></code>)</a>, <a class="link" href="../../../karma/reference/directive/repeat.html" title="Repetition Generator Directive (repeat[])">Repeat</a>. 398 </p> 399 </td> 400</tr> 401<tr> 402<td> 403 <p> 404 <a class="link" href="compare_iterators.html" title="Compare two Iterator pointing into a Container Attribute for Equality"><code class="computeroutput"><span class="identifier">traits</span><span class="special">::</span><span class="identifier">compare_iterators</span></code></a> 405 </p> 406 </td> 407<td> 408 <p> 409 Karma: <a class="link" href="../../../karma/reference/operator/list.html" title="List Generator (a % b)">List 410 (<code class="computeroutput"><span class="special">%</span></code>)</a>, <a class="link" href="../../../karma/reference/operator/kleene.html" title="Kleene Star Generator (*a)">Kleene (unary 411 <code class="computeroutput"><span class="special">*</span></code>)</a>, <a class="link" href="../../../karma/reference/operator/plus.html" title="Plus Generator (+a)">Plus (unary 412 <code class="computeroutput"><span class="special">+</span></code>)</a>, <a class="link" href="../../../karma/reference/directive/repeat.html" title="Repetition Generator Directive (repeat[])">Repeat</a>. 413 </p> 414 </td> 415</tr> 416</tbody> 417</table></div> 418<h6> 419<a name="spirit.advanced.customize.iterate.next_iterator.h9"></a> 420 <span class="phrase"><a name="spirit.advanced.customize.iterate.next_iterator.example"></a></span><a class="link" href="next_iterator.html#spirit.advanced.customize.iterate.next_iterator.example">Example</a> 421 </h6> 422<p> 423 Here are the header files needed to make the example code below compile: 424 </p> 425<p> 426</p> 427<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">spirit</span><span class="special">/</span><span class="identifier">include</span><span class="special">/</span><span class="identifier">karma</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 428<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span> 429<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">string</span><span class="special">></span> 430<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">vector</span><span class="special">></span> 431</pre> 432<p> 433 </p> 434<p> 435 The example (for the full source code please see here: <a href="../../../../../../example/karma/customize_use_as_container.cpp" target="_top">customize_use_as_container.cpp</a>) 436 uses the data structure 437 </p> 438<p> 439</p> 440<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">client</span> 441<span class="special">{</span> 442 <span class="keyword">struct</span> <span class="identifier">use_as_container</span> 443 <span class="special">{</span> 444 <span class="comment">// Expose a pair holding a pointer to the use_as_container and to the </span> 445 <span class="comment">// current element as our iterator.</span> 446 <span class="comment">// We intentionally leave out having it a 'operator==()' to demonstrate</span> 447 <span class="comment">// the use of the 'compare_iterators' customization point.</span> 448 <span class="keyword">struct</span> <span class="identifier">iterator</span> 449 <span class="special">{</span> 450 <span class="identifier">iterator</span><span class="special">(</span><span class="identifier">use_as_container</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">container</span><span class="special">,</span> <span class="keyword">int</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">current</span><span class="special">)</span> 451 <span class="special">:</span> <span class="identifier">container_</span><span class="special">(</span><span class="identifier">container</span><span class="special">),</span> <span class="identifier">current_</span><span class="special">(</span><span class="identifier">current</span><span class="special">)</span> 452 <span class="special">{}</span> 453 454 <span class="identifier">use_as_container</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">container_</span><span class="special">;</span> 455 <span class="keyword">int</span> <span class="keyword">const</span><span class="special">*</span> <span class="identifier">current_</span><span class="special">;</span> 456 <span class="special">};</span> 457 458 <span class="comment">// expose 'int' as the type of each generated element</span> 459 <span class="keyword">typedef</span> <span class="keyword">int</span> <span class="identifier">type</span><span class="special">;</span> 460 461 <span class="identifier">use_as_container</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">value1</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">value2</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">value3</span><span class="special">)</span> 462 <span class="special">:</span> <span class="identifier">value1_</span><span class="special">(</span><span class="identifier">value1</span><span class="special">),</span> <span class="identifier">value2_</span><span class="special">(</span><span class="identifier">value2</span><span class="special">),</span> <span class="identifier">value3_</span><span class="special">(</span><span class="identifier">value3</span><span class="special">)</span> 463 <span class="special">{}</span> 464 465 <span class="keyword">int</span> <span class="identifier">value1_</span><span class="special">;</span> 466 <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">dummy1_</span><span class="special">;</span> <span class="comment">// insert some unrelated data</span> 467 <span class="keyword">int</span> <span class="identifier">value2_</span><span class="special">;</span> 468 <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">dummy2_</span><span class="special">;</span> <span class="comment">// insert some more unrelated data</span> 469 <span class="keyword">int</span> <span class="identifier">value3_</span><span class="special">;</span> 470 <span class="special">};</span> 471<span class="special">}</span> 472</pre> 473<p> 474 </p> 475<p> 476 as a direct attribute to the <a class="link" href="../../../karma/reference/operator/list.html" title="List Generator (a % b)">List 477 (<code class="computeroutput"><span class="special">%</span></code>)</a> generator. This 478 type does not expose any of the interfaces of an STL container. It does 479 not even expose the usual semantics of a container. The purpose of this 480 artificial example is to demonstrate how the customization points can 481 be used to expose independent data elements as a single container. The 482 example shows how to enable its use as an attribute to <span class="emphasis"><em>Karma's</em></span> 483 repetitive generators. 484 </p> 485<p> 486 In order to make this data structure compatible we need to specialize 487 a couple of attribute customization points: <a class="link" href="../is_container.html" title="Determine if a Type Should be Treated as a Container (Qi and Karma)"><code class="computeroutput"><span class="identifier">traits</span><span class="special">::</span><span class="identifier">is_container</span></code></a>, <a class="link" href="container_iterator.html" title="Determine the Type of the Iterator of a Container"><code class="computeroutput"><span class="identifier">traits</span><span class="special">::</span><span class="identifier">container_iterator</span></code></a>, <a class="link" href="begin_container.html" title="Get the Iterator pointing to the Begin of a Container Attribute"><code class="computeroutput"><span class="identifier">traits</span><span class="special">::</span><span class="identifier">begin_container</span></code></a>, and <a class="link" href="end_container.html" title="Get the Iterator pointing to the End of a Container Attribute"><code class="computeroutput"><span class="identifier">traits</span><span class="special">::</span><span class="identifier">end_container</span></code></a>. In addition, 488 we specialize all of the iterator related customization points as well: 489 <a class="link" href="deref_iterator.html" title="Dereference the Iterator pointing into a Container Attribute"><code class="computeroutput"><span class="identifier">traits</span><span class="special">::</span><span class="identifier">deref_iterator</span></code></a>, <a class="link" href="next_iterator.html" title="Increment the Iterator pointing into a Container Attribute"><code class="computeroutput"><span class="identifier">traits</span><span class="special">::</span><span class="identifier">next_iterator</span></code></a>, and <a class="link" href="compare_iterators.html" title="Compare two Iterator pointing into a Container Attribute for Equality"><code class="computeroutput"><span class="identifier">traits</span><span class="special">::</span><span class="identifier">compare_iterators</span></code></a>. 490 </p> 491<p> 492</p> 493<pre class="programlisting"><span class="comment">// All specializations of attribute customization points have to be placed into</span> 494<span class="comment">// the namespace boost::spirit::traits.</span> 495<span class="comment">//</span> 496<span class="comment">// Note that all templates below are specialized using the 'const' type.</span> 497<span class="comment">// This is necessary as all attributes in Karma are 'const'.</span> 498<span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">spirit</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">traits</span> 499<span class="special">{</span> 500 <span class="comment">// The specialization of the template 'is_container<>' will tell the </span> 501 <span class="comment">// library to treat the type 'client::use_as_container' as a </span> 502 <span class="comment">// container holding the items to generate output from.</span> 503 <span class="keyword">template</span> <span class="special"><></span> 504 <span class="keyword">struct</span> <span class="identifier">is_container</span><span class="special"><</span><span class="identifier">client</span><span class="special">::</span><span class="identifier">use_as_container</span> <span class="keyword">const</span><span class="special">></span> 505 <span class="special">:</span> <span class="identifier">mpl</span><span class="special">::</span><span class="identifier">true_</span> 506 <span class="special">{};</span> 507 508 <span class="comment">// The specialization of the template 'container_iterator<>' will be</span> 509 <span class="comment">// invoked by the library to evaluate the iterator type to be used</span> 510 <span class="comment">// for iterating the data elements in the container. We simply return</span> 511 <span class="comment">// the type of the iterator exposed by the embedded 'std::vector<int>'.</span> 512 <span class="keyword">template</span> <span class="special"><></span> 513 <span class="keyword">struct</span> <span class="identifier">container_iterator</span><span class="special"><</span><span class="identifier">client</span><span class="special">::</span><span class="identifier">use_as_container</span> <span class="keyword">const</span><span class="special">></span> 514 <span class="special">{</span> 515 <span class="keyword">typedef</span> <span class="identifier">client</span><span class="special">::</span><span class="identifier">use_as_container</span><span class="special">::</span><span class="identifier">iterator</span> <span class="identifier">type</span><span class="special">;</span> 516 <span class="special">};</span> 517 518 <span class="comment">// The specialization of the templates 'begin_container<>' and </span> 519 <span class="comment">// 'end_container<>' below will be used by the library to get the iterators </span> 520 <span class="comment">// pointing to the begin and the end of the data to generate output from. </span> 521 <span class="comment">//</span> 522 <span class="comment">// The passed argument refers to the attribute instance passed to the list </span> 523 <span class="comment">// generator.</span> 524 <span class="keyword">template</span> <span class="special"><></span> 525 <span class="keyword">struct</span> <span class="identifier">begin_container</span><span class="special"><</span><span class="identifier">client</span><span class="special">::</span><span class="identifier">use_as_container</span> <span class="keyword">const</span><span class="special">></span> 526 <span class="special">{</span> 527 <span class="keyword">static</span> <span class="identifier">client</span><span class="special">::</span><span class="identifier">use_as_container</span><span class="special">::</span><span class="identifier">iterator</span> 528 <span class="identifier">call</span><span class="special">(</span><span class="identifier">client</span><span class="special">::</span><span class="identifier">use_as_container</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">c</span><span class="special">)</span> 529 <span class="special">{</span> 530 <span class="keyword">return</span> <span class="identifier">client</span><span class="special">::</span><span class="identifier">use_as_container</span><span class="special">::</span><span class="identifier">iterator</span><span class="special">(&</span><span class="identifier">c</span><span class="special">,</span> <span class="special">&</span><span class="identifier">c</span><span class="special">.</span><span class="identifier">value1_</span><span class="special">);</span> 531 <span class="special">}</span> 532 <span class="special">};</span> 533 534 <span class="keyword">template</span> <span class="special"><></span> 535 <span class="keyword">struct</span> <span class="identifier">end_container</span><span class="special"><</span><span class="identifier">client</span><span class="special">::</span><span class="identifier">use_as_container</span> <span class="keyword">const</span><span class="special">></span> 536 <span class="special">{</span> 537 <span class="keyword">static</span> <span class="identifier">client</span><span class="special">::</span><span class="identifier">use_as_container</span><span class="special">::</span><span class="identifier">iterator</span> 538 <span class="identifier">call</span><span class="special">(</span><span class="identifier">client</span><span class="special">::</span><span class="identifier">use_as_container</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">c</span><span class="special">)</span> 539 <span class="special">{</span> 540 <span class="keyword">return</span> <span class="identifier">client</span><span class="special">::</span><span class="identifier">use_as_container</span><span class="special">::</span><span class="identifier">iterator</span><span class="special">(&</span><span class="identifier">c</span><span class="special">,</span> <span class="special">(</span><span class="keyword">int</span> <span class="keyword">const</span><span class="special">*)</span><span class="number">0</span><span class="special">);</span> 541 <span class="special">}</span> 542 <span class="special">};</span> 543<span class="special">}}}</span> 544</pre> 545<p> 546 </p> 547<p> 548</p> 549<pre class="programlisting"><span class="comment">// All specializations of attribute customization points have to be placed into</span> 550<span class="comment">// the namespace boost::spirit::traits.</span> 551<span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">spirit</span> <span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">traits</span> 552<span class="special">{</span> 553 <span class="comment">// The specialization of the template 'deref_iterator<>' will be used to </span> 554 <span class="comment">// dereference the iterator associated with our counter data structure.</span> 555 <span class="keyword">template</span> <span class="special"><></span> 556 <span class="keyword">struct</span> <span class="identifier">deref_iterator</span><span class="special"><</span><span class="identifier">client</span><span class="special">::</span><span class="identifier">use_as_container</span><span class="special">::</span><span class="identifier">iterator</span><span class="special">></span> 557 <span class="special">{</span> 558 <span class="keyword">typedef</span> <span class="identifier">client</span><span class="special">::</span><span class="identifier">use_as_container</span><span class="special">::</span><span class="identifier">type</span> <span class="identifier">type</span><span class="special">;</span> 559 560 <span class="keyword">static</span> <span class="identifier">type</span> <span class="identifier">call</span><span class="special">(</span><span class="identifier">client</span><span class="special">::</span><span class="identifier">use_as_container</span><span class="special">::</span><span class="identifier">iterator</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">it</span><span class="special">)</span> 561 <span class="special">{</span> 562 <span class="keyword">return</span> <span class="special">*</span><span class="identifier">it</span><span class="special">.</span><span class="identifier">current_</span><span class="special">;</span> 563 <span class="special">}</span> 564 <span class="special">};</span> 565 566 <span class="keyword">template</span> <span class="special"><></span> 567 <span class="keyword">struct</span> <span class="identifier">next_iterator</span><span class="special"><</span><span class="identifier">client</span><span class="special">::</span><span class="identifier">use_as_container</span><span class="special">::</span><span class="identifier">iterator</span><span class="special">></span> 568 <span class="special">{</span> 569 <span class="keyword">static</span> <span class="keyword">void</span> <span class="identifier">call</span><span class="special">(</span><span class="identifier">client</span><span class="special">::</span><span class="identifier">use_as_container</span><span class="special">::</span><span class="identifier">iterator</span><span class="special">&</span> <span class="identifier">it</span><span class="special">)</span> 570 <span class="special">{</span> 571 <span class="keyword">if</span> <span class="special">(</span><span class="identifier">it</span><span class="special">.</span><span class="identifier">current_</span> <span class="special">==</span> <span class="special">&</span><span class="identifier">it</span><span class="special">.</span><span class="identifier">container_</span><span class="special">-></span><span class="identifier">value1_</span><span class="special">)</span> 572 <span class="identifier">it</span><span class="special">.</span><span class="identifier">current_</span> <span class="special">=</span> <span class="special">&</span><span class="identifier">it</span><span class="special">.</span><span class="identifier">container_</span><span class="special">-></span><span class="identifier">value2_</span><span class="special">;</span> 573 <span class="keyword">else</span> <span class="keyword">if</span> <span class="special">(</span><span class="identifier">it</span><span class="special">.</span><span class="identifier">current_</span> <span class="special">==</span> <span class="special">&</span><span class="identifier">it</span><span class="special">.</span><span class="identifier">container_</span><span class="special">-></span><span class="identifier">value2_</span><span class="special">)</span> 574 <span class="identifier">it</span><span class="special">.</span><span class="identifier">current_</span> <span class="special">=</span> <span class="special">&</span><span class="identifier">it</span><span class="special">.</span><span class="identifier">container_</span><span class="special">-></span><span class="identifier">value3_</span><span class="special">;</span> 575 <span class="keyword">else</span> 576 <span class="identifier">it</span><span class="special">.</span><span class="identifier">current_</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> 577 <span class="special">}</span> 578 <span class="special">};</span> 579 580 <span class="keyword">template</span> <span class="special"><></span> 581 <span class="keyword">struct</span> <span class="identifier">compare_iterators</span><span class="special"><</span><span class="identifier">client</span><span class="special">::</span><span class="identifier">use_as_container</span><span class="special">::</span><span class="identifier">iterator</span><span class="special">></span> 582 <span class="special">{</span> 583 <span class="keyword">static</span> <span class="keyword">bool</span> <span class="identifier">call</span><span class="special">(</span><span class="identifier">client</span><span class="special">::</span><span class="identifier">use_as_container</span><span class="special">::</span><span class="identifier">iterator</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">it1</span> 584 <span class="special">,</span> <span class="identifier">client</span><span class="special">::</span><span class="identifier">use_as_container</span><span class="special">::</span><span class="identifier">iterator</span> <span class="keyword">const</span><span class="special">&</span> <span class="identifier">it2</span><span class="special">)</span> 585 <span class="special">{</span> 586 <span class="keyword">return</span> <span class="identifier">it1</span><span class="special">.</span><span class="identifier">current_</span> <span class="special">==</span> <span class="identifier">it2</span><span class="special">.</span><span class="identifier">current_</span> <span class="special">&&</span> 587 <span class="identifier">it1</span><span class="special">.</span><span class="identifier">container_</span> <span class="special">==</span> <span class="identifier">it2</span><span class="special">.</span><span class="identifier">container_</span><span class="special">;</span> 588 <span class="special">}</span> 589 <span class="special">};</span> 590<span class="special">}}}</span> 591</pre> 592<p> 593 </p> 594<p> 595 The last code snippet shows an example using an instance of the data 596 structure <code class="computeroutput"><span class="identifier">client</span><span class="special">::</span><span class="identifier">use_as_container</span></code> to generate output 597 from a <a class="link" href="../../../karma/reference/operator/list.html" title="List Generator (a % b)">List (<code class="computeroutput"><span class="special">%</span></code>)</a> generator: 598 </p> 599<p> 600</p> 601<pre class="programlisting"><span class="identifier">client</span><span class="special">::</span><span class="identifier">use_as_container</span> <span class="identifier">d2</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> 602<span class="comment">// use the instance of a 'client::use_as_container' instead of a STL vector</span> 603<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">karma</span><span class="special">::</span><span class="identifier">format</span><span class="special">(</span><span class="identifier">karma</span><span class="special">::</span><span class="identifier">int_</span> <span class="special">%</span> <span class="string">", "</span><span class="special">,</span> <span class="identifier">d2</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> <span class="comment">// prints: '1, 2, 3'</span> 604</pre> 605<p> 606 </p> 607<p> 608 As you can see, the specializations for the customization points as defined 609 above enable the seamless integration of the custom data structure without 610 having to modify the output format or the generator itself. 611 </p> 612</div> 613<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 614<td align="left"></td> 615<td align="right"><div class="copyright-footer">Copyright © 2001-2011 Joel de Guzman, Hartmut Kaiser<p> 616 Distributed under the Boost Software License, Version 1.0. (See accompanying 617 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>) 618 </p> 619</div></td> 620</tr></table> 621<hr> 622<div class="spirit-nav"> 623<a accesskey="p" href="end_container.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../iterate.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="deref_iterator.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a> 624</div> 625</body> 626</html> 627
