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:
Managing Object Lifetimes through Reference Counting in the Windows SDK*.*
Implementing Reference Counting in the Windows SDK*.*
Rules for Managing Reference Counts in the Windows SDK*.*
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
Other Resources
Change History
Date |
History |
Reason |
|---|---|---|
October 2009 |
Described when to call ReleaseBuffer. |
Customer feedback. |