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-20014, 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_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       </purpose>
  98
  99       <description>
 100         <simpara>The <code>polymorphic_get</code> function allows run-time checked,
 101           type-safe retrieval of the content of the given
 102           <code><classname>variant</classname></code>. The function succeeds
 103           only if the content is of the specified type <code>U</code> or of type
 104           derived from type <code>U</code>, with
 105           failure indicated as described below.</simpara>
 106         <simpara><emphasis role="bold">Warning</emphasis>: After either
 107           <code>operand</code> or its content is destroyed (e.g., when the
 108           given <code><classname>variant</classname></code> is assigned a
 109           value of different type), the returned reference is invalidated.
 110           Thus, significant care and caution must be extended when handling
 111           the returned reference.</simpara>
 112       </description>
 113
 114       <notes>
 115         <simpara>As part of its guarantee of type-safety, <code>polymorphic_get</code>
 116         enforces <code>const</code>-correctness. Thus, the specified type
 117         <code>U</code> must be <code>const</code>-qualified whenever
 118         <code>operand</code> or its content is likewise
 119         <code>const</code>-qualified. The converse, however, is not required:
 120         that is, the specified type <code>U</code> may be
 121         <code>const</code>-qualified even when <code>operand</code> and its
 122         content are not.</simpara>
 123       </notes>
 124
 125       <returns>
 126         <simpara>If passed a pointer, <code>polymorphic_get</code> returns a pointer to
 127         the value content if it is of the specified type <code>U</code> or of type
 128         derived from type <code>U</code>;
 129         otherwise, a null pointer is returned. If passed a reference,
 130         <code>polymorphic_get</code> returns a reference to the value content if it is of
 131         the specified type <code>U</code>  or of type
 132           derived from type <code>U</code>; otherwise, an exception is thrown
 133         (see below).</simpara>
 134       </returns>
 135
 136       <throws>
 137         <simpara>Overloads taking a
 138         <code><classname>variant</classname></code> pointer will not
 139         throw; the overloads taking a
 140         <code><classname>variant</classname></code> reference throw
 141         <code><classname>bad_polymorphic_get</classname></code> if the content is not of
 142         the specified type <code>U</code>or of type
 143         derived from type <code>U</code>.</simpara>
 144       </throws>
 145
 146       <rationale>
 147         <simpara>While visitation via
 148         <code><functionname>apply_visitor</functionname></code>
 149         is generally preferred due to its greater safety, <code>polymorphic_get</code> may
 150         may be more convenient in some cases due to its straightforward
 151         usage.</simpara>
 152       </rationale>
 153     </overloaded-function>
 154
 155   </namespace>
 156 </header>