]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | <?xml version="1.0" encoding="utf-8"?> |
2 | <!DOCTYPE header PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" | |
3 | "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd"> | |
4 | <!-- | |
5 | Copyright 2013-20014, Antony Polukhin. | |
6 | ||
7 | Distributed under the Boost Software License, Version 1.0. (See accompanying | |
8 | file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) | |
9 | --> | |
10 | <header name="boost/variant/polymorphic_get.hpp"> | |
11 | <namespace name="boost"> | |
12 | ||
13 | <class name="bad_polymorphic_get"> | |
14 | <inherit access="public"> | |
15 | <classname>boost::bad_get</classname> | |
16 | </inherit> | |
17 | ||
18 | <purpose> | |
19 | <simpara>The exception thrown in the event of a failed application of | |
20 | <code><functionname>boost::polymorphic_get</functionname></code> on the given | |
21 | operand value.</simpara> | |
22 | </purpose> | |
23 | ||
24 | <method name="what" specifiers="virtual" cv="const"> | |
25 | <type>const char *</type> | |
26 | </method> | |
27 | </class> | |
28 | ||
29 | <overloaded-function name="polymorphic_relaxed_get"> | |
30 | <signature> | |
31 | <template> | |
32 | <template-type-parameter name="U"/> | |
33 | <template-type-parameter name="T1"/> | |
34 | <template-type-parameter name="T2"/> | |
35 | <template-varargs/> | |
36 | <template-type-parameter name="TN"/> | |
37 | </template> | |
38 | ||
39 | <type>U *</type> | |
40 | ||
41 | <parameter name="operand"> | |
42 | <paramtype><classname>variant</classname><T1, T2, ..., TN> *</paramtype> | |
43 | </parameter> | |
44 | </signature> | |
45 | ||
46 | <signature> | |
47 | <template> | |
48 | <template-type-parameter name="U"/> | |
49 | <template-type-parameter name="T1"/> | |
50 | <template-type-parameter name="T2"/> | |
51 | <template-varargs/> | |
52 | <template-type-parameter name="TN"/> | |
53 | </template> | |
54 | ||
55 | <type>const U *</type> | |
56 | ||
57 | <parameter name="operand"> | |
58 | <paramtype>const <classname>variant</classname><T1, T2, ..., TN> *</paramtype> | |
59 | </parameter> | |
60 | </signature> | |
61 | ||
62 | <signature> | |
63 | <template> | |
64 | <template-type-parameter name="U"/> | |
65 | <template-type-parameter name="T1"/> | |
66 | <template-type-parameter name="T2"/> | |
67 | <template-varargs/> | |
68 | <template-type-parameter name="TN"/> | |
69 | </template> | |
70 | ||
71 | <type>U &</type> | |
72 | ||
73 | <parameter name="operand"> | |
74 | <paramtype><classname>variant</classname><T1, T2, ..., TN> &</paramtype> | |
75 | </parameter> | |
76 | </signature> | |
77 | ||
78 | <signature> | |
79 | <template> | |
80 | <template-type-parameter name="U"/> | |
81 | <template-type-parameter name="T1"/> | |
82 | <template-type-parameter name="T2"/> | |
83 | <template-varargs/> | |
84 | <template-type-parameter name="TN"/> | |
85 | </template> | |
86 | ||
87 | <type>const U &</type> | |
88 | ||
89 | <parameter name="operand"> | |
90 | <paramtype>const <classname>variant</classname><T1, T2, ..., TN> &</paramtype> | |
91 | </parameter> | |
92 | </signature> | |
93 | ||
94 | <purpose> | |
95 | <simpara>Retrieves a value of a specified type from a given | |
96 | <code><classname>variant</classname></code>.</simpara> | |
97 | <simpara>Unlike <functionname>polymorphic_strict_get</functionname> does not assert at compile time | |
98 | that type <code>U</code> is one of the types that can be stored in variant.</simpara> | |
99 | </purpose> | |
100 | ||
101 | <description> | |
102 | <simpara>The <code>polymorphic_get</code> function allows run-time checked, | |
103 | type-safe retrieval of the content of the given | |
104 | <code><classname>variant</classname></code>. The function succeeds | |
105 | only if the content is of the specified type <code>U</code> or of type | |
106 | derived from type <code>U</code>, with | |
107 | failure indicated as described below.</simpara> | |
108 | <simpara><emphasis role="bold">Recomendation</emphasis>: Use | |
109 | <functionname>polymorphic_get</functionname> or <functionname>polymorphic_strict_get</functionname> | |
110 | in new code. | |
111 | <functionname>polymorphic_strict_get</functionname> | |
112 | provides more compile time checks and its behavior is closer to <code>std::get</code> | |
113 | from C++ Standard Library.</simpara> | |
114 | <simpara><emphasis role="bold">Warning</emphasis>: After either | |
115 | <code>operand</code> or its content is destroyed (e.g., when the | |
116 | given <code><classname>variant</classname></code> is assigned a | |
117 | value of different type), the returned reference is invalidated. | |
118 | Thus, significant care and caution must be extended when handling | |
119 | the returned reference.</simpara> | |
120 | </description> | |
121 | ||
122 | <notes> | |
123 | <simpara>As part of its guarantee of type-safety, <code>polymorphic_get</code> | |
124 | enforces <code>const</code>-correctness. Thus, the specified type | |
125 | <code>U</code> must be <code>const</code>-qualified whenever | |
126 | <code>operand</code> or its content is likewise | |
127 | <code>const</code>-qualified. The converse, however, is not required: | |
128 | that is, the specified type <code>U</code> may be | |
129 | <code>const</code>-qualified even when <code>operand</code> and its | |
130 | content are not.</simpara> | |
131 | </notes> | |
132 | ||
133 | <returns> | |
134 | <simpara>If passed a pointer, <code>polymorphic_get</code> returns a pointer to | |
135 | the value content if it is of the specified type <code>U</code> or of type | |
136 | derived from type <code>U</code>; | |
137 | otherwise, a null pointer is returned. If passed a reference, | |
138 | <code>polymorphic_get</code> returns a reference to the value content if it is of | |
139 | the specified type <code>U</code> or of type | |
140 | derived from type <code>U</code>; otherwise, an exception is thrown | |
141 | (see below).</simpara> | |
142 | </returns> | |
143 | ||
144 | <throws> | |
145 | <simpara>Overloads taking a | |
146 | <code><classname>variant</classname></code> pointer will not | |
147 | throw; the overloads taking a | |
148 | <code><classname>variant</classname></code> reference throw | |
149 | <code><classname>bad_polymorphic_get</classname></code> if the content is not of | |
150 | the specified type <code>U</code>or of type | |
151 | derived from type <code>U</code>.</simpara> | |
152 | </throws> | |
153 | ||
154 | <rationale> | |
155 | <simpara>While visitation via | |
156 | <code><functionname>apply_visitor</functionname></code> | |
157 | is generally preferred due to its greater safety, <code>polymorphic_get</code> may | |
158 | may be more convenient in some cases due to its straightforward | |
159 | usage.</simpara> | |
160 | </rationale> | |
161 | </overloaded-function> | |
162 | ||
163 | ||
164 | ||
165 | <overloaded-function name="polymorphic_strict_get"> | |
166 | <signature> | |
167 | <template> | |
168 | <template-type-parameter name="U"/> | |
169 | <template-type-parameter name="T1"/> | |
170 | <template-type-parameter name="T2"/> | |
171 | <template-varargs/> | |
172 | <template-type-parameter name="TN"/> | |
173 | </template> | |
174 | ||
175 | <type>U *</type> | |
176 | ||
177 | <parameter name="operand"> | |
178 | <paramtype><classname>variant</classname><T1, T2, ..., TN> *</paramtype> | |
179 | </parameter> | |
180 | </signature> | |
181 | ||
182 | <signature> | |
183 | <template> | |
184 | <template-type-parameter name="U"/> | |
185 | <template-type-parameter name="T1"/> | |
186 | <template-type-parameter name="T2"/> | |
187 | <template-varargs/> | |
188 | <template-type-parameter name="TN"/> | |
189 | </template> | |
190 | ||
191 | <type>const U *</type> | |
192 | ||
193 | <parameter name="operand"> | |
194 | <paramtype>const <classname>variant</classname><T1, T2, ..., TN> *</paramtype> | |
195 | </parameter> | |
196 | </signature> | |
197 | ||
198 | <signature> | |
199 | <template> | |
200 | <template-type-parameter name="U"/> | |
201 | <template-type-parameter name="T1"/> | |
202 | <template-type-parameter name="T2"/> | |
203 | <template-varargs/> | |
204 | <template-type-parameter name="TN"/> | |
205 | </template> | |
206 | ||
207 | <type>U &</type> | |
208 | ||
209 | <parameter name="operand"> | |
210 | <paramtype><classname>variant</classname><T1, T2, ..., TN> &</paramtype> | |
211 | </parameter> | |
212 | </signature> | |
213 | ||
214 | <signature> | |
215 | <template> | |
216 | <template-type-parameter name="U"/> | |
217 | <template-type-parameter name="T1"/> | |
218 | <template-type-parameter name="T2"/> | |
219 | <template-varargs/> | |
220 | <template-type-parameter name="TN"/> | |
221 | </template> | |
222 | ||
223 | <type>const U &</type> | |
224 | ||
225 | <parameter name="operand"> | |
226 | <paramtype>const <classname>variant</classname><T1, T2, ..., TN> &</paramtype> | |
227 | </parameter> | |
228 | </signature> | |
229 | ||
230 | <purpose> | |
231 | <simpara>Retrieves a value of a specified type from a given | |
232 | <code><classname>variant</classname></code>.</simpara> | |
233 | </purpose> | |
234 | ||
235 | <description> | |
236 | <simpara>Acts exactly like <functionname>polymorphic_relaxed_get</functionname> but does a compile time check | |
237 | that type <code>U</code> is one of the types that can be stored in variant.</simpara> | |
238 | </description> | |
239 | </overloaded-function> | |
240 | ||
241 | <overloaded-function name="polymorphic_get"> | |
242 | <signature> | |
243 | <template> | |
244 | <template-type-parameter name="U"/> | |
245 | <template-type-parameter name="T1"/> | |
246 | <template-type-parameter name="T2"/> | |
247 | <template-varargs/> | |
248 | <template-type-parameter name="TN"/> | |
249 | </template> | |
250 | ||
251 | <type>U *</type> | |
252 | ||
253 | <parameter name="operand"> | |
254 | <paramtype><classname>variant</classname><T1, T2, ..., TN> *</paramtype> | |
255 | </parameter> | |
256 | </signature> | |
257 | ||
258 | <signature> | |
259 | <template> | |
260 | <template-type-parameter name="U"/> | |
261 | <template-type-parameter name="T1"/> | |
262 | <template-type-parameter name="T2"/> | |
263 | <template-varargs/> | |
264 | <template-type-parameter name="TN"/> | |
265 | </template> | |
266 | ||
267 | <type>const U *</type> | |
268 | ||
269 | <parameter name="operand"> | |
270 | <paramtype>const <classname>variant</classname><T1, T2, ..., TN> *</paramtype> | |
271 | </parameter> | |
272 | </signature> | |
273 | ||
274 | <signature> | |
275 | <template> | |
276 | <template-type-parameter name="U"/> | |
277 | <template-type-parameter name="T1"/> | |
278 | <template-type-parameter name="T2"/> | |
279 | <template-varargs/> | |
280 | <template-type-parameter name="TN"/> | |
281 | </template> | |
282 | ||
283 | <type>U &</type> | |
284 | ||
285 | <parameter name="operand"> | |
286 | <paramtype><classname>variant</classname><T1, T2, ..., TN> &</paramtype> | |
287 | </parameter> | |
288 | </signature> | |
289 | ||
290 | <signature> | |
291 | <template> | |
292 | <template-type-parameter name="U"/> | |
293 | <template-type-parameter name="T1"/> | |
294 | <template-type-parameter name="T2"/> | |
295 | <template-varargs/> | |
296 | <template-type-parameter name="TN"/> | |
297 | </template> | |
298 | ||
299 | <type>const U &</type> | |
300 | ||
301 | <parameter name="operand"> | |
302 | <paramtype>const <classname>variant</classname><T1, T2, ..., TN> &</paramtype> | |
303 | </parameter> | |
304 | </signature> | |
305 | ||
306 | <purpose> | |
307 | <simpara>Retrieves a value of a specified type from a given | |
308 | <code><classname>variant</classname></code>.</simpara> | |
309 | </purpose> | |
310 | ||
311 | <description> | |
312 | <simpara>Evaluates to <functionname>polymorphic_strict_get</functionname> | |
313 | if <code>BOOST_VARIANT_USE_RELAXED_GET_BY_DEFAULT</code> | |
314 | is not defined. If <code>BOOST_VARIANT_USE_RELAXED_GET_BY_DEFAULT</code> | |
315 | is defined then evaluates to <functionname>polymorphic_relaxed_get</functionname>. </simpara> | |
316 | ||
317 | <simpara><emphasis role="bold">Recomendation</emphasis>: Use | |
318 | <functionname>polymorphic_get</functionname> in new code without defining | |
319 | <code>BOOST_VARIANT_USE_RELAXED_GET_BY_DEFAULT</code>. In that way | |
320 | <functionname>polymorphic_get</functionname> | |
321 | provides more compile time checks and its behavior is closer to <code>std::get</code> | |
322 | from C++ Standard Library.</simpara> | |
323 | </description> | |
324 | </overloaded-function> | |
325 | </namespace> | |
326 | </header> |