CHeapPtrBase Class

 

For the latest documentation on Visual Studio 2017, see Visual Studio 2017 Documentation.

For the latest documentation on Visual Studio 2017, see CHeapPtrBase Class on docs.microsoft.com. This class forms the basis for several smart heap pointer classes.

System_CAPS_ICON_important.jpg Important

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

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.

Public Constructors

NameDescription
CHeapPtrBase::~CHeapPtrBaseThe destructor.

Public Methods

NameDescription
CHeapPtrBase::AllocateBytesCall this method to allocate memory.
CHeapPtrBase::AttachCall this method to take ownership of an existing pointer.
CHeapPtrBase::DetachCall this method to release ownership of a pointer.
CHeapPtrBase::FreeCall this method to delete an object pointed to by a CHeapPtrBase.
CHeapPtrBase::ReallocateBytesCall this method to reallocate memory.

Public Operators

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

Public Data Members

NameDescription
CHeapPtrBase::m_pDataThe pointer data member variable.

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.

Header: atlcore.h

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.

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.

The destructor.

~CHeapPtrBase() throw();

Remarks

Frees all allocated resources.

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.

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.

The pointer data member variable.

T* m_pData;

Remarks

This member variable holds the pointer information.

The & operator.

T** operator&() throw();

Return Value

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

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.

The cast operator.

operator T*() const throw();

Remarks

Returns CHeapPtrBase::m_pData.

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.

CHeapPtr Class
CComHeapPtr Class
Class Overview

Show: