From 462025d8e6eb0d9881c55170620018cb59a91ca9 Mon Sep 17 00:00:00 2001 From: Dave Abrahams Date: Sat, 26 Feb 2005 14:58:12 +0000 Subject: [PATCH] Fix docs [SVN r27509] --- cast.htm | 72 +++++++++++++++++++++++++++++++------------------------- 1 file changed, 40 insertions(+), 32 deletions(-) diff --git a/cast.htm b/cast.htm index 4c7bac7..a7e55f2 100644 --- a/cast.htm +++ b/cast.htm @@ -20,9 +20,9 @@

Cast Functions

The header boost/cast.hpp provides - polymorphic_cast, polymorphic_downcast, and numeric_cast function templates designed to + polymorphic_cast, polymorphic_downcast, and numeric_cast function templates designed to complement the C++ built-in casts.

The program cast_test.cpp can be used to @@ -34,43 +34,51 @@ 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 - as from one base to the other in a Y diagram hierarchy.

+ as from one base to the other in a Y diagram hierarchy.

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.

-

The C++ built-in static_cast can be used for efficiently +

The C++ built-in static_cast can be used for efficiently downcasting pointers to polymorphic objects, but provides no error detection for the case where the pointer being cast actually points to - the wrong derived class. The polymorphic_downcast template retains - the efficiency of static_cast for non-debug compilations, but for - debug compilations adds safety via an assert() that a dynamic_cast + the wrong derived class. The polymorphic_downcast template retains + the efficiency of static_cast for non-debug compilations, but for + debug compilations adds safety via an assert() that a dynamic_cast succeeds.

-

The C++ built-in dynamic_cast can be used for downcasts and +

The C++ built-in dynamic_cast can be used for downcasts and 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, - easy to forget to test. The throwing form of dynamic_cast, which + easy to forget to test. The throwing form of dynamic_cast, which works on references, can be used on pointers through the ugly expression &dynamic_cast<T&>(*p), which causes undefined - behavior if p is 0. The polymorphic_cast - template performs a dynamic_cast on a pointer, and throws an - exception if the dynamic_cast returns 0.

+ behavior if p is 0. The polymorphic_cast + template performs a dynamic_cast on a pointer, and throws an + exception if the dynamic_cast returns 0.

-

A polymorphic_downcast is preferred when debug-mode tests will - cover 100% of the object types possibly cast and when non-debug-mode - efficiency is an issue. If these two conditions are not present, - polymorphic_cast is preferred. It must also be used for - crosscasts. It does an assert( dynamic_cast<Derived>(x) == x ) - where x is the base pointer, ensuring that not only is a non-zero pointer - returned, but also that it correct in the presence of multiple - inheritance. Warning:: Because polymorphic_downcast uses - assert(), it violates the one definition rule (ODR) if NDEBUG is - inconsistently defined across translation units. [See ISO Std 3.2]

+

A polymorphic_downcast should be used for + downcasts that you are certain should succeed. Error checking is + only performed in translation units where NDEBUG is + not defined, via +

+  assert( dynamic_cast<Derived>(x) == x )
+
where x 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 polymorphic_downcast will + fail to compile. + Warning: Because polymorphic_downcast uses assert(), it + violates the One Definition Rule (ODR) if NDEBUG is inconsistently + defined across translation units. [See ISO Std 3.2] +

+ For crosscasts, or when the success of a cast can only be known at + runtime, or when efficiency is not important, + polymorphic_cast is preferred.

-

The C++ built-in dynamic_cast must be used to cast references +

The C++ built-in dynamic_cast must be used to cast references 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.

@@ -113,9 +121,9 @@ void f( Fruit * fruit ) {

numeric_cast

-

A static_cast or implicit conversion will not detect failure to - preserve range for numeric casts. The numeric_cast function - templates are similar to static_cast and certain (dubious) +

A static_cast or implicit conversion will not detect failure to + preserve range for numeric casts. The numeric_cast function + templates are similar to static_cast and certain (dubious) implicit conversions in this respect, except that they detect loss of numeric range. An exception is thrown when a runtime value-preservation check fails.

@@ -132,7 +140,7 @@ void f( Fruit * fruit ) { true.
  • The argument can be converted to the result type using - static_cast.
    • + static_cast. @@ -178,11 +186,11 @@ void ariane(double vx)

    History

    -

    polymorphic_cast was suggested by Bjarne Stroustrup in "The C++ +

    polymorphic_cast was suggested by Bjarne Stroustrup in "The C++ Programming Language".
    - polymorphic_downcast was contributed by Dave Abrahams.
    - numeric_cast     was contributed by polymorphic_downcast was contributed by Dave Abrahams.
    + numeric_cast     was contributed by Kevlin Henney.