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.

Syntax

struct CStringData

Members

Methods

Data Members

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.

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.

  Note

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

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.

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.

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.

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.

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.

See Also

Hierarchy Chart
ATL/MFC Shared Classes