CSimpleStringT::GetBuffer

Returns a pointer to the internal character buffer for the CSimpleStringT object.

PXSTR GetBuffer( 
   int nMinBufferLength 
); 
PXSTR GetBuffer();

Parameters

• nMinBufferLength
  The minimum number of characters that the character buffer can hold. This value does not include space for a null terminator.

  If nMinBufferLength is larger than the length of the current buffer, GetBuffer destroys the current buffer, replaces it with a buffer of the requested size, and resets the object reference count to zero. If you have previously called LockBuffer on this buffer, you lose the buffer lock.

Return Value

An PXSTR pointer to the object's (null-terminated) character buffer.

Remarks

Call this method to return the buffer contents of the CSimpleStringT object. The returned PXSTR is not a constant and therefore allows direct modification of CSimpleStringT contents.

If you use the pointer returned by GetBuffer to change the string contents, you must call ReleaseBuffer before you use any other CSimpleStringT member methods.

The address returned by GetBuffer 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 reallocated 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, you should not append the terminating null character. However, you must specify the final string length when you release the buffer with ReleaseBuffer. If you do append a terminating null character, you should pass –1 (the default) for the length. ReleaseBuffer then determines the buffer length.

If there is insufficient memory to satisfy the GetBuffer request, this method throws a CMemoryException*.

Example

CSimpleString s(_T("abcd"), pMgr);

LPTSTR pBuffer = s.GetBuffer(10);
int    sizeOfBuffer = s.GetAllocLength();

// Directly access CSimpleString buffer
_tcscpy_s(pBuffer, sizeOfBuffer, _T("Hello")); 
ASSERT(_tcscmp(s, _T("Hello")) == 0);

s.ReleaseBuffer();   

Requirements

Header: atlsimpstr.h

See Also

Reference

CSimpleStringT Class

CSimpleStringT::GetBufferSetLength

CSimpleStringT::ReleaseBuffer

Other Resources

CSimpleStringT Members

Change History

Date	History	Reason
May 2009	Added exception description. Moved nMinBufferLength description from Remarks to Parameters.	Information enhancement.