libs/spirit/doc/html/spirit/advanced/customize/iterate/next_iterator.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   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.78.1">
   7 <link rel="home" href="../../../../index.html" title="Spirit 2.5.2">
   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">&lt;</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">&gt;</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">&lt;</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">&gt;</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">&amp;</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">&lt;</span><span class="identifier">Iterator</span><span class="special">&gt;::</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">&lt;</span><span class="identifier">C</span><span class="special">&gt;::</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">&lt;</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">&gt;</span>
 428 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
 429 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">string</span><span class="special">&gt;</span>
 430 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">vector</span><span class="special">&gt;</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&lt;&gt;' 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">&lt;&gt;</span>
 504     <span class="keyword">struct</span> <span class="identifier">is_container</span><span class="special">&lt;</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">&gt;</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&lt;&gt;' 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&lt;int&gt;'.</span>
 512     <span class="keyword">template</span> <span class="special">&lt;&gt;</span>
 513     <span class="keyword">struct</span> <span class="identifier">container_iterator</span><span class="special">&lt;</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">&gt;</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&lt;&gt;' and </span>
 519     <span class="comment">// 'end_container&lt;&gt;' 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">&lt;&gt;</span>
 525     <span class="keyword">struct</span> <span class="identifier">begin_container</span><span class="special">&lt;</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">&gt;</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">&amp;</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">(&amp;</span><span class="identifier">c</span><span class="special">,</span> <span class="special">&amp;</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">&lt;&gt;</span>
 535     <span class="keyword">struct</span> <span class="identifier">end_container</span><span class="special">&lt;</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">&gt;</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">&amp;</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">(&amp;</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&lt;&gt;' 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">&lt;&gt;</span>
 556     <span class="keyword">struct</span> <span class="identifier">deref_iterator</span><span class="special">&lt;</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">&gt;</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">&amp;</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">&lt;&gt;</span>
 567     <span class="keyword">struct</span> <span class="identifier">next_iterator</span><span class="special">&lt;</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">&gt;</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">&amp;</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">&amp;</span><span class="identifier">it</span><span class="special">.</span><span class="identifier">container_</span><span class="special">-&gt;</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">&amp;</span><span class="identifier">it</span><span class="special">.</span><span class="identifier">container_</span><span class="special">-&gt;</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">&amp;</span><span class="identifier">it</span><span class="special">.</span><span class="identifier">container_</span><span class="special">-&gt;</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">&amp;</span><span class="identifier">it</span><span class="special">.</span><span class="identifier">container_</span><span class="special">-&gt;</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">&lt;&gt;</span>
 581     <span class="keyword">struct</span> <span class="identifier">compare_iterators</span><span class="special">&lt;</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">&gt;</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">&amp;</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">&amp;</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">&amp;&amp;</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">&lt;&lt;</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">&lt;&lt;</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 &#169; 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>