mirror of
https://github.com/boostorg/smart_ptr.git
synced 2026-01-27 07:22:09 +00:00
184 lines
8.3 KiB
HTML
184 lines
8.3 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<title>pointer_cast</title>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
|
|
</head>
|
|
<body text="#000000" bgcolor="#ffffff" link="#0000ff" vlink="#0000ff">
|
|
<h1><img height="86" alt="boost.png (6897 bytes)" src="../../boost.png"
|
|
width="277" align="middle" border="0" />pointer_cast</h1>
|
|
<p>The pointer cast functions (<code>boost::static_pointer_cast</code> <code>boost::dynamic_pointer_cast</code>
|
|
<code>boost::reinterpret_pointer_cast</code> <code>boost::const_pointer_cast</code>)
|
|
provide a way to write generic pointer castings for raw pointers, <code>std::shared_ptr</code> and <code>std::unique_ptr</code>. The functions
|
|
are defined in <cite><a href="../../boost/pointer_cast.hpp">boost/pointer_cast.hpp</a>.</cite></p>
|
|
<p>There is test/example code in <cite><a href="test/pointer_cast_test.cpp">pointer_cast_test.cpp</a></cite>.</p>
|
|
<h2><a name="rationale">Rationale</a></h2>
|
|
<P>Boost smart pointers usually overload those functions to provide a mechanism to
|
|
emulate pointers casts. For example, <code>boost::shared_ptr<...></code> implements
|
|
a static pointer cast this way:</P>
|
|
<pre>
|
|
template<class T, class U>
|
|
shared_ptr<T> static_pointer_cast(shared_ptr<U> const &r);
|
|
</pre>
|
|
<p>Pointer cast functions from <cite><A href="../../boost/pointer_cast.hpp">boost/pointer_cast.hpp</A></CITE>
|
|
are overloads of <code>boost::static_pointer_cast</code>, <code>boost::dynamic_pointer_cast</code>,
|
|
<code>boost::reinterpret_pointer_cast</code> and <code>boost::const_pointer_cast</code>
|
|
for raw pointers, <code>std::shared_ptr</code> and <code>std::unique_ptr</code>. This way when developing
|
|
pointer type independent classes, for example, memory managers or shared memory compatible classes, the same
|
|
code can be used for raw and smart pointers.</p>
|
|
<h2><a name="synopsis">Synopsis</a></h2>
|
|
<blockquote>
|
|
<pre>
|
|
namespace boost {
|
|
|
|
template<class T, class U>
|
|
inline T* static_pointer_cast(U *ptr)
|
|
{ return static_cast<T*>(ptr); }
|
|
|
|
template<class T, class U>
|
|
inline T* dynamic_pointer_cast(U *ptr)
|
|
{ return dynamic_cast<T*>(ptr); }
|
|
|
|
template<class T, class U>
|
|
inline T* const_pointer_cast(U *ptr)
|
|
{ return const_cast<T*>(ptr); }
|
|
|
|
template<class T, class U>
|
|
inline T* reinterpret_pointer_cast(U *ptr)
|
|
{ return reinterpret_cast<T*>(ptr); }
|
|
|
|
template<class T, class U>
|
|
inline std::shared_ptr<T> static_pointer_cast(std::shared_ptr<U> const& r);
|
|
|
|
template<class T, class U>
|
|
inline std::shared_ptr<T> dynamic_pointer_cast(std::shared_ptr<U> const& r);
|
|
|
|
template<class T, class U>
|
|
inline std::shared_ptr<T> const_pointer_cast(std::shared_ptr<U> const& r);
|
|
|
|
template<class T, class U>
|
|
inline std::shared_ptr<T> reinterpret_pointer_cast(std::shared_ptr<U> const& r);
|
|
|
|
template<class T, class U>
|
|
inline std::unique_ptr<T> static_pointer_cast(std::unique_ptr<U>&& r);
|
|
|
|
template<class T, class U>
|
|
inline std::unique_ptr<T> dynamic_pointer_cast(std::unique_ptr<U>&& r);
|
|
|
|
template<class T, class U>
|
|
inline std::unique_ptr<T> const_pointer_cast(std::unique_ptr<U>&& r);
|
|
|
|
template<class T, class U>
|
|
inline std::unique_ptr<T> reinterpret_pointer_cast(std::unique_ptr<U>&& r);
|
|
|
|
} // namespace boost
|
|
</pre>
|
|
</blockquote>
|
|
<p>As you can see from the above synopsis, the pointer cast functions for raw pointers are just
|
|
wrappers around standard C++ cast operators.</p>
|
|
|
|
<p>The pointer casts for <code>std::shared_ptr</code> are aliases of the corresponding standard
|
|
functions with the same names and equivalent to <a href="shared_ptr.htm#static_pointer_cast">the
|
|
functions taking <code>boost::shared_ptr</code></a>.</p>
|
|
|
|
<p>The pointer casts for <code>std::unique_ptr</code> are documented below.</p>
|
|
|
|
<h3 id="static_pointer_cast">static_pointer_cast</h3>
|
|
<pre>template<class T, class U>
|
|
unique_ptr<T> static_pointer_cast(unique_ptr<U>&& r); // never throws</pre>
|
|
<blockquote>
|
|
<p><b>Requires:</b> The expression <code>static_cast<T*>( (U*)0 )</code>
|
|
must be well-formed.</p>
|
|
<p><b>Returns:</b> <code>unique_ptr<T>( static_cast<typename unique_ptr<T>::element_type*>(r.release()) )</code>.</p>
|
|
<p><b>Throws:</b> nothing.</p>
|
|
<p><b>Notes:</b> the seemingly equivalent expression
|
|
<code>unique_ptr<T>(static_cast<T*>(r.get()))</code>
|
|
will eventually result in undefined behavior, attempting to delete the same
|
|
object twice.</p>
|
|
</blockquote>
|
|
<h3 id="const_pointer_cast">const_pointer_cast</h3>
|
|
<pre>template<class T, class U>
|
|
unique_ptr<T> const_pointer_cast(unique_ptr<U>&& r); // never throws</pre>
|
|
<blockquote>
|
|
<p><b>Requires:</b> The expression <code>const_cast<T*>( (U*)0 )</code>
|
|
must be well-formed.</p>
|
|
<p><b>Returns:</b> <code>unique_ptr<T>( const_cast<typename unique_ptr<T>::element_type*>(r.release()) )</code>.</p>
|
|
<p><b>Throws:</b> nothing.</p>
|
|
</blockquote>
|
|
<h3 id="dynamic_pointer_cast">dynamic_pointer_cast</h3>
|
|
<pre>template<class T, class U>
|
|
unique_ptr<T> dynamic_pointer_cast(unique_ptr<U>&& r);</pre>
|
|
<blockquote>
|
|
<p><b>Requires:</b> The expression <code>dynamic_cast<T*>( (U*)0 )</code>
|
|
must be well-formed. <code>T</code> must have a virtual destructor.</p>
|
|
<p><b>Returns:</b></p>
|
|
<ul>
|
|
<li>
|
|
When <code>dynamic_cast<typename unique_ptr<T>::element_type*>(r.get())</code> returns a nonzero value,
|
|
<code>unique_ptr<T>(dynamic_cast<typename unique_ptr<T>::element_type*>(r.release()))</code>;</li>
|
|
<li>
|
|
Otherwise, <code>unique_ptr<T>()</code>.</li></ul>
|
|
<p><b>Throws:</b> nothing.</p>
|
|
</blockquote>
|
|
<h3 id="reinterpret_pointer_cast">reinterpret_pointer_cast</h3>
|
|
<pre>template<class T, class U>
|
|
unique_ptr<T> reinterpret_pointer_cast(unique_ptr<U>&& r); // never throws</pre>
|
|
<blockquote>
|
|
<p><b>Requires:</b> The expression <code>reinterpret_cast<T*>( (U*)0 )</code>
|
|
must be well-formed.</p>
|
|
<p><b>Returns:</b> <code>unique_ptr<T>( reinterpret_cast<typename unique_ptr<T>::element_type*>(r.release()) )</code>.</p>
|
|
<p><b>Throws:</b> nothing.</p>
|
|
</blockquote>
|
|
|
|
<h2><a name="example">Example</a></h2>
|
|
<blockquote>
|
|
<pre>
|
|
#include <boost/pointer_cast.hpp>
|
|
#include <boost/shared_ptr.hpp>
|
|
|
|
class base
|
|
{
|
|
public:
|
|
|
|
virtual ~base()
|
|
{
|
|
}
|
|
};
|
|
|
|
class derived: public base
|
|
{
|
|
};
|
|
|
|
template <class BasePtr>
|
|
void check_if_it_is_derived(const BasePtr &ptr)
|
|
{
|
|
assert(boost::dynamic_pointer_cast<derived>(ptr) != 0);
|
|
}
|
|
|
|
int main()
|
|
{
|
|
<em>// Create a raw and a shared_ptr</em>
|
|
|
|
base *ptr = new derived;
|
|
boost::shared_ptr<base> sptr(new derived);
|
|
|
|
<em>// Check that base pointer points actually to derived class</em>
|
|
|
|
check_if_it_is_derived(ptr);
|
|
check_if_it_is_derived(sptr);
|
|
|
|
<em>// Ok!</em>
|
|
|
|
delete ptr;
|
|
return 0;
|
|
}</pre>
|
|
</blockquote>
|
|
<p>The example demonstrates how the generic pointer casts help us create pointer
|
|
independent code.</p>
|
|
<hr />
|
|
<p>Copyright 2005 Ion Gaztañaga. Use, modification, and distribution are subject to
|
|
the Boost Software License, Version 1.0. (See accompanying file <a href="../../LICENSE_1_0.txt">
|
|
LICENSE_1_0.txt</a> or a copy at <<a href="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</a>>.)</p>
|
|
</body>
|
|
</html>
|