ceph/src/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 <!--
   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>&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>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>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>, with
 106           failure indicated as described below.</simpara>
 107         <simpara><emphasis role="bold">Recomendation</emphasis>: Use
 108           <functionname>get</functionname> or <functionname>strict_get</functionname> in new code.
 109           <functionname>strict_get</functionname>
 110           provides more compile time checks and its behavior is closer to <code>std::get</code>
 111           from C++ Standard Library.</simpara>
 112         <simpara><emphasis role="bold">Warning</emphasis>: After either
 113           <code>operand</code> or its content is destroyed (e.g., when the
 114           given <code><classname>variant</classname></code> is assigned a
 115           value of different type), the returned reference is invalidated.
 116           Thus, significant care and caution must be extended when handling
 117           the returned reference.</simpara>
 118       </description>
 119
 120       <notes>
 121         <simpara>As part of its guarantee of type-safety, <code>get</code>
 122         enforces <code>const</code>-correctness. Thus, the specified type
 123         <code>U</code> must be <code>const</code>-qualified whenever
 124         <code>operand</code> or its content is likewise
 125         <code>const</code>-qualified. The converse, however, is not required:
 126         that is, the specified type <code>U</code> may be
 127         <code>const</code>-qualified even when <code>operand</code> and its
 128         content are not.</simpara>
 129       </notes>
 130
 131       <returns>
 132         <simpara>If passed a pointer, <code>get</code> returns a pointer to
 133         the value content if it is of the specified type <code>U</code>;
 134         otherwise, a null pointer is returned. If passed a reference,
 135         <code>get</code> returns a reference to the value content if it is of
 136         the specified type <code>U</code>; otherwise, an exception is thrown
 137         (see below).</simpara>
 138       </returns>
 139
 140       <throws>
 141         <simpara>Overloads taking a
 142         <code><classname>variant</classname></code> pointer will not
 143         throw; the overloads taking a
 144         <code><classname>variant</classname></code> reference throw
 145         <code><classname>bad_get</classname></code> if the content is not of
 146         the specified type <code>U</code>.</simpara>
 147       </throws>
 148
 149       <rationale>
 150         <simpara>While visitation via
 151         <code><functionname>apply_visitor</functionname></code>
 152         is generally preferred due to its greater safety, <code>get</code> may
 153         may be more convenient in some cases due to its straightforward
 154         usage.</simpara>
 155       </rationale>
 156     </overloaded-function>
 157
 158     <overloaded-function name="strict_get">
 159       <signature>
 160         <template>
 161           <template-type-parameter name="U"/>
 162           <template-type-parameter name="T1"/>
 163           <template-type-parameter name="T2"/>
 164           <template-varargs/>
 165           <template-type-parameter name="TN"/>
 166         </template>
 167
 168         <type>U *</type>
 169
 170         <parameter name="operand">
 171           <paramtype><classname>variant</classname>&lt;T1, T2, ..., TN&gt; *</paramtype>
 172         </parameter>
 173       </signature>
 174
 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>const U *</type>
 185
 186         <parameter name="operand">
 187           <paramtype>const <classname>variant</classname>&lt;T1, T2, ..., TN&gt; *</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>U &amp;</type>
 201
 202         <parameter name="operand">
 203           <paramtype><classname>variant</classname>&lt;T1, T2, ..., TN&gt; &amp;</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>const U &amp;</type>
 217
 218         <parameter name="operand">
 219           <paramtype>const <classname>variant</classname>&lt;T1, T2, ..., TN&gt; &amp;</paramtype>
 220         </parameter>
 221       </signature>
 222
 223       <purpose>
 224         <simpara>Retrieves a value of a specified type from a given
 225           <code><classname>variant</classname></code>.</simpara>
 226       </purpose>
 227
 228       <description>
 229         <simpara>Acts exactly like <functionname>relaxed_get</functionname> but does a compile time check
 230         that type <code>U</code> is one of the types that can be stored in variant.</simpara>
 231       </description>
 232     </overloaded-function>
 233
 234     <overloaded-function name="get">
 235       <signature>
 236         <template>
 237           <template-type-parameter name="U"/>
 238           <template-type-parameter name="T1"/>
 239           <template-type-parameter name="T2"/>
 240           <template-varargs/>
 241           <template-type-parameter name="TN"/>
 242         </template>
 243
 244         <type>U *</type>
 245
 246         <parameter name="operand">
 247           <paramtype><classname>variant</classname>&lt;T1, T2, ..., TN&gt; *</paramtype>
 248         </parameter>
 249       </signature>
 250
 251       <signature>
 252         <template>
 253           <template-type-parameter name="U"/>
 254           <template-type-parameter name="T1"/>
 255           <template-type-parameter name="T2"/>
 256           <template-varargs/>
 257           <template-type-parameter name="TN"/>
 258         </template>
 259
 260         <type>const U *</type>
 261
 262         <parameter name="operand">
 263           <paramtype>const <classname>variant</classname>&lt;T1, T2, ..., TN&gt; *</paramtype>
 264         </parameter>
 265       </signature>
 266
 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 &amp;</type>
 277
 278         <parameter name="operand">
 279           <paramtype><classname>variant</classname>&lt;T1, T2, ..., TN&gt; &amp;</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 &amp;</type>
 293
 294         <parameter name="operand">
 295           <paramtype>const <classname>variant</classname>&lt;T1, T2, ..., TN&gt; &amp;</paramtype>
 296         </parameter>
 297       </signature>
 298
 299       <purpose>
 300         <simpara>Retrieves a value of a specified type from a given
 301           <code><classname>variant</classname></code>.</simpara>
 302       </purpose>
 303
 304       <description>
 305         <simpara>Evaluates to <functionname>strict_get</functionname> if <code>BOOST_VARIANT_USE_RELAXED_GET_BY_DEFAULT</code>
 306           is not defined. If <code>BOOST_VARIANT_USE_RELAXED_GET_BY_DEFAULT</code>
 307           is defined then evaluates to <functionname>relaxed_get</functionname>. </simpara>
 308
 309         <simpara><emphasis role="bold">Recomendation</emphasis>: Use
 310           <functionname>get</functionname> in new code without defining
 311           <code>BOOST_VARIANT_USE_RELAXED_GET_BY_DEFAULT</code>. In that way <functionname>get</functionname>
 312           provides more compile time checks and its behavior is closer to <code>std::get</code>
 313           from C++ Standard Library.</simpara>
 314       </description>
 315     </overloaded-function>
 316
 317   </namespace>
 318 </header>