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-2020 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> 327