Squashed 'third_party/boostorg/serialization/' content from commit 738695b
Change-Id: I48528198ad1f62b90288d249eb2243d4db02fd5d
git-subtree-dir: third_party/boostorg/serialization
git-subtree-split: 738695b70733f9d592a570fb17a505d6a029b48a
diff --git a/doc/smart_cast.html b/doc/smart_cast.html
new file mode 100644
index 0000000..f438226
--- /dev/null
+++ b/doc/smart_cast.html
@@ -0,0 +1,155 @@
+<!doctype HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<!--
+(C) Copyright 2002-4 Robert Ramey - http://www.rrsd.com .
+Use, modification and distribution is subject to the Boost Software
+License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
+http://www.boost.org/LICENSE_1_0.txt)
+-->
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<link rel="stylesheet" type="text/css" href="../../../boost.css">
+<link rel="stylesheet" type="text/css" href="style.css">
+<title>Serialization - BOOST_STATIC_WARNING</title>
+</head>
+<body link="#0000ff" vlink="#800080">
+<table border="0" cellpadding="7" cellspacing="0" width="100%" summary="header">
+ <tr>
+ <td valign="top" width="300">
+ <h3><a href="../../../index.htm"><img height="86" width="277" alt="C++ Boost" src="../../../boost.png" border="0"></a></h3>
+ </td>
+ <td valign="top">
+ <h1 align="center">Serialization</h1>
+ <h2 align="center"><code>smart_cast</code></h2>
+ </td>
+ </tr>
+</table>
+<hr>
+<h3>Motivation</h3>
+To cast from one type to another related type, C++ provides the following
+operators:
+
+<dl>
+ <dt><code>static_cast<T *<>(U *)<br>static_cast<T &<>(U &)</code></dt>
+ <dd>
+ <ul>
+ <li>required if neither T nor U are polymorphic
+ <li>permitted in other cases.
+ <li>fails to detect erroneous casts of polymophic pointers/references at runtime.
+ <li>does not permit "cross casting"
+ <li>inline function calls can be optimized away during compile time.
+ </ul>
+ </dd>
+ <p>
+ <dt><code>dynamic_cast<T *<>(U *)<br>dynamic_cast<T &<>(U &)</code></dt>
+ <dd>
+ <ul>
+ <li>permitted if either T or U are polymorphic
+ <li>prohibited in other cases.
+ <li>throws exception on detecting erroneous casts of polymorphic pointers/references
+ at runtime.
+ <li>permits "cross casting"
+ <li>cannot optimise inline virtual functions at compile time.
+ </ul>
+ </dd>
+</dl>
+
+These rules can make it difficult to use casting with a function template argument.
+Consider the following example:
+
+<pre><code>
+#include <boost/serialization/smart_cast.hpp>
+
+struct top {
+};
+
+struct base1 : public top {
+ bool is_storable() const {
+ return true;
+ }
+ virtual ~base1();
+};
+
+struct base2 {
+ virtual ~base2();
+};
+
+struct derived1 :
+ public base1
+{
+ derived1();
+};
+
+struct derived2 :
+ public base1,
+ public base2
+{
+ derived2();
+};
+
+template<class T>
+bool is_storable(T &t){
+ // what type of cast to use here?
+
+ // this fails at compile time when T == base2
+ // return static_cast<base1 &>(t).is_storable();
+
+ // this fails at compile time when T == top
+ // otherwise it works but cannot optimize inline function call
+ // return dynamic_cast<base1 &>(t).is_storable();
+
+ // this always works - and is guaranteed to generate the fastest code !
+ return (boost::smart_cast_reference<base1 &>(t)).is_storable();
+}
+
+int main(){
+ derived1 d1;
+ top & t1 = d1;
+ derived2 d2;
+ base2 & b2 = d2;
+
+ bool result;
+ result = is_storable(d1);
+ result = is_storable(d2);
+ result = is_storable(b2);
+ result = is_storable(b2);
+ result = is_storable(t1);
+ return 0;
+}
+</code></pre>
+The serialization library includes a mix of classes which use
+both static polymorphism (<strong>CRTP</strong>) and dynamic
+polymorphism via virtual functions. <code style="white-space: normal">smart_cast</code>
+was written to address the more problematic manifestations of the
+situation exemplified above.
+
+<h3>Usage</h3>
+The following syntax is supported:
+<pre><code>
+smart_cast<Target *, Source *>(Source * s);
+smart_cast<Target *>(Source * s);
+smart_cast<Target &, Source &>(Source & s);
+</code></pre>
+Note that the above syntax doesn't include
+<pre><code>
+smart_cast<Target & >(Source & s)
+</code></pre>
+but the same functionality is supported with the following special syntax
+<pre><code>
+smart_cast_reference<Target &>(Source & s)
+</code></pre>
+
+<h3>Requirements</h3>
+<code style="white-space: normal">smart_cast</code> can be used only on compilers that support partial
+template specialization or on types for which the
+macro <code style="white-space: normal">
+BOOST_BROKEN_COMPILER_TYPE_TRAITS_SPECIALIZATION(<type>)</code>
+has been applied.
+
+<hr>
+<p><i>© Copyright <a href="http://www.rrsd.com">Robert Ramey</a> 2002-2004.
+Distributed under the Boost Software License, Version 1.0. (See
+accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+</i></p>
+</body>
+</html>