2002-02-06 19:42:04 +00:00
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2001-01-06 16:25:08 +00:00
< html >
2003-09-15 16:30:22 +00:00
< head >
< meta name = "generator" content =
2005-06-23 23:33:01 +00:00
"Microsoft FrontPage 5.0" >
2003-09-15 16:30:22 +00:00
< meta http-equiv = "Content-Type" content =
"text/html; charset=windows-1252" >
< meta name = "GENERATOR" content = "Microsoft FrontPage 4.0" >
< meta name = "ProgId" content = "FrontPage.Editor.Document" >
2001-01-06 16:25:08 +00:00
2003-09-15 16:30:22 +00:00
< title > Header boost/cast.hpp Documentation</ title >
2013-07-24 08:46:08 +00:00
< style >
. copyright
{
color : #666666 ;
font-size : small ;
}
</ style >
2003-09-15 16:30:22 +00:00
</ head >
2001-01-06 16:25:08 +00:00
2003-09-15 16:30:22 +00:00
< body bgcolor = "#FFFFFF" text = "#000000" >
2004-10-05 15:45:52 +00:00
< h1 >< img src = "../../boost.png" alt = "boost.png (6897 bytes)" align =
2003-09-15 16:30:22 +00:00
"middle" width = "277" height = "86" > Header < a href =
"../../boost/cast.hpp" > boost/cast.hpp</ a ></ h1 >
2001-01-06 16:25:08 +00:00
2003-09-15 16:30:22 +00:00
< h2 >< a name = "Cast Functions" > Cast Functions</ a ></ h2 >
2002-02-06 19:42:04 +00:00
2005-06-23 23:33:01 +00:00
< p > The header < a href = "../../boost/cast.hpp" > boost/cast.hpp</ a > provides < code >
< a href = "#Polymorphic_cast" > polymorphic_cast</ a > and</ code > < a href =
"#Polymorphic_cast" >< code > polymorphic_downcast</ code ></ a > function templates designed to
2003-09-15 16:30:22 +00:00
complement the C++ built-in casts.</ p >
2002-02-06 19:42:04 +00:00
2003-09-15 16:30:22 +00:00
< p > The program < a href = "cast_test.cpp" > cast_test.cpp</ a > can be used to
verify these function templates work as expected.</ p >
2002-02-06 19:42:04 +00:00
2003-09-15 16:30:22 +00:00
< h3 >< a name = "Polymorphic_cast" > Polymorphic casts</ a ></ h3 >
< p > Pointers to polymorphic objects (objects of classes which define at
least one virtual function) are sometimes downcast or crosscast.
Downcasting means casting from a base class to a derived class.
Crosscasting means casting across an inheritance hierarchy diagram, such
2005-02-26 14:58:12 +00:00
as from one base to the other in a < code > Y</ code > diagram hierarchy.</ p >
2003-09-15 16:30:22 +00:00
< p > Such casts can be done with old-style casts, but this approach is
never to be recommended. Old-style casts are sorely lacking in type
safety, suffer poor readability, and are difficult to locate with search
tools.</ p >
2005-02-26 14:58:12 +00:00
< p > The C++ built-in < code > static_cast</ code > can be used for efficiently
2003-09-15 16:30:22 +00:00
downcasting pointers to polymorphic objects, but provides no error
detection for the case where the pointer being cast actually points to
2005-02-26 14:58:12 +00:00
the wrong derived class. The < code > polymorphic_downcast</ code > template retains
the efficiency of < code > static_cast</ code > for non-debug compilations, but for
debug compilations adds safety via an assert() that a < code > dynamic_cast</ code >
2003-09-15 16:30:22 +00:00
succeeds.</ p >
2005-02-26 14:58:12 +00:00
< p > The C++ built-in < code > dynamic_cast</ code > can be used for downcasts and
2003-09-15 16:30:22 +00:00
crosscasts of pointers to polymorphic objects, but error notification in
the form of a returned value of 0 is inconvenient to test, or worse yet,
2005-02-26 14:58:12 +00:00
easy to forget to test. The throwing form of < code > dynamic_cast</ code > , which
2003-09-15 16:30:22 +00:00
works on references, can be used on pointers through the ugly expression
& < code > dynamic_cast< T&> (*p)</ code > , which causes undefined
2005-02-26 14:58:12 +00:00
behavior if < code > p</ code > is < code > 0</ code > . The < code > polymorphic_cast</ code >
template performs a < code > dynamic_cast</ code > on a pointer, and throws an
exception if the < code > dynamic_cast</ code > returns 0.</ p >
2003-09-15 16:30:22 +00:00
2005-02-26 14:58:12 +00:00
< p > A < code > polymorphic_downcast</ code > should be used for
downcasts that you are certain should succeed. Error checking is
only performed in translation units where < code > NDEBUG</ code > is
2005-06-23 23:33:01 +00:00
not defined, via
< pre > assert( dynamic_cast< Derived> (x) == x )
2005-02-26 14:58:12 +00:00
</ pre > where < code > x</ code > is the source pointer. This approach
ensures that not only is a non-zero pointer returned, but also
that it is correct in the presence of multiple inheritance.
Attempts to crosscast using < code > polymorphic_downcast</ code > will
fail to compile.
< b > Warning:</ b > Because < code > polymorphic_downcast</ code > uses assert(), it
violates the One Definition Rule (ODR) if NDEBUG is inconsistently
defined across translation units. [See ISO Std 3.2]
</ p >< p >
For crosscasts, or when the success of a cast can only be known at
runtime, or when efficiency is not important,
< code > polymorphic_cast</ code > is preferred. </ p >
2003-09-15 16:30:22 +00:00
2005-02-26 14:58:12 +00:00
< p > The C++ built-in < code > dynamic_cast</ code > must be used to cast references
2003-09-15 16:30:22 +00:00
rather than pointers. It is also the only cast that can be used to check
whether a given interface is supported; in that case a return of 0 isn't
an error condition.</ p >
< h3 > polymorphic_cast and polymorphic_downcast synopsis</ h3 >
< blockquote >
2005-06-23 23:33:01 +00:00
< pre > namespace boost {
2001-01-06 16:25:08 +00:00
template < class Derived, class Base>
inline Derived polymorphic_cast(Base* x);
// Throws: std::bad_cast if ( dynamic_cast< Derived> (x) == 0 )
// Returns: dynamic_cast< Derived> (x)
template < class Derived, class Base>
inline Derived polymorphic_downcast(Base* x);
// Effects: assert( dynamic_cast< Derived> (x) == x );
// Returns: static_cast< Derived> (x)
2003-09-15 16:30:22 +00:00
}
</ pre >
</ blockquote >
< h3 > polymorphic_downcast example</ h3 >
< blockquote >
2005-06-23 23:33:01 +00:00
< pre > #include < boost/cast.hpp>
2001-01-06 16:25:08 +00:00
...
class Fruit { public: virtual ~Fruit(){}; ... };
class Banana : public Fruit { ... };
...
void f( Fruit * fruit ) {
// ... logic which leads us to believe it is a Banana
Banana * banana = boost::polymorphic_downcast< Banana*> (fruit);
2003-09-15 16:30:22 +00:00
...
</ pre >
</ blockquote >
< h3 > History</ h3 >
2005-02-26 14:58:12 +00:00
< p >< code > polymorphic_cast</ code > was suggested by Bjarne Stroustrup in "The C++
2003-09-15 16:30:22 +00:00
Programming Language".< br >
2005-02-26 14:58:12 +00:00
< code > polymorphic_downcast</ code > was contributed by < a href =
2008-02-10 14:56:22 +00:00
"http://www.boost.org/people/dave_abrahams.htm" > Dave Abrahams</ a > .< code >< br >
2005-06-23 23:33:01 +00:00
An old
numeric_cast</ code > that was contributed by < a href =
2008-08-06 15:28:17 +00:00
"http://www.boost.org/people/kevlin_henney.htm" > Kevlin Henney</ a > is now superseeded by the < a href = "../numeric/conversion/doc/html/index.html" > Boost Numeric Conversion Library</ a ></ p >
2003-09-15 16:30:22 +00:00
< hr >
2005-06-23 23:33:01 +00:00
< p > Revised
2003-09-15 16:30:22 +00:00
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan
2005-06-23 23:33:01 +00:00
--> June 23, 2005<!--webbot bot="Timestamp" endspan i-checksum="30348"
2003-09-15 16:30:22 +00:00
--> </ p >
2013-07-24 08:46:08 +00:00
< p class = "copyright" > © Copyright boost.org 1999.
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at < a href = "http://www.boost.org/LICENSE_1_0.txt" > http://www.boost.org/LICENSE_1_0.txt</ a > )
</ p >
2003-09-15 16:30:22 +00:00
</ body >
2013-07-24 08:46:08 +00:00
</ html >
