PCL
pcl::AutoPointer< T, D > Class Template Reference

A smart pointer with sole object ownership and optional automatic object destruction. More...

#include <AutoPointer.h>

+ Inheritance diagram for pcl::AutoPointer< T, D >:

Public Types

typedef const T * const_pointer
 
typedef D deleter
 
typedef T * pointer
 
typedef T value_type
 

Public Member Functions

 AutoPointer (bool autoDelete=true, const deleter &d=deleter())
 
 AutoPointer (pointer p, bool autoDelete=true, const deleter &d=deleter())
 
 AutoPointer (AutoPointer &x)
 
 AutoPointer (AutoPointer &&x)
 
virtual ~AutoPointer ()
 
const deleterDeleter () const
 
deleterDeleter ()
 
void Destroy ()
 
void DisableAutoDelete (bool disable=true)
 
void EnableAutoDelete (bool enable=true)
 
bool IsAutoDelete () const
 
bool IsNull () const
 
bool IsValid () const
 
 operator bool () const
 
 operator const_pointer () const
 
 operator pointer ()
 
const value_typeoperator* () const
 
value_typeoperator* ()
 
const_pointer operator-> () const
 
pointer operator-> ()
 
AutoPointeroperator= (AutoPointer &x)
 
AutoPointeroperator= (AutoPointer &&x)
 
AutoPointeroperator= (pointer p)
 
const_pointer Pointer () const
 
pointer Pointer ()
 
const_pointer Ptr () const
 
pointer Ptr ()
 
pointer Release ()
 
void Reset ()
 
void SetPointer (pointer p)
 

Friends

void Swap (AutoPointer &x1, AutoPointer &x2)
 

Detailed Description

template<class T, class D = StandardDeleter<T>>
class pcl::AutoPointer< T, D >

AutoPointer stores a pointer to an object of which it is the sole owner. The owned object can optionally be destroyed when the owner AutoPointer instance is destroyed.

The template argument T represents the type of the objects owned by this template instantiation. The template argument D represents a functor class responsible for deletion of objects of type T. By default, AutoPointer uses the StandardDeleter template class, which is a simple wrapper for the standard delete operator.

Smart pointers are useful entities to guarantee proper destruction and deallocation of data in a variety of scenarios, such as exception driven code where the same objects have to be destroyed at different points in the execution workflow. For example, consider the following pseudocode:

struct Foo { ... };
void Bar()
{
Foo* one = nullptr, * two = nullptr;
try
{
// ... some code that may create new Foo objects ...
if ( condition1 ) one = new Foo;
if ( condition2 ) two = new Foo;
// ... some code that can throw exceptions ...
if ( one != nullptr ) delete one;
if ( two != nullptr ) delete two;
}
catch ( ... )
{
if ( one != nullptr ) delete one;
if ( two != nullptr ) delete two;
throw;
}
}

Note that the objects pointed to by the one and two variables have to be destroyed at two locations: at the bottom of the try block (normal execution), and when an exception is caught, within the catch block. If the Bar() routine were more complex, even more deallocations might be necessary at different locations, making the code intricate and prone to memory leaks.

All of these complexities and potential problems can be avoided easily with smart pointers. For example, the following snippet would be equivalent to the pseudocode above:

struct Foo { ... };
void Bar()
{
AutoPointer<Foo> one, two;
// ... some code that may create new Foo objects ...
if ( condition1 ) one = new Foo;
if ( condition2 ) two = new Foo;
// ... some code that can throw exceptions ...
}

With smart pointers, there's no need to explicitly destroy the dynamically allocated objects one and two: The AutoPointer objects will destroy and deallocate them automatically when they get out of scope. On the other hand, the AutoPointer instances behave just like normal pointers allowing indirections, pointer assignments, and structure member selections for their owned objects transparently. The resulting code is simpler and more robust.

By default, when an AutoPointer instance is destroyed it also destroys the object pointed to by its contained pointer (if the AutoPointer stores a non-null pointer). This automatic deletion feature can be disabled in some situations where a single AutoPointer can store either a pointer to a dynamically allocated object, or a pointer to an already existing object that must be preserved (e.g., an object living in the stack). For example:

void Foo( Image& image )
{
//
// Extract the CIE L* component of a color image ...
// ... or use the same image as the working lightness if it is grayscale.
//
AutoPointer<Image> lightness;
if ( image.IsColor() )
{
lightness = new Image;
image.ExtractLightness( *lightness );
}
else
{
lightness = &image;
lightness.DisableAutoDelete();
}
DoSomeStuffWithTheLightnessComponent( *lightness );
//
// Insert the modified CIE L* component back in the color image.
//
if ( image.IsColor() )
image.SetLightness( *lightness );
}

In the above code, the lightness variable can either store a newed image, if the passed image is a color image, or a pointer to image if it is a grayscale image. In the latter case we have disabled the automatic deletion feature for the lightness AutoPointer, so it won't delete its stored pointer when it gets out of scope.

See also
StandardDeleter, AutoPointerCloner

Definition at line 241 of file AutoPointer.h.

Member Typedef Documentation

◆ const_pointer

template<class T, class D = StandardDeleter<T>>
typedef const T* pcl::AutoPointer< T, D >::const_pointer

Represents a pointer to an immutable object stored in this smart pointer.

Definition at line 258 of file AutoPointer.h.

◆ deleter

template<class T, class D = StandardDeleter<T>>
typedef D pcl::AutoPointer< T, D >::deleter

Represents the type of the object responsible for object deletion.

Definition at line 263 of file AutoPointer.h.

◆ pointer

template<class T, class D = StandardDeleter<T>>
typedef T* pcl::AutoPointer< T, D >::pointer

Represents a pointer stored in this smart pointer.

Definition at line 253 of file AutoPointer.h.

◆ value_type

template<class T, class D = StandardDeleter<T>>
typedef T pcl::AutoPointer< T, D >::value_type

Represents the type of the object pointed to by this smart pointer.

Definition at line 248 of file AutoPointer.h.

Constructor & Destructor Documentation

◆ AutoPointer() [1/4]

template<class T, class D = StandardDeleter<T>>
pcl::AutoPointer< T, D >::AutoPointer ( bool  autoDelete = true,
const deleter d = deleter() 
)
inline

Constructs a null smart pointer.

Parameters
autoDeleteInitial state of the automatic deletion feature. The default value is true, so auto deletion is always enabled by default for newly created AutoPointer objects.
dDeleter object, responsible for object destruction when the automatic deletion feature is enabled.

A null smart pointer stores a null pointer, so it does not point to a valid object.

A copy of the specified deleter d will be used. If no deleter is specified, this object will use a default-constructed instance of the deleter template argument class.

Definition at line 283 of file AutoPointer.h.

◆ AutoPointer() [2/4]

template<class T, class D = StandardDeleter<T>>
pcl::AutoPointer< T, D >::AutoPointer ( pointer  p,
bool  autoDelete = true,
const deleter d = deleter() 
)
inline

Constructs a smart pointer to store a given pointer.

Parameters
pThe pointer to store in this AutoPointer instance.
autoDeleteInitial state of the automatic deletion feature. The default value is true, so auto deletion is always enabled by default for newly created AutoPointer objects.
dDeleter object, responsible for object destruction when the automatic deletion feature is enabled.

A copy of the specified deleter d will be used. If no deleter is specified, this object will use a default-constructed instance of the deleter template argument class.

Definition at line 306 of file AutoPointer.h.

◆ AutoPointer() [3/4]

template<class T, class D = StandardDeleter<T>>
pcl::AutoPointer< T, D >::AutoPointer ( AutoPointer< T, D > &  x)
inline

Non-trivial copy constructor. Constructs a smart pointer by transferring the pointer stored in another smart pointer x.

The automatic deletion feature for this object will be in the same state as it is currently set for the source object x.

The smart pointer x will be a null pointer after this instance is constructed. This happens irrespective of the state of the automatic deletion feature. This guarantees that, as long as no two AutoPointer instances have been explicitly constructed to store the same pointer, no two AutoPointer instances can share the same pointer accidentally, and hence multiple deletions are not possible.

Definition at line 327 of file AutoPointer.h.

◆ AutoPointer() [4/4]

template<class T, class D = StandardDeleter<T>>
pcl::AutoPointer< T, D >::AutoPointer ( AutoPointer< T, D > &&  x)
inline

Move constructor.

Definition at line 337 of file AutoPointer.h.

◆ ~AutoPointer()

template<class T, class D = StandardDeleter<T>>
virtual pcl::AutoPointer< T, D >::~AutoPointer ( )
inlinevirtual

Destroys an AutoPointer object.

If this instance stores a non-null pointer, and the automatic deletion feature is enabled, the pointed object will be destroyed by calling the deleter object.

Definition at line 351 of file AutoPointer.h.

Member Function Documentation

◆ Deleter() [1/2]

template<class T, class D = StandardDeleter<T>>
const deleter& pcl::AutoPointer< T, D >::Deleter ( ) const
inline

Returns a reference to the immutable deleter object in this instance.

Definition at line 514 of file AutoPointer.h.

◆ Deleter() [2/2]

template<class T, class D = StandardDeleter<T>>
deleter& pcl::AutoPointer< T, D >::Deleter ( )
inline

Returns a reference to the deleter object in this instance.

Definition at line 522 of file AutoPointer.h.

◆ Destroy()

template<class T, class D = StandardDeleter<T>>
void pcl::AutoPointer< T, D >::Destroy ( )
inline

◆ DisableAutoDelete()

template<class T, class D = StandardDeleter<T>>
void pcl::AutoPointer< T, D >::DisableAutoDelete ( bool  disable = true)
inline

Disables (or enables) the automatic deletion feature of AutoPointer for this object.

See also
IsAutoDelete(), EnableAutoDelete()

Definition at line 506 of file AutoPointer.h.

◆ EnableAutoDelete()

template<class T, class D = StandardDeleter<T>>
void pcl::AutoPointer< T, D >::EnableAutoDelete ( bool  enable = true)
inline

Enables (or disables) the automatic deletion feature of AutoPointer for this object.

See also
IsAutoDelete(), DisableAutoDelete()

Definition at line 495 of file AutoPointer.h.

◆ IsAutoDelete()

template<class T, class D = StandardDeleter<T>>
bool pcl::AutoPointer< T, D >::IsAutoDelete ( ) const
inline

Returns true iff the automatic deletion feature of AutoPointer is currently enabled for this object.

When automatic deletion is enabled, the object pointed to by this instance will be destroyed (by calling the deleter object) when this instance is destroyed, or when it is assigned with a different pointer.

When automatic deletion is disabled, the pointed object will not be destroyed automatically.

See the detailed description for the AutoPointer class for more information, including code examples.

See also
EnableAutoDelete(), DisableAutoDelete()

Definition at line 484 of file AutoPointer.h.

◆ IsNull()

◆ IsValid()

template<class T, class D = StandardDeleter<T>>
bool pcl::AutoPointer< T, D >::IsValid ( ) const
inline

Returns true iff this smart pointer object stores a non-null pointer. Equivalent to !IsNull().

Definition at line 463 of file AutoPointer.h.

◆ operator bool()

template<class T, class D = StandardDeleter<T>>
pcl::AutoPointer< T, D >::operator bool ( ) const
inline

Returns true iff this smart pointer stores a non-null pointer. This operator is equivalent to !IsNull().

Definition at line 654 of file AutoPointer.h.

◆ operator const_pointer()

template<class T, class D = StandardDeleter<T>>
pcl::AutoPointer< T, D >::operator const_pointer ( ) const
inline

Returns a pointer to the immutable object pointed to by this instance.

This operator is a synonym for the Pointer() const member function.

Definition at line 595 of file AutoPointer.h.

◆ operator pointer()

template<class T, class D = StandardDeleter<T>>
pcl::AutoPointer< T, D >::operator pointer ( )
inline

Returns a copy of the pointer stored in this AutoPointer instance.

This operator is a synonym for the Pointer() member function.

Definition at line 605 of file AutoPointer.h.

◆ operator*() [1/2]

template<class T, class D = StandardDeleter<T>>
const value_type& pcl::AutoPointer< T, D >::operator* ( ) const
inline

Dereference operator. Returns a reference to the immutable object pointed to by this smart pointer.

Definition at line 634 of file AutoPointer.h.

◆ operator*() [2/2]

template<class T, class D = StandardDeleter<T>>
value_type& pcl::AutoPointer< T, D >::operator* ( )
inline

Dereference operator. Returns a reference to the object pointed to by this smart pointer.

Definition at line 644 of file AutoPointer.h.

◆ operator->() [1/2]

template<class T, class D = StandardDeleter<T>>
const_pointer pcl::AutoPointer< T, D >::operator-> ( ) const
inline

Structure member selection operator. Returns a pointer to the immutable object pointed to by this AutoPointer instance.

Definition at line 614 of file AutoPointer.h.

◆ operator->() [2/2]

template<class T, class D = StandardDeleter<T>>
pointer pcl::AutoPointer< T, D >::operator-> ( )
inline

Structure member selection operator. Returns a copy of the pointer stored in this AutoPointer instance.

Definition at line 624 of file AutoPointer.h.

◆ operator=() [1/3]

template<class T, class D = StandardDeleter<T>>
AutoPointer& pcl::AutoPointer< T, D >::operator= ( AutoPointer< T, D > &  x)
inline

Copy assignment operator. Transfers the pointer stored in another smart pointer to this object.

This assignment operator performs the following actions:

(1) If this smart pointer stores a valid (non-null) pointer, and the automatic deletion feature is enabled, the pointed object is destroyed by the deleter object.

(2) The pointer stored in the other smart pointer x is copied to this instance.

(3) The other smart pointer x is forced to store a null pointer.

(4) Returns a reference to this object.

This operator function does nothing if the specified AutoPointer x stores the same pointer as this object. This prevents multiple deletions.

Definition at line 547 of file AutoPointer.h.

◆ operator=() [2/3]

template<class T, class D = StandardDeleter<T>>
AutoPointer& pcl::AutoPointer< T, D >::operator= ( AutoPointer< T, D > &&  x)
inline

Move assignment operator. For the AutoPointer class, this member function performs the same actions as the copy assignment operator.

Definition at line 559 of file AutoPointer.h.

◆ operator=() [3/3]

template<class T, class D = StandardDeleter<T>>
AutoPointer& pcl::AutoPointer< T, D >::operator= ( pointer  p)
inline

Causes this smart pointer to store the specified pointer p. Returns a reference to this object.

If this instance stores a non-null pointer when this function is called, and the automatic deletion feature is enabled, the pointed object is destroyed by the deleter object.

If this object already stores the specified pointer p, this function does nothing.

This member function is equivalent to:

Definition at line 584 of file AutoPointer.h.

◆ Pointer() [1/2]

template<class T, class D = StandardDeleter<T>>
const_pointer pcl::AutoPointer< T, D >::Pointer ( ) const
inline

Returns a pointer to the immutable object pointed to by this AutoPointer instance.

Definition at line 422 of file AutoPointer.h.

◆ Pointer() [2/2]

template<class T, class D = StandardDeleter<T>>
pointer pcl::AutoPointer< T, D >::Pointer ( )
inline

Returns a copy of the pointer stored in this AutoPointer instance.

Definition at line 430 of file AutoPointer.h.

◆ Ptr() [1/2]

template<class T, class D = StandardDeleter<T>>
const_pointer pcl::AutoPointer< T, D >::Ptr ( ) const
inline

A synonym for Pointer() const.

Definition at line 438 of file AutoPointer.h.

◆ Ptr() [2/2]

template<class T, class D = StandardDeleter<T>>
pointer pcl::AutoPointer< T, D >::Ptr ( )
inline

A synonym for Pointer().

Definition at line 446 of file AutoPointer.h.

◆ Release()

template<class T, class D = StandardDeleter<T>>
pointer pcl::AutoPointer< T, D >::Release ( )
inline

Returns the pointer stored in this AutoPointer, and causes this object to forget it by storing a null pointer.

The object pointed is never destroyed by this function, irrespective of the state of automatic deletion. In this way, ownership of the pointed object (that is, the responsibility for destroying it) is transferred to the caller.

Definition at line 411 of file AutoPointer.h.

Referenced by pcl::AutoPointer< OpenFileDialogPrivate >::AutoPointer(), and pcl::AutoPointer< OpenFileDialogPrivate >::operator=().

◆ Reset()

template<class T, class D = StandardDeleter<T>>
void pcl::AutoPointer< T, D >::Reset ( )
inline

Causes this smart pointer to store a null pointer.

If this instance stores a non-null pointer when this function is called, and the automatic deletion feature is enabled, the pointed object is destroyed by calling the deleter object.

This member function is functionally equivalent to SetPointer( nullptr ).

Definition at line 383 of file AutoPointer.h.

◆ SetPointer()

template<class T, class D = StandardDeleter<T>>
void pcl::AutoPointer< T, D >::SetPointer ( pointer  p)
inline

Causes this smart pointer to store the specified pointer p.

If this instance stores a non-null pointer when this function is called, and the automatic deletion feature is enabled, the pointed object is destroyed by calling the deleter object.

Definition at line 363 of file AutoPointer.h.

Friends And Related Function Documentation

◆ Swap

template<class T, class D = StandardDeleter<T>>
void Swap ( AutoPointer< T, D > &  x1,
AutoPointer< T, D > &  x2 
)
friend

Exchanges two smart pointers x1 and x2.

Definition at line 662 of file AutoPointer.h.


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