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.
Syntax
__interface IAtlStringMgr
Members
Methods
| 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. |
Remarks
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.
Requirements
Header: atlsimpstr.h
IAtlStringMgr::Allocate
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.
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.
Note
For usage examples, see Memory Management and CStringT.
IAtlStringMgr::Clone
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.
Note
For usage examples, see Memory Management and CStringT.
IAtlStringMgr::Free
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.
Note
For usage examples, see Memory Management and CStringT.
IAtlStringMgr::GetNilString
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.
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.
IAtlStringMgr::Reallocate
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.
Note
For usage examples, see Memory Management and CStringT.