La classe `CSimpleStringT`

Article
01/30/2024

Cette classe représente un CSimpleStringT objet.

Syntaxe

template <typename BaseType>
class CSimpleStringT

Paramètres

BaseType
Type de caractère de la classe de chaîne. Il peut s'agir d'une des méthodes suivantes :

char (pour les chaînes de caractères ANSI).
wchar_t (pour les chaînes de caractères Unicode).
TCHAR (pour les chaînes de caractères ANSI et Unicode).

Membres

Typedefs publics

Nom	Description
`CSimpleStringT::PCXSTR`	Pointeur vers une chaîne constante.
`CSimpleStringT::PXSTR`	Pointeur vers une chaîne.

Constructeurs publics

Nom	Description
`CSimpleStringT::CSimpleStringT`	Construit des `CSimpleStringT` objets de différentes façons.
`CSimpleStringT::~CSimpleStringT`	Destructeur.

Méthodes publiques

Nom	Description
`CSimpleStringT::Append`	Ajoute un `CSimpleStringT` objet à un objet existant `CSimpleStringT` .
`CSimpleStringT::AppendChar`	Ajoute un caractère à un objet existant `CSimpleStringT` .
`CSimpleStringT::CopyChars`	Copie un caractère ou des caractères dans une autre chaîne.
`CSimpleStringT::CopyCharsOverlapped`	Copie un caractère ou des caractères dans une autre chaîne dans laquelle les mémoires tampons se chevauchent.
`CSimpleStringT::Empty`	Force une chaîne à avoir une longueur de zéro.
`CSimpleStringT::FreeExtra`	Libère toute mémoire supplémentaire précédemment allouée par l’objet de chaîne.
`CSimpleStringT::GetAllocLength`	Récupère la longueur allouée d’un `CSimpleStringT` objet.
`CSimpleStringT::GetAt`	Retourne le caractère à une position donnée.
`CSimpleStringT::GetBuffer`	Retourne un pointeur vers les caractères d’un `CSimpleStringT`.
`CSimpleStringT::GetBufferSetLength`	Retourne un pointeur vers les caractères d’un `CSimpleStringT`, tronqué à la longueur spécifiée.
`CSimpleStringT::GetLength`	Retourne le nombre de caractères d’un `CSimpleStringT` objet.
`CSimpleStringT::GetManager`	Récupère le gestionnaire de mémoire de l’objet `CSimpleStringT` .
`CSimpleStringT::GetString`	Récupère la chaîne de caractères
`CSimpleStringT::IsEmpty`	Teste si un `CSimpleStringT` objet ne contient aucun caractère.
`CSimpleStringT::LockBuffer`	Désactive le comptage des références et protège la chaîne dans la mémoire tampon.
`CSimpleStringT::Preallocate`	Alloue une quantité spécifique de mémoire pour la mémoire tampon de caractères.
`CSimpleStringT::ReleaseBuffer`	Libère le contrôle de la mémoire tampon retournée par `GetBuffer`.
`CSimpleStringT::ReleaseBufferSetLength`	Libère le contrôle de la mémoire tampon retournée par `GetBuffer`.
`CSimpleStringT::SetAt`	Définit un caractère à une position donnée.
`CSimpleStringT::SetManager`	Définit le gestionnaire de mémoire d’un `CSimpleStringT` objet.
`CSimpleStringT::SetString`	Définit la chaîne d’un `CSimpleStringT` objet.
`CSimpleStringT::StringLength`	Retourne le nombre de caractères dans la chaîne spécifiée.
`CSimpleStringT::Truncate`	Tronque la chaîne à une longueur spécifiée.
`CSimpleStringT::UnlockBuffer`	Active le comptage des références et libère la chaîne dans la mémoire tampon.

Opérateurs publics

Nom	Description
`CSimpleStringT::operator PCXSTR`	Accède directement aux caractères stockés dans un `CSimpleStringT` objet sous forme de chaîne de style C.
`CSimpleStringT::operator[]`	Retourne le caractère à une position donnée — substitution d’opérateur pour `GetAt`.
`CSimpleStringT::operator +=`	Concatène une nouvelle chaîne à la fin d’une chaîne existante.
`CSimpleStringT::operator =`	Affecte une nouvelle valeur à un `CSimpleStringT` objet.

Notes

CSimpleStringT est la classe de base pour les différentes classes de chaîne prises en charge par Visual C++. Il offre une prise en charge minimale de la gestion de la mémoire de l’objet de chaîne et de la manipulation de mémoire tampon de base. Pour plus d’objets de chaîne avancés, consultez CStringT Class.

Spécifications

En-tête : atlsimpstr.h

`CSimpleStringT::Append`

Ajoute un CSimpleStringT objet à un objet existant CSimpleStringT .

Syntaxe

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

Paramètres

strSrc
Objet CSimpleStringT à ajouter.

pszSrc
Pointeur vers une chaîne contenant les caractères à ajouter.

nLength
Nombre de caractères à ajouter.

Notes

Appelez cette méthode pour ajouter un objet existant CSimpleStringT à un autre CSimpleStringT objet.

Exemple

L'exemple suivant montre l'utilisation de 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`

Ajoute un caractère à un objet existant CSimpleStringT .

Syntaxe

void AppendChar(XCHAR ch);

Paramètres

ch
Caractère à ajouter

Notes

Appelez cette fonction pour ajouter le caractère spécifié à la fin d’un objet existant CSimpleStringT .

`CSimpleStringT::CopyChars`

Copie un caractère ou des caractères dans un CSimpleStringT objet.

Syntaxe

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

Paramètres

pchDest
Pointeur vers une chaîne de caractères.

nDestLen
Taille de la mémoire tampon de pchDest

pchSrc
Pointeur vers une chaîne contenant les caractères à copier.

nChars
Nombre de pchSrc caractères à copier.

Notes

Appelez cette méthode pour copier des caractères de pchSrc la pchDest chaîne.

Exemple

L'exemple suivant montre l'utilisation de 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);

La sortie de cet exemple est la suivante :

xxxxxxxxxxxxxxxxxxx
Hello world!xxxxxxx

`CSimpleStringT::CopyCharsOverlapped`

Copie un caractère ou des caractères dans un CSimpleStringT objet.

Syntaxe

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

Paramètres

pchDest
Pointeur vers une chaîne de caractères.

pchSrc
Pointeur vers une chaîne contenant les caractères à copier.

nChars
Nombre de pchSrc caractères à copier.

Notes

Appelez cette méthode pour copier des caractères de pchSrc la pchDest chaîne. Contrairement CopyCharsà , CopyCharsOverlapped fournit une méthode sécurisée pour la copie à partir de mémoires tampons de caractères qui peuvent se chevaucher.

Exemple

Consultez l’exemple pour CSimpleStringT::CopyChars, ou le code source pour CSimpleStringT::SetString (situé dans atlsimpstr.h).

`CSimpleStringT::CSimpleStringT`

Construit un objet CSimpleStringT.

Syntaxe

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

Paramètres

strSrc
Objet existant CSimpleStringT à copier dans cet CSimpleStringT objet.

pchSrc
Pointeur vers un tableau de caractères de longueur nLength, non null terminé.

pszSrc
Chaîne terminée par null à copier dans cet CSimpleStringT objet.

nLength
Nombre de caractères dans pch.

pStringMgr
Pointeur vers le gestionnaire de mémoire de l’objet CSimpleStringT . Pour plus d’informations sur IAtlStringMgr la gestion de la mémoire et CSimpleStringTla gestion de la mémoire, consultez Gestion de la mémoire et CStringT.

Notes

Construisez un nouvel CSimpleStringT objet. Étant donné que les constructeurs copient les données d’entrée dans un nouveau stockage alloué, des exceptions de mémoire peuvent se produire.

Exemple

L’exemple suivant illustre l’utilisation d’ATL CSimpleStringT::CSimpleStringT typedef CSimpleString. CSimpleString est une spécialisation couramment utilisée du modèle CSimpleStringTde classe.

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`

Fait de cet CSimpleStringT objet une chaîne vide et libère de la mémoire selon les besoins.

Syntaxe

void Empty() throw();

Notes

Pour plus d’informations, consultez Chaînes : CString Nettoyage des exceptions.

Exemple

L'exemple suivant montre l'utilisation de CSimpleStringT::Empty.

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

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

`CSimpleStringT::FreeExtra`

Libère toute mémoire supplémentaire précédemment allouée par la chaîne, mais n’est plus nécessaire.

Syntaxe

void FreeExtra();

Notes

Cela doit réduire la surcharge de mémoire consommée par l’objet de chaîne. La méthode réalloue la mémoire tampon à la longueur exacte retournée par GetLength.

Exemple

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

La sortie de cet exemple est la suivante :

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`

Récupère la longueur allouée d’un CSimpleStringT objet.

Syntaxe

int GetAllocLength() const throw();

Valeur de retour

Nombre de caractères alloués pour cet objet.

Notes

Appelez cette méthode pour déterminer le nombre de caractères alloués pour cet CSimpleStringT objet. Consultez FreeExtra un exemple d’appel de cette fonction.

`CSimpleStringT::GetAt`

Retourne un caractère d’un CSimpleStringT objet.

Syntaxe

XCHAR GetAt(int iChar) const;

Paramètres

iChar
Index de base zéro du caractère dans l’objet CSimpleStringT . Le iChar paramètre doit être supérieur ou égal à 0 et inférieur à la valeur retournée par GetLength. Sinon, GetAt génère une exception.

Valeur de retour

Qui XCHAR contient le caractère à la position spécifiée dans la chaîne.

Notes

Appelez cette méthode pour renvoyer le caractère spécifié par iChar. L’opérateur d’indice surchargé ([]) est un alias pratique pour GetAt. Le terminateur Null est adressable sans générer d’exception à l’aide GetAtde . Toutefois, elle n’est pas comptabilisée par GetLength, et la valeur retournée est 0.

Exemple

L’exemple suivant montre comment utiliser CSimpleStringT::GetAt.

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

`CSimpleStringT::GetBuffer`

Retourne un pointeur vers la mémoire tampon de caractères interne de l’objet CSimpleStringT .

Syntaxe

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

Paramètres

nMinBufferLength
Nombre minimal de caractères que la mémoire tampon de caractères peut contenir. Cette valeur n’inclut pas d’espace pour un terminateur Null.

Si nMinBufferLength elle est supérieure à la longueur de la mémoire tampon actuelle, GetBuffer détruit la mémoire tampon actuelle, la remplace par une mémoire tampon de la taille demandée et réinitialise le nombre de références d’objet à zéro. Si vous avez déjà appelé LockBuffer cette mémoire tampon, vous perdez le verrou de la mémoire tampon.

Valeur de retour

Pointeur PXSTR vers la mémoire tampon de caractères (null-terminated) de l’objet.

Notes

Appelez cette méthode pour retourner le contenu de la mémoire tampon de l’objet CSimpleStringT . Le retour PXSTR n’est pas une constante et permet donc une modification directe du CSimpleStringT contenu.

Si vous utilisez le pointeur retourné par GetBuffer pour modifier le contenu de la chaîne, vous devez appeler ReleaseBuffer pour mettre à jour l’état interne avant d’utiliser CSimpleStringT d’autres CSimpleStringT méthodes.

L’adresse retournée par GetBuffer peut ne pas être valide après l’appel, ReleaseBuffer car des opérations supplémentaires CSimpleStringT peuvent entraîner la réaffectation de la CSimpleStringT mémoire tampon. La mémoire tampon n’est pas réaffectée si vous ne modifiez pas la longueur du CSimpleStringT.

La mémoire tampon est automatiquement libérée lorsque l’objet CSimpleStringT est détruit.

Si vous effectuez le suivi de la longueur de chaîne vous-même, vous ne devez pas ajouter le caractère null de fin. Toutefois, vous devez spécifier la longueur de chaîne finale lorsque vous relâchez la mémoire tampon avec ReleaseBuffer. Si vous ajoutez un caractère null de fin, vous devez passer -1 (valeur par défaut) pour la longueur. ReleaseBuffer détermine ensuite la longueur de la mémoire tampon.

Si la mémoire est insuffisante pour satisfaire la GetBuffer requête, cette méthode lève un CMemoryException*.

Exemple

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`

Retourne un pointeur vers la mémoire tampon de caractères interne de l’objet CSimpleStringT , tronquer ou augmenter sa longueur si nécessaire pour correspondre exactement à la longueur spécifiée dans nLength.

Syntaxe

PXSTR GetBufferSetLength(int nLength);

Paramètres

nLength
Taille exacte de la mémoire tampon de CSimpleStringT caractères en caractères.

Valeur de retour

Pointeur PXSTR vers la mémoire tampon de caractères (null-terminated) de l’objet.

Notes

Appelez cette méthode pour récupérer une longueur spécifiée de la mémoire tampon interne de l’objet CSimpleStringT . Le pointeur retourné PXSTR n’est pas const et autorise donc la modification directe du CSimpleStringT contenu.

Si vous utilisez le pointeur retourné par GetBufferSetLength pour modifier le contenu de la chaîne, appelez ReleaseBuffer pour mettre à jour l’état interne avant d’utiliser CSimpleStringT d’autres CSimpleStringT méthodes.

L’adresse retournée par GetBufferSetLength peut ne pas être valide après l’appel, ReleaseBuffer car des opérations supplémentaires CSimpleStringT peuvent entraîner la réaffectation de la CSimpleStringT mémoire tampon. La mémoire tampon n’est pas réaffectée si vous ne modifiez pas la longueur du CSimpleStringT.

La mémoire tampon est automatiquement libérée lorsque l’objet CSimpleStringT est détruit.

Si vous effectuez le suivi de la longueur de chaîne vous-même, n’ajoutez pas le caractère null de fin. Vous devez spécifier la longueur de chaîne finale lorsque vous relâchez la mémoire tampon à l’aide ReleaseBufferde . Si vous ajoutez un caractère null de fin lorsque vous appelez ReleaseBuffer, passez -1 (valeur par défaut) pour la longueur à ReleaseBuffer, et ReleaseBuffer effectuez une strlen opération sur la mémoire tampon pour déterminer sa longueur.

Pour plus d’informations sur le comptage des références, consultez les articles suivants :

Gestion des durées de vie des objets via le comptage de références dans le Kit de développement logiciel (SDK) Windows.
Implémentation du comptage de références dans le Kit de développement logiciel (SDK) Windows.
Règles de gestion des nombres de références dans le Kit de développement logiciel (SDK) Windows.

Exemple

L'exemple suivant montre l'utilisation de 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`

Retourne le nombre de caractères dans l’objet CSimpleStringT .

Syntaxe

int GetLength() const throw();

Valeur de retour

Nombre de caractères dans la chaîne.

Notes

Appelez cette méthode pour retourner le nombre de caractères dans l’objet. Le nombre n’inclut pas de terminateur Null.

Pour les jeux de caractères multioctets (MBCS), GetLength compte chaque caractère de 8 bits ; autrement dit, un octet de prospect et de fin dans un caractère multioctet est comptabilisé sous la forme de deux octets. Consultez FreeExtra un exemple d’appel de cette fonction.

`CSimpleStringT::GetManager`

Récupère le gestionnaire de mémoire de l’objet CSimpleStringT .

Syntaxe

IAtlStringMgr* GetManager() const throw();

Valeur de retour

Pointeur vers le gestionnaire de mémoire de l’objet CSimpleStringT .

Notes

Appelez cette méthode pour récupérer le gestionnaire de mémoire utilisé par l’objet CSimpleStringT . Pour plus d’informations sur les gestionnaires de mémoire et les objets de chaîne, consultez Gestion de la mémoire et CStringT.

`CSimpleStringT::GetString`

Récupère la chaîne de caractères.

Syntaxe

PCXSTR GetString() const throw();

Valeur de retour

Pointeur vers une chaîne de caractères terminée par null.

Notes

Appelez cette méthode pour récupérer la chaîne de caractères associée à l’objet CSimpleStringT .

Remarque

Le pointeur retourné PCXSTR est et n’autorise const pas la modification directe du CSimpleStringT contenu.

Exemple

L'exemple suivant montre l'utilisation de CSimpleStringT::GetString.

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

La sortie de cet exemple est la suivante :

Cup soccer is best!

`CSimpleStringT::IsEmpty`

Teste un CSimpleStringT objet pour la condition vide.

Syntaxe

bool IsEmpty() const throw();

Valeur de retour

Retourne TRUE si l’objet CSimpleStringT a 0 longueur ; sinon FALSE.

Notes

Appelez cette méthode pour déterminer si l’objet contient une chaîne vide.

Exemple

L'exemple suivant montre l'utilisation de CSimpleStringT::IsEmpty.

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

`CSimpleStringT::LockBuffer`

Désactive le comptage des références et protège la chaîne dans la mémoire tampon.

Syntaxe

PXSTR LockBuffer();

Valeur de retour

Pointeur vers un CSimpleStringT objet ou une chaîne terminée par null.

Notes

Appelez cette méthode pour verrouiller la mémoire tampon de l’objet CSimpleStringT . En appelant LockBuffer, vous créez une copie de la chaîne, avec un -1 pour le nombre de références. Lorsque la valeur du nombre de références est -1, la chaîne de la mémoire tampon est considérée comme étant dans un état « verrouillé ». Dans un état verrouillé, la chaîne est protégée de deux façons :

Aucune autre chaîne ne peut obtenir une référence aux données de la chaîne verrouillée, même si cette chaîne est affectée à la chaîne verrouillée.
La chaîne verrouillée ne référencera jamais une autre chaîne, même si cette autre chaîne est copiée dans la chaîne verrouillée.

En verrouillant la chaîne dans la mémoire tampon, vous vérifiez que la conservation exclusive de la chaîne sur la mémoire tampon reste intacte.

Une fois que vous avez terminé, LockBufferappelez UnlockBuffer pour réinitialiser le nombre de références à 1.

Remarque

Si vous appelez GetBuffer une mémoire tampon verrouillée et que vous définissez le GetBuffer paramètre nMinBufferLength sur une longueur supérieure à la longueur de la mémoire tampon actuelle, vous perdez le verrou de la mémoire tampon. Un tel appel pour GetBuffer détruire la mémoire tampon actuelle, le remplace par une mémoire tampon de la taille demandée et réinitialise le nombre de références à zéro.

Pour plus d’informations sur le comptage des références, consultez les articles suivants :

Gestion des durées de vie des objets via le comptage de références dans le Kit de développement logiciel (SDK) Windows
Implémentation du comptage de références dans le Kit de développement logiciel (SDK) Windows
Règles de gestion des nombres de références dans le Kit de développement logiciel (SDK) Windows

Exemple

L'exemple suivant montre l'utilisation de 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();

La sortie de cet exemple est la suivante :

`CSimpleStringT::operator[]`

Appelez cette fonction pour accéder à un caractère unique du tableau de caractères.

Syntaxe

XCHAR operator[](int iChar) const;

Paramètres

iChar
Index de base zéro d’un caractère dans la chaîne.

Notes

L’opérateur d’indice[] surchargé () retourne un caractère unique spécifié par l’index de base zéro dans iChar. Cet opérateur est un substitut pratique à la GetAt fonction membre.

Remarque

Vous pouvez utiliser l’opérateur d’indice ([]) pour obtenir la valeur d’un caractère dans un CSimpleStringT, mais vous ne pouvez pas l’utiliser pour modifier la valeur d’un caractère dans un CSimpleStringT.

Exemple

L'exemple suivant montre l'utilisation de CSimpleStringT::operator [].

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

`CSimpleStringT::operator []`

Appelez cette fonction pour accéder à un caractère unique du tableau de caractères.

Syntaxe

XCHAR operator[](int iChar) const;

Paramètres

iChar
Index de base zéro d’un caractère dans la chaîne.

Notes

Remarque

`CSimpleStringT::operator +=`

Joint une nouvelle chaîne ou un caractère à la fin d’une chaîne existante.

Syntaxe

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

Paramètres

pszSrc
Pointeur vers une chaîne terminée par null.

strSrc
Pointeur vers un objet existant CSimpleStringT .

ch
Caractère à ajouter.

Notes

L’opérateur accepte un autre CSimpleStringT objet ou un caractère. Notez que des exceptions de mémoire peuvent se produire chaque fois que vous utilisez cet opérateur de concaténation, car le nouveau stockage peut être alloué pour les caractères ajoutés à cet CSimpleStringT objet.

Exemple

L'exemple suivant montre l'utilisation de CSimpleStringT::operator +=.

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

`CSimpleStringT::operator =`

Affecte une nouvelle valeur à un CSimpleStringT objet.

Syntaxe

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

Paramètres

pszSrc
Pointeur vers une chaîne terminée par null.

strSrc
Pointeur vers un objet existant CSimpleStringT .

Notes

Si la chaîne de destination (côté gauche) est déjà assez grande pour stocker les nouvelles données, aucune nouvelle allocation de mémoire n’est effectuée. Notez que les exceptions de mémoire peuvent se produire chaque fois que vous utilisez l’opérateur d’affectation, car le nouveau stockage est souvent alloué pour contenir l’objet résultant CSimpleStringT .

Exemple

L'exemple suivant montre l'utilisation de 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`

Accède directement aux caractères stockés dans un CSimpleStringT objet sous forme de chaîne de style C.

Syntaxe

operator PCXSTR() const throw();

Valeur de retour

Pointeur de caractères vers les données de la chaîne.

Notes

Aucun caractère n’est copié ; seul un pointeur est retourné. Soyez prudent avec cet opérateur. Si vous modifiez un CString objet après avoir obtenu le pointeur de caractère, vous pouvez provoquer une réaffectation de la mémoire qui invalide le pointeur.

Exemple

L'exemple suivant montre l'utilisation de 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`

Pointeur vers une chaîne constante.

Syntaxe

typedef ChTraitsBase< BaseType >::PCXSTR PCXSTR;

`CSimpleStringT::Preallocate`

Alloue une quantité spécifique d’octets pour l’objet CSimpleStringT .

Syntaxe

void Preallocate( int nLength);

Paramètres

nLength
Taille exacte de la mémoire tampon de CSimpleStringT caractères en caractères.

Notes

Appelez cette méthode pour allouer une taille de mémoire tampon spécifique pour l’objet CSimpleStringT .

CSimpleStringT génère une exception s’il n’est pas en mesure d’allouer de STATUS_NO_MEMORY l’espace pour la mémoire tampon de caractères. Par défaut, l’allocation de mémoire est effectuée par les fonctions HeapAlloc d’API WIN32 ou HeapReAlloc.

Exemple

L'exemple suivant montre l'utilisation de 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());

La sortie de cet exemple est la suivante :

Allocated length: 0
Allocated length: 103

`CSimpleStringT::PXSTR`

Pointeur vers une chaîne.

Syntaxe

typedef ChTraitsBase< BaseType >::PXSTR PXSTR;

`CSimpleStringT::ReleaseBuffer`

Libère le contrôle de la mémoire tampon allouée par GetBuffer.

Syntaxe

void ReleaseBuffer(int nNewLength = -1);

Paramètres

nNewLength
Nouvelle longueur de la chaîne en caractères, sans compter un terminateur Null. Si la chaîne est terminée par null, la valeur par défaut -1 définit la taille sur la CSimpleStringT longueur actuelle de la chaîne.

Notes

Appelez cette méthode pour libérer ou libérer la mémoire tampon de l’objet chaîne. Si vous savez que la chaîne dans la mémoire tampon est terminée par null, vous pouvez omettre l’argument nNewLength . Si votre chaîne n’est pas terminée par null, utilisez nNewLength cette option pour spécifier sa longueur. L’adresse retournée par GetBuffer n’est pas valide après l’appel à ReleaseBuffer ou toute autre CSimpleStringT opération.

Exemple

L'exemple suivant montre l'utilisation de 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`

Libère le contrôle de la mémoire tampon allouée par GetBuffer.

Syntaxe

void ReleaseBufferSetLength(int nNewLength);

Paramètres

nNewLength
Longueur de la chaîne libérée

Notes

Cette fonction est fonctionnellement similaire à celle ReleaseBuffer d’une longueur valide pour l’objet de chaîne.

`CSimpleStringT::SetAt`

Définit un caractère unique à partir d’un CSimpleStringT objet.

Syntaxe

void SetAt(int iChar, XCHAR ch);

Paramètres

iChar
Index de base zéro du caractère dans l’objet CSimpleStringT . Le iChar paramètre doit être supérieur ou égal à 0 et inférieur à la valeur retournée par GetLength.

ch
Nouveau caractère.

Notes

Appelez cette méthode pour remplacer le caractère situé à l’emplacement iChar. Cette méthode n’agrandit pas la chaîne si iChar elle dépasse les limites de la chaîne existante.

Exemple

L'exemple suivant montre l'utilisation de CSimpleStringT::SetAt.

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

`CSimpleStringT::SetManager`

Spécifie le gestionnaire de mémoire de l’objet CSimpleStringT .

Syntaxe

void SetManager(IAtlStringMgr* pStringMgr);

Paramètres

pStringMgr
Pointeur vers le nouveau gestionnaire de mémoire.

Notes

Appelez cette méthode pour spécifier un nouveau gestionnaire de mémoire utilisé par l’objet CSimpleStringT . Pour plus d’informations sur les gestionnaires de mémoire et les objets de chaîne, consultez Gestion de la mémoire et CStringT.

Exemple

L'exemple suivant montre l'utilisation de CSimpleStringT::SetManager.

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

`CSimpleStringT::SetString`

Définit la chaîne d’un CSimpleStringT objet.

Syntaxe

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

Paramètres

pszSrc
Pointeur vers une chaîne terminée par null.

nLength
Nombre de caractères dans pszSrc.

Notes

Copiez une chaîne dans l’objet CSimpleStringT . SetString remplace les données de chaîne plus anciennes dans la mémoire tampon.

Les deux versions de SetString vérification indiquent s’il pszSrc s’agit d’un pointeur Null et, le cas échéant, lèvent une E_INVALIDARG erreur.

La version un paramètre de s’attend SetString pszSrc à pointer vers une chaîne terminée par null.

La version à deux paramètres de SetString s’attend pszSrc également à être une chaîne terminée par null. Il utilise nLength comme longueur de chaîne, sauf s’il rencontre d’abord un terminateur Null.

La version à deux paramètres de SetString vérifie également si pszSrc un emplacement pointe vers un emplacement dans la mémoire tampon actuelle dans CSimpleStringT. Dans ce cas spécial, SetString utilise une fonction de copie de mémoire qui ne remplace pas les données de chaîne, car elle copie les données de chaîne dans sa mémoire tampon.

Exemple

L'exemple suivant montre l'utilisation de 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`

Retourne le nombre de caractères dans la chaîne spécifiée.

Syntaxe

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

Paramètres

psz
Pointeur vers une chaîne terminée par null.

Valeur de retour

Nombre de caractères dans psz; sans compter un terminateur Null.

Notes

Appelez cette méthode pour récupérer le nombre de caractères dans la chaîne pointée par psz.

Exemple

L'exemple suivant montre l'utilisation de CSimpleStringT::StringLength.

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

`CSimpleStringT::Truncate`

Tronque la chaîne à la nouvelle longueur.

Syntaxe

void Truncate(int nNewLength);

Paramètres

nNewLength
Nouvelle longueur de la chaîne.

Notes

Appelez cette méthode pour tronquer le contenu de la chaîne à la nouvelle longueur.

Remarque

Cela n’affecte pas la longueur allouée de la mémoire tampon. Pour diminuer ou augmenter la mémoire tampon actuelle, consultez FreeExtra et Preallocate.

Exemple

L'exemple suivant montre l'utilisation de 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);

La sortie de cet exemple est :

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

`CSimpleStringT::UnlockBuffer`

Déverrouille la mémoire tampon de l’objet CSimpleStringT .

Syntaxe

void UnlockBuffer() throw();

Notes

Appelez cette méthode pour réinitialiser le nombre de références de la chaîne à 1.

Le CSimpleStringT destructeur appelle UnlockBuffer automatiquement pour s’assurer que la mémoire tampon n’est pas verrouillée lorsque le destructeur est appelé. Pour obtenir un exemple de cette méthode, consultez LockBuffer.

`CSimpleStringT::~CSimpleStringT`

Détruit un objet CSimpleStringT .

Syntaxe

~CSimpleStringT() throw();

Notes

Appelez cette méthode pour détruire l’objet CSimpleStringT .

Voir aussi

Graphique hiérarchique
Classes partagées ATL/MFC

Partager via

La classe CSimpleStringT

Syntaxe

Paramètres

Membres

Typedefs publics

Constructeurs publics

Méthodes publiques

Opérateurs publics

Notes

Spécifications

CSimpleStringT::Append

Syntaxe

Paramètres

Notes

Exemple

CSimpleStringT::AppendChar

Syntaxe

Paramètres

Notes

CSimpleStringT::CopyChars

Syntaxe

Paramètres

Notes

Exemple

CSimpleStringT::CopyCharsOverlapped

Syntaxe

Paramètres

Notes

Exemple

CSimpleStringT::CSimpleStringT

Syntaxe

Paramètres

Notes

Exemple

CSimpleStringT::Empty

Syntaxe

Notes

Exemple

CSimpleStringT::FreeExtra

Syntaxe

Notes

Exemple

CSimpleStringT::GetAllocLength

Syntaxe

Valeur de retour

Notes

CSimpleStringT::GetAt

Syntaxe

Paramètres

Valeur de retour

Notes

Exemple

CSimpleStringT::GetBuffer

Syntaxe

Paramètres

Valeur de retour

Notes

Exemple

CSimpleStringT::GetBufferSetLength

Syntaxe

Paramètres

Valeur de retour

Notes

Exemple

CSimpleStringT::GetLength

Syntaxe

Valeur de retour

Notes

CSimpleStringT::GetManager

Syntaxe

Valeur de retour

Notes

CSimpleStringT::GetString

Syntaxe

Valeur de retour

Notes

Exemple

CSimpleStringT::IsEmpty

Syntaxe

La classe `CSimpleStringT`

`CSimpleStringT::Append`

`CSimpleStringT::AppendChar`

`CSimpleStringT::CopyChars`

`CSimpleStringT::CopyCharsOverlapped`

`CSimpleStringT::CSimpleStringT`

`CSimpleStringT::Empty`

`CSimpleStringT::FreeExtra`

`CSimpleStringT::GetAllocLength`

`CSimpleStringT::GetAt`

`CSimpleStringT::GetBuffer`

`CSimpleStringT::GetBufferSetLength`

`CSimpleStringT::GetLength`

`CSimpleStringT::GetManager`

`CSimpleStringT::GetString`

`CSimpleStringT::IsEmpty`

`CSimpleStringT::LockBuffer`

`CSimpleStringT::operator[]`

`CSimpleStringT::operator []`

`CSimpleStringT::operator +=`

`CSimpleStringT::operator =`

`CSimpleStringT::operator PCXSTR`

`CSimpleStringT::PCXSTR`

`CSimpleStringT::Preallocate`

`CSimpleStringT::PXSTR`

`CSimpleStringT::ReleaseBuffer`

`CSimpleStringT::ReleaseBufferSetLength`

`CSimpleStringT::SetAt`

`CSimpleStringT::SetManager`

`CSimpleStringT::SetString`

`CSimpleStringT::StringLength`