Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/libs/range/doc/utility_class.html @ 29

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

updated boost from 1_33_1 to 1_34_1
File size: 35.1 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
2
3<html>
4<head>
5    <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6    <title>Boost.Range Utilities </title>
7    <link rel="stylesheet" href="style.css" type="text/css">
8</head>
9
10    <body>
11    <table border="0" >
12        <tr>
13            <td ><img src="../../../boost.png" border="0" ></td>
14            <td ><h1 align="center">Boost.Range</h1></td>
15        </tr>
16    </table>
17
18    <h2>Utilities</h2>
19    <p>
20    Having an abstraction that encapsulates a pair of iterators is very useful. The
21    standard library uses <code>std::pair</code> in some circumstances, but that
22    class is cumbersome to use because we need to specify two template arguments,
23    and for all range algorithm purposes we must enforce the two template arguments
24    to be the same. Moreover, <code>std::pair&lt;iterator,iterator></code> is hardly
25    self-documenting whereas more domain specific class names are. Therefore these
26    two classes are provided:
27
28    <ul>
29        <li>
30            Class <a href=#iter_range><code>iterator_range</code></a>
31        <li>
32            Class <a href=#sub_range><code>sub_range</code></a>
33    </ul>
34    </ul>
35
36    The <code>iterator_range</code> class is templated on an
37    <a href="../../iterator/doc/new-iter-concepts.html#forward-traversal-iterators-lib-forward-traversal-iterators">Forward
38    Traversal Iterator</a> and should be used whenever fairly general code is needed.
39    The <code>sub_range</code> class is templated on an <a href="range.html#forward_range">Forward
40    Range</a> and it is less general, but a bit easier to use since its template
41    argument is easier to specify. The biggest difference is, however, that a
42    <code>sub_range</code> can propagate constness because it knows what a
43corresponding <code>const_iterator</code> is. </p>
44   
45    <p>
46    Both classes can be used as ranges since they implement the <a 
47    href="boost_range.html#minimal_interface">minimal interface</a>
48    required for this to work automatically.
49    </p>
50
51    <hr>
52    <a name=iter_range></a> <h1>Class <code>iterator_range</code></h1>
53    <p>
54    The intention of the <code>iterator_range</code> class is to encapsulate two
55    iterators so they fulfill the <a
56      href="range.html#forward_range">Forward Range</a> concept. A few other
57    functions are also provided for convenience.
58    </p>
59    <p>
60    If the template argument is not a model of Forward Traversal Iterator, one can
61    still use a subset of the interface. In particular, <code>size()</code> requires
62    Forward Traversal Iterators whereas <code>empty()</code> only requires Single
63    Pass Iterators.
64    </p>
65
66    <p>
67    Recall that many default constructed iterators
68    are <i>singular</i> and hence can only be assigned, but not compared or
69    incremented or anything. However, if one creates a default constructed
70    <code>iterator_range</code>, then one
71    can still call all its member functions. This means that the
72    <code>iterator_range</code> will still be usable in many contexts even
73    though the iterators underneath are not.
74    </p>
75   
76    <h3>Synopsis</h3>
77
78    <pre>
79<span class=keyword>namespace </span><span class=identifier>boost</span>
80<span class=special>{
81    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>ForwardTraversalIterator </span><span class=special>&gt;
82    </span><span class=keyword>class </span><span class=identifier>iterator_range
83    </span><span class=special>{
84    </span><span class=keyword>public</span><span class=special>: </span><span class=comment>// Forward Range types
85        </span><span class=keyword>typedef </span><span class=special>...                        </span><span class=identifier>value_type</span><span class=special>;
86        </span><span class=keyword>typedef </span><span class=special>...                        </span><span class=identifier>difference_type</span><span class=special>;
87        </span><span class=keyword>typedef </span><span class=special>...                        </span><span class=identifier>size_type</span><span class=special>;
88        </span><span class=keyword>typedef </span><span class=identifier>ForwardTraversalIterator   </span><span class=identifier>iterator</span><span class=special>;
89        </span><span class=keyword>typedef </span><span class=identifier>ForwardTraversalIterator   </span><span class=identifier>const_iterator</span><span class=special>;
90
91    </span><span class=keyword>public</span><span class=special>: </span><span class=comment>// construction, assignment
92        </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>ForwardTraversalIterator2 </span><span class=special>&gt;
93        </span><span class=identifier>iterator_range</span><span class=special>( </span><span class=identifier>ForwardTraversalIterator2 </span><span class=identifier>Begin</span><span class=special>, </span><span class=identifier>ForwardTraversalIterator2 </span><span class=identifier>End </span><span class=special>);
94                   
95        </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>ForwardRange </span><span class=special>&gt;
96        </span><span class=identifier>iterator_range</span><span class=special>( </span><span class=identifier>ForwardRange</span><span class=special>&amp; </span><span class=identifier>r </span><span class=special>);
97 
98        </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>ForwardRange </span><span class=special>&gt;
99        </span><span class=identifier>iterator_range</span><span class=special>( </span><span class=keyword>const </span><span class=identifier>ForwardRange</span><span class=special>&amp; </span><span class=identifier>r </span><span class=special>);
100       
101        </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>ForwardRange </span><span class=special>&gt;
102        </span><span class=identifier>iterator_range</span><span class=special>&amp; </span><span class=keyword>operator</span><span class=special>=( </span><span class=identifier>ForwardRange</span><span class=special>&amp; </span><span class=identifier>r </span><span class=special>);
103
104        </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>ForwardRange </span><span class=special>&gt;
105        </span><span class=identifier>iterator_range</span><span class=special>&amp; </span><span class=keyword>operator</span><span class=special>=( </span><span class=keyword>const </span><span class=identifier>ForwardRange</span><span class=special>&amp; </span><span class=identifier>r </span><span class=special>);
106   
107    </span><span class=keyword>public</span><span class=special>: </span><span class=comment>// Forward Range functions
108        </span><span class=identifier>iterator  </span><span class=identifier>begin</span><span class=special>() </span><span class=keyword>const</span><span class=special>;
109        </span><span class=identifier>iterator  </span><span class=identifier>end</span><span class=special>() </span><span class=keyword>const</span><span class=special>;
110        </span><span class=identifier>size_type </span><span class=identifier>size</span><span class=special>() </span><span class=keyword>const</span><span class=special>;
111        </span><span class=keyword>bool      </span><span class=identifier>empty</span><span class=special>() </span><span class=keyword>const</span><span class=special>;
112       
113    </span><span class=keyword>public</span><span class=special>: </span><span class=comment>// convenience
114        </span><span class=keyword>operator    </span><a href="#unspecified_bool"><span class=identifier>unspecified_bool_type</span></a><span class=special>() </span><span class=keyword>const</span><span class=special>;
115    </span>    <span class=keyword>bool</span>        <span 
116class=identifier><a href="#equal">equal</a></span><span
117class=special>( </span><span class=keyword>const <span 
118class=identifier>iterator_range</span><span class=special>& ) </span><span 
119class=keyword>const;</span>
120        <span class=identifier>value_type</span><span class=special>&amp; </span><span class=identifier>front</span><span class=special>() </span><span class=keyword>const</span><span class=special>;</span>
121        <span class=identifier>value_type</span><span class=special>&amp; </span><span class=identifier>back</span><span class=special>() </span><span class=keyword>const</span><span class=special>;</span>
122        <span class=comment>// for Random Access Range only: </span>
123        <span class=identifier>value_type</span><span class=special>&amp; </span><span class=keyword>operator</span><span class=special>[]( </span><span class=identifier>size_type </span><span class=identifier>at </span><span class=special>) </span><span class=keyword>const</span><span class=special>;</span>
124    </span><span class=special>};
125   
126    </span><span class=comment>// stream output
127    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>ForwardTraversalIterator</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>T</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>Traits </span><span class=special>&gt;
128    </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>basic_ostream</span><span class=special>&lt;</span><span class=identifier>T</span><span class=special>,</span><span class=identifier>Traits</span><span class=special>&gt;&amp; 
129    </span><span class=keyword>operator</span><span class=special>&lt;&lt;( </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>basic_ostream</span><span class=special>&lt;</span><span class=identifier>T</span><span class=special>,</span><span class=identifier>Traits</span><span class=special>&gt;&amp; </span><span class=identifier>Os</span><span class=special>,
130                </span><span class=keyword>const </span><span class=identifier>iterator_range</span><span class=special>&lt;</span><span class=identifier>ForwardTraversalIterator</span><span class=special>&gt;&amp; </span><span class=identifier>r </span><span class=special>);
131
132    </span><span class=comment>// <a href="#comparison">comparison</a>
133    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>ForwardTraversalIterator</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>ForwardTraversalIterator2 </span><span class=special>&gt;
134    </span><span class=keyword>bool </span><span class=keyword>operator</span><span class=special>==( </span><span class=keyword>const </span><span class=identifier>iterator_range</span><span class=special>&lt;</span><span class=identifier>ForwardTraversalIterator</span><span class=special>&gt;&amp; </span><span class=identifier>l</span><span class=special>,
135                     </span><span class=keyword>const </span><span class=identifier>iterator_range</span><span class=special>&lt;</span><span class=identifier>ForwardTraversalIterator2</span><span class=special>&gt;&amp; </span><span class=identifier>r </span><span class=special>);
136
137    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>ForwardTraversalIterator</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>ForwardRange </span><span class=special>&gt;
138    </span><span class=keyword>bool </span><span class=keyword>operator</span><span class=special>==( </span><span class=keyword>const </span><span class=identifier>iterator_range</span><span class=special>&lt;</span><span class=identifier>ForwardTraversalIterator</span><span class=special>&gt;&amp; </span><span class=identifier>l</span><span class=special>,
139                     </span><span class=keyword>const </span><span class=identifier>ForwardRange</span><span class=special>&amp; </span><span class=identifier>r </span><span class=special>);
140
141    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>ForwardTraversalIterator</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>ForwardRange </span><span class=special>&gt;
142    </span><span class=keyword>bool </span><span class=keyword>operator</span><span class=special>==( </span><span class=keyword>const </span><span class=identifier>ForwardRange</span><span class=special>&amp; </span><span class=identifier>l</span><span class=special>,
143                     </span><span class=keyword>const </span><span class=identifier>iterator_range</span><span class=special>&lt;</span><span class=identifier>ForwardTraversalIterator</span><span class=special>&gt;&amp; </span><span class=identifier>r </span><span class=special>);
144
145    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>ForwardTraversalIterator</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>ForwardTraversalIterator2 </span><span class=special>&gt;
146    </span><span class=keyword>bool </span><span class=keyword>operator</span><span class=special>!=( </span><span class=keyword>const </span><span class=identifier>iterator_range</span><span class=special>&lt;</span><span class=identifier>ForwardTraversalIterator</span><span class=special>&gt;&amp; </span><span class=identifier>l</span><span class=special>,
147                     </span><span class=keyword>const </span><span class=identifier>iterator_range</span><span class=special>&lt;</span><span class=identifier>ForwardTraversalIterator2</span><span class=special>&gt;&amp; </span><span class=identifier>r </span><span class=special>);
148
149    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>ForwardTraversalIterator</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>ForwardRange </span><span class=special>&gt;
150    </span><span class=keyword>bool </span><span class=keyword>operator</span><span class=special>!=( </span><span class=keyword>const </span><span class=identifier>iterator_range</span><span class=special>&lt;</span><span class=identifier>ForwardTraversalIterator</span><span class=special>&gt;&amp; </span><span class=identifier>l</span><span class=special>,
151                     </span><span class=keyword>const </span><span class=identifier>ForwardRange</span><span class=special>&amp; </span><span class=identifier>r </span><span class=special>);
152
153    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>ForwardTraversalIterator</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>ForwardRange </span><span class=special>&gt;
154    </span><span class=keyword>bool </span><span class=keyword>operator</span><span class=special>!=( </span><span class=keyword>const </span><span class=identifier>ForwardRange</span><span class=special>&amp; </span><span class=identifier>l</span><span class=special>,
155                     </span><span class=keyword>const </span><span class=identifier>iterator_range</span><span class=special>&lt;</span><span class=identifier>ForwardTraversalIterator</span><span class=special>&gt;&amp; </span><span class=identifier>r </span><span class=special>);
156
157    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>ForwardTraversalIterator</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>ForwardTraversalIterator2 </span><span class=special>&gt;
158    </span><span class=keyword>bool </span><span class=keyword>operator</span><span class=special>&lt;( </span><span class=keyword>const </span><span class=identifier>iterator_range</span><span class=special>&lt;</span><span class=identifier>ForwardTraversalIterator</span><span class=special>&gt;&amp; </span><span class=identifier>l</span><span class=special>,
159                    </span><span class=keyword>const </span><span class=identifier>iterator_range</span><span class=special>&lt;</span><span class=identifier>ForwardTraversalIterator2</span><span class=special>&gt;&amp; </span><span class=identifier>r </span><span class=special>);
160
161    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>ForwardTraversalIterator</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>ForwardRange </span><span class=special>&gt;
162    </span><span class=keyword>bool </span><span class=keyword>operator</span><span class=special>&lt;( </span><span class=keyword>const </span><span class=identifier>iterator_range</span><span class=special>&lt;</span><span class=identifier>ForwardTraversalIterator</span><span class=special>&gt;&amp; </span><span class=identifier>l</span><span class=special>,
163                    </span><span class=keyword>const </span><span class=identifier>ForwardRange</span><span class=special>&amp; </span><span class=identifier>r </span><span class=special>);
164
165    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>ForwardTraversalIterator</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>ForwardRange </span><span class=special>&gt;
166    </span><span class=keyword>bool </span><span class=keyword>operator</span><span class=special>&lt;( </span><span class=keyword>const </span><span class=identifier>ForwardRange</span><span class=special>&amp; </span><span class=identifier>l</span><span class=special>,
167                    </span><span class=keyword>const </span><span class=identifier>iterator_range</span><span class=special>&lt;</span><span class=identifier>ForwardTraversalIterator</span><span class=special>&gt;&amp; </span><span class=identifier>r </span><span class=special>);</span>
168 
169    </span><span class=comment>// external construction
170    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>ForwardTraversalIterator </span><span class=special>&gt;
171    </span><span class=identifier>iterator_range</span><span class=special>&lt; </span><span class=identifier>ForwardTraversalIterator </span><span class=special>&gt;
172    </span><span class=identifier>make_iterator_range</span><span class=special>( </span><span class=identifier>ForwardTraversalIterator </span><span class=identifier>Begin</span><span class=special>,
173                         </span><span class=identifier>ForwardTraversalIterator </span><span class=identifier>End </span><span class=special>);
174       
175    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>ForwardRange </span><span class=special>&gt;
176    </span><span class=identifier>iterator_range</span><span class=special>&lt; </span><span class=keyword>typename </span><span class=identifier>iterator_of</span><span class=special>&lt;</span><span class=identifier>ForwardRange</span><span class=special>&gt;::</span><span class=identifier>type </span><span class=special>&gt;
177    </span><span class=identifier>make_iterator_range</span><span class=special>( </span><span class=identifier>ForwardRange</span><span class=special>&amp; </span><span class=identifier>r </span><span class=special>);
178
179    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>ForwardRange </span><span class=special>&gt;
180    </span><span class=identifier>iterator_range</span><span class=special>&lt; </span><span class=keyword>typename </span><span class=identifier>const_iterator_of</span><span class=special>&lt;</span><span class=identifier>ForwardRange</span><span class=special>&gt;::</span><span class=identifier>type </span><span class=special>&gt;
181    </span><span class=identifier>make_iterator_range</span><span class=special>( </span><span class=keyword>const </span><span class=identifier>ForwardRange</span><span class=special>&amp; </span><span class=identifier>r </span><span class=special>);
182    </span>
183    <span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>Range </span><span class=special>&gt;</span>
184    <span class=identifier>iterator_range</span><span class=special>&lt; </span><span class=keyword>typename </span><span class=identifier>range_iterator</span><span class=special>&lt;</span><span class=identifier>Range</span><span class=special>&gt;::</span><span class=identifier>type </span><span class=special>&gt;</span>
185    <span class=identifier><a href="#make_iterator_range">make_iterator_range</a></span><span class=special>(</span><span class=identifier> Range</span><span class=special>&amp; </span><span class=identifier>r</span><span class=special>,
186                         </span><span class=keyword>typename </span><span class=identifier>range_difference</span><span class=special>&lt;</span><span class=identifier>Range</span><span class=special>&gt;::</span><span class=identifier>type </span><span class=identifier>advance_begin</span><span class=special>,
187                         </span><span class=keyword>typename </span><span class=identifier>range_difference</span><span class=special>&lt;</span><span class=identifier>Range</span><span class=special>&gt;::</span><span class=identifier>type </span><span class=identifier>advance_end </span><span class=special>);
188    </span>
189    <span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>Range </span><span class=special>&gt;</span>
190    <span class=identifier>iterator_range</span><span class=special>&lt; </span><span class=keyword>typename </span><span class=identifier>range_const_iterator</span><span class=special>&lt;</span><span class=identifier>Range</span><span class=special>&gt;::</span><span class=identifier>type </span><span class=special>&gt;</span>
191    <span class=identifier>make_iterator_range</span><span class=special>( </span><span class=keyword>const </span><span class=identifier>Range</span><span class=special>&amp; </span><span class=identifier>r</span><span class=special>,
192                         </span><span class=keyword>typename </span><span class=identifier>range_difference</span><span class=special>&lt;</span><span class=identifier>Range</span><span class=special>&gt;::</span><span class=identifier>type </span><span class=identifier>advance_begin</span><span class=special>,
193                         </span><span class=keyword>typename </span><span class=identifier>range_difference</span><span class=special>&lt;</span><span class=identifier>Range</span><span class=special>&gt;::</span><span class=identifier>type </span><span class=identifier>advance_end </span><span class=special>);</span>
194   
195    </span><span class=comment>// convenience
196    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>Sequence</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>ForwardRange </span><span class=special>&gt;
197    </span><span class=identifier>Sequence </span><a href="#copy_range"><span 
198class=identifier>copy_range</span></a><span class=special>( </span><span 
199class=keyword>const </span><span class=identifier>ForwardRange</span><span class=special>&amp; </span><span class=identifier>r </span><span class=special>);
200    </span>
201<span class=special>} </span><span class=comment>// namespace 'boost'</span>
202    </pre>
203
204<p>
205 If an instance of
206<code>iterator_range</code> is constructed by a client with two iterators, the
207client must ensure that the two iterators delimit a valid closed-open range
208<code>[begin,end)</code>.
209 </p>
210
211<p>
212It is worth noticing that the templated constructors and assignment operators
213allow conversion from <code>iterator_range&lt;iterator></code> to
214<code>iterator_range&lt;const_iterator></code>. Similarly, since the comparison
215operators have two template arguments, we can compare ranges whenever the
216iterators are comparable; for example when we are dealing with const and
217non-const iterators from the same container. </p>
218 
219 <h3>Details member functions</h3>
220 
221<p> 
222<a name="unspecified_bool"></a> 
223<code>operator  unspecified_bool_type() const; </code>
224 <blockquote>
225<i>Returns</i> <code>!empty();</code>
226 </blockquote>
227</p>
228     
229<p>
230<a name="equal"></a>     
231<code>bool equal( iterator_range& r ) const;</code>
232<blockquote>
233    <i>Returns</i> <code>begin() == r.begin() && end() == r.end();</code>
234</blockquote>
235</p>     
236
237 <h3>Details functions</h3>
238
239<p> 
240<a name="comparison"></a>
241<code>bool operator==( const ForwardRange1& l, const ForwardRange2& r );</code>
242<blockquote>
243    <i>Returns</i> <code>size(l) != size(r) ? false : std::equal( begin(l), end(l), begin(r) );</code> </blockquote> </p>
244<code>bool operator!=( const ForwardRange1& l, const ForwardRange2& r );</code>
245<blockquote>
246    <i>Returns</i> <code>!( l == r );</code>
247</blockquote>
248<code>bool operator<( const ForwardRange1& l, const ForwardRange2& r );</code>
249<blockquote>
250    <i>Returns</i> <code>std::lexicographical_compare( begin(l), end(l), begin(r), end(r) );</code> </blockquote>
251   
252<p>   
253<a name="make_iterator_range"></a>
254<pre>
255iterator_range make_iterator_range( Range& r,
256                                    typename range_difference&lt;Range>::type advance_begin,
257                                    typename range_difference&lt;Range>::type advance_end );
258</pre>
259<blockquote>
260    <i>Effects</i>:
261<pre>
262iterator new_begin = begin( r ),
263iterator new_end   = end( r );
264std::advance( new_begin, advance_begin );
265std::advance( new_end, advance_end );
266return make_iterator_range( new_begin, new_end );
267</pre>
268</blockquote>
269<p> 
270<a name="copy_range"></a> 
271<code>Sequence copy_range( const ForwardRange& r );</code>
272<blockquote>
273    <i>Returns</i> <code>Sequence( begin(r), end(r) );</code>
274</blockquote>
275</p>
276
277<hr> <a name=sub_range></a>
278<h1>Class <code>sub_range</code></h1>
279
280The <code>sub_range</code> class inherits all its functionality
281from the <a href="#iter_range"><code>iterator_range</code></a> class.
282The <code>sub_range</code> class is often easier to use because
283one must specify the <a href="range.html#forward_range">Forward Range</a>
284template argument instead of an iterator. Moreover, the <code>sub_range</code>
285class can propagate constness since it knows what a corresponding
286<code>const_iterator</code> is.
287
288<h3>Synopsis</h3>
289
290<pre>
291<span class=keyword>namespace </span><span class=identifier>boost</span>
292<span class=special>{
293    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>ForwardRange </span><span class=special>&gt;
294    </span><span class=keyword>class </span><span class=identifier>sub_range </span><span class=special>: </span><span class=keyword>public </span><span class=identifier>iterator_range</span><span class=special>&lt; </span><span class=keyword>typename </span><span class=identifier>range_result_iterator</span><span class=special>&lt;</span><span class=identifier>ForwardRange</span><span class=special>&gt;::</span><span class=identifier>type </span><span class=special>&gt;
295    </span><span class=special>{
296    </span><span class=keyword>public</span><span class=special>: </span>
297        <span class=keyword>typedef </span><span class=keyword>typename </span><span class=identifier>range_result_iterator</span><span class=special>&lt;</span><span class=identifier>ForwardRange</span><spanclass=special>&gt;::</span><span class=identifier>type </span><span class=identifier>iterator</span><span class=special>;</span>
298        <span class=keyword>typedef </span><span class=keyword>typename </span><span class=identifier>range_const_iterator</span><span class=special>&lt;</span><span class=identifier>ForwardRange</span><span class=special>&gt;::</span><span class=identifier>type  </span><span class=identifier>const_iterator</span><span class=special>;</span>
299   
300    <span class=keyword>public</span><span class=special>: </span><span class=comment>// construction, assignment
301        </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>ForwardTraversalIterator </span><span class=special>&gt;
302        </span><span class=identifier>sub_range</span><span class=special>( </span><span class=identifier>ForwardTraversalIterator </span><span class=identifier>Begin</span><span class=special>, </span><span class=identifier>ForwardTraversalIterator </span><span class=identifier>End </span><span class=special>);
303
304        </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>ForwardRange2 </span><span class=special>&gt;
305        </span><span class=identifier>sub_range</span><span class=special>( </span><span class=identifier>ForwardRange2</span><span class=special>&amp; </span><span class=identifier>r </span><span class=special>);
306         
307        </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>ForwardRange2 </span><span class=special>&gt;
308        </span><span class=identifier>sub_range</span><span class=special>( </span><span class=keyword>const </span><span class=identifier>Range2</span><span class=special>&amp; </span><span class=identifier>r </span><span class=special>);
309         
310        </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>ForwardRange2 </span><span class=special>&gt;
311        </span><span class=identifier>sub_range</span><span class=special>&amp; </span><span class=keyword>operator</span><span class=special>=( </span><span class=identifier>ForwardRange2</span><span class=special>&amp; </span><span class=identifier>r </span><span class=special>);
312
313        </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>ForwardRange2 </span><span class=special>&gt;
314        </span><span class=identifier>sub_range</span><span class=special>&amp; </span><span class=keyword>operator</span><span class=special>=( </span><span class=keyword>const </span><span class=identifier>ForwardRange2</span><span class=special>&amp; </span><span class=identifier>r </span><span class=special>);   
315    </span>
316    <span class=keyword>public</span><span class=special>:  </span><span class=comment>// Forward Range functions
317        </span><span class=identifier>iterator        </span><span class=identifier>begin</span><span class=special>();
318        </span><span class=identifier>const_iterator  </span><span class=identifier>begin</span><span class=special>() </span><span class=keyword>const</span><span class=special>;
319        </span><span class=identifier>iterator        </span><span class=identifier>end</span><span class=special>();
320        </span><span class=identifier>const_iterator  </span><span class=identifier>end</span><span class=special>() </span><span class=keyword>const</span><span class=special>;</span>   
321       
322    <span class=keyword>public</span><span class=special>: </span><span class=comment>// convenience
323    </span>    <span class=identifier>value_type</span><span class=special>&amp;       </span><span class=identifier>front</span><span class=special>();</span>
324        <span class=keyword>const </span><span class=identifier>value_type</span><span class=special>&amp; </span><span class=identifier>front</span><span class=special>() </span><span class=keyword>const</span><span class=special>;</span>
325        <span class=identifier>value_type</span><span class=special>&amp;       </span><span class=identifier>back</span><span class=special>();</span>
326        <span class=keyword>const </span><span class=identifier>value_type</span><span class=special>&amp; </span><span class=identifier>back</span><span class=special>() </span><span class=keyword>const</span><span class=special>;</span>
327        <span class=comment>// for Random Access Range only: </span>
328        <span class=identifier>value_type</span><span class=special>&amp;       </span><span class=keyword>operator</span><span class=special>[]( </span><span class=identifier>size_type </span><span class=identifier>at </span><span class=special>);</span>
329        <span class=keyword>const </span><span class=identifier>value_type</span><span class=special>&amp; </span><span class=keyword>operator</span><span class=special>[]( </span><span class=identifier>size_type </span><span class=identifier>at </span><span class=special>) </span><span class=keyword>const</span><span class=special>;</span>
330   
331    <span class=keyword>public</span><span class=special>:
332        </span><span class=comment>// rest of interface inherited from <a href=#iter_range><code>iterator_range</code></a>
333    </span><span class=special>};
334    </span>
335<span class=special>} </span><span class=comment>// namespace 'boost'</span>
336</pre>
337   
338    <p>
339    The class should be trivial to use as seen below.
340   Imagine that we have an algorithm that searches for a sub-string in a string.
341    The
342    result is an <code>iterator_range</code>, that delimits the match. We need to
343store the result
344    from this algorithm. Here is an example of how we can do it with and without
345<code>sub_range</code>
346    <pre>
347    <span class=identifier>std</span><span class=special>::</span><span class=identifier>string </span><span class=identifier>str</span><span class=special>(</span><span class=string>&quot;hello&quot;</span><span class=special>);
348    </span><span class=identifier>iterator_range</span><span class=special>&lt;</span><span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span><span class=special>::</span><span class=identifier>iterator</span><span class=special>&gt; </span><span class=identifier>ir </span><span class=special>= </span><span class=identifier>find_first</span><span class=special>( </span><span class=identifier>str</span><span class=special>, </span><span class=string>&quot;ll&quot; </span><span class=special>);
349    </span><span class=identifier>sub_range</span><span class=special>&lt;</span><span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span><span class=special>&gt;               </span><span class=identifier>sub </span><span class=special>= </span><span class=identifier>find_first</span><span class=special>( </span><span class=identifier>str</span><span class=special>, </span><span class=string>&quot;ll&quot; </span><span class=special>);</span>
350</pre>
351 </p>
352
353<hr>
354  <p>
355    (C) Copyright Thorsten Ottosen 2003-2004. Use, modification and distribution is subject to the Boost Software License, Version 1.0.
356  </p>
357
358  <br>
359  <br>
360  <br>
361  <br>
362  <br>
363  <br>
364  <br>
365  <br>
366  <br>
367  <br>
368  <br>
369  <br>
370 
371   
372    </body>
373</html>
374
Note: See TracBrowser for help on using the repository browser.