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

#include <AutoPointer.h>

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

Public Types
using	const_pointer = const T *

using	deleter = D

using	pointer = T *

using	value_type = T

Public Member Functions
	AutoPointer (AutoPointer &&x)

	AutoPointer (AutoPointer &x)

	AutoPointer (bool autoDelete=true, const deleter &d=deleter())

	AutoPointer (pointer p, bool autoDelete=true, const deleter &d=deleter())

virtual	~AutoPointer ()

deleter &	Deleter ()

const deleter &	Deleter () const

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 ()

value_type &	operator* ()

const value_type &	operator* () const

pointer	operator-> ()

const_pointer	operator-> () const

AutoPointer &	operator= (AutoPointer &&x)

AutoPointer &	operator= (AutoPointer &x)

AutoPointer &	operator= (pointer p)

pointer	Pointer ()

const_pointer	Pointer () const

pointer	Ptr ()

const_pointer	Ptr () const

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 245 of file AutoPointer.h.

Member Typedef Documentation

◆ const_pointer

template<class T , class D = StandardDeleter<T>>

using pcl::AutoPointer< T, D >::const_pointer = const T*

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

Definition at line 262 of file AutoPointer.h.

◆ deleter

template<class T , class D = StandardDeleter<T>>

using pcl::AutoPointer< T, D >::deleter = D

Represents the type of the object responsible for object deletion.

Definition at line 267 of file AutoPointer.h.

◆ pointer

template<class T , class D = StandardDeleter<T>>

using pcl::AutoPointer< T, D >::pointer = T*

Represents a pointer stored in this smart pointer.

Definition at line 257 of file AutoPointer.h.

◆ value_type

template<class T , class D = StandardDeleter<T>>

using pcl::AutoPointer< T, D >::value_type = T

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

Definition at line 252 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

autoDelete	Initial state of the automatic deletion feature. The default value is true, so auto deletion is always enabled by default for newly created AutoPointer objects.
d	Deleter 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 D template argument class.

Definition at line 287 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

p	The pointer to store in this AutoPointer instance.
autoDelete	Initial state of the automatic deletion feature. The default value is true, so auto deletion is always enabled by default for newly created AutoPointer objects.
d	Deleter 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 D template argument class.

Definition at line 310 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 transport 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 331 of file AutoPointer.h.

References pcl::AutoPointer< T, D >::Release().

◆ 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 341 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 355 of file AutoPointer.h.

Member Function Documentation

◆ Deleter() [1/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 526 of file AutoPointer.h.

◆ Deleter() [2/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 518 of file AutoPointer.h.

◆ Destroy()

template<class T , class D = StandardDeleter<T>>

void pcl::AutoPointer< T, D >::Destroy ( )

inline

A synonym for Reset(). Useful to enforce semantics when the smart pointer owns the pointed object.

Definition at line 401 of file AutoPointer.h.

Referenced by pcl::ATrousWaveletTransform::WaveletScalingFunction::Clear(), pcl::ATrousWaveletTransform::WaveletScalingFunction::operator=(), and pcl::ATrousWaveletTransform::WaveletScalingFunction::Set().

◆ 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 510 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 499 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 488 of file AutoPointer.h.

◆ IsNull()

template<class T , class D = StandardDeleter<T>>

bool pcl::AutoPointer< T, D >::IsNull ( ) const

inline

Returns true iff this smart pointer object stores a null pointer.

Definition at line 458 of file AutoPointer.h.

Referenced by pcl::ATrousWaveletTransform::WaveletScalingFunction::WaveletScalingFunction(), pcl::ATrousWaveletTransform::WaveletScalingFunction::IsNonseparable(), pcl::ATrousWaveletTransform::WaveletScalingFunction::IsSeparable(), pcl::ATrousWaveletTransform::WaveletScalingFunction::operator=(), pcl::ATrousWaveletTransform::WaveletScalingFunction::operator==(), and pcl::ATrousWaveletTransform::WaveletScalingFunction::Set().

◆ 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 467 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 658 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 599 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 609 of file AutoPointer.h.

◆ operator*() [1/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 648 of file AutoPointer.h.

◆ operator*() [2/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 638 of file AutoPointer.h.

◆ operator->() [1/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 628 of file AutoPointer.h.

◆ operator->() [2/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 618 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

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

Definition at line 563 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

Non-trivial 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 551 of file AutoPointer.h.

References pcl::AutoPointer< T, D >::Release().

◆ 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:

SetPointer( p );

pcl::AutoPointer::SetPointer

void SetPointer(pointer p)

Definition: AutoPointer.h:367

Definition at line 588 of file AutoPointer.h.

◆ Pointer() [1/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 434 of file AutoPointer.h.

◆ Pointer() [2/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 426 of file AutoPointer.h.

◆ Ptr() [1/2]

template<class T , class D = StandardDeleter<T>>

pointer pcl::AutoPointer< T, D >::Ptr ( )

inline

A synonym for Pointer().

Definition at line 450 of file AutoPointer.h.

◆ Ptr() [2/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 442 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 (or more specifically, the responsibility for destroying it) is transferred to the caller.

Definition at line 415 of file AutoPointer.h.

Referenced by pcl::AutoPointer< T, D >::AutoPointer(), and pcl::AutoPointer< T, D >::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 387 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 367 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 666 of file AutoPointer.h.

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

AutoPointer.h

Public Types

Public Member Functions

Friends

Detailed Description

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

Member Typedef Documentation

◆ const_pointer

◆ deleter

◆ pointer

◆ value_type

Constructor & Destructor Documentation

◆ AutoPointer() [1/4]

◆ AutoPointer() [2/4]

◆ AutoPointer() [3/4]

◆ AutoPointer() [4/4]

◆ ~AutoPointer()

Member Function Documentation

◆ Deleter() [1/2]

◆ Deleter() [2/2]

◆ Destroy()

◆ DisableAutoDelete()

◆ EnableAutoDelete()

◆ IsAutoDelete()

◆ IsNull()

◆ IsValid()

◆ operator bool()

◆ operator const_pointer()

◆ operator pointer()

◆ operator*() [1/2]

◆ operator*() [2/2]

◆ operator->() [1/2]

◆ operator->() [2/2]

◆ operator=() [1/3]

◆ operator=() [2/3]

◆ operator=() [3/3]

◆ Pointer() [1/2]

◆ Pointer() [2/2]

◆ Ptr() [1/2]

◆ Ptr() [2/2]

◆ Release()

◆ Reset()

◆ SetPointer()

Friends And Related Function Documentation

◆ Swap

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