Partager via

CStringData Class

  • Article

 

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

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

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

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.

See Also

Hierarchy Chart
ATL/MFC Shared Classes