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 2003, Eric Friedman, Itay Maman. 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/get.hpp"> 11 <namespace name="boost"> 12 13 <class name="bad_get"> 14 <inherit access="public"> 15 <classname>std::exception</classname> 16 </inherit> 17 18 <purpose> 19 <simpara>The exception thrown in the event of a failed application of 20 <code><functionname>boost::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="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 <signature> 95 <template> 96 <template-type-parameter name="U"/> 97 <template-type-parameter name="T1"/> 98 <template-type-parameter name="T2"/> 99 <template-varargs/> 100 <template-type-parameter name="TN"/> 101 </template> 102 103 <type>U &&</type> 104 105 <parameter name="operand"> 106 <paramtype><classname>variant</classname><T1, T2, ..., TN> &&</paramtype> 107 </parameter> 108 </signature> 109 110 <purpose> 111 <simpara>Retrieves a value of a specified type from a given 112 <code><classname>variant</classname></code>. </simpara> 113 <simpara>Unlike <functionname>strict_get</functionname> does not assert at compile time 114 that type <code>U</code> is one of the types that can be stored in variant.</simpara> 115 </purpose> 116 117 <description> 118 <simpara>The <code>get</code> function allows run-time checked, 119 type-safe retrieval of the content of the given 120 <code><classname>variant</classname></code>. The function succeeds 121 only if the content is of the specified type <code>U</code>, with 122 failure indicated as described below.</simpara> 123 <simpara><emphasis role="bold">Recomendation</emphasis>: Use 124 <functionname>get</functionname> or <functionname>strict_get</functionname> in new code. 125 <functionname>strict_get</functionname> 126 provides more compile time checks and its behavior is closer to <code>std::get</code> 127 from C++ Standard Library.</simpara> 128 <simpara><emphasis role="bold">Warning</emphasis>: After either 129 <code>operand</code> or its content is destroyed (e.g., when the 130 given <code><classname>variant</classname></code> is assigned a 131 value of different type), the returned reference is invalidated. 132 Thus, significant care and caution must be extended when handling 133 the returned reference.</simpara> 134 </description> 135 136 <notes> 137 <simpara>As part of its guarantee of type-safety, <code>get</code> 138 enforces <code>const</code>-correctness. Thus, the specified type 139 <code>U</code> must be <code>const</code>-qualified whenever 140 <code>operand</code> or its content is likewise 141 <code>const</code>-qualified. The converse, however, is not required: 142 that is, the specified type <code>U</code> may be 143 <code>const</code>-qualified even when <code>operand</code> and its 144 content are not.</simpara> 145 </notes> 146 147 <returns> 148 <simpara>If passed a pointer, <code>get</code> returns a pointer to 149 the value content if it is of the specified type <code>U</code>; 150 otherwise, a null pointer is returned. If passed a reference, 151 <code>get</code> returns a reference to the value content if it is of 152 the specified type <code>U</code>; otherwise, an exception is thrown 153 (see below).</simpara> 154 </returns> 155 156 <throws> 157 <simpara>Overloads taking a 158 <code><classname>variant</classname></code> pointer will not 159 throw; the overloads taking a 160 <code><classname>variant</classname></code> reference throw 161 <code><classname>bad_get</classname></code> if the content is not of 162 the specified type <code>U</code>.</simpara> 163 </throws> 164 165 <rationale> 166 <simpara>While visitation via 167 <code><functionname>apply_visitor</functionname></code> 168 is generally preferred due to its greater safety, <code>get</code> may 169 may be more convenient in some cases due to its straightforward 170 usage.</simpara> 171 </rationale> 172 </overloaded-function> 173 174 <overloaded-function name="strict_get"> 175 <signature> 176 <template> 177 <template-type-parameter name="U"/> 178 <template-type-parameter name="T1"/> 179 <template-type-parameter name="T2"/> 180 <template-varargs/> 181 <template-type-parameter name="TN"/> 182 </template> 183 184 <type>U *</type> 185 186 <parameter name="operand"> 187 <paramtype><classname>variant</classname><T1, T2, ..., TN> *</paramtype> 188 </parameter> 189 </signature> 190 191 <signature> 192 <template> 193 <template-type-parameter name="U"/> 194 <template-type-parameter name="T1"/> 195 <template-type-parameter name="T2"/> 196 <template-varargs/> 197 <template-type-parameter name="TN"/> 198 </template> 199 200 <type>const U *</type> 201 202 <parameter name="operand"> 203 <paramtype>const <classname>variant</classname><T1, T2, ..., TN> *</paramtype> 204 </parameter> 205 </signature> 206 207 <signature> 208 <template> 209 <template-type-parameter name="U"/> 210 <template-type-parameter name="T1"/> 211 <template-type-parameter name="T2"/> 212 <template-varargs/> 213 <template-type-parameter name="TN"/> 214 </template> 215 216 <type>U &</type> 217 218 <parameter name="operand"> 219 <paramtype><classname>variant</classname><T1, T2, ..., TN> &</paramtype> 220 </parameter> 221 </signature> 222 223 <signature> 224 <template> 225 <template-type-parameter name="U"/> 226 <template-type-parameter name="T1"/> 227 <template-type-parameter name="T2"/> 228 <template-varargs/> 229 <template-type-parameter name="TN"/> 230 </template> 231 232 <type>const U &</type> 233 234 <parameter name="operand"> 235 <paramtype>const <classname>variant</classname><T1, T2, ..., TN> &</paramtype> 236 </parameter> 237 </signature> 238 239 <signature> 240 <template> 241 <template-type-parameter name="U"/> 242 <template-type-parameter name="T1"/> 243 <template-type-parameter name="T2"/> 244 <template-varargs/> 245 <template-type-parameter name="TN"/> 246 </template> 247 248 <type>U &&</type> 249 250 <parameter name="operand"> 251 <paramtype><classname>variant</classname><T1, T2, ..., TN> &&</paramtype> 252 </parameter> 253 </signature> 254 255 <purpose> 256 <simpara>Retrieves a value of a specified type from a given 257 <code><classname>variant</classname></code>.</simpara> 258 </purpose> 259 260 <description> 261 <simpara>Acts exactly like <functionname>relaxed_get</functionname> but does a compile time check 262 that type <code>U</code> is one of the types that can be stored in variant.</simpara> 263 </description> 264 </overloaded-function> 265 266 <overloaded-function name="get"> 267 <signature> 268 <template> 269 <template-type-parameter name="U"/> 270 <template-type-parameter name="T1"/> 271 <template-type-parameter name="T2"/> 272 <template-varargs/> 273 <template-type-parameter name="TN"/> 274 </template> 275 276 <type>U *</type> 277 278 <parameter name="operand"> 279 <paramtype><classname>variant</classname><T1, T2, ..., TN> *</paramtype> 280 </parameter> 281 </signature> 282 283 <signature> 284 <template> 285 <template-type-parameter name="U"/> 286 <template-type-parameter name="T1"/> 287 <template-type-parameter name="T2"/> 288 <template-varargs/> 289 <template-type-parameter name="TN"/> 290 </template> 291 292 <type>const U *</type> 293 294 <parameter name="operand"> 295 <paramtype>const <classname>variant</classname><T1, T2, ..., TN> *</paramtype> 296 </parameter> 297 </signature> 298 299 <signature> 300 <template> 301 <template-type-parameter name="U"/> 302 <template-type-parameter name="T1"/> 303 <template-type-parameter name="T2"/> 304 <template-varargs/> 305 <template-type-parameter name="TN"/> 306 </template> 307 308 <type>U &</type> 309 310 <parameter name="operand"> 311 <paramtype><classname>variant</classname><T1, T2, ..., TN> &</paramtype> 312 </parameter> 313 </signature> 314 315 <signature> 316 <template> 317 <template-type-parameter name="U"/> 318 <template-type-parameter name="T1"/> 319 <template-type-parameter name="T2"/> 320 <template-varargs/> 321 <template-type-parameter name="TN"/> 322 </template> 323 324 <type>const U &</type> 325 326 <parameter name="operand"> 327 <paramtype>const <classname>variant</classname><T1, T2, ..., TN> &</paramtype> 328 </parameter> 329 </signature> 330 331 <signature> 332 <template> 333 <template-type-parameter name="U"/> 334 <template-type-parameter name="T1"/> 335 <template-type-parameter name="T2"/> 336 <template-varargs/> 337 <template-type-parameter name="TN"/> 338 </template> 339 340 <type>U &&</type> 341 342 <parameter name="operand"> 343 <paramtype><classname>variant</classname><T1, T2, ..., TN> &&</paramtype> 344 </parameter> 345 </signature> 346 347 <purpose> 348 <simpara>Retrieves a value of a specified type from a given 349 <code><classname>variant</classname></code>.</simpara> 350 </purpose> 351 352 <description> 353 <simpara>Evaluates to <functionname>strict_get</functionname> if <code>BOOST_VARIANT_USE_RELAXED_GET_BY_DEFAULT</code> 354 is not defined. If <code>BOOST_VARIANT_USE_RELAXED_GET_BY_DEFAULT</code> 355 is defined then evaluates to <functionname>relaxed_get</functionname>. </simpara> 356 357 <simpara><emphasis role="bold">Recomendation</emphasis>: Use 358 <functionname>get</functionname> in new code without defining 359 <code>BOOST_VARIANT_USE_RELAXED_GET_BY_DEFAULT</code>. In that way <functionname>get</functionname> 360 provides more compile time checks and its behavior is closer to <code>std::get</code> 361 from C++ Standard Library.</simpara> 362 </description> 363 </overloaded-function> 364 365 </namespace> 366</header> 367