OpenCV  3.0.0-rc1
Open Source Computer Vision
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Macros Groups Pages
Public Types | Public Member Functions | Friends | List of all members
cv::Ptr< T > Struct Template Reference

Template class for smart pointers with shared ownership. More...

#include "cvstd.hpp"

Public Types

typedef T element_type
 

Public Member Functions

 Ptr ()
 
template<typename Y >
 Ptr (Y *p)
 
template<typename Y , typename D >
 Ptr (Y *p, D d)
 
 Ptr (const Ptr &o)
 
template<typename Y >
 Ptr (const Ptr< Y > &o)
 
template<typename Y >
 Ptr (const Ptr< Y > &o, T *p)
 
 ~Ptr ()
 
template<typename Y >
Ptr< Y > constCast () const
 
template<typename Y >
Ptr< Y > dynamicCast () const
 
bool empty () const
 
T * get () const
 
 operator T * () const
 
detail::RefOrVoid< T >::type operator* () const
 
T * operator-> () const
 
Ptroperator= (const Ptr &o)
 
template<typename Y >
Ptroperator= (const Ptr< Y > &o)
 
void release ()
 
template<typename Y >
void reset (Y *p)
 
template<typename Y , typename D >
void reset (Y *p, D d)
 
template<typename Y >
Ptr< Y > staticCast () const
 
void swap (Ptr &o)
 

Friends

template<typename Y >
struct Ptr
 

Detailed Description

template<typename T>
struct cv::Ptr< T >

Template class for smart pointers with shared ownership.

A Ptr<T> pretends to be a pointer to an object of type T. Unlike an ordinary pointer, however, the object will be automatically cleaned up once all Ptr instances pointing to it are destroyed.

Ptr is similar to boost::shared_ptr that is part of the Boost library (http://www.boost.org/doc/libs/release/libs/smart_ptr/shared_ptr.htm) and std::shared_ptr from the C++11 standard.

This class provides the following advantages:

A Ptr is said to own a pointer - that is, for each Ptr there is a pointer that will be deleted once all Ptr instances that own it are destroyed. The owned pointer may be null, in which case nothing is deleted. Each Ptr also stores a pointer. The stored pointer is the pointer the Ptr pretends to be; that is, the one you get when you use Ptr::get or the conversion to T*. It's usually the same as the owned pointer, but if you use casts or the general shared-ownership constructor, the two may diverge: the Ptr will still own the original pointer, but will itself point to something else.

The owned pointer is treated as a black box. The only thing Ptr needs to know about it is how to delete it. This knowledge is encapsulated in the deleter - an auxiliary object that is associated with the owned pointer and shared between all Ptr instances that own it. The default deleter is an instance of DefaultDeleter, which uses the standard C++ delete operator; as such it will work with any pointer allocated with the standard new operator.

However, if the pointer must be deleted in a different way, you must specify a custom deleter upon Ptr construction. A deleter is simply a callable object that accepts the pointer as its sole argument. For example, if you want to wrap FILE, you may do so as follows:

Ptr<FILE> f(fopen("myfile.txt", "w"), fclose);
if(!f) throw ...;
fprintf(f, ....);
...
// the file will be closed automatically by f's destructor.

Alternatively, if you want all pointers of a particular type to be deleted the same way, you can specialize DefaultDeleter<T>::operator() for that type, like this:

namespace cv {
template<> void DefaultDeleter<FILE>::operator ()(FILE * obj) const
{
fclose(obj);
}
}

For convenience, the following types from the OpenCV C API already have such a specialization that calls the appropriate release function:

Examples:
houghlines.cpp, lsd_lines.cpp, and segment_objects.cpp.

Member Typedef Documentation

template<typename T>
typedef T cv::Ptr< T >::element_type

Generic programming support.

Constructor & Destructor Documentation

template<typename T>
cv::Ptr< T >::Ptr ( )

The default constructor creates a null Ptr - one that owns and stores a null pointer.

template<typename T>
template<typename Y >
cv::Ptr< T >::Ptr ( Y *  p)

If p is null, these are equivalent to the default constructor. Otherwise, these constructors assume ownership of p - that is, the created Ptr owns and stores p and assumes it is the sole owner of it. Don't use them if p is already owned by another Ptr, or else p will get deleted twice. With the first constructor, DefaultDeleter<Y>() becomes the associated deleter (so p will eventually be deleted with the standard delete operator). Y must be a complete type at the point of invocation. With the second constructor, d becomes the associated deleter. Y* must be convertible to T*.

Parameters
pPointer to own.
Note
It is often easier to use makePtr instead.
template<typename T>
template<typename Y , typename D >
cv::Ptr< T >::Ptr ( Y *  p,
d 
)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
dDeleter to use for the owned pointer.
pPointer to own.
template<typename T>
cv::Ptr< T >::Ptr ( const Ptr< T > &  o)

These constructors create a Ptr that shares ownership with another Ptr - that is, own the same pointer as o. With the first two, the same pointer is stored, as well; for the second, Y* must be convertible to T*. With the third, p is stored, and Y may be any type. This constructor allows to have completely unrelated owned and stored pointers, and should be used with care to avoid confusion. A relatively benign use is to create a non-owning Ptr, like this:

ptr = Ptr<T>(Ptr<T>(), dont_delete_me); // owns nothing; will not delete the pointer.
Parameters
oPtr to share ownership with.
template<typename T>
template<typename Y >
cv::Ptr< T >::Ptr ( const Ptr< Y > &  o)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
oPtr to share ownership with.
template<typename T>
template<typename Y >
cv::Ptr< T >::Ptr ( const Ptr< Y > &  o,
T *  p 
)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
oPtr to share ownership with.
pPointer to store.
template<typename T>
cv::Ptr< T >::~Ptr ( )

The destructor is equivalent to calling Ptr::release.

Member Function Documentation

template<typename T>
template<typename Y >
Ptr<Y> cv::Ptr< T >::constCast ( ) const

Ditto for const_cast.

template<typename T>
template<typename Y >
Ptr<Y> cv::Ptr< T >::dynamicCast ( ) const

Ditto for dynamic_cast.

template<typename T>
bool cv::Ptr< T >::empty ( ) const

ptr.empty() is equivalent to !ptr.get().

template<typename T>
T* cv::Ptr< T >::get ( ) const

Returns the stored pointer.

template<typename T>
cv::Ptr< T >::operator T * ( ) const

Equivalent to get().

template<typename T>
detail::RefOrVoid<T>::type cv::Ptr< T >::operator* ( ) const

Ordinary pointer emulation.

template<typename T>
T* cv::Ptr< T >::operator-> ( ) const

Ordinary pointer emulation.

template<typename T>
Ptr& cv::Ptr< T >::operator= ( const Ptr< T > &  o)

Assignment replaces the current Ptr instance with one that owns and stores same pointers as o and then destroys the old instance.

Parameters
oPtr to share ownership with.
template<typename T>
template<typename Y >
Ptr& cv::Ptr< T >::operator= ( const Ptr< Y > &  o)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<typename T>
void cv::Ptr< T >::release ( )

If no other Ptr instance owns the owned pointer, deletes it with the associated deleter. Then sets both the owned and the stored pointers to NULL.

template<typename T>
template<typename Y >
void cv::Ptr< T >::reset ( Y *  p)

ptr.reset(...) is equivalent to ptr = Ptr<T>(...).

Parameters
pPointer to own.
template<typename T>
template<typename Y , typename D >
void cv::Ptr< T >::reset ( Y *  p,
d 
)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters
dDeleter to use for the owned pointer.
pPointer to own.
template<typename T>
template<typename Y >
Ptr<Y> cv::Ptr< T >::staticCast ( ) const

Returns a Ptr that owns the same pointer as this, and stores the same pointer as this, except converted via static_cast to Y*.

template<typename T>
void cv::Ptr< T >::swap ( Ptr< T > &  o)

Swaps the owned and stored pointers (and deleters, if any) of this and o.

Parameters
oPtr to swap with.

Friends And Related Function Documentation

template<typename T>
template<typename Y >
friend struct Ptr
friend

The documentation for this struct was generated from the following file: