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.