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">
5 Copyright 2013-20014, Antony Polukhin.
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)
10 <header name=
"boost/variant/polymorphic_get.hpp">
11 <namespace name=
"boost">
13 <class name=
"bad_polymorphic_get">
14 <inherit access=
"public">
15 <classname>boost::bad_get
</classname>
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>
24 <method name=
"what" specifiers=
"virtual" cv=
"const">
25 <type>const char *
</type>
29 <overloaded-function name=
"polymorphic_relaxed_get">
32 <template-type-parameter name=
"U"/>
33 <template-type-parameter name=
"T1"/>
34 <template-type-parameter name=
"T2"/>
36 <template-type-parameter name=
"TN"/>
41 <parameter name=
"operand">
42 <paramtype><classname>variant
</classname><T1, T2, ..., TN
> *
</paramtype>
48 <template-type-parameter name=
"U"/>
49 <template-type-parameter name=
"T1"/>
50 <template-type-parameter name=
"T2"/>
52 <template-type-parameter name=
"TN"/>
55 <type>const U *
</type>
57 <parameter name=
"operand">
58 <paramtype>const
<classname>variant
</classname><T1, T2, ..., TN
> *
</paramtype>
64 <template-type-parameter name=
"U"/>
65 <template-type-parameter name=
"T1"/>
66 <template-type-parameter name=
"T2"/>
68 <template-type-parameter name=
"TN"/>
73 <parameter name=
"operand">
74 <paramtype><classname>variant
</classname><T1, T2, ..., TN
> &</paramtype>
80 <template-type-parameter name=
"U"/>
81 <template-type-parameter name=
"T1"/>
82 <template-type-parameter name=
"T2"/>
84 <template-type-parameter name=
"TN"/>
87 <type>const U
&</type>
89 <parameter name=
"operand">
90 <paramtype>const
<classname>variant
</classname><T1, T2, ..., TN
> &</paramtype>
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>
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>
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>
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>
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>
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>
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
161 </overloaded-function>
165 <overloaded-function name=
"polymorphic_strict_get">
168 <template-type-parameter name=
"U"/>
169 <template-type-parameter name=
"T1"/>
170 <template-type-parameter name=
"T2"/>
172 <template-type-parameter name=
"TN"/>
177 <parameter name=
"operand">
178 <paramtype><classname>variant
</classname><T1, T2, ..., TN
> *
</paramtype>
184 <template-type-parameter name=
"U"/>
185 <template-type-parameter name=
"T1"/>
186 <template-type-parameter name=
"T2"/>
188 <template-type-parameter name=
"TN"/>
191 <type>const U *
</type>
193 <parameter name=
"operand">
194 <paramtype>const
<classname>variant
</classname><T1, T2, ..., TN
> *
</paramtype>
200 <template-type-parameter name=
"U"/>
201 <template-type-parameter name=
"T1"/>
202 <template-type-parameter name=
"T2"/>
204 <template-type-parameter name=
"TN"/>
209 <parameter name=
"operand">
210 <paramtype><classname>variant
</classname><T1, T2, ..., TN
> &</paramtype>
216 <template-type-parameter name=
"U"/>
217 <template-type-parameter name=
"T1"/>
218 <template-type-parameter name=
"T2"/>
220 <template-type-parameter name=
"TN"/>
223 <type>const U
&</type>
225 <parameter name=
"operand">
226 <paramtype>const
<classname>variant
</classname><T1, T2, ..., TN
> &</paramtype>
231 <simpara>Retrieves a value of a specified type from a given
232 <code><classname>variant
</classname></code>.
</simpara>
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>
239 </overloaded-function>
241 <overloaded-function name=
"polymorphic_get">
244 <template-type-parameter name=
"U"/>
245 <template-type-parameter name=
"T1"/>
246 <template-type-parameter name=
"T2"/>
248 <template-type-parameter name=
"TN"/>
253 <parameter name=
"operand">
254 <paramtype><classname>variant
</classname><T1, T2, ..., TN
> *
</paramtype>
260 <template-type-parameter name=
"U"/>
261 <template-type-parameter name=
"T1"/>
262 <template-type-parameter name=
"T2"/>
264 <template-type-parameter name=
"TN"/>
267 <type>const U *
</type>
269 <parameter name=
"operand">
270 <paramtype>const
<classname>variant
</classname><T1, T2, ..., TN
> *
</paramtype>
276 <template-type-parameter name=
"U"/>
277 <template-type-parameter name=
"T1"/>
278 <template-type-parameter name=
"T2"/>
280 <template-type-parameter name=
"TN"/>
285 <parameter name=
"operand">
286 <paramtype><classname>variant
</classname><T1, T2, ..., TN
> &</paramtype>
292 <template-type-parameter name=
"U"/>
293 <template-type-parameter name=
"T1"/>
294 <template-type-parameter name=
"T2"/>
296 <template-type-parameter name=
"TN"/>
299 <type>const U
&</type>
301 <parameter name=
"operand">
302 <paramtype>const
<classname>variant
</classname><T1, T2, ..., TN
> &</paramtype>
307 <simpara>Retrieves a value of a specified type from a given
308 <code><classname>variant
</classname></code>.
</simpara>
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>
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>
324 </overloaded-function>