IAtlStringMgr Class
This class represents the interface to a CStringT memory manager.
__interface IAtlStringMgr
| Name | Description |
|---|---|
| Allocate | Call this method to allocate a new string data structure. |
| Clone | Call this method to return a pointer to a new string manager for use with another instance of CSimpleStringT. |
| Free | Call this method to free a string data structure. |
| GetNilString | Returns a pointer to the CStringData object used by empty string objects. |
| Reallocate | Call 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();
nAllocLength
The number of characters in the new memory block.
nCharSize
The size (in bytes) of the character type used by the string manager.
Returns a pointer to the newly allocated memory block.
Note
Do not signal a failed allocation by throwing an exception. Instead, a failed allocation should be signaled by returning NULL.
Call IAtlStringMgr::Free or IAtlStringMgr::ReAllocate to free the memory allocated by this method.
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();
Returns a copy of the IAtlStringMgr object.
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.
Note
For usage examples, see Memory Management and CStringT.
Frees a string data structure.
void Free(CStringData* pData) throw();
pData
A pointer to the memory block to be freed.
Frees the specified memory block previously allocated by Allocate or Reallocate.
Note
For usage examples, see Memory Management and CStringT.
Returns a pointer to a string data structure for an empty string.
CStringData* GetNilString() throw();
A pointer to the CStringData object used to represent an empty string.
Call this function to return a representation of an empty string.
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.
Note
For usage examples, see Memory Management and CStringT.
Reallocates a string data structure.
CStringData* Reallocate(
CStringData* pData,
int nAllocLength,
int nCharSize) throw();
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.
Returns a pointer to the start of the newly allocated memory block.
Call this function to resize the existing memory block specified by pData.
Call IAtlStringMgr::Free to free the memory allocated by this method.
Note
For usage examples, see Memory Management and CStringT.