CSimpleStringT Classe

Esta classe representa um CSimpleStringT objeto.

Sintaxe

template <typename BaseType>
class CSimpleStringT

Parâmetros

BaseType
O tipo de caractere da classe string. Pode ser um dos seguintes:

• char (para cadeias de caracteres ANSI).

• wchar_t (para cadeias de caracteres Unicode).

• TCHAR (para cadeias de caracteres ANSI e Unicode).

Membros

Typedefs Públicos

Construtores Públicos

Métodos Públicos

Operadores Públicos

Observações

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

Requerimentos

Cabeçalho:atlsimpstr.h

CSimpleStringT::Append

Acrescenta um CSimpleStringT objeto a um objeto existente CSimpleStringT .

Sintaxe

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

Parâmetros

strSrc
O CSimpleStringT objeto a ser anexado.

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

nLength
O número de caracteres a acrescentar.

Observações

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

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 existente CSimpleStringT .

Sintaxe

void AppendChar(XCHAR ch);

Parâmetros

ch
O caractere a ser anexado

Observações

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

CSimpleStringT::CopyChars

Copia um caractere ou caracteres para um CSimpleStringT objeto.

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 pchSrc caracteres a serem copiados.

Observações

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

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 deste exemplo é a seguinte:

xxxxxxxxxxxxxxxxxxx
Hello world!xxxxxxx

CSimpleStringT::CopyCharsOverlapped

Copia um caractere ou caracteres para um CSimpleStringT objeto.

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 pchSrc caracteres a serem copiados.

Observações

Chame esse método para copiar caracteres para a pchSrc cadeia de pchDest caracteres. Ao contrário CopyCharsdo , 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 de 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 existente CSimpleStringT a ser copiado para este CSimpleStringT objeto.

pchSrc
Um ponteiro para uma matriz de caracteres de comprimento nLength, não terminado nulo.

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

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

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

Observações

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

Exemplo

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

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

Sintaxe

void Empty() throw();

Observações

Para obter mais informações, consulte Strings: CString Exception Cleanup.

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, mas não mais necessária.

Sintaxe

void FreeExtra();

Observações

Isso deve reduzir a sobrecarga de memória consumida pelo objeto string. 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 deste 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 CSimpleStringT objeto.

Sintaxe

int GetAllocLength() const throw();

Valor de retorno

O número de caracteres alocados para este objeto.

Observações

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

CSimpleStringT::GetAt

Retorna um caractere de um CSimpleStringT objeto.

Sintaxe

XCHAR GetAt(int iChar) const;

Parâmetros

iChar
Índice baseado em zero do caractere no CSimpleStringT objeto. O iChar parâmetro 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.

Observações

Chame esse método para retornar o 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::GetAto .

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

CSimpleStringT::GetBuffer

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

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 destrói o buffer atual, substitui-o por um buffer do tamanho solicitado e redefine a contagem de referência de objeto para zero. Se você tiver chamado LockBuffer esse buffer anteriormente, você perderá o bloqueio de buffer.

Valor de retorno

Um PXSTR ponteiro para o buffer de caracteres (terminado nulo) do objeto.

Observações

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

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 do 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 porque ReleaseBuffer operações adicionais CSimpleStringT podem fazer com que o CSimpleStringT buffer seja realocado. O buffer não é realocado se você não alterar o comprimento do CSimpleStringT.

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

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

Se não houver memória suficiente para satisfazer a GetBuffer solicitação, esse método lançará um CMemoryException*arquivo .

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 do CSimpleStringT objeto, 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 CSimpleStringT buffer de caracteres em caracteres.

Valor de retorno

Um PXSTR ponteiro para o buffer de caracteres (terminado nulo) do objeto.

Observações

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

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 antes de CSimpleStringT usar quaisquer outros CSimpleStringT métodos.

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

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

Se você mesmo 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 quando 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 contagem de referências, consulte os seguintes artigos:

• Gerenciando tempos de vida de objetos por meio da contagem de referência no SDK do Windows.
• Implementando a contagem de referência no SDK do Windows.
• Regras para gerenciar contagens de referência 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 CSimpleStringT objeto.

Sintaxe

int GetLength() const throw();

Valor de retorno

Uma contagem dos caracteres na cadeia de caracteres.

Observações

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

Para conjuntos de caracteres multibyte (MBCS), GetLength conta cada caractere de 8 bits, ou seja, um byte de lead e trail em um caractere multibyte são contados como dois bytes. Veja FreeExtra um exemplo de como chamar essa função.

CSimpleStringT::GetManager

Recupera o gerenciador de memória do CSimpleStringT objeto.

Sintaxe

IAtlStringMgr* GetManager() const throw();

Valor de retorno

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

Observações

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

CSimpleStringT::GetString

Recupera a cadeia de caracteres.

Sintaxe

PCXSTR GetString() const throw();

Valor de retorno

Um ponteiro para uma cadeia de caracteres terminada em nulo.

Observações

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

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 deste exemplo é a seguinte:

Cup soccer is best!

CSimpleStringT::IsEmpty

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

Sintaxe

bool IsEmpty() const throw();

Valor de retorno

Retorna TRUE se o CSimpleStringT objeto tiver 0 comprimento; caso contrário FALSE.

Observações

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ência e protege a cadeia de caracteres no buffer.

Sintaxe

PXSTR LockBuffer();

Valor de retorno

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

Observações

Chame esse método para bloquear o buffer do CSimpleStringT objeto. Ao chamar LockBuffero , 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 como estando 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 para a 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, ligue UnlockBuffer para redefinir a contagem de referência para 1.

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

• Gerenciando tempos de vida de objetos por meio da contagem de referência no SDK do Windows

• Implementando a contagem de referência no SDK do Windows

• Regras para gerenciar contagens de referência 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 deste exemplo é a seguinte:

l

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.

Observações

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

Exemplo

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

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

CSimpleStringT::operator +=

Junta 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 existente CSimpleStringT .

ch
O caractere a ser acrescentado.

Observações

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

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 CSimpleStringT objeto.

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 existente CSimpleStringT .

Observações

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 podem ocorrer sempre que você usa o operador de atribuição porque o novo armazenamento geralmente é alocado para armazenar o objeto resultante CSimpleStringT .

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 os caracteres armazenados em um CSimpleStringT objeto como uma cadeia de caracteres no estilo C.

Sintaxe

operator PCXSTR() const throw();

Valor de retorno

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

Observações

Nenhum caractere é copiado; apenas um ponteiro é retornado. Tenha cuidado com este operador. Se você alterar um CString objeto depois de obter o ponteiro de caracteres, poderá causar uma realocação de memória que invalida 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 CSimpleStringT objeto.

Sintaxe

void Preallocate( int nLength);

Parâmetros

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

Observações

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

CSimpleStringT gera uma STATUS_NO_MEMORY exceção se não for possível alocar espaço para o buffer de caracteres. Por padrão, a alocação de memória é executada por funções HeapAlloc de API WIN32 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 deste 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 pelo 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 string for null terminated, o valor padrão -1 define o CSimpleStringT tamanho para o comprimento atual da string.

Observações

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

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 pelo GetBuffer.

Sintaxe

void ReleaseBufferSetLength(int nNewLength);

Parâmetros

nNewLength
O comprimento da cadeia de caracteres que está sendo liberada

Observações

Esta função é funcionalmente semelhante, ReleaseBuffer exceto que um comprimento válido para o objeto string deve ser passado.

CSimpleStringT::SetAt

Define um único caractere de um CSimpleStringT objeto.

Sintaxe

void SetAt(int iChar, XCHAR ch);

Parâmetros

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

ch
O novo personagem.

Observações

Chame esse método para substituir o caractere localizado em iChar. Esse método não aumentará 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 CSimpleStringT objeto.

Sintaxe

void SetManager(IAtlStringMgr* pStringMgr);

Parâmetros

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

Observações

Chame esse método para especificar um novo gerenciador de memória usado pelo CSimpleStringT objeto. Para obter mais informações sobre gerenciadores de memória e objetos de cadeia de caracteres, consulte 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 a cadeia de caracteres de um CSimpleStringT objeto.

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.

Observações

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

Ambas as versões de SetString verificar se pszSrc é um ponteiro nulo e, se for, lançar um E_INVALIDARG erro.

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

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

A versão de dois parâmetros do SetString também verifica se pszSrc aponta para um local no buffer atual no CSimpleStringT. Nesse caso especial, usa uma função de cópia de memória que não substitui os dados da cadeia de caracteres, SetString pois copia os dados da 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.

Observações

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 para o novo comprimento.

Sintaxe

void Truncate(int nNewLength);

Parâmetros

nNewLength
O novo comprimento da cadeia de caracteres.

Observações

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

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 deste exemplo é:

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

CSimpleStringT::UnlockBuffer

Desbloqueia o CSimpleStringT buffer do objeto.

Sintaxe

void UnlockBuffer() throw();

Observações

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

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

CSimpleStringT::~CSimpleStringT

Destrói um CSimpleStringT objeto.

Sintaxe

~CSimpleStringT() throw();

Observações

Chame esse método para destruir o CSimpleStringT objeto.

Ver também

Gráfico de Hierarquia
Classes compartilhadas ATL/MFC