boost/libs/variant/doc/reference/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 <header name="boost/variant/get.hpp">
   5   <namespace name="boost">
   6
   7     <class name="bad_get">
   8       <inherit access="public">
   9         <classname>std::exception</classname>
  10       </inherit>
  11
  12       <purpose>
  13         <simpara>The exception thrown in        the     event   of a failed application of
  14         <code><functionname>boost::get</functionname></code> on the given
  15         operand value.</simpara>
  16       </purpose>
  17
  18       <method   name="what"     specifiers="virtual" cv="const">
  19         <type>const     char *</type>
  20       </method>
  21     </class>
  22
  23     <overloaded-function name="get">
  24       <signature>
  25         <template>
  26           <template-type-parameter name="U"/>
  27           <template-type-parameter name="T1"/>
  28           <template-type-parameter name="T2"/>
  29           <template-varargs/>
  30           <template-type-parameter name="TN"/>
  31         </template>
  32
  33         <type>U *</type>
  34
  35         <parameter name="operand">
  36           <paramtype><classname>variant</classname>&lt;T1, T2, ..., TN&gt; *</paramtype>
  37         </parameter>
  38       </signature>
  39
  40       <signature>
  41         <template>
  42           <template-type-parameter name="U"/>
  43           <template-type-parameter name="T1"/>
  44           <template-type-parameter name="T2"/>
  45           <template-varargs/>
  46           <template-type-parameter name="TN"/>
  47         </template>
  48
  49         <type>const U *</type>
  50
  51         <parameter name="operand">
  52           <paramtype>const <classname>variant</classname>&lt;T1, T2, ..., TN&gt; *</paramtype>
  53         </parameter>
  54       </signature>
  55
  56       <signature>
  57         <template>
  58           <template-type-parameter name="U"/>
  59           <template-type-parameter name="T1"/>
  60           <template-type-parameter name="T2"/>
  61           <template-varargs/>
  62           <template-type-parameter name="TN"/>
  63         </template>
  64
  65         <type>U &amp;</type>
  66
  67         <parameter name="operand">
  68           <paramtype><classname>variant</classname>&lt;T1, T2, ..., TN&gt; &amp;</paramtype>
  69         </parameter>
  70       </signature>
  71
  72       <signature>
  73         <template>
  74           <template-type-parameter name="U"/>
  75           <template-type-parameter name="T1"/>
  76           <template-type-parameter name="T2"/>
  77           <template-varargs/>
  78           <template-type-parameter name="TN"/>
  79         </template>
  80
  81         <type>const U &amp;</type>
  82
  83         <parameter name="operand">
  84           <paramtype>const <classname>variant</classname>&lt;T1, T2, ..., TN&gt; &amp;</paramtype>
  85         </parameter>
  86       </signature>
  87
  88       <purpose>
  89         <simpara>Retrieves a value of a specified type from a given
  90           <code><classname>variant</classname></code>.</simpara>
  91       </purpose>
  92
  93       <description>
  94         <simpara>The <code>get</code> function allows run-time checked,
  95           type-safe retrieval of the content of the given
  96           <code><classname>variant</classname></code>. The function succeeds
  97           only if the content is of the specified type <code>U</code>, with
  98           failure indicated as described below.</simpara>
  99         <simpara><emphasis role="bold">Warning</emphasis>: After either
 100           <code>operand</code> or its content is destroyed (e.g., when the
 101           given <code><classname>variant</classname></code> is assigned a
 102           value of different type), the returned reference is invalidated.
 103           Thus, significant care and caution must be extended when handling
 104           the returned reference.</simpara>
 105       </description>
 106
 107       <notes>
 108         <simpara>As part of its guarantee of type-safety, <code>get</code>
 109         enforces <code>const</code>-correctness. Thus, the specified type
 110         <code>U</code> must be <code>const</code>-qualified whenever
 111         <code>operand</code> or its content is likewise
 112         <code>const</code>-qualified. The converse, however, is not required:
 113         that is, the specified type <code>U</code> may be
 114         <code>const</code>-qualified even when <code>operand</code> and its
 115         content are not.</simpara>
 116       </notes>
 117
 118       <returns>
 119         <simpara>If passed a pointer, <code>get</code> returns a pointer to
 120         the value content if it is of the specified type <code>U</code>;
 121         otherwise, a null pointer is returned. If passed a reference,
 122         <code>get</code> returns a reference to the value content if it is of
 123         the specified type <code>U</code>; otherwise, an exception is thrown
 124         (see below).</simpara>
 125       </returns>
 126
 127       <throws>
 128         <simpara>Overloads taking a
 129         <code><classname>variant</classname></code> pointer will not
 130         throw; the overloads taking a
 131         <code><classname>variant</classname></code> reference throw
 132         <code><classname>bad_get</classname></code> if the content is not of
 133         the specified type <code>U</code>.</simpara>
 134       </throws>
 135
 136       <rationale>
 137         <simpara>While visitation via
 138         <code><functionname>apply_visitor</functionname></code>
 139         is generally preferred due to its greater safety, <code>get</code> may
 140         may be more convenient in some cases due to its straightforward
 141         usage.</simpara>
 142       </rationale>
 143     </overloaded-function>
 144
 145   </namespace>
 146 </header>