Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/libs/conversion/cast.htm @ 29

Last change on this file since 29 was 29, checked in by landauf, 16 years ago

updated boost from 1_33_1 to 1_34_1
File size: 6.0 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2
3<html>
4  <head>
5    <meta name="generator" content=
6    "Microsoft FrontPage 5.0">
7    <meta http-equiv="Content-Type" content=
8    "text/html; charset=windows-1252">
9    <meta name="GENERATOR" content="Microsoft FrontPage 4.0">
10    <meta name="ProgId" content="FrontPage.Editor.Document">
11
12    <title>Header boost/cast.hpp Documentation</title>
13  </head>
14
15  <body bgcolor="#FFFFFF" text="#000000">
16    <h1><img src="../../boost.png" alt="boost.png (6897 bytes)" align=
17    "middle" width="277" height="86">Header <a href=
18    "../../boost/cast.hpp">boost/cast.hpp</a></h1>
19
20    <h2><a name="Cast Functions">Cast Functions</a></h2>
21
22    <p>The header <a href="../../boost/cast.hpp">boost/cast.hpp</a> provides <code>
23    <a href="#Polymorphic_cast">polymorphic_cast</a> and</code> <a href=
24    "#Polymorphic_cast"><code>polymorphic_downcast</code></a> function templates designed to
25    complement the C++ built-in casts.</p>
26
27    <p>The program <a href="cast_test.cpp">cast_test.cpp</a> can be used to
28    verify these function templates work as expected.</p>
29
30    <h3><a name="Polymorphic_cast">Polymorphic casts</a></h3>
31
32    <p>Pointers to polymorphic objects (objects of classes which define at
33    least one virtual function) are sometimes downcast or crosscast.
34    Downcasting means casting from a base class to a derived class.
35    Crosscasting means casting across an inheritance hierarchy diagram, such
36    as from one base to the other in a <code>Y</code> diagram hierarchy.</p>
37
38    <p>Such casts can be done with old-style casts, but this approach is
39    never to be recommended. Old-style casts are sorely lacking in type
40    safety, suffer poor readability, and are difficult to locate with search
41    tools.</p>
42
43    <p>The C++ built-in <code>static_cast</code> can be used for efficiently
44    downcasting pointers to polymorphic objects, but provides no error
45    detection for the case where the pointer being cast actually points to
46    the wrong derived class. The <code>polymorphic_downcast</code> template retains
47    the efficiency of <code>static_cast</code> for non-debug compilations, but for
48    debug compilations adds safety via an assert() that a <code>dynamic_cast</code>
49    succeeds.</p>
50
51    <p>The C++ built-in <code>dynamic_cast</code> can be used for downcasts and
52    crosscasts of pointers to polymorphic objects, but error notification in
53    the form of a returned value of 0 is inconvenient to test, or worse yet,
54    easy to forget to test. The throwing form of <code>dynamic_cast</code>, which
55    works on references, can be used on pointers through the ugly expression
56    &amp;<code>dynamic_cast&lt;T&amp;&gt;(*p)</code>, which causes undefined
57    behavior if <code>p</code> is <code>0</code>. The <code>polymorphic_cast</code>
58    template performs a <code>dynamic_cast</code> on a pointer, and throws an
59    exception if the <code>dynamic_cast</code> returns 0.</p>
60
61    <p>A <code>polymorphic_downcast</code> should be used for
62    downcasts that you are certain should succeed.  Error checking is
63    only performed in translation units where <code>NDEBUG</code> is
64    not defined, via
65<pre>  assert( dynamic_cast&lt;Derived&gt;(x) == x )
66</pre> where <code>x</code> is the source pointer.  This approach
67    ensures that not only is a non-zero pointer returned, but also
68    that it is correct in the presence of multiple inheritance.
69    Attempts to crosscast using <code>polymorphic_downcast</code> will
70    fail to compile.
71    <b>Warning:</b> Because <code>polymorphic_downcast</code> uses assert(), it
72    violates the One Definition Rule (ODR) if NDEBUG is inconsistently
73    defined across translation units. [See ISO Std 3.2]
74</p><p>
75    For crosscasts, or when the success of a cast can only be known at
76    runtime, or when efficiency is not important,
77    <code>polymorphic_cast</code> is preferred. </p>
78
79    <p>The C++ built-in <code>dynamic_cast</code> must be used to cast references
80    rather than pointers. It is also the only cast that can be used to check
81    whether a given interface is supported; in that case a return of 0 isn't
82    an error condition.</p>
83
84    <h3>polymorphic_cast and polymorphic_downcast synopsis</h3>
85
86    <blockquote>
87<pre>namespace boost {
88
89template &lt;class Derived, class Base&gt;
90inline Derived polymorphic_cast(Base* x);
91// Throws: std::bad_cast if ( dynamic_cast&lt;Derived&gt;(x) == 0 )
92// Returns: dynamic_cast&lt;Derived&gt;(x)
93
94template &lt;class Derived, class Base&gt;
95inline Derived polymorphic_downcast(Base* x);
96// Effects: assert( dynamic_cast&lt;Derived&gt;(x) == x );
97// Returns: static_cast&lt;Derived&gt;(x)
98
99}
100</pre>
101    </blockquote>
102
103    <h3>polymorphic_downcast example</h3>
104
105    <blockquote>
106<pre>#include &lt;boost/cast.hpp&gt;
107...
108class Fruit { public: virtual ~Fruit(){}; ... };
109class Banana : public Fruit { ... };
110...
111void f( Fruit * fruit ) {
112// ... logic which leads us to believe it is a Banana
113  Banana * banana = boost::polymorphic_downcast&lt;Banana*&gt;(fruit);
114  ...
115</pre>
116    </blockquote>
117
118    <h3>History</h3>
119
120    <p><code>polymorphic_cast</code> was suggested by Bjarne Stroustrup in "The C++
121    Programming Language".<br>
122     <code>polymorphic_downcast</code> was contributed by <a href=
123    "../../people/dave_abrahams.htm">Dave Abrahams</a>.<code><br>
124     An old
125     numeric_cast</code> that was contributed by <a href=
126    "../../people/kevlin_henney.htm">Kevlin Henney</a> is now superseeded by the <a href="../numeric/conversion/doc/index.html">Boost Numeric Conversion Library</a></p>
127    <hr>
128
129    <p>Revised
130    <!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan
131                    -->June 23, 2005<!--webbot bot="Timestamp" endspan i-checksum="30348"
132                    --></p>
133
134    <p>&copy; Copyright boost.org 1999. Permission to copy, use, modify, sell
135    and distribute this document is granted provided this copyright notice
136    appears in all copies. This document is provided "as is" without express
137    or implied warranty, and with no claim as to its suitability for any
138    purpose.</p>
139  </body>
140</html>
Note: See TracBrowser for help on using the repository browser.