CHeapPtr 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 CHeapPtr Class.
A smart pointer class for managing heap pointers.
Important
This class and its members cannot be used in applications that execute in the Windows Runtime.
Syntax
template<typename T, class Allocator=CCRTAllocator>
class CHeapPtr : public CHeapPtrBase<T, Allocator>
Parameters
T
The object type to be stored on the heap.
Allocator
The memory allocation class to use.
Members
Public Constructors
| Name | Description |
|---|---|
| CHeapPtr::CHeapPtr | The constructor. |
Public Methods
| Name | Description |
|---|---|
| CHeapPtr::Allocate | Call this method to allocate memory on the heap to store objects. |
| CHeapPtr::Reallocate | Call this method to reallocate the memory on the heap. |
Public Operators
| Name | Description |
|---|---|
| CHeapPtr::operator = | The assignment operator. |
Remarks
CHeapPtr is derived from CHeapPtrBase and by default uses the CRT routines (in CCRTAllocator) to allocate and free memory. The class CHeapPtrList may be used to construct a list of heap pointers. See also CComHeapPtr, which uses COM memory allocation routines.
Inheritance Hierarchy
CHeapPtr
Requirements
Header: atlcore.h
CHeapPtr::Allocate
Call this method to allocate memory on the heap to store objects.
bool Allocate(size_t nElements = 1) throw();
Parameters
nElements
The number of elements used to calculate the amount of memory to allocate. The default value is 1.
Return Value
Returns true if the memory was successfully allocated, false on failure.
Remarks
The allocator routines are used to reserve enough memory on the heap to store nElement objects of a type defined in the constructor.
Example
// Create a new CHeapPtr object
CHeapPtr <int> myHP;
// Allocate space for 10 integers on the heap
myHP.Allocate(10);
CHeapPtr::CHeapPtr
The constructor.
CHeapPtr() throw();
explicit CHeapPtr(T* p) throw();
CHeapPtr(CHeapPtr<T, Allocator>& p) throw();
Parameters
p
An existing heap pointer or CHeapPtr.
Remarks
The heap pointer can optionally be created using an existing pointer, or a CHeapPtr object. If so, the new CHeapPtr object assumes responsibility for managing the new pointer and resources.
Example
// Create a new CHeapPtr object
CHeapPtr <int> myHP;
// Create a new CHeapPtr from the first
CHeapPtr <int> myHP2(myHP);
CHeapPtr::operator =
Assignment operator.
CHeapPtr<T, Allocator>& operator=(
CHeapPtr<T, Allocator>& p) throw();
Parameters
p
An existing CHeapPtr object.
Return Value
Returns a reference to the updated CHeapPtr.
Example
// Create a new CHeapPtr object
CHeapPtr <int> myHP;
// Allocate space for 10 integers on the heap
myHP.Allocate(10);
// Create a second heap pointer
// and assign it to the first pointer.
CHeapPtr <int> myHP2;
myHP2 = myHP;
CHeapPtr::Reallocate
Call this method to reallocate the memory on the heap.
bool Reallocate(size_t nElements) throw();
Parameters
nElements
The new number of elements used to calculate the amount of memory to allocate.
Return Value
Returns true if the memory was successfully allocated, false on failure.
Example
// Create a new CHeapPtr object
CHeapPtr <int> myHP;
// Allocate space for 10 integers on the heap
myHP.Allocate(10);
// Resize the allocated memory for 20 integers
myHP.Reallocate(20);