CSimpleStringT Class

This class represents a CSimpleStringT object.

template <typename BaseType>
class CSimpleStringT

BaseType
The character type of the string 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).

CSimpleStringT is the base class for the various string classes supported by Visual C++. It provides minimal support for memory management of the string object and basic buffer manipulation. For more advanced string objects, see CStringT Class.

Header: atlsimpstr.h

Appends a CSimpleStringT object to an existing CSimpleStringT object.

void Append(const CSimpleStringT& strSrc);
void Append(PCXSTR pszSrc, int nLength);
void Append(PCXSTR pszSrc);

strSrc
The CSimpleStringT object to be appended.

pszSrc
A pointer to a string containing the characters to be appended.

nLength
The number of characters to append.

Call this method to append an existing CSimpleStringT object to another CSimpleStringT object.

The following example demonstrates the use of CSimpleStringT::Append.

CAtlString basestr;
IAtlStringMgr* pMgr = basestr.GetManager();
CSimpleString str1(pMgr), str2(pMgr);
str1.SetString(_T("Soccer is"));
str2.SetString(_T(" an elegant game"));
str1.Append(str2);
ASSERT(_tcscmp(str1, _T("Soccer is an elegant game")) == 0);

Appends a character to an existing CSimpleStringT object.

void AppendChar(XCHAR ch);

ch
The character to be appended

Call this function to append the specified character to the end of an existing CSimpleStringT object.

Copies a character or characters to a CSimpleStringT object.

static void CopyChars(
    XCHAR* pchDest,
    const XCHAR* pchSrc,
    int nChars) throw();
static void CopyChars(
    XCHAR* pchDest,
    size_t nDestLen,
    const XCHAR* pchSrc,
    int nChars) throw();

pchDest
A pointer to a character string.

nDestLen
Buffer size of pchDest

pchSrc
A pointer to a string containing the characters to be copied.

nChars
The number of pchSrc characters to be copied.

Call this method to copy characters from pchSrc to the pchDest string.

The following example demonstrates the use of CSimpleStringT::CopyChars.

CAtlString basestr;
IAtlStringMgr* pMgr = basestr.GetManager();
CSimpleString str(_T("xxxxxxxxxxxxxxxxxxx"), 20, pMgr);
const TCHAR* pszSrc = _T("Hello world!");
_tprintf_s(_T("%s\n"), str);
str.CopyChars(str.GetBuffer(), 20, pszSrc, 12);
_tprintf_s(_T("%s\n"), str);

The output from this example is as follows:

xxxxxxxxxxxxxxxxxxx
Hello world!xxxxxxx

Copies a character or characters to a CSimpleStringT object.

static void CopyCharsOverlapped(
    XCHAR* pchDest,
    const XCHAR* pchSrc,
    int nChars) throw();

pchDest
A pointer to a character string.

pchSrc
A pointer to a string containing the characters to be copied.

nChars
The number of pchSrc characters to be copied.

Call this method to copy characters from pchSrc to the pchDest string. Unlike CopyChars, CopyCharsOverlapped provides a safe method for copying from character buffers that might be overlapped.

See the example for CSimpleStringT::CopyChars, or the source code for CSimpleStringT::SetString (located in atlsimpstr.h).

Constructs a CSimpleStringT object.

CSimpleStringT(const XCHAR* pchSrc, int nLength, IAtlStringMgr* pStringMgr);
CSimpleStringT(PCXSTR pszSrc, IAtlStringMgr* pStringMgr);
CSimpleStringT(const CSimpleStringT& strSrc);
explicit CSimpleStringT(IAtlStringMgr* pStringMgr) throw();

strSrc
An existing CSimpleStringT object to be copied into this CSimpleStringT object.

pchSrc
A pointer to an array of characters of length nLength, not null terminated.

pszSrc
A null-terminated string to be copied into this CSimpleStringT object.

nLength
A count of the number of characters in pch.

pStringMgr
A pointer to the memory manager of the CSimpleStringT object. For more information about IAtlStringMgr and memory management for CSimpleStringT, see Memory Management and CStringT.

Construct a new CSimpleStringT object. Because the constructors copy the input data into new allocated storage, memory exceptions may result.

The following example demonstrates the use of CSimpleStringT::CSimpleStringT by using the ATL typedef CSimpleString. CSimpleString is a commonly used specialization of the class template CSimpleStringT.

CAtlString basestr;
IAtlStringMgr* pMgr = basestr.GetManager();

CSimpleString s1(pMgr);
// Empty string
CSimpleString s2(_T("cat"), pMgr);
// From a C string literal

CSimpleString s3(s2);
// Copy constructor
CSimpleString s4(s2 + _T(" ") + s3);

// From a string expression
CSimpleString s5(_T("xxxxxx"), 6, pMgr);
// s5 = "xxxxxx"

Makes this CSimpleStringT object an empty string and frees memory as appropriate.

void Empty() throw();

For more information, see Strings: CString Exception Cleanup.

The following example demonstrates the use of CSimpleStringT::Empty.

CAtlString basestr;
IAtlStringMgr* pMgr = basestr.GetManager();

CSimpleString s(pMgr);
ASSERT(s.IsEmpty());

Frees any extra memory previously allocated by the string but no longer needed.

void FreeExtra();

This should reduce the memory overhead consumed by the string object. The method reallocates the buffer to the exact length returned by GetLength.

CAtlString basestr;
IAtlStringMgr* pMgr;

pMgr= basestr.GetManager();
ASSERT(pMgr != NULL);

// Create a CSimpleString with 28 characters
CSimpleString str(_T("Many sports are fun to play."), 28, pMgr);
_tprintf_s(_T("Alloc length is %d, String length is %d\n"),
   str.GetAllocLength(), str.GetLength());

// Assigning a smaller string won't cause CSimpleString to free its
// memory, because it assumes the string will grow again anyway.
str = _T("Soccer is best!");
_tprintf_s(_T("Alloc length is %d, String length is %d\n"),
   str.GetAllocLength(), str.GetLength());

// This call forces CSimpleString to release the extra
// memory it doesn't need.
str.FreeExtra();
_tprintf_s(_T("Alloc length is %d, String length is %d\n"),
   str.GetAllocLength(), str.GetLength());

The output from this example is as follows:

Alloc length is 1031, String length is 1024
Alloc length is 1031, String length is 15
Alloc length is 15, String length is 15

Retrieves the allocated length of a CSimpleStringT object.

int GetAllocLength() const throw();

The number of characters allocated for this object.

Call this method to determine the number of characters allocated for this CSimpleStringT object. See FreeExtra for an example of calling this function.

Returns one character from a CSimpleStringT object.

XCHAR GetAt(int iChar) const;

iChar
Zero-based index of the character in the CSimpleStringT object. The iChar parameter must be greater than or equal to 0 and less than the value returned by GetLength. Otherwise, GetAt will generate an exception.

An XCHAR that contains the character at the specified position in the string.

Call this method to return the one character specified by iChar. The overloaded subscript ([]) operator is a convenient alias for GetAt. The null terminator is addressable without generating an exception by using GetAt. However, it is not counted by GetLength, and the value returned is 0.

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

CSimpleString s(_T("abcdef"), pMgr);
ASSERT(s.GetAt(2) == _T('c'));

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

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

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.

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

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 to update the internal state of CSimpleStringT before you use any other CSimpleStringT 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*.

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();

Returns a pointer to the internal character buffer for the CSimpleStringT object, truncating or growing its length if necessary to exactly match the length specified in nLength.

PXSTR GetBufferSetLength(int nLength);

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

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

Call this method to retrieve a specified length of the internal buffer of the CSimpleStringT object. The returned PXSTR pointer is not const and thus allows 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.

The following example demonstrates the use of CSimpleStringT::GetBufferSetLength.

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

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

Returns the number of characters in the CSimpleStringT object.

int GetLength() const throw();

A count of the characters in the string.

Call this method to return the number of characters in the object. The count does not include a null terminator.

For multibyte character sets (MBCS), GetLength counts each 8-bit character; that is, a lead and trail byte in one multibyte character are counted as two bytes. See FreeExtra for an example of calling this function.

Retrieves the memory manager of the CSimpleStringT object.

IAtlStringMgr* GetManager() const throw();

A pointer to the memory manager for the CSimpleStringT object.

Call this method to retrieve the memory manager used by the CSimpleStringT object. For more information on memory managers and string objects, see Memory Management and CStringT.

Retrieves the character string.

PCXSTR GetString() const throw();

A pointer to a null-terminated character string.

Call this method to retrieve the character string associated with the CSimpleStringT object.

The following example demonstrates the use of CSimpleStringT::GetString.

CAtlString basestr;
IAtlStringMgr* pMgr = basestr.GetManager();   
CSimpleString str(pMgr);
str += _T("Cup soccer is best!");
_tprintf_s(_T("%s"), str.GetString());

The output from this example is as follows:

Cup soccer is best!

Tests a CSimpleStringT object for the empty condition.

bool IsEmpty() const throw();

Returns TRUE if the CSimpleStringT object has 0 length; otherwise FALSE.

Call this method to determine if the object contains an empty string.

The following example demonstrates the use of CSimpleStringT::IsEmpty.

CSimpleString s(pMgr);
ASSERT(s.IsEmpty());

Disables reference counting and protects the string in the buffer.

PXSTR LockBuffer();

A pointer to a CSimpleStringT object or a null-terminated string.

Call this method to lock the buffer of the CSimpleStringT object. By calling LockBuffer, you create a copy of the string, with a -1 for the reference count. When the reference count value is -1, the string in the buffer is considered to be in a "locked" state. While in a locked state, the string is protected in two ways:

• No other string can get a reference to the data in the locked string, even if that string is assigned to the locked string.

• The locked string will never reference another string, even if that other string is copied to the locked string.

By locking the string in the buffer, you ensure that the string's exclusive hold on the buffer will remain intact.

After you have finished with LockBuffer, call UnlockBuffer to reset the reference count to 1.

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

The following example demonstrates the use of CSimpleStringT::LockBuffer.

CAtlString basestr;
IAtlStringMgr* pMgr = basestr.GetManager();

CSimpleString str(_T("Hello"), pMgr);
TCHAR ch;

str.LockBuffer();
ch = str.GetAt(2);
_tprintf_s(_T("%c"), ch);
str.UnlockBuffer();

The output from this example is as follows:

l

Call this function to access a single character of the character array.

XCHAR operator[](int iChar) const;

iChar
Zero-based index of a character in the string.

The overloaded subscript ([]) operator returns a single character specified by the zero-based index in iChar. This operator is a convenient substitute for the GetAt member function.

The following example demonstrates the use of CSimpleStringT::operator [].

CSimpleString s(_T("abc"), pMgr);
ASSERT(s[1] == _T('b'));

Call this function to access a single character of the character array.

XCHAR operator[](int iChar) const;

iChar
Zero-based index of a character in the string.

The overloaded subscript ([]) operator returns a single character specified by the zero-based index in iChar. This operator is a convenient substitute for the GetAt member function.

Joins a new string or character to the end of an existing string.

CSimpleStringT& operator +=(PCXSTR pszSrc);
CSimpleStringT& operator +=(const CSimpleStringT& strSrc);
template<int t_nSize>
CSimpleStringT& operator+=(const CStaticString< XCHAR, t_nSize >& strSrc);
CSimpleStringT& operator +=(char ch);
CSimpleStringT& operator +=(unsigned char ch);
CSimpleStringT& operator +=(wchar_t ch);

pszSrc
A pointer to a null-terminated string.

strSrc
A pointer to an existing CSimpleStringT object.

ch
The character to be appended.

The operator accepts another CSimpleStringT object or a character. Note that memory exceptions may occur whenever you use this concatenation operator because new storage may be allocated for characters added to this CSimpleStringT object.

The following example demonstrates the use of CSimpleStringT::operator +=.

CSimpleString str(_T("abc"), pMgr);
ASSERT(_tcscmp((str += _T("def")), _T("abcdef")) == 0);

Assigns a new value to a CSimpleStringT object.

CSimpleStringT& operator =(PCXSTR pszSrc);
CSimpleStringT& operator =(const CSimpleStringT& strSrc);

pszSrc
A pointer to a null-terminated string.

strSrc
A pointer to an existing CSimpleStringT object.

If the destination string (the left side) is already large enough to store the new data, no new memory allocation is performed. Note that memory exceptions may occur whenever you use the assignment operator because new storage is often allocated to hold the resulting CSimpleStringT object.

The following example demonstrates the use of CSimpleStringT::operator =.

CSimpleString s1(pMgr), s2(pMgr);
// Empty CSimpleStringT objects

s1 = _T("cat");
// s1 = "cat"
ASSERT(_tcscmp(s1, _T("cat")) == 0);

s2 = s1;               // s1 and s2 each = "cat"
ASSERT(_tcscmp(s2, _T("cat")) == 0);

s1 = _T("the ") + s1;
// Or expressions
ASSERT(_tcscmp(s1, _T("the cat")) == 0);

s1 = _T("x");
// Or just individual characters
ASSERT(_tcscmp(s1, _T("x")) == 0);

Directly accesses characters stored in a CSimpleStringT object as a C-style string.

operator PCXSTR() const throw();

A character pointer to the string's data.

No characters are copied; only a pointer is returned. Be careful with this operator. If you change a CString object after you have obtained the character pointer, you may cause a reallocation of memory that invalidates the pointer.

The following example demonstrates the use of CSimpleStringT::operator PCXSTR.

// If the prototype of a function is known to the compiler,
// the PCXSTR cast operator may be invoked implicitly.

CSimpleString strSports(L"Soccer is Best!", pMgr);
WCHAR sz[1024];

wcscpy_s(sz, strSports);

// If the prototype isn't known or is a va_arg prototype,
// you must invoke the cast operator explicitly. For example,
// the va_arg part of a call to swprintf_s() needs the cast:

swprintf_s(sz, 1024, L"I think that %s!\n", (PCWSTR)strSports);

// While the format parameter is known to be an PCXSTR and
// therefore doesn't need the cast:

swprintf_s(sz, 1024, strSports);

// Note that some situations are ambiguous. This line will
// put the address of the strSports object to stdout:

wcout << strSports;

// while this line will put the content of the string out:

wcout << (PCWSTR)strSports;

A pointer to a constant string.

typedef ChTraitsBase< BaseType >::PCXSTR PCXSTR;

Allocates a specific amount of bytes for the CSimpleStringT object.

void Preallocate( int nLength);

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

Call this method to allocate a specific buffer size for the CSimpleStringT object.

CSimpleStringT generates a STATUS_NO_MEMORY exception if it is unable to allocate space for the character buffer. By default, memory allocation is performed by WIN32 API functions HeapAlloc or HeapReAlloc.

The following example demonstrates the use of CSimpleStringT::Preallocate.

CAtlString basestr;
IAtlStringMgr* pMgr = basestr.GetManager();

CSimpleString str(pMgr);
_tprintf_s(_T("Allocated length: %d\n"), str.GetAllocLength());
str.Preallocate(100);
_tprintf_s(_T("Allocated length: %d\n"), str.GetAllocLength());

The output from this example is as follows:

Allocated length: 0
Allocated length: 103

A pointer to a string.

typedef ChTraitsBase< BaseType >::PXSTR PXSTR;

Releases control of the buffer allocated by GetBuffer.

void ReleaseBuffer(int nNewLength = -1);

nNewLength
The new length of the string in characters, not counting a null terminator. If the string is null terminated, the -1 default value sets the CSimpleStringT size to the current length of the string.

Call this method to reallocate or free up the buffer of the string object. If you know that the string in the buffer is null terminated, you can omit the nNewLength argument. If your string is not null terminated, use nNewLength to specify its length. The address returned by GetBuffer is invalid after the call to ReleaseBuffer or any other CSimpleStringT operation.

The following example demonstrates the use of CSimpleStringT::ReleaseBuffer.

const int bufferSize = 1024;
CSimpleString s(_T("abc"), pMgr);
LPTSTR p = s.GetBuffer(bufferSize);
_tcscpy_s(p, bufferSize, _T("abc"));

// use the buffer directly
ASSERT(s.GetLength() == 3);

// String length = 3
s.ReleaseBuffer();

// Surplus memory released, p is now invalid.
ASSERT(s.GetLength() == 3);

// Length still 3

Releases control of the buffer allocated by GetBuffer.

void ReleaseBufferSetLength(int nNewLength);

nNewLength
The length of the string being released

This function is functionally similar to ReleaseBuffer except that a valid length for the string object must be passed.

Sets a single character from a CSimpleStringT object.

void SetAt(int iChar, XCHAR ch);

iChar
Zero-based index of the character in the CSimpleStringT object. The iChar parameter must be greater than or equal to 0 and less than the value returned by GetLength.

ch
The new character.

Call this method to overwrite the character located at iChar. This method will not enlarge the string if iChar exceeds the bounds of the existing string.

The following example demonstrates the use of CSimpleStringT::SetAt.

CSimpleString s(_T("abcdef"), pMgr);
s.SetAt(1, _T('a'));
ASSERT(_tcscmp(s, _T("aacdef")) == 0);

Specifies the memory manager of the CSimpleStringT object.

void SetManager(IAtlStringMgr* pStringMgr);

pStringMgr
A pointer to the new memory manager.

Call this method to specify a new memory manager used by the CSimpleStringT object. For more information on memory managers and string objects, see Memory Management and CStringT.

The following example demonstrates the use of CSimpleStringT::SetManager.

CSimpleString s(pMgr);
s.SetManager(pCustomMgr);

Sets the string of a CSimpleStringT object.

void SetString(PCXSTR pszSrc, int nLength);
void SetString(PCXSTR pszSrc);

pszSrc
A pointer to a null-terminated string.

nLength
A count of the number of characters in pszSrc.

Copy a string into the CSimpleStringT object. SetString overwrites the older string data in the buffer.

Both versions of SetString check whether pszSrc is a null pointer, and if it is, throw an E_INVALIDARG error.

The one-parameter version of SetString expects pszSrc to point to a null-terminated string.

The two-parameter version of SetString also expects pszSrc to be a null-terminated string. It uses nLength as the string length unless it encounters a null terminator first.

The two-parameter version of SetString also checks whether pszSrc points to a location in the current buffer in CSimpleStringT. In this special case, SetString uses a memory copy function that does not overwrite the string data as it copies the string data back to its buffer.

The following example demonstrates the use of CSimpleStringT::SetString.

CSimpleString s(_T("abcdef"), pMgr);
ASSERT(_tcscmp(s, _T("abcdef")) == 0);
s.SetString(_T("Soccer"), 6);
ASSERT(_tcscmp(s, _T("Soccer")) == 0);

Returns the number of characters in the specified string.

ATL_NOINLINE static int StringLength(PCXSTR psz) throw();

psz
A pointer to a null-terminated string.

The number of characters in psz; not counting a null terminator.

Call this method to retrieve the number of characters in the string pointed to by psz.

The following example demonstrates the use of CSimpleStringT::StringLength.

ASSERT(CSimpleString::StringLength(_T("soccer")) == 6);

Truncates the string to the new length.

void Truncate(int nNewLength);

nNewLength
The new length of the string.

Call this method to truncate the contents of the string to the new length.

The following example demonstrates the use of CSimpleStringT::Truncate.

CAtlString basestr;
IAtlStringMgr* pMgr = basestr.GetManager();
CSimpleString str(_T("abcdefghi"), pMgr);
_tprintf_s(_T("String length: %d / Allocated length: %d\n"), str.GetLength(), str.GetAllocLength());
_tprintf_s(_T("Contents: %s\n"), (LPCTSTR)str);
str.Truncate(4);
_tprintf_s(_T("String length: %d / Allocated length: %d\n"), str.GetLength(), str.GetAllocLength());
_tprintf_s(_T("Contents: %s\n"), (LPCTSTR)str);

The output from this example is:

String length: 9 / Allocated length: 15
Contents: abcdefghi
String length: 4 / Allocated length: 15
Contents: abcd

Unlocks the buffer of the CSimpleStringT object.

void UnlockBuffer() throw();

Call this method to reset the reference count of the string to 1.

The CSimpleStringT destructor automatically calls UnlockBuffer to ensure that the buffer is not locked when the destructor is called. For an example of this method, see LockBuffer.

Destroys a CSimpleStringT object.

~CSimpleStringT() throw();

Call this method to destroy the CSimpleStringT object.

Hierarchy Chart
ATL/MFC Shared Classes