Share via


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

CHeapPtrBase

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

See Also

CHeapPtrBase Class
CCRTAllocator Class
Class Overview