Classe `CSimpleStringT`

Artigo
01/26/2024

Essa classe representa um objeto CSimpleStringT.

Sintaxe

template <typename BaseType>
class CSimpleStringT

Parâmetros

BaseType
O tipo de caractere da classe de cadeia de caracteres. Um dos seguintes pode ser feito:

char (para cadeia de caracteres ANSI).
wchar_t (para cadeia de caracteres Unicode).
TCHAR (para cadeia de caracteres Unicode e ANSI).

Membros

Typedefs públicos

Nome	Descrição
`CSimpleStringT::PCXSTR`	Um ponteiro para uma cadeia de caracteres constante.
`CSimpleStringT::PXSTR`	Um ponteiro para uma cadeia de caracteres.

Construtores públicos

Nome	Descrição
`CSimpleStringT::CSimpleStringT`	Constrói objetos `CSimpleStringT` de várias maneiras.
`CSimpleStringT::~CSimpleStringT`	Destruidor.

Métodos públicos

Nome	Descrição
`CSimpleStringT::Append`	Acrescenta um objeto `CSimpleStringT` a um objeto `CSimpleStringT` existente.
`CSimpleStringT::AppendChar`	Acrescenta um caractere a um objeto `CSimpleStringT` existente.
`CSimpleStringT::CopyChars`	Copia um caractere ou caracteres em outra cadeia de caracteres.
`CSimpleStringT::CopyCharsOverlapped`	Copia um caractere ou caracteres em outra cadeia de caracteres na qual os buffers se sobrepõem.
`CSimpleStringT::Empty`	Força uma cadeia de caracteres a ter um comprimento de zero.
`CSimpleStringT::FreeExtra`	Libera qualquer memória extra alocada anteriormente pelo objeto de cadeia de caracteres.
`CSimpleStringT::GetAllocLength`	Recupera o comprimento alocado de um objeto `CSimpleStringT`.
`CSimpleStringT::GetAt`	Retorna o caractere em uma determinada posição.
`CSimpleStringT::GetBuffer`	Retorna um ponteiro para os caracteres em um `CSimpleStringT`.
`CSimpleStringT::GetBufferSetLength`	Retorna um ponteiro para os caracteres em um `CSimpleStringT`, truncando no comprimento especificado.
`CSimpleStringT::GetLength`	Retorna o número de caracteres em um objeto `CSimpleStringT`.
`CSimpleStringT::GetManager`	Recupera o gerenciador de memória do objeto `CSimpleStringT`.
`CSimpleStringT::GetString`	Recupera a cadeia de caracteres
`CSimpleStringT::IsEmpty`	Testa se um objeto `CSimpleStringT` não contém caracteres.
`CSimpleStringT::LockBuffer`	Desabilita a contagem de referências e protege a cadeia de caracteres no buffer.
`CSimpleStringT::Preallocate`	Aloca uma quantidade específica de memória para o buffer de caracteres.
`CSimpleStringT::ReleaseBuffer`	Libera o controle do buffer retornado por `GetBuffer`.
`CSimpleStringT::ReleaseBufferSetLength`	Libera o controle do buffer retornado por `GetBuffer`.
`CSimpleStringT::SetAt`	Define um caractere em uma determinada posição.
`CSimpleStringT::SetManager`	Define o gerenciador de memória de um objeto `CSimpleStringT`.
`CSimpleStringT::SetString`	Define uma cadeia de caracteres de um objeto `CSimpleStringT`.
`CSimpleStringT::StringLength`	Retorna o número de caracteres na cadeia de caracteres especificada.
`CSimpleStringT::Truncate`	Trunca a cadeia de caracteres no comprimento especificado.
`CSimpleStringT::UnlockBuffer`	Habilita a contagem de referências e libera a cadeia de caracteres no buffer.

Operadores públicos

Nome	Descrição
`CSimpleStringT::operator PCXSTR`	Acessa diretamente caracteres armazenados em um objeto `CSimpleStringT` como uma cadeia de caracteres no estilo C.
`CSimpleStringT::operator[]`	Retorna o caractere em uma determinada posição – substituição do operador para `GetAt`.
`CSimpleStringT::operator +=`	Concatena uma nova cadeia de caracteres até o final de uma cadeia de caracteres existente.
`CSimpleStringT::operator =`	Atribui um novo valor a um objeto `CSimpleStringT`.

Comentários

CSimpleStringT é a classe base para as várias classes de cadeia de caracteres compatíveis com o Visual C++. Ele fornece suporte mínimo para o gerenciamento de memória do objeto de cadeia de caracteres e manipulação básica do buffer. Para obter objetos de cadeia de caracteres mais avançados, confira CStringT Class.

Requisitos

Cabeçalho: atlsimpstr.h

`CSimpleStringT::Append`

Acrescenta um objeto CSimpleStringT a um objeto CSimpleStringT existente.

Sintaxe

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

Parâmetros

strSrc
O objeto CSimpleStringT a ser acrescentado.

pszSrc
Um ponteiro para uma cadeia de caracteres que contém os caracteres de destino a serem acrescentados.

nLength
O número de caracteres a serem acrescentados.

Comentários

Chame esse método para acrescentar um objeto CSimpleStringT existente a outro objeto CSimpleStringT.

Exemplo

O exemplo a seguir demonstra o uso 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`

Acrescenta um caractere a um objeto CSimpleStringT existente.

Sintaxe

void AppendChar(XCHAR ch);

Parâmetros

ch
O caractere a ser acrescentado

Comentários

Chame essa função para acrescentar o caractere especificado ao final de um objeto CSimpleStringT existente.

`CSimpleStringT::CopyChars`

Copia um caractere ou caracteres em um objeto CSimpleStringT.

Sintaxe

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

Parâmetros

pchDest
Um ponteiro para uma cadeia de caracteres.

nDestLen
Tamanho do buffer de pchDest

pchSrc
Um ponteiro para uma cadeia de caracteres que contém os caracteres a serem copiados.

nChars
O número de caracteres pchSrc a serem copiados.

Comentários

Chame esse método para copiar caracteres da cadeia de caracteres pchSrc para pchDest.

Exemplo

O exemplo a seguir demonstra o uso 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);

A saída desse exemplo é a seguinte:

xxxxxxxxxxxxxxxxxxx
Hello world!xxxxxxx

`CSimpleStringT::CopyCharsOverlapped`

Copia um caractere ou caracteres em um objeto CSimpleStringT.

Sintaxe

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

Parâmetros

pchDest
Um ponteiro para uma cadeia de caracteres.

pchSrc
Um ponteiro para uma cadeia de caracteres que contém os caracteres a serem copiados.

nChars
O número de caracteres pchSrc a serem copiados.

Comentários

Chame esse método para copiar caracteres da cadeia de caracteres pchSrc para pchDest. Diferentemente de CopyChars, CopyCharsOverlapped fornece um método seguro para copiar de buffers de caracteres que podem ser sobrepostos.

Exemplo

Consulte o exemplo de CSimpleStringT::CopyChars, ou o código-fonte para CSimpleStringT::SetString (localizado em atlsimpstr.h).

`CSimpleStringT::CSimpleStringT`

Constrói um objeto CSimpleStringT.

Sintaxe

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

Parâmetros

strSrc
Um objeto CSimpleStringT existente a ser copiado nesse objeto CSimpleStringT.

pchSrc
Um ponteiro para uma matriz de caracteres de tamanho nLength, que não termina em nulo.

pszSrc
Uma cadeia de caracteres terminada em nulo a ser copiada para nesse objeto CSimpleStringT.

nLength
Uma contagem do número de caracteres em pch.

pStringMgr
Um ponteiro para o gerenciador de memória do objeto CSimpleStringT. Para obter mais informações sobre IAtlStringMgr e gerenciamento de memória de CSimpleStringT, confira Gerenciamento de memória e CStringT.

Comentários

Construa um novo objeto CSimpleStringT. Como os construtores copiam os dados de entrada em um novo armazenamento alocado, podem ocorrer exceções de memória.

Exemplo

O exemplo a seguir demonstra o uso do CSimpleStringT::CSimpleStringT usando o ATL typedef CSimpleString. CSimpleString é uma especialização comumente usada do modelo de classe 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`

Torna esse objeto CSimpleStringT uma cadeia de caracteres vazia e libera a memória conforme apropriado.

Sintaxe

void Empty() throw();

Comentários

Para obter mais informações, confira Cadeias de caracteres: limpeza de exceção CString.

Exemplo

O exemplo a seguir demonstra o uso de CSimpleStringT::Empty.

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

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

`CSimpleStringT::FreeExtra`

Libera qualquer memória extra alocada anteriormente pela cadeia de caracteres que não é mais necessária.

Sintaxe

void FreeExtra();

Comentários

Isso deve reduzir a sobrecarga de memória consumida pelo objeto da cadeia de caracteres. O método realoca o buffer para o comprimento exato retornado por GetLength.

Exemplo

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

A saída desse exemplo é a seguinte:

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`

Recupera o comprimento alocado de um objeto CSimpleStringT.

Sintaxe

int GetAllocLength() const throw();

Valor retornado

O número de caracteres alocados para esse objeto.

Comentários

Chame esse método para determinar o número de caracteres alocados para esse objeto CSimpleStringT. Confira FreeExtra para um exemplo de como chamar essa função.

`CSimpleStringT::GetAt`

Retorna um caractere de um objeto CSimpleStringT.

Sintaxe

XCHAR GetAt(int iChar) const;

Parâmetros

iChar
Índice baseado em zero do caractere no objeto CSimpleStringT. O parâmetro iChar deve ser maior ou igual a 0 e menor que o valor retornado por GetLength. Caso contrário, GetAt gerará uma exceção.

Valor de retorno

Um XCHAR que contém o caractere na posição especificada na cadeia de caracteres.

Comentários

Chame esse método para retornar um caractere especificado por iChar. O operador subscrito sobrecarregado ([]) é um alias conveniente para GetAt. O terminador nulo é endereçável sem gerar uma exceção usando GetAt. No entanto, ele não é contado por GetLength, e o valor retornado é 0.

Exemplo

O exemplo a seguir demonstra como usar CSimpleStringT::GetAt.

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

`CSimpleStringT::GetBuffer`

Retorna um ponteiro para o buffer de caracteres interno do objeto CSimpleStringT.

Sintaxe

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

Parâmetros

nMinBufferLength
O número mínimo de caracteres que o buffer de caracteres pode conter. Esse valor não inclui espaço para um terminador nulo.

Se nMinBufferLength for maior que o comprimento do buffer atual, GetBuffer destruirá o buffer atual, e ele será substituído por um buffer do tamanho solicitado e a contagem de referência de objeto será redefinida como zero. Se já tiver chamado LockBuffer nesse buffer, você perderá o bloqueio do buffer.

Valor de retorno

Um ponteiro PXSTR para o buffer de caracteres do objeto (com terminação nula).

Comentários

Chame esse método para retornar o conteúdo do buffer do objeto CSimpleStringT. O PXSTR retornado não é uma constante e, portanto, permite modificação direta do conteúdo CSimpleStringT.

Se você usar o ponteiro retornado por GetBuffer para alterar o conteúdo da cadeia de caracteres, deverá chamar ReleaseBuffer para atualizar o estado interno de antes de CSimpleStringT usar qualquer outro CSimpleStringT método.

O endereço retornado por GetBuffer pode não ser válido após a chamada para ReleaseBuffer porque operações CSimpleStringT adicionais podem fazer com que o buffer CSimpleStringT seja realocado. O buffer não será realocado se você não alterar o comprimento de CSimpleStringT.

A memória do buffer é liberada automaticamente quando o objeto CSimpleStringT é destruído.

Se você controlar o comprimento da cadeia de caracteres, não acrescente o caractere nulo de terminação. No entanto, você deve especificar o comprimento final da cadeia de caracteres ao liberar o buffer com ReleaseBuffer. Se você acrescentar um caractere nulo de terminação, deverá passar -1 (o padrão) para o comprimento. ReleaseBuffer determina o comprimento do buffer.

Se não houver memória suficiente para atender à solicitação GetBuffer, esse método gerará um CMemoryException*.

Exemplo

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`

Retorna um ponteiro para o buffer de caracteres interno para o objeto CSimpleStringT, truncando ou aumentando seu comprimento, se necessário, para corresponder exatamente ao comprimento especificado em nLength.

Sintaxe

PXSTR GetBufferSetLength(int nLength);

Parâmetros

nLength
O tamanho exato do buffer de caracteres CSimpleStringT em caracteres.

Valor de retorno

Um ponteiro PXSTR para o buffer de caracteres do objeto (com terminação nula).

Comentários

Chame esse método para recuperar um comprimento especificado do buffer interno do objeto CSimpleStringT. O ponteiro PXSTR retornado não é const e, portanto, permite modificação direta do conteúdo CSimpleStringT.

Se você usar o ponteiro retornado por GetBufferSetLength para alterar o conteúdo da cadeia de caracteres, chame ReleaseBuffer para atualizar o estado interno de CSimpleStringT antes de usar outros métodos CSimpleStringT.

O endereço retornado por GetBufferSetLength pode não ser válido após a chamada para ReleaseBuffer porque operações CSimpleStringT adicionais podem fazer com que o buffer CSimpleStringT seja realocado. O buffer não será reatribuído se você não alterar o comprimento de CSimpleStringT.

A memória do buffer é liberada automaticamente quando o objeto CSimpleStringT é destruído.

Se você controlar o comprimento da cadeia de caracteres, não acrescente o caractere nulo de terminação. Você deve especificar o comprimento final da cadeia de caracteres ao liberar o buffer usando ReleaseBuffer. Se você acrescentar um caractere nulo de terminação ao chamar ReleaseBuffer, passe -1 (o padrão) para o comprimento para ReleaseBuffer, e ReleaseBuffer executará um strlen no buffer para determinar seu comprimento.

Para obter mais informações sobre a contagem de referências, confira os seguintes artigos:

Gerenciamento de tempos de vida do objeto por meio da contagem de referências no SDK do Windows.
Implementar a contagem de referências no SDK do Windows.
Regras para gerenciar as contagens de referências no SDK do Windows.

Exemplo

O exemplo a seguir demonstra o uso 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`

Retorna o número de caracteres no objeto CSimpleStringT.

Sintaxe

int GetLength() const throw();

Valor retornado

Uma contagem dos caracteres na cadeia de caracteres.

Comentários

Chame esse método para retornar o número de caracteres no objeto. A contagem não inclui um terminador nulo.

Para MBCS (conjuntos de caracteres multibyte), GetLength refere-se a cada caractere de 8 bits. Ou seja, um byte à direita e um byte à esquerda em um caractere multibyte são contados como dois bytes. Confira FreeExtra para um exemplo de como chamar essa função.

`CSimpleStringT::GetManager`

Recupera o gerenciador de memória do objeto CSimpleStringT.

Sintaxe

IAtlStringMgr* GetManager() const throw();

Valor retornado

Um ponteiro para o gerenciador de memória do objeto CSimpleStringT.

Comentários

Chame esse método para recuperar o gerenciador de memória usado pelo objeto CSimpleStringT. Para obter mais informações sobre gerenciadores de memória e objetos de cadeia de caracteres, confira Gerenciamento de memória e CStringT.

`CSimpleStringT::GetString`

Recupera a cadeia de caracteres.

Sintaxe

PCXSTR GetString() const throw();

Valor retornado

Um ponteiro para uma cadeia de caracteres terminada em nulo.

Comentários

Chame esse método para recuperar a cadeia de caracteres associada ao objeto CSimpleStringT.

Observação

O ponteiro PCXSTR retornado é const e não permite modificação direta do conteúdo CSimpleStringT.

Exemplo

O exemplo a seguir demonstra o uso de CSimpleStringT::GetString.

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

A saída desse exemplo é a seguinte:

Cup soccer is best!

`CSimpleStringT::IsEmpty`

Testa um objeto CSimpleStringT quanto a condição vazia.

Sintaxe

bool IsEmpty() const throw();

Valor retornado

Retorna TRUE se o objeto CSimpleStringT tiver comprimento 0. Caso contrário, FALSE.

Comentários

Chame esse método para determinar se o objeto contém uma cadeia de caracteres vazia.

Exemplo

O exemplo a seguir demonstra o uso de CSimpleStringT::IsEmpty.

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

`CSimpleStringT::LockBuffer`

Desabilita a contagem de referências e protege a cadeia de caracteres no buffer.

Sintaxe

PXSTR LockBuffer();

Valor retornado

Um ponteiro para um objeto CSimpleStringT ou uma cadeia de caracteres terminada em nulo.

Comentários

Chame esse método para bloquear o buffer do objeto CSimpleStringT. Ao chamar LockBuffer, você cria uma cópia da cadeia de caracteres, com um -1 para a contagem de referência. Quando o valor da contagem de referência é -1, a cadeia de caracteres no buffer é considerada em um estado "bloqueado". Enquanto estiver em um estado bloqueado, a cadeia de caracteres é protegida de duas maneiras:

Nenhuma outra cadeia de caracteres pode obter uma referência aos dados na cadeia de caracteres bloqueada, mesmo que essa cadeia de caracteres seja atribuída à cadeia de caracteres bloqueada.
A cadeia de caracteres bloqueada nunca fará referência a outra cadeia de caracteres, mesmo que essa outra cadeia de caracteres seja copiada na cadeia de caracteres bloqueada.

Ao bloquear a cadeia de caracteres no buffer, você garante que a retenção exclusiva da cadeia de caracteres no buffer permanecerá intacta.

Depois de terminar com LockBuffer, chame UnlockBuffer para redefinir a contagem de referências para 1.

Observação

Se você chamar GetBuffer em um buffer bloqueado e definir o parâmetro GetBuffer nMinBufferLength como maior que o comprimento do buffer atual, perderá o bloqueio de buffer. Essa chamada para GetBuffer destrói o buffer atual, faz a substituição dele por um buffer do tamanho solicitado e redefine a contagem de referências como zero.

Para obter mais informações sobre a contagem de referências, confira os seguintes artigos:

Gerenciamento de tempos de vida do objeto por meio da contagem de referências no SDK do Windows
Implementar a contagem de referências no SDK do Windows
Regras para gerenciar as contagens de referências no SDK do Windows

Exemplo

O exemplo a seguir demonstra o uso 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();

A saída desse exemplo é a seguinte:

`CSimpleStringT::operator[]`

Chame essa função para acessar um único caractere da matriz de caracteres.

Sintaxe

XCHAR operator[](int iChar) const;

Parâmetros

iChar
Índice baseado em zero de um caractere na cadeia de caracteres.

Comentários

O operador subscrito sobrecarregado ([]) retorna um único caractere especificado pelo índice baseado em zero em iChar. Esse operador é um substituto conveniente para a função de membro GetAt.

Observação

Você pode usar o operador subscrito ([]) para obter o valor de um caractere em um CSimpleStringT, mas não pode usá-lo para alterar o valor de um caractere em um CSimpleStringT.

Exemplo

O exemplo a seguir demonstra o uso de CSimpleStringT::operator [].

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

`CSimpleStringT::operator []`

Chame essa função para acessar um único caractere da matriz de caracteres.

Sintaxe

XCHAR operator[](int iChar) const;

Parâmetros

iChar
Índice baseado em zero de um caractere na cadeia de caracteres.

Comentários

Observação

Você pode usar o operador subscrito ([]) para obter o valor de um caractere em um CSimpleStringT, mas não pode usá-lo para alterar o valor de um caractere em um CSimpleStringT.

`CSimpleStringT::operator +=`

Une uma nova cadeia de caracteres ou caractere ao final de uma cadeia de caracteres existente.

Sintaxe

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

Parâmetros

pszSrc
Um ponteiro para uma cadeia de caracteres terminada em nulo.

strSrc
Um ponteiro para um objeto CSimpleStringT existente.

ch
O caractere a ser acrescentado.

Comentários

O operador aceita outro objeto CSimpleStringT ou um caractere. Observe que exceções de memória poderão ocorrer sempre que você usar esse operador de concatenação porque o novo armazenamento poderá ser alocado para caracteres adicionados a esse objeto CSimpleStringT.

Exemplo

O exemplo a seguir demonstra o uso de CSimpleStringT::operator +=.

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

`CSimpleStringT::operator =`

Atribui um novo valor a um objeto CSimpleStringT.

Sintaxe

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

Parâmetros

pszSrc
Um ponteiro para uma cadeia de caracteres terminada em nulo.

strSrc
Um ponteiro para um objeto CSimpleStringT existente.

Comentários

Se a cadeia de caracteres de destino (o lado esquerdo) já for grande o suficiente para armazenar os novos dados, nenhuma nova alocação de memória será executada. Observe que exceções de memória poderão ocorrer sempre que você usar o operador de atribuição porque o novo armazenamento é, geralmente, alocado para reter o objeto CSimpleStringT resultante.

Exemplo

O exemplo a seguir demonstra o uso 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`

Acessa diretamente caracteres armazenados em um objeto CSimpleStringT como uma cadeia de caracteres no estilo C.

Sintaxe

operator PCXSTR() const throw();

Valor retornado

Um ponteiro de caractere para os dados da cadeia de caracteres.

Comentários

Nenhum caractere é copiado. Apenas um ponteiro é retornado. Tenha cuidado com esse operador. Se você alterar um objeto CString depois de obter o ponteiro de caracteres, poderá causar uma realocação da memória que invalidará o ponteiro.

Exemplo

O exemplo a seguir demonstra o uso 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`

Um ponteiro para uma cadeia de caracteres constante.

Sintaxe

typedef ChTraitsBase< BaseType >::PCXSTR PCXSTR;

`CSimpleStringT::Preallocate`

Aloca uma quantidade específica de bytes para o objeto CSimpleStringT.

Sintaxe

void Preallocate( int nLength);

Parâmetros

nLength
O tamanho exato do buffer de caracteres CSimpleStringT em caracteres.

Comentários

Chame esse método para alocar um tamanho do buffer específico para o objeto CSimpleStringT.

CSimpleStringT gerará uma exceção STATUS_NO_MEMORY se não for possível alocar espaço para o buffer de caracteres. Por padrão, a alocação de memória é executada pelas funções de API WIN32 HeapAlloc ou HeapReAlloc.

Exemplo

O exemplo a seguir demonstra o uso 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());

A saída desse exemplo é a seguinte:

Allocated length: 0
Allocated length: 103

`CSimpleStringT::PXSTR`

Um ponteiro para uma cadeia de caracteres.

Sintaxe

typedef ChTraitsBase< BaseType >::PXSTR PXSTR;

`CSimpleStringT::ReleaseBuffer`

Libera o controle do buffer alocado por GetBuffer.

Sintaxe

void ReleaseBuffer(int nNewLength = -1);

Parâmetros

nNewLength
O novo comprimento da cadeia de caracteres em caracteres, sem contar um terminador nulo. Se a cadeia de caracteres for terminada em nulo, o valor padrão -1 definirá o tamanho CSimpleStringT como o comprimento atual da cadeia de caracteres.

Comentários

Chame esse método para realocar ou liberar o buffer do objeto de cadeia de caracteres. Se souber que a cadeia de caracteres no buffer é terminada em nulo, você poderá omitir o argumento nNewLength. Se a cadeia de caracteres não for terminada em nulo, use nNewLength para especificar seu comprimento. O endereço retornado por GetBuffer é inválido após a chamada para ReleaseBuffer ou qualquer outra operação CSimpleStringT.

Exemplo

O exemplo a seguir demonstra o uso 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`

Libera o controle do buffer alocado por GetBuffer.

Sintaxe

void ReleaseBufferSetLength(int nNewLength);

Parâmetros

nNewLength
O comprimento da cadeia de caracteres a ser liberada

Comentários

Essa função é funcionalmente semelhante à ReleaseBuffer, exceto que um comprimento válido para o objeto de cadeia de caracteres deve ser passado.

`CSimpleStringT::SetAt`

Define um único caractere de um objeto CSimpleStringT.

Sintaxe

void SetAt(int iChar, XCHAR ch);

Parâmetros

iChar
Índice baseado em zero do caractere no objeto CSimpleStringT. O parâmetro iChar deve ser maior ou igual a 0 e menor que o valor retornado por GetLength.

ch
O caractere novo.

Comentários

Chame esse método para substituir o caractere localizado em iChar. Esse método não ampliará a cadeia de caracteres se iChar exceder os limites da cadeia de caracteres existente.

Exemplo

O exemplo a seguir demonstra o uso de CSimpleStringT::SetAt.

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

`CSimpleStringT::SetManager`

Especifica o gerenciador de memória do objeto CSimpleStringT.

Sintaxe

void SetManager(IAtlStringMgr* pStringMgr);

Parâmetros

pStringMgr
Um ponteiro para o novo gerenciador de memória.

Comentários

Chame esse método para especificar um novo gerenciador de memória usado pelo objeto CSimpleStringT. Para obter mais informações sobre gerenciadores de memória e objetos de cadeia de caracteres, confira Gerenciamento de memória e CStringT.

Exemplo

O exemplo a seguir demonstra o uso de CSimpleStringT::SetManager.

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

`CSimpleStringT::SetString`

Define uma cadeia de caracteres de um objeto CSimpleStringT.

Sintaxe

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

Parâmetros

pszSrc
Um ponteiro para uma cadeia de caracteres terminada em nulo.

nLength
Uma contagem do número de caracteres em pszSrc.

Comentários

Copie uma cadeia de caracteres no objeto CSimpleStringT. SetString substitui os dados de cadeia de caracteres mais antigos no buffer.

Ambas as versões de SetString verificam se pszSrc é um ponteiro nulo e, se for, gerarão um erro E_INVALIDARG.

A versão de um parâmetro de SetString espera que pszSrc aponte para uma cadeia de caracteres terminada em nulo.

A versão de dois parâmetros de SetString espera que pszSrc seja uma cadeia de caracteres terminada em nulo. Ela usa nLength como o comprimento da cadeia de caracteres, a menos que encontre um terminador nulo primeiro.

A versão de dois parâmetros de SetString também verifica se pszSrc aponta para um local no buffer atual em CSimpleStringT. Nesse caso especial, SetString usa uma função de cópia de memória que não substitui os dados de cadeia de caracteres, pois copia os dados de cadeia de caracteres de volta para seu buffer.

Exemplo

O exemplo a seguir demonstra o uso 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`

Retorna o número de caracteres na cadeia de caracteres especificada.

Sintaxe

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

Parâmetros

psz
Um ponteiro para uma cadeia de caracteres terminada em nulo.

Valor de retorno

O número de caracteres em psz, sem contar um terminador nulo.

Comentários

Chame esse método para recuperar o número de caracteres na cadeia de caracteres apontada por psz.

Exemplo

O exemplo a seguir demonstra o uso de CSimpleStringT::StringLength.

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

`CSimpleStringT::Truncate`

Trunca a cadeia de caracteres no novo comprimento.

Sintaxe

void Truncate(int nNewLength);

Parâmetros

nNewLength
O novo comprimento da cadeia de caracteres.

Comentários

Chame esse método para truncar o conteúdo da cadeia de caracteres no novo comprimento.

Observação

Isso não afeta o comprimento alocado do buffer. Para diminuir ou aumentar o buffer atual, confira FreeExtra e Preallocate.

Exemplo

O exemplo a seguir demonstra o uso 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);

A saída desse exemplo é:

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

`CSimpleStringT::UnlockBuffer`

Desbloqueia o buffer do objeto CSimpleStringT.

Sintaxe

void UnlockBuffer() throw();

Comentários

Chame esse método para redefinir a contagem de referência da cadeia de caracteres para 1.

O destruidor CSimpleStringT chama UnlockBuffer automaticamente para garantir que o buffer não esteja bloqueado quando o destruidor for chamado. Para obter um exemplo desse método, confira LockBuffer.

`CSimpleStringT::~CSimpleStringT`

Destrói um objeto CSimpleStringT.

Sintaxe

~CSimpleStringT() throw();

Comentários

Chame esse método para destruir o objeto CSimpleStringT.

Confira também

Gráfico da hierarquia
Classes compartilhadas ATL/MFC

Partilhar via

Classe CSimpleStringT

Sintaxe

Parâmetros

Membros

Typedefs públicos

Construtores públicos

Métodos públicos

Operadores públicos

Comentários

Requisitos

CSimpleStringT::Append

Sintaxe

Parâmetros

Comentários

Exemplo

CSimpleStringT::AppendChar

Sintaxe

Parâmetros

Comentários

CSimpleStringT::CopyChars

Sintaxe

Parâmetros

Comentários

Exemplo

CSimpleStringT::CopyCharsOverlapped

Sintaxe

Parâmetros

Comentários

Exemplo

CSimpleStringT::CSimpleStringT

Sintaxe

Parâmetros

Comentários

Exemplo

CSimpleStringT::Empty

Sintaxe

Comentários

Exemplo

CSimpleStringT::FreeExtra

Sintaxe

Comentários

Exemplo

CSimpleStringT::GetAllocLength

Sintaxe

Valor retornado

Comentários

CSimpleStringT::GetAt

Sintaxe

Parâmetros

Valor de retorno

Comentários

Exemplo

CSimpleStringT::GetBuffer

Sintaxe

Parâmetros

Valor de retorno

Comentários

Exemplo

CSimpleStringT::GetBufferSetLength

Sintaxe

Parâmetros

Valor de retorno

Comentários

Exemplo

CSimpleStringT::GetLength

Sintaxe

Valor retornado

Comentários

CSimpleStringT::GetManager

Sintaxe

Valor retornado

Comentários

CSimpleStringT::GetString

Sintaxe

Valor retornado

Comentários

Exemplo

CSimpleStringT::IsEmpty

Sintaxe

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`