Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/libs/range/doc/boost_range.html @ 30

Last change on this file since 30 was 29, checked in by landauf, 17 years ago

updated boost from 1_33_1 to 1_34_1
File size: 41.0 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2<html>
3        <head>
4                <title>Boost.Range Reference </title>
5                <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
6                <link rel="stylesheet" href="style.css" type="text/css">
7        </head>
8        <body>
9                <table>
10                        <tr>
11                                <td><img src="../../../boost.png" width="100%" border="0"></td>
12                                <td><h1><br>
13                                                Boost.Range
14                                        </h1>
15                                </td>
16                        </tr>
17                </table>
18                <h2>Synopsis and Reference
19                </h2>
20                <ul>
21                        <li>
22                                <a href="#overview">Overview</a>
23                        <li>
24                                <a href="#Synopsis">Synopsis</a>
25                        <li>
26                                <a href="#Semantics">Semantics</a>
27                        <li>
28                                <a href="#minimal_interface">Extending the library</a></li>
29                </ul>
30                <hr size="1">
31                <a name="overview"></a>
32                <h3>Overview</h3>
33                <p>
34                        Four types of objects are currently supported by the library:
35                        <ul>
36                                <li>
37                                standard-like containers
38                                <li>
39                                        <code>std::pair&lt;iterator,iterator&gt;</code>
40                                <li>
41                                        null terminated strings (this includes <code>char[]</code>,<code>wchar_t[]</code>,
42                                        <code>char*</code>, and <code>wchar_t*</code>)
43                                        <p>
44                                                <b>Warning:</b><i> support for null-terminated strings is deprecated and will
45                                                        disappear in the next Boost release (1.34). </i>
46                                        </p>
47                                <li>
48                                        built-in arrays
49                                </li>
50                        </ul>
51                        Even though the behavior of the primary templates are exactly such that
52                        standard containers will be supported by default, the requirements are much
53                        lower than the standard container requirements. For example, the utility class <a href="utility_class.html#iter_range">
54                                <code>iterator_range</code></a> implements the <a href="#minimal_interface">minimal
55                                interface</a> required to make the class a <a href="range.html#forward_range">Forward
56                                Range</a>
57                .
58                <P></P>
59                <p>
60                        Please also see <a href="range.html">Range concepts</a> for more details.
61                </p>
62                <a name="Synopsis"></a>
63                <h3>Synopsis</h3>
64                <p>
65                        <pre>
66<span class=keyword>namespace </span><span class=identifier>boost</span>
67<span class=special>{
68    </span><span class=comment>//
69    // Single Pass Range metafunctions
70    //
71   
72    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>&gt;
73    </span><span class=keyword>struct </span><a href="#range_value"><span 
74class=identifier>range_value</span></a><span class=special>;
75                 
76    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>&gt;
77    </span><span class=keyword>struct </span><a href="#range_iterator"><span 
78class=identifier>range_iterator</span></a><span class=special>;
79   
80    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>&gt;
81    </span><span class=keyword>struct </span><a href="#range_const_iterator"><span 
82class=identifier>range_const_iterator</span></a><span class=special>;
83   
84    </span><span class=comment>//
85    // Forward Range metafunctions
86    //
87   
88    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>&gt;
89    </span><span class=keyword>struct </span><a href="#range_difference"><span 
90class=identifier>range_difference</span></a><span class=special>;
91   
92    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>&gt;
93    </span><span class=keyword>struct </span><a href="#range_size"><span 
94class=identifier>range_size</span></a><span class=special>;
95   
96    </span><span class=comment>//
97    // Bidirectional Range metafunctions
98    //
99   
100    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>&gt;
101    </span><span class=keyword>struct </span><a 
102href="#range_reverse_iterator"><span
103class=identifier>range_reverse_iterator</span></a><span class=special>;
104
105    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>&gt;
106    </span><span class=keyword>struct </span><a 
107href="#range_const_reverse_iterator"><span
108class=identifier>range_const_reverse_iterator</span></a><span class=special>;
109   
110    </span><span class=comment>//
111    // Special metafunctions
112    //
113   
114    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>&gt;
115    </span><span class=keyword>struct </span><a href="#range_result_iterator"><span 
116class=identifier>range_result_iterator</span></a><span class=special>;
117                 
118    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>&gt;
119    </span><span class=keyword>struct </span><a 
120href="#range_reverse_result_iterator"><span
121class=identifier>range_reverse_result_iterator</span></a><span class=special>;
122
123    </span><span class=comment>//
124    // Single Pass Range functions
125    //
126   
127    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>&gt;
128    </span><span class=keyword></span><span class=keyword>typename </span><span class=identifier>range_iterator</span><span class=special>&lt;</span><span class=identifier>T</span><span class=special>&gt;::</span><span class=identifier>type
129    </span><a href="#begin"><span class=identifier>begin</span></a><span class=special>( </span><span class=identifier>T</span><span class=special>&amp; </span><span class=identifier>c </span><span class=special>);
130   
131    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>&gt;
132    </span><span class=keyword></span><span class=keyword>typename </span><span class=identifier>range_const_iterator</span><span class=special>&lt;</span><span class=identifier>T</span><span class=special>&gt;::</span><span class=identifier>type
133    </span><a href="#begin"><span class=identifier>begin</span></a><span class=special>( </span><span class=keyword>const </span><span class=identifier>T</span><span class=special>&amp; </span><span class=identifier>c </span><span class=special>);
134       
135    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>&gt;
136    </span><span class=keyword></span><span class=keyword>typename </span><span class=identifier>range_iterator</span><span class=special>&lt;</span><span class=identifier>T</span><span class=special>&gt;::</span><span class=identifier>type
137    </span><a href="#end"><span class=identifier>end</span></a><span class=special>( </span><span class=identifier>T</span><span class=special>&amp; </span><span class=identifier>c </span><span class=special>);
138                     
139    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>&gt;
140    </span><span class=keyword></span><span class=keyword>typename </span><span class=identifier>range_const_iterator</span><span class=special>&lt;</span><span class=identifier>T</span><span class=special>&gt;::</span><span class=identifier>type
141    </span><a href="#end"><span class=identifier>end</span></a><span class=special>( </span><span class=keyword>const </span><span class=identifier>T</span><span class=special>&amp; </span><span class=identifier>c </span><span class=special>);
142   
143    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>&gt;
144    </span><span class=keyword></span><span class=keyword>bool
145    </span><a href="#empty"><span class=identifier>empty</span></a><span class=special>( </span><span class=keyword>const </span><span class=identifier>T</span><span class=special>&amp; </span><span class=identifier>c </span><span class=special>);
146               
147    </span><span class=comment>//
148    // Forward Range functions
149    //
150   
151    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>&gt;
152    </span><span class=keyword></span><span class=keyword>typename </span><span class=identifier>range_size</span><span class=special>&lt;</span><span class=identifier>T</span><span class=special>&gt;::</span><span class=identifier>type
153    </span><a href="#size"><span class=identifier>size</span></a><span class=special>( </span><span class=keyword>const </span><span class=identifier>T</span><span class=special>&amp; </span><span class=identifier>c </span><span class=special>);
154                           
155    </span><span class=comment>//
156    // Bidirectional Range functions
157    //
158                     
159    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>&gt;
160    </span><span class=keyword></span><span class=keyword>typename </span><span class=identifier>range_reverse_iterator</span><span class=special>&lt;</span><span class=identifier>T</span><span class=special>&gt;::</span><span class=identifier>type
161    </span><a href="#rbegin"><span class=identifier>rbegin</span></a><span class=special>( </span><span class=identifier>T</span><span class=special>&amp; </span><span class=identifier>c </span><span class=special>);
162   
163    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>&gt;
164    </span><span class=keyword></span><span class=keyword>typename </span><span class=identifier>range_const_reverse_iterator</span><span class=special>&lt;</span><span class=identifier>T</span><span class=special>&gt;::</span><span class=identifier>type
165    </span><a href="#rbegin"><span class=identifier>rbegin</span></a><span class=special>( </span><span class=keyword>const </span><span class=identifier>T</span><span class=special>&amp; </span><span class=identifier>c </span><span class=special>);
166       
167    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>&gt;
168    </span><span class=keyword></span><span class=keyword>typename </span><span class=identifier>range_reverse_iterator</span><span class=special>&lt;</span><span class=identifier>T</span><span class=special>&gt;::</span><span class=identifier>type
169    </span><a href="#rend"><span class=identifier>rend</span></a><span class=special>( </span><span class=identifier>T</span><span class=special>&amp; </span><span class=identifier>c </span><span class=special>);
170                     
171    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>&gt;
172    </span><span class=keyword></span><span class=keyword>typename </span><span class=identifier>range_const_reverse_iterator</span><span class=special>&lt;</span><span class=identifier>T</span><span class=special>&gt;::</span><span class=identifier>type
173    </span><a href="#rend"><span class=identifier>rend</span></a><span class=special>( </span><span class=keyword>const </span><span 
174class=identifier>T</span><span class=special>&amp; </span><span class=identifier>c </span><span class=special>);
175    </span>
176    <span class=comment>//
177    // Special const Range functions
178    //
179    </span>
180    <span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>&gt;</span>
181    <span class=keyword>typename </span><span class=identifier>range_const_iterator</span><span class=special>&lt;</span><span class=identifier>T</span><span class=special>&gt;::</span><span class=identifier>type </span>
182    <a href="#const_begin"><span class=identifier>const_begin</span></a><span class=special>(</span><span class=keyword> const </span><span class=identifier>T</span><span class=special>&amp; </span><span class=identifier>r </span><span class=special>);
183    </span>
184    <span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>&gt;</span>
185    <span class=keyword>typename </span><span class=identifier>range_const_iterator</span><span class=special>&lt;</span><span class=identifier>T</span><span class=special>&gt;::</span><span class=identifier>type </span>
186    <a href="#const_end"><span class=identifier>const_end</span></a><span class=special>(</span><span class=keyword> const </span><span class=identifier>T</span><span class=special>&amp; </span><span class=identifier>r </span><span class=special>);
187    </span>
188    <span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>&gt;</span>
189    <span class=keyword>typename </span><span class=identifier>range_const_reverse_iterator</span><span class=special>&lt;</span><span class=identifier>T</span><span class=special>&gt;::</span><span class=identifier>type </span>
190    <a href="#const_rbegin"><span class=identifier>const_rbegin</span></a><span class=special>(</span><span class=keyword> const </span><span class=identifier>T</span><span class=special>&amp; </span><span class=identifier>r </span><span class=special>);
191    </span>
192    <span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>&gt;</span>
193    <span class=keyword>typename </span><span class=identifier>range_const_reverse_iterator</span><span class=special>&lt;</span><span class=identifier>T</span><span class=special>&gt;::</span><span class=identifier>type </span>
194    <a href="#const_rend"><span class=identifier>const_rend</span></a><span class=special>( </span><span class=keyword>const </span><span class=identifier>T</span><span class=special>&amp; </span><span class=identifier>r </span><span class=special>);</span>
195
196<span class=special>} </span><span class=comment>// namespace 'boost'
197</span>
198</pre>
199                <P></P>
200                <a name="Semantics"></a>
201                <h3>Semantics</h3>
202                <h4>notation</h4>
203                <p>
204                        <table cellpadding="5" border="1">
205                                <tr>
206                                        <th>
207                                                Type
208                                                <th>
209                                                        Object
210                                                        <th>
211                                        Describes
212                                </tr>
213                                <tr>
214                                        <td><code>X</code>
215                                        <td><code>x</code>
216                                        <td>any type</td>
217                                <tr>
218                                        <td><code>T</code>
219                                        </td>
220                                        <td><code>t</code>
221                                        <td>denotes behavior of the primary templates</td>
222                                </tr>
223                                <tr>
224                                        <td><code>P</code>
225                                        <td><code>p</code>
226                                        <td>denotes <code>std::pair&lt;iterator,iterator&gt;</code></td>
227                                <tr>
228                                        <td><code>A[sz]</code>
229                                        <td><code>a</code>
230                                        <td>denotes an array of type <code>A</code> of size <code>sz</code>
231                                <tr>
232                                <tr>
233                                        <td><code>Char*</code>
234                                        <td><code>s</code>
235                                        <td>denotes either <code>char*</code> or <code>wchar_t*</code></td>
236                                </tr>
237                        </table>
238                </p>
239                <p>
240                        Please notice in tables below that when four lines appear in a cell, the first
241                        line will describe the primary template, the second line pairs of iterators,
242                        the third line arrays and the last line null-terminated strings.
243                </p>
244                <h4>Metafunctions</h4>
245                <p>
246                        <table border="1" cellpadding="5">
247                                <tr>
248                                        <th>
249                                                Expression</th>
250                                        <th>
251                                                Return type</th>
252                                        <th>
253                                                Complexity</th>
254                                </tr>
255                                <tr>
256                                        <a name="range_value"></a>
257                                        <td><code>range_value&lt;X&gt;::type</code></td>
258                                        <td><code>T::value_type</code><br>
259                                                <code>boost::iterator_value&lt;P::first_type&gt;::type</code> <!--if <code>P</code> is an instantiation of <code>std::pair</code>--><br>
260                                                <code>A</code><br>
261                                                <code>Char</code>
262                                        <td>compile time</td>
263                                </tr>
264                                <tr>
265                                        <a name="range_iterator"></a>
266                                        <td><code>range_iterator&lt;X&gt;::type</code></td>
267                                        <td><code>T::iterator</code><br>
268                                                <code>P::first_type</code><br>
269                                                <code>A*</code><br>
270                                                <code>Char*</code>
271                                        <td>compile time</td>
272                                </tr>
273                                <tr>
274                                        <a name="range_const_iterator"></a>
275                                        <td><code>range_const_iterator&lt;X&gt;::type</code></td>
276                                        <td><code>T::const_iterator</code><br>
277                                                <code>P::first_type</code><br>
278                                                <code>const A*</code><br>
279                                                <code>const Char*</code>
280                                        <td>compile time</td>
281                                </tr>
282                                <tr>
283                                        <a name="range_difference"></a>
284                                        <td><code>range_difference&lt;X&gt;::type</code></td>
285                                        <td><code>T::difference_type</code><br>
286                                                <code>boost::iterator_difference&lt;P::first_type&gt;::type</code><br>
287                                                <code>std::ptrdiff_t</code><br>
288                                                <code>std::ptrdiff_t</code><br>
289                                        <td>compile time</td>
290                                </tr>
291                                <tr>
292                                        <a name="range_size"></a>
293                                        <td><code>range_size&lt;X&gt;::type</code></td>
294                                        <td><code>T::size_type</code><br>
295                                                <code>std::size_t</code><br>
296                                                <code>std::size_t</code><br>
297                                                <code>std::size_t</code><br>
298                                        <td>compile time</td>
299                                </tr>
300                                <tr>
301                                        <a name="range_result_iterator"></a>
302                                        <td><code>range_result_iterator&lt;X&gt;::type</code></td>
303                                        <td><code>range_const_iterator&lt;X&gt;::type</code> if <code>X</code> is <code>const</code>
304                                                <br>
305                                                <code>range_iterator&lt;X&gt;::type</code> otherwise
306                                        </td>
307                                        <td>compile time</td>
308                                </tr>
309                                <tr>
310                                        <a name="range_reverse_iterator"></a>
311                                        <td><code>range_reverse_iterator&lt;X&gt;::type</code></td>
312                                        <td><code>boost::reverse_iterator&lt; typename range_iterator&lt;T&gt;::type &gt;</code><br>
313                                        <td>compile time</td>
314                                </tr>
315                                <tr>
316                                        <a name="range_const_reverse_iterator"></a>
317                                        <td><code>range_const_reverse_iterator&lt;X&gt;::type</code></td>
318                                        <td><code>boost::reverse_iterator&lt; typename range_const_iterator&lt;T&gt;::type &gt;</code>
319                                                <br>
320                                        <td>compile time</td>
321                                </tr>
322                                <tr>
323                                        <a name="range_reverse_result_iterator"></a>
324                                        <td><code>range_reverse_result_iterator&lt;X&gt;::type</code></td>
325                                        <td><code>boost::reverse_iterator&lt; typename range_result_iterator&lt;T&gt;::type
326                                                        &gt;</code>
327                                        <td>compile time</td>
328                                </tr>
329                        </table>
330                </p>
331                <p>
332                        The special metafunctions <code>range_result_iterator</code> and <code>range_reverse_result_iterator</code>
333                        are not part of any Range concept, but they are very useful when implementing
334                        certain Range classes like <a href="utility_class.html#sub_range"><code>sub_range</code></a>
335                        because of their ability to select iterators based on constness.
336                </p>
337                <h4>Functions</h4>
338                <p>
339                        <table border="1" cellpadding="5">
340                                <tr>
341                                        <th>
342                                                Expression</th>
343                                        <th>
344                                                Return type</th>
345                                        <th>
346                                                Returns</th>
347                                        <th>
348                                                Complexity</th>
349                                </tr>
350                                <tr>
351                                        <a name="begin"></a>
352                                        <td><code>begin(x)</code></td>
353                                        <td><code>range_result_iterator&lt;X&gt;::type</code></td>
354                                        <td>
355                                                <code>p.first</code> if <code>p</code> is of type <code>std::pair&ltT&gt;<code><br>
356                                                <code>a</code> if <code>a</code> is an array <br>
357                                                <code>s</code> if <code>s</code> is a string literal<br>
358                                                <code>boost_range_begin(x)</code> if that expression would invoke a function found by ADL <br>
359                                                <code>t.begin()</code> otherwise
360   
361                                        <td>constant time</td>
362                                </tr>
363                                <tr>
364                                        <a name="end"></a>
365                                        <td><code>end(x)</code></td>
366                                        <td><code>range_result_iterator&lt;X&gt;::type</code></td>
367                                        <td>
368                                                <code>p.second</code> if <code>p</code> is of type <code>std::pair&ltT&gt;<code><br>
369                                                <code>a + sz</code> if <code>a</code> is an array of size <code>sz</code><br>
370                                                <code>s + std::char_traits&lt;X&gt;::length( s )</code> if <code>s</code> is a <code>Char*</code>
371                                                <br>
372                                                <code>s + sz - 1</code> if <code>s</code> is a string literal of size <code>sz</code>
373                                                <br>
374                                            <code>boost_range_end(x)</code> if that expression would invoke a function found by ADL <br>
375                                                <code>t.end()</code> otherwise
376                                               
377                                        <td>linear if <code>X</code> is <code>Char*</code>
378                                                <br>
379                                                constant time otherwise</td>
380                                </tr>
381                                <tr>
382                                        <a name="empty"></a>
383                                        <td><code>empty(x)</code></td>
384                                        <td><code>bool</code></td>
385                                        <td><code>begin(x) == end( x )</code><br>
386                                        <td>linear if <code>X</code> is <code>Char*</code>
387                                                <br>
388                                                constant time otherwise<br>
389                                        </td>
390                                </tr>
391                                <tr>
392                                        <a name="size"></a>
393                                        <td><code>size(x)</code></td>
394                                        <td><code>range_size&lt;X&gt;::type</code></td>
395                                        <td>
396                                                <code>std::distance(p.first,p.second)</code> if <code>p</code> is of type <code>std::pair&ltT&gt;<code><br>
397                                                <code>sz</code> if <code>a</code> is an array of size <code>sz</code><br>
398                                                <code>end(s) - s</code> if <code>s</code> is a string literal or a <code>Char*</code><br>
399                                                <code>boost_range_size(x)</code> if that expression would invoke a function found by ADL <br>
400                                                <code>t.size()</code> otherwise
401                                        <td>linear if <code>X</code> is <code>Char*</code>
402                                                <br>
403                                                or if <code>std::distance()</code> is linear
404                                                <br>
405                                                constant time otherwise</td>
406                                </tr>
407                                <tr>
408                                        <a name="rbegin"></a>
409                                        <td><code>rbegin(x)</code></td>
410                                        <td><code>range_reverse_result_iterator&lt;X&gt;::type</code></td>
411                                        <td><code>range_reverse_result_iterator&lt;X&gt;::type( end(x) )</code>
412                                                <br>
413                                        <td>same as <code>end(x)</code>
414                                        </td>
415                                </tr>
416                                <tr>
417                                        <a name="rend"></a>
418                                        <td><code>rend(x)</code></td>
419                                        <td><code>range_reverse_result_iterator&lt;X&gt;::type</code></td>
420                                        <td><code>range_reverse_result_iterator&lt;X&gt;::type( begin(x) )</code>
421                                        <td>same as <code>begin(x)</code></td>
422                                </tr>
423                                <tr>
424                                        <a name="const_begin"></a>
425                                        <td><code>const_begin(x)</code></td>
426                                        <td><code>range_const_iterator&lt;X&gt;::type</code></td>
427                                        <td><code>range_const_iterator&lt;X&gt;::type( begin(x) )</code>
428                                                <br>
429                                        <td>same as <code>begin(x)</code>
430                                        </td>
431                                </tr>
432                                <tr>
433                                        <a name="const_end"></a>
434                                        <td><code>const_end(x)</code></td>
435                                        <td><code>range_const_iterator&lt;X&gt;::type</code></td>
436                                        <td><code>range_const_iterator&lt;X&gt;::type( end(x) )</code>
437                                        <td>same as <code>end(x)</code></td>
438                                </tr>
439                                <tr>
440                                        <a name="const_rbegin"></a>
441                                        <td><code>const_rbegin(x)</code></td>
442                                        <td><code>range_const_reverse_iterator&lt;X&gt;::type</code></td>
443                                        <td><code>range_const_reverse_iterator&lt;X&gt;::type( rbegin(x) )</code>
444                                                <br>
445                                        <td>same as <code>rbegin(x)</code>
446                                        </td>
447                                </tr>
448                                <tr>
449                                        <a name="const_rend"></a>
450                                        <td><code>const_rend(x)</code></td>
451                                        <td><code>range_const_reverse_iterator&lt;X&gt;::type</code></td>
452                                        <td><code>range_const_reverse_iterator&lt;X&gt;::type( rend(x) )</code>
453                                        <td>same as <code>rend(x)</code></td>
454                                </tr>
455                        </table>
456                </p>
457                <p>
458                        The special <code>const</code> functions are not part of any Range concept, but
459                        are very useful when you want to document clearly that your code is read-only.
460                </p>
461                <hr>
462                <a name="minimal_interface"></a>
463                <h3>Extending the library</h3>
464                <ul>
465                <li><a href="#method1">Method 1: provide member functions and nested types</a></li>
466        <li><a href="#method2">Method 2: provide free-standing functions and specialize metafunctions</a></li>
467                </ul>
468
469                <!--<b>Warning:</b><i> If possible, then prefer method 1 if you want to be absolutely sure your code is forward compatible.
470                                           </i>-->
471
472                <a name="method1"></a>
473                <h4>Method 1: provide member functions and nested types</h4>
474               
475                <p>
476                This procedure assumes that you have control over the types that should be made
477                conformant to a Range concept. If not, see <a href="#method2">method 2</a>.
478                </p>
479               
480                <p>
481                        The primary templates in this library are implemented such that standard
482                        containers will work automatically and so will <code>boost::<a href="../../array/index.html">array</a></code>.
483                        Below is given an overview of which member functions and member types a class
484                        must specify to be useable as a certain Range concept.
485                </p>
486                <p>
487                        <table cellpadding="5" border="1">
488                                <tr>
489                                        <th>
490                                                Member function</th>
491                                        <th>
492                                                Related concept</th>
493                                <tr>
494                                        <td><code>begin()</code></td>
495                                        <td><a href="range.html#single_pass_range">Single Pass Range</a></td>
496                                </tr>
497                                <tr>
498                                        <td><code>end()</code>
499                                        </td>
500                                        <td><a href="range.html#single_pass_range">Single Pass Range</a></td>
501                                </tr>
502                                <tr>
503                                        <td><code>size()</code></td>
504                                        <td><a href="range.html#forward_range">Forward Range</a></td>
505                                </tr>
506                        </table>
507                </p>
508                <p>
509                        Notice that <code>rbegin()</code> and <code>rend()</code> member functions are
510                        not needed even though the container can support bidirectional iteration.
511                </p>
512                <p>
513                        The required member types are:
514                </p>
515                <p>
516                        <table cellpadding="5" border="1">
517                                <tr>
518                                        <th>
519                                                Member type</th>
520                                        <th>
521                                                Related concept</th>
522                                <tr>
523                                <tr>
524                                        <td><code>iterator</code></td>
525                                        <td><a href="range.html#single_pass_range">Single Pass Range</a></td>
526                                </tr>
527                                <tr>
528                                        <td><code>const_iterator</code></td>
529                                        <td><a href="range.html#single_pass_range">Single Pass Range</a></td>
530                                </tr>
531                                <tr>
532                                        <td><code>size_type</code></td>
533                                        <td><a href="range.html#forward_range">Forward Range</a></td>
534                                </tr>
535                        </table>
536                </p>
537                <p>
538                        Again one should notice that member types <code>reverse_iterator</code> and <code>const_reverse_iterator</code>
539                        are not needed.
540                </p>
541                <a name="method2"></a>
542        <h4>Method 2: provide free-standing functions and specialize metafunctions</h4>
543
544                <p>
545                This procedure assumes that you cannot (or do not wish to) change the types that should be made
546                conformant to a Range concept. If this is not true, see <a href="#method1">method 1</a>.
547                </p>
548               
549                <p>
550                        The primary templates in this library are implemented such that
551                        certain functions are found via argument-dependent-lookup (ADL).
552                        Below is given an overview of which free-standing functions a class
553                        must specify to be useable as a certain Range concept.
554                        Let <code>x</code> be a variable (<code>const</code> or mutable)
555                        of the class in question.
556                </p>
557                <p>
558                        <table cellpadding="5" border="1" ID="Table1">
559                                <tr>
560                                        <th>
561                                                Function</th>
562                                        <th>
563                                                Related concept</th>
564                                <tr>
565                                        <td><code>boost_range_begin(x)</code></td>
566                                        <td><a href="range.html#single_pass_range">Single Pass Range</a></td>
567                                </tr>
568                                <tr>
569                                        <td><code>boost_range_end(x)</code>
570                                        </td>
571                                        <td><a href="range.html#single_pass_range">Single Pass Range</a></td>
572                                </tr>
573                                <tr>
574                                        <td><code>boost_range_size(x)</code></td>
575                                        <td><a href="range.html#forward_range">Forward Range</a></td>
576                                </tr>
577                        </table>               
578                </p>
579                <p><code>boost_range_begin()</code> and <code>boost_range_end()</code> must be
580                overloaded for both <code>const</code> and mutable reference arguments.
581                </p>
582               
583                <p>
584                You must also specialize 3 metafunctions for your type <code>X</code>:
585                </p>
586                <p>
587                        <table cellpadding="5" border="1" ID="Table2">
588                                <tr>
589                                        <th>
590                                                Metafunction</th>
591                                        <th>
592                                                Related concept</th>
593                                <tr>
594                                        <td><code>boost::range_iterator</code></td>
595                                        <td><a href="range.html#single_pass_range">Single Pass Range</a></td>
596                                </tr>
597                                <tr>
598                                        <td><code>boost::range_const_iterator</code></td>
599                                        <td><a href="range.html#single_pass_range">Single Pass Range</a></td>
600                                </tr>
601                                <tr>
602                                        <td><code>boost::range_size</code></td>
603                                        <td><a href="range.html#forward_range">Forward Range</a></td>
604                                </tr>
605                        </table>
606                </p>
607                <p>
608                A complete example is given here:
609                </p>
610                <blockquote>
611                <pre>
612<span class=preprocessor>#include</span> <span class=special>&lt;</span><span class=identifier>boost</span><span class=special>/</span><span class=identifier>range</span><span class=special>.</span><span class=identifier>hpp</span><span class=special>&gt;</span>
613<span class=preprocessor>#include</span> <span class=special>&lt;</span><span class=identifier>iterator</span><span class=special>&gt;</span>         <span class=comment>// for std::iterator_traits, std::distance()</span>
614
615<span class=keyword>namespace</span> <span class=identifier>Foo</span>
616<span class=special>{</span>
617        <span class=comment>//
618        // Our sample UDT. A 'Pair'
619        // will work as a range when the stored
620        // elements are iterators.
621        //</span>
622        <span class=keyword>template</span><span class=special>&lt;</span> <span class=keyword>class</span> <span class=identifier>T</span> <span class=special>&gt;</span>
623        <span class=keyword>struct</span> <span class=identifier>Pair</span>
624        <span class=special>{</span>
625                <span class=identifier>T</span> <span class=identifier>first</span><span class=special>,</span> <span class=identifier>last</span><span class=special>;</span> 
626        <span class=special>};</span>
627
628<span class=special>}</span> <span class=comment>// namespace 'Foo'</span>
629
630<span class=keyword>namespace</span> <span class=identifier>boost</span>
631<span class=special>{</span>
632        <span class=comment>//
633        // Specialize metafunctions. We must include the range.hpp header.
634        // We must open the 'boost' namespace.
635        //</span>
636
637        <span class=keyword>template</span><span class=special>&lt;</span> <span class=keyword>class</span> <span class=identifier>T</span> <span class=special>&gt;</span>
638        <span class=keyword>struct</span> <span class=identifier>range_iterator</span><span class=special>&lt;</span> <span class=identifier>Foo</span><span class=special>::</span><span class=identifier>Pair</span><span class=special>&lt;</span><span class=identifier>T</span><span class=special>&gt;</span> <span class=special>&gt;</span>
639        <span class=special>{</span>
640                <span class=keyword>typedef</span> <span class=identifier>T</span> <span class=identifier>type</span><span class=special>;</span>
641        <span class=special>};</span>
642
643        <span class=keyword>template</span><span class=special>&lt;</span> <span class=keyword>class</span> <span class=identifier>T</span> <span class=special>&gt;</span>
644        <span class=keyword>struct</span> <span class=identifier>range_const_iterator</span><span class=special>&lt;</span> <span class=identifier>Foo</span><span class=special>::</span><span class=identifier>Pair</span><span class=special>&lt;</span><span class=identifier>T</span><span class=special>&gt;</span> <span class=special>&gt;</span>
645        <span class=special>{</span>
646                <span class=comment>//
647                // Remark: this is defined similar to 'range_iterator'
648                //         because the 'Pair' type does not distinguish
649                //         between an iterator and a const_iterator.
650                //</span>
651                <span class=keyword>typedef</span> <span class=identifier>T</span> <span class=identifier>type</span><span class=special>;</span>
652        <span class=special>};</span>
653
654        <span class=keyword>template</span><span class=special>&lt;</span> <span class=keyword>class</span> <span class=identifier>T</span> <span class=special>&gt;</span>
655        <span class=keyword>struct</span> <span class=identifier>range_size</span><span class=special>&lt;</span> <span class=identifier>Foo</span><span class=special>::</span><span class=identifier>Pair</span><span class=special>&lt;</span><span class=identifier>T</span><span class=special>&gt;</span> <span class=special>&gt;</span>
656        <span class=special>{</span>
657
658                <span class=keyword>typedef</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>size_t</span> <span class=identifier>type</span><span class=special>;</span>
659        <span class=special>};</span>
660
661<span class=special>}</span> <span class=comment>// namespace 'boost'</span>
662
663<span class=keyword>namespace</span> <span class=identifier>Foo</span>
664<span class=special>{</span>
665        <span class=comment>//
666        // The required functions. These should be defined in
667        // the same namespace as 'Pair', in this case
668        // in namespace 'Foo'.
669        //</span>
670       
671        <span class=keyword>template</span><span class=special>&lt;</span> <span class=keyword>class</span> <span class=identifier>T</span> <span class=special>&gt;</span>
672        <span class=keyword>inline</span> <span class=identifier>T</span> <span class=identifier>boost_range_begin</span><span class=special>(</span> <span class=identifier>Pair</span><span class=special>&lt;</span><span class=identifier>T</span><span class=special>&gt;&amp;</span> <span class=identifier>x</span> <span class=special>)</span>
673        <span class=special>{</span> 
674                <span class=keyword>return</span> <span class=identifier>x</span><span class=special>.</span><span class=identifier>first</span><span class=special>;</span>
675        <span class=special>}</span>
676
677        <span class=keyword>template</span><span class=special>&lt;</span> <span class=keyword>class</span> <span class=identifier>T</span> <span class=special>&gt;</span>
678        <span class=keyword>inline</span> <span class=identifier>T</span> <span class=identifier>boost_range_begin</span><span class=special>(</span> <span class=keyword>const</span> <span class=identifier>Pair</span><span class=special>&lt;</span><span class=identifier>T</span><span class=special>&gt;&amp;</span> <span class=identifier>x</span> <span class=special>)</span>
679        <span class=special>{</span> 
680                <span class=keyword>return</span> <span class=identifier>x</span><span class=special>.</span><span class=identifier>first</span><span class=special>;</span>
681        <span class=special>}</span>
682
683        <span class=keyword>template</span><span class=special>&lt;</span> <span class=keyword>class</span> <span class=identifier>T</span> <span class=special>&gt;</span>
684        <span class=keyword>inline</span> <span class=identifier>T</span> <span class=identifier>boost_range_end</span><span class=special>(</span> <span class=identifier>Pair</span><span class=special>&lt;</span><span class=identifier>T</span><span class=special>&gt;&amp;</span> <span class=identifier>x</span> <span class=special>)</span>
685        <span class=special>{</span> 
686                <span class=keyword>return</span> <span class=identifier>x</span><span class=special>.</span><span class=identifier>last</span><span class=special>;</span>
687        <span class=special>}</span>
688
689        <span class=keyword>template</span><span class=special>&lt;</span> <span class=keyword>class</span> <span class=identifier>T</span> <span class=special>&gt;</span>
690        <span class=keyword>inline</span> <span class=identifier>T</span> <span class=identifier>boost_range_end</span><span class=special>(</span> <span class=keyword>const</span> <span class=identifier>Pair</span><span class=special>&lt;</span><span class=identifier>T</span><span class=special>&gt;&amp;</span> <span class=identifier>x</span> <span class=special>)</span>
691        <span class=special>{</span> 
692                <span class=keyword>return</span> <span class=identifier>x</span><span class=special>.</span><span class=identifier>last</span><span class=special>;</span>
693        <span class=special>}</span>
694
695        <span class=keyword>template</span><span class=special>&lt;</span> <span class=keyword>class</span> <span class=identifier>T</span> <span class=special>&gt;</span>
696        <span class=keyword>inline</span> <span class=keyword>typename</span> <span class=identifier>boost</span><span class=special>::</span><span class=identifier>range_size</span><span class=special>&lt;</span> <span class=identifier>Pair</span><span class=special>&lt;</span><span class=identifier>T</span><span class=special>&gt;</span> <span class=special>&gt;::</span><span class=identifier>type</span>
697        <span class=identifier>boost_range_size</span><span class=special>(</span> <span class=keyword>const</span> <span class=identifier>Pair</span><span class=special>&lt;</span><span class=identifier>T</span><span class=special>&gt;&amp;</span> <span class=identifier>x</span> <span class=special>)</span>
698        <span class=special>{</span>
699                <span class=keyword>return</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>distance</span><span class=special>(</span><span class=identifier>x</span><span class=special>.</span><span class=identifier>first</span><span class=special>,</span><span class=identifier>x</span><span class=special>.</span><span class=identifier>last</span><span class=special>);</span>
700        <span class=special>}</span>
701
702<span class=special>}</span> <span class=comment>// namespace 'Foo'</span>
703
704<span class=preprocessor>#include</span> <span class=special>&lt;</span><span class=identifier>vector</span><span class=special>&gt;</span>
705
706<span class=keyword>int</span> <span class=identifier>main</span><span class=special>()</span>
707<span class=special>{</span>
708        <span class=keyword>typedef</span> <span class=identifier>std</span><span class=special>::</span><span class=identifier>vector</span><span class=special>&lt;</span><span class=keyword>int</span><span class=special>&gt;::</span><span class=identifier>iterator</span>  <span class=identifier>iter</span><span class=special>;</span>
709        <span class=identifier>std</span><span class=special>::</span><span class=identifier>vector</span><span class=special>&lt;</span><span class=keyword>int</span><span class=special>&gt;</span>                    <span class=identifier>vec</span><span class=special>;</span>
710        <span class=identifier>Foo</span><span class=special>::</span><span class=identifier>Pair</span><span class=special>&lt;</span><span class=identifier>iter</span><span class=special>&gt;</span>                     <span class=identifier>pair</span> <span class=special>=</span> <span class=special>{</span> <span class=identifier>vec</span><span class=special>.</span><span class=identifier>begin</span><span class=special>(),</span> <span class=identifier>vec</span><span class=special>.</span><span class=identifier>end</span><span class=special>()</span> <span class=special>};</span>
711        <span class=keyword>const</span> <span class=identifier>Foo</span><span class=special>::</span><span class=identifier>Pair</span><span class=special>&lt;</span><span class=identifier>iter</span><span class=special>&gt;&amp;</span>              <span class=identifier>cpair</span> <span class=special>=</span> <span class=identifier>pair</span><span class=special>;</span> 
712        <span class=comment>//
713        // Notice that we call 'begin' etc with qualification.
714        //</span>
715        <span class=identifier>iter</span> <span class=identifier>i</span> <span class=special>=</span> <span class=identifier>boost</span><span class=special>::</span><span class=identifier>begin</span><span class=special>(</span> <span class=identifier>pair</span> <span class=special>);</span>
716        <span class=identifier>iter</span> <span class=identifier>e</span> <span class=special>=</span> <span class=identifier>boost</span><span class=special>::</span><span class=identifier>end</span><span class=special>(</span> <span class=identifier>pair</span> <span class=special>);</span>
717        <span class=identifier>i</span>      <span class=special>=</span> <span class=identifier>boost</span><span class=special>::</span><span class=identifier>begin</span><span class=special>(</span> <span class=identifier>cpair</span> <span class=special>);</span>
718        <span class=identifier>e</span>      <span class=special>=</span> <span class=identifier>boost</span><span class=special>::</span><span class=identifier>end</span><span class=special>(</span> <span class=identifier>cpair</span> <span class=special>);</span>
719        <span class=identifier>boost</span><span class=special>::</span><span class=identifier>range_size</span><span class=special>&lt;</span> <span class=identifier>Foo</span><span class=special>::</span><span class=identifier>Pair</span><span class=special>&lt;</span><span class=identifier>iter</span><span class=special>&gt;</span> <span class=special>&gt;::</span><span class=identifier>type</span> <span class=identifier>s</span> <span class=special>=</span> <span class=identifier>boost</span><span class=special>::</span><span class=identifier>size</span><span class=special>(</span> <span class=identifier>pair</span> <span class=special>);</span>
720        <span class=identifier>s</span>      <span class=special>=</span> <span class=identifier>boost</span><span class=special>::</span><span class=identifier>size</span><span class=special>(</span> <span class=identifier>cpair</span> <span class=special>);</span>
721        <span class=identifier>boost</span><span class=special>::</span><span class=identifier>range_const_reverse_iterator</span><span class=special>&lt;</span> <span class=identifier>Foo</span><span class=special>::</span><span class=identifier>Pair</span><span class=special>&lt;</span><span class=identifier>iter</span><span class=special>&gt;</span> <span class=special>&gt;::</span><span class=identifier>type</span>
722        <span class=identifier>ri</span>     <span class=special>=</span> <span class=identifier>boost</span><span class=special>::</span><span class=identifier>rbegin</span><span class=special>(</span> <span class=identifier>cpair</span> <span class=special>),</span>
723        <span class=identifier>re</span>     <span class=special>=</span> <span class=identifier>boost</span><span class=special>::</span><span class=identifier>rend</span><span class=special>(</span> <span class=identifier>cpair</span> <span class=special>);</span>
724<span class=special>}</span>   
725</pre>
726</blockquote>
727               
728                <hr>
729                <p>
730                        (C) Copyright Thorsten Ottosen 2003-2004. Use, modification and distribution is subject to the Boost Software License, Version 1.0.
731                </p>
732                <br>
733                <br>
734                <br>
735                <br>
736                <br>
737                <br>
738                <br>
739                <br>
740                <br>
741                <br>
742                <br>
743                <br>
744        </body>
745</html>
Note: See TracBrowser for help on using the repository browser.