Udostępnij za pośrednictwem


CSimpleStringT::GetBufferSetLength

Returns a pointer to the internal character buffer for the CSimpleStringT object, and truncates or grows its length to exactly match the length specified in nLength.

PXSTR GetBufferSetLength(
   int nLength
);

Parameters

  • nLength
    The exact size of the CSimpleStringT character buffer in characters.

Return Value

A PXSTR pointer to the CSimpleStringT (null-terminated) character buffer.

Remarks

Call this method to retrieve a specified length of the internal buffer of the CSimpleStringT object. The returned PXSTR pointer is not const and therefore enables direct modification of CSimpleStringT contents.

If you use the pointer returned by GetBufferSetLength to change the string contents, call ReleaseBuffer to update the internal state of CSimpleStringT before you use any other CSimpleStringT methods.

The address returned by GetBufferSetLength may not be valid after the call to ReleaseBuffer because additional CSimpleStringT operations can cause the CSimpleStringT buffer to be reallocated. The buffer is not reassigned if you do not change the length of the CSimpleStringT.

The buffer memory is automatically freed when the CSimpleStringT object is destroyed.

If you keep track of the string length yourself, do not append the terminating null character. You must specify the final string length when you release the buffer by using ReleaseBuffer. If you do append a terminating null character when you call ReleaseBuffer, pass -1 (the default) for the length to ReleaseBuffer, and ReleaseBuffer will perform a strlen on the buffer to determine its length.

For more information about reference counting, see the following articles:

Example

The following example demonstrates how to use CSimpleStringT::GetBufferSetLength.

CSimpleString str(pMgr);
LPTSTR pstr = str.GetBufferSetLength(3);
pstr[0] = _T('C');
pstr[1] = _T('u');
pstr[2] = _T('p');

// No need for trailing zero or call to ReleaseBuffer() 
// because GetBufferSetLength() set it for us.

str += _T(" soccer is best!");
ASSERT(_tcscmp(str, _T("Cup soccer is best!")) == 0);   

Requirements

Header: atlsimpstr.h

See Also

Reference

CSimpleStringT Class

CSimpleStringT::GetBuffer

CSimpleStringT::ReleaseBuffer

Other Resources

CSimpleStringT Members

Change History

Date

History

Reason

October 2009

Described when to call ReleaseBuffer.

Customer feedback.