CStrBufT 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 CStrBufT Class.
This class provides automatic resource cleanup for GetBuffer and ReleaseBuffer calls on an existing CStringT object.
Syntax
template<typename TCharType>
class CStrBufT
Parameters
TCharType
The character type of the CStrBufT class. Can be one of the following:
char(for ANSI character strings)wchar_t(for Unicode character strings)TCHAR (for both ANSI and Unicode character strings)
Members
Public Typedefs
| Name | Description |
|---|---|
PCXSTR |
A pointer to a constant string. |
PXSTR |
A pointer to a string. |
StringType |
The string type whose buffer is to be manipulated by specializations of this class template. |
Public Constructors
| Name | Description |
|---|---|
| CStrBufT::CStrBufT | The constructor for the string buffer object. |
Public Methods
| Name | Description |
|---|---|
| CStrBufT::SetLength | Sets the character buffer length of the associated string object. |
Public Operators
| Name | Description |
|---|---|
| CStrBufT::operator PCXSTR | Retrieves a const pointer to the character buffer of the associated string object. |
| CStrBufT::operator PXSTR | Retrieves a pointer to the character buffer of the associated string object. |
Public Constants
| Name | Description |
|---|---|
| CStrBufT::AUTO_LENGTH | Automatically determine the new length of the string at release. |
| CStrBufT::SET_LENGTH | Set the length of the string object at GetBuffer time |
Remarks
This class is used as a wrapper class for replacing calls to GetBuffer and ReleaseBuffer, or GetBufferSetLength and ReleaseBuffer.
Primarily designed as a helper class, CStrBufT provides a convenient way for a developer to work with the character buffer of a string object without worrying about how or when to call ReleaseBuffer. This is possible because the wrapper object goes out of scope naturally in the case of an exception or multiple exiting code paths; causing its destructor to free the string resource.
Requirements
Header: atlsimpstr.h
CStrBufT::AUTO_LENGTH
Automatically determine the new length of the string at release.
static const DWORD AUTO_LENGTH = 0x01;
Remarks
Automatically determine the new length of the string at release. The string must be null-terminated.
CStrBufT::CStrBufT
Constructs a buffer object.
CStrBufT(StringType& str, int nMinLength, DWORD dwFlags = AUTO_LENGTH) throw(...);
explicit CStrBufT(StringType& str) throw(...);
Parameters
str
The string object associated with the buffer. Typically, the developer will use the predefined typedefs of CStrBuf ( TCHAR variant), CStrBufA ( char variant) and CStrBufW ( wchar_t variant).
nMinLength
The minimum length of the character buffer.
dwFlags
Determines if the string length is automatically determined. Can be one of the following:
AUTO_LENGTH String length is automatically determined when CSimpleStringT::Release is called. The string must be null-terminated. Default value.
SET_LENGTH String length is set when CSimpleStringT::GetBuffer is called.
Remarks
Creates a string buffer for the associated string object. During construction, CSimpleStringT::GetBuffer or CSimpleStringT::GetBufferSetLength is called.
Note that the copy constructor is private.
CStrBufT::operator PCXSTR
Directly accesses characters stored in the associated string object as a C-style string.
operator PCXSTR() const throw();
Return Value
A character pointer to the string's data.
Remarks
Call this function to return a pointer to the character buffer of a string object. The contents of the string object cannot be changed with this pointer.
CStrBufT::operator PXSTR
Directly accesses characters stored in the associated string object as a C-style string.
operator PXSTR() throw();
Return Value
A character pointer to the string's data.
Remarks
Call this function to return a pointer to the character buffer of a string object. The developer may change the contents of the string object with this pointer.
CStrBufT::PCXSTR
A pointer to a constant string.
typedef CSimpleStringT<TCharType>::PCXSTR PCXSTR;
CStrBufT::PXSTR
A pointer to a string.
typedef CSimpleStringT<TCharType>::PXSTR PXSTR;
CStrBufT::SET_LENGTH
Set the length of the string object at GetBuffer time.
static const DWORD SET_LENGTH = 0x02;
Remarks
Set the length of the string object at GetBuffer time.
Determines if CSimpleStringT::GetBuffer and CSimpleStringT::GetBufferSetLength are called when the string buffer object is constructed.
CStrBufT::SetLength
Sets the length of the character buffer.
void SetLength(int nLength);
Parameters
nLength
The new length of the character buffer of the string object.
Note
Must be less than or equal to the minimum buffer length specified in the constructor of CStrBufT.
Remarks
Call this function to set the length of the string represented by the buffer object.
CStrBufT::StringType
The string type whose buffer is to be manipulated by specializations of this class template.
typedef CSimpleStringT<TCharType> StringType;
Remarks
TCharType is the character type used to specialize the class template.