51e76ebff63fef9ec13881274df4558cf7df9ab3
[platform/upstream/boost.git] / libs / spirit / doc / html / spirit / advanced / customize / iterate / end_container.html
1 <html>
2 <head>
3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
4 <title>Get the Iterator pointing to the End of 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="begin_container.html" title="Get the Iterator pointing to the Begin of a Container Attribute">
10 <link rel="next" href="next_iterator.html" title="Increment 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="begin_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="next_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.end_container"></a><a class="link" href="end_container.html" title="Get the Iterator pointing to the End of a Container Attribute">Get
28           the Iterator pointing to the End of a Container Attribute</a>
29 </h5></div></div></div>
30 <h6>
31 <a name="spirit.advanced.customize.iterate.end_container.h0"></a>
32             <span class="phrase"><a name="spirit.advanced.customize.iterate.end_container.end_container"></a></span><a class="link" href="end_container.html#spirit.advanced.customize.iterate.end_container.end_container">end_container</a>
33           </h6>
34 <p>
35             The template <code class="computeroutput"><span class="identifier">end_container</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 end of the container holding
41             the attributes to generate output from.
42           </p>
43 <h6>
44 <a name="spirit.advanced.customize.iterate.end_container.h1"></a>
45             <span class="phrase"><a name="spirit.advanced.customize.iterate.end_container.module_headers"></a></span><a class="link" href="end_container.html#spirit.advanced.customize.iterate.end_container.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.end_container.h2"></a>
66             <span class="phrase"><a name="spirit.advanced.customize.iterate.end_container.namespace"></a></span><a class="link" href="end_container.html#spirit.advanced.customize.iterate.end_container.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.end_container.h3"></a>
83             <span class="phrase"><a name="spirit.advanced.customize.iterate.end_container.synopsis"></a></span><a class="link" href="end_container.html#spirit.advanced.customize.iterate.end_container.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">Container</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">end_container</span>
87 <span class="special">{</span>
88     <span class="keyword">static</span> <span class="keyword">typename</span> <span class="identifier">container_iterator</span><span class="special">&lt;</span><span class="identifier">Container</span><span class="special">&gt;::</span><span class="identifier">type</span>
89     <span class="identifier">call</span><span class="special">(</span><span class="identifier">Container</span><span class="special">&amp;</span> <span class="identifier">c</span><span class="special">);</span>
90 <span class="special">};</span>
91 </pre>
92 <h6>
93 <a name="spirit.advanced.customize.iterate.end_container.h4"></a>
94             <span class="phrase"><a name="spirit.advanced.customize.iterate.end_container.template_parameters"></a></span><a class="link" href="end_container.html#spirit.advanced.customize.iterate.end_container.template_parameters">Template
95             parameters</a>
96           </h6>
97 <div class="informaltable"><table class="table">
98 <colgroup>
99 <col>
100 <col>
101 <col>
102 </colgroup>
103 <thead><tr>
104 <th>
105                     <p>
106                       Parameter
107                     </p>
108                   </th>
109 <th>
110                     <p>
111                       Description
112                     </p>
113                   </th>
114 <th>
115                     <p>
116                       Default
117                     </p>
118                   </th>
119 </tr></thead>
120 <tbody>
121 <tr>
122 <td>
123                     <p>
124                       <code class="computeroutput"><span class="identifier">Container</span></code>
125                     </p>
126                   </td>
127 <td>
128                     <p>
129                       The type, <code class="computeroutput"><span class="identifier">Container</span></code>
130                       for which the iterator pointing to the first element has to
131                       be returned
132                     </p>
133                   </td>
134 <td>
135                     <p>
136                       none
137                     </p>
138                   </td>
139 </tr>
140 <tr>
141 <td>
142                     <p>
143                       <code class="computeroutput"><span class="identifier">Enable</span></code>
144                     </p>
145                   </td>
146 <td>
147                     <p>
148                       Helper template parameter usable to selectively enable or disable
149                       certain specializations of <code class="computeroutput"><span class="identifier">end_container</span></code>
150                       utilizing SFINAE (i.e. <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">enable_if</span></code>
151                       or <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">disable_if</span></code>).
152                     </p>
153                   </td>
154 <td>
155                     <p>
156                       <code class="computeroutput"><span class="keyword">void</span></code>
157                     </p>
158                   </td>
159 </tr>
160 </tbody>
161 </table></div>
162 <div class="variablelist">
163 <p class="title"><b>Notation</b></p>
164 <dl class="variablelist">
165 <dt><span class="term"><code class="computeroutput"><span class="identifier">C</span></code></span></dt>
166 <dd><p>
167                   A container type the end iterator needs to be returned for.
168                 </p></dd>
169 <dt><span class="term"><code class="computeroutput"><span class="identifier">c</span></code></span></dt>
170 <dd><p>
171                   An instance of a container, <code class="computeroutput"><span class="identifier">C</span></code>.
172                 </p></dd>
173 </dl>
174 </div>
175 <h6>
176 <a name="spirit.advanced.customize.iterate.end_container.h5"></a>
177             <span class="phrase"><a name="spirit.advanced.customize.iterate.end_container.expression_semantics"></a></span><a class="link" href="end_container.html#spirit.advanced.customize.iterate.end_container.expression_semantics">Expression
178             Semantics</a>
179           </h6>
180 <div class="informaltable"><table class="table">
181 <colgroup>
182 <col>
183 <col>
184 </colgroup>
185 <thead><tr>
186 <th>
187                     <p>
188                       Expression
189                     </p>
190                   </th>
191 <th>
192                     <p>
193                       Semantics
194                     </p>
195                   </th>
196 </tr></thead>
197 <tbody><tr>
198 <td>
199                     <p>
200                       <code class="computeroutput"><span class="identifier">end_container</span><span class="special">&lt;</span><span class="identifier">C</span><span class="special">&gt;::</span><span class="identifier">call</span><span class="special">(</span><span class="identifier">c</span><span class="special">)</span></code>
201                     </p>
202                   </td>
203 <td>
204                     <p>
205                       Return the iterator usable to compare a different iterator
206                       with in order to detect whether the other iterator reached
207                       the end of the given container, <code class="computeroutput"><span class="identifier">c</span></code>.
208                       The type of the returned iterator is expected to be the same
209                       as the type 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>.
210                     </p>
211                   </td>
212 </tr></tbody>
213 </table></div>
214 <h6>
215 <a name="spirit.advanced.customize.iterate.end_container.h6"></a>
216             <span class="phrase"><a name="spirit.advanced.customize.iterate.end_container.predefined_specializations"></a></span><a class="link" href="end_container.html#spirit.advanced.customize.iterate.end_container.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">C</span></code>
247                     </p>
248                   </td>
249 <td>
250                     <p>
251                       Returns <code class="computeroutput"><span class="identifier">c</span><span class="special">.</span><span class="identifier">end</span><span class="special">()</span></code>.
252                     </p>
253                   </td>
254 </tr>
255 <tr>
256 <td>
257                     <p>
258                       <code class="computeroutput"><span class="identifier">C</span> <span class="keyword">const</span></code>
259                     </p>
260                   </td>
261 <td>
262                     <p>
263                       Returns <code class="computeroutput"><span class="identifier">c</span><span class="special">.</span><span class="identifier">end</span><span class="special">()</span></code>.
264                     </p>
265                   </td>
266 </tr>
267 <tr>
268 <td>
269                     <p>
270                       <code class="computeroutput"><span class="identifier">unused_type</span></code>
271                     </p>
272                   </td>
273 <td>
274                     <p>
275                       Returns <code class="computeroutput"><span class="special">&amp;</span><span class="identifier">unused</span></code>.
276                     </p>
277                   </td>
278 </tr>
279 </tbody>
280 </table></div>
281 <h6>
282 <a name="spirit.advanced.customize.iterate.end_container.h7"></a>
283             <span class="phrase"><a name="spirit.advanced.customize.iterate.end_container.when_to_implement"></a></span><a class="link" href="end_container.html#spirit.advanced.customize.iterate.end_container.when_to_implement">When
284             to implement</a>
285           </h6>
286 <p>
287             The customization point <code class="computeroutput"><span class="identifier">end_container</span></code>
288             needs to be implemented for a specific type whenever this type is to
289             be used as an attribute in place of a STL container. It is applicable
290             for generators (<span class="emphasis"><em>Spirit.Karma</em></span>) only. As a rule of
291             thumb: it has to be implemented whenever a certain type is to be passed
292             as an attribute to a generator normally exposing a STL container, <code class="computeroutput"><span class="identifier">C</span></code> and if the type does not expose the
293             interface of a STL container (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>
294             would normally return <code class="computeroutput"><span class="identifier">mpl</span><span class="special">::</span><span class="identifier">false_</span></code>).
295           </p>
296 <h6>
297 <a name="spirit.advanced.customize.iterate.end_container.h8"></a>
298             <span class="phrase"><a name="spirit.advanced.customize.iterate.end_container.related_attribute_customization_points"></a></span><a class="link" href="end_container.html#spirit.advanced.customize.iterate.end_container.related_attribute_customization_points">Related
299             Attribute Customization Points</a>
300           </h6>
301 <p>
302             If this customization point is implemented, the following other customization
303             points might need to be implemented as well.
304           </p>
305 <div class="informaltable"><table class="table">
306 <colgroup>
307 <col>
308 <col>
309 </colgroup>
310 <thead><tr>
311 <th>
312                     <p>
313                       Name
314                     </p>
315                   </th>
316 <th>
317                     <p>
318                       When to implement
319                     </p>
320                   </th>
321 </tr></thead>
322 <tbody>
323 <tr>
324 <td>
325                     <p>
326                       <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>
327                     </p>
328                   </td>
329 <td>
330                     <p>
331                       Needs to be implemented whenever a type is to be used as a
332                       container attribute in <span class="emphasis"><em>Karma</em></span>.
333                     </p>
334                   </td>
335 </tr>
336 <tr>
337 <td>
338                     <p>
339                       <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>
340                     </p>
341                   </td>
342 <td>
343                     <p>
344                       Karma: <a class="link" href="../../../karma/reference/operator/list.html" title="List Generator (a % b)">List
345                       (<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
346                       <code class="computeroutput"><span class="special">*</span></code>)</a>, <a class="link" href="../../../karma/reference/operator/plus.html" title="Plus Generator (+a)">Plus (unary
347                       <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>.
348                     </p>
349                   </td>
350 </tr>
351 <tr>
352 <td>
353                     <p>
354                       <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>
355                     </p>
356                   </td>
357 <td>
358                     <p>
359                       Karma: <a class="link" href="../../../karma/reference/operator/list.html" title="List Generator (a % b)">List
360                       (<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
361                       <code class="computeroutput"><span class="special">*</span></code>)</a>, <a class="link" href="../../../karma/reference/operator/plus.html" title="Plus Generator (+a)">Plus (unary
362                       <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>.
363                     </p>
364                   </td>
365 </tr>
366 <tr>
367 <td>
368                     <p>
369                       <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>
370                     </p>
371                   </td>
372 <td>
373                     <p>
374                       Karma: <a class="link" href="../../../karma/reference/operator/list.html" title="List Generator (a % b)">List
375                       (<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
376                       <code class="computeroutput"><span class="special">*</span></code>)</a>, <a class="link" href="../../../karma/reference/operator/plus.html" title="Plus Generator (+a)">Plus (unary
377                       <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>.
378                     </p>
379                   </td>
380 </tr>
381 <tr>
382 <td>
383                     <p>
384                       <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>
385                     </p>
386                   </td>
387 <td>
388                     <p>
389                       Karma: <a class="link" href="../../../karma/reference/operator/list.html" title="List Generator (a % b)">List
390                       (<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
391                       <code class="computeroutput"><span class="special">*</span></code>)</a>, <a class="link" href="../../../karma/reference/operator/plus.html" title="Plus Generator (+a)">Plus (unary
392                       <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>.
393                     </p>
394                   </td>
395 </tr>
396 <tr>
397 <td>
398                     <p>
399                       <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>
400                     </p>
401                   </td>
402 <td>
403                     <p>
404                       Karma: <a class="link" href="../../../karma/reference/operator/list.html" title="List Generator (a % b)">List
405                       (<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
406                       <code class="computeroutput"><span class="special">*</span></code>)</a>, <a class="link" href="../../../karma/reference/operator/plus.html" title="Plus Generator (+a)">Plus (unary
407                       <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>.
408                     </p>
409                   </td>
410 </tr>
411 <tr>
412 <td>
413                     <p>
414                       <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>
415                     </p>
416                   </td>
417 <td>
418                     <p>
419                       Karma: <a class="link" href="../../../karma/reference/operator/list.html" title="List Generator (a % b)">List
420                       (<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
421                       <code class="computeroutput"><span class="special">*</span></code>)</a>, <a class="link" href="../../../karma/reference/operator/plus.html" title="Plus Generator (+a)">Plus (unary
422                       <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>.
423                     </p>
424                   </td>
425 </tr>
426 </tbody>
427 </table></div>
428 <h6>
429 <a name="spirit.advanced.customize.iterate.end_container.h9"></a>
430             <span class="phrase"><a name="spirit.advanced.customize.iterate.end_container.example"></a></span><a class="link" href="end_container.html#spirit.advanced.customize.iterate.end_container.example">Example</a>
431           </h6>
432 <p>
433             For examples of how to use the customization point <code class="computeroutput"><span class="identifier">end_container</span></code>
434             please see here: <a class="link" href="container_iterator.html#spirit.advanced.customize.iterate.container_iterator.example">embedded_container_example</a>,
435             <a class="link" href="next_iterator.html#spirit.advanced.customize.iterate.next_iterator.example">use_as_container</a>,
436             and <a class="link" href="deref_iterator.html#spirit.advanced.customize.iterate.deref_iterator.example">counter_example</a>.
437           </p>
438 </div>
439 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
440 <td align="left"></td>
441 <td align="right"><div class="copyright-footer">Copyright &#169; 2001-2011 Joel de Guzman, Hartmut Kaiser<p>
442         Distributed under the Boost Software License, Version 1.0. (See accompanying
443         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>)
444       </p>
445 </div></td>
446 </tr></table>
447 <hr>
448 <div class="spirit-nav">
449 <a accesskey="p" href="begin_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="next_iterator.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a>
450 </div>
451 </body>
452 </html>