1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 3.2//EN">
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">
14 <td ><img src=
"../../../boost.png" border=
"0" ></td>
16 <h1 align=
"center">Assignment Library
</h1>
22 Copyright ©
2003-
2006 Thorsten Ottosen
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>).
29 <h3>Table of Contents
</h3>
31 <li><a href=
"#intro">Introduction
</a></li>
33 <a href=
"#tutorial" >Tutorial
</a>
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>,
<code>repeat_fun()
</code> and
<code>range()
</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>,
44 <code>ptr_insert()
</code> and
<code>ptr_map_insert()
</code></a>
45 <li>Function
<a href=
"#ptr_list_of"><code>ptr_list_of()
</code></a>
48 <a href=
"#reference">Reference
</a>
50 <li><a href=
"#headers">Headers
</a> </li>
51 <li><a href=
"#std">Standard containers
</a> </li>
52 <li>Functions
<a href=
"#list_of_ref"><code>list_of()
</code> and
<code>map_list_of()
</code></a></li>
53 <li>Functions
<a href=
"#repeat_ref"><code>repeat()
</code>,
54 <code>repeat_fun()
</code> and
<code>range()
</code> </a> </li>
55 <li>Class
<a href=
"#list_inserter"><code>list_inserter
</code></a></li>
56 <li>Function
<a href=
"#make_list_inserter"><code>make_list_inserter()
</code></a></li>
57 <li><a href=
"#limit"> Customizing
</a> argument list sizes
</li>
59 <li> <a href=
"#exceptions">Exceptions and exception-safety
</a></li>
60 <li> <a href=
"#extensions">Extending the library
</a>
61 <li> <a href=
"#boost_libs">Supported libraries
</a>
62 <li> <a href=
"#examples">Examples
</a></li> <ul></ul>
63 <li><a href=
"#portability">Portability
</a></li>
64 <li><a href=
"#history">History and Acknowledgment
</a>
65 <li><a href=
"#ref">References
</a></li>
71 <h2><a name=
"intro">Introduction
</a></h2> <p> <i>There appear to be few
72 practical uses of
<code>operator,()
</code></i>.
<!-- p. 247 --> <br><b>Bjarne
73 Stroustrup
</b>, The Design and Evolution of C++
</p> <p> The purpose of this
74 library is to make it easy to fill containers with data by overloading
75 <code>operator,()
</code> and
<code>operator()()
</code>. These two operators
76 make it possible to construct lists of values that are then copied into a
77 container:
</p> <ul> <li> A comma-separated list:
<p>
78 <!-- vector< int > v; v += 1,2,3,4,5,6,7,8,9; -->
81 class=identifier
>vector
</span><span class=special
><
</span><span
82 class=keyword
>int
</span><span class=special
>></span><span
83 class=identifier
> v
</span><span class=special
>;
</span>
84 <span class=identifier
>v
</span><span class=special
>+=
</span><span
85 class=number
>1</span><span
86 class=special
>,
</span><span class=number
>2</span><span
87 class=special
>,
</span><span class=number
>3</span><span
88 class=special
>,
</span><span class=number
>4</span><span
89 class=special
>,
</span><span class=number
>5</span><span
90 class=special
>,
</span><span class=number
>6</span><span
91 class=special
>,
</span><span class=number
>7</span><span
92 class=special
>,
</span><span class=number
>8</span><span
93 class=special
>,
</span><span class=number
>9</span><span class=special
>;
</span></pre></p>
94 <li> A parenthesis-separated list:
97 <span class=identifier
>map
</span><span class=special
><
</span><span
98 class=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>
99 <span class=identifier
>insert
</span><span class=special
>(
</span><span class=identifier
>m
</span><span class=special
>)(
</span><span class=string
>"Bar
"</span><span class=special
>,
</span><span class=number
>1 </span><span class=special
>)(
</span><span class=string
>"Foo
"</span><span class=special
>,
</span><span class=number
>2 </span><span class=special
>);
</span></pre>
102 These lists are particularly useful in
103 learning, testing, and prototyping situations, but can also be handy otherwise.
104 The library comes with predefined operators for the containers of the
105 standard library, but most functionality will work with any standard
106 compliant container. The library also makes it possible to extend user
107 defined types so for example a member function can be called for a list of
108 values instead of its normal arguments.
</p>
111 <a name=
"tutorial"></a>
114 Within two minutes you should be able to use this library. The main
115 components are explained in these sections:
117 <li>Function
<a href=
"#operator+="><code>operator+=()
</code></a>
118 <li>Function
<a href=
"#operator()"><code>operator()()
</code></a>
119 <li>Function
<a href=
"#list_of"><code>list_of()
</code></a>
120 <li>Function
<a href=
"#map_list_of"><code>map_list_of()
</code></a>
121 <li>Function
<a href=
"#tuple_list_of"><code>tuple_list_of()
</code></a>
122 <li>Functions
<a href=
"#repeat"><code>repeat()
</code>,
<code>repeat_fun()
</code> and
<code>range()
</code> </a>
123 <li>Functions
<a href=
"#ref_list_of"><code>ref_list_of()
</code> and
<code>cref_list_of()
</code></a>
124 <li>A
<a href=
"#complicated">"complicated"</a> example
125 <li>Functions
<a href=
"#ptr_push_back"><code>ptr_push_back(), ptr_push_front()
</code>,
<code>ptr_insert()
</code> and
<code>ptr_map_insert()
</code></a>
126 <li>Function
<a href=
"#ptr_list_of"><code>ptr_list_of()
</code></a>
129 The two first functions are used for adding elements after a container object
130 has been created whereas the next two is used when we need to initialize an
132 <h3>Function
<code>operator+=()
</code><a name=
"operator+="></h3>
134 To fill a vector (or any standard container) with values using
135 <code>operator+=()
</code> you write
137 <span class=preprocessor
>#include
</span><span class=special
><</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
>> </span><span class=comment
>// for 'operator+=()'
138 </span><span class=preprocessor
>#include
</span><span class=special
><</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
>>;
139 </span><span class=keyword
>using
</span><span class=keyword
>namespace
</span><span class=identifier
>std
</span><span class=special
>;
140 </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
141 </span><span class=special
>
142 </span><span class=special
>{
143 </span><span class=identifier
>vector
</span><span class=special
><</span><span class=keyword
>int
</span><span class=special
>> </span><span class=identifier
>values
</span><span class=special
>;
144 </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
145 </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
>);
146 </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
>);
147 </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
>);
148 </span><span class=special
>}
</span></pre></blockquote>
150 Here we only stuffed constants into the container, but the list can
151 consists of arbitrary expressions as long as the result of each
152 expression is convertible to the
<code>value_type
</code> of the container.
156 <h3>Function
<code>operator()()
</code> <a name=
"operator()"></h3>
158 We do not call
<code>operator()()
</code> directly, but instead we call a
159 function that returns a proxy-object that defines
<code>operator()()
</code>.
160 The function that returns the proxy object is always named after the member
161 function that is used to copy the values in the list into the container.
162 So to fill a map with pairs of values you write
164 <span class=preprocessor
>#include
</span><span class=special
><</span><span
165 class=identifier
>boost
</span><span class=special
>/
</span><span
166 class=identifier
>assign
</span><span class=special
>/
</span><span
167 class=identifier
>list_inserter
</span><span class=special
>.
</span><span
168 class=identifier
>hpp
</span><span class=special
>> </span><span class=comment
>// for 'insert()'
169 </span><span class=preprocessor
>#include
</span><span class=special
><</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
>>
170 </span><span class=preprocessor
>#include
</span><span class=special
><</span><span class=identifier
>string
</span><span class=special
>>
171 </span><span class=keyword
>using
</span><span class=keyword
>namespace
</span><span class=identifier
>std
</span><span class=special
>;
172 </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
173 </span><span class=special
>
174 </span><span class=special
>{
175 </span><span class=identifier
>map
</span><span class=special
><</span><span class=identifier
>string
</span><span class=special
>,
</span><span class=keyword
>int
</span><span class=special
>> </span><span class=identifier
>months
</span><span class=special
>;
176 </span><span class=identifier
>insert
</span><span class=special
>(
</span><span class=identifier
>months
</span><span class=special
>)
177 </span><span class=special
>(
</span><span class=string
>"january
"</span><span class=special
>,
</span><span class=number
>31 </span><span class=special
>)(
</span><span class=string
>"february
"</span><span class=special
>,
</span><span class=number
>28 </span><span class=special
>)
178 </span><span class=special
>(
</span><span class=string
>"march
"</span><span class=special
>,
</span><span class=number
>31 </span><span class=special
>)(
</span><span class=string
>"april
"</span><span class=special
>,
</span><span class=number
>30 </span><span class=special
>)
179 </span><span class=special
>(
</span><span class=string
>"may
"</span><span class=special
>,
</span><span class=number
>31 </span><span class=special
>)(
</span><span class=string
>"june
"</span><span class=special
>,
</span><span class=number
>30 </span><span class=special
>)
180 </span><span class=special
>(
</span><span class=string
>"july
"</span><span class=special
>,
</span><span class=number
>31 </span><span class=special
>)(
</span><span class=string
>"august
"</span><span class=special
>,
</span><span class=number
>31 </span><span class=special
>)
181 </span><span class=special
>(
</span><span class=string
>"september
"</span><span class=special
>,
</span><span class=number
>30 </span><span class=special
>)(
</span><span class=string
>"october
"</span><span class=special
>,
</span><span class=number
>31 </span><span class=special
>)
182 </span><span class=special
>(
</span><span class=string
>"november
"</span><span class=special
>,
</span><span class=number
>30 </span><span class=special
>)(
</span><span class=string
>"december
"</span><span class=special
>,
</span><span class=number
>31 </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
184 class=identifier
>size
</span><span class=special
>()
</span><span class=special
>==
</span><span class=number
>12 </span><span class=special
>);
185 </span><span class=identifier
>BOOST_ASSERT
</span><span class=special
>(
</span><span class=identifier
>months
</span><span class=special
>[
</span><span class=string
>"january
"</span><span class=special
>]
</span><span class=special
>==
</span><span class=number
>31 </span><span class=special
>);
186 </span><span class=special
>}
</span> </pre></blockquote>
188 Note that
<code>operator()()
</code> is much more handy when
189 we need to construct objects using several arguments
190 (up to five arguments are supported by default, but the limit can be
<a href=
"#limit">customized
</a>).
191 This is also true for sequences:
194 <span class=preprocessor
>#include
</span><span class=special
><</span><span
195 class=identifier
>boost
</span><span class=special
>/
</span><span
196 class=identifier
>assign
</span><span class=special
>/
</span>list_inserter
</span><span class=special
>.
</span><span class=identifier
>hpp
</span><span class=special
>> </span><span class=comment
>// for 'push_front()'
197 </span><span class=preprocessor
>#include
</span><span class=special
><</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
>>
198 </span><span class=preprocessor
>#include
</span><span class=special
><</span><span class=identifier
>string
</span><span class=special
>>
199 </span><span class=preprocessor
>#include
</span><span class=special
><</span><span class=identifier
>utility
</span><span class=special
>>
200 </span><span class=keyword
>using
</span><span class=keyword
>namespace
</span><span class=identifier
>std
</span><span class=special
>;
201 </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
202 </span><span class=special
>
203 </span><span class=special
>{
204 </span><span class=keyword
>typedef
</span><span class=identifier
>pair
</span><span class=special
>< </span><span class=identifier
>string
</span><span class=special
>,
</span><span class=identifier
>string
</span><span class=special
>> </span><span class=identifier
>str_pair
</span><span class=special
>;
205 </span><span class=identifier
>deque
</span><span class=special
><</span><span class=identifier
>str_pair
</span><span class=special
>> </span><span class=identifier
>deq
</span><span class=special
>;
206 </span><span class=identifier
>push_front
</span><span class=special
>(
</span><span class=identifier
>deq
</span><span class=special
>)(
</span><span class=string
>"foo
"</span><span class=special
>,
</span><span class=string
>"bar
"</span><span class=special
>)(
</span><span class=string
>"boo
"</span><span class=special
>,
</span><span class=string
>"far
" </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
>size
</span><span class=special
>()
</span><span class=special
>==
</span><span class=number
>2 </span><span class=special
>);
208 </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
>"boo
" </span><span class=special
>);
209 </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
>"bar
" </span><span class=special
>);
210 </span><span class=special
>}
</span></pre></blockquote>
212 Besides
<code>push_front()
</code> we could also have used
213 <code>push_back()
</code> if the container has a corresponding member
214 function. Empty parentheses can be used to insert default-constructed
215 objects, for example,
216 <code>push_front( deq )()()
</code> will insert two default-constructed
217 <code>str_pair
</code> objects.
</p>
220 If
<code>operator()()
</code> is too cumbersome to use with eg.
221 <code>push_front()
</code>we can also say
</p>
225 <span class=identifier
>deque
</span><span class=special
><</span><span class=keyword
>int
</span><span class=special
>> </span><span class=identifier
>di
</span><span class=special
>;
</span>
226 <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>
227 <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>
228 <span class=identifier
>BOOST_ASSERT
</span><span class=special
>(
</span><span
229 class=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>
233 Just to make it perfectly clear, the code above is not restricted to the
234 standard containers, but will work with all
<i>standard compliant
</i> containers
235 with the right member function. It is only
<code>operator+=()
</code> that has been restricted to
236 the standard containers.
</p>
238 <h3>Function
<code>list_of()
</code> <a name=
"list_of"></h3>
239 But what if we need to
<i>initialize
</i> a container? This is where
240 <code>list_of()
</code> comes into play. With
<code>list_of()
</code>
241 we can create anonymous lists that automatically converts to
244 <span class=preprocessor
>#include
</span><span class=special
><</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
>> </span><span class=comment
>// for 'list_of()'
245 </span><span class=preprocessor
>#include
</span><span class=special
><</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
>>
246 </span><span class=preprocessor
>#include
</span><span class=special
><</span><span class=identifier
>list
</span><span class=special
>>
247 </span><span class=preprocessor
>#include
</span><span class=special
><</span><span class=identifier
>stack
</span><span class=special
>>
248 </span><span class=preprocessor
>#include
</span><span class=special
><</span><span class=identifier
>string
</span><span class=special
>>
249 </span><span class=keyword
>using
</span><span class=keyword
>namespace
</span><span class=identifier
>std
</span><span class=special
>;
250 </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
251 </span><span class=special
>
252 </span><span class=special
>{
253 </span><span class=keyword
>const
</span><span class=identifier
>list
</span><span class=special
><</span><span class=keyword
>int
</span><span class=special
>> </span><span class=identifier
>primes
</span><span class=special
>=
</span><span class=identifier
>list_of
</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
>);
254 </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
>5 </span><span class=special
>);
255 </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
>);
256 </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
>2 </span><span class=special
>);
258 </span><span class=keyword
>const
</span><span
259 class=identifier
>stack
</span><span class=special
><</span><span
260 class=identifier
>string
</span><span class=special
>> </span><span
261 class=identifier
>names
</span><span class=special
>=
</span><span
262 class=special
></span><span class=identifier
>list_of
</span><span class=special
>(
</span><span class=string
>"Mr. Foo
" </span><span class=special
>)(
</span><span class=string
>"Mr. Bar
"</span><span class=special
>)(
</span><span class=string
>"Mrs. FooBar
" </span><span
263 class=special
>).
</span><span class=identifier
>to_adapter();
264 </span><span class=keyword
>const
</span><span
265 class=identifier
>stack
</span><span class=special
><</span><span
266 class=identifier
>string
</span><span class=special
>> </span><span
267 class=identifier
>names2
</span><span class=special
>=
</span><span
268 class=special
>(
</span><span class=identifier
>list_of
</span><span class=special
>(
</span><span class=string
>"Mr. Foo
" </span><span class=special
>),
</span><span class=string
>"Mr. Bar
"</span><span class=special
>,
</span><span class=string
>"Mrs. FooBar
" </span><span
269 class=special
>).
</span><span class=identifier
>to_adapter();
270 </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
>);
271 </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
>"Mrs. FooBar
" </span><span class=special
>);
272 </span><span class=special
>}
</span></pre></blockquote>
273 If we need to initialize a container adapter, we need to help the compiler a
274 little by calling
<code>to_adapter()
</code>. As the second example also shows,
275 we can use a comma-separated
276 list with
<code>list_of()
</code> if we add parenthesis around the
277 entire right hand side. It is worth noticing that the first argument
278 of
<code>list_of()
</code> determines the type of the anonymous list.
279 In case of the stack, the anonymous list consists of
280 <code>const char*
</code> objects which are then converted to
281 a stack of
<code>string
</code> objects. The conversion is always
282 possible as long as the conversion between the stored types is possible.
285 Please notice that
<code>list_of()
</code> can even convert to a
287 href=
"../../array/index.html">array
</a><T,sz
></code> and see also the list
288 of
<a href=
"#boost_libs">supported libraries
</a>.
</p>
290 Note that the type returned by
291 <code>list_of()
</code> (and its variants) has overloaded comparison operators. This allows you to
292 write test code such as
294 BOOST_CHECK_EQUAL( my_container, list_of(
2)(
3)(
4)(
5) );.
298 <h3>Function
<code>map_list_of()
</code> <a name=
"map_list_of"></h3>
299 This function is defined for pure convenience when working with
300 maps. Its usage is simple:
302 <span class=preprocessor
>#include
</span><span class=special
><</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
>> </span><span class=comment
>// for 'map_list_of()'
303 </span><span class=preprocessor
>#include
</span><span class=special
><</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
>>
304 </span><span class=preprocessor
>#include
</span><span class=special
><</span><span class=identifier
>map
</span><span class=special
>>
305 </span><span class=keyword
>using
</span><span class=keyword
>namespace
</span><span class=identifier
>std
</span><span class=special
>;
306 </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
307 </span><span class=special
>
308 </span><span class=special
>{
309 </span><span class=identifier
>map
</span><span class=special
><</span><span class=keyword
>int
</span><span class=special
>,
</span><span class=keyword
>int
</span><span class=special
>> </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
>);
310 </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
>);
311 </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
>);
312 </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
>);
314 </span><span class=comment
>// or we can use 'list_of()' by specifying what type
315 // the list consists of
316 </span><span class=identifier
>next
</span><span class=special
>=
</span><span class=identifier
>list_of
</span><span class=special
>< </span><span class=identifier
>pair
</span><span class=special
><</span><span class=keyword
>int
</span><span class=special
>,
</span><span class=keyword
>int
</span><span class=special
>> </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
>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
>);
317 </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
>);
318 </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
>);
319 </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
>);
320 </span><span class=special
>}
</span></pre></blockquote>
322 The function
<code>pair_list_of()
</code> may also be used.
324 <h3>Function
<code>tuple_list_of()
</code> <a name=
"tuple_list_of"></h3>
326 If you are working with tuples, it might be convenient to use
327 <code>tuple_list_of()
</code>:
332 <span class=preprocessor
>#include
</span><span class=special
><</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
>></span>
333 <span class=preprocessor
>#include
</span><span class=special
><</span><span class=identifier
>vector
</span><span class=special
>>
335 <span class=keyword
>using
</span><span class=keyword
>namespace
</span><span class=identifier
>std
</span><span class=special
>;
</span>
336 <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
>;
338 <span class=special
>{
339 </span><span class=keyword
>typedef
</span><span class=identifier
>boost
</span><span class=special
>::
</span><span class=identifier
>tuple
</span><span class=special
><</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
>> </span><span class=identifier
>tuple
</span><span class=special
>;
341 </span><span class=identifier
>vector
</span><span class=special
><</span><span class=identifier
>tuple
</span><span class=special
>> </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
>"foo
"</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
>"bar
"</span><span class=special
>,
</span><span class=number
>4 </span><span class=special
>);
342 </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
>);
343 </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
><</span><span class=number
>0</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=special
>)
</span><span class=special
>==
</span><span class=number
>3 </span><span class=special
>);
</span>
344 <span class=special
>}
</span>
348 <h3>Functions
<code>repeat()
</code>,
<code>repeat_fun()
</code> and
<code>range()
</code> <a name=
"repeat"></h3>
350 Sometimes it is too irritating to repeat the same value many times. This is
351 where
<code>repeat()
</code> can be handy:
354 <span class=preprocessor
>#include
</span><span class=special
><</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
>></span>
355 <span class=preprocessor
>#include
</span><span class=special
><</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
>></span>
356 <span class=preprocessor
>#include
</span><span class=special
><</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
>>
358 <span class=keyword
>using
</span><span class=keyword
>namespace
</span><span class=identifier
>std
</span><span class=special
>;
</span>
359 <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>
360 <span class=special
> </span>
361 <span class=special
>{
362 </span><span class=identifier
>vector
</span><span class=special
><</span><span class=keyword
>int
</span><span class=special
>> </span><span class=identifier
>v
</span><span class=special
>;
363 </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
>;
364 </span><span class=comment
>// v = [
1,
2,
3,
4,
4,
4,
4,
4,
4,
4,
4,
4,
4,
5,
6,
7,
8,
9]
365 </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
>);
367 </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
>);
368 </span><span class=comment
>// v = [
1,
2,
2,
2,
2,
2,
3]
369 </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
>);
371 </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
>);
372 </span><span class=comment
>// v = old v + [
1,
2,
3]
373 </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>
374 <span class=special
>}
</span></pre>
376 As we can see, then the first argument to
<code>repeat()
</code> is the number
377 of times to repeat the second argument.
380 A more general list can be constructed with
<code>repeat_fun()
</code>:
384 <span class=preprocessor
>#include
</span><span class=special
><</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
>></span>
385 <span class=preprocessor
>#include
</span><span class=special
><</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
>></span>
386 <span class=preprocessor
>#include
</span><span class=special
><</span><span class=identifier
>cstdlib
</span><span class=special
>> </span><span class=comment
>// for 'rand()'
388 <span class=keyword
>using
</span><span class=keyword
>namespace
</span><span class=identifier
>std
</span><span class=special
>;
</span>
389 <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>
390 <span class=special
> </span>
391 <span class=keyword
>template
</span><span class=special
>< </span><span class=keyword
>class
</span><span class=identifier
>T
</span><span class=special
>></span>
392 <span class=keyword
>struct
</span><span class=identifier
>next
</span>
393 <span class=special
>{
394 </span><span class=identifier
>T
</span><span class=identifier
>seed
</span><span class=special
>;
395 </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
>)
396 </span><span class=special
>{
</span><span class=special
>}
398 </span><span class=identifier
>T
</span><span class=keyword
>operator
</span><span class=special
>()()
</span><span class=keyword
>
399 </span><span class=special
>{
400 </span><span class=keyword
>return
</span><span class=identifier
>seed
</span><span class=special
>++;
401 </span><span class=special
>}
</span>
402 <span class=special
>};
</span>
403 <span class=special
> </span>
404 <span class=special
>{
405 </span><span class=identifier
>vector
</span><span class=special
><</span><span class=keyword
>int
</span><span class=special
>> </span><span class=identifier
>v
</span><span class=special
>;
406 </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
>,
&</span><span class=identifier
>rand
</span><span class=special
>),
</span><span class=number
>4</span><span class=special
>;
407 </span><span class=comment
>// v = [
1,
2,?,?,?,?,
4]
408 </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
>);
410 </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
><</span><span class=keyword
>int
</span><span class=special
>>(
</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
><</span><span class=keyword
>int
</span><span class=special
>>(
</span><span class=number
>5</span><span class=special
>));
411 </span><span class=comment
>// v = old v + [
0,
1,
2,
3,
4,
5,
6,
7,
8]
412 </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>
413 <span class=special
>}
</span> </pre>
415 The only requirement of the second argument to
<code>repeat_fun()
</code> is that
416 it is a nullary function.
</p>
420 If you just need to insert an iterator-range somewhere in the list, the member function
<code>range()
</code> provides just what you want.
421 It is based on
<a href=
"../../range/index.html">Boost.Range
</a>, so you can pass all the ranges supported by that library. For example
422 <blockquote><pre><span class=preprocessor
>#include
</span> <span class=special
><</span><span class=identifier
>boost
</span><span class=special
>/
</span><span class=identifier
>assign
</span><span class=special
>/
</span><span class=identifier
>list_inserter
</span><span class=special
>.
</span><span class=identifier
>hpp
</span><span class=special
>></span> <span class=comment
>// for 'push_back()'
</span>
423 <span class=preprocessor
>#include
</span> <span class=special
><</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
>></span> <span class=comment
>// for 'list_of()' and 'ref_list_of()'
</span>
424 <span class=preprocessor
>#include
</span> <span class=special
><</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
>></span>
426 <span class=keyword
>using
</span> <span class=keyword
>namespace
</span> <span class=identifier
>std
</span><span class=special
>;
</span>
427 <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>
429 <span class=special
>{
</span>
430 <span class=identifier
>vector
</span><span class=special
><</span><span class=keyword
>int
</span><span class=special
>></span> <span class=identifier
>v
</span><span class=special
>,
</span> <span class=identifier
>v2
</span><span class=special
>;
</span>
431 <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=number
>2</span><span class=special
>)(
</span><span class=number
>3</span><span class=special
>);
</span>
432 <span class=identifier
>v2
</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=identifier
>range
</span><span class=special
>(
</span><span class=identifier
>v
</span><span class=special
>).
</span><span class=identifier
>range
</span><span class=special
>(
</span><span class=identifier
>v
</span><span class=special
>.
</span><span class=identifier
>begin
</span><span class=special
>(),
</span><span class=identifier
>v
</span><span class=special
>.
</span><span class=identifier
>end
</span><span class=special
>())(
</span><span class=number
>4</span><span class=special
>);
</span>
433 <span class=comment
>// v2 = [
0,
1,
2,
3,
1,
2,
3,
4]
</span>
434 <span class=identifier
>BOOST_ASSERT
</span><span class=special
>(
</span> <span class=identifier
>v2
</span><span class=special
>.
</span><span class=identifier
>size
</span><span class=special
>()
</span> <span class=special
>==
</span> <span class=number
>8u</span> <span class=special
>);
</span>
436 <span class=identifier
>push_back
</span><span class=special
>(
</span> <span class=identifier
>v
</span> <span class=special
>).
</span><span class=identifier
>range
</span><span class=special
>(
</span><span class=identifier
>v2
</span><span class=special
>)(
</span><span class=number
>5</span><span class=special
>);
</span>
437 <span class=comment
>// v = [
1,
2,
3,
0,
1,
2,
3,
1,
2,
3,
4,
5]
</span>
438 <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
>12u</span> <span class=special
>);
</span>
440 <span class=comment
>//
441 // create a list of references, some coming from a container, others from the stack
443 <span class=keyword
>int
</span> <span class=identifier
>x
</span> <span class=special
>=
</span> <span class=number
>0</span><span class=special
>;
</span>
444 <span class=keyword
>int
</span> <span class=identifier
>y
</span> <span class=special
>=
</span> <span class=number
>1</span><span class=special
>;
</span>
445 <span class=identifier
>BOOST_ASSERT
</span><span class=special
>(
</span> <span class=identifier
>ref_list_of
</span><span class=special
><</span><span class=number
>10</span><span class=special
>>(
</span><span class=identifier
>x
</span><span class=special
>).
</span><span class=identifier
>range
</span><span class=special
>(
</span><span class=identifier
>v2
</span><span class=special
>)(
</span><span class=identifier
>y
</span><span class=special
>).
</span><span class=identifier
>size
</span><span class=special
>()
</span> <span class=special
>==
</span> <span class=number
>10u</span> <span class=special
>);
</span>
446 <span class=special
>}
</span></pre>
448 As you can see, one can also pass two iterators if that is more appropriate.
449 The last example also introduces list of references. More about that below.
452 <h3>Functions
<code>ref_list_of()
</code> and
<code>cref_list_of()
</code> <a name=
"ref_list_of"></h3>
454 When you need to create an anonymous range of values and speed is essential,
455 these two functions provide what you want.
<blockquote>
457 <span class=preprocessor
>#include
</span><span class=special
><</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
>></span>
458 <span class=preprocessor
>#include
</span><span class=special
><</span><span class=identifier
>algorithm
</span><span class=special
>>
460 <span class=comment
>//
461 // Define Range algorithm
463 <span class=keyword
>template
</span><span class=special
>< </span><span class=keyword
>class
</span><span class=identifier
>Range
</span><span class=special
>></span>
464 <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
>& </span><span class=identifier
>r
</span><span class=special
>)
</span>
465 <span class=special
>{
466 </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>
467 <span class=special
>}
469 <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
>;
471 <span class=special
>{
472 </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
>;
473 </span><span class=keyword
>int
</span><span class=special
>& </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
><</span><span class=number
>8</span><span class=special
>>(
</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
>);
474 </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
>);
475 </span><span class=identifier
>max
</span><span class=special
>=
</span><span class=number
>8</span><span class=special
>;
476 </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
>);
477 </span><span class=keyword
>const
</span><span class=keyword
>int
</span><span
478 class=special
>& </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
><</span><span class=number
>8</span><span class=special
>>(
</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
>);
479 </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>
480 <span class=special
>}
</span>
484 You can only use lvalues with
<code>ref_list_of()
</code> while
485 <code>cref_list_of()
</code> accepts rvalues too. Do not worry about not
486 specifying exactly the right size; the extra space used is minimal and there
487 is no runtime overhead associated with it.
489 You may also use these functions instead of
<code>list_of()
</code> if speed is
492 <h3>A
"complicated" example
<a name=
"complicated"></h3>
494 As a last example, let us assume that we need to keep track of the
495 result of soccer matches. A team will get one point if it wins
496 and zero otherwise. If there has been played three games in each group, the code might look
501 <span class=preprocessor
>#include
</span><span class=special
><</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
>></span>
502 <span class=preprocessor
>#include
</span><span class=special
><</span><span
503 class=identifier
>boost
</span><span class=special
>/
</span><span
504 class=identifier
>assign
</span><span class=special
>/
</span><span
505 class=identifier
>list_inserter
</span><span class=special
>.
</span><span
506 class=identifier
>hpp
</span><span class=special
>></span>
507 <span class=preprocessor
>#include
</span><span class=special
><</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
>></span>
508 <span class=preprocessor
>#include
</span><span class=special
><</span><span class=identifier
>string
</span><span class=special
>></span>
509 <span class=preprocessor
>#include
</span><span class=special
><</span><span class=identifier
>vector
</span><span class=special
>>
511 <span class=keyword
>using
</span><span class=keyword
>namespace
</span><span class=identifier
>std
</span><span class=special
>;
</span>
512 <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
>;
514 <span class=special
>{
515 </span><span class=keyword
>typedef
</span><span class=identifier
>vector
</span><span class=special
><</span><span class=keyword
>int
</span><span class=special
>> </span><span class=identifier
>score_type
</span><span class=special
>;
516 </span><span class=keyword
>typedef
</span><span class=identifier
>map
</span><span class=special
><</span><span class=identifier
>string
</span><span class=special
>,
</span><span class=identifier
>score_type
</span><span class=special
>> </span><span class=identifier
>team_score_map
</span><span class=special
>;
517 </span><span class=keyword
>typedef
</span><span class=identifier
>pair
</span><span class=special
><</span><span class=identifier
>string
</span><span class=special
>,
</span><span class=identifier
>score_type
</span><span class=special
>> </span><span class=identifier
>score_pair
</span><span class=special
>;
519 </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
>;
521 </span><span class=comment
>//
522 // method
1: using 'insert()'
524 </span><span class=identifier
>insert
</span><span class=special
>(
</span><span class=identifier
>group1
</span><span class=special
>)(
</span><span class=string
>"Denmark
"</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
>)
525 </span><span class=special
>(
</span><span class=string
>"Germany
"</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
>)
526 </span><span class=special
>(
</span><span class=string
>"England
"</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
>);
527 </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
>);
528 </span><span class=identifier
>BOOST_ASSERT
</span><span class=special
>(
</span><span class=identifier
>group1
</span><span class=special
>[
</span><span class=string
>"Denmark
" </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
>);
529 </span><span class=identifier
>BOOST_ASSERT
</span><span class=special
>(
</span><span class=identifier
>group1
</span><span class=special
>[
</span><span class=string
>"Germany
" </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
>);
531 </span><span class=comment
>//
532 // method
2: using 'list_of()'
534 </span><span class=identifier
>group2
</span><span class=special
>=
</span><span class=identifier
>list_of
</span><span class=special
>< </span><span class=identifier
>score_pair
</span><span class=special
>>
535 </span><span class=special
>(
</span><span class=string
>"Norway
"</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
>)
536 </span><span class=special
>(
</span><span class=string
>"USA
"</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
>)
537 </span><span class=special
>(
</span><span class=string
>"Andorra
"</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
>);
538 </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
>);
539 </span><span class=identifier
>BOOST_ASSERT
</span><span class=special
>(
</span><span class=identifier
>group2
</span><span class=special
>[
</span><span class=string
>"Norway
" </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
>);
540 </span><span class=identifier
>BOOST_ASSERT
</span><span class=special
>(
</span><span class=identifier
>group2
</span><span class=special
>[
</span><span class=string
>"USA
" </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>
541 <span class=special
>}
</span>
545 In the first example, notice how the result of
<code>list_of()
</code>
546 can be converted automatically to a
<code>vector
<int
></code> because
547 <code>insert()
</code> knows it expects a
<code>vector
<int
></code>.
548 In the second example we can see that
<code>list_of()
</code> is somewhat
549 less intelligent since here it needs to be told explicitly what arguments to
550 expect. (In the future it might be possible to introduce a more intelligent
551 conversion layer in
<code>list_of()
</code>.)
554 <h3>Functions
<code>ptr_push_back(),
555 ptr_push_front()
</code>,
<code>ptr_insert()
</code> and
<code>ptr_map_insert()
</code> <a name=
"ptr_push_back"></h3>
557 For use with
<a href=
"../../ptr_container/index.html">Boost.Pointer Container
</a>
558 a few special exception-safe functions are provided. Using these function you
559 do not need to call
<code>new
</code> manually:
564 <span class=preprocessor
>#include
</span> <span class=special
><</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
>></span> <span class=comment
>// for 'ptr_push_back()', 'ptr_insert()' and 'ptr_push_front()'
</span>
565 <span class=preprocessor
>#include
</span> <span class=special
><</span><span class=identifier
>boost
</span><span class=special
>/
</span><span class=identifier
>assign
</span><span class=special
>/
</span><span class=identifier
>ptr_map_inserter
</span><span class=special
>.
</span><span class=identifier
>hpp
</span><span class=special
>></span> <span class=comment
>// for 'ptr_map_insert()'
</span>
566 <span class=preprocessor
>#include
</span> <span class=special
><</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
>></span>
567 <span class=preprocessor
>#include
</span> <span class=special
><</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
>></span>
568 <span class=preprocessor
>#include
</span> <span class=special
><</span><span class=identifier
>boost
</span><span class=special
>/
</span><span class=identifier
>ptr_container
</span><span class=special
>/
</span><span class=identifier
>ptr_map
</span><span class=special
>.
</span><span class=identifier
>hpp
</span><span class=special
>></span>
570 <span class=comment
>//
573 <span class=keyword
>struct
</span> <span class=identifier
>Foo
</span>
574 <span class=special
>{
</span>
575 <span class=keyword
>int
</span> <span class=identifier
>i
</span><span class=special
>;
</span>
577 <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
>)
</span>
578 <span class=special
>{
</span> <span class=special
>}
</span>
579 <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
>)
</span>
580 <span class=special
>{
</span> <span class=special
>}
</span>
581 <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
>)
</span>
582 <span class=special
>{
</span> <span class=special
>}
</span>
583 <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
>)
</span>
584 <span class=special
>{
</span> <span class=special
>}
</span>
586 <span class=keyword
>virtual
</span> <span class=special
>~
</span><span class=identifier
>Foo
</span><span class=special
>()
</span>
587 <span class=special
>{}
</span>
588 <span class=special
>};
</span>
590 <span class=keyword
>struct
</span> <span class=identifier
>Bar
</span> <span class=special
>:
</span> <span class=identifier
>Foo
</span>
591 <span class=special
>{
</span>
592 <span class=identifier
>Bar
</span><span class=special
>()
</span>
593 <span class=special
>{
</span> <span class=special
>}
</span>
595 <span class=identifier
>Bar
</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
>Foo
</span><span class=special
>(
</span> <span class=number
>42</span> <span class=special
>)
</span>
596 <span class=special
>{
</span> <span class=special
>}
</span>
597 <span class=special
>};
</span>
599 <span class=comment
>//
600 // Required by ptr_set
<Foo
>
602 <span class=keyword
>inline
</span> <span class=keyword
>bool
</span> <span class=keyword
>operator
</span><span class=special
><(
</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>
603 <span class=special
>{
</span>
604 <span class=keyword
>return
</span> <span class=identifier
>l
</span><span class=special
>.
</span><span class=identifier
>i
</span> <span class=special
><</span> <span class=identifier
>r
</span><span class=special
>.
</span><span class=identifier
>i
</span><span class=special
>;
</span>
605 <span class=special
>}
</span>
608 <span class=keyword
>using
</span> <span class=keyword
>namespace
</span> <span class=identifier
>boost
</span><span class=special
>;
</span>
609 <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>
611 <span class=keyword
>int
</span> <span class=identifier
>main
</span><span class=special
>()
</span>
612 <span class=special
>{
</span>
613 <span class=identifier
>ptr_deque
</span><span class=special
><</span><span class=identifier
>Foo
</span><span class=special
>></span> <span class=identifier
>deq
</span><span class=special
>;
</span>
614 <span class=identifier
>ptr_push_back
</span><span class=special
>(
</span> <span class=identifier
>deq
</span> <span class=special
>)()();
</span>
615 <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
>2u</span> <span class=special
>);
</span>
616 <span class=identifier
>ptr_push_back
</span><span class=special
><</span><span class=identifier
>Bar
</span><span class=special
>>(
</span> <span class=identifier
>deq
</span> <span class=special
>)()();
</span> <span class=comment
>// insert 'Bar' objects
</span>
617 <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
>4u</span> <span class=special
>);
</span>
618 <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
>"foo
"</span><span class=special
>,
</span> <span class=number
>42</span><span class=special
>,
</span> <span class=number
>42</span> <span class=special
>);
</span>
619 <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
>7u</span> <span class=special
>);
</span>
621 <span class=identifier
>ptr_set
</span><span class=special
><</span><span class=identifier
>Foo
</span><span class=special
>></span> <span class=identifier
>a_set
</span><span class=special
>;
</span>
622 <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
>"foo
"</span><span class=special
>,
</span> <span class=number
>3</span><span class=special
>,
</span> <span class=number
>3</span> <span class=special
>);
</span>
623 <span class=identifier
>BOOST_ASSERT
</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
>4u</span> <span class=special
>);
</span>
624 <span class=identifier
>ptr_insert
</span><span class=special
>(
</span> <span class=identifier
>a_set
</span> <span class=special
>)()()()();
</span>
625 <span class=identifier
>BOOST_ASSERT
</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
>4u</span> <span class=special
>);
</span> <span class=comment
>// duplicates not inserted
</span>
626 <span class=identifier
>ptr_insert
</span><span class=special
><</span><span class=identifier
>Bar
</span><span class=special
>>(
</span> <span class=identifier
>a_set
</span> <span class=special
>)(
</span> <span class=number
>42</span> <span class=special
>);
</span> <span class=comment
>// insert a 'Bar' object
</span>
627 <span class=identifier
>BOOST_ASSERT
</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
>5u</span> <span class=special
>);
</span>
629 <span class=identifier
>ptr_map
</span><span class=special
><</span><span class=keyword
>int
</span><span class=special
>,
</span><span class=identifier
>Foo
</span><span class=special
>></span> <span class=identifier
>a_map
</span><span class=special
>;
</span>
630 <span class=identifier
>ptr_map_insert
</span><span class=special
>(
</span> <span class=identifier
>a_map
</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
>3</span> <span class=special
>)(
</span> <span class=number
>4</span><span class=special
>,
</span> <span class=string
>"foo
"</span><span class=special
>,
</span> <span class=number
>4</span><span class=special
>,
</span> <span class=number
>4</span> <span class=special
>);
</span>
631 <span class=identifier
>ptr_map_insert
</span><span class=special
><</span><span class=identifier
>Bar
</span><span class=special
>>(
</span> <span class=identifier
>a_map
</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=comment
>// insert a 'Bar' object
</span>
632 <span class=special
>}
</span>
636 Notice how you may provide a template argument to these functions. This argument determines the type to allocate with
<code>new
</code>.
637 You have to specify this argument when the container is based on an abstract type (because one cannot create objects of such a type).
640 For
<code>ptr_map_insert()
</code> the first argument
<code>arg1
</code> in an argument tuple
<code>(arg1,arg2,...,argN)
</code> is used to
641 construct a key; this means that the first argument need only be convertible to the
<code>key_type
</code> of the container.
642 The rest of the arguments are used to construct the mapped object.
645 <h3>Function
<code>ptr_list_of()
</code> <a name=
"ptr_list_of"></h3>
647 Just like you can use
<code>list_of()
</code> to initialize containers, you can
648 use
<code>ptr_list_of()
</code> to initialize a
<a href=
"../../ptr_container/index.html">pointer container
</a>.
649 Here is a small example:
653 <span class=preprocessor
>#include
</span><span class=special
><</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
>></span>
654 <span class=preprocessor
>#include
</span><span class=special
><</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
>>
656 <span class=keyword
>using
</span><span class=keyword
>namespace
</span><span class=identifier
>boost
</span><span class=special
>;
</span>
657 <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
>;
659 <span class=special
>{
660 </span><span class=identifier
>ptr_deque
</span><span class=special
><</span><span class=identifier
>Foo
</span><span class=special
>> </span><span class=identifier
>deq
</span><span class=special
>;
661 </span><span class=identifier
>deq
</span><span class=special
>=
</span><span class=identifier
>ptr_list_of
</span><span class=special
><</span><span class=identifier
>Foo
</span><span class=special
>>(
</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
>"foo
"</span><span class=special
>,
</span><span class=number
>2</span><span class=special
>,
</span><span class=number
>1 </span><span class=special
>);
662 </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>
663 <span class=special
>}
</span>
667 Notice that a trailing
<code>.to_container(deq)
</code> may be added to help many poor
668 compilers to figure out the conversion (a few get it right).
669 Notice also that pointer maps are
673 That is all; now you are ready to use this library.
677 <h2><a name=
"reference">Reference
</a></h2>
679 It is worth noticing the way the library is implemented.
680 A free-standing function (eg.
<code>push_back()
</code>
681 or
<code>operator+=()
</code>) returns a proxy
682 object which is responsible for the insertion or the assignment. The proxy
683 object does the insertion or assignment by overloading
<code>operator,()
</code>
684 and
<code>operator()()
</code> and by calling the
"insert" function from within
685 those operators. The
"insert" function is typically stored in the proxy object
686 by using
<code>boost::
<a href=
"../../function/index.html">function
</a></code>.
</p>
690 of
<code>operator,()
</code> is discouraged because it can lead to surprising
691 results, but the approach taken in this library is safe since the
692 user never deals with objects that have overloaded
<code>operator,()
</code>
693 directly. However, you should be aware of this:
698 expressions in a comma-separated list no longer follow the rules of the
699 built-in comma-operator. This means that the order of evaluation of
700 expressions in a comma-separated list is undefined like when one specifies
701 a list of function arguments.
705 Most of the code in this document use
<code>int
</code> in the examples,
706 but of course it works for arbitrary types as long as they are
707 Copy Constructible. The inserted data need not be constant data,
708 but can be variables or data returned from functions; the only requirement
709 is that the type of the data is convertible to the type stored in the
714 All forwarding is done by passing objects by
<code>const
</code> reference.
715 Originally arguments were passed by value (and still is in
716 <code>tuple_list_of()
</code>). One thing to remember is that references
717 can be passed by using
<code>boost::
<a href=
"http://www.boost.org/doc/html/ref.html">ref
</a></code>.
721 Everything is put in namespace
722 <code>boost::assign
</code>.
</p>
724 <p> More details can be found below:
</p>
727 <li><a href=
"#headers">Headers
</a> </li>
728 <li><a href=
"#std">Standard containers
</a> </li>
729 <li>Functions
<a href=
"#list_of_ref"><code>list_of()
</code> and
<code>map_list_of()
</code></a></li>
730 <li>Functions
<a href=
"#repeat_ref"><code>repeat()
</code>,
<code>repeat_fun()
</code> and
733 <li>Class
<a href=
"#list_inserter"><code>list_inserter
</code></a></li>
734 <li>Function
<a href=
"#make_list_inserter"><code>make_list_inserter()
</code></a></li>
735 <li><a href=
"#limit">Customizing
</a> argument list sizes
</li>
737 <h3>Headers
<a name=
"headers"></h3>
740 An overview of the headers in this library
741 is given below. Please notice
<code><boost/assign/list_inserter.hpp
></code>
742 is included for each header that defines
<code>operator+=()
</code>.
</p>
744 <table cellpadding=
5 border=
1 > <tr>
748 <td> <boost/assign.hpp
> </td>
749 <td> everything except support for pointer containers
</td>
751 <td> <boost/assign/list_of.hpp
> </td>
752 <td> <a href=
"#list_of"><code>list_of()
</a>,
<a
753 href=
"#map_list_of">map_list_of()
</code></a>,
754 <a href=
"#tuple_list_of">tuple_list_of()
</code></a>,
755 <a href=
"#ref_list_of">ref_list_of()
</code> and
756 <code>cref_list_of()
</code></a>
759 <td> <boost/assign/std.hpp
> </td>
760 <td> <a href=
"#operator+="><code>operator+=()
</code></a> for all
762 containers (see below)
</td> <tr> <td> <boost/assign/std/deque.hpp
> </td>
763 <td> <code>operator+=()
</code> for
764 <code>std::deque
</code>,
<code><deque
></code>
766 <td> <boost/assign/std/list.hpp
> </td>
767 <td> <code>operator+=()
</code> for
768 <code>std::list
</code>,
<code><list
></code>
770 <td> <boost/assign/std/map.hpp
> </td>
771 <td> <code>operator+=()
</code> for
772 <code>std::map
</code> and
<code>std::multimap
</code> ,
773 <code><map
></code> <tr>
774 <td> <boost/assign/std/queue.hpp
> </td>
775 <td> <code>operator+=()
</code> for
776 <code>std::queue
</code> and
<code>std::priority_queue
</code>,
777 <code><queue
></code> <tr>
778 <td> <boost/assign/std/set.hpp
> </td>
779 <td> <code>operator+=()
</code> for
780 <code>std::set
</code> and
<code>std::multiset
</code>,
781 <code><set
></code> <tr>
782 <td> <boost/assign/std/slist.hpp
> </td>
783 <td> <code>operator+=()
</code> for
784 <code>std::slist
</code> if the class is available ,
785 <code><slist
></code> <tr>
786 <td> <boost/assign/std/stack.hpp
> </td>
787 <td> <code>operator+=()
</code> for
788 <code>std::stack
</code>,
<code><stack
></code>
790 <td> <boost/assign/std/vector.hpp
> </td>
791 <td> <code>operator+=()
</code> for
792 <code>std::vector
</code>,
<code><vector
></code>
794 <td> <boost/assign/assignment_exception.hpp
> </td>
796 href=
"#assignment_exception"><code>assignment_exception
</code></a> which might
797 be thrown by the proxy returned by
<code>list_of()
</code>
799 <td> <boost/assign/list_inserter.hpp
> </td>
801 href=
"#make_list_inserter"><code>make_list_inserter()
</code></a>,
<code>push_back()
</code>,
802 <code>push_front()
</code>,
<code>insert()
</code>,
804 push()
</code> and class
<a href=
"#list_inserter"><code>list_inserter
</code></a>
805 which is the back-bone of this entire library.
808 <td> <boost/assign/ptr_list_inserter.hpp
> </td>
809 <td>Functions
<a href=
"#ptr_push_back"><code>ptr_push_back()
</code></a>,
810 <code>ptr_push_front()
</code> and
<code>ptr_insert()
</code>
813 <td> <boost/assign/ptr_map_inserter.hpp
> </td>
814 <td>Functions
<a href=
"#ptr_push_back"><code>ptr_map_insert()
</code></a>
817 <td> <boost/assign/ptr_list_of.hpp
> </td>
818 <td>Function
<a href=
"#ptr_list_of"><code>ptr_list_of()
</code></a>
822 <h3>Standard containers
<a name=
"std"> </h3>
823 <p> In the following three dots (...) will mean
824 implementation defined.
825 <code>operator+=()
</code> returns a proxy that forwards calls to either
826 <code>push_back()
</code>,
<code>insert()
</code>, or
<code>push()
</code>
827 depending on which operation the container supports.
</p> <b>Synopsis
</b>
831 <span class=keyword
>namespace
</span><span class=identifier
>boost
</span>
832 <span class=special
>{
</span>
833 <span class=keyword
>namespace
</span><span class=identifier
>assign
</span>
834 <span class=special
>{
835 </span><span class=keyword
>template
</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
>A
</span><span class=special
>,
</span><span class=keyword
>class
</span><span class=identifier
>V2
</span><span class=special
>>
836 </span><span class=identifier
>list_inserter
</span><span class=special
>< </span><span class=special
>...
</span><span class=special
>> </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
><</span><span class=identifier
>V
</span><span class=special
>,
</span><span class=identifier
>A
</span><span class=special
>>& </span><span class=identifier
>c
</span><span class=special
>,
</span><span class=identifier
>V2
</span><span class=identifier
>v
</span><span class=special
>);
838 </span><span class=keyword
>template
</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
>A
</span><span class=special
>,
</span><span class=keyword
>class
</span><span class=identifier
>V2
</span><span class=special
>>
839 </span><span class=identifier
>list_inserter
</span><span class=special
>< </span><span class=special
>...
</span><span class=special
>> </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
><</span><span class=identifier
>V
</span><span class=special
>,
</span><span class=identifier
>A
</span><span class=special
>>& </span><span class=identifier
>c
</span><span class=special
>,
</span><span class=identifier
>V2
</span><span class=identifier
>v
</span><span class=special
>);
841 </span><span class=keyword
>template
</span><span class=special
>< </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
>>
842 </span><span class=identifier
>list_inserter
</span><span class=special
>< </span><span class=special
>...
</span><span class=special
>> </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
><</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
>>& </span><span class=identifier
>m
</span><span class=special
>,
</span><span class=keyword
>const
</span><span class=identifier
>P
</span><span class=special
>& </span><span class=identifier
>p
</span><span class=special
>);
844 </span><span class=keyword
>template
</span><span class=special
>< </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
>>
845 </span><span class=identifier
>list_inserter
</span><span class=special
>< </span><span class=special
>...
</span><span class=special
>> </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
><</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
>>& </span><span class=identifier
>m
</span><span class=special
>,
</span><span class=keyword
>const
</span><span class=identifier
>P
</span><span class=special
>& </span><span class=identifier
>p
</span><span class=special
>);
847 </span><span class=keyword
>template
</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
>V2
</span><span class=special
>>
848 </span><span class=identifier
>list_inserter
</span><span class=special
>< </span><span class=special
>...
</span><span class=special
>> </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
><</span><span class=identifier
>V
</span><span class=special
>,
</span><span class=identifier
>C
</span><span class=special
>>& </span><span class=identifier
>c
</span><span class=special
>,
</span><span class=identifier
>V2
</span><span class=identifier
>v
</span><span class=special
>);
850 </span><span class=keyword
>template
</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
>V2
</span><span class=special
>>
851 </span><span class=identifier
>list_inserter
</span><span class=special
>< </span><span class=special
>...
</span><span class=special
>> </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
><</span><span class=identifier
>V
</span><span class=special
>,
</span><span class=identifier
>C
</span><span class=special
>>& </span><span class=identifier
>c
</span><span class=special
>,
</span><span class=identifier
>V2
</span><span class=identifier
>v
</span><span class=special
>);
853 </span><span class=keyword
>template
</span><span class=special
>< </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
>>
854 </span><span class=identifier
>list_inserter
</span><span class=special
>< </span><span class=special
>...
</span><span class=special
>> </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
><</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
>>& </span><span class=identifier
>c
</span><span class=special
>,
</span><span class=identifier
>K2
</span><span class=identifier
>k
</span><span class=special
>);
856 </span><span class=keyword
>template
</span><span class=special
>< </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
>>
857 </span><span class=identifier
>list_inserter
</span><span class=special
>< </span><span class=special
>...
</span><span class=special
>> </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
><</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
>>& </span><span class=identifier
>c
</span><span class=special
>,
</span><span class=identifier
>K2
</span><span class=identifier
>k
</span><span class=special
>);
859 </span><span class=preprocessor
>#ifdef
</span><span class=identifier
>BOOST_HAS_SLIST
861 </span><span class=keyword
>template
</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
>A
</span><span class=special
>,
</span><span class=keyword
>class
</span><span class=identifier
>V2
</span><span class=special
>>
862 </span><span class=identifier
>list_inserter
</span><span class=special
>< </span><span class=special
>...
</span><span class=special
>> </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
><</span><span class=identifier
>V
</span><span class=special
>,
</span><span class=identifier
>A
</span><span class=special
>>& </span><span class=identifier
>c
</span><span class=special
>,
</span><span class=identifier
>V2
</span><span class=identifier
>v
</span><span class=special
>);
864 </span><span class=preprocessor
>#endif
866 </span><span class=keyword
>template
</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
>V2
</span><span class=special
>>
867 </span><span class=identifier
>list_inserter
</span><span class=special
>< </span><span class=special
>...
</span><span class=special
>> </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
><</span><span class=identifier
>V
</span><span class=special
>,
</span><span class=identifier
>C
</span><span class=special
>>& </span><span class=identifier
>c
</span><span class=special
>,
</span><span class=identifier
>V2
</span><span class=identifier
>v
</span><span class=special
>);
869 </span><span class=keyword
>template
</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
>A
</span><span class=special
>,
</span><span class=keyword
>class
</span><span class=identifier
>V2
</span><span class=special
>>
870 </span><span class=identifier
>list_inserter
</span><span class=special
>< </span><span class=special
>...
</span><span class=special
>> </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
><</span><span class=identifier
>V
</span><span class=special
>,
</span><span class=identifier
>A
</span><span class=special
>>& </span><span class=identifier
>c
</span><span class=special
>,
</span><span class=identifier
>V2
</span><span class=identifier
>v
</span><span class=special
>);
</span>
872 <span class=special
>}
</span><span class=comment
>// namespace 'assign'
</span>
873 <span class=special
>}
</span><span class=comment
>// namespace 'boost'
</span> </pre></blockquote>
874 Note that the extra template argument
<code>V2
</code> etc. is
875 necessary to allow for types convertible to
<code>V
</code>.
877 <h3>Functions
<code>list_of()
</code> and
878 <code>map_list_of()
</code> <a name=
"list_of_ref"> </h3>
880 These two functions are used to construct anonymous
881 list which can be converted to any standard container
882 and
<code>boost::
<a href=
"../../array/index.html">array
</a><T,sz
>.
</code>
883 The object returned by the two
884 functions is guaranteed to have the interface described below.
888 <pre><span class=keyword
>namespace
</span><span class=identifier
>boost
</span>
889 <span class=special
>{
</span>
890 <span class=keyword
>namespace
</span><span class=identifier
>assign
</span>
891 <span class=special
>{
892 </span><span class=keyword
>template
</span><span class=special
>< </span><span class=keyword
>class
</span><span class=identifier
>T
</span><span class=special
>>
893 </span><span class=keyword
>class
</span><span class=identifier
>Implementation
</span><span class=special
>-
</span><span class=identifier
>defined
</span>
894 </span><span class=special
>{
895 </span><span class=keyword
>public
</span><span class=special
>:
896 </span><span class=identifier
>const_iterator
</span><span class=identifier
>begin
</span><span class=special
>()
<span class=keyword
>const
</span>;
897 </span><span class=identifier
>const_iterator
</span><span class=identifier
>end
</span><span class=special
>()
<span class=keyword
>const
</span>;
899 </span><span class=keyword
>template
</span><span class=special
>< </span><span class=keyword
>class
</span><span class=identifier
>U
</span><span class=special
>>
900 </span><span class=identifier
>Implementation
</span><span class=special
>-
</span><span class=identifier
>defined
</span>& </span><span class=keyword
>operator
</span><span class=special
>,(
</span><span class=identifier
>U
</span><span class=identifier
>u
</span><span class=special
>);
902 </span><span class=comment
>// inserts default-constructed object
903 </span><span class=identifier
>Implementation
</span><span class=special
>-
</span><span class=identifier
>defined
</span>& </span><span class=keyword
>operator
</span><span class=special
>()();
905 </span><span class=keyword
>template
</span><span class=special
>< </span><span class=keyword
>class
</span><span class=identifier
>U
</span><span class=special
>>
906 </span><span class=identifier
>Implementation
</span><span class=special
>-
</span><span class=identifier
>defined
</span>& </span><span class=keyword
>operator
</span><span class=special
>()(
</span><span class=identifier
>U
</span><span class=identifier
>u
</span><span class=special
>);
908 </span><span class=keyword
>template
</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
>>
909 </span><span class=identifier
>Implementation
</span><span class=special
>-
</span><span class=identifier
>defined
</span>& </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
>);
911 </span><span class=comment
>//
912 // and similarly up to
5 arguments
916 // Convert to a 'Container'. 'Container' must have a constructor
917 // which takes two iterators.
919 </span><span class=keyword
>template
</span><span class=special
>< </span><span class=keyword
>class
</span><span class=identifier
>Container
</span><span class=special
>>
920 </span><span class=keyword
>operator
</span><span class=identifier
>Container
</span><span class=special
>()
</span><span class=keyword
>const
</span><span class=special
>;
922 </span><span class=comment
>//
923 // Convert to a container adapter like 'std::stack
<>'.
925 </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
>;
927 </span><span class=comment
>//
929 // Convert to eg. 'boost::array
<T,std::size_t
>'. If the
930 // assigned variable is too small,
931 // a
<a href=
"#assignment_exception">assignment_exception
</a> is thrown.
932 // If the assigned variable it is too big, the rest of the
933 // values are default-constructed.
935 </span><span class=keyword
>template
</span><span class=special
>< </span><span class=keyword
>template
</span><span class=special
><</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
>> </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
>>
936 </span><span class=keyword
>operator
</span><span class=identifier
>Array
</span><span class=special
><</span><span class=identifier
>U
</span><span class=special
>,
</span><span class=identifier
>sz
</span><span class=special
>>()
</span><span class=keyword
>const
</span><span class=special
>;
937 </span><span class=special
>};
</span>
939 <span class=comment
>//
940 // Comparison operators. 'op' can be
<,
>,
<=,
>=,==,!=
942 <span class=keyword
>template
</span><span class=special
><</span> <span class=keyword
>class
</span> <span class=identifier
>Range
</span> <span class=special
>></span>
943 <span class=keyword
>bool
</span> <span class=identifier
>op
</span><span class=special
>(
</span> <span class=keyword
>const
</span> <span class=identifier
>Implementation
</span><span class=special
>-
</span><span class=identifier
>defined
</span><span class=special
>&,
</span> <span class=keyword
>const
</span> <span class=identifier
>Range
</span><span class=special
>&</span> <span class=special
>);
</span>
944 <span class=keyword
>template
</span><span class=special
><</span> <span class=keyword
>class
</span> <span class=identifier
>Range
</span> <span class=special
>></span>
945 <span class=keyword
>bool
</span> <span class=identifier
>op
</span><span class=special
>(
</span> <span class=keyword
>const
</span> <span class=identifier
>Range
</span><span class=special
>&,
</span> <span class=keyword
>const
</span> <span class=identifier
>Implementation
</span><span class=special
>-
</span><span class=identifier
>defined
</span><span class=special
>&</span> <span class=special
>);
</span>
947 <span class=keyword
>template
</span><span class=special
>< </span><span class=keyword
>class
</span><span class=identifier
>T
</span><span class=special
>>
948 </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
>);
950 </span><span class=keyword
>template
</span><span class=special
>< </span><span class=keyword
>class
</span><span class=identifier
>T
</span><span class=special
>>
951 </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
>);
953 </span><span class=keyword
>template
</span><span class=special
>< </span><span class=keyword
>class
</span><span class=identifier
>T
</span><span class=special
>,
</span><span class=keyword
>class
</span><span class=identifier
>U
</span><span class=special
>,
</span><span class=keyword
>class
</span><span class=identifier
>U2
</span><span class=special
>>
954 </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
>);
956 </span><span class=keyword
>template
</span><span class=special
>< </span><span class=keyword
>class
</span><span class=identifier
>T
</span><span class=special
>,
</span><span class=keyword
>class
</span><span class=identifier
>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
>>
957 </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
>);
959 </span><span class=keyword
>template
</span><span class=special
>< </span><span class=keyword
>class
</span><span class=identifier
>T
</span><span class=special
>,
</span><span class=keyword
>class
</span><span class=identifier
>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
>>
960 </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
>);
962 </span><span class=keyword
>template
</span><span class=special
>< </span><span class=keyword
>class
</span><span class=identifier
>T
</span><span class=special
>,
</span><span class=keyword
>class
</span><span class=identifier
>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
>>
963 </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
>);
965 </span><span class=keyword
>template
</span><span class=special
>< </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
>>
966 </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
>)
967 </span><span class=special
>{
968 </span><span class=keyword
>return
</span><span class=identifier
>list_of
</span><span class=special
>< </span><span class=identifier
>std
</span><span class=special
>::
</span><span class=identifier
>pair
</span><span class=special
><</span><span class=identifier
>Key
</span><span class=special
>,
</span><span class=identifier
>T
</span><span class=special
>> </span><span class=special
>>()(
</span><span class=identifier
>k
</span><span class=special
>,
</span><span class=identifier
>t
</span><span class=special
>);
969 </span><span class=special
>}
</span>
970 <span class=special
>}
</span><span class=comment
>// namespace 'assign'
</span>
971 <span class=special
>}
</span><span class=comment
>// namespace 'boost'
</span> </pre></blockquote>
974 <h3>Functions
<code>repeat()
</code>,
975 <code>repeat_fun()
</code> and
<code>range()
</code> <a name=
"repeat_ref"> </h3>
977 These first two function exist both as free-standing functions and as member functions of the object returned by
978 <code>list_of()
</code> and of
<code>list_inserter
</code>.
979 The free-standing versions are used to create a
980 hook for
<code>operator,()
</code> so we can call the functions in the middle of a comma-list. The member functions
981 are used when we need to call the functions in the middle of a parenthesis-list. In both cases we have that
983 <li> the return type is always implementation defined for both functions,
984 <li> the argument list of
<code>repeat()
</code> is
<code>(std::size_t,T)
</code>, and
985 <li> the argument list of
<code>repeat_fun()
</code> is
<code>(std::size_t,Nullary_function)
</code>
990 The function
<code>range()
</code> only exists as a member function. The following two overloads are provided:
992 <pre><span class=keyword
>template
</span><span class=special
><</span> <span class=keyword
>class
</span> <span class=identifier
>SinglePassIterator
</span> <span class=special
>></span>
993 <span class=identifier
>Implementation
</span><span class=special
>-
</span><span class=identifier
>defined
</span> <span class=identifier
>range
</span><span class=special
>(
</span> <span class=identifier
>SinglePassIterator
</span> <span class=identifier
>first
</span><span class=special
>,
</span> <span class=identifier
>SinglePassIterator
</span> <span class=identifier
>last
</span> <span class=special
>);
</span>
995 <span class=keyword
>template
</span><span class=special
><</span> <span class=keyword
>class
</span> <span class=identifier
>SinglePassRange
</span> <span class=special
>></span>
996 <span class=identifier
>Implementation
</span><span class=special
>-
</span><span class=identifier
>defined
</span> <span class=identifier
>range
</span><span class=special
>(
</span> <span class=keyword
>const
</span> <span class=identifier
>SinglePassRange
</span><span class=special
>&</span> <span class=identifier
>rng
</span> <span class=special
>);
</span></pre>
1001 <h3><a name=
"list_inserter">Class
<code>list_inserter
</code></a></h3>
1003 This class is responsible for inserting elements into containers and
1004 it is the key to extending the library to support your favourite class.
1010 <span class=keyword
>namespace
</span><span class=identifier
>boost
</span>
1011 <span class=special
>{
</span>
1012 <span class=keyword
>namespace
</span><span class=identifier
>assign
</span>
1013 <span class=special
>{
1014 </span><span class=keyword
>template
</span><span class=special
>< </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
>>
1015 </span><span class=keyword
>class
</span><span class=identifier
>list_inserter
1016 </span><span class=special
>{
1017 </span><span class=identifier
>Function
</span><span class=identifier
>fun
</span><span class=special
>;
1019 </span><span class=keyword
>public
</span><span class=special
>:
1020 </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
>);
1022 </span><span class=comment
>// conversion constructor
1023 </span><span class=keyword
>template
</span><span class=special
>< </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
>>
1024 </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
><</span><span class=identifier
>Function2
</span><span class=special
>,
</span><span class=identifier
>Arg
</span><span class=special
>>& </span><span class=special
>);
1026 </span><span class=keyword
>public
</span><span class=special
>:
1027 </span><span class=keyword
>template
</span><span class=special
>< </span><span class=keyword
>class
</span><span class=identifier
>U
</span><span class=special
>>
1028 </span><span class=identifier
>list_inserter
</span><span class=special
>& </span><span class=keyword
>operator
</span><span class=special
>,(
</span><span class=identifier
>U
</span><span class=identifier
>u
</span><span class=special
>);
1030 </span><span class=keyword
>template
</span><span class=special
>< </span><span class=keyword
>class
</span><span class=identifier
>U
</span><span class=special
>>
1031 </span><span class=identifier
>list_inserter
</span><span class=special
>& </span><span class=keyword
>operator
</span><span class=special
>=(
</span><span class=identifier
>U
</span><span class=identifier
>u
</span><span class=special
>);
1033 </span><span class=comment
>// calls 'fun()' with default-constructed object
1034 </span><span class=identifier
>list_inserter
</span><span class=special
>& </span><span class=keyword
>operator
</span><span class=special
>()();
1036 </span><span class=keyword
>template
</span><span class=special
>< </span><span class=keyword
>class
</span><span class=identifier
>U
</span><span class=special
>>
1037 </span><span class=identifier
>list_inserter
</span><span class=special
>& </span><span class=keyword
>operator
</span><span class=special
>()(
</span><span class=identifier
>U
</span><span class=identifier
>u
</span><span class=special
>);
1039 </span><span class=keyword
>template
</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
>>
1040 </span><span class=identifier
>list_inserter
</span><span class=special
>& </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
>)
1041 </span><span class=special
>{
1042 </span><span class=comment
>//
1043 // if 'Argument' is 'void'
1046 // fun( Argument( u, u2 ) );
1048 </span><span class=keyword
>return
</span><span class=special
>*
</span><span class=keyword
>this
</span><span class=special
>;
1049 </span><span class=special
>}
1051 </span><span class=comment
>//
1052 // similarly up to
5 arguments
1054 </span><span class=special
>};
</span>
1056 <span class=keyword
>template
</span><span class=special
>< </span><span
1057 class=keyword
>class
</span><span class=identifier
>C
</span><span class=special
>>
1058 </span><span class=identifier
>list_inserter
</span><span class=special
>< </span><span class=special
>...
</span><span class=special
>> </span><span class=identifier
>push_back
</span><span class=special
>(
</span><span class=identifier
>C
</span><span class=special
>& </span><span class=special
>);
1060 </span><span class=keyword
>template
</span><span class=special
>< </span><span class=keyword
>class
</span><span class=identifier
>C
</span><span class=special
>>
1061 </span><span class=identifier
>list_inserter
</span><span class=special
>< </span><span class=special
>...
</span><span class=special
>> </span><span class=identifier
>push_front
</span><span class=special
>(
</span><span class=identifier
>C
</span><span class=special
>& </span><span class=special
>);
1063 </span><span class=keyword
>template
</span><span class=special
>< </span><span class=keyword
>class
</span><span class=identifier
>C
</span><span class=special
>>
1064 </span><span class=identifier
>list_inserter
</span><span class=special
>< </span><span class=special
>...
</span><span class=special
>> </span><span class=identifier
>insert
</span><span class=special
>(
</span><span class=identifier
>C
</span><span class=special
>& </span><span class=special
>);
1066 </span><span class=keyword
>template
</span><span class=special
>< </span><span class=keyword
>class
</span><span class=identifier
>C
</span><span class=special
>>
1067 </span><span class=identifier
>list_inserter
</span><span class=special
>< </span><span class=special
>...
</span><span class=special
>> </span><span class=identifier
>push
</span><span class=special
>(
</span><span class=identifier
>C
</span><span class=special
>& </span><span class=special
>);
</span>
1069 <span class=special
>}
</span><span class=comment
>// namespace 'assign'
</span>
1070 <span class=special
>}
</span><span class=comment
>// namespace 'boost'
</span></pre></blockquote>
1072 Notice how the arguments to
<code>operator,()
</code> and
1073 <code>operator()()
</code> are passed differently to
1074 <code>fun
</code> depending of the type of
<code>Argument
</code>.
1075 So if we only pass one template argument to
<code>list_inserter,
</code>
1076 we can forward
"arbitrary" argument lists of functions. If we pass
1077 two template arguments to
<code>list_inserter
</code> we can
1078 construct types with
"arbitrary" constructors.
1083 a reference to
<code>list_inserter
</code> is returned, we can
1084 chain argument list together in a very space-efficient manner.
1087 <h3><a name=
"make_list_inserter">Function
<code>make_list_inserter()
</code></a></h3>
1089 A simple
"constructor" function for
<code>list_inserter
</code>. A typical
1090 use of this function is to call it with the result of
1091 <code>boost::bind()
</code>
1092 which in general returns some unreadable and weird class template.
1096 <span class=keyword
>namespace
</span><span class=identifier
>boost
</span>
1097 <span class=special
>{
</span>
1098 <span class=keyword
>namespace
</span><span class=identifier
>assign
</span>
1099 <span class=special
>{
1100 </span><span class=keyword
>template
</span><span class=special
>< </span><span class=keyword
>class
</span><span class=identifier
>Function
</span><span class=special
>>
1101 </span><span class=identifier
>list_inserter
</span><span class=special
><</span><span class=identifier
>Function
</span><span class=special
>> </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
>)
1102 </span><span class=special
>{
1103 </span><span class=keyword
>return
</span><span class=identifier
>list_inserter
</span><span class=special
><</span><span class=identifier
>Function
</span><span class=special
>>(
</span><span class=identifier
>fun
</span><span class=special
>);
1104 </span><span class=special
>}
</span>
1105 <span class=special
>}
</span>
1106 <span class=special
>}
</span> </pre></blockquote>
1108 <a name=
"limit"></a>
1109 <h3>Customizing argument list sizes
</h3>
1111 This library uses the boost Preprocessor Library to implement overloaded
1112 versions of
<code>operator()()
</code> and
<code>list_of()
</code>. By default you
1113 can call these functions with five arguments, but you can also customize this
1114 number by defining a macros before including a header from this library:
1117 <span class=preprocessor
>#define
</span><span class=identifier
>BOOST_ASSIGN_MAX_PARAMS
</span><span class=number
>10
1118 </span><span class=preprocessor
>#include
</span><span class=special
><</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
>></span>
1123 <h2><a name=
"exceptions">Exceptions and exception-safety
</a></h2>
1125 The exception guarantees by the library is the same as guarantee as the
1126 guarantee of the function that is forwarded to. For standard
1127 containers this means that the
1128 strong guarantee is given for a single insertions and that the basic guarantee
1129 is given for many insertions (provided that the object being copied
1130 gives the basic guarantee).
1133 The functions may throw standard exceptions
1134 like
<code>std::bad_alloc
</code>. Note however that, unfortunately, the standard does not guarantee allocation-failures
1135 in standard containers to be reported by
<code>std::bad_alloc
</code> or exceptions derived from
<code>std::exception
</code>.
1138 <h3><a name=
"assignment_exception">Class
1139 <code>assignment_exception
</code></a></h3>
1141 The exception is thrown by the conversion operator in the proxy object
1142 returned from
<code>list_of()
</code>.
1146 <span class=keyword
>namespace
</span><span class=identifier
>boost
</span>
1147 <span class=special
>{
</span>
1148 <span class=keyword
>namespace
</span><span class=identifier
>assign
</span>
1149 <span class=special
>{
1150 </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
1151 </span><span class=special
>{
1152 </span><span class=keyword
>public
</span><span class=special
>:
1153 </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
>);
1154 </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
>();
1155 </span><span class=special
>};
</span>
1156 <span class=special
>}
</span>
1157 <span class=special
>}
</span> </pre></blockquote>
1160 <h2><a name=
"extensions">Extending the library
</a></h2>
1162 It is very simple to make the library work with new classes.
1163 This code shows how to use
<code>operator+=()
</code> with
1166 <span class=keyword
>template
</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
>A
</span><span class=special
>,
</span><span class=keyword
>class
</span><span class=identifier
>V2
</span><span class=special
>>
1167 </span><span class=keyword
>inline
</span><span class=identifier
>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
>< </span><span class=identifier
>std
</span><span class=special
>::
</span><span class=identifier
>vector
</span><span class=special
><</span><span class=identifier
>V
</span><span class=special
>,
</span><span class=identifier
>A
</span><span class=special
>> </span><span class=special
>>,
</span><span class=identifier
>V
</span><span class=special
>>
1168 </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
><</span><span class=identifier
>V
</span><span class=special
>,
</span><span class=identifier
>A
</span><span class=special
>>& </span><span class=identifier
>c
</span><span class=special
>,
</span><span class=identifier
>V2
</span><span class=identifier
>v
</span><span class=special
>)
1169 </span><span class=special
>{
1170 </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
>< </span><span class=identifier
>std
</span><span class=special
>::
</span><span class=identifier
>vector
</span><span class=special
><</span><span class=identifier
>V
</span><span class=special
>,
</span><span class=identifier
>A
</span><span class=special
>> </span><span class=special
>>(
</span><span class=identifier
>c
</span><span class=special
>)
</span><span class=special
>)(
</span><span class=identifier
>v
</span><span class=special
>);
1171 </span><span class=special
>}
1176 where
<code>call_push_back
</code> is defined as
1180 <span class=keyword
>template
</span><span class=special
>< </span><span class=keyword
>class
</span><span class=identifier
>C
</span><span class=special
>>
1181 </span><span class=keyword
>class
</span><span class=identifier
>call_push_back
1182 </span><span class=special
>{
1183 </span><span class=identifier
>C
</span><span class=special
>& </span><span class=identifier
>c_
</span><span class=special
>;
1184 </span><span class=keyword
>public
</span><span class=special
>:
1186 </span><span class=identifier
>call_push_back
</span><span class=special
>(
</span><span class=identifier
>C
</span><span class=special
>& </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
>)
1187 </span><span class=special
>{
</span><span class=special
>}
1189 </span><span class=keyword
>template
</span><span class=special
>< </span><span class=keyword
>class
</span><span class=identifier
>T
</span><span class=special
>>
1190 </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
>)
1191 </span><span class=special
>{
1192 </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
>);
1193 </span><span class=special
>}
1194 </span><span class=special
>};
</span></pre>
1198 a second template argument to
<code>list_inserter
</code> so argument
1199 lists will be used to construct a
<code>V
</code> object. Otherwise we
1200 could end up trying to call
<code>push_back()
</code> with
<i>n
</i> arguments
1205 An alternative way would be to use
<code>boost::function
</code> and
1206 <code>boost::bind()
</code> in combination. However, in this case one must
1207 remember that it is illegal to take the address of a function in
1208 the standard library.
1212 Calling a function with more that one argument can be
1213 very useful too. This small example shows how we take advantage of this
1217 <span class=comment
>//
1218 // A class representing emails
1220 <span class=keyword
>class
</span><span class=identifier
>email
</span>
1221 <span class=special
>{
</span>
1222 <span class=keyword
>public
</span><span class=special
>:
1223 </span><span class=keyword
>enum
</span><span class=identifier
>address_option
1224 </span><span class=special
>{
1225 </span><span class=identifier
>check_addr_book
</span><span class=special
>,
1226 </span><span class=identifier
>dont_check_addr_book
1227 </span><span class=special
>};
1229 <span class=keyword
>private
</span><span class=special
>:
1231 </span><span class=keyword
>typedef
</span><span class=identifier
>std
</span><span class=special
>::
</span><span class=identifier
>map
</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=identifier
>address_option
</span><span class=special
>> </span><span class=identifier
>address_map
</span><span class=special
>;
1233 </span><span class=comment
>//
1234 // Store list of persons that must be cc'ed
1236 </span><span class=keyword
>mutable
</span><span class=identifier
>address_map
</span><span class=identifier
>cc_list
</span><span class=special
>;
1238 </span><span class=comment
>//
1239 // This extra function-object will take care of the
1240 // insertion for us. It stores a reference to a
1241 // map and 'operator()()' does the work.
1243 </span><span class=keyword
>struct
</span><span class=identifier
>add_to_map
1244 </span><span class=special
>{
1245 </span><span class=identifier
>address_map
</span><span class=special
>& </span><span class=identifier
>m
</span><span class=special
>;
1247 </span><span class=identifier
>add_to_map
</span><span class=special
>(
</span><span class=identifier
>address_map
</span><span class=special
>& </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
>)
1248 </span><span class=special
>{}
1250 </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
>& </span><span class=identifier
>name
</span><span class=special
>,
</span><span class=identifier
>address_option
</span><span class=identifier
>ao
</span><span class=special
>)
1251 </span><span class=special
>{
1252 </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
>;
1253 </span><span class=special
>}
1254 </span><span class=special
>};
1256 <span class=keyword
>public
</span><span class=special
>:
1258 </span><span class=comment
>//
1259 // This function constructs the appropriate 'list_inserter'.
1260 // Again we could have use 'boost::function', but it is
1261 // trivial to use a function object.
1263 // Notice that we do not specify an extra template
1264 // parameter to 'list_inserter'; this means we forward
1265 // all parameters directly to the function without
1266 // calling any constructor.
1268 </span><span class=identifier
>list_inserter
</span><span class=special
>< </span><span class=identifier
>add_to_map
</span><span class=special
>>
1269 </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
>)
1270 </span><span class=special
>{
1271 </span><span class=comment
>//
1272 // Notice how we pass the arguments 'name' and 'ao' to
1273 // the 'list_inserter'.
1275 </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
>);
1276 </span><span class=special
>}
</span>
1277 <span class=special
>};
1279 <span class=comment
>//
1280 // Now we can use the class like this:
1282 <span class=identifier
>email
</span><span class=identifier
>e
</span><span class=special
>;
</span>
1283 <span class=identifier
>e
</span><span class=special
>.
</span><span class=identifier
>add_cc
</span><span class=special
>(
</span><span class=string
>"Mr. Foo
"</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
>)
1284 </span><span class=special
>(
</span><span class=string
>"Mr. Bar
"</span><span class=special
>,
</span><span class=identifier
>email
</span><span class=special
>::
</span><span class=identifier
>check_addr_book
</span><span class=special
>)
1285 </span><span class=special
>(
</span><span class=string
>"Mrs. FooBar
"</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>
1289 The full example can be seen in
<a href=
"email_example.html">email_example.cpp
</a> </p>
1291 <h2>Examples
<a name=
"examples"></h2>
1293 Additional examples can be found in the test files:
1295 <li> <a href=
"email_example.html">email_example.cpp
</a>
1296 <li> <a href=
"my_vector_example.html">my_vector_example.cpp
</a>
1297 <li> <a href=
"multi_index_container.html">multi_index_container.cpp
</a>
1298 <li> <a href=
"../test/array.cpp">array.cpp
</a>
1299 <li> <a href=
"../test/list_of.cpp">list_of.cpp
</a>
1300 <li> <a href=
"../test/std.cpp">std.cpp
</a>
1301 <li> <a href=
"../test/list_inserter.cpp">list_inserter.cpp
</a>
1302 <li> <a href=
"../test/list_of_workaround.cpp">list_of_work_around.cpp
</a>
1307 <h2><a name=
"boost_libs">Supported libraries
</a></h2>
1308 Here is a list libraries has been tested with Boost.Assign:
1311 <li> <code>boost::
<a href=
"../../array/index.html">array
</a></code>
1312 <li> <code>boost::
<a href=
"../../multi_index/index.html">multi_index_container
</a></code>
1313 <li> <code>Boost.
<a href=
"../../ptr_container/index.html">Pointer Container
</code> </ol> <p>
1319 <h2><a name=
"portability">Portability
</a></h2>
1321 Library has been successfully compiled and tested with
1322 MVC++
7.1, GCC
3.2 (under Cygwin) Comeau
4.3.3
1325 There are known limitation on platforms not supporting templated
1326 conversion operators. The solution is to call certain member functions on
1327 the object returned by
<code>list_of()
</code>:
</p>
1330 <span class=special
>{
1331 </span><span class=keyword
>using
</span><span class=keyword
>namespace
</span><span class=identifier
>std
</span><span class=special
>;
1332 </span><span class=keyword
>using
</span><span class=keyword
>namespace
</span><span class=identifier
>boost
</span><span class=special
>;
1333 </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
>;
1335 </span><span class=keyword
></span><span
1336 class=identifier
>vector
</span><span
1337 class=special
><</span><span class=keyword
>int
</span><span
1338 class=special
>></span> <span class=identifier
>v
</span><span
1339 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
>v
</span><span class=special
>);
1340 </span><span class=identifier
>set
</span><span class=special
><</span><span class=keyword
>int
</span><span class=special
>> </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
>);
1341 </span><span class=identifier
>map
</span><span class=special
><</span><span class=keyword
>int
</span><span class=special
>,
</span><span class=keyword
>int
</span><span class=special
>> </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
>);
1342 </span><span class=identifier
>stack
</span><span class=special
><</span><span class=keyword
>int
</span><span class=special
>> </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
>);
1343 </span><span class=identifier
>queue
</span><span class=special
><</span><span class=keyword
>int
</span><span class=special
>> </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
>);
1344 </span><span class=identifier
>array
</span><span class=special
><</span><span class=keyword
>int
</span><span class=special
>,
</span><span class=number
>4</span><span class=special
>> </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>
1345 <span class=special
>}
</span> </pre>
1348 Notice how one must supply the functions with an argument so the right
1349 return type can be deduced.
1351 <p>Some standard libraries are also broken. One problem is that
1352 <code>insert()
</code> might not work:
1355 <span class=identifier
>map
</span><span class=special
><</span><span class=keyword
>int
</span><span class=special
>,
</span><span class=keyword
>int
</span><span class=special
>> </span><span class=identifier
>next
</span><span class=special
>;
1356 </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>
1358 The solution is to use
<code>map_list_of()
</code> instead:
1361 <span class=identifier
>map
</span><span class=special
><</span><span class=keyword
>int
</span><span class=special
>,
</span><span class=keyword
>int
</span><span class=special
>> </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>
1364 <h2><a name=
"history">History and Acknowledgment
</a></h2>
1366 The idea for an assignment/initialization library is not new. The
1367 functionality of this
1368 library resembles Leor Zolman's STL Container Initialization Library a great
1369 deal, but it does not rely on string parsing to achieve its goals.
1373 library is non-intrusive and puts only a minimum of requirements
1374 on its supported classes.
1375 Overloading operator comma is sometimes viewed as a bad practice
<a
1376 href=
"#meyers">[
1]
</A>. However, it has been done
1377 with success in eg. the Generative Matrix Computation Library and Blitz to initialize matrices
1378 (see
<a href=
"#gmcl">[
2]
</A>) and
<a href=
"#blitz">[
3]
</A>). The
1379 Initialization Library overloads
1380 the comma operator in a safe manner by letting free standing functions
1381 return an object that is responsible for the initialization. Therefore it takes
1383 action from the programmer to begin using the overloaded
<code>operator,()
</CODE>.
1386 There has recently been some discussion about enhancing the language to
1387 support better initialization (see
<a href=
"#initializer">[
4]
</a>).
1390 Special thanks goes to
1392 <li> Leor Zolman for our many discussion that eventually led to this library.
1393 <li> Tom Brinkman for being review manager.
1394 <li> Joaquín Muñoz for vc6/vc7 portability.
1395 <li> Pavel Vozenilek for his countless suggestions, improvements and
1397 <li> Rene Rivera for Code Warrior portability.
1402 <h2><a name=
"ref">References
</a></h2>
1405 <li> <a name=
"meyers"> Scott. Meyers,
"More Effective C++", Item
7, Addison Wesley,
1996
1406 <li> <a name=
"gmcl"> K. Czarnecki and U.W. Eisenecker,
"Generative programming", Addison-Wesley,
2000
1407 <li> <a name=
"blitz"> <a href=
"http://www.oonumerics.org/blitz/"> http://www.oonumerics.org/blitz/
</A>
1408 <li> <a name=
"initializer">
1409 Gabriel Dos Reis and Bjarne Stroustrup,
1410 <a href=
"http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2003/n1509.pdf"> "Generalized Initializer
1411 Lists"</a>,
2003 </a>
1416 (C) Copyright Thorsten Ottosen
2003-
2006