CStringData Class
This class represents the data of a string object.
Syntax
struct CStringData
Members
Methods
| Name | Description |
|---|---|
| AddRef | Increments the reference count of the string data object. |
| data | Retrieves the character data of a string object. |
| IsLocked | Determines if the buffer of the associated string object is locked. |
| IsShared | Determines if the buffer of the associated string object is currently shared. |
| Lock | Locks the buffer of the associated string object. |
| Release | Releases the specified string object. |
| Unlock | Unlocks the buffer of the associated string object. |
Data Members
| Name | Description |
|---|---|
| nAllocLength | Length of allocated data in XCHARs (not including terminating null) |
| nDataLength | Length of currently used data in XCHARs (not including terminating null) |
| nRefs | The current reference count of the object. |
| pStringMgr | A pointer to the string manager of this string object. |
Remarks
This class should only be used by developers implementing custom string managers. For more information on custom string managers, see Memory Management and CStringT
This class encapsulates various types of information and data associated with a higher string object, such as CStringT, CSimpleStringT, or CFixedStringT objects. Every higher string object contains a pointer to its associated CStringData object, allowing multiple string objects to point to the same string data object. This relationship is represented by the reference count (nRefs) of the CStringData object.
Note
In certain cases, a string type (such as CFixedString) will not share a string data object with more than one higher string object. For more information on this, see Memory Management and CStringT.
This data is composed of:
The memory manager (of type IAtlStringMgr) of the string.
The current length ( nDataLength) of the string.
The allocated length ( nAllocLength) of the string. For performance reasons, this can differ from the current string length
The current reference count ( nRefs) of the
CStringDataobject. This value is used in determining how many string objects are sharing the sameCStringDataobject.The actual character buffer ( data) of the string.
Note
The actual character buffer of the string object is allocated by the string manager and is appended to the
CStringDataobject.
Requirements
Header: atlsimpstr.h
CStringData::AddRef
Increments the reference count of the string object.
void AddRef() throw();
Remarks
Increments the reference count of the string object.
Note
Do not call this method on a string with a negative reference count, since a negative count indicates that the string buffer is locked.
CStringData::data
Returns a pointer to the character buffer of a string object.
void* data() throw();
Return Value
A pointer to the character buffer of the string object.
Remarks
Call this function to return the current character buffer of the associated string object.
Note
This buffer is not allocated by the CStringData object but by the string manager when needed. When allocated, the buffer is appended to the string data object.
CStringData::IsLocked
Determines if the character buffer is locked.
bool IsLocked() const throw();
Return Value
Returns TRUE if the buffer is locked; otherwise FALSE.
Remarks
Call this function to determine if the character buffer of a string object is currently locked.
CStringData::IsShared
Determines if the character buffer is shared.
bool IsShared() const throw();
Return Value
Returns TRUE if the buffer is shared; otherwise FALSE.
Remarks
Call this function to determine if the character buffer of a string data object is currently shared among multiple string objects.
CStringData::Lock
Locks the character buffer of the associated string object.
void Lock() throw();
Remarks
Call this function to lock the character buffer of the string data object. Locking and unlocking is used when direct access to the character buffer is required by the developer. A good example of locking is demonstrated by the LockBuffer and UnlockBuffer methods of CSimpleStringT.
Note
A character buffer can only be locked if the buffer is not shared among higher string objects.
CStringData::nAllocLength
Length of the allocated character buffer.
int nAllocLength;
Remarks
Stores the length of the allocated data buffer in XCHARs (not including terminating null).
CStringData::nDataLength
Current length of the string object.
int nDataLength;
Remarks
Stores the length of currently used data in XCHARs (not including terminating null).
CStringData::nRefs
Reference count of the string data object.
long nRefs;
Remarks
Stores the reference count of the string data object. This count indicates the number of higher string objects that are associated with the string data object. A negative value indicates that the string data object is currently locked.
CStringData::pStringMgr
The memory manager of the associated string object.
IAtlStringMgr* pStringMgr;
Remarks
Stores the memory manager for the associated string object. For more information on memory managers and strings, see Memory Management and CStringT.
CStringData::Release
Decrements the reference count of the string data object.
void Release() throw();
Remarks
Call this function to decrement the reference count, freeing the CStringData structure if the reference count hits zero. This is commonly done when a string object is deleted, and therefore no longer needs to reference the string data object.
For example, the following code would call CStringData::Release for the string data object associated with str1:
{
CString str1 = _T("Hello world"); // Allocates new CStringData
}
// str1 is deleted when it goes out of scope, so it releases its string data
CStringData::Unlock
Unlocks the character buffer of the associated string object.
void Unlock() throw();
Remarks
Call this function to unlock the character buffer of the string data object. Once a buffer is unlocked, it is shareable and can be reference counted.
Note
Each call to Lock must be matched by a corresponding call to Unlock.
Locking and unlocking is used when the developer must ensure that the string data not be shared. A good example of locking is demonstrated by the LockBuffer and UnlockBuffer methods of CSimpleStringT.