libs/variant/doc/reference/polymorphic_get.xml

   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-2019 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>&lt;T1, T2, ..., TN&gt; *</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>&lt;T1, T2, ..., TN&gt; *</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 &amp;</type>
  72
  73         <parameter name="operand">
  74           <paramtype><classname>variant</classname>&lt;T1, T2, ..., TN&gt; &amp;</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 &amp;</type>
  88
  89         <parameter name="operand">
  90           <paramtype>const <classname>variant</classname>&lt;T1, T2, ..., TN&gt; &amp;</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>&lt;T1, T2, ..., TN&gt; *</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>&lt;T1, T2, ..., TN&gt; *</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 &amp;</type>
 208
 209         <parameter name="operand">
 210           <paramtype><classname>variant</classname>&lt;T1, T2, ..., TN&gt; &amp;</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 &amp;</type>
 224
 225         <parameter name="operand">
 226           <paramtype>const <classname>variant</classname>&lt;T1, T2, ..., TN&gt; &amp;</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>&lt;T1, T2, ..., TN&gt; *</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>&lt;T1, T2, ..., TN&gt; *</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 &amp;</type>
 284
 285         <parameter name="operand">
 286           <paramtype><classname>variant</classname>&lt;T1, T2, ..., TN&gt; &amp;</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 &amp;</type>
 300
 301         <parameter name="operand">
 302           <paramtype>const <classname>variant</classname>&lt;T1, T2, ..., TN&gt; &amp;</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>