Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_33_1/libs/assign/doc/index.html @ 13

Last change on this file since 13 was 12, checked in by landauf, 18 years ago

added boost
File size: 129.4 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.Assignment Documentation </title>
7<link rel="stylesheet" href="style.css" type="text/css">
8</head>
9
10<body>
11
12  <table border="0" >
13    <tr>
14      <td ><img src="../../../boost.png" border="0" ></td>
15      <td >
16        <h1 align="center">Assignment Library</h1>
17      </td>
18    </tr>
19  </table>
20
21  <p>
22  Copyright © 2003-2004 Thorsten Ottosen
23  </p>
24  <p>
25  Use, modification and distribution is subject to the Boost Software License, Version 1.0
26  (see <a href=http://www.boost.org/LICENSE_1_0.txt>
27   http://www.boost.org/LICENSE_1_0.txt</a>).
28  </p>
29  <h3>Table of Contents</h3>
30  <ul>
31    <li><a href="#intro">Introduction</a></li>
32    <li>     
33        <a href="#tutorial" >Tutorial</a>
34        <ul>
35            <li>Function <a href="#operator+="><code>operator+=()</code></a>
36            <li>Function <a href="#operator()"><code>operator()()</code></a>
37            <li>Function <a href="#list_of"><code>list_of()</code></a>   
38            <li>Function <a href="#map_list_of"><code>map_list_of()</code></a> 
39            <li>Function <a href="#tuple_list_of"><code>tuple_list_of()</code></a>
40            <li>Functions <a href="#repeat"><code>repeat()</code> and <code>repeat_fun()</code> </a> 
41            <li>Functions <a href="#ref_list_of"><code>ref_list_of()</code> and <code>cref_list_of()</code></a>   
42            <li>A <a href="#complicated">"complicated"</a> example   
43            <li>Functions <a href="#ptr_push_back"><code>ptr_push_back(), ptr_push_front()</code> and <code>ptr_insert()</code></a>
44            <li>Function <a href="#ptr_list_of"><code>ptr_list_of()</code></a>         
45       </ul> <li>         
46               
47        <a href="#reference">Reference</a>
48      <ul>
49        <li><a href="#headers">Headers</a> </li>
50        <li><a href="#std">Standard containers</a> </li>
51        <li>Functions <a href="#list_of_ref"><code>list_of()</code> and <code>map_list_of()</code></a></li>
52        <li>Functions <a href="#repeat_ref"><code>repeat()</code> and <code>repeat_fun()</code> </a> 
53        <li>Class <a href="#list_inserter"><code>list_inserter</code></a></li>
54        <li>Function <a href="#make_list_inserter"><code>make_list_inserter()</code></a></li>
55        <li><a href="#limit"> Customizing</a> argument list sizes</li>   
56     </ul>
57    <li> <a href="#exceptions">Exceptions and exception-safety </a></li>
58    <li> <a href="#extensions">Extending the library</a>           
59    <li> <a href="#boost_libs">Supported libraries </a>       
60    <li> <a href="#examples">Examples</a></li> <ul></ul>
61    <li><a href="#portability">Portability</a></li>
62    <li><a href="#history">History and Acknowledgment</a>   
63    <li><a href="#ref">References</a></li>
64  </ul>
65  <hr>
66
67 
68 
69<h2><a name="intro">Introduction</a></h2> <p> <i>There appear to be few
70practical uses of <code>operator,()</code></i>.  <!-- p.  247 --> <br><b>Bjarne
71Stroustrup</b>, The Design and Evolution of C++ </p> <p> The purpose of this
72library is to make it easy to fill containers with data by overloading
73<code>operator,()</code> and <code>operator()()</code>.  These two operators
74make it possible to construct lists of values that are then copied into a
75container: </p> <ul> <li> A comma-separated list: <p> 
76       <!--  vector< int > v; v += 1,2,3,4,5,6,7,8,9; -->
77 
78<pre><span 
79class=identifier>vector</span><span class=special><</span><span 
80class=keyword>int</span><span class=special>></span><span 
81class=identifier> v</span><span class=special>; </span>
82<span class=identifier>v </span><span class=special>+= </span><span 
83class=number>1</span><span
84class=special>,</span><span class=number>2</span><span 
85class=special>,</span><span class=number>3</span><span 
86class=special>,</span><span class=number>4</span><span 
87class=special>,</span><span class=number>5</span><span 
88class=special>,</span><span class=number>6</span><span 
89class=special>,</span><span class=number>7</span><span 
90class=special>,</span><span class=number>8</span><span 
91class=special>,</span><span class=number>9</span><span class=special>;</span></pre></p>
92       <li> A parenthesis-separated list:
93             <p>       
94             <pre>
95<span class=identifier>map</span><span class=special><</span><span 
96class=identifier>string</span><span class=special>,</span><span class=keyword>int</span><span class=special>> </span><span class=identifier>m</span><span class=special>; </span>
97<span class=identifier>insert</span><span class=special>( </span><span class=identifier>m </span><span class=special>)( </span><span class=string>&quot;Bar&quot;</span><span class=special>, </span><span class=number>1 </span><span class=special>)( </span><span class=string>&quot;Foo&quot;</span><span class=special>, </span><span class=number>2 </span><span class=special>);</span></pre> 
98    </ul> 
99<p>
100    These lists are particularly useful in
101    learning, testing, and prototyping situations, but can also be handy otherwise.
102      The library comes with predefined operators for the containers of the 
103      standard library, but most functionality will work with any standard
104compliant container. The library also makes it possible to extend user
105  defined types so for example a member function can be called for a list of
106values instead of its normal arguments. </p>
107   <hr>
108   
109   <a name="tutorial"></a>
110   <h2>Tutorial</h2>
111   <p>
112   Within two minutes you should be able to use this library. The main
113components are explained in these sections:
114   <ul>
115        <li>Function <a href="#operator+="><code>operator+=()</code></a>
116        <li>Function <a href="#operator()"><code>operator()()</code></a>
117        <li>Function <a href="#list_of"><code>list_of()</code></a>   
118        <li>Function <a href="#map_list_of"><code>map_list_of()</code></a> 
119        <li>Function <a href="#tuple_list_of"><code>tuple_list_of()</code></a>   
120        <li>Functions <a href="#repeat"><code>repeat()</code> and <code>repeat_fun()</code> </a> 
121        <li>Functions <a href="#ref_list_of"><code>ref_list_of()</code> and <code>cref_list_of()</code></a>
122        <li>A <a href="#complicated">"complicated"</a> example   
123        <li>Functions <a href="#ptr_push_back"><code>ptr_push_back(), ptr_push_front()</code> and <code>ptr_insert()</code></a>
124        <li>Function <a href="#ptr_list_of"><code>ptr_list_of()</code></a>         
125           
126   </ul>
127   The two first functions are used for adding elements after a container object
128   has been created whereas the next two is used when we need to initialize an
129   object. </p>
130   <h3>Function <code>operator+=()</code><a name="operator+="></h3>
131   <p>
132    To fill a vector (or any standard container) with values using
133    <code>operator+=()</code> you write   
134    <blockquote><pre>
135<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>std</span><span class=special>/</span><span class=identifier>vector</span><span class=special>.</span><span class=identifier>hpp</span><span class=special>&gt; </span><span class=comment>// for 'operator+=()'
136</span><span class=preprocessor>#include </span><span class=special>&lt;</span><span class=identifier>boost</span><span class=special>/</span><span class=identifier>assert</span><span class=special>.</span><span class=identifier>hpp</span><span class=special>&gt;;
137</span><span class=keyword>using </span><span class=keyword>namespace </span><span class=identifier>std</span><span class=special>;
138</span><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><span class=comment>// bring 'operator+=()' into scope
139</span><span class=special>
140</span><span class=special>{
141    </span><span class=identifier>vector</span><span class=special>&lt;</span><span class=keyword>int</span><span class=special>&gt; </span><span class=identifier>values</span><span class=special>; 
142    </span><span class=identifier>values </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><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=comment>// insert values at the end of the container
143    </span><span class=identifier>BOOST_ASSERT</span><span class=special>( </span><span class=identifier>values</span><span class=special>.</span><span class=identifier>size</span><span class=special>() </span><span class=special>== </span><span class=number>9 </span><span class=special>);
144    </span><span class=identifier>BOOST_ASSERT</span><span class=special>( </span><span class=identifier>values</span><span class=special>[</span><span class=number>0</span><span class=special>] </span><span class=special>== </span><span class=number>1 </span><span class=special>);
145    </span><span class=identifier>BOOST_ASSERT</span><span class=special>( </span><span class=identifier>values</span><span class=special>[</span><span class=number>8</span><span class=special>] </span><span class=special>== </span><span class=number>9 </span><span class=special>);
146</span><span class=special>}</span></pre></blockquote>
147
148    Here we only stuffed constants into the container, but the list can
149    consists of arbitrary expressions as long as the result of each 
150expression is convertible to the <code>value_type</code> of the container.
151   </p> 
152   
153   
154   <h3>Function <code>operator()()</code> <a name="operator()"></h3>
155   <p>
156   We do not call <code>operator()()</code> directly, but instead we call a
157   function that returns a proxy-object that defines <code>operator()()</code>.
158   The function that returns the proxy object is always named after the member
159   function that is used to copy the values in the list into the container.
160   So to fill a map with pairs of values you write
161   <blockquote><pre>
162<span class=preprocessor>#include </span><span class=special>&lt;</span><span 
163class=identifier>boost</span><span class=special>/</span><span 
164class=identifier>assign</span><span class=special>/</span><span 
165class=identifier>list_inserter</span><span class=special>.</span><span 
166class=identifier>hpp</span><span class=special>&gt; </span><span class=comment>// for 'insert()'
167</span><span class=preprocessor>#include </span><span class=special>&lt;</span><span class=identifier>boost</span><span class=special>/</span><span class=identifier>assert</span><span class=special>.</span><span class=identifier>hpp</span><span class=special>&gt; 
168</span><span class=preprocessor>#include </span><span class=special>&lt;</span><span class=identifier>string</span><span class=special>&gt;
169</span><span class=keyword>using </span><span class=keyword>namespace </span><span class=identifier>std</span><span class=special>;
170</span><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><span class=comment>// bring 'insert()' into scope
171</span><span class=special> 
172</span><span class=special>{
173    </span><span class=identifier>map</span><span class=special>&lt;</span><span class=identifier>string</span><span class=special>,</span><span class=keyword>int</span><span class=special>&gt; </span><span class=identifier>months</span><span class=special>; 
174    </span><span class=identifier>insert</span><span class=special>( </span><span class=identifier>months </span><span class=special>)
175        </span><span class=special>( </span><span class=string>&quot;january&quot;</span><span class=special>,   </span><span class=number>31 </span><span class=special>)( </span><span class=string>&quot;february&quot;</span><span class=special>, </span><span class=number>28 </span><span class=special>)
176        </span><span class=special>( </span><span class=string>&quot;march&quot;</span><span class=special>,     </span><span class=number>31 </span><span class=special>)( </span><span class=string>&quot;april&quot;</span><span class=special>,    </span><span class=number>30 </span><span class=special>)
177        </span><span class=special>( </span><span class=string>&quot;may&quot;</span><span class=special>,       </span><span class=number>31 </span><span class=special>)( </span><span class=string>&quot;june&quot;</span><span class=special>,     </span><span class=number>30 </span><span class=special>)
178        </span><span class=special>( </span><span class=string>&quot;july&quot;</span><span class=special>,      </span><span class=number>31 </span><span class=special>)( </span><span class=string>&quot;august&quot;</span><span class=special>,   </span><span class=number>31 </span><span class=special>)
179        </span><span class=special>( </span><span class=string>&quot;september&quot;</span><span class=special>, </span><span class=number>30 </span><span class=special>)( </span><span class=string>&quot;october&quot;</span><span class=special>,  </span><span class=number>31 </span><span class=special>)
180        </span><span class=special>( </span><span class=string>&quot;november&quot;</span><span class=special>,  </span><span class=number>30 </span><span class=special>)( </span><span class=string>&quot;december&quot;</span><span class=special>, </span><span class=number>31 </span><span class=special>);
181    </span><span class=identifier>BOOST_ASSERT</span><span class=special>( </span><span class=identifier>months</span><span class=special>.</span><span 
182class=identifier>size</span><span class=special>() </span><span class=special>== </span><span class=number>12 </span><span class=special>);
183    </span><span class=identifier>BOOST_ASSERT</span><span class=special>( </span><span class=identifier>months</span><span class=special>[</span><span class=string>&quot;january&quot;</span><span class=special>] </span><span class=special>== </span><span class=number>31 </span><span class=special>);
184</span><span class=special>}</span> </pre></blockquote>
185
186   Note that <code>operator()()</code> is much more handy when
187   we need to construct objects using several arguments
188   (up to five arguments are supported by default, but the limit can be <a href="#limit">customized</a>).
189    This is also true for sequences:
190
191      <blockquote><pre>
192<span class=preprocessor>#include </span><span class=special>&lt;</span><span 
193class=identifier>boost</span><span class=special>/</span><span 
194class=identifier>assign</span><span class=special>/</span>list_inserter</span><span class=special>.</span><span class=identifier>hpp</span><span class=special>&gt; </span><span class=comment>// for 'push_front()'
195</span><span class=preprocessor>#include </span><span class=special>&lt;</span><span class=identifier>boost</span><span class=special>/</span><span class=identifier>assert</span><span class=special>.</span><span class=identifier>hpp</span><span class=special>&gt; 
196</span><span class=preprocessor>#include </span><span class=special>&lt;</span><span class=identifier>string</span><span class=special>&gt;
197</span><span class=preprocessor>#include </span><span class=special>&lt;</span><span class=identifier>utility</span><span class=special>&gt;
198</span><span class=keyword>using </span><span class=keyword>namespace </span><span class=identifier>std</span><span class=special>;
199</span><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><span class=comment>// bring 'push_front()' into scope
200</span><span class=special> 
201</span><span class=special>{
202    </span><span class=keyword>typedef </span><span class=identifier>pair</span><span class=special>&lt; </span><span class=identifier>string</span><span class=special>,</span><span class=identifier>string </span><span class=special>&gt; </span><span class=identifier>str_pair</span><span class=special>;
203    </span><span class=identifier>deque</span><span class=special>&lt;</span><span class=identifier>str_pair</span><span class=special>&gt; </span><span class=identifier>deq</span><span class=special>;
204    </span><span class=identifier>push_front</span><span class=special>( </span><span class=identifier>deq </span><span class=special>)( </span><span class=string>&quot;foo&quot;</span><span class=special>, </span><span class=string>&quot;bar&quot;</span><span class=special>)( </span><span class=string>&quot;boo&quot;</span><span class=special>, </span><span class=string>&quot;far&quot; </span><span class=special>);
205    </span><span class=identifier>BOOST_ASSERT</span><span class=special>( </span><span class=identifier>deq</span><span class=special>.</span><span class=identifier>size</span><span class=special>() </span><span class=special>== </span><span class=number>2 </span><span class=special>);
206    </span><span class=identifier>BOOST_ASSERT</span><span class=special>( </span><span class=identifier>deq</span><span class=special>.</span><span class=identifier>front</span><span class=special>().</span><span class=identifier>first </span><span class=special>== </span><span class=string>&quot;boo&quot; </span><span class=special>);
207    </span><span class=identifier>BOOST_ASSERT</span><span class=special>( </span><span class=identifier>deq</span><span class=special>.</span><span class=identifier>back</span><span class=special>().</span><span class=identifier>second </span><span class=special>== </span><span class=string>&quot;bar&quot; </span><span class=special>);
208</span><span class=special>}   </span></pre></blockquote>
209
210   Besides <code>push_front()</code> we could also have used
211   <code>push_back()</code> if the container has a corresponding member
212   function. Empty parentheses can be used to insert default-constructed
213objects, for example,
214<code>push_front( deq )()()</code> will insert two default-constructed
215<code>str_pair</code> objects. </p>   
216   
217   <p>
218   If <code>operator()()</code> is too cumbersome to use with eg.
219<code>push_front()</code>we can also say </p>
220
221<blockquote>
222    <pre>
223<span class=identifier>deque</span><span class=special>&lt;</span><span class=keyword>int</span><span class=special>&gt; </span><span class=identifier>di</span><span class=special>;    </span>
224<span class=identifier>push_front</span><span class=special>( </span><span class=identifier>di </span><span class=special>) </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><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>
225<span class=identifier>BOOST_ASSERT</span><span class=special>( </span><span class=identifier>di</span><span class=special>.</span><span class=identifier>size</span><span class=special>() </span><span class=special>== </span><span class=number>9 </span><span class=special>);    </span>
226<span class=identifier>BOOST_ASSERT</span><span class=special>( </span><span 
227class=identifier>di</span><span class=special>[</span><span class=number>0</span><span class=special>] </span><span class=special>== </span><span class=number>9 </span><span class=special>);    </span>
228</pre>
229</blockquote>
230<p>
231Just to make it perfectly clear, the code above is not restricted to the
232standard containers, but will work with all <i>standard compliant</i> containers
233with the right member function. It is only <code>operator+=()</code> that has been restricted to
234the standard containers. </p>
235 
236  <h3>Function <code>list_of()</code> <a name="list_of"></h3>
237  But what if we need to <i>initialize</i> a container? This is where
238  <code>list_of()</code> comes into play. With <code>list_of()</code>
239  we can create anonymous lists that automatically converts to
240  any container:
241  <blockquote><pre>
242<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>list_of</span><span class=special>.</span><span class=identifier>hpp</span><span class=special>&gt; </span><span class=comment>// for 'list_of()'
243</span><span class=preprocessor>#include </span><span class=special>&lt;</span><span class=identifier>boost</span><span class=special>/</span><span class=identifier>assert</span><span class=special>.</span><span class=identifier>hpp</span><span class=special>&gt; 
244</span><span class=preprocessor>#include </span><span class=special>&lt;</span><span class=identifier>list</span><span class=special>&gt;
245</span><span class=preprocessor>#include </span><span class=special>&lt;</span><span class=identifier>stack</span><span class=special>&gt;
246</span><span class=preprocessor>#include </span><span class=special>&lt;</span><span class=identifier>string</span><span class=special>&gt;
247</span><span class=keyword>using </span><span class=keyword>namespace </span><span class=identifier>std</span><span class=special>;
248</span><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><span class=comment>// bring 'list_of()' into scope
249</span><span class=special> 
250</span><span class=special>{
251    </span><span class=keyword>const </span><span class=identifier>list</span><span class=special>&lt;</span><span class=keyword>int</span><span class=special>&gt; </span><span class=identifier>primes </span><span class=special>= </span><span class=identifier>list_of</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>5</span><span class=special>)(</span><span class=number>7</span><span class=special>)(</span><span class=number>11</span><span class=special>);
252    </span><span class=identifier>BOOST_ASSERT</span><span class=special>( </span><span class=identifier>primes</span><span class=special>.</span><span class=identifier>size</span><span class=special>() </span><span class=special>== </span><span class=number>6 </span><span class=special>);
253    </span><span class=identifier>BOOST_ASSERT</span><span class=special>( </span><span class=identifier>primes</span><span class=special>.</span><span class=identifier>back</span><span class=special>() </span><span class=special>== </span><span class=number>11 </span><span class=special>);
254    </span><span class=identifier>BOOST_ASSERT</span><span class=special>( </span><span class=identifier>primes</span><span class=special>.</span><span class=identifier>front</span><span class=special>() </span><span class=special>== </span><span class=number>1 </span><span class=special>);
255   
256    </span><span class=keyword>const </span><span 
257class=identifier>stack</span><span class=special>&lt;</span><span 
258class=identifier>string</span><span class=special>&gt; </span><span 
259class=identifier>names </span><span class=special>= </span><span 
260class=special></span><span class=identifier>list_of</span><span class=special>( </span><span class=string>&quot;Mr. Foo&quot; </span><span class=special>)( </span><span class=string>&quot;Mr. Bar&quot;</span><span class=special>)( </span><span class=string>&quot;Mrs. FooBar&quot; </span><span
261class=special>).</span><span class=identifier>to_adapter();
262    </span><span class=keyword>const </span><span 
263class=identifier>stack</span><span class=special>&lt;</span><span 
264class=identifier>string</span><span class=special>&gt; </span><span 
265class=identifier>names2 </span><span class=special>= </span><span 
266class=special>(</span><span class=identifier>list_of</span><span class=special>( </span><span class=string>&quot;Mr. Foo&quot; </span><span class=special>), </span><span class=string>&quot;Mr. Bar&quot;</span><span class=special>, </span><span class=string>&quot;Mrs. FooBar&quot; </span><span
267class=special>).</span><span class=identifier>to_adapter();
268    </span><span class=identifier>BOOST_ASSERT</span><span class=special>( </span><span class=identifier>names</span><span class=special>.</span><span class=identifier>size</span><span class=special>() </span><span class=special>== </span><span class=number>3 </span><span class=special>);
269    </span><span class=identifier>BOOST_ASSERT</span><span class=special>( </span><span class=identifier>names</span><span class=special>.</span><span class=identifier>top</span><span class=special>()</span><span class=special> == </span><span class=string>&quot;Mrs. FooBar&quot; </span><span class=special>);
270</span><span class=special>}   </span></pre></blockquote>
271  If we need to initialize a container adapter, we need to help the compiler a
272little by calling <code>to_adapter()</code>. As the second example also shows,
273we can use a comma-separated
274list with <code>list_of()</code> if we add parenthesis around the
275  entire right hand side. It is worth noticing that the first argument
276  of <code>list_of()</code> determines the type of the anonymous list.
277  In case of the stack, the anonymous list consists of
278  <code>const char*</code> objects which are then converted to
279  a stack of <code>string</code> objects. The conversion is always 
280  possible as long as the conversion between the stored types is possible.
281 </p>
282 <p>
283 Please notice that <code>list_of()</code> can even convert to a
284 <code>boost::<a 
285href="../../array/index.html">array</a>&lt;T,sz></code> and see also the list
286of <a href="#boost_libs">supported libraries </a>.
287 
288 <h3>Function <code>map_list_of()</code> <a name="map_list_of"></h3>
289 This function is defined for pure convenience when working with
290 maps. Its usage is simple:
291 <blockquote><pre>
292<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>list_of</span><span class=special>.</span><span class=identifier>hpp</span><span class=special>&gt; </span><span class=comment>// for 'map_list_of()'
293</span><span class=preprocessor>#include </span><span class=special>&lt;</span><span class=identifier>boost</span><span class=special>/</span><span class=identifier>assert</span><span class=special>.</span><span class=identifier>hpp</span><span class=special>&gt; 
294</span><span class=preprocessor>#include </span><span class=special>&lt;</span><span class=identifier>map</span><span class=special>&gt;
295</span><span class=keyword>using </span><span class=keyword>namespace </span><span class=identifier>std</span><span class=special>;
296</span><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><span class=comment>// bring 'map_list_of()' into scope
297</span><span class=special> 
298</span><span class=special>{
299    </span><span class=identifier>map</span><span class=special>&lt;</span><span class=keyword>int</span><span class=special>,</span><span class=keyword>int</span><span class=special>&gt; </span><span class=identifier>next </span><span class=special>= </span><span class=identifier>map_list_of</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>2</span><span class=special>,</span><span class=number>3</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>4</span><span class=special>,</span><span class=number>5</span><span class=special>)(</span><span class=number>5</span><span class=special>,</span><span class=number>6</span><span class=special>);
300    </span><span class=identifier>BOOST_ASSERT</span><span class=special>( </span><span class=identifier>next</span><span class=special>.</span><span class=identifier>size</span><span class=special>() </span><span class=special>== </span><span class=number>5 </span><span class=special>);
301    </span><span class=identifier>BOOST_ASSERT</span><span class=special>( </span><span class=identifier>next</span><span class=special>[ </span><span class=number>1 </span><span class=special>] </span><span class=special>== </span><span class=number>2 </span><span class=special>);
302    </span><span class=identifier>BOOST_ASSERT</span><span class=special>( </span><span class=identifier>next</span><span class=special>[ </span><span class=number>5 </span><span class=special>] </span><span class=special>== </span><span class=number>6 </span><span class=special>);
303   
304    </span><span class=comment>// or we can use 'list_of()' by specifying what type
305    // the list consists of
306    </span><span class=identifier>next </span><span class=special>= </span><span class=identifier>list_of</span><span class=special>&lt; </span><span class=identifier>pair</span><span class=special>&lt;</span><span class=keyword>int</span><span class=special>,</span><span class=keyword>int</span><span class=special>&gt; </span><span class=special>&gt;(</span><span class=number>6</span><span class=special>,</span><span class=number>7</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>8</span><span class=special>,</span><span class=number>9</span><span class=special>);
307    </span><span class=identifier>BOOST_ASSERT</span><span class=special>( </span><span class=identifier>next</span><span class=special>.</span><span class=identifier>size</span><span class=special>() </span><span class=special>== </span><span class=number>3 </span><span class=special>);
308    </span><span class=identifier>BOOST_ASSERT</span><span class=special>( </span><span class=identifier>next</span><span class=special>[ </span><span class=number>6 </span><span class=special>] </span><span class=special>== </span><span class=number>7 </span><span class=special>);
309    </span><span class=identifier>BOOST_ASSERT</span><span class=special>( </span><span class=identifier>next</span><span class=special>[ </span><span class=number>8 </span><span class=special>] </span><span class=special>== </span><span class=number>9 </span><span class=special>);     
310</span><span class=special>}   </span></pre></blockquote>
311
312The function <code>pair_list_of()</code> may also be used.
313
314<h3>Function <code>tuple_list_of()</code> <a name="tuple_list_of"></h3>
315
316If you are working with tuples, it might be convenient to use
317<code>tuple_list_of()</code>:
318
319
320<blockquote>
321    <pre>
322<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>list_of</span><span class=special>.</span><span class=identifier>hpp</span><span class=special>&gt;</span>
323<span class=preprocessor>#include </span><span class=special>&lt;</span><span class=identifier>vector</span><span class=special>&gt;
324</span>
325<span class=keyword>using </span><span class=keyword>namespace </span><span class=identifier>std</span><span class=special>;</span>
326<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>;
327</span>
328<span class=special>{
329    </span><span class=keyword>typedef </span><span class=identifier>boost</span><span class=special>::</span><span class=identifier>tuple</span><span class=special>&lt;</span><span class=keyword>int</span><span class=special>,</span><span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span><span class=special>,</span><span class=keyword>int</span><span class=special>&gt; </span><span class=identifier>tuple</span><span class=special>;
330
331    </span><span class=identifier>vector</span><span class=special>&lt;</span><span class=identifier>tuple</span><span class=special>&gt; </span><span class=identifier>v </span><span class=special>= </span><span class=identifier>tuple_list_of</span><span class=special>( </span><span class=number>1</span><span class=special>, </span><span class=string>&quot;foo&quot;</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=string>&quot;bar&quot;</span><span class=special>, </span><span class=number>4 </span><span class=special>);
332    </span><span class=identifier>BOOST_CHECK</span><span class=special>( </span><span class=identifier>v</span><span class=special>.</span><span class=identifier>size</span><span class=special>() </span><span class=special>== </span><span class=number>2 </span><span class=special>);
333    </span><span class=identifier>BOOST_CHECK</span><span class=special>( </span><span class=identifier>boost</span><span class=special>::</span><span class=identifier>get</span><span class=special>&lt;</span><span class=number>0</span><span class=special>&gt;( </span><span class=identifier>v</span><span class=special>[</span><span class=number>1</span><span class=special>] </span><span class=special>) </span><span class=special>==  </span><span class=number>3 </span><span class=special>);</span>
334<span class=special>}</span>
335    </pre>
336</blockquote>
337
338<h3>Functions <code>repeat()</code> and <code>repeat_fun()</code> <a name="repeat"></h3> 
339<p>
340Sometimes it is too irritating to repeat the same value many times. This is
341where <code>repeat()</code> can be handy:
342<blockquote>
343    <pre>
344<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>list_of</span><span class=special>.</span><span class=identifier>hpp</span><span class=special>&gt;</span>
345<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>std</span><span class=special>/</span><span class=identifier>vector</span><span class=special>.</span><span class=identifier>hpp</span><span class=special>&gt;</span>
346<span class=preprocessor>#include </span><span class=special>&lt;</span><span class=identifier>boost</span><span class=special>/</span><span class=identifier>assert</span><span class=special>.</span><span class=identifier>hpp</span><span class=special>&gt;
347</span>
348<span class=keyword>using </span><span class=keyword>namespace </span><span class=identifier>std</span><span class=special>;</span>
349<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>
350<span class=special> </span>
351<span class=special>{
352    </span><span class=identifier>vector</span><span class=special>&lt;</span><span class=keyword>int</span><span class=special>&gt; </span><span class=identifier>v</span><span class=special>;
353    </span><span class=identifier>v </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=identifier>repeat</span><span class=special>(</span><span class=number>10</span><span class=special>,</span><span class=number>4</span><span class=special>),</span><span class=number>5</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>;
354    </span><span class=comment>// v = [1,2,3,4,4,4,4,4,4,4,4,4,4,5,6,7,8,9]
355    </span><span class=identifier>BOOST_ASSERT</span><span class=special>( </span><span class=identifier>v</span><span class=special>.</span><span class=identifier>size</span><span class=special>() </span><span class=special>== </span><span class=number>3 </span><span class=special>+ </span><span class=number>10 </span><span class=special>+ </span><span class=number>5 </span><span class=special>);
356   
357    </span><span class=identifier>v </span><span class=special>= </span><span class=identifier>list_of</span><span class=special>(</span><span class=number>1</span><span class=special>).</span><span class=identifier>repeat</span><span class=special>(</span><span class=number>5</span><span class=special>,</span><span class=number>2</span><span class=special>)(</span><span class=number>3</span><span class=special>);
358    </span><span class=comment>// v = [1,2,2,2,2,2,3]
359    </span><span class=identifier>BOOST_ASSERT</span><span class=special>( </span><span class=identifier>v</span><span class=special>.</span><span class=identifier>size</span><span class=special>() </span><span class=special>== </span><span class=number>1 </span><span class=special>+ </span><span class=number>5 </span><span class=special>+ </span><span class=number>1 </span><span class=special>);
360   
361    </span><span class=identifier>push_back</span><span class=special>( </span><span class=identifier>v </span><span class=special>)(</span><span class=number>1</span><span class=special>).</span><span class=identifier>repeat</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>);
362    </span><span class=comment>// v = old v + [1,2,3]
363    </span><span class=identifier>BOOST_ASSERT</span><span class=special>( </span><span class=identifier>v</span><span class=special>.</span><span class=identifier>size</span><span class=special>() </span><span class=special>== </span><span class=number>10 </span><span class=special>);</span>
364<span class=special>}</span></pre>
365</blockquote>
366As we can see, then the first argument to <code>repeat()</code> is the number
367of times to repeat the second argument.
368</p>
369<p>
370A more general list can be constructed with <code>repeat_fun()</code>:
371
372<blockquote>
373    <pre>
374<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>std</span><span class=special>/</span><span class=identifier>vector</span><span class=special>.</span><span class=identifier>hpp</span><span class=special>&gt;</span>
375<span class=preprocessor>#include </span><span class=special>&lt;</span><span class=identifier>boost</span><span class=special>/</span><span class=identifier>assert</span><span class=special>.</span><span class=identifier>hpp</span><span class=special>&gt;</span>
376<span class=preprocessor>#include </span><span class=special>&lt;</span><span class=identifier>cstdlib</span><span class=special>&gt; </span><span class=comment>// for 'rand()'             
377</span>
378<span class=keyword>using </span><span class=keyword>namespace </span><span class=identifier>std</span><span class=special>;</span>
379<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>
380<span class=special> </span>
381<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>
382<span class=keyword>struct </span><span class=identifier>next    </span>
383<span class=special>{
384    </span><span class=identifier>T </span><span class=identifier>seed</span><span class=special>;
385    </span><span class=identifier>next</span><span class=special>( </span><span class=identifier>T </span><span class=identifier>seed </span><span class=special>) </span><span class=special>: </span><span class=identifier>seed</span><span class=special>(</span><span class=identifier>seed</span><span class=special>)
386    </span><span class=special>{ </span><span class=special>}
387   
388    </span><span class=identifier>T </span><span class=keyword>operator</span><span class=special>()() </span><span class=keyword>
389    </span><span class=special>{
390        </span><span class=keyword>return </span><span class=identifier>seed</span><span class=special>++;
391    </span><span class=special>}</span>
392<span class=special>};</span>
393<span class=special>     </span>
394<span class=special>{
395    </span><span class=identifier>vector</span><span class=special>&lt;</span><span class=keyword>int</span><span class=special>&gt; </span><span class=identifier>v</span><span class=special>;
396    </span><span class=identifier>v </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=identifier>repeat_fun</span><span class=special>(</span><span class=number>4</span><span class=special>,&amp;</span><span class=identifier>rand</span><span class=special>),</span><span class=number>4</span><span class=special>;
397    </span><span class=comment>// v = [1,2,?,?,?,?,4]
398    </span><span class=identifier>BOOST_ASSERT</span><span class=special>( </span><span class=identifier>v</span><span class=special>.</span><span class=identifier>size</span><span class=special>() </span><span class=special>== </span><span class=number>7 </span><span class=special>);
399   
400    </span><span class=identifier>push_back</span><span class=special>( </span><span class=identifier>v </span><span class=special>).</span><span class=identifier>repeat_fun</span><span class=special>(</span><span class=number>4</span><span class=special>,</span><span class=identifier>next</span><span class=special>&lt;</span><span class=keyword>int</span><span class=special>&gt;(</span><span class=number>0</span><span class=special>))(</span><span class=number>4</span><span class=special>).</span><span class=identifier>repeat_fun</span><span class=special>(</span><span class=number>4</span><span class=special>,</span><span class=identifier>next</span><span class=special>&lt;</span><span class=keyword>int</span><span class=special>&gt;(</span><span class=number>5</span><span class=special>));
401    </span><span class=comment>// v = old v + [0,1,2,3,4,5,6,7,8]
402    </span><span class=identifier>BOOST_ASSERT</span><span class=special>( </span><span class=identifier>v</span><span class=special>.</span><span class=identifier>size</span><span class=special>() </span><span class=special>== </span><span class=number>16 </span><span class=special>);</span>
403<span class=special>}</span>        </pre>
404</blockquote>
405The only requirement of the second argument to <code>repeat_fun()</code> is that
406it is a nullary function. </p>
407
408<h3>Functions <code>ref_list_of()</code> and <code>cref_list_of()</code> <a name="ref_list_of"></h3>
409
410When you need to create an anonymous range of values and speed is essential,
411these two functions provide what you want. <blockquote>
412    <pre>
413<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>list_of</span><span class=special>.</span><span class=identifier>hpp</span><span class=special>&gt;</span>
414<span class=preprocessor>#include </span><span class=special>&lt;</span><span class=identifier>algorithm</span><span class=special>&gt;
415</span>
416<span class=comment>//
417// Define Range algorithm
418//</span>
419<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>
420<span class=keyword>typename </span><span class=identifier>Range</span><span class=special>::</span><span class=identifier>const_iterator </span><span class=identifier>max_element</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>)</span>
421<span class=special>{
422    </span><span class=keyword>return </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>max_element</span><span class=special>( </span><span class=identifier>r</span><span class=special>.</span><span class=identifier>begin</span><span class=special>(), </span><span class=identifier>r</span><span class=special>.</span><span class=identifier>end</span><span class=special>() </span><span class=special>);</span>
423<span class=special>}
424</span>
425<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>;
426</span>
427<span class=special>{
428    </span><span class=keyword>int </span><span class=identifier>a</span><span class=special>=</span><span class=number>1</span><span class=special>,</span><span class=identifier>b</span><span class=special>=</span><span class=number>5</span><span class=special>,</span><span class=identifier>c</span><span class=special>=</span><span class=number>3</span><span class=special>,</span><span class=identifier>d</span><span class=special>=</span><span class=number>4</span><span class=special>,</span><span class=identifier>e</span><span class=special>=</span><span class=number>2</span><span class=special>,</span><span class=identifier>f</span><span class=special>=</span><span class=number>9</span><span class=special>,</span><span class=identifier>g</span><span class=special>=</span><span class=number>0</span><span class=special>,</span><span class=identifier>h</span><span class=special>=</span><span class=number>7</span><span class=special>;
429    </span><span class=keyword>int</span><span class=special>&amp; </span><span class=identifier>max </span><span class=special>= </span><span class=special>*</span><span class=identifier>max_element</span><span class=special>( </span><span class=identifier>ref_list_of</span><span class=special>&lt;</span><span class=number>8</span><span class=special>&gt;(</span><span class=identifier>a</span><span class=special>)(</span><span class=identifier>b</span><span class=special>)(</span><span class=identifier>c</span><span class=special>)(</span><span class=identifier>d</span><span class=special>)(</span><span class=identifier>e</span><span class=special>)(</span><span class=identifier>f</span><span class=special>)(</span><span class=identifier>g</span><span class=special>)(</span><span class=identifier>h</span><span class=special>) </span><span class=special>);
430    </span><span class=identifier>BOOST_CHECK_EQUAL</span><span class=special>( </span><span class=identifier>max</span><span class=special>, </span><span class=identifier>f </span><span class=special>);
431    </span><span class=identifier>max </span><span class=special>= </span><span class=number>8</span><span class=special>;
432    </span><span class=identifier>BOOST_CHECK_EQUAL</span><span class=special>( </span><span class=identifier>f</span><span class=special>, </span><span class=number>8 </span><span class=special>);
433    </span><span class=keyword>const </span><span class=keyword>int</span><span 
434class=special>&amp; </span><span class=identifier>const_max </span><span class=special>= </span><span class=special>*</span><span class=identifier>max_element</span><span class=special>(</span><span class=identifier>cref_list_of</span><span class=special>&lt;</span><span class=number>8</span><span class=special>&gt;(</span><span class=identifier>a</span><span class=special>)(</span><span class=identifier>b</span><span class=special>)(</span><span class=identifier>c</span><span class=special>)(</span><span class=identifier>d</span><span class=special>)(</span><span class=identifier>e</span><span class=special>)(</span><span class=identifier>f</span><span class=special>)(</span><span class=identifier>g</span><span class=special>)(</span><span class=identifier>h</span><span class=special>) </span><span class=special>);
435    </span><span class=identifier>BOOST_CHECK_EQUAL</span><span class=special>( </span><span class=identifier>max</span><span class=special>, </span><span class=identifier>const_max </span><span class=special>);</span>
436<span class=special>}</span>
437    </pre>
438</blockquote>
439
440You can only use lvalues with <code>ref_list_of()</code> while
441<code>cref_list_of()</code> accepts rvalues too. Do not worry about not
442specifying exactly the right size; the extra space used is minimal and there
443is no runtime overhead associated with it.
444
445You may also use these functions instead of <code>list_of()</code> if speed is
446essential.
447
448<h3>A "complicated" example <a name="complicated"></h3>
449<p> 
450As a last example, let us assume that we need to keep track of the
451result of soccer matches. A team will get one point if it wins
452and zero otherwise. If there has been played three games in each group, the code might look
453like this:
454
455<blockquote>
456    <pre>
457<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>list_of</span><span class=special>.</span><span class=identifier>hpp</span><span class=special>&gt;</span>
458<span class=preprocessor>#include </span><span class=special>&lt;</span><span 
459class=identifier>boost</span><span class=special>/</span><span 
460class=identifier>assign</span><span class=special>/</span><span 
461class=identifier>list_inserter</span><span class=special>.</span><span 
462class=identifier>hpp</span><span class=special>&gt;</span>
463<span class=preprocessor>#include </span><span class=special>&lt;</span><span class=identifier>boost</span><span class=special>/</span><span class=identifier>assert</span><span class=special>.</span><span class=identifier>hpp</span><span class=special>&gt;</span>
464<span class=preprocessor>#include </span><span class=special>&lt;</span><span class=identifier>string</span><span class=special>&gt;</span>
465<span class=preprocessor>#include </span><span class=special>&lt;</span><span class=identifier>vector</span><span class=special>&gt;
466</span>
467<span class=keyword>using </span><span class=keyword>namespace </span><span class=identifier>std</span><span class=special>;</span>
468<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>;
469 </span>
470<span class=special>{
471    </span><span class=keyword>typedef </span><span class=identifier>vector</span><span class=special>&lt;</span><span class=keyword>int</span><span class=special>&gt;                   </span><span class=identifier>score_type</span><span class=special>;
472    </span><span class=keyword>typedef </span><span class=identifier>map</span><span class=special>&lt;</span><span class=identifier>string</span><span class=special>,</span><span class=identifier>score_type</span><span class=special>&gt;        </span><span class=identifier>team_score_map</span><span class=special>;
473    </span><span class=keyword>typedef </span><span class=identifier>pair</span><span class=special>&lt;</span><span class=identifier>string</span><span class=special>,</span><span class=identifier>score_type</span><span class=special>&gt;       </span><span class=identifier>score_pair</span><span class=special>;
474
475    </span><span class=identifier>team_score_map </span><span class=identifier>group1</span><span class=special>, </span><span class=identifier>group2</span><span class=special>;
476   
477    </span><span class=comment>//
478    // method 1: using 'insert()'
479    //
480    </span><span class=identifier>insert</span><span class=special>( </span><span class=identifier>group1 </span><span class=special>)( </span><span class=string>&quot;Denmark&quot;</span><span class=special>, </span><span class=identifier>list_of</span><span class=special>(</span><span class=number>1</span><span class=special>)(</span><span class=number>1</span><span class=special>) </span><span class=special>)
481                    </span><span class=special>( </span><span class=string>&quot;Germany&quot;</span><span class=special>, </span><span class=identifier>list_of</span><span class=special>(</span><span class=number>0</span><span class=special>)(</span><span class=number>0</span><span class=special>) </span><span class=special>)
482                    </span><span class=special>( </span><span class=string>&quot;England&quot;</span><span class=special>, </span><span class=identifier>list_of</span><span class=special>(</span><span class=number>0</span><span class=special>)(</span><span class=number>1</span><span class=special>) </span><span class=special>);
483    </span><span class=identifier>BOOST_ASSERT</span><span class=special>( </span><span class=identifier>group1</span><span class=special>.</span><span class=identifier>size</span><span class=special>() </span><span class=special>== </span><span class=number>3 </span><span class=special>);
484    </span><span class=identifier>BOOST_ASSERT</span><span class=special>( </span><span class=identifier>group1</span><span class=special>[ </span><span class=string>&quot;Denmark&quot; </span><span class=special>][</span><span class=number>1</span><span class=special>] </span><span class=special>== </span><span class=number>1 </span><span class=special>);
485    </span><span class=identifier>BOOST_ASSERT</span><span class=special>( </span><span class=identifier>group1</span><span class=special>[ </span><span class=string>&quot;Germany&quot; </span><span class=special>][</span><span class=number>0</span><span class=special>] </span><span class=special>== </span><span class=number>0 </span><span class=special>);
486   
487    </span><span class=comment>//
488    // method 2: using 'list_of()'
489    //
490    </span><span class=identifier>group2 </span><span class=special>= </span><span class=identifier>list_of</span><span class=special>&lt; </span><span class=identifier>score_pair </span><span class=special>&gt;
491                        </span><span class=special>( </span><span class=string>&quot;Norway&quot;</span><span class=special>,  </span><span class=identifier>list_of</span><span class=special>(</span><span class=number>1</span><span class=special>)(</span><span class=number>0</span><span class=special>) </span><span class=special>)
492                        </span><span class=special>( </span><span class=string>&quot;USA&quot;</span><span class=special>,     </span><span class=identifier>list_of</span><span class=special>(</span><span class=number>0</span><span class=special>)(</span><span class=number>0</span><span class=special>) </span><span class=special>)
493                        </span><span class=special>( </span><span class=string>&quot;Andorra&quot;</span><span class=special>, </span><span class=identifier>list_of</span><span class=special>(</span><span class=number>1</span><span class=special>)(</span><span class=number>1</span><span class=special>) </span><span class=special>);
494    </span><span class=identifier>BOOST_ASSERT</span><span class=special>( </span><span class=identifier>group2</span><span class=special>.</span><span class=identifier>size</span><span class=special>() </span><span class=special>== </span><span class=number>3 </span><span class=special>);
495    </span><span class=identifier>BOOST_ASSERT</span><span class=special>( </span><span class=identifier>group2</span><span class=special>[ </span><span class=string>&quot;Norway&quot; </span><span class=special>][</span><span class=number>0</span><span class=special>] </span><span class=special>== </span><span class=number>1 </span><span class=special>);
496    </span><span class=identifier>BOOST_ASSERT</span><span class=special>( </span><span class=identifier>group2</span><span class=special>[ </span><span class=string>&quot;USA&quot; </span><span class=special>][</span><span class=number>0</span><span class=special>] </span><span class=special>== </span><span class=number>0 </span><span class=special>);</span>
497<span class=special>}</span>
498    </pre>
499</blockquote>
500
501In the first example, notice how the result of <code>list_of()</code>
502can be converted automatically to a <code>vector&lt;int></code> because
503<code>insert()</code> knows it expects a <code>vector&lt;int></code>.
504In the second example we can see that <code>list_of()</code> is somewhat
505less intelligent since here it needs to be told explicitly what arguments to
506expect. (In the future it might be possible to introduce a more intelligent
507conversion layer in <code>list_of()</code>.)
508</p>
509
510<h3>Functions <code>ptr_push_back(),
511ptr_push_front()</code> and <code>ptr_insert()</code> <a name="ptr_push_back"></h3>
512
513For use with <a href="../../ptr_container/index.html">Boost.Pointer Container</a>
514a few special exception-safe functions are provided. Using these function you
515do not need to call <code>new</code> manually:
516
517
518<blockquote>
519    <pre>
520<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>ptr_list_inserter</span><span class=special>.</span><span class=identifier>hpp</span><span class=special>&gt;</span>
521<span class=preprocessor>#include </span><span class=special>&lt;</span><span class=identifier>boost</span><span class=special>/</span><span class=identifier>ptr_container</span><span class=special>/</span><span class=identifier>ptr_deque</span><span class=special>.</span><span class=identifier>hpp</span><span class=special>&gt;</span>
522<span class=preprocessor>#include </span><span class=special>&lt;</span><span class=identifier>boost</span><span class=special>/</span><span class=identifier>ptr_container</span><span class=special>/</span><span class=identifier>ptr_set</span><span class=special>.</span><span class=identifier>hpp</span><span class=special>&gt;
523</span>
524<span class=comment>//
525// Example class
526//</span>
527<span class=keyword>struct </span><span class=identifier>Foo</span>
528<span class=special>{
529    </span><span class=keyword>int </span><span class=identifier>i</span><span class=special>;
530   
531    </span><span class=identifier>Foo</span><span class=special>() </span><span class=special>: </span><span class=identifier>i</span><span class=special>(</span><span class=number>0</span><span class=special>)
532    </span><span class=special>{ </span><span class=special>}
533    </span><span class=identifier>Foo</span><span class=special>( </span><span class=keyword>int </span><span class=identifier>i </span><span class=special>) </span><span class=special>: </span><span class=identifier>i</span><span class=special>(</span><span class=identifier>i</span><span class=special>)
534    </span><span class=special>{ </span><span class=special>}
535    </span><span class=identifier>Foo</span><span class=special>( </span><span class=keyword>int </span><span class=identifier>i</span><span class=special>, </span><span class=keyword>int </span><span class=special>) </span><span class=special>: </span><span class=identifier>i</span><span class=special>(</span><span class=identifier>i</span><span class=special>)
536    </span><span class=special>{ </span><span class=special>}
537    </span><span class=identifier>Foo</span><span class=special>( </span><span class=keyword>const </span><span class=keyword>char</span><span class=special>*, </span><span class=keyword>int </span><span class=identifier>i</span><span class=special>, </span><span class=keyword>int </span><span class=special>) </span><span class=special>: </span><span class=identifier>i</span><span class=special>(</span><span class=identifier>i</span><span class=special>)
538    </span><span class=special>{ </span><span class=special>}</span>
539<span class=special>};
540</span>
541<span class=comment>//
542// Required by ptr_set&lt;Foo&gt;
543//</span>
544<span class=keyword>inline </span><span class=keyword>bool </span><span class=keyword>operator</span><span class=special>&lt;( </span><span class=identifier>Foo </span><span class=identifier>l</span><span class=special>, </span><span class=identifier>Foo </span><span class=identifier>r </span><span class=special>)</span>
545<span class=special>{
546    </span><span class=keyword>return </span><span class=identifier>l</span><span class=special>.</span><span class=identifier>i </span><span class=special>&lt; </span><span class=identifier>r</span><span class=special>.</span><span class=identifier>i</span><span class=special>;</span>
547<span class=special>}
548</span>
549<span class=keyword>using </span><span class=keyword>namespace </span><span class=identifier>boost</span><span class=special>;</span>
550<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>;
551</span>
552<span class=special>{
553    </span><span class=identifier>ptr_deque</span><span class=special>&lt;</span><span class=identifier>Foo</span><span class=special>&gt; </span><span class=identifier>deq</span><span class=special>;
554    </span><span class=identifier>ptr_push_back</span><span class=special>( </span><span class=identifier>deq </span><span class=special>)()();
555    </span><span class=identifier>BOOST_CHECK</span><span class=special>( </span><span class=identifier>deq</span><span class=special>.</span><span class=identifier>size</span><span class=special>() </span><span class=special>== </span><span class=number>2u </span><span class=special>);
556    </span><span class=identifier>ptr_push_front</span><span class=special>( </span><span class=identifier>deq </span><span class=special>)( </span><span class=number>3 </span><span class=special>)( </span><span class=number>42</span><span class=special>, </span><span class=number>42 </span><span class=special>)( </span><span class=string>&quot;foo&quot;</span><span class=special>, </span><span class=number>42</span><span class=special>, </span><span class=number>42 </span><span class=special>);
557    </span><span class=identifier>BOOST_CHECK</span><span class=special>( </span><span class=identifier>deq</span><span class=special>.</span><span class=identifier>size</span><span class=special>() </span><span class=special>== </span><span class=number>5 </span><span class=special>);
558
559    </span><span class=identifier>ptr_set</span><span class=special>&lt;</span><span class=identifier>Foo</span><span class=special>&gt; </span><span class=identifier>a_set</span><span class=special>;
560    </span><span class=identifier>ptr_insert</span><span class=special>( </span><span class=identifier>a_set </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>2 </span><span class=special>)( </span><span class=string>&quot;foo&quot;</span><span class=special>, </span><span class=number>3</span><span class=special>, </span><span class=number>3 </span><span class=special>);
561    </span><span class=identifier>BOOST_CHECK</span><span class=special>( </span><span class=identifier>a_set</span><span class=special>.</span><span class=identifier>size</span><span class=special>() </span><span class=special>== </span><span class=number>4 </span><span class=special>);
562    </span><span class=identifier>ptr_insert</span><span class=special>( </span><span class=identifier>a_set </span><span class=special>)()()()();
563    </span><span class=identifier>BOOST_CHECK</span><span class=special>( </span><span class=identifier>a_set</span><span class=special>.</span><span class=identifier>size</span><span class=special>() </span><span class=special>== </span><span class=number>4 </span><span class=special>); </span><span class=comment>// duplicates not inserted</span>
564<span class=special>}</span>
565    </pre>
566</blockquote>
567                       
568<h3>Function <code>ptr_list_of()</code> <a name="ptr_list_of"></h3>         
569
570Just like you can use <code>list_of()</code> to initialize containers, you can
571use <code>ptr_list_of()</code> to initialize a <a href="../../ptr_container/index.html">pointer container</a>.
572Here is a small example:
573
574<blockquote>
575    <pre>
576<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>ptr_list_of</span><span class=special>.</span><span class=identifier>hpp</span><span class=special>&gt;</span>
577<span class=preprocessor>#include </span><span class=special>&lt;</span><span class=identifier>boost</span><span class=special>/</span><span class=identifier>ptr_container</span><span class=special>/</span><span class=identifier>ptr_deque</span><span class=special>.</span><span class=identifier>hpp</span><span class=special>&gt;
578</span>
579<span class=keyword>using </span><span class=keyword>namespace </span><span class=identifier>boost</span><span class=special>;</span>
580<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>;
581</span>
582<span class=special>{
583    </span><span class=identifier>ptr_deque</span><span class=special>&lt;</span><span class=identifier>Foo</span><span class=special>&gt; </span><span class=identifier>deq</span><span class=special>;
584    </span><span class=identifier>deq </span><span class=special>= </span><span class=identifier>ptr_list_of</span><span class=special>&lt;</span><span class=identifier>Foo</span><span class=special>&gt;( </span><span class=number>42 </span><span class=special>)()()( </span><span class=number>3</span><span class=special>, </span><span class=number>3 </span><span class=special>)( </span><span class=string>&quot;foo&quot;</span><span class=special>, </span><span class=number>2</span><span class=special>, </span><span class=number>1 </span><span class=special>).</span><span class=identifier>to_container</span><span class=special>( </span><span class=identifier>deq </span><span class=special>);
585    </span><span class=identifier>BOOST_CHECK</span><span class=special>( </span><span class=identifier>deq</span><span class=special>.</span><span class=identifier>size</span><span class=special>() </span><span class=special>== </span><span class=number>5 </span><span class=special>);</span>
586<span class=special>}</span>   
587    </pre>
588</blockquote>
589
590Notice the trailing <code>.to_container(deq)</code> which helps many poor
591compilers to figure out the conversion (a few get it right).
592Notice also that pointer maps are
593not supported.
594
595<p>
596That is all; now you are ready to use this library.
597 </p>
598
599  <hr> 
600  <h2><a name="reference">Reference</a></h2>
601    <p>
602  It is worth noticing the way the library is implemented.
603  A free-standing function (eg. <code>push_back()</code>
604  or <code>operator+=()</code>) returns a proxy
605  object which is responsible for the insertion or the assignment. The proxy
606object does the insertion or assignment by overloading <code>operator,()</code>
607  and <code>operator()()</code> and by calling the "insert" function from within
608  those operators. The "insert" function is typically stored in the proxy object
609  by using <code>boost::<a href="../../function/index.html">function</a></code>. </p>
610 
611  <p>
612  Often overloading
613  of <code>operator,()</code> is discouraged because it can lead to surprising
614  results, but the approach taken in this library is safe since the
615  user never deals with objects that have overloaded <code>operator,()</code>
616  directly. However, you should be aware of this:
617  </p>
618 
619  <p><i>
620  The
621  expressions in a comma-separated list no longer follow the rules of the
622  built-in comma-operator. This means that the order of evaluation of
623  expressions in a comma-separated list is undefined like when one specifies
624  a list of function arguments.
625  </i></p>
626 
627    <p>
628  Most of the code in this document use <code>int</code> in the examples,
629  but of course it works for arbitrary types as long as they are
630  Copy Constructible. The inserted data need not be constant data,
631  but can be variables or data returned from functions; the only requirement
632  is that the type of the data is convertible to the type stored in the
633  container.
634  </p>
635 
636  <p>
637  All forwarding is done by passing objects by <code>const</code> reference.
638Originally arguments were passed by value (and still is in
639<code>tuple_list_of()</code>). One thing to remember is that references
640  can be passed by using <code>boost::<a href=http://www.boost.org/doc/html/ref.html>ref</a></code>.
641  </p>
642 
643  <p>
644   Everything is put in namespace
645  <code>boost::assign</code>. </p>
646
647  <p> More details can be found below: </p>
648      <ul>
649         
650        <li><a href="#headers">Headers</a> </li>
651        <li><a href="#std">Standard containers</a> </li>
652        <li>Functions <a href="#list_of_ref"><code>list_of()</code> and <code>map_list_of()</code></a></li>
653        <li>Functions <a href="#repeat_ref"><code>repeat()</code> and <code>repeat_fun()</code></a></li>
654        <li>Class <a href="#list_inserter"><code>list_inserter</code></a></li>
655        <li>Function <a href="#make_list_inserter"><code>make_list_inserter()</code></a></li>
656        <li><a href="#limit">Customizing</a> argument list sizes </li>
657     </ul>
658  <h3>Headers <a name="headers"></h3>     
659 
660  <p>
661  An overview of the headers in this library
662is given below. Please notice <code>&lt;boost/assign/list_inserter.hpp></code> 
663is included for each header that defines <code>operator+=()</code>.</p>
664
665<table cellpadding=5 border=1 > <tr>
666         <th>  Header                      </th>
667         <th>        Includes              </th> 
668     <tr>
669         <td> &lt;boost/assign.hpp>               </td>
670         <td>     everything except support for pointer containers  </td>
671     <tr>
672         <td> &lt;boost/assign/list_of.hpp>       </td>
673         <td> <a href="#list_of"><code>list_of()</a>, <a 
674href="#map_list_of">map_list_of()</code></a>,
675         <a href="#tuple_list_of">tuple_list_of()</code></a>,
676         <a href="#ref_list_of">ref_list_of()</code> and
677<code>cref_list_of()</code></a>
678                 
679         </td> <tr>
680         <td> &lt;boost/assign/std.hpp>       </td>
681         <td> <a href="#operator+="><code>operator+=()</code></a> for all
682standard
683containers (see below)</td> <tr> <td>  &lt;boost/assign/std/deque.hpp> </td>
684        <td>  <code>operator+=()</code> for
685              <code>std::deque</code>, <code>&lt;deque></code> 
686    <tr> 
687        <td>  &lt;boost/assign/std/list.hpp> </td>
688        <td>  <code>operator+=()</code> for
689              <code>std::list</code>, <code>&lt;list></code> 
690    <tr> 
691        <td>  &lt;boost/assign/std/map.hpp> </td>
692        <td>  <code>operator+=()</code> for
693              <code>std::map</code> and <code>std::multimap</code> ,
694<code>&lt;map></code> <tr> 
695        <td>  &lt;boost/assign/std/queue.hpp> </td>
696        <td>  <code>operator+=()</code> for
697              <code>std::queue</code> and <code>std::priority_queue</code>,
698<code>&lt;queue></code> <tr> 
699        <td>  &lt;boost/assign/std/set.hpp> </td>
700        <td>  <code>operator+=()</code> for
701              <code>std::set</code> and <code>std::multiset</code>,
702<code>&lt;set></code> <tr> 
703        <td>  &lt;boost/assign/std/slist.hpp> </td>
704        <td>  <code>operator+=()</code> for
705              <code>std::slist</code> if the class is available ,
706<code>&lt;slist></code> <tr> 
707        <td>  &lt;boost/assign/std/stack.hpp> </td>
708        <td>  <code>operator+=()</code> for
709              <code>std::stack</code>, <code>&lt;stack></code> 
710    <tr> 
711        <td>  &lt;boost/assign/std/vector.hpp> </td>
712        <td>  <code>operator+=()</code> for
713              <code>std::vector</code>, <code>&lt;vector></code> 
714    <tr> 
715        <td>  &lt;boost/assign/assignment_exception.hpp> </td>
716        <td>  Class <a 
717href="#assignment_exception"><code>assignment_exception</code></a> which might
718be thrown by the proxy returned by <code>list_of()</code>
719    <tr> 
720        <td>  &lt;boost/assign/list_inserter.hpp> </td>
721            <td>Functions <a
722               href="#make_list_inserter"><code>make_list_inserter()</code></a>, <code>push_back()</code>,
723                <code>push_front()</code>,<code>insert()</code>,
724                <code>
725                push()</code> and class <a href="#list_inserter"><code>list_inserter</code></a> 
726                which is the back-bone of this entire library.
727
728            <tr>   
729            <td>  &lt;boost/assign/ptr_list_inserter.hpp> </td>
730            <td>Functions <a href="#ptr_push_back"><code>ptr_push_back()</code></a>,
731                <code>ptr_push_front()</code> and <code>ptr_insert()</code>
732                 
733                            <tr>   
734            <td>  &lt;boost/assign/ptr_list_of.hpp> </td>
735            <td>Function <a href="#ptr_list_of"><code>ptr_list_of()</code></a>
736
737    </table>
738 
739  <h3>Standard containers <a name="std"> </h3>
740   <p> In the following three dots (...) will mean
741       implementation defined. 
742       <code>operator+=()</code> returns a proxy that forwards calls to either
743       <code>push_back()</code>,<code>insert()</code>, or <code>push()</code> 
744       depending on which operation the container supports. </p> <b>Synopsis</b>
745  <p>
746<blockquote>
747<pre>
748<span class=keyword>namespace </span><span class=identifier>boost</span>
749<span class=special>{</span>
750<span class=keyword>namespace </span><span class=identifier>assign</span>
751<span class=special>{
752    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>V</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>A</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>V2 </span><span class=special>&gt;
753    </span><span class=identifier>list_inserter</span><span class=special>&lt; </span><span class=special>... </span><span class=special>&gt;    </span><span class=keyword>operator</span><span class=special>+=( </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>deque</span><span class=special>&lt;</span><span class=identifier>V</span><span class=special>,</span><span class=identifier>A</span><span class=special>&gt;&amp; </span><span class=identifier>c</span><span class=special>, </span><span class=identifier>V2 </span><span class=identifier>v </span><span class=special>);
754   
755    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>V</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>A</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>V2 </span><span class=special>&gt;
756    </span><span class=identifier>list_inserter</span><span class=special>&lt; </span><span class=special>... </span><span class=special>&gt;    </span><span class=keyword>operator</span><span class=special>+=( </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>list</span><span class=special>&lt;</span><span class=identifier>V</span><span class=special>,</span><span class=identifier>A</span><span class=special>&gt;&amp; </span><span class=identifier>c</span><span class=special>, </span><span class=identifier>V2 </span><span class=identifier>v </span><span class=special>);
757   
758    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>K</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>V</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>C</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>A</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>P </span><span class=special>&gt;
759    </span><span class=identifier>list_inserter</span><span class=special>&lt; </span><span class=special>... </span><span class=special>&gt;    </span><span class=keyword>operator</span><span class=special>+=( </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>map</span><span class=special>&lt;</span><span class=identifier>K</span><span class=special>,</span><span class=identifier>V</span><span class=special>,</span><span class=identifier>C</span><span class=special>,</span><span class=identifier>A</span><span class=special>&gt;&amp; </span><span class=identifier>m</span><span class=special>, </span><span class=keyword>const </span><span class=identifier>P</span><span class=special>&amp; </span><span class=identifier>p </span><span class=special>);
760   
761    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>K</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>V</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>C</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>A</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>P </span><span class=special>&gt;
762    </span><span class=identifier>list_inserter</span><span class=special>&lt; </span><span class=special>... </span><span class=special>&gt;    </span><span class=keyword>operator</span><span class=special>+=( </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>multimap</span><span class=special>&lt;</span><span class=identifier>K</span><span class=special>,</span><span class=identifier>V</span><span class=special>,</span><span class=identifier>C</span><span class=special>,</span><span class=identifier>A</span><span class=special>&gt;&amp; </span><span class=identifier>m</span><span class=special>, </span><span class=keyword>const </span><span class=identifier>P</span><span class=special>&amp; </span><span class=identifier>p </span><span class=special>);
763   
764    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>V</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>C</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>V2 </span><span class=special>&gt;
765    </span><span class=identifier>list_inserter</span><span class=special>&lt; </span><span class=special>... </span><span class=special>&gt;    </span><span class=keyword>operator</span><span class=special>+=( </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>queue</span><span class=special>&lt;</span><span class=identifier>V</span><span class=special>,</span><span class=identifier>C</span><span class=special>&gt;&amp; </span><span class=identifier>c</span><span class=special>, </span><span class=identifier>V2 </span><span class=identifier>v </span><span class=special>);
766   
767    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>V</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>C</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>V2 </span><span class=special>&gt;
768    </span><span class=identifier>list_inserter</span><span class=special>&lt; </span><span class=special>... </span><span class=special>&gt;    </span><span class=keyword>operator</span><span class=special>+=( </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>priority_queue</span><span class=special>&lt;</span><span class=identifier>V</span><span class=special>,</span><span class=identifier>C</span><span class=special>&gt;&amp; </span><span class=identifier>c</span><span class=special>, </span><span class=identifier>V2 </span><span class=identifier>v </span><span class=special>);
769   
770    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>K</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>C</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>A</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>K2 </span><span class=special>&gt;
771    </span><span class=identifier>list_inserter</span><span class=special>&lt; </span><span class=special>... </span><span class=special>&gt; </span><span class=keyword>operator</span><span class=special>+=( </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>set</span><span class=special>&lt;</span><span class=identifier>K</span><span class=special>,</span><span class=identifier>C</span><span class=special>,</span><span class=identifier>A</span><span class=special>&gt;&amp; </span><span class=identifier>c</span><span class=special>, </span><span class=identifier>K2 </span><span class=identifier>k </span><span class=special>);
772   
773    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>K</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>C</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>A</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>K2 </span><span class=special>&gt;
774    </span><span class=identifier>list_inserter</span><span class=special>&lt; </span><span class=special>... </span><span class=special>&gt; </span><span class=keyword>operator</span><span class=special>+=( </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>multiset</span><span class=special>&lt;</span><span class=identifier>K</span><span class=special>,</span><span class=identifier>C</span><span class=special>,</span><span class=identifier>A</span><span class=special>&gt;&amp; </span><span class=identifier>c</span><span class=special>, </span><span class=identifier>K2 </span><span class=identifier>k </span><span class=special>);
775   
776    </span><span class=preprocessor>#ifdef </span><span class=identifier>BOOST_HAS_SLIST
777             
778    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>V</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>A</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>V2 </span><span class=special>&gt;
779    </span><span class=identifier>list_inserter</span><span class=special>&lt; </span><span class=special>... </span><span class=special>&gt;    </span><span class=keyword>operator</span><span class=special>+=( </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>slist</span><span class=special>&lt;</span><span class=identifier>V</span><span class=special>,</span><span class=identifier>A</span><span class=special>&gt;&amp; </span><span class=identifier>c</span><span class=special>, </span><span class=identifier>V2 </span><span class=identifier>v </span><span class=special>);
780   
781    </span><span class=preprocessor>#endif
782   
783    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>V</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>C</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>V2 </span><span class=special>&gt;
784    </span><span class=identifier>list_inserter</span><span class=special>&lt; </span><span class=special>... </span><span class=special>&gt;    </span><span class=keyword>operator</span><span class=special>+=( </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>stack</span><span class=special>&lt;</span><span class=identifier>V</span><span class=special>,</span><span class=identifier>C</span><span class=special>&gt;&amp; </span><span class=identifier>c</span><span class=special>, </span><span class=identifier>V2 </span><span class=identifier>v </span><span class=special>);
785   
786    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>V</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>A</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>V2 </span><span class=special>&gt;
787    </span><span class=identifier>list_inserter</span><span class=special>&lt; </span><span class=special>... </span><span class=special>&gt;    </span><span class=keyword>operator</span><span class=special>+=( </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>vector</span><span class=special>&lt;</span><span class=identifier>V</span><span class=special>,</span><span class=identifier>A</span><span class=special>&gt;&amp; </span><span class=identifier>c</span><span class=special>, </span><span class=identifier>V2 </span><span class=identifier>v </span><span class=special>);    </span>
788
789<span class=special>} </span><span class=comment>// namespace 'assign'</span>
790<span class=special>} </span><span class=comment>// namespace 'boost'</span>  </pre></blockquote>
791    Note that the extra template argument <code>V2</code> etc. is
792    necessary to allow for types convertible to <code>V</code>.   
793     
794  <h3>Functions <code>list_of()</code> and
795      <code>map_list_of()</code> <a name=list_of_ref> </h3>
796    <p> 
797  These two functions are used to construct anonymous   
798  list which can be converted to any standard container
799  and <code>boost::<a href=../../array/index.html>array</a>&lt;T,sz>.</code> 
800The object returned by the two
801  functions is guaranteed to have the interface described below.
802  </p>
803  <b>Synopsis</b>
804  <blockquote> 
805  <pre><span class=keyword>namespace </span><span class=identifier>boost  </span>
806<span class=special>{</span>
807<span class=keyword>namespace </span><span class=identifier>assign</span>
808<span class=special>{
809    </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;
810    </span><span class=keyword>class </span><span class=identifier>Implementation</span><span class=special>-</span><span class=identifier>defined</span>
811    </span><span class=special>{
812    </span><span class=keyword>public</span><span class=special>:
813        </span><span class=identifier>const_iterator  </span><span class=identifier>begin</span><span class=special>() <span class=keyword>const</span>;
814        </span><span class=identifier>const_iterator  </span><span class=identifier>end</span><span class=special>() <span class=keyword>const</span>;
815       
816        </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>U </span><span class=special>&gt;
817        </span><span class=identifier>Implementation</span><span class=special>-</span><span class=identifier>defined</span>&amp; </span><span class=keyword>operator</span><span class=special>,( </span><span class=identifier>U </span><span class=identifier>u </span><span class=special>);
818       
819        </span><span class=comment>// inserts default-constructed object
820        </span><span class=identifier>Implementation</span><span class=special>-</span><span class=identifier>defined</span>&amp; </span><span class=keyword>operator</span><span class=special>()(); 
821
822        </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>U </span><span class=special>&gt;
823        </span><span class=identifier>Implementation</span><span class=special>-</span><span class=identifier>defined</span>&amp; </span><span class=keyword>operator</span><span class=special>()( </span><span class=identifier>U </span><span class=identifier>u </span><span class=special>);
824       
825        </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>U</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>U2 </span><span class=special>&gt;
826        </span><span class=identifier>Implementation</span><span class=special>-</span><span class=identifier>defined</span>&amp; </span><span class=keyword>operator</span><span class=special>()( </span><span class=identifier>U </span><span class=identifier>u</span><span class=special>, </span><span class=identifier>U2 </span><span class=identifier>u2 </span><span class=special>);
827
828        </span><span class=comment>//
829        // and similarly up to 5 arguments
830        //
831       
832        //
833        // Convert to a 'Container'. 'Container' must have a constructor
834        // which takes two iterators. 
835        //
836        </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>Container </span><span class=special>&gt;
837        </span><span class=keyword>operator </span><span class=identifier>Container</span><span class=special>() </span><span class=keyword>const</span><span class=special>;
838
839        </span><span class=comment>//
840        // Convert to a container adapter like 'std::stack&lt;&gt;'.
841        //
842        </span><span class=identifier>Convertible</span><span class=special>-</span><span class=identifier>to</span><span class=special>-</span><span class=identifier>adapter</span> </span><span class=identifier>to_adapter</span><span class=special>() </span><span class=keyword>const</span><span class=special>;
843       
844        </span><span class=comment>//
845        //
846        // Convert to eg. 'boost::array&lt;T,std::size_t&gt;'. If the 
847        // assigned variable is too small,
848        // a <a href="#assignment_exception">assignment_exception</a> is thrown.
849        // If the assigned variable it is too big, the rest of the
850        // values are  default-constructed.
851        //
852        </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>template </span><span class=special>&lt;</span><span class=keyword>class</span><span class=special>,</span><span class=identifier>std</span><span class=special>::</span><span class=identifier>size_t</span><span class=special>&gt; </span><span class=keyword>class </span><span class=identifier>Array</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>U</span><span class=special>, </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>size_t </span><span class=identifier>sz </span><span class=special>&gt; 
853        </span><span class=keyword>operator </span><span class=identifier>Array</span><span class=special>&lt;</span><span class=identifier>U</span><span class=special>,</span><span class=identifier>sz</span><span class=special>&gt;() </span><span class=keyword>const</span><span class=special>;
854    </span><span class=special>};
855   
856    </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;
857    </span><span class=identifier>Implementation</span><span class=special>-</span><span class=identifier>defined</span>   </span><span class=identifier>list_of</span><span class=special>(</span><span class=special>);
858
859    </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;
860    </span><span class=identifier>Implementation</span><span class=special>-</span><span class=identifier>defined</span>   </span><span class=identifier>list_of</span><span class=special>( </span><span class=identifier>T </span><span class=identifier>t </span><span class=special>);
861   
862    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>T</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>U</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>U2 </span><span class=special>&gt;
863    </span><span class=identifier>Implementation</span><span class=special>-</span><span class=identifier>defined</span>   </span><span class=identifier>list_of</span><span class=special>( </span><span class=identifier>U </span><span class=identifier>u</span><span class=special>, </span><span class=identifier>U2 </span><span class=identifier>u2 </span><span class=special>);
864   
865    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>T</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>U</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>U2</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>U3 </span><span class=special>&gt;
866    </span><span class=identifier>Implementation</span><span class=special>-</span><span class=identifier>defined</span>   </span><span class=identifier>list_of</span><span class=special>( </span><span class=identifier>U </span><span class=identifier>u</span><span class=special>, </span><span class=identifier>U2 </span><span class=identifier>u2</span><span class=special>, </span><span class=identifier>U3 </span><span class=identifier>u3 </span><span class=special>);
867
868    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>T</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>U</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>U2</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>U3</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>U4 </span><span class=special>&gt;
869    </span><span class=identifier>Implementation</span><span class=special>-</span><span class=identifier>defined</span>   </span><span class=identifier>list_of</span><span class=special>( </span><span class=identifier>U </span><span class=identifier>u</span><span class=special>, </span><span class=identifier>U2 </span><span class=identifier>u2</span><span class=special>, </span><span class=identifier>U3 </span><span class=identifier>u3</span><span class=special>, </span><span class=identifier>U4 </span><span class=identifier>u4 </span><span class=special>);
870 
871    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>T</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>U</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>U2</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>U3</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>U4</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>U5 </span><span class=special>&gt;
872    </span><span class=identifier>Implementation</span><span class=special>-</span><span class=identifier>defined</span>   </span><span class=identifier>list_of</span><span class=special>( </span><span class=identifier>U </span><span class=identifier>u</span><span class=special>, </span><span class=identifier>U2 </span><span class=identifier>u2</span><span class=special>, </span><span class=identifier>U3 </span><span class=identifier>u3</span><span class=special>, </span><span class=identifier>U4 </span><span class=identifier>u4</span><span class=special>, </span><span class=identifier>U5 </span><span class=identifier>u5 </span><span class=special>);
873
874    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>Key</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>T </span><span class=special>&gt;
875    </span><span class=identifier>Implementation</span><span class=special>-</span><span class=identifier>defined</span>   </span><span class=identifier>map_list_of</span><span class=special>( </span><span class=identifier>Key </span><span class=identifier>k</span><span class=special>, </span><span class=identifier>T </span><span class=identifier>t </span><span class=special>)
876    </span><span class=special>{
877        </span><span class=keyword>return </span><span class=identifier>list_of</span><span class=special>&lt; </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>pair</span><span class=special>&lt;</span><span class=identifier>Key</span><span class=special>,</span><span class=identifier>T</span><span class=special>&gt; </span><span class=special>&gt;()( </span><span class=identifier>k</span><span class=special>, </span><span class=identifier>t </span><span class=special>);
878    </span><span class=special>}</span>
879<span class=special>} </span><span class=comment>// namespace 'assign'</span>
880<span class=special>} </span><span class=comment>// namespace 'boost'</span>  </pre></blockquote>
881
882  <h3>Functions <code>repeat()</code> and
883     <code>repeat_fun()</code> <a name="repeat_ref"> </h3>
884  <p>
885      These two function exist both as free-standing functions and as member functions of the object returned by
886      <code>list_of()</code> and of <code>list_inserter</code>. The free-standing versions are used to create a
887      hook for <code>operator,()</code> so we can call the functions in the middle of a comma-list. The member functions
888      are used when we need to call the functions in the middle of a parenthesis-list. In both cases we have that
889      <ul>
890          <li> the return type is always implementation defined for both functions,
891          <li> the argument list of <code>repeat()</code> is <code>(std::size_t,T)</code>, and 
892          <li> the argument list of <code>repeat_fun()</code> is <code>(std::size_t,Nullary_function)</code>   
893      </ul>
894     
895  </p>
896     
897  <h3><a name="list_inserter">Class <code>list_inserter</code></a></h3> 
898 
899  This class is responsible for inserting elements into containers and
900  it is the key to extending the library to support your favourite class.
901
902    <p>
903  <b>Synopsis</b> 
904  </p>
905  <blockquote><pre>
906<span class=keyword>namespace </span><span class=identifier>boost</span>
907<span class=special>{</span>
908<span class=keyword>namespace </span><span class=identifier>assign</span>
909<span class=special>{
910    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=identifier>Function</span><span class=special>, </span><span class=identifier>Argument </span><span class=special>= </span><span class=keyword>void </span><span class=special>&gt; 
911    </span><span class=keyword>class </span><span class=identifier>list_inserter
912    </span><span class=special>{
913        </span><span class=identifier>Function </span><span class=identifier>fun</span><span class=special>;
914       
915    </span><span class=keyword>public</span><span class=special>:
916        </span><span class=keyword>explicit </span><span class=identifier>list_inserter</span><span class=special>( </span><span class=identifier>Function </span><span class=identifier>fun </span><span class=special>);
917       
918        </span><span class=comment>// conversion constructor
919        </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>Function2</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>Arg </span><span class=special>&gt;
920        </span><span class=identifier>list_inserter</span><span class=special>( </span><span class=keyword>const </span><span class=identifier>list_inserter</span><span class=special>&lt;</span><span class=identifier>Function2</span><span class=special>,</span><span class=identifier>Arg</span><span class=special>&gt;&amp; </span><span class=special>);
921       
922    </span><span class=keyword>public</span><span class=special>:
923        </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>U </span><span class=special>&gt;
924        </span><span class=identifier>list_inserter</span><span class=special>&amp; </span><span class=keyword>operator</span><span class=special>,( </span><span class=identifier>U </span><span class=identifier>u </span><span class=special>);
925       
926        </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>U </span><span class=special>&gt;
927        </span><span class=identifier>list_inserter</span><span class=special>&amp; </span><span class=keyword>operator</span><span class=special>=( </span><span class=identifier>U </span><span class=identifier>u </span><span class=special>);
928       
929        </span><span class=comment>// calls 'fun()' with default-constructed object
930        </span><span class=identifier>list_inserter</span><span class=special>&amp; </span><span class=keyword>operator</span><span class=special>()();
931       
932        </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>U </span><span class=special>&gt;
933        </span><span class=identifier>list_inserter</span><span class=special>&amp; </span><span class=keyword>operator</span><span class=special>()( </span><span class=identifier>U </span><span class=identifier>u </span><span class=special>);
934       
935        </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>U</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>U2 </span><span class=special>&gt;
936        </span><span class=identifier>list_inserter</span><span class=special>&amp; </span><span class=keyword>operator</span><span class=special>()( </span><span class=identifier>U </span><span class=identifier>u</span><span class=special>, </span><span class=identifier>U2 </span><span class=identifier>u2 </span><span class=special>)
937        </span><span class=special>{
938           </span><span class=comment>//
939           // if 'Argument' is 'void'
940           //     fun( u, u2 );
941           // else
942           //     fun( Argument( u, u2 ) );
943           //
944           </span><span class=keyword>return </span><span class=special>*</span><span class=keyword>this</span><span class=special>;
945        </span><span class=special>}
946
947        </span><span class=comment>//
948        // similarly up to 5 arguments
949        //
950    </span><span class=special>};</span>
951   
952    <span class=keyword>template</span><span class=special>&lt; </span><span 
953class=keyword>class </span><span class=identifier>C </span><span class=special>&gt;
954    </span><span class=identifier>list_inserter</span><span class=special>&lt; </span><span class=special>... </span><span class=special>&gt; </span><span class=identifier>push_back</span><span class=special>( </span><span class=identifier>C</span><span class=special>&amp; </span><span class=special>);
955     
956    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>C </span><span class=special>&gt;
957    </span><span class=identifier>list_inserter</span><span class=special>&lt; </span><span class=special>... </span><span class=special>&gt; </span><span class=identifier>push_front</span><span class=special>( </span><span class=identifier>C</span><span class=special>&amp; </span><span class=special>);
958
959    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>C </span><span class=special>&gt;
960    </span><span class=identifier>list_inserter</span><span class=special>&lt; </span><span class=special>... </span><span class=special>&gt; </span><span class=identifier>insert</span><span class=special>( </span><span class=identifier>C</span><span class=special>&amp; </span><span class=special>);
961
962    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>C </span><span class=special>&gt;
963    </span><span class=identifier>list_inserter</span><span class=special>&lt; </span><span class=special>... </span><span class=special>&gt; </span><span class=identifier>push</span><span class=special>( </span><span class=identifier>C</span><span class=special>&amp; </span><span class=special>);</span>
964     
965<span class=special>} </span><span class=comment>// namespace 'assign'</span>
966<span class=special>} </span><span class=comment>// namespace 'boost'</span></pre></blockquote>
967  <p>
968  Notice how the arguments to <code>operator,()</code> and
969  <code>operator()()</code> are passed differently to
970  <code>fun</code> depending of the type of <code>Argument</code>.
971  So if we only pass one template argument to <code>list_inserter,</code>
972  we can forward "arbitrary" argument lists of functions. If we pass
973  two template arguments to <code>list_inserter</code> we can
974  construct types with "arbitrary" constructors.
975  </p> 
976   
977  <p> 
978   And because
979  a reference to <code>list_inserter</code> is returned, we can
980  chain argument list together in a very space-efficient manner.
981  </p>
982
983  <h3><a name="make_list_inserter">Function <code>make_list_inserter()</code></a></h3>
984  <p>
985  A simple "constructor" function for <code>list_inserter</code>. A typical
986  use of this function is to call it with the result of
987<code>boost::bind()</code>
988  which in general returns some unreadable and weird class template.
989  </p>
990  <b>Synopsis</b>
991  <blockquote><pre>
992<span class=keyword>namespace </span><span class=identifier>boost </span>
993<span class=special>{</span>
994<span class=keyword>namespace </span><span class=identifier>assign</span>
995<span class=special>{ 
996    </span><span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>Function </span><span class=special>&gt;
997    </span><span class=identifier>list_inserter</span><span class=special>&lt;</span><span class=identifier>Function</span><span class=special>&gt;  </span><span class=identifier>make_list_inserter</span><span class=special>( </span><span class=identifier>Function </span><span class=identifier>fun </span><span class=special>)
998    </span><span class=special>{
999        </span><span class=keyword>return </span><span class=identifier>list_inserter</span><span class=special>&lt;</span><span class=identifier>Function</span><span class=special>&gt;( </span><span class=identifier>fun </span><span class=special>);
1000    </span><span class=special>} </span>
1001<span class=special>}</span>
1002<span class=special>}  </span>  </pre></blockquote>
1003
1004   <a name="limit"></a>   
1005   <h3>Customizing argument list sizes</h3>   
1006      <p>
1007    This library uses the boost Preprocessor Library to implement overloaded
1008    versions of <code>operator()()</code> and <code>list_of()</code>. By default you
1009    can call these functions with five arguments, but you can also customize this
1010    number by defining a macros before including a header from this library:
1011       <blockquote>
1012       <pre>
1013<span class=preprocessor>#define </span><span class=identifier>BOOST_ASSIGN_MAX_PARAMS </span><span class=number>10
1014</span><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>
1015</pre>
1016       </blockquote>     
1017       </p>
1018  <hr>   
1019  <h2><a name="exceptions">Exceptions and exception-safety</a></h2>
1020  <p>
1021  The exception guarantees by the library is the same as guarantee as the
1022  guarantee of the function that is forwarded to. For standard
1023  containers this means that the
1024  strong guarantee is given for a single insertions and that the basic guarantee
1025  is given for many insertions (provided that the object being copied
1026  gives the basic guarantee).
1027  </p>
1028  <p>
1029  The functions may throw standard exceptions
1030  like <code>std::bad_alloc</code>. Note however that, unfortunately, the standard does not guarantee allocation-failures
1031  in standard containers to be reported by <code>std::bad_alloc</code> or exceptions derived from <code>std::exception</code>.
1032 </p>
1033 
1034  <h3><a name="assignment_exception">Class
1035  <code>assignment_exception</code></a></h3>
1036  <p>
1037   The exception is thrown by the conversion operator in the proxy object
1038   returned from <code>list_of()</code>.
1039  </p>
1040
1041  <blockquote><pre>
1042<span class=keyword>namespace </span><span class=identifier>boost </span>
1043<span class=special>{</span>
1044<span class=keyword>namespace </span><span class=identifier>assign</span>
1045<span class=special>{
1046    </span><span class=keyword>class </span><span class=identifier>assignment_exception </span><span class=special>: </span><span class=keyword>public </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>exception
1047    </span><span class=special>{
1048    </span><span class=keyword>public</span><span class=special>:
1049        </span><span class=keyword>explicit </span><span class=identifier>assignment_exception</span><span class=special>( </span><span class=keyword>const </span><span class=keyword>char</span><span class=special>* </span><span class=identifier>what </span><span class=special>);
1050        </span><span class=keyword>virtual </span><span class=keyword>const </span><span class=keyword>char</span><span class=special>* </span><span class=identifier>what</span><span class=special>() </span><span class=keyword>const </span><span class=keyword>throw</span><span class=special>();
1051    </span><span class=special>};</span>
1052<span class=special>}   </span>
1053<span class=special>}</span>  </pre></blockquote> 
1054
1055  <hr>
1056  <h2><a name="extensions">Extending the library</a></h2> 
1057  <p>
1058  It is very simple to make the library work with new classes.
1059  This code shows how to use <code>operator+=()</code> with
1060  a container:
1061  <blockquote><pre>
1062<span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>V</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>A</span><span class=special>, </span><span class=keyword>class </span><span class=identifier>V2 </span><span class=special>&gt;
1063</span><span class=keyword>inline </span><span class=identifier>list_inserter</span><span class=special>&lt; </span><span class=identifier>assign_detail</span><span class=special>::</span><span class=identifier>call_push_back</span><span class=special>&lt; </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>vector</span><span class=special>&lt;</span><span class=identifier>V</span><span class=special>,</span><span class=identifier>A</span><span class=special>&gt; </span><span class=special>&gt;, </span><span class=identifier>V </span><span class=special>&gt; 
1064</span><span class=keyword>operator</span><span class=special>+=( </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>vector</span><span class=special>&lt;</span><span class=identifier>V</span><span class=special>,</span><span class=identifier>A</span><span class=special>&gt;&amp; </span><span class=identifier>c</span><span class=special>, </span><span class=identifier>V2 </span><span class=identifier>v </span><span class=special>)
1065</span><span class=special>{
1066    </span><span class=keyword>return </span><span class=identifier>make_list_inserter</span><span class=special>( </span><span class=identifier>assign_detail</span><span class=special>::</span><span class=identifier>call_push_back</span><span class=special>&lt; </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>vector</span><span class=special>&lt;</span><span class=identifier>V</span><span class=special>,</span><span class=identifier>A</span><span class=special>&gt; </span><span class=special>&gt;( </span><span class=identifier>c </span><span class=special>) </span><span class=special>)( </span><span class=identifier>v </span><span class=special>);
1067</span><span class=special>}
1068</span></pre>
1069</blockquote>     
1070
1071
1072where <code>call_push_back</code> is defined as   
1073     
1074<blockquote>     
1075<pre>
1076<span class=keyword>template</span><span class=special>&lt; </span><span class=keyword>class </span><span class=identifier>C </span><span class=special>&gt;
1077</span><span class=keyword>class </span><span class=identifier>call_push_back
1078</span><span class=special>{
1079    </span><span class=identifier>C</span><span class=special>&amp; </span><span class=identifier>c_</span><span class=special>;
1080</span><span class=keyword>public</span><span class=special>:
1081
1082    </span><span class=identifier>call_push_back</span><span class=special>( </span><span class=identifier>C</span><span class=special>&amp; </span><span class=identifier>c </span><span class=special>) </span><span class=special>: </span><span class=identifier>c_</span><span class=special>( </span><span class=identifier>c </span><span class=special>)
1083    </span><span class=special>{ </span><span class=special>}
1084   
1085    </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;
1086    </span><span class=keyword>void </span><span class=keyword>operator</span><span class=special>()( </span><span class=identifier>T </span><span class=identifier>r </span><span class=special>)
1087    </span><span class=special>{
1088        </span><span class=identifier>c_</span><span class=special>.</span><span class=identifier>push_back</span><span class=special>( </span><span class=identifier>r </span><span class=special>);
1089    </span><span class=special>}
1090</span><span class=special>};</span></pre>   
1091</blockquote>
1092     
1093      Note that we pass
1094  a second template argument to <code>list_inserter</code> so argument
1095  lists will be used to construct a <code>V</code> object. Otherwise we
1096  could end up trying to call <code>push_back()</code> with <i>n</i> arguments
1097  instead of one.
1098  </p>
1099     
1100  <p>   
1101  An alternative way would be to use <code>boost::function</code> and
1102  <code>boost::bind()</code> in combination. However, in this case one must
1103  remember that it is illegal to take the address of a function in
1104  the standard library.
1105  </p>
1106     
1107  <p>
1108  Calling a function with more that one argument can be
1109  very useful too. This small example shows how we take advantage of this
1110  functionality:
1111  </p>
1112  <blockquote><pre>
1113<span class=comment>// 
1114// A class representing emails
1115//</span>
1116<span class=keyword>class </span><span class=identifier>email</span>
1117<span class=special>{</span>
1118<span class=keyword>public</span><span class=special>:
1119    </span><span class=keyword>enum </span><span class=identifier>address_option
1120    </span><span class=special>{
1121        </span><span class=identifier>check_addr_book</span><span class=special>,
1122        </span><span class=identifier>dont_check_addr_book
1123    </span><span class=special>};
1124    </span>
1125<span class=keyword>private</span><span class=special>:
1126
1127    </span><span class=keyword>typedef </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>map</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>address_option </span><span class=special>&gt;  </span><span class=identifier>address_map</span><span class=special>;
1128   
1129    </span><span class=comment>//
1130    // Store list of persons that must be cc'ed
1131    //
1132    </span><span class=keyword>mutable </span><span class=identifier>address_map </span><span class=identifier>cc_list</span><span class=special>;
1133       
1134    </span><span class=comment>//
1135    // This extra function-object will take care of the
1136    // insertion for us. It stores a reference to a
1137    // map and 'operator()()' does the work.
1138    //
1139    </span><span class=keyword>struct </span><span class=identifier>add_to_map
1140    </span><span class=special>{
1141        </span><span class=identifier>address_map</span><span class=special>&amp; </span><span class=identifier>m</span><span class=special>;
1142   
1143        </span><span class=identifier>add_to_map</span><span class=special>( </span><span class=identifier>address_map</span><span class=special>&amp; </span><span class=identifier>m </span><span class=special>) </span><span class=special>: </span><span class=identifier>m</span><span class=special>(</span><span class=identifier>m</span><span class=special>)       
1144        </span><span class=special>{}
1145   
1146        </span><span class=keyword>void </span><span class=keyword>operator</span><span class=special>()( </span><span class=keyword>const </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span><span class=special>&amp; </span><span class=identifier>name</span><span class=special>, </span><span class=identifier>address_option </span><span class=identifier>ao </span><span class=special>)
1147        </span><span class=special>{
1148            </span><span class=identifier>m</span><span class=special>[ </span><span class=identifier>name </span><span class=special>] </span><span class=special>= </span><span class=identifier>ao</span><span class=special>;
1149        </span><span class=special>}
1150    </span><span class=special>};
1151</span>
1152<span class=keyword>public</span><span class=special>:
1153   
1154    </span><span class=comment>//
1155    // This function constructs the appropriate 'list_inserter'.
1156    // Again we could have use 'boost::function', but it is
1157    // trivial to use a function object.
1158    //
1159    // Notice that we do not specify an extra template
1160    // parameter to 'list_inserter'; this means we forward
1161    // all parameters directly to the function without
1162    // calling any constructor.
1163    //
1164    </span><span class=identifier>list_inserter</span><span class=special>&lt; </span><span class=identifier>add_to_map </span><span class=special>&gt;
1165    </span><span class=identifier>add_cc</span><span class=special>( </span><span class=identifier>std</span><span class=special>::</span><span class=identifier>string </span><span class=identifier>name</span><span class=special>, </span><span class=identifier>address_option </span><span class=identifier>ao </span><span class=special>)
1166    </span><span class=special>{
1167        </span><span class=comment>//
1168        // Notice how we pass the arguments 'name' and 'ao' to
1169        // the 'list_inserter'.
1170        //
1171        </span><span class=keyword>return </span><span class=identifier>make_list_inserter</span><span class=special>( </span><span class=identifier>add_to_map</span><span class=special>( </span><span class=identifier>cc_list </span><span class=special>) </span><span class=special>)( </span><span class=identifier>name</span><span class=special>, </span><span class=identifier>ao </span><span class=special>);
1172    </span><span class=special>}</span>
1173<span class=special>};
1174</span>
1175<span class=comment>//
1176// Now we can use the class like this:
1177//</span>
1178<span class=identifier>email </span><span class=identifier>e</span><span class=special>;</span>
1179<span class=identifier>e</span><span class=special>.</span><span class=identifier>add_cc</span><span class=special>( </span><span class=string>&quot;Mr. Foo&quot;</span><span class=special>, </span><span class=identifier>email</span><span class=special>::</span><span class=identifier>dont_check_addr_book </span><span class=special>)
1180        </span><span class=special>( </span><span class=string>&quot;Mr. Bar&quot;</span><span class=special>, </span><span class=identifier>email</span><span class=special>::</span><span class=identifier>check_addr_book </span><span class=special>)
1181        </span><span class=special>( </span><span class=string>&quot;Mrs. FooBar&quot;</span><span class=special>, </span><span class=identifier>email</span><span class=special>::</span><span class=identifier>check_addr_book </span><span class=special>);  </span>
1182</pre></blockquote>
1183     
1184   
1185  The full example can be seen in <a href="email_example.html">email_example.cpp</a> </p>
1186  <hr>
1187  <h2>Examples <a name="examples"></h2>
1188  <p>
1189  Additional examples can be found in the test files:
1190  <ul>
1191      <li> <a href="email_example.html">email_example.cpp</a>         
1192      <li> <a href="my_vector_example.html">my_vector_example.cpp</a>               
1193      <li> <a href="multi_index_container.html">multi_index_container.cpp</a> 
1194      <li> <a href="../test/array.cpp">array.cpp</a>     
1195      <li> <a href="../test/list_of.cpp">list_of.cpp</a>     
1196      <li> <a href="../test/std.cpp">std.cpp</a>     
1197      <li> <a href="../test/list_inserter.cpp">list_inserter.cpp</a>     
1198      <li> <a href="../test/list_of_workaround.cpp">list_of_work_around.cpp</a>     
1199</ul> </p>
1200 
1201 
1202  <hr>
1203  <h2><a name="boost_libs">Supported libraries</a></h2> 
1204  Here is a list libraries has been tested with Boost.Assign:
1205 
1206  <ol>
1207      <li> <code>boost::<a href=../../array/index.html>array</a></code>
1208      <li> <code>boost::<a href=../../multi_index/index.html>multi_index_container</a></code>
1209      <li> <code>Boost.<a href=../../ptr_container/index.html>Pointer Container</code> </ol> <p>
1210
1211  </p>
1212 
1213 
1214  <hr>
1215  <h2><a name="portability">Portability</a></h2>
1216  <p>
1217    Library has been successfully compiled and tested with
1218    MVC++ 7.1, GCC 3.2 (under Cygwin) Comeau 4.3.3
1219  </p>
1220  <p>
1221    There are known limitation on platforms not supporting templated
1222    conversion operators. The solution is to call certain member functions on
1223    the object returned by <code>list_of()</code>: </p>
1224 <blockquote>
1225     <pre>
1226<span class=special>{
1227    </span><span class=keyword>using </span><span class=keyword>namespace </span><span class=identifier>std</span><span class=special>;
1228    </span><span class=keyword>using </span><span class=keyword>namespace </span><span class=identifier>boost</span><span class=special>;
1229    </span><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>;
1230   
1231    </span><span class=keyword></span><span 
1232class=identifier>vector</span><span
1233class=special>&lt;</span><span class=keyword>int</span><span 
1234class=special>&gt;</span>         <span class=identifier>v </span><span 
1235class=special>= </span><span class=identifier>list_of</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=identifier>to_container</span><span class=special>( </span><span class=identifier>v </span><span class=special>);
1236    </span><span class=identifier>set</span><span class=special>&lt;</span><span class=keyword>int</span><span class=special>&gt;            </span><span class=identifier>s </span><span class=special>= </span><span class=identifier>list_of</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=identifier>to_container</span><span class=special>( </span><span class=identifier>s </span><span class=special>); 
1237    </span><span class=identifier>map</span><span class=special>&lt;</span><span class=keyword>int</span><span class=special>,</span><span class=keyword>int</span><span class=special>&gt;        </span><span class=identifier>m </span><span class=special>= </span><span class=identifier>map_list_of</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>2</span><span class=special>,</span><span class=number>3</span><span class=special>).</span><span class=identifier>to_container</span><span class=special>( </span><span class=identifier>m </span><span class=special>);
1238    </span><span class=identifier>stack</span><span class=special>&lt;</span><span class=keyword>int</span><span class=special>&gt;         </span><span class=identifier>st </span><span class=special>= </span><span class=identifier>list_of</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=identifier>to_adapter</span><span class=special>( </span><span class=identifier>st </span><span class=special>);
1239    </span><span class=identifier>queue</span><span class=special>&lt;</span><span class=keyword>int</span><span class=special>&gt;          </span><span class=identifier>q </span><span class=special>= </span><span class=identifier>list_of</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=identifier>to_adapter</span><span class=special>( </span><span class=identifier>q </span><span class=special>);
1240    </span><span class=identifier>array</span><span class=special>&lt;</span><span class=keyword>int</span><span class=special>,</span><span class=number>4</span><span class=special>&gt;        </span><span class=identifier>a </span><span class=special>= </span><span class=identifier>list_of</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=identifier>to_array</span><span class=special>( </span><span class=identifier>a </span><span class=special>);</span>
1241<span class=special>}</span>     </pre>
1242 </blockquote>
1243 <p>
1244 Notice how one must supply the functions with an argument so the right
1245 return type can be deduced.
1246 </p>
1247 <p>Some standard libraries are also broken. One problem is that
1248<code>insert()</code> might not work:
1249<blockquote>
1250    <pre>
1251<span class=identifier>map</span><span class=special>&lt;</span><span class=keyword>int</span><span class=special>,</span><span class=keyword>int</span><span class=special>&gt; </span><span class=identifier>next</span><span class=special>;
1252</span><span class=identifier>insert</span><span class=special>( </span><span class=identifier>next </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>2</span><span class=special>,</span><span class=number>3</span><span class=special>); </span><span class=comment>// compile-time error</span> </pre>
1253</blockquote>
1254The solution is to use <code>map_list_of()</code> instead:
1255<blockquote>
1256    <pre>
1257<span class=identifier>map</span><span class=special>&lt;</span><span class=keyword>int</span><span class=special>,</span><span class=keyword>int</span><span class=special>&gt; </span><span class=identifier>next </span><span class=special>= </span><span class=identifier>map_list_of</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>2</span><span class=special>,</span><span class=number>3</span><span class=special>);</span></pre></blockquote>
1258</p>
1259 <hr>
1260  <h2><a name="history">History and Acknowledgment</a></h2>
1261  <p>
1262  The idea for an assignment/initialization library is not new. The
1263  functionality of this
1264  library resembles Leor Zolman's STL Container Initialization Library a great
1265  deal, but it does not rely on string parsing to achieve its goals.
1266  </p> 
1267  <p>
1268  The 
1269  library is non-intrusive and puts only a minimum of requirements
1270  on its supported classes.
1271 Overloading operator comma is sometimes viewed as a bad practice <a 
1272href=#meyers>[1]</A>. However, it has been done
1273  with success in eg. the Generative Matrix Computation Library  and Blitz to initialize matrices
1274      (see <a href=#gmcl>[2]</A>) and <a href=#blitz>[3]</A>). The
1275Initialization Library overloads
1276      the comma operator in a safe manner by letting free standing functions
1277 return an object that is responsible for the initialization. Therefore it takes
1278explicit
1279      action from the programmer to begin using the overloaded <code>operator,()</CODE>.
1280  </p>
1281  <p>
1282  There has recently been some discussion about enhancing the language to
1283support better initialization (see <a href="#initializer">[4]</a>).
1284  </p>
1285  <p>
1286  Special thanks goes to
1287  <ul>
1288  <li> Leor Zolman for our many discussion that eventually led to this library.
1289  <li> Tom Brinkman for being review manager.
1290  <li> Joaquín Muñoz for vc6/vc7 portability.
1291  <li> Pavel Vozenilek for his countless suggestions, improvements and
1292       portability fixes.
1293  <li> Rene Rivera for Code Warrior portability.     
1294       
1295       </ul>
1296  </p>
1297  <hr>
1298  <h2><a name="ref">References</a></h2>
1299  <p>
1300  <ol>
1301      <li> <a name="meyers">     Scott. Meyers, "More Effective C++", Item 7, Addison Wesley, 1996       
1302      <li> <a name="gmcl">       K. Czarnecki and U.W. Eisenecker, "Generative programming", Addison-Wesley, 2000       
1303      <li> <a name="blitz">      <a href=http://www.oonumerics.org/blitz/> http://www.oonumerics.org/blitz/ </A>     
1304      <li> <a name="initializer"> 
1305          Gabriel Dos Reis and Bjarne Stroustrup,
1306          <a href=http://anubis.dkuug.dk/jtc1/sc22/wg21/docs/papers/2003/n1509.pdf> "Generalized Initializer
1307            Lists"</a>, 2003  </a>
1308 </OL> 
1309 </p>
1310  <hr>
1311  <p>
1312    (C) Copyright Thorsten Ottosen 2003-2004
1313  </p>
1314
1315  <br>
1316  <br>
1317  <br>
1318  <br>
1319  <br>
1320  <br>
1321  <br>
1322  <br>
1323  <br>
1324  <br>
1325  <br>
1326  <br>
1327</body>
1328</html>
Note: See TracBrowser for help on using the repository browser.