ceph/src/boost/libs/serialization/doc/smart_cast.html

   1 <!doctype HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html>
   3 <!--
   4 (C) Copyright 2002-4 Robert Ramey - http://www.rrsd.com .
   5 Use, modification and distribution is subject to the Boost Software
   6 License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
   7 http://www.boost.org/LICENSE_1_0.txt)
   8 -->
   9 <head>
  10 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
  11 <link rel="stylesheet" type="text/css" href="../../../boost.css">
  12 <link rel="stylesheet" type="text/css" href="style.css">
  13 <title>Serialization - BOOST_STATIC_WARNING</title>
  14 </head>
  15 <body link="#0000ff" vlink="#800080">
  16 <table border="0" cellpadding="7" cellspacing="0" width="100%" summary="header">
  17   <tr>
  18     <td valign="top" width="300">
  19       <h3><a href="../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../boost.png" border="0"></a></h3>
  20     </td>
  21     <td valign="top">
  22       <h1 align="center">Serialization</h1>
  23       <h2 align="center"><code>smart_cast</code></h2>
  24     </td>
  25   </tr>
  26 </table>
  27 <hr>
  28 <h3>Motivation</h3>
  29 To cast from one type to another related type, C++ provides the following
  30 operators:
  31
  32 <dl>
  33   <dt><code>static_cast&lt;T *<&gt;(U *)<br>static_cast&lt;T &<&gt;(U &)</code></dt>
  34   <dd>
  35     <ul>
  36       <li>required if neither T nor U are polymorphic
  37       <li>permitted in other cases.
  38       <li>fails to detect erroneous casts of polymophic pointers/references at runtime.
  39       <li>does not permit "cross casting"
  40       <li>inline function calls can be optimized away during compile time.
  41     </ul>
  42   </dd>
  43   <p>
  44   <dt><code>dynamic_cast&lt;T *<&gt;(U *)<br>dynamic_cast&lt;T &<&gt;(U &)</code></dt>
  45   <dd>
  46     <ul>
  47       <li>permitted if either T or U are polymorphic
  48       <li>prohibited in other cases.
  49       <li>throws exception on detecting erroneous casts of polymorphic pointers/references
  50           at runtime.
  51       <li>permits "cross casting"
  52       <li>cannot optimise inline virtual functions at compile time.
  53     </ul>
  54   </dd>
  55 </dl>
  56
  57 These rules can make it difficult to use casting with a function template argument.
  58 Consider the following example:
  59
  60 <pre><code>
  61 #include &lt;boost/serialization/smart_cast.hpp&gt;
  62
  63 struct top {
  64 };
  65
  66 struct base1 : public top {
  67     bool is_storable() const {
  68         return true;
  69     }
  70     virtual ~base1();
  71 };
  72
  73 struct base2 {
  74     virtual ~base2();
  75 };
  76
  77 struct derived1 :
  78     public base1
  79 {
  80     derived1();
  81 };
  82
  83 struct derived2 :
  84     public base1,
  85     public base2
  86 {
  87     derived2();
  88 };
  89
  90 template&lt;class T&gt;
  91 bool is_storable(T &amp;t){
  92     // what type of cast to use here?
  93
  94     // this fails at compile time when T == base2
  95     // return static_cast&lt;base1 &amp;&gt;(t).is_storable();
  96
  97     // this fails at compile time when T == top
  98     // otherwise it works but cannot optimize inline function call
  99     // return dynamic_cast&lt;base1 &amp;&gt;(t).is_storable();
 100
 101     // this always works - and is guaranteed to generate the fastest code !
 102     return (boost::smart_cast_reference&lt;base1 &amp;&gt;(t)).is_storable();
 103 }
 104
 105 int main(){
 106     derived1 d1;
 107     top &amp; t1 = d1;
 108     derived2 d2;
 109     base2 &amp; b2 = d2;
 110
 111     bool result;
 112     result = is_storable(d1);
 113     result = is_storable(d2);
 114     result = is_storable(b2);
 115     result = is_storable(b2);
 116     result = is_storable(t1);
 117     return 0;
 118 }
 119 </code></pre>
 120 The serialization library includes a mix of classes which use
 121 both static polymorphism (<strong>CRTP</strong>) and dynamic
 122 polymorphism via virtual functions.  <code style="white-space: normal">smart_cast</code>
 123 was written to address the more problematic manifestations of the
 124 situation exemplified above.
 125
 126 <h3>Usage</h3>
 127 The following syntax is supported:
 128 <pre><code>
 129 smart_cast&lt;Target *, Source *&gt;(Source * s);
 130 smart_cast&lt;Target *>(Source * s);
 131 smart_cast&lt;Target &, Source &amp;&gt(Source &amp; s);
 132 </code></pre>
 133 Note that the above syntax doesn't include
 134 <pre><code>
 135 smart_cast&lt;Target &amp; &gt(Source &amp; s)
 136 </code></pre>
 137 but the same functionality is supported with the following special syntax
 138 <pre><code>
 139 smart_cast_reference&lt;Target &amp;&gt(Source &amp; s)
 140 </code></pre>
 141
 142 <h3>Requirements</h3>
 143 <code style="white-space: normal">smart_cast</code> can be used only on compilers that support partial
 144 template specialization or on types for which the
 145 macro <code style="white-space: normal">
 146 BOOST_BROKEN_COMPILER_TYPE_TRAITS_SPECIALIZATION(&lt;type&gt;)</code>
 147 has been applied.
 148
 149 <hr>
 150 <p><i>&copy; Copyright <a href="http://www.rrsd.com">Robert Ramey</a> 2002-2004.
 151 Distributed under the Boost Software License, Version 1.0. (See
 152 accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 153 </i></p>
 154 </body>
 155 </html>