CHeapPtrBase Class

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at CHeapPtrBase Class.

This class forms the basis for several smart heap pointer classes.

Important

This class and its members cannot be used in applications that execute in the Windows Runtime.

Syntax

template <class T, class Allocator = CCRTAllocator>  
class CHeapPtrBase

Parameters

T
The object type to be stored on the heap.

Allocator
The memory allocation class to use. By default CRT routines are used to allocate and free memory.

Members

Public Constructors

Name Description
CHeapPtrBase::~CHeapPtrBase The destructor.

Public Methods

Name Description
CHeapPtrBase::AllocateBytes Call this method to allocate memory.
CHeapPtrBase::Attach Call this method to take ownership of an existing pointer.
CHeapPtrBase::Detach Call this method to release ownership of a pointer.
CHeapPtrBase::Free Call this method to delete an object pointed to by a CHeapPtrBase.
CHeapPtrBase::ReallocateBytes Call this method to reallocate memory.

Public Operators

Name Description
CHeapPtrBase::operator T* The cast operator.
CHeapPtrBase::operator & The & operator.
CHeapPtrBase::operator -> The pointer-to-member operator.

Public Data Members

Name Description
CHeapPtrBase::m_pData The pointer data member variable.

Remarks

This class forms the basis for several smart heap pointer classes. The derived classes, for example, CHeapPtr and CComHeapPtr, add their own constructors and operators. See these classes for implementation examples.

Requirements

Header: atlcore.h

CHeapPtrBase::AllocateBytes

Call this method to allocate memory.

bool AllocateBytes(size_t nBytes) throw();

Parameters

nBytes
The number of bytes of memory to allocate.

Return Value

Returns true if the memory is successfully allocated, false otherwise.

Remarks

In debug builds, an assertion failure will occur if the CHeapPtrBase::m_pData member variable currently points to an existing value; that is, it is not equal to NULL.

CHeapPtrBase::Attach

Call this method to take ownership of an existing pointer.

void Attach(T* pData) throw();

Parameters

pData
The CHeapPtrBase object will take ownership of this pointer.

Remarks

When a CHeapPtrBase object takes ownership of a pointer, it will automatically delete the pointer and any allocated data when it goes out of scope.

In debug builds, an assertion failure will occur if the CHeapPtrBase::m_pData member variable currently points to an existing value; that is, it is not equal to NULL.

CHeapPtrBase::~CHeapPtrBase

The destructor.

~CHeapPtrBase() throw();

Remarks

Frees all allocated resources.

CHeapPtrBase::Detach

Call this method to release ownership of a pointer.

T* Detach() throw();

Return Value

Returns a copy of the pointer.

Remarks

Releases ownership of a pointer, sets the CHeapPtrBase::m_pData member variable to NULL, and returns a copy of the pointer.

CHeapPtrBase::Free

Call this method to delete an object pointed to by a CHeapPtrBase.

void Free() throw();

Remarks

The object pointed to by the CHeapPtrBase is freed, and the CHeapPtrBase::m_pData member variable is set to NULL.

CHeapPtrBase::m_pData

The pointer data member variable.

T* m_pData;

Remarks

This member variable holds the pointer information.

CHeapPtrBase::operator &

The & operator.

T** operator&() throw();

Return Value

Returns the address of the object pointed to by the CHeapPtrBase object.

CHeapPtrBase::operator ->

The pointer-to-member operator.

T* operator->() const throw();

Return Value

Returns the value of the CHeapPtrBase::m_pData member variable.

Remarks

Use this operator to call a method in a class pointed to by the CHeapPtrBase object. In debug builds, an assertion failure will occur if the CHeapPtrBase points to NULL.

CHeapPtrBase::operator T*

The cast operator.

operator T*() const throw();

Remarks

Returns CHeapPtrBase::m_pData.

CHeapPtrBase::ReallocateBytes

Call this method to reallocate memory.

bool ReallocateBytes(size_t nBytes) throw();

Parameters

nBytes
The new amount of memory to allocate, in bytes.

Return Value

Returns true if the memory is successfully allocated, false otherwise.

See Also

CHeapPtr Class
CComHeapPtr Class
Class Overview