CSimpleStringT-Klasse

Diese Klasse stellt ein CSimpleStringT Objekt dar.

Syntax

template <typename BaseType>
class CSimpleStringT

Parameter

BaseType
Der Zeichentyp der Zeichenfolgenklasse. Dabei kann es sich um eine der folgenden Methoden handeln:

• char (für ANSI-Zeichenfolgen).

• wchar_t (für Unicode-Zeichenfolgen).

• TCHAR (sowohl für ANSI- als auch für Unicode-Zeichenzeichenfolgen).

Member

Öffentliche Typedefs

Name	Beschreibung
CSimpleStringT::PCXSTR	Ein Zeiger auf eine konstante Zeichenfolge.
CSimpleStringT::PXSTR	Ein Zeiger auf eine Zeichenfolge.

Öffentliche Konstruktoren

Name	Beschreibung
CSimpleStringT::CSimpleStringT	CSimpleStringT Erstellt Objekte auf verschiedene Arten.
CSimpleStringT::~CSimpleStringT	Destruktor.

Öffentliche Methoden

Name	Beschreibung
CSimpleStringT::Append	Fügt ein Objekt an ein CSimpleStringT vorhandenes CSimpleStringT Objekt an.
CSimpleStringT::AppendChar	Fügt ein Zeichen an ein vorhandenes CSimpleStringT Objekt an.
CSimpleStringT::CopyChars	Kopiert ein Zeichen oder Zeichen in eine andere Zeichenfolge.
CSimpleStringT::CopyCharsOverlapped	Kopiert ein Zeichen oder Zeichen in eine andere Zeichenfolge, in der sich die Puffer überlappen.
CSimpleStringT::Empty	Erzwingt eine Zeichenfolge, die eine Länge von Null hat.
CSimpleStringT::FreeExtra	Gibt zusätzlichen Arbeitsspeicher frei, der zuvor vom Zeichenfolgenobjekt zugewiesen wurde.
CSimpleStringT::GetAllocLength	Ruft die zugewiesene Länge eines CSimpleStringT Objekts ab.
CSimpleStringT::GetAt	Gibt das Zeichen an einer bestimmten Position zurück.
CSimpleStringT::GetBuffer	Gibt einen Zeiger auf die Zeichen in einem CSimpleStringT.
CSimpleStringT::GetBufferSetLength	Gibt einen Zeiger auf die Zeichen in einem CSimpleStringT, abgeschnitten auf die angegebene Länge zurück.
CSimpleStringT::GetLength	Gibt die Anzahl der Zeichen in einem CSimpleStringT Objekt zurück.
CSimpleStringT::GetManager	Ruft den Speicher-Manager des CSimpleStringT Objekts ab.
CSimpleStringT::GetString	Ruft die Zeichenfolge ab.
CSimpleStringT::IsEmpty	Überprüft, ob ein CSimpleStringT Objekt keine Zeichen enthält.
CSimpleStringT::LockBuffer	Deaktiviert die Verweiszählung und schützt die Zeichenfolge im Puffer.
CSimpleStringT::Preallocate	Weist einen bestimmten Arbeitsspeicher für den Zeichenpuffer zu.
CSimpleStringT::ReleaseBuffer	Gibt die Steuerung des puffers frei, der von GetBuffer.
CSimpleStringT::ReleaseBufferSetLength	Gibt die Steuerung des puffers frei, der von GetBuffer.
CSimpleStringT::SetAt	Legt ein Zeichen an einer bestimmten Position fest.
CSimpleStringT::SetManager	Legt den Speicher-Manager eines CSimpleStringT Objekts fest.
CSimpleStringT::SetString	Legt die Zeichenfolge eines CSimpleStringT Objekts fest.
CSimpleStringT::StringLength	Gibt die Anzahl der Zeichen in der angegebenen Zeichenfolge zurück.
CSimpleStringT::Truncate	Schneidet die Zeichenfolge auf eine angegebene Länge ab.
CSimpleStringT::UnlockBuffer	Aktiviert die Verweiszählung und gibt die Zeichenfolge im Puffer frei.

Öffentliche Operatoren

Name	Beschreibung
CSimpleStringT::operator PCXSTR	Greift direkt auf Zeichen zu, die in einem CSimpleStringT Objekt als Zeichenfolge im C-Stil gespeichert sind.
CSimpleStringT::operator[]	Gibt das Zeichen an einer bestimmten Position zurück – Operatorenersetzung für GetAt.
CSimpleStringT::operator +=	Verkettet eine neue Zeichenfolge am Ende einer vorhandenen Zeichenfolge.
CSimpleStringT::operator =	Weist einem CSimpleStringT Objekt einen neuen Wert zu.

Hinweise

CSimpleStringT ist die Basisklasse für die verschiedenen Zeichenfolgenklassen, die von Visual C++ unterstützt werden. Es bietet minimale Unterstützung für die Speicherverwaltung des Zeichenfolgenobjekts und die grundlegende Puffermanipulation. Weitere erweiterte Zeichenfolgenobjekte finden Sie unter CStringT Class.

Anforderungen

Kopfball:atlsimpstr.h

CSimpleStringT::Append

Fügt ein Objekt an ein CSimpleStringT vorhandenes CSimpleStringT Objekt an.

Syntax

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

Parameter

strSrc
Das CSimpleStringT objekt, das angefügt werden soll.

pszSrc
Ein Zeiger auf eine Zeichenfolge, die die anzufügenden Zeichen enthält.

nLength
Die Anzahl der anzufügenden Zeichen.

Hinweise

Rufen Sie diese Methode auf, um ein vorhandenes CSimpleStringT Objekt an ein anderes CSimpleStringT Objekt anzufügen.

Beispiel

Das folgende Beispiel veranschaulicht die Verwendung von 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);

CSimpleStringT::AppendChar

Fügt ein Zeichen an ein vorhandenes CSimpleStringT Objekt an.

Syntax

void AppendChar(XCHAR ch);

Parameter

ch
Das anzufügende Zeichen

Hinweise

Rufen Sie diese Funktion auf, um das angegebene Zeichen am Ende eines vorhandenen CSimpleStringT Objekts anzufügen.

CSimpleStringT::CopyChars

Kopiert ein Zeichen oder Zeichen in ein CSimpleStringT Objekt.

Syntax

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

Parameter

pchDest
Ein Zeiger auf eine Zeichenfolge.

nDestLen
Puffergröße von pchDest

pchSrc
Ein Zeiger auf eine Zeichenfolge, die die zu kopierenden Zeichen enthält.

nChars
Die Anzahl der pchSrc zu kopierenden Zeichen.

Hinweise

Rufen Sie diese Methode auf, um Zeichen aus pchSrc der pchDest Zeichenfolge zu kopieren.

Beispiel

Das folgende Beispiel veranschaulicht die Verwendung von 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);

Die Ausgabe aus diesem Beispiel lautet wie folgt:

xxxxxxxxxxxxxxxxxxx
Hello world!xxxxxxx

CSimpleStringT::CopyCharsOverlapped

Kopiert ein Zeichen oder Zeichen in ein CSimpleStringT Objekt.

Syntax

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

Parameter

pchDest
Ein Zeiger auf eine Zeichenfolge.

pchSrc
Ein Zeiger auf eine Zeichenfolge, die die zu kopierenden Zeichen enthält.

nChars
Die Anzahl der pchSrc zu kopierenden Zeichen.

Hinweise

Rufen Sie diese Methode auf, um Zeichen aus pchSrc der pchDest Zeichenfolge zu kopieren. Im Gegensatz dazu CopyCharsCopyCharsOverlapped wird eine sichere Methode zum Kopieren aus Zeichenpuffern bereitgestellt, die sich möglicherweise überlappen.

Beispiel

Sehen Sie sich das Beispiel für CSimpleStringT::CopyCharsoder den Quellcode für CSimpleStringT::SetString (in atlsimpstr.h) an.

CSimpleStringT::CSimpleStringT

Erstellt ein CSimpleStringT-Objekt.

Syntax

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

Parameter

strSrc
Ein vorhandenes CSimpleStringT Objekt, das in dieses CSimpleStringT Objekt kopiert werden soll.

pchSrc
Ein Zeiger auf ein Array von Längenzeichen nLength, nicht null beendet.

pszSrc
Eine mit Null beendete Zeichenfolge, die in dieses CSimpleStringT Objekt kopiert werden soll.

nLength
Anzahl der Zeichen in pch.

pStringMgr
Ein Zeiger auf den Speicher-Manager des CSimpleStringT Objekts. Weitere Informationen zur IAtlStringMgr Speicherverwaltung und zur Speicherverwaltung CSimpleStringTfinden Sie unter Speicherverwaltung und CStringT.

Hinweise

Erstellt ein neues CSimpleStringT-Objekt. Da die Konstruktoren die Eingabedaten in neuen zugewiesenen Speicher kopieren, können Speichereinnahmen dazu führen.

Beispiel

Im folgenden Beispiel wird die Verwendung CSimpleStringT::CSimpleStringT der ATL typedefCSimpleStringveranschaulicht. CSimpleString ist eine häufig verwendete Spezialisierung der Klassenvorlage 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"

CSimpleStringT::Empty

Macht dieses CSimpleStringT Objekt zu einer leeren Zeichenfolge und gibt ggf. Arbeitsspeicher frei.

Syntax

void Empty() throw();

Hinweise

Weitere Informationen finden Sie unter "Zeichenfolgen: CString Ausnahmebereinigung".

Beispiel

Das folgende Beispiel veranschaulicht die Verwendung von CSimpleStringT::Empty.

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

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

CSimpleStringT::FreeExtra

Gibt zusätzlichen Arbeitsspeicher frei, der zuvor von der Zeichenfolge zugewiesen wurde, aber nicht mehr benötigt wird.

Syntax

void FreeExtra();

Hinweise

Dadurch sollte der vom Zeichenfolgenobjekt verbrauchte Arbeitsspeicheraufwand reduziert werden. Die Methode bezieht die Zuordnung des Puffers auf die genaue Länge, die von GetLength.

Beispiel

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

Die Ausgabe aus diesem Beispiel lautet wie folgt:

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

CSimpleStringT::GetAllocLength

Ruft die zugewiesene Länge eines CSimpleStringT Objekts ab.

Syntax

int GetAllocLength() const throw();

Rückgabewert

Die Anzahl der für dieses Objekt zugewiesenen Zeichen.

Hinweise

Rufen Sie diese Methode auf, um die Anzahl der für dieses CSimpleStringT Objekt zugewiesenen Zeichen zu bestimmen. Sehen Sie FreeExtra sich ein Beispiel für das Aufrufen dieser Funktion an.

CSimpleStringT::GetAt

Gibt ein Zeichen aus einem CSimpleStringT Objekt zurück.

Syntax

XCHAR GetAt(int iChar) const;

Parameter

iChar
Nullbasierter Index des Zeichens im CSimpleStringT Objekt. Der iChar Parameter muss größer oder gleich 0 und kleiner als der wert sein, der von GetLength. GetAt Andernfalls wird eine Ausnahme generiert.

Rückgabewert

Eine XCHAR , die das Zeichen an der angegebenen Position in der Zeichenfolge enthält.

Hinweise

Rufen Sie diese Methode auf, um das durch iChar. Der überladene Tiefstellungsoperator ([]) ist ein bequemer Alias für GetAt. Der Null-Endator kann adressiert werden, ohne eine Ausnahme mithilfe GetAtvon . Es wird jedoch nicht von GetLengthgezählt, und der zurückgegebene Wert ist 0.

Beispiel

Im folgenden Beispiel wird die Verwendung CSimpleStringT::GetAtveranschaulicht.

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

CSimpleStringT::GetBuffer

Gibt einen Zeiger auf den internen Zeichenpuffer für das CSimpleStringT Objekt zurück.

Syntax

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

Parameter

nMinBufferLength
Die Mindestanzahl von Zeichen, die der Zeichenpuffer enthalten kann. Dieser Wert enthält keinen Leerraum für einen Null-Terminator.

Wenn nMinBufferLength die Länge des aktuellen Puffers größer ist, GetBuffer wird der aktuelle Puffer zerstört, durch einen Puffer der angeforderten Größe ersetzt und die Objektverweisanzahl auf Null zurückgesetzt. Wenn Sie diesen Puffer zuvor aufgerufen LockBuffer haben, verlieren Sie die Puffersperre.

Rückgabewert

Ein PXSTR Zeiger auf den (null-beendeten) Zeichenpuffer des Objekts.

Hinweise

Rufen Sie diese Methode auf, um den Pufferinhalt des CSimpleStringT Objekts zurückzugeben. Die zurückgegebene PXSTR ist keine Konstante und ermöglicht daher eine direkte Änderung des CSimpleStringT Inhalts.

Wenn Sie den zeiger verwenden, der zurückgegeben GetBuffer wird, um den Zeichenfolgeninhalt zu ändern, müssen Sie den ReleaseBuffer internen Zustand CSimpleStringT aktualisieren, bevor Sie andere CSimpleStringT Methoden verwenden.

Die zurückgegebene GetBuffer Adresse ist möglicherweise nach dem Aufruf ReleaseBuffer ungültig, da zusätzliche CSimpleStringT Vorgänge dazu führen können, dass der CSimpleStringT Puffer neu zugeordnet wird. Der Puffer wird nicht neu zuweisungen, wenn Sie die Länge der CSimpleStringT.

Der Pufferspeicher wird automatisch freigegeben, wenn das CSimpleStringT Objekt zerstört wird.

Wenn Sie die Länge der Zeichenfolge selbst nachverfolgen, sollten Sie das endende NULL-Zeichen nicht anfügen. Sie müssen jedoch die endgültige Zeichenfolgenlänge angeben, wenn Sie den Puffer freigeben.ReleaseBuffer Wenn Sie ein endendes NULL-Zeichen anfügen, sollten Sie -1 (standard) für die Länge übergeben. ReleaseBuffer bestimmt dann die Pufferlänge.

Wenn nicht genügend Arbeitsspeicher vorhanden ist, um die GetBuffer Anforderung zu erfüllen, löst diese Methode eine CMemoryException*.

Beispiel

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

CSimpleStringT::GetBufferSetLength

Gibt einen Zeiger auf den internen Zeichenpuffer für das CSimpleStringT Objekt zurück, schneidet oder wächst die Länge, wenn erforderlich, um genau mit der angegebenen nLengthLänge übereinzugleichen.

Syntax

PXSTR GetBufferSetLength(int nLength);

Parameter

nLength
Die genaue Größe des CSimpleStringT Zeichenpuffers in Zeichen.

Rückgabewert

Ein PXSTR Zeiger auf den (null-beendeten) Zeichenpuffer des Objekts.

Hinweise

Rufen Sie diese Methode auf, um eine angegebene Länge des internen Puffers des CSimpleStringT Objekts abzurufen. Der zurückgegebene Zeiger PXSTR ist nicht const und ermöglicht somit eine direkte Änderung des CSimpleStringT Inhalts.

Wenn Sie den zurückgegebenen GetBufferSetLength Zeiger verwenden, um den Zeichenfolgeninhalt zu ändern, rufen ReleaseBuffer Sie auf, um den internen Zustand CSimpleStringT zu aktualisieren, bevor Sie andere CSimpleStringT Methoden verwenden.

Die zurückgegebene GetBufferSetLength Adresse ist möglicherweise nach dem Aufruf ReleaseBuffer ungültig, da zusätzliche CSimpleStringT Vorgänge dazu führen können, dass der CSimpleStringT Puffer neu zugeordnet wird. Der Puffer wird nicht neu zugewiesen, wenn Sie die Länge der CSimpleStringT.

Der Pufferspeicher wird automatisch freigegeben, wenn das CSimpleStringT Objekt zerstört wird.

Wenn Sie die Länge der Zeichenfolge selbst nachverfolgen, fügen Sie das endende NULL-Zeichen nicht an. Sie müssen die endgültige Zeichenfolgenlänge angeben, wenn Sie den Puffer mithilfe von ReleaseBuffer. Wenn Sie beim Aufrufen ReleaseBufferein endendes NULL-Zeichen anfügen, übergeben Sie -1 (standard) für die Länge ReleaseBufferan , und ReleaseBuffer führen Sie einen strlen für den Puffer aus, um die Länge zu bestimmen.

Weitere Informationen zur Referenzzählung finden Sie in den folgenden Artikeln:

• Verwalten von Objektlebensdauern über Referenzzählung im Windows SDK.
• Implementieren von Referenzzählungen im Windows SDK.
• Regeln für die Verwaltung von Referenzanzahlen im Windows SDK.

Beispiel

Das folgende Beispiel veranschaulicht die Verwendung von 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);

CSimpleStringT::GetLength

Gibt die Anzahl der Zeichen im CSimpleStringT Objekt zurück.

Syntax

int GetLength() const throw();

Rückgabewert

Anzahl der Zeichen in der Zeichenfolge.

Hinweise

Rufen Sie diese Methode auf, um die Anzahl der Zeichen im Objekt zurückzugeben. Die Anzahl enthält keinen Null-Terminator.

Bei Multibyte-Zeichensätzen (MBCS) GetLength werden jedes 8-Bit-Zeichen gezählt, d. h. ein Lead- und Trailbyte-Byte in einem Multibyte-Zeichen werden als zwei Bytes gezählt. Sehen Sie FreeExtra sich ein Beispiel für das Aufrufen dieser Funktion an.

CSimpleStringT::GetManager

Ruft den Speicher-Manager des CSimpleStringT Objekts ab.

Syntax

IAtlStringMgr* GetManager() const throw();

Rückgabewert

Ein Zeiger auf den Speicher-Manager für das CSimpleStringT Objekt.

Hinweise

Rufen Sie diese Methode auf, um den vom CSimpleStringT Objekt verwendeten Speicher-Manager abzurufen. Weitere Informationen zu Speichermanagern und Zeichenfolgenobjekten finden Sie unter Speicherverwaltung und CStringT.

CSimpleStringT::GetString

Ruft die Zeichenfolge ab.

Syntax

PCXSTR GetString() const throw();

Rückgabewert

Ein Zeiger auf eine mit Null beendete Zeichenfolge.

Hinweise

Rufen Sie diese Methode auf, um die dem Objekt zugeordnete CSimpleStringT Zeichenfolge abzurufen.

Hinweis

Der zurückgegebene Zeiger PCXSTR ist const und lässt keine direkte Änderung von Inhalten CSimpleStringT zu.

Beispiel

Das folgende Beispiel veranschaulicht die Verwendung von CSimpleStringT::GetString.

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

Die Ausgabe aus diesem Beispiel lautet wie folgt:

Cup soccer is best!

CSimpleStringT::IsEmpty

Testet ein CSimpleStringT Objekt für die leere Bedingung.

Syntax

bool IsEmpty() const throw();

Rückgabewert

Gibt zurück TRUE , wenn das CSimpleStringT Objekt eine Länge von 0 hat; andernfalls FALSE.

Hinweise

Rufen Sie diese Methode auf, um festzustellen, ob das Objekt eine leere Zeichenfolge enthält.

Beispiel

Das folgende Beispiel veranschaulicht die Verwendung von CSimpleStringT::IsEmpty.

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

CSimpleStringT::LockBuffer

Deaktiviert die Verweiszählung und schützt die Zeichenfolge im Puffer.

Syntax

PXSTR LockBuffer();

Rückgabewert

Ein Zeiger auf ein CSimpleStringT Objekt oder eine mit Null beendete Zeichenfolge.

Hinweise

Rufen Sie diese Methode auf, um den Puffer des CSimpleStringT Objekts zu sperren. Durch Aufrufen LockBuffererstellen Sie eine Kopie der Zeichenfolge mit einer -1 für die Referenzanzahl. Wenn der Wert für die Referenzanzahl -1 lautet, wird die Zeichenfolge im Puffer als "gesperrt" betrachtet. In einem gesperrten Zustand ist die Zeichenfolge auf zwei Arten geschützt:

• Keine andere Zeichenfolge kann einen Verweis auf die Daten in der gesperrten Zeichenfolge abrufen, auch wenn diese Zeichenfolge der gesperrten Zeichenfolge zugewiesen ist.

• Die gesperrte Zeichenfolge verweist niemals auf eine andere Zeichenfolge, auch wenn diese andere Zeichenfolge in die gesperrte Zeichenfolge kopiert wird.

Durch Sperren der Zeichenfolge im Puffer stellen Sie sicher, dass der exklusive Halteraum der Zeichenfolge für den Puffer erhalten bleibt.

Nachdem Sie mit LockBufferdem Vorgang fertig sind, rufen Sie auf UnlockBuffer , um die Verweisanzahl auf 1 zurückzusetzen.

Hinweis

Wenn Sie einen gesperrten Puffer aufrufen GetBuffer und den GetBuffer Parameter nMinBufferLength auf größer als die Länge des aktuellen Puffers festlegen, verlieren Sie die Puffersperre. Ein solcher Aufruf, um den aktuellen Puffer zu GetBuffer zerstören, ersetzt ihn durch einen Puffer der angeforderten Größe und setzt die Referenzanzahl auf Null zurück.

Weitere Informationen zur Referenzzählung finden Sie in den folgenden Artikeln:

• Verwalten von Objektlebensdauern über Referenzzählung im Windows SDK

• Implementieren von Verweiszählungen im Windows SDK

• Regeln für die Verwaltung von Referenzanzahlen im Windows SDK

Beispiel

Das folgende Beispiel veranschaulicht die Verwendung von 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();

Die Ausgabe aus diesem Beispiel lautet wie folgt:

l

CSimpleStringT::operator[]

Rufen Sie diese Funktion auf, um auf ein einzelnes Zeichen des Zeichenarrays zuzugreifen.

Syntax

XCHAR operator[](int iChar) const;

Parameter

iChar
Nullbasierter Index eines Zeichens in der Zeichenfolge.

Hinweise

Der Überladungsoperator tiefgestellt ([]) gibt ein einzelnes Zeichen zurück, das durch den nullbasierten Index in iCharangegeben wird. Dieser Operator ist ein praktischer Ersatz für die GetAt Memberfunktion.

Hinweis

Sie können den Operator tiefgestellt ([]) verwenden, um den Wert eines Zeichens in einem CSimpleStringTZeichen abzurufen, aber Sie können ihn nicht verwenden, um den Wert eines Zeichens in einem CSimpleStringTZeichen zu ändern.

Beispiel

Das folgende Beispiel veranschaulicht die Verwendung von CSimpleStringT::operator [].

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

CSimpleStringT::operator +=

Verknüpft eine neue Zeichenfolge oder ein neues Zeichen am Ende einer vorhandenen Zeichenfolge.

Syntax

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

Parameter

pszSrc
Ein Zeiger auf eine mit Null beendete Zeichenfolge.

strSrc
Ein Zeiger auf ein vorhandenes CSimpleStringT Objekt.

ch
Das Zeichen, das angefügt werden soll.

Hinweise

Der Operator akzeptiert ein anderes CSimpleStringT Objekt oder ein Zeichen. Beachten Sie, dass Speicherabnahmen auftreten können, wenn Sie diesen Verkettungsoperator verwenden, da diesem Objekt möglicherweise neuer Speicher für Zeichen zugewiesen werden kann, die diesem CSimpleStringT Objekt hinzugefügt werden.

Beispiel

Das folgende Beispiel veranschaulicht die Verwendung von CSimpleStringT::operator +=.

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

CSimpleStringT::operator =

Weist einem CSimpleStringT Objekt einen neuen Wert zu.

Syntax

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

Parameter

pszSrc
Ein Zeiger auf eine mit Null beendete Zeichenfolge.

strSrc
Ein Zeiger auf ein vorhandenes CSimpleStringT Objekt.

Hinweise

Wenn die Zielzeichenfolge (links) bereits groß genug ist, um die neuen Daten zu speichern, wird keine neue Speicherzuweisung durchgeführt. Beachten Sie, dass Speicherausnahmen auftreten können, wenn Sie den Zuordnungsoperator verwenden, da häufig neuer Speicher für das resultierende CSimpleStringT Objekt zugeordnet ist.

Beispiel

Das folgende Beispiel veranschaulicht die Verwendung von 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);

CSimpleStringT::operator PCXSTR

Greift direkt auf Zeichen zu, die in einem CSimpleStringT Objekt als Zeichenfolge im C-Stil gespeichert sind.

Syntax

operator PCXSTR() const throw();

Rückgabewert

Ein Zeichenzeiger auf die Daten der Zeichenfolge.

Hinweise

Es werden keine Zeichen kopiert; nur ein Zeiger wird zurückgegeben. Achten Sie bei diesem Operator darauf. Wenn Sie ein CString Objekt ändern, nachdem Sie den Zeichenzeiger abgerufen haben, kann dies zu einer Neuzuweisung des Speichers führen, der den Zeiger ungültig macht.

Beispiel

Das folgende Beispiel veranschaulicht die Verwendung von 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;

CSimpleStringT::PCXSTR

Ein Zeiger auf eine konstante Zeichenfolge.

Syntax

typedef ChTraitsBase< BaseType >::PCXSTR PCXSTR;

CSimpleStringT::Preallocate

Weist eine bestimmte Anzahl von Bytes für das CSimpleStringT Objekt zu.

Syntax

void Preallocate( int nLength);

Parameter

nLength
Die genaue Größe des CSimpleStringT Zeichenpuffers in Zeichen.

Hinweise

Rufen Sie diese Methode auf, um eine bestimmte Puffergröße für das CSimpleStringT Objekt zuzuweisen.

CSimpleStringT generiert eine STATUS_NO_MEMORY Ausnahme, wenn der Platz für den Zeichenpuffer nicht zugewiesen werden kann. Standardmäßig erfolgt die Speicherzuweisung durch WIN32-API-Funktionen HeapAlloc oder HeapReAlloc.

Beispiel

Das folgende Beispiel veranschaulicht die Verwendung von 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());

Die Ausgabe aus diesem Beispiel lautet wie folgt:

Allocated length: 0
Allocated length: 103

CSimpleStringT::PXSTR

Ein Zeiger auf eine Zeichenfolge.

Syntax

typedef ChTraitsBase< BaseType >::PXSTR PXSTR;

CSimpleStringT::ReleaseBuffer

Gibt die Steuerung des puffers frei, der von GetBuffer.

Syntax

void ReleaseBuffer(int nNewLength = -1);

Parameter

nNewLength
Die neue Länge der Zeichenfolge in Zeichen, ohne einen Null-Terminator zu zählen. Wenn die Zeichenfolge null beendet ist, legt der Standardwert -1 die CSimpleStringT Größe auf die aktuelle Länge der Zeichenfolge fest.

Hinweise

Rufen Sie diese Methode auf, um den Puffer des Zeichenfolgenobjekts neu zu verlagern oder freizugeben. Wenn Sie wissen, dass die Zeichenfolge im Puffer null beendet ist, können Sie das nNewLength Argument weglassen. Wenn die Zeichenfolge nicht null beendet ist, geben Sie nNewLength die Länge an. Die zurückgegebene GetBuffer Adresse ist nach dem Aufruf ReleaseBuffer oder einem anderen CSimpleStringT Vorgang ungültig.

Beispiel

Das folgende Beispiel veranschaulicht die Verwendung von 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

CSimpleStringT::ReleaseBufferSetLength

Gibt die Steuerung des puffers frei, der von GetBuffer.

Syntax

void ReleaseBufferSetLength(int nNewLength);

Parameter

nNewLength
Die Länge der Zeichenfolge, die freigegeben wird

Hinweise

Diese Funktion ähnelt ReleaseBuffer funktional, mit der Ausnahme, dass eine gültige Länge für das Zeichenfolgenobjekt übergeben werden muss.

CSimpleStringT::SetAt

Legt ein einzelnes Zeichen aus einem CSimpleStringT Objekt fest.

Syntax

void SetAt(int iChar, XCHAR ch);

Parameter

iChar
Nullbasierter Index des Zeichens im CSimpleStringT Objekt. Der iChar Parameter muss größer oder gleich 0 und kleiner als der wert sein, der von GetLength.

ch
Das neue Zeichen.

Hinweise

Rufen Sie diese Methode auf, um das Zeichen zu überschreiben, das sich in iChar. Diese Methode vergrößert die Zeichenfolge nicht, wenn iChar die Grenzen der vorhandenen Zeichenfolge überschritten werden.

Beispiel

Das folgende Beispiel veranschaulicht die Verwendung von CSimpleStringT::SetAt.

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

CSimpleStringT::SetManager

Gibt den Speicher-Manager des CSimpleStringT Objekts an.

Syntax

void SetManager(IAtlStringMgr* pStringMgr);

Parameter

pStringMgr
Ein Zeiger auf den neuen Speicher-Manager.

Hinweise

Rufen Sie diese Methode auf, um einen neuen Speicher-Manager anzugeben, der CSimpleStringT vom Objekt verwendet wird. Weitere Informationen zu Speichermanagern und Zeichenfolgenobjekten finden Sie unter Speicherverwaltung und CStringT.

Beispiel

Das folgende Beispiel veranschaulicht die Verwendung von CSimpleStringT::SetManager.

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

CSimpleStringT::SetString

Legt die Zeichenfolge eines CSimpleStringT Objekts fest.

Syntax

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

Parameter

pszSrc
Ein Zeiger auf eine mit Null beendete Zeichenfolge.

nLength
Anzahl der Zeichen in pszSrc.

Hinweise

Kopieren Sie eine Zeichenfolge in das CSimpleStringT Objekt. SetString überschreibt die älteren Zeichenfolgendaten im Puffer.

Beide Versionen überprüfen SetString , ob pszSrc es sich um einen NULL-Zeiger handelt, und wenn dies der Grund ist, wird ein E_INVALIDARG Fehler ausgelöst.

Die 1-Parameter-Version von SetString erwartet, pszSrc dass sie auf eine mit Null beendete Zeichenfolge verweist.

Die Zwei-Parameter-Version von SetString erwartet auch pszSrc , dass es sich um eine null-beendete Zeichenfolge wird. Sie wird als Zeichenfolgenlänge verwendet nLength , es sei denn, es wird zuerst ein Null-Terminator angezeigt.

Die Zwei-Parameter-Version überprüft SetString auch, ob pszSrc auf eine Position im aktuellen Puffer in CSimpleStringT. In diesem Speziellen Fall wird eine Speicherkopiefunktion verwendet, SetString die die Zeichenfolgendaten nicht überschreibt, da sie die Zeichenfolgendaten zurück in den Puffer kopiert.

Beispiel

Das folgende Beispiel veranschaulicht die Verwendung von CSimpleStringT::SetString.

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

CSimpleStringT::StringLength

Gibt die Anzahl der Zeichen in der angegebenen Zeichenfolge zurück.

Syntax

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

Parameter

psz
Ein Zeiger auf eine mit Null beendete Zeichenfolge.

Rückgabewert

Die Anzahl der Zeichen in psz; nicht zählt einen NULL-Terminator.

Hinweise

Rufen Sie diese Methode auf, um die Anzahl der Zeichen in der Zeichenfolge abzurufen, auf die verwiesen wird psz.

Beispiel

Das folgende Beispiel veranschaulicht die Verwendung von CSimpleStringT::StringLength.

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

CSimpleStringT::Truncate

Schneidet die Zeichenfolge auf die neue Länge ab.

Syntax

void Truncate(int nNewLength);

Parameter

nNewLength
Die neue Länge der Zeichenfolge.

Hinweise

Rufen Sie diese Methode auf, um den Inhalt der Zeichenfolge auf die neue Länge zu kürzen.

Hinweis

Dies wirkt sich nicht auf die zugewiesene Länge des Puffers aus. Informationen zum Verringern oder Vergrößern des aktuellen Puffers finden Sie unter FreeExtra und Preallocate.

Beispiel

Das folgende Beispiel veranschaulicht die Verwendung von 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);

Die Ausgabe dieses Beispiels lautet:

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

CSimpleStringT::UnlockBuffer

Entsperrt den Puffer des CSimpleStringT Objekts.

Syntax

void UnlockBuffer() throw();

Hinweise

Rufen Sie diese Methode auf, um die Referenzanzahl der Zeichenfolge auf 1 zurückzusetzen.

Der CSimpleStringT Destruktor ruft automatisch auf UnlockBuffer , um sicherzustellen, dass der Puffer nicht gesperrt ist, wenn der Destruktor aufgerufen wird. Ein Beispiel für diese Methode finden Sie unter LockBuffer.

CSimpleStringT::~CSimpleStringT

Zerstört ein CSimpleStringT -Objekt.

Syntax

~CSimpleStringT() throw();

Hinweise

Rufen Sie diese Methode auf, um das CSimpleStringT Objekt zu zerstören.

Siehe auch

Hierarchiediagramm
ATL/MFC Shared Classes