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

This class represents the data of a string object.

struct CStringData

Methods

AddRefIncrements the reference count of the string data object.
dataRetrieves the character data of a string object.
IsLockedDetermines if the buffer of the associated string object is locked.
IsSharedDetermines if the buffer of the associated string object is currently shared.
LockLocks the buffer of the associated string object.
ReleaseReleases the specified string object.
UnlockUnlocks the buffer of the associated string object.

Data Members

nAllocLengthLength of allocated data in XCHARs (not including terminating null)
nDataLengthLength of currently used data in XCHARs (not including terminating null)
nRefsThe current reference count of the object.
pStringMgrA pointer to the string manager of this string object.

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.

System_CAPS_ICON_note.jpg 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 CStringData object. This value is used in determining how many string objects are sharing the same CStringData object.

  • The actual character buffer ( data) of the string.

    System_CAPS_ICON_note.jpg Note

    The actual character buffer of the string object is allocated by the string manager and is appended to the CStringData object.

Header: atlsimpstr.h

Increments the reference count of the string object.

void AddRef() throw();

Remarks

Increments the reference count of the string object.

System_CAPS_ICON_note.jpg 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.

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.

System_CAPS_ICON_note.jpg 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.

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.

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.

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.

System_CAPS_ICON_note.jpg Note

A character buffer can only be locked if the buffer is not shared among higher string objects.

Length of the allocated character buffer.

int nAllocLength;

Remarks

Stores the length of the allocated data buffer in XCHARs (not including terminating null).

Current length of the string object.

int nDataLength;

Remarks

Stores the length of currently used data in XCHARs (not including terminating null).

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.

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.

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   

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.

System_CAPS_ICON_note.jpg 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.

Hierarchy Chart
ATL/MFC Shared Classes

Show: