libs/smart_ptr/pointer_cast.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3     <head>
   4         <title>pointer_cast</title>
   5         <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   6     </head>
   7     <body text="#000000" bgcolor="#ffffff" link="#0000ff" vlink="#0000ff">
   8         <h1><img height="86" alt="boost.png (6897 bytes)" src="../../boost.png"
   9             width="277" align="middle" border="0">pointer_cast</h1>
  10         <p>The pointer cast functions (<code>boost::static_pointer_cast</code> <code>boost::dynamic_pointer_cast</code>
  11             <code>boost::reinterpret_pointer_cast</code> <code>boost::const_pointer_cast</code>)
  12             provide a way to write generic pointer castings for raw pointers. The functions
  13             are defined in <CITE><A href="../../boost/pointer_cast.hpp">boost/pointer_cast.hpp</A>.</CITE></p>
  14         <P>There is test/example code in <CITE><A href="test/pointer_cast_test.cpp">pointer_cast_test.cpp</A></CITE>.</p>
  15             <h2><a name="rationale">Rationale</a></h2>
  16         <P>Boost smart pointers usually overload those functions to provide a mechanism to
  17             emulate pointers casts. For example, <code>boost::shared_ptr&lt;...&gt;</code> implements
  18             a static pointer cast this way:</P>
  19         <pre>
  20 template&lt;class T, class U&gt;
  21     shared_ptr&lt;T&gt; static_pointer_cast(shared_ptr&lt;U&gt; const &amp;r);
  22 </pre>
  23         <P>Pointer cast functions from <CITE><A href="../../boost/pointer_cast.hpp">boost/pointer_cast.hpp</A></CITE>
  24             are overloads of <code>boost::static_pointer_cast</code>, <code>boost::dynamic_pointer_cast</code>,
  25             <code>boost::reinterpret_pointer_cast</code> and <code>boost::const_pointer_cast</code>
  26             for raw pointers. This way when developing pointer type independent classes,
  27             for example, memory managers or shared memory compatible classes, the same code
  28             can be used for raw and smart pointers.</p>
  29             <H2><A name="synopsis">Synopsis</A></H2>
  30             <BLOCKQUOTE>
  31                 <PRE>
  32 namespace boost {
  33
  34 template&lt;class T, class U&gt;
  35 inline T* static_pointer_cast(U *ptr)
  36   { return static_cast&lt;T*&gt;(ptr); }
  37
  38 template&lt;class T, class U&gt;
  39 inline T* dynamic_pointer_cast(U *ptr)
  40   { return dynamic_cast&lt;T*&gt;(ptr); }
  41
  42 template&lt;class T, class U&gt;
  43 inline T* const_pointer_cast(U *ptr)
  44   { return const_cast&lt;T*&gt;(ptr); }
  45
  46 template&lt;class T, class U&gt;
  47 inline T* reinterpret_pointer_cast(U *ptr)
  48   { return reinterpret_cast&lt;T*&gt;(ptr); }
  49
  50 } // namespace boost
  51 </PRE>
  52             </BLOCKQUOTE>
  53         <P>As you can see from the above synopsis, the pointer cast functions are just
  54             wrappers around standard C++ cast operators.</P>
  55         <H2><A name="example">Example</A></H2>
  56         <BLOCKQUOTE>
  57             <PRE>
  58 #include &lt;boost/pointer_cast.hpp&gt;
  59 #include &lt;boost/shared_ptr.hpp&gt;
  60
  61 class base
  62 {
  63 public:
  64
  65    virtual ~base()
  66    {
  67    }
  68 };
  69
  70 class derived: public base
  71 {
  72 };
  73
  74 template &lt;class BasePtr&gt;
  75 void check_if_it_is_derived(const BasePtr &amp;ptr)
  76 {
  77    assert(boost::dynamic_pointer_cast&lt;derived&gt;(ptr) != 0);
  78 }
  79
  80 int main()
  81 {
  82    <I>// Create a raw and a shared_ptr</I>
  83
  84    base *ptr = new derived;
  85    boost::shared_ptr&lt;base&gt; sptr(new derived);
  86
  87    <I>// Check that base pointer points actually to derived class</I>
  88
  89    check_if_it_is_derived(ptr);
  90    check_if_it_is_derived(sptr);
  91
  92    // <EM>Ok!</EM>
  93
  94    delete ptr;
  95    return 0;
  96 }</PRE>
  97         </BLOCKQUOTE>
  98         <P>The example demonstrates how the generic pointer casts help us create pointer
  99             independent code.</P>
 100         <hr>
 101         <p>$Date$</p>
 102         <p>Copyright 2005 Ion Gaztañaga. Use, modification, and distribution are subject to
 103             the Boost Software License, Version 1.0. (See accompanying file <A href="../../LICENSE_1_0.txt">
 104             LICENSE_1_0.txt</A> or a copy at &lt;<A href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>&gt;.)</p>
 105     </body>
 106 </html>