ceph/src/boost/libs/variant/doc/reference/recursive_wrapper.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/recursive_wrapper.hpp">
  11   <namespace name="boost">
  12
  13     <class name="recursive_wrapper">
  14       <purpose>Solves circular dependencies, enabling recursive types.</purpose>
  15
  16       <template>
  17         <template-type-parameter name="T"/>
  18       </template>
  19
  20       <description>
  21         <simpara>The <code>recursive_wrapper</code> class template has an
  22           interface similar to a simple value container, but its content is
  23           allocated dynamically. This allows <code>recursive_wrapper</code> to
  24           hold types <code>T</code> whose member data leads to a circular
  25           dependency (e.g., a data member of <code>T</code> has a data member
  26           of type <code>T</code>).</simpara>
  27
  28         <simpara>The application of <code>recursive_wrapper</code> is easiest
  29           understood in context. See
  30           <xref linkend="variant.tutorial.recursive.recursive-wrapper"/> for a
  31           demonstration of a common use of the class template.</simpara>
  32
  33         <simpara><emphasis role="bold">Notes</emphasis>:</simpara>
  34         <itemizedlist>
  35           <listitem>Any type specified as the template argument to
  36             <code>recursive_wrapper</code> must be capable of construction via
  37             <code>operator new</code>. Thus, for instance, references are not
  38             supported.</listitem>
  39         </itemizedlist>
  40       </description>
  41
  42       <typedef name="type">
  43         <type>T</type>
  44       </typedef>
  45
  46       <destructor>
  47         <purpose>Destructor.</purpose>
  48         <description>
  49           <simpara>Deletes the content of <code>*this</code>.</simpara>
  50         </description>
  51
  52         <throws>Will not throw.</throws>
  53       </destructor>
  54
  55       <constructor>
  56         <purpose>Default constructor.</purpose>
  57         <description>
  58           <simpara>Initializes <code>*this</code> by default construction of
  59             <code>T</code>.</simpara>
  60         </description>
  61
  62         <requires>
  63           <simpara><code>T</code> must fulfill the requirements of the
  64             <emphasis>DefaultConstructible</emphasis> [20.1.4]
  65             concept.</simpara>
  66         </requires>
  67
  68         <throws>
  69           <simpara>May fail with any exceptions arising from the default
  70             constructor of <code>T</code> or, in the event of
  71             insufficient memory, with <code>std::bad_alloc</code>.</simpara>
  72         </throws>
  73       </constructor>
  74
  75       <constructor>
  76         <parameter name="other">
  77           <paramtype>const recursive_wrapper &amp;</paramtype>
  78         </parameter>
  79
  80         <purpose>Copy constructor.</purpose>
  81         <description>
  82           <simpara>Copies the content of <code>other</code> into
  83             <code>*this</code>.</simpara>
  84         </description>
  85
  86         <throws>
  87           <simpara>May fail with any exceptions arising from the
  88             copy constructor of <code>T</code> or, in the event of
  89             insufficient memory, with <code>std::bad_alloc</code>.</simpara>
  90         </throws>
  91       </constructor>
  92
  93       <constructor>
  94         <parameter name="operand">
  95           <paramtype>const T &amp;</paramtype>
  96         </parameter>
  97
  98         <purpose>Value constructor.</purpose>
  99         <description>
 100           <simpara>Copies <code>operand</code> into
 101             <code>*this</code>.</simpara>
 102         </description>
 103
 104         <throws>
 105           <simpara>May fail with any exceptions arising from the
 106             copy constructor of <code>T</code> or, in the event of
 107             insufficient memory, with <code>std::bad_alloc</code>.</simpara>
 108         </throws>
 109       </constructor>
 110
 111       <method-group name="modifiers">
 112
 113         <method name="swap">
 114           <type>void</type>
 115
 116           <parameter name="other">
 117             <paramtype>recursive_wrapper &amp;</paramtype>
 118           </parameter>
 119
 120           <description>
 121             <simpara>Exchanges contents of <code>*this</code> and
 122               <code>other</code>.</simpara>
 123           </description>
 124
 125           <throws>Will not throw.</throws>
 126         </method>
 127
 128         <method name="operator=">
 129           <type>recursive_wrapper &amp;</type>
 130
 131           <parameter name="rhs">
 132             <paramtype>const recursive_wrapper &amp;</paramtype>
 133           </parameter>
 134
 135           <purpose>Copy assignment operator.</purpose>
 136           <description>
 137             <simpara>Assigns the content of <code>rhs</code> to the content of
 138               <code>*this</code>.</simpara>
 139           </description>
 140
 141           <requires>
 142             <simpara><code>T</code> must fulfill the requirements of
 143             the <conceptname>Assignable</conceptname>
 144             concept.</simpara>
 145           </requires>
 146
 147           <throws>
 148             <simpara>May fail with any exceptions arising from the assignment
 149               operator of <code>T</code>.</simpara>
 150           </throws>
 151         </method>
 152
 153         <method name="operator=">
 154           <type>recursive_wrapper &amp;</type>
 155
 156           <parameter name="rhs">
 157             <paramtype>const T &amp;</paramtype>
 158           </parameter>
 159
 160           <purpose>Value assignment operator.</purpose>
 161           <description>
 162             <simpara>Assigns <code>rhs</code> into the content of
 163               <code>*this</code>.</simpara>
 164           </description>
 165
 166           <requires>
 167             <simpara><code>T</code> must fulfill the requirements of the
 168               <conceptname>Assignable</conceptname>
 169               concept.</simpara>
 170           </requires>
 171
 172           <throws>
 173             <simpara>May fail with any exceptions arising from the assignment
 174               operator of <code>T</code>.</simpara>
 175           </throws>
 176         </method>
 177
 178       </method-group>
 179
 180       <method-group name="queries">
 181
 182         <overloaded-method name="get">
 183           <signature>
 184             <type>T &amp;</type>
 185           </signature>
 186           <signature cv="const">
 187             <type>const T &amp;</type>
 188           </signature>
 189
 190           <description>
 191             <simpara>Returns a reference to the content of
 192               <code>*this</code>.</simpara>
 193           </description>
 194
 195           <throws>Will not throw.</throws>
 196         </overloaded-method>
 197
 198         <overloaded-method name="get_pointer">
 199           <signature>
 200             <type>T *</type>
 201           </signature>
 202           <signature cv="const">
 203             <type>const T *</type>
 204           </signature>
 205
 206           <description>
 207             <simpara>Returns a pointer to the content of
 208               <code>*this</code>.</simpara>
 209           </description>
 210
 211           <throws>Will not throw.</throws>
 212         </overloaded-method>
 213
 214       </method-group>
 215
 216     </class>
 217
 218     <class name="is_recursive_wrapper">
 219       <purpose>
 220         <simpara>Determines whether the specified type is a specialization of
 221           <code>recursive_wrapper</code>.</simpara>
 222       </purpose>
 223
 224       <template>
 225         <template-type-parameter name="T"/>
 226       </template>
 227
 228       <description>
 229         <simpara>Value is true iff <code>T</code> is a specialization of
 230           <code><classname>recursive_wrapper</classname></code>.</simpara>
 231         <simpara><emphasis role="bold">Note</emphasis>:
 232           <code>is_recursive_wrapper</code> is a model of
 233           <libraryname>MPL</libraryname>'s
 234           <emphasis>IntegralConstant</emphasis> concept.</simpara>
 235       </description>
 236
 237       <typedef name="type">
 238         <type><emphasis>unspecified</emphasis></type>
 239       </typedef>
 240
 241       <static-constant name="value">
 242         <type>bool</type>
 243         <default><emphasis>unspecified</emphasis></default>
 244       </static-constant>
 245     </class>
 246
 247     <class name="unwrap_recursive_wrapper">
 248       <purpose>
 249         <simpara>Unwraps the specified argument if given a specialization of
 250           <code><classname>recursive_wrapper</classname></code>.</simpara>
 251       </purpose>
 252
 253       <template>
 254         <template-type-parameter name="T"/>
 255       </template>
 256
 257       <description>
 258         <simpara><code>type</code> is equivalent to <code>T::type</code> if
 259           <code>T</code> is a specialization of
 260           <code><classname>recursive_wrapper</classname></code>. Otherwise,
 261           <code>type</code> is equivalent to <code>T</code>.</simpara>
 262       </description>
 263
 264       <typedef name="type">
 265         <type><emphasis>unspecified</emphasis></type>
 266       </typedef>
 267     </class>
 268
 269   </namespace>
 270 </header>