IAtlStringMgr 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 IAtlStringMgr Class.

This class represents the interface to a CStringT memory manager.

__interface IAtlStringMgr

Methods

AllocateCall this method to allocate a new string data structure.
CloneCall this method to return a pointer to a new string manager for use with another instance of CSimpleStringT.
FreeCall this method to free a string data structure.
GetNilStringReturns a pointer to the CStringData object used by empty string objects.
ReallocateCall this method to reallocate a string data structure.

This interface manages the memory used by the MFC-independent string classes; such as CSimpleStringT, CStringT, and CFixedStringT.

You can also use this class to implement a custom memory manager for your custom string class. For more information, see Memory Management and CStringT.

Header: atlsimpstr.h

Allocates a new string data structure.

CStringData* Allocate(int nAllocLength,int nCharSize) throw();

Parameters

nAllocLength
The number of characters in the new memory block.

nCharSize
The size (in bytes) of the character type used by the string manager.

Return Value

Returns a pointer to the newly allocated memory block.

System_CAPS_ICON_note.jpg Note

Do not signal a failed allocation by throwing an exception. Instead, a failed allocation should be signaled by returning NULL.

Remarks

Call IAtlStringMgr::Free or IAtlStringMgr::ReAllocate to free the memory allocated by this method.

System_CAPS_ICON_note.jpg Note

For usage examples, see Memory Management and CStringT.

Returns a pointer to a new string manager for use with another instance of CSimpleStringT.

IAtlStringMgr* Clone() throw();

Return Value

Returns a copy of the IAtlStringMgr object.

Remarks

Commonly called by the framework when a string manager is needed for a new string. In most cases, the this pointer is returned.

However, if the memory manager does not support being used by multiple instances of CSimpleStringT, a pointer to a sharable string manager should be returned.

System_CAPS_ICON_note.jpg Note

For usage examples, see Memory Management and CStringT.

Frees a string data structure.

void Free(CStringData* pData) throw();

Parameters

pData
A pointer to the memory block to be freed.

Remarks

Frees the specified memory block previously allocated by Allocate or Reallocate.

System_CAPS_ICON_note.jpg Note

For usage examples, see Memory Management and CStringT.

Returns a pointer to a string data structure for an empty string.

CStringData* GetNilString() throw();

Return Value

A pointer to the CStringData object used to represent an empty string.

Remarks

Call this function to return a representation of an empty string.

System_CAPS_ICON_note.jpg Note

When implementing a custom string manager, this function must never fail. You can ensure this by embedding an instance of CNilStringData in the string manager class, and return a pointer to that instance.

System_CAPS_ICON_note.jpg Note

For usage examples, see Memory Management and CStringT.

Reallocates a string data structure.

CStringData* Reallocate(  
 CStringData* pData,
 int nAllocLength,
 int nCharSize) throw();

Parameters

pData
Pointer to the memory previously allocated by this memory manager.

nAllocLength
The number of characters in the new memory block.

nCharSize
The size (in bytes) of the character type used by the string manager.

Return Value

Returns a pointer to the start of the newly allocated memory block.

Remarks

Call this function to resize the existing memory block specified by pData.

Call IAtlStringMgr::Free to free the memory allocated by this method.

System_CAPS_ICON_note.jpg Note

For usage examples, see Memory Management and CStringT.

Hierarchy Chart
ATL/MFC Shared Classes

Show: