IAtlStringMgr Class

This class represents the interface to a CStringT memory manager.

Syntax

__interface IAtlStringMgr

Members

Methods

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.

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.

See also

Hierarchy Chart
ATL/MFC Shared Classes