Imported Upstream version 1.49.0
[platform/upstream/boost.git] / libs / range / doc / html / range / reference / adaptors / reference / type_erased.html
1 <html>
2 <head>
3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
4 <title>type_erased</title>
5 <link rel="stylesheet" href="../../../../../../../../doc/src/boostbook.css" type="text/css">
6 <meta name="generator" content="DocBook XSL Stylesheets V1.75.2">
7 <link rel="home" href="../../../../index.html" title="Chapter&#160;1.&#160;Range 2.0">
8 <link rel="up" href="../reference.html" title="Reference">
9 <link rel="prev" href="strided.html" title="strided">
10 <link rel="next" href="tokenized.html" title="tokenized">
11 </head>
12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
13 <table cellpadding="2" width="100%"><tr>
14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../../boost.png"></td>
15 <td align="center"><a href="../../../../../../../../index.html">Home</a></td>
16 <td align="center"><a href="../../../../../../../../libs/libraries.htm">Libraries</a></td>
17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
19 <td align="center"><a href="../../../../../../../../more/index.htm">More</a></td>
20 </tr></table>
21 <hr>
22 <div class="spirit-nav">
23 <a accesskey="p" href="strided.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.html"><img src="../../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="tokenized.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a>
24 </div>
25 <div class="section">
26 <div class="titlepage"><div><div><h5 class="title">
27 <a name="range.reference.adaptors.reference.type_erased"></a><a class="link" href="type_erased.html" title="type_erased">type_erased</a>
28 </h5></div></div></div>
29 <div class="toc"><dl><dt><span class="section"><a href="type_erased.html#range.reference.adaptors.reference.type_erased.type_erased_example">type-erased
30             example</a></span></dt></dl></div>
31 <div class="informaltable"><table class="table">
32 <colgroup>
33 <col>
34 <col>
35 </colgroup>
36 <thead><tr>
37 <th>
38                     <p>
39                       Syntax
40                     </p>
41                   </th>
42 <th>
43                     <p>
44                       Code
45                     </p>
46                   </th>
47 </tr></thead>
48 <tbody>
49 <tr>
50 <td>
51                     <p>
52                       Pipe
53                     </p>
54                   </td>
55 <td>
56                     <p>
57                       <code class="computeroutput"><span class="identifier">rng</span> <span class="special">|</span>
58                       <span class="identifier">boost</span><span class="special">::</span><span class="identifier">adaptors</span><span class="special">::</span><span class="identifier">type_erased</span><span class="special">&lt;</span><span class="identifier">Value</span><span class="special">,</span>
59                       <span class="identifier">Traversal</span><span class="special">,</span>
60                       <span class="identifier">Reference</span><span class="special">,</span>
61                       <span class="identifier">Difference</span><span class="special">,</span>
62                       <span class="identifier">Buffer</span><span class="special">&gt;()</span></code>
63                     </p>
64                   </td>
65 </tr>
66 <tr>
67 <td>
68                     <p>
69                       Function
70                     </p>
71                   </td>
72 <td>
73                     <p>
74                       <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">adaptors</span><span class="special">::</span><span class="identifier">type_erase</span><span class="special">(</span><span class="identifier">rng</span><span class="special">,</span>
75                       <span class="identifier">boost</span><span class="special">::</span><span class="identifier">adaptors</span><span class="special">::</span><span class="identifier">type_erased</span><span class="special">&lt;</span><span class="identifier">Value</span><span class="special">,</span>
76                       <span class="identifier">Traversal</span><span class="special">,</span>
77                       <span class="identifier">Reference</span><span class="special">,</span>
78                       <span class="identifier">Difference</span><span class="special">,</span>
79                       <span class="identifier">Buffer</span><span class="special">&gt;)</span></code>
80                     </p>
81                   </td>
82 </tr>
83 </tbody>
84 </table></div>
85 <p>
86             Please note that it is frequently unnecessary to use the <code class="computeroutput"><span class="identifier">type_erased</span></code> adaptor. It is often better
87             to use the implicit conversion to <code class="computeroutput"><span class="identifier">any_range</span></code>.
88           </p>
89 <p>
90             Let <code class="computeroutput"><span class="identifier">Rng</span></code> be the type of
91             <code class="computeroutput"><span class="identifier">rng</span></code>.
92           </p>
93 <div class="itemizedlist"><ul class="itemizedlist" type="disc">
94 <li class="listitem">
95 <p class="simpara">
96                 <span class="bold"><strong>Template parameters:</strong></span>
97               </p>
98 <div class="itemizedlist"><ul class="itemizedlist" type="circle">
99 <li class="listitem">
100                     <code class="computeroutput"><span class="identifier">Value</span></code> is the
101                     <code class="computeroutput"><span class="identifier">value_type</span></code> for
102                     the <code class="computeroutput"><span class="identifier">any_range</span></code>.
103                     If this is set to boost::use_default, <code class="computeroutput"><span class="identifier">Value</span></code>
104                     will be calculated from the range type when the adaptor is applied.
105                   </li>
106 <li class="listitem">
107                     <code class="computeroutput"><span class="identifier">Traversal</span></code> is
108                     the tag used to identify the traversal of the resultant range.
109                     Frequently it is desireable to set a traversal category lower
110                     than the source container or range to maximize the number of
111                     ranges that can convert to the <code class="computeroutput"><span class="identifier">any_range</span></code>.
112                     If this is left as boost::use_default then <code class="computeroutput"><span class="identifier">Traversal</span></code>
113                     will be <code class="computeroutput"><span class="keyword">typename</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">iterator_traversal</span><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">range_iterator</span><span class="special">&lt;</span><span class="identifier">Rng</span><span class="special">&gt;::</span><span class="identifier">type</span><span class="special">&gt;::</span><span class="identifier">type</span></code>
114                   </li>
115 <li class="listitem">
116                     <code class="computeroutput"><span class="identifier">Reference</span></code> is
117                     the <code class="computeroutput"><span class="identifier">reference</span></code>
118                     for the <code class="computeroutput"><span class="identifier">any_range</span></code>.
119                     <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">use_default</span></code> will equate to
120                     <code class="computeroutput"><span class="keyword">typename</span> <span class="identifier">range_reference</span><span class="special">&lt;</span><span class="identifier">Rng</span><span class="special">&gt;::</span><span class="identifier">type</span></code>.
121                   </li>
122 <li class="listitem">
123                     <code class="computeroutput"><span class="identifier">Difference</span></code> is
124                     the <code class="computeroutput"><span class="identifier">difference_type</span></code>
125                     for the any_range. <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">use_default</span></code>
126                     will equate to <code class="computeroutput"><span class="keyword">typename</span>
127                     <span class="identifier">boost</span><span class="special">::</span><span class="identifier">range_difference</span><span class="special">&lt;</span><span class="identifier">Rng</span><span class="special">&gt;::</span><span class="identifier">type</span></code>
128                   </li>
129 <li class="listitem">
130                     <code class="computeroutput"><span class="identifier">Buffer</span></code> is the
131                     storage used to allocate the underlying iterator wrappers. This
132                     can typically be ignored, but is available as a template parameter
133                     for customization. Buffer must be a model of the <code class="computeroutput"><span class="identifier">AnyIteratorBufferConcept</span></code>.
134                   </li>
135 </ul></div>
136 </li>
137 <li class="listitem">
138                 <span class="bold"><strong>Precondition:</strong></span> <code class="computeroutput"><span class="identifier">Traversal</span></code>
139                 is one of <code class="computeroutput"><span class="special">{</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">use_default</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">single_pass_traversal_tag</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">forward_traversal_tag</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">bidirectional_traversal_tag</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">random_access_traversal_tag</span>
140                 <span class="special">}</span></code>
141               </li>
142 <li class="listitem">
143                 <span class="bold"><strong>Returns:</strong></span> The returned value is the
144                 same as <code class="computeroutput"><span class="keyword">typename</span> <span class="identifier">any_range_type_generator</span><span class="special">&lt;</span> <span class="identifier">Rng</span><span class="special">,</span> <span class="identifier">Value</span><span class="special">,</span> <span class="identifier">Traversal</span><span class="special">,</span> <span class="identifier">Reference</span><span class="special">,</span> <span class="identifier">Difference</span><span class="special">,</span> <span class="identifier">Buffer</span>
145                 <span class="special">&gt;</span></code> that represents <code class="computeroutput"><span class="identifier">rng</span></code> in a type-erased manner.
146               </li>
147 <li class="listitem">
148                 <span class="bold"><strong>Range Category:</strong></span> <a class="link" href="../../../concepts/single_pass_range.html" title="Single Pass Range">Single
149                 Pass Range</a>
150               </li>
151 <li class="listitem">
152                 <span class="bold"><strong>Returned Range Category:</strong></span> if <code class="computeroutput"><span class="identifier">Traversal</span></code> was specified as <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">use_default</span></code> then <code class="computeroutput"><span class="keyword">typename</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">iterator_traversal</span><span class="special">&lt;</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">range_iterator</span><span class="special">&lt;</span><span class="identifier">Rng</span><span class="special">&gt;::</span><span class="identifier">type</span><span class="special">&gt;::</span><span class="identifier">type</span></code>,
153                 otherwise <code class="computeroutput"><span class="identifier">Traversal</span></code>.
154               </li>
155 </ul></div>
156 <a name="range.reference.adaptors.reference.type_erased.anyiteratorbufferconcept"></a><h6>
157 <a name="id677095"></a>
158             <a class="link" href="type_erased.html#range.reference.adaptors.reference.type_erased.anyiteratorbufferconcept">AnyIteratorBufferConcept</a>
159           </h6>
160 <p>
161             
162 </p>
163 <pre class="programlisting"><span class="keyword">class</span> <span class="identifier">AnyIteratorBufferConcept</span>
164 <span class="special">{</span>
165 <span class="keyword">public</span><span class="special">:</span>
166     <span class="identifier">AnyIteratorBufferConcept</span><span class="special">();</span>
167     <span class="special">~</span><span class="identifier">AnyIteratorBufferConcept</span><span class="special">();</span>
168
169     <span class="comment">// bytes is the requested size to allocate. This function
170 </span>    <span class="comment">// must return a pointer to an adequate area of memory.
171 </span>    <span class="comment">// throws: bad_alloc
172 </span>    <span class="comment">//
173 </span>    <span class="comment">// The buffer will only ever have zero or one
174 </span>    <span class="comment">// outstanding memory allocations.
175 </span>    <span class="keyword">void</span><span class="special">*</span> <span class="identifier">allocate</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">bytes</span><span class="special">);</span>
176
177     <span class="comment">// deallocate this buffer
178 </span>    <span class="keyword">void</span> <span class="identifier">deallocate</span><span class="special">();</span>
179 <span class="special">};</span>
180 </pre>
181 <p>
182           </p>
183 <div class="section">
184 <div class="titlepage"><div><div><h6 class="title">
185 <a name="range.reference.adaptors.reference.type_erased.type_erased_example"></a><a class="link" href="type_erased.html#range.reference.adaptors.reference.type_erased.type_erased_example" title="type-erased example">type-erased
186             example</a>
187 </h6></div></div></div>
188 <p>
189               
190 </p>
191 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">range</span><span class="special">/</span><span class="identifier">adaptor</span><span class="special">/</span><span class="identifier">type_erased</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
192 <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">algorithm</span><span class="special">/</span><span class="identifier">copy</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
193 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">assign</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
194 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">foreach</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
195 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">algorithm</span><span class="special">&gt;</span>
196 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
197 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">list</span><span class="special">&gt;</span>
198 <span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">vector</span><span class="special">&gt;</span>
199
200 <span class="comment">// The client interface from an OO perspective merely requires a sequence
201 </span><span class="comment">// of integers that can be forward traversed
202 </span><span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">any_range</span><span class="special">&lt;</span>
203     <span class="keyword">int</span>
204   <span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">forward_traversal_tag</span>
205   <span class="special">,</span> <span class="keyword">int</span>
206   <span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ptrdiff_t</span>
207 <span class="special">&gt;</span> <span class="identifier">integer_range</span><span class="special">;</span>
208
209 <span class="keyword">namespace</span> <span class="identifier">server</span>
210 <span class="special">{</span>
211     <span class="keyword">void</span> <span class="identifier">display_integers</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">integer_range</span><span class="special">&amp;</span> <span class="identifier">rng</span><span class="special">)</span>
212     <span class="special">{</span>
213         <span class="identifier">boost</span><span class="special">::</span><span class="identifier">copy</span><span class="special">(</span><span class="identifier">rng</span><span class="special">,</span>
214                     <span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream_iterator</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">,</span> <span class="string">","</span><span class="special">));</span>
215
216         <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
217     <span class="special">}</span>
218 <span class="special">}</span>
219
220 <span class="keyword">namespace</span> <span class="identifier">client</span>
221 <span class="special">{</span>
222     <span class="keyword">void</span> <span class="identifier">run</span><span class="special">()</span>
223     <span class="special">{</span>
224         <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">assign</span><span class="special">;</span>
225         <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">adaptors</span><span class="special">;</span>
226
227         <span class="comment">// Under most conditions one would simply use an appropriate
228 </span>        <span class="comment">// any_range as a function parameter. The type_erased adaptor
229 </span>        <span class="comment">// is often superfluous. However because the type_erased
230 </span>        <span class="comment">// adaptor is applied to a range, we can use default template
231 </span>        <span class="comment">// arguments that are generated in conjunction with the
232 </span>        <span class="comment">// range type to which we are applying the adaptor.
233 </span>
234         <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">input</span><span class="special">;</span>
235         <span class="identifier">input</span> <span class="special">+=</span> <span class="number">1</span><span class="special">,</span><span class="number">2</span><span class="special">,</span><span class="number">3</span><span class="special">,</span><span class="number">4</span><span class="special">,</span><span class="number">5</span><span class="special">;</span>
236
237         <span class="comment">// Note that this call is to a non-template function
238 </span>        <span class="identifier">server</span><span class="special">::</span><span class="identifier">display_integers</span><span class="special">(</span><span class="identifier">input</span><span class="special">);</span>
239
240         <span class="identifier">std</span><span class="special">::</span><span class="identifier">list</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">input2</span><span class="special">;</span>
241         <span class="identifier">input2</span> <span class="special">+=</span> <span class="number">6</span><span class="special">,</span><span class="number">7</span><span class="special">,</span><span class="number">8</span><span class="special">,</span><span class="number">9</span><span class="special">,</span><span class="number">10</span><span class="special">;</span>
242
243         <span class="comment">// Note that this call is to the same non-tempate function
244 </span>        <span class="identifier">server</span><span class="special">::</span><span class="identifier">display_integers</span><span class="special">(</span><span class="identifier">input2</span><span class="special">);</span>
245
246         <span class="identifier">input2</span><span class="special">.</span><span class="identifier">clear</span><span class="special">();</span>
247         <span class="identifier">input2</span> <span class="special">+=</span> <span class="number">11</span><span class="special">,</span><span class="number">12</span><span class="special">,</span><span class="number">13</span><span class="special">,</span><span class="number">14</span><span class="special">,</span><span class="number">15</span><span class="special">;</span>
248
249         <span class="comment">// Calling using the adaptor looks like this:
250 </span>        <span class="comment">// Notice that here I have a type_erased that would be a
251 </span>        <span class="comment">// bidirectional_traversal_tag, but this is convertible
252 </span>        <span class="comment">// to the forward_traversal_tag equivalent hence this
253 </span>        <span class="comment">// works.
254 </span>        <span class="identifier">server</span><span class="special">::</span><span class="identifier">display_integers</span><span class="special">(</span><span class="identifier">input2</span> <span class="special">|</span> <span class="identifier">type_erased</span><span class="special">&lt;&gt;());</span>
255
256         <span class="comment">// However we may simply wish to define an adaptor that
257 </span>        <span class="comment">// takes a range and makes it into an appropriate
258 </span>        <span class="comment">// forward_traversal any_range...
259 </span>        <span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">adaptors</span><span class="special">::</span><span class="identifier">type_erased</span><span class="special">&lt;</span>
260             <span class="identifier">boost</span><span class="special">::</span><span class="identifier">use_default</span>
261           <span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">forward_traversal_tag</span>
262         <span class="special">&gt;</span> <span class="identifier">type_erased_forward</span><span class="special">;</span>
263
264         <span class="comment">// This adaptor can turn other containers with different
265 </span>        <span class="comment">// value_types and reference_types into the appropriate
266 </span>        <span class="comment">// any_range.
267 </span>
268         <span class="identifier">server</span><span class="special">::</span><span class="identifier">display_integers</span><span class="special">(</span><span class="identifier">input2</span> <span class="special">|</span> <span class="identifier">type_erased_forward</span><span class="special">());</span>
269     <span class="special">}</span>
270 <span class="special">}</span>
271
272 <span class="keyword">int</span> <span class="identifier">main</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">argc</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">argv</span><span class="special">[])</span>
273 <span class="special">{</span>
274     <span class="identifier">client</span><span class="special">::</span><span class="identifier">run</span><span class="special">();</span>
275     <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
276 <span class="special">}</span>
277 </pre>
278 <p>
279             </p>
280 </div>
281 <p>
282             This would produce the output: 
283 </p>
284 <pre class="programlisting"><span class="number">1</span><span class="special">,</span><span class="number">2</span><span class="special">,</span><span class="number">3</span><span class="special">,</span><span class="number">4</span><span class="special">,</span><span class="number">5</span>
285 <span class="number">6</span><span class="special">,</span><span class="number">7</span><span class="special">,</span><span class="number">8</span><span class="special">,</span><span class="number">9</span><span class="special">,</span><span class="number">10</span>
286 <span class="number">11</span><span class="special">,</span><span class="number">12</span><span class="special">,</span><span class="number">13</span><span class="special">,</span><span class="number">14</span><span class="special">,</span><span class="number">15</span>
287 <span class="number">11</span><span class="special">,</span><span class="number">12</span><span class="special">,</span><span class="number">13</span><span class="special">,</span><span class="number">14</span><span class="special">,</span><span class="number">15</span>
288 </pre>
289 <p>
290           </p>
291 </div>
292 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
293 <td align="left"></td>
294 <td align="right"><div class="copyright-footer">Copyright &#169; 2003 -2010 Thorsten Ottosen, Neil Groves<p>
295         Distributed under the Boost Software License, Version 1.0. (See accompanying
296         file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
297       </p>
298 </div></td>
299 </tr></table>
300 <hr>
301 <div class="spirit-nav">
302 <a accesskey="p" href="strided.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../reference.html"><img src="../../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../../index.html"><img src="../../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="tokenized.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a>
303 </div>
304 </body>
305 </html>