Classe CStringT

  • Artigo

Essa classe representa um objeto CStringT.

Sintaxe

template<typename BaseType, class StringTraits>
class CStringT :
    public CSimpleStringT<BaseType,
        _CSTRING_IMPL_::_MFCDLLTraitsCheck<BaseType, StringTraits>::c_bIsMFCDLLTraits>

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

StringTraits
Determina se a classe de cadeia de caracteres precisa de suporte à Biblioteca CRT (C Run-Time) e onde os recursos de cadeia de caracteres estão localizados. Um dos seguintes pode ser feito:

  • StrTraitATL<wchar_t | char | TCHAR, ChTraitsCRT<wchar_t | char | TCHAR>>

    A classe requer suporte ao CRT e pesquisa cadeias de caracteres do recurso no módulo especificado por m_hInstResource (um membro da classe de módulo do aplicativo).

  • StrTraitATL<wchar_t | char | TCHAR, ChTraitsOS<wchar_t | char |TCHAR>>

    A classe não requer suporte ao CRT e pesquisa cadeias de caracteres do recurso no módulo especificado por m_hInstResource (um membro da classe de módulo do aplicativo).

  • StrTraitMFC<wchar_t | char | TCHAR, ChTraitsCRT<wchar_t | char | TCHAR>>

    A classe requer suporte ao CRT e pesquisa cadeias de caracteres de recurso usando o algoritmo de pesquisa do MFC padrão.

  • StrTraitMFC<wchar_t | char | TCHAR, ChTraitsOS<wchar_t | char | TCHAR>>

    A classe não requer suporte ao CRT e pesquisa cadeias de caracteres de recurso usando o algoritmo de pesquisa do MFC padrão.

Membros

Construtores públicos

Nome Descrição
CStringT::CStringT Constrói um objeto CStringT de várias maneiras.
CStringT::~CStringT Destrói um objeto CStringT.

Métodos públicos

Nome Descrição
CStringT::AllocSysString Aloca um BSTR de dados CStringT.
CStringT::AnsiToOem Faz uma conversão in-loco do conjunto de caracteres ANSI para o conjunto de caracteres OEM.
CStringT::AppendFormat Acrescenta dados formatados a um objeto CStringT existente.
CStringT::Collate Compara duas cadeias de caracteres (diferencia maiúsculas de minúsculas, usa informações específicas da localidade).
CStringT::CollateNoCase Compara duas cadeias de caracteres (não diferencia maiúsculas de minúsculas, usa informações específicas da localidade).
CStringT::Compare Compara duas cadeias de caracteres (diferencia maiúsculas de minúsculas).
CStringT::CompareNoCase Compara duas cadeias de caracteres (não diferencia maiúsculas de minúsculas).
CStringT::Delete Exclui um caractere ou caracteres de uma cadeia de caracteres.
CStringT::Find Localiza um caractere ou substring dentro de uma cadeia de caracteres maior.
CStringT::FindOneOf Localiza o primeiro caractere correspondente de um conjunto.
CStringT::Format Formata a cadeia de caracteres como sprintf faz.
CStringT::FormatMessage Formata uma cadeia de caracteres de mensagem.
CStringT::FormatMessageV Formata uma cadeia de caracteres de mensagem usando uma lista de argumentos variáveis.
CStringT::FormatV Formata a cadeia de caracteres usando uma lista variável de argumentos.
CStringT::GetEnvironmentVariable Define a cadeia de caracteres como o valor da variável de ambiente especificada.
CStringT::Insert Insere um único caractere ou uma substring no índice fornecido dentro da cadeia de caracteres.
CStringT::Left Extrai a parte esquerda de uma cadeia de caracteres.
CStringT::LoadString Carrega um objeto CStringT existente de um recurso do Windows.
CStringT::MakeLower Converte todos os caracteres nessa cadeia de caracteres em caracteres minúsculos.
CStringT::MakeReverse Inverte a cadeia de caracteres.
CStringT::MakeUpper Converte todos os caracteres nessa cadeia de caracteres em caracteres maiúsculos.
CStringT::Mid Extrai a parte intermediária de uma cadeia de caracteres.
CStringT::OemToAnsi Faz uma conversão in-loco do conjunto de caracteres OEM para o conjunto de caracteres ANSI.
CStringT::Remove Remove os caracteres indicados de uma cadeia de caracteres.
CStringT::Replace Substitui caracteres indicados por outros caracteres.
CStringT::ReverseFind Localiza um caractere dentro de uma cadeia de caracteres maior; começa do final.
CStringT::Right Extrai a parte direita de uma cadeia de caracteres.
CStringT::SetSysString Define um objeto BSTR existente usando dados de um objeto CStringT.
CStringT::SpanExcluding Extrai caracteres da cadeia de caracteres, começando com o primeiro caractere, que não estão no conjunto de caracteres identificados por pszCharSet.
CStringT::SpanIncluding Extrai uma substring que contém apenas os caracteres em um conjunto.
CStringT::Tokenize Extrai tokens especificados em uma cadeia de caracteres de destino.
CStringT::Trim Remove todos os caracteres de espaço em branco à esquerda e à direita de uma cadeia de caracteres.
CStringT::TrimLeft Remove os caracteres de espaço em branco à esquerda de uma cadeia de caracteres.
CStringT::TrimRight Remove todos os caracteres de espaço em branco à direita de uma cadeia de caracteres.

Operadores

Nome Descrição
CStringT::operator = Atribui um novo valor a um objeto CStringT.
CStringT::operator + Concatena duas cadeias de caracteres ou um caractere e uma cadeia de caracteres.
CStringT::operator += Concatena uma nova cadeia de caracteres até o final de uma cadeia de caracteres existente.
CStringT::operator == Determina se duas cadeias de caracteres são logicamente iguais.
CStringT::operator != Determina se duas cadeias de caracteres não são logicamente iguais.
CStringT::operator < Determina se a cadeia de caracteres à esquerda do operador é menor que a cadeia de caracteres à direita.
CStringT::operator > Determina se a cadeia de caracteres à esquerda do operador é maior que a cadeia de caracteres à direita.
CStringT::operator <= Determina se a cadeia de caracteres à esquerda do operador é menor ou igual à cadeia de caracteres à direita.
CStringT::operator >= Determina se a cadeia de caracteres à esquerda do operador é maior ou igual à cadeia de caracteres à direita.

Comentários

CStringT herda da classe CSimpleStringT. Recursos avançados, como manipulação, ordenação e pesquisa de caracteres, são implementados por CStringT.

Observação

Os objetos CStringT são capazes de gerar exceções. Isso ocorre quando um objeto CStringT fica sem memória por qualquer motivo.

Um objeto CStringT consiste em uma sequência de comprimento variável de caracteres. O CStringT fornece funções e operadores usando sintaxe semelhante à do Basic. Os operadores de concatenação e comparação, juntamente com o gerenciamento de memória simplificado, deixam o uso de objetos CStringT mais fácil do que as matrizes de caracteres comuns.

Observação

Embora seja possível criar instâncias CStringT que contenham caracteres nulos inseridos, não recomendamos isso. Chamar métodos e operadores em objetos CStringT que contêm caracteres nulos inseridos pode produzir resultados não intencionais.

Usando combinações diferentes dos parâmetros BaseType e StringTraits, os objetos CStringT podem vir nos tipos a seguir, que foram predefinidos pelas bibliotecas da ATL.

Se estiver usando em um aplicativo da ATL:

CString, CStringA e CStringW são exportados da DLL do MFC (MFC90.DLL), nunca de DLLs de usuário. Isso é feito para evitar que CStringT seja definido várias vezes.

Observação

Se o código contiver a solução alternativa para erros do vinculador descritos em Exportar classes de cadeia de caracteres usando CStringT, você deverá remover esse código. Ele não é mais necessário.

Os seguintes tipos de cadeia de caracteres estão disponíveis em aplicativos com base em MFC:

Tipo CStringT Declaração
CStringA Uma cadeia de caracteres ANSI com suporte a CRT.
CStringW Uma cadeia de caracteres Unicode com suporte a CRT.
CString Tipos de caracteres ANSI e Unicode com suporte a CRT.

Os seguintes tipos de cadeia de caracteres estão disponíveis em projetos em que ATL_CSTRING_NO_CRT é definido:

Tipo CStringT Declaração
CAtlStringA Uma cadeia de caracteres ANSI sem suporte a CRT.
CAtlStringW Uma cadeia de caracteres Unicode sem suporte a CRT.
CAtlString Tipos de caracteres ANSI e Unicode sem suporte a CRT.

Os seguintes tipos de cadeia de caracteres estão disponíveis em projetos em que ATL_CSTRING_NO_CRT não é definido:

Tipo CStringT Declaração
CAtlStringA Uma cadeia de caracteres ANSI com suporte a CRT.
CAtlStringW Uma cadeia de caracteres Unicode com suporte a CRT.
CAtlString Tipos de caracteres ANSI e Unicode com suporte a CRT.

Os objetos CString também têm as seguintes características:

  • Os objetos CStringT podem aumentar devido a operações de concatenação.

  • Os objetos CStringT seguem a "semântica de valor". Pense em um objeto CStringT como uma cadeia de caracteres real, não como um ponteiro para uma cadeia de caracteres.

  • Você pode substituir objetos CStringT livremente por argumentos de função PCXSTR.

  • Gerenciamento de memória personalizado para buffers de cadeia de caracteres. Para saber mais, confira Gerenciamento de memória e CStringT.

Tipos predefinidos do CStringT

Como CStringT usa um argumento de modelo para definir o tipo de caractere (wchar_t ou char) com suporte, os tipos de parâmetro de método podem ser complicados às vezes. Para simplificar esse problema, um conjunto de tipos predefinidos é definido e usado em toda a classe CStringT. A seguinte tabela lista os vários tipos:

Nome Descrição
XCHAR Um único caractere (wchar_t ou char) com o mesmo tipo de caractere que o objeto CStringT.
YCHAR Um único caractere (wchar_t ou char) com o tipo de caractere oposto ao do objeto CStringT.
PXSTR Um ponteiro para uma cadeia de caracteres (wchar_t ou char) com o mesmo tipo de caractere que o objeto CStringT.
PYSTR Um ponteiro para uma cadeia de caracteres (wchar_t ou char) com o tipo de caractere oposto ao do objeto CStringT.
PCXSTR Um ponteiro para uma cadeia de caracteres const (wchar_t ou char) com o mesmo tipo de caractere que o objeto CStringT.
PCYSTR Um ponteiro para uma cadeia de caracteres const (wchar_t ou char) com o tipo de caractere oposto ao do objeto CStringT.

Observação

O código que usou anteriormente métodos não documentados de CString (como AssignCopy) deve ser substituído pelo código que usa os seguintes métodos documentados de CStringT (como GetBuffer ou ReleaseBuffer). Esses métodos são herdados de CSimpleStringT.

Hierarquia de herança

CSimpleStringT

CStringT

Requisitos

Cabeçalho Usar para
cstringt.h Objetos de cadeia de caracteres somente MFC
atlstr.h Objetos de cadeia de caracteres não MFC

CStringT::AllocSysString

Aloca uma cadeia de caracteres compatível com automação do tipo BSTR e copia o conteúdo do objeto CStringT nele, incluindo o caractere nulo de terminação.

BSTR AllocSysString() const;

Valor de Devolução

A cadeia de caracteres recém-alocada.

Comentários

Em programas MFC, uma classe CMemoryException será lançada se houver memória insuficiente. Em programas da ATL, um CAtlException é lançado. Essa função normalmente é usada para retornar cadeias de caracteres para Automação.

Normalmente, se essa cadeia de caracteres for passada para uma função COM como um parâmetro [in], isso exigirá que o chamador libere a cadeia de caracteres. Isso pode ser feito usando SysFreeString, conforme descrito no SDK do Windows. Para obter mais informações, confira Alocar e liberar memória para um BSTR.

Para obter mais informações sobre funções de alocação OLE no Windows, confira SysAllocString no SDK do Windows.

Exemplo

O exemplo a seguir demonstra o uso de CStringT::AllocSysString.

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;
CAtlString str(_T("This is a test string!"));
BSTR bstr = str.AllocSysString();

// bstr now contains "This is a test string!", and can be
// passed to any OLE function requiring a BSTR.
// Normally, if you pass the BSTR, you will
// need to free the string after returning from the function call.

CStringT::AnsiToOem

Converte todos os caracteres nesse objeto CStringT do conjunto de caracteres ANSI para o conjunto de caracteres OEM.

void AnsiToOem();

Comentários

A função não estará disponível se _UNICODE estiver definida.

Exemplo

// OEM character 252 on most IBM-compatible computers in
// many countries/regions is superscript n, as in 2^n.
// Converting it to the ANSI English charset results in a
// normal character 'n', which is the closest possible
// representation.

CStringT<char, StrTraitATL<char, ChTraitsCRT<char>>> str((WCHAR)252);
str.OemToAnsi();
ASSERT(str[0] == 'n');

// Be aware that in OEM to ANSI conversion the 'n'
// from the previous result cannot be converted back to
// a supsercript n because the system does not know what
// the character's value truly was.
str.AnsiToOem();
ASSERT(str[0] != 252);
ASSERT(str[0] == 'n');

CStringT::AppendFormat

Acrescenta dados formatados a um objeto CStringT existente.

void __cdecl AppendFormat(PCXSTR pszFormat, [, argument] ...);
void __cdecl AppendFormat(UINT nFormatID, [, argument] ...);

Parâmetros

pszFormat
Uma cadeia de caracteres de controle de formato.

nFormatID
O identificador de recurso de cadeia de caracteres que contém a cadeia de caracteres de controle de formato.

argument
Argumentos opcionais.

Comentários

Essa função formata e acrescenta uma série de caracteres e valores em CStringT. Cada argumento opcional (se houver) é convertido e acrescentado de acordo com a especificação de formato correspondente em pszFormat ou do recurso de cadeia de caracteres identificado por nFormatID.

Exemplo

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString str = _T("Some data:\t");

str.AppendFormat(_T("X value = %.2f\n"), 12345.12345);
_tprintf_s(_T("%s"), (LPCTSTR) str);

CStringT::Collate

Compara duas cadeias de caracteres usando a função _tcscoll de texto genérico.

int Collate(PCXSTR psz) const throw();

Parâmetros

psz
A outra cadeia de caracteres usada para comparação.

Valor de Devolução

Zero se as cadeias de caracteres forem idênticas, < 0 se esse objeto CStringT for menor que psz, ou > 0 se esse objeto CStringT for maior que psz.

Comentários

A função _tcscoll de texto genérico, que é definida em TCHAR.H, mapeia para strcoll, wcscoll ou _mbscoll, dependendo do conjunto de caracteres definido no tempo de compilação. Cada uma dessas funções executa uma comparação que diferencia maiúsculas e minúsculas das cadeias de caracteres, de acordo com a página de código atualmente em uso. Para obter mais informações, confira strcoll, wcscoll, _mbscoll, _strcoll_l, _wcscoll_l, _mbscoll_l.

CStringT::CollateNoCase

Compara duas cadeias de caracteres usando a função _tcscoll de texto genérico.

int CollateNoCase(PCXSTR psz) const throw();

Parâmetros

psz
A outra cadeia de caracteres usada para comparação.

Valor de Devolução

Zero se as cadeias de caracteres forem idênticas (ignorando maiúsculas e minúsculas), < 0 se esse objeto CStringT for menor que psz (ignorando maiúsculas e minúsculas) ou > 0 se esse objeto CStringT for maior que psz (ignorando maiúsculas e minúsculas).

Comentários

A função _tcscoll de texto genérico, que é definida em TCHAR.H, mapeia para stricoll, wcsicoll ou _mbsicoll, dependendo do conjunto de caracteres definido no tempo de compilação. Cada uma dessas funções executa uma comparação que não diferencia maiúsculas e minúsculas das cadeias de caracteres, de acordo com a página de código atualmente em uso. Para obter mais informações, confira strcoll, wcscoll, _mbscoll, _strcoll_l, _wcscoll_l, _mbscoll_l.

Exemplo

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString str1 = _T("Co-Op");
CAtlString str2 = _T("con");

int n;

// Collation uses language rules, such as ignoring dashes.
// NoCase version ignores case.
n = str1.CollateNoCase(str2);
ASSERT(n < 0);

// Comparison is a strict ASCII comparison with no language rules
// but still ignores case in NoCase version.
n = str1.CompareNoCase(str2);
ASSERT(n < 0);

CStringT::Compare

Compara duas cadeias de caracteres (diferencia maiúsculas de minúsculas).

int Compare(PCXSTR psz) const;

Parâmetros

psz
A outra cadeia de caracteres usada para comparação.

Valor de Devolução

Zero se as cadeias de caracteres forem idênticas, < 0 se esse objeto CStringT for menor que psz, ou > 0 se esse objeto CStringT for maior que psz.

Comentários

A função _tcscmp de texto genérico, que é definida em TCHAR.H, mapeia para strcmp, wcscmp ou _mbscmp, dependendo do conjunto de caracteres definido no tempo de compilação. Cada função faz uma comparação que diferencia maiúsculas de minúsculas das cadeias de caracteres e não é afetada pela localidade. Para obter mais informações, confira strcmp, wcscmp, _mbscmp.

Se a cadeia de caracteres contiver nulos inseridos, para fins de comparação, a cadeia de caracteres será considerada truncada no primeiro caractere nulo inserido.

Exemplo

O exemplo a seguir demonstra o uso de CStringT::Compare.

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString s1(_T("abc"));
CAtlString s2(_T("abd"));
ASSERT(s1.Compare(s2) < 0);    // Compare with another CAtlString.
ASSERT(s1.Compare(_T("abe")) < 0); // Compare with LPTSTR string.

CStringT::CompareNoCase

Compara duas cadeias de caracteres (não diferencia maiúsculas de minúsculas).

int CompareNoCase(PCXSTR psz) const throw();

Parâmetros

psz
A outra cadeia de caracteres usada para comparação.

Valor de Devolução

Zero se as cadeias de caracteres forem idênticas (ignorando maiúsculas e minúsculas), <0 se esse objeto CStringT for menor que psz (ignorando maiúsculas e minúsculas) ou >0 se esse objeto CStringT for maior que psz (ignorando maiúsculas e minúsculas).

Comentários

A função _tcsicmp de texto genérico, que é definida em TCHAR.H, mapeia para _stricmp, _wcsicmp ou _mbsicmp, dependendo do conjunto de caracteres definido no tempo de compilação. Cada função faz uma comparação que não diferencia maiúsculas de minúsculas das cadeias de caracteres. A comparação depende do aspecto LC_CTYPE da localidade, mas não de LC_COLLATE. Para obter mais informações, confira _stricmp, _wcsicmp, _mbsicmp, _stricmp_l, _wcsicmp_l, _mbsicmp_l.

Exemplo

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString s1(_T("abc"));
CAtlString s2(_T("ABD"));
ASSERT(s1.CompareNoCase(s2) < 0); // Compare with a CAtlString.
ASSERT(s1.CompareNoCase(_T("ABE")) < 0); // Compare with LPTSTR string.

CStringT::CStringT

Constrói um objeto CStringT.

CStringT() throw() :
    CThisSimpleString(StringTraits::GetDefaultManager());

explicit CStringT(IAtlStringMgr* pStringMgr) throw() :
    CThisSimpleString( pStringMgr);

CStringT(const VARIANT& varSrc);

CStringT(const VARIANT& varSrc, IAtlStringMgr* pStringMgr);

CStringT(const CStringT& strSrc) :
    CThisSimpleString( strSrc);

operator CSimpleStringT<
                    BaseType,
                    !_CSTRING_IMPL_::_MFCDLLTraitsCheck<BaseType, StringTraits>
                    :: c_bIsMFCDLLTraits> &()

template <bool bMFCDLL>
CStringT(const CSimpleStringT<BaseType, bMFCDLL>& strSrc) :
    CThisSimpleString( strSrc);

template <class SystemString>
CStringT(SystemString^ pString) :
    CThisSimpleString( StringTraits::GetDefaultManager());

CStringT(const XCHAR* pszSrc) :
    CThisSimpleString( StringTraits::GetDefaultManager());

CSTRING_EXPLICIT CStringT(const YCHAR* pszSrc) :
    CThisSimpleString( StringTraits::GetDefaultManager());

CStringT(LPCSTR pszSrc, IAtlStringMgr* pStringMgr) :
    CThisSimpleString( pStringMgr);

CStringT(LPCWSTR pszSrc, IAtlStringMgr* pStringMgr) :
    CThisSimpleString( pStringMgr);

CSTRING_EXPLICIT CStringT(const unsigned char* pszSrc) :
    CThisSimpleString( StringTraits::GetDefaultManager());

/*CSTRING_EXPLICIT*/ CStringT(char* pszSrc) :
    CThisSimpleString( StringTraits::GetDefaultManager());

CSTRING_EXPLICIT CStringT(unsigned char* pszSrc) :
    CThisSimpleString( StringTraits::GetDefaultManager());

CSTRING_EXPLICIT CStringT(wchar_t* pszSrc) :
    CThisSimpleString( StringTraits::GetDefaultManager());

CStringT(const unsigned char* pszSrc, IAtlStringMgr* pStringMgr) :
    CThisSimpleString( pStringMgr);

CSTRING_EXPLICIT CStringT(char ch, int nLength = 1) :
    CThisSimpleString( StringTraits::GetDefaultManager());

CSTRING_EXPLICIT CStringT(wchar_t ch, int nLength = 1) :
    CThisSimpleString( StringTraits::GetDefaultManager());

CStringT(const XCHAR* pch, int nLength) :
    CThisSimpleString( pch, nLength, StringTraits::GetDefaultManager());

CStringT(const YCHAR* pch, int nLength) :
    CThisSimpleString( StringTraits::GetDefaultManager());

CStringT(const XCHAR* pch, int nLength, AtlStringMgr* pStringMgr) :
    CThisSimpleString( pch, nLength, pStringMgr);

CStringT(const YCHAR* pch, int nLength, IAtlStringMgr* pStringMgr) :
    CThisSimpleString( pStringMgr);

Parâmetros

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

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

ch
Um único caractere.

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

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

strSrc
Um objeto CStringT existente a ser copiado nesse objeto CStringT. Para obter mais informações sobre CThisString e CThisSimpleString, confira a seção "Comentários".

varSrc
Um objeto variante a ser copiado nesse objeto CStringT.

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

bMFCDLL
O booliano que especifica se o projeto é uma DLL do MFC (TRUE) ou não (FALSE).

SystemString
Deve ser System::String, e o projeto deve ser compilado com /clr.

pString
Um identificador para um objeto CStringT.

Comentários

Como os construtores copiam os dados de entrada em um novo armazenamento alocado, podem ocorrer exceções de memória. Alguns desses construtores atuam como funções de conversão. Isso permite substituir, por exemplo, um LPTSTR em que um objeto CStringT é esperado.

  • CStringT( LPCSTRlpsz ):: constrói um CStringT Unicode usando uma cadeia de caracteres ANSI. Também é possível usar esse construtor para carregar um recurso de cadeia de caracteres, conforme mostrado no exemplo abaixo.

  • CStringT(LPCWSTRlpsz ): constrói um CStringT usando uma cadeia de caracteres Unicode.

  • CStringT( const unsigned char*psz ): permite que você construa um CStringT de um ponteiro para unsigned char.

Observação

Defina a macro _CSTRING_DISABLE_NARROW_WIDE_CONVERSION para desligar a conversão de cadeia de caracteres implícita entre cadeias de caracteres ANSI e Unicode. A macro exclui dos construtores de compilação que dão suporte à conversão.

O parâmetro strSrc pode ser um objeto CStringT ou CThisSimpleString. Para CStringT, use uma de suas instanciações padrão (CString, CStringA ou CStringW). Para CThisSimpleString, use um ponteiro this. CThisSimpleString declara uma instância da classe CSimpleStringT, que é uma classe de cadeia de caracteres menor com menos funcionalidades internas do que a classe CStringT.

O operador CSimpleStringT<>&() de sobrecarga constrói um objeto CStringT usando uma declaração CSimpleStringT.

Observação

Embora seja possível criar instâncias CStringT que contenham caracteres nulos inseridos, não recomendamos isso. Chamar métodos e operadores em objetos CStringT que contêm caracteres nulos inseridos pode produzir resultados não intencionais.

Exemplo

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString s1;                    // Empty string
CAtlString s2(_T("cat"));           // From a C string literal
CAtlString s3 = s2;               // Copy constructor
CAtlString s4(s2 + _T(" ") + s3);   // From a string expression

CAtlString s5(_T('x'));             // s5 = "x"
CAtlString s6(_T('x'), 6);          // s6 = "xxxxxx"

CAtlString s7((LPCSTR)ID_FILE_NEW); // s7 = "Create a new document"

VARIANT var;
V_VT(&var) = VT_BSTR;
V_BSTR(&var) = ::SysAllocString(L"Football is a fun sport.");
CAtlString s8(var); // s8 = "Football is a fun sport."

// The following statement does not call the assignment operator.
// The compiler considers the following statement equivalent to
// CAtlString city("Paris")
CAtlString city = _T("Paris");

CStringT::~CStringT

Destrói o objeto CStringT.

~CStringT() throw();

Comentários

Destrói o objeto CStringT.

CStringT::Delete

Exclui um caractere ou caracteres de uma cadeia de caracteres começando com o caractere no índice fornecido.

int Delete(int iIndex, int nCount = 1);

Parâmetros

iIndex
O índice baseado em zero do primeiro caractere nno objeto CStringT a ser excluído.

nCount
O número de caracteres a serem removidos.

Valor de Devolução

O comprimento da cadeia de caracteres alterada.

Comentários

Se nCount for maior que a cadeia de caracteres, o restante da cadeia de caracteres será removido.

Exemplo

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString str(_T("Soccer is best, but hockey is quicker!"));
_tprintf_s(_T("Before: %s\n"), (LPCTSTR)str);

int n = str.Delete(6, 3);
_tprintf_s(_T("After: %s\n"), (LPCTSTR)str);
ASSERT(n == str.GetLength());

Before: Soccer is best,
    but hockey is quicker!
After: Soccer best,
    but hockey is quicker!

CStringT::Find

Pesquisa essa cadeia de caracteres para a primeira correspondência de um caractere ou substring.

int Find(PCXSTR pszSub, int iStart=0) const throw();
int Find(XCHAR ch, int iStart=0) const throw();

Parâmetros

pszSub
A substring a ser pesquisada.

iStart
O índice do caractere na cadeia de caracteres com o qual iniciar a pesquisa ou 0 para começar desde o início.

ch
Um único caractere a ser pesquisado.

Valor de Devolução

O índice baseado em zero do primeiro caractere nesse objeto CStringT que corresponde aos caracteres ou substring solicitada; -1 se o caractere ou substring não for encontrada.

Comentários

A função é sobrecarregada para aceitar os caracteres únicos (semelhantes à função strchr em tempo de execução) e cadeias de caracteres (semelhantes a strstr).

Exemplo

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString s(_T("abcdef"));
ASSERT(s.Find(_T('c')) == 2);
ASSERT(s.Find(_T("de")) == 3);

CAtlString str(_T("The waves are still"));
int n = str.Find(_T('e'), 5);
ASSERT(n == 7);

CStringT::FindOneOf

Pesquisa essa cadeia de caracteres para o primeiro caractere que corresponde a qualquer caractere contido em pszCharSet.

int FindOneOf(PCXSTR pszCharSet) const throw();

Parâmetros

pszCharSet
Cadeia de caracteres contendo caracteres para correspondência.

Valor de Devolução

O índice baseado em zero do primeiro caractere nessa cadeia de caracteres que também está em pszCharSet; -1 se não houver correspondência.

Comentários

Localiza a primeira ocorrência de um dos caracteres em pszCharSet.

Exemplo

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString s(_T("abcdef"));
ASSERT(s.FindOneOf(_T("xd")) == 3); // 'd' is first match

CStringT::Format

Grava dados formatados em um CStringT do mesmo modo que sprintf_s formata dados em uma matriz de caracteres no estilo C.

void __cdecl Format(UINT nFormatID, [, argument]...);
void __cdecl Format(PCXSTR pszFormat,  [, argument] ...);

Parâmetros

nFormatID
O identificador de recurso de cadeia de caracteres que contém a cadeia de caracteres de controle de formato.

pszFormat
Uma cadeia de caracteres de controle de formato.

argument
Argumentos opcionais.

Comentários

A função formata e armazena uma série de caracteres e valores em CStringT. Cada argumento opcional (se houver) é convertido e processado de acordo com a especificação de formato correspondente em pszFormat ou do recurso de cadeia de caracteres identificado por nFormatID.

A chamada falhará se o objeto de cadeia de caracteres em si for oferecido como um parâmetro para Format. Por exemplo, o seguinte código fornecerá resultados imprevisíveis:

CAtlString str = _T("Some Data");
str.Format(_T("%s%d"), str, 123);   
// Attention: str is also used in the parameter list.

Para obter mais informações, confira Sintaxe de especificação de formato: funções printf e wprintf.

Exemplo

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;
CAtlString str;

str.Format(_T("Floating point: %.2f\n"), 12345.12345);
_tprintf_s(_T("%s"), (LPCTSTR) str);

str.Format(_T("Left-justified integer: %.6d\n"), 35);
_tprintf_s(_T("%s"), (LPCTSTR) str);

CStringT::FormatMessage

Formata uma cadeia de caracteres de mensagem.

void __cdecl FormatMessage(UINT nFormatID, [, argument]...);
void __cdecl FormatMessage(PCXSTR pszFormat, [, argument]...);

Parâmetros

nFormatID
O identificador de recurso de cadeia de caracteres que contém o texto da mensagem não formatada.

pszFormat
Aponta para a cadeia de caracteres de controle de formato. Ele será verificado quanto a inserções e formatado de acordo. A cadeia de caracteres de formato é semelhante às cadeias de caracteres de formato em estilo printf da função em tempo de execução, exceto que permite que os parâmetros sejam inseridos em uma ordem arbitrária.

argument
Argumentos opcionais.

Comentários

A função requer uma definição de mensagem como entrada. A definição da mensagem é determinada por pszFormat ou pelo recurso de cadeia de caracteres identificado por nFormatID. A função copia o texto da mensagem formatada para o objeto CStringT, processando todas as sequências de inserção inseridas, se solicitadas.

Observação

FormatMessage tenta alocar memória do sistema para a cadeia de caracteres recém-formatada. Se essa tentativa falhar, uma exceção de memória será gerada automaticamente.

Cada inserção deve ter um parâmetro correspondente seguindo o parâmetro pszFormat ou nFormatID. No texto da mensagem, há suporte para várias sequências de escape para formatar dinamicamente a mensagem. Para obter mais informações, confira a função FormatMessage do Windows no SDK do Windows.

Exemplo

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString str;
int nAsked = 5;
int nAgree = 4;

str.FormatMessage(_T("%1!d! of %2!d! writers agree: Soccer is %3%!"), 
   nAgree, nAsked, _T("Best"));
ASSERT(str == _T("4 of 5 writers agree: Soccer is Best!"));

CStringT::FormatMessageV

Formata uma cadeia de caracteres de mensagem usando uma lista de argumentos variáveis.

void FormatMessageV(PCXSTR pszFormat, va_list* pArgList);

Parâmetros

pszFormat
Aponta para a cadeia de caracteres de controle de formato. Ele será verificado quanto a inserções e formatado de acordo. A cadeia de caracteres de formato é semelhante às cadeias de caracteres de formato em estilo printf da função em tempo de execução, exceto que permite que os parâmetros sejam inseridos em uma ordem arbitrária.

pArgList
Um ponteiro para uma lista de argumentos.

Comentários

A função requer uma definição de mensagem como entrada, determinada por pszFormat. A função copia o texto da mensagem formatada e uma lista variável de argumentos para o objeto CStringT, processando todas as sequências de inserção inseridas, se solicitadas.

Observação

FormatMessageV chama CStringT::FormatMessage, que tenta alocar memória do sistema para a cadeia de caracteres recém-formatada. Se essa tentativa falhar, uma exceção de memória será gerada automaticamente.

Para obter mais informações, confira a função FormatMessage do Windows no SDK do Windows.

CStringT::FormatV

Formata uma cadeia de caracteres de mensagem usando uma lista de argumentos variáveis.

void FormatV(PCXSTR pszFormat, va_list args);

Parâmetros

pszFormat
Aponta para a cadeia de caracteres de controle de formato. Ele será verificado quanto a inserções e formatado de acordo. A cadeia de caracteres de formato é semelhante às cadeias de caracteres de formato em estilo printf da função em tempo de execução, exceto que permite que os parâmetros sejam inseridos em uma ordem arbitrária.

args
Um ponteiro para uma lista de argumentos.

Comentários

Grava uma cadeia de caracteres formatada e uma lista variável de argumentos em uma cadeia de caracteres CStringT do mesmo modo que vsprintf_s formata dados em uma matriz de caracteres no estilo C.

Exemplo

void WriteString(LPCTSTR pstrFormat, ...)
{
    CString str;

    // format and write the data you were given
    va_list args;
    va_start(args, pstrFormat);

    str.FormatV(pstrFormat, args);
    va_end(args);

    _tprintf_s(str);
    return;
}

 

// Call the above WriteString function.
WriteString(_T("%d error(s) found in %d line(s)"), 10, 1351);

CStringT::GetEnvironmentVariable

Define a cadeia de caracteres como o valor da variável de ambiente especificada.

BOOL GetEnvironmentVariable(PCXSTR pszVar);

Parâmetros

pszVar
Ponteiro para uma cadeia de caracteres terminada em nulo que especifica a variável de ambiente.

Valor de Devolução

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

Recupera o valor da variável especificada do bloco de ambiente do processo de chamada. O valor está no formato de uma cadeia de caracteres terminada em nulo.

Exemplo

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;
CAtlString EnvStr;

EnvStr.GetEnvironmentVariable(_T("TEMP"));
_tprintf_s(_T("Current value of TEMP variable: %s\n"), EnvStr);

CStringT::Insert

Insere um único caractere ou uma substring no índice fornecido dentro da cadeia de caracteres.

int Insert(int iIndex, PCXSTR psz);
int Insert(int iIndex, XCHAR ch);

Parâmetros

iIndex
O índice do caractere antes do qual a inserção ocorrerá.

psz
Um ponteiro para a substring a ser inserida.

ch
O caractere a ser testado.

Valor de Devolução

O comprimento da cadeia de caracteres alterada.

Comentários

O parâmetro iIndex identifica o primeiro caractere que será movido para abrir espaço para o caractere ou substring. Se nIndex for zero, a inserção ocorrerá antes de toda a cadeia de caracteres. Se nIndex for maior que o tamanho da cadeia de caracteres, a função concatenará a cadeia de caracteres atual e o novo material fornecido por um ch ou psz.

Exemplo

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString str(_T("SoccerBest"));
int n = str.Insert(6, _T("is "));
ASSERT(n == str.GetLength());
_tprintf_s(_T("1: %s\n"), (LPCTSTR) str);

n = str.Insert(6, _T(' '));
ASSERT(n == str.GetLength());
_tprintf_s(_T("2: %s\n"), (LPCTSTR) str);

n = str.Insert(55, _T('!'));
ASSERT(n == str.GetLength());
_tprintf_s(_T("3: %s\n"), (LPCTSTR) str);

CStringT::Left

Extrai os caracteres nCount da extremidade esquerda desse objeto CStringT e retorna uma cópia da substring extraída.

CStringT Left(int nCount) const;

Parâmetros

nCount
O número de caracteres para extrair desse objeto CStringT.

Valor de Devolução

Um objeto CStringT que contém uma cópia do intervalo especificado de caracteres. O objeto CStringT retornado pode estar vazio.

Comentários

Se nCount exceder o tamanho da cadeia de caracteres, a cadeia de caracteres inteira será extraída. Left é semelhante à função Left básica.

Para MBCS (conjuntos de caracteres multibyte), nCount trata cada sequência de 8 bits como um caractere para que nCount retorne o número de caracteres de vários bytes multiplicados por dois.

Exemplo

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString s(_T("abcdef"));
ASSERT(s.Left(2) == _T("ab"));

CStringT::LoadString

Lê um recurso de cadeia de caracteres do Windows, identificado por nID, em um objeto CStringT existente.

BOOL LoadString(HINSTANCE hInstance, UINT nID, WORD wLanguageID);
BOOL LoadString(HINSTANCE hInstance, UINT nID);
BOOL LoadString(UINT nID);

Parâmetros

hInstance
Um identificador para a instância do módulo.

nID
Uma ID do recurso da cadeia de caracteres do Windows.

wLanguageID
A linguagem do recurso de cadeia de caracteres.

Valor de Devolução

Diferente de zero se a carga de recursos foi bem-sucedida. Caso contrário, 0.

Comentários

Carrega o recurso de cadeia de caracteres (nID) do módulo especificado (hInstance) usando a linguagem especificada (wLanguage).

Exemplo

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString s;
s.LoadString(IDS_APP_TITLE);

CStringT::MakeLower

Converte o objeto CStringT em uma cadeia de caracteres em minúsculas.

CStringT& MakeLower();

Valor de Devolução

A cadeia de caracteres em minúsculas resultante.

Exemplo

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString s(_T("ABC"));

ASSERT(s.MakeLower() == _T("abc"));

CStringT::MakeReverse

Inverte a ordem dos caracteres no objeto CStringT.

CStringT& MakeReverse();

Valor de Devolução

A cadeia de caracteres invertida resultante.

Exemplo

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString s(_T("abc"));

ASSERT(s.MakeReverse() == _T("cba"));

CStringT::MakeUpper

Converte o objeto CStringT em uma cadeia de caracteres em maiúsculas.

CStringT& MakeUpper();

Valor de Devolução

A cadeia de caracteres em maiúsculas resultante.

Comentários

Exemplo

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString s(_T("abc"));

ASSERT(s.MakeUpper() == _T("ABC"));

CStringT::Mid

Extrai uma substring com nCount caracteres desse objeto CStringT, começando na posição iFirst (baseada em zero).

CStringT Mid(int iFirst, int nCount) const;
CStringT Mid(int iFirst) const;

Parâmetros

iFirst
O índice baseado em zero do primeiro caractere nesse objeto CStringT que deve ser incluído na substring extraída.

nCount
O número de caracteres para extrair desse objeto CStringT. Se esse parâmetro não for fornecido, o restante da cadeia de caracteres será extraído.

Valor de Devolução

Um objeto CStringT que contém uma cópia do intervalo especificado de caracteres. O objeto CStringT retornado pode estar vazio.

Comentários

A função retorna uma cópia da substring extraída. Mid é semelhante à função Basic Mid (exceto que os índices no Basic são baseados em um).

Para MBCS (conjuntos de caracteres multibyte), nCount 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 caracteres.

Exemplo

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString s(_T("abcdef"));
ASSERT(s.Mid(2, 3) == _T("cde"));

CStringT::OemToAnsi

Converte todos os caracteres nesse objeto CStringT do conjunto de caracteres OEM para o conjunto de caracteres ANSI.

void OemToAnsi();

Comentários

Essa função não estará disponível se _UNICODE estiver definida.

Exemplo

Confira o exemplo de CStringT::AnsiToOem.

CStringT::operator =

Atribui um novo valor à cadeia de caracteres.

CStringT& operator=(const CStringT& strSrc);

template<bool bMFCDLL>
CStringT& operator=(const CSimpleStringT<BaseType, bMFCDLL>& str);
CStringT& operator=(PCXSTR pszSrc);
CStringT& operator=(PCYSTR pszSrc);
CStringT& operator=(const unsigned char* pszSrc);
CStringT& operator=(XCHAR ch);
CStringT& operator=(YCHAR ch);
CStringT& operator=(const VARIANT& var);

Parâmetros

strSrc
A CStringT para atribuir a essa cadeia de caracteres.

str
Uma referência a um objeto CThisSimpleString.

bMFCDLL
Um booliano que especifica se o projeto é uma DLL do MFC ou não.

BaseType
O tipo base de cadeia de caracteres.

var
Um objeto variante a ser atribuído a essa cadeia de caracteres.

ch
Um caractere ANSI ou Unicode a ser atribuído à cadeia de caracteres.

pszSrc
Um ponteiro para a cadeia de caracteres original que está sendo atribuída.

Comentários

O operador de atribuição aceita outro objeto CStringT, um ponteiro de caractere ou um único caractere. Pode ocorrer exceções de memória ao usar esse operador porque um novo armazenamento pode ser alocado.

Para obter mais informações sobre CThisSimpleString, confira a seção "Comentários" de CStringT::CStringT.

Observação

Embora seja possível criar instâncias CStringT que contenham caracteres nulos inseridos, não recomendamos isso. Chamar métodos e operadores em objetos CStringT que contêm caracteres nulos inseridos pode produzir resultados não intencionais.

CStringT::operator +

Concatena duas cadeias de caracteres ou um caractere e uma cadeia de caracteres.

friend CStringT operator+(const CStringT& str1, const CStringT& str2);
friend CStringT operator+(const CStringT& str1, PCXSTR psz2);
friend CStringT operator+(PCXSTR psz1, const CStringT& str2,);
friend CStringT operator+(char ch1, const CStringT& str2,);
friend CStringT operator+(const CStringT& str1, char ch2);
friend CStringT operator+(const CStringT& str1, wchar_t ch2);
friend CStringT operator+(wchar_t ch1, const CStringT& str2,);

Parâmetros

ch1
Um caractere ANSI ou Unicode para concatenar com uma cadeia de caracteres.

ch2
Um caractere ANSI ou Unicode para concatenar com uma cadeia de caracteres.

str1
Um CStringT para concatenar com uma cadeia de caracteres ou caracteres.

str2
Um CStringT para concatenar com uma cadeia de caracteres ou caracteres.

psz1
Um ponteiro para uma cadeia de caracteres terminada em nulo para concatenar com uma cadeia de caracteres ou caracteres.

psz2
Um ponteiro para uma cadeia de caracteres para concatenar com uma cadeia de caracteres ou caracteres.

Comentários

Há sete formas de sobrecarga da função CStringT::operator+. A primeira versão concatena dois objetos CStringT existentes. Os dois seguintes concatenam um objeto CStringT e uma cadeia de caracteres terminada em nulo. Os dois seguintes concatenam um objeto CStringT e um caractere ANSI. Os dois seguintes concatenam um objeto CStringT e um caractere Unicode.

Observação

Embora seja possível criar instâncias CStringT que contenham caracteres nulos inseridos, não recomendamos isso. Chamar métodos e operadores em objetos CStringT que contêm caracteres nulos inseridos pode produzir resultados não intencionais.

Exemplo

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;
CAtlString s1(_T("dog ")), s2(_T(" awake")), s3;  // Empty CAtlString objects

s1= _T("The ") + s1;
s3= s1 + _T('i');
s3= s3 + _T('s');
s3= s3 + s2;
ASSERT(s3 == _T("The dog is awake"));

CStringT::operator +=

Concatena caracteres até o final da cadeia de caracteres.

CStringT& operator+=(const CThisSimpleString& str);

template<bool bMFCDLL>
CStringT& operator+=(const const CSimpleStringT<BaseType, bMFCDLL>& str);

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

Parâmetros

str
Uma referência a um objeto CThisSimpleString.

bMFCDLL
Um booliano que especifica se o projeto é uma DLL do MFC ou não.

BaseType
O tipo base de cadeia de caracteres.

var
Um objeto variante a ser concatenado a essa cadeia de caracteres.

ch
Um caractere ANSI ou Unicode para concatenar com uma cadeia de caracteres.

pszSrc
Um ponteiro para a cadeia de caracteres original que está sendo concatenada.

strSrc
Um CStringT a ser concatenado a essa cadeia de caracteres.

Comentários

O operador aceita outro objeto CStringT, um ponteiro de caractere ou um único caractere. 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 CStringT.

Para obter mais informações sobre CThisSimpleString, confira a seção "Comentários" de CStringT::CStringT.

Observação

Embora seja possível criar instâncias CStringT que contenham caracteres nulos inseridos, não recomendamos isso. Chamar métodos e operadores em objetos CStringT que contêm caracteres nulos inseridos pode produzir resultados não intencionais.

Exemplo

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString s(_T("abc"));
ASSERT((s += _T("def")) == _T("abcdef"));

CStringT::operator ==

Determina se duas cadeias de caracteres são logicamente iguais.

friend bool operator==(const CStringT& str1, const CStringT& str2) throw();
friend bool operator==(const CStringT& str1, PCXSTR psz2) throw();
friend bool operator==(const CStringT& str1, PCYSTR psz2) throw();
friend bool operator==(const CStringT& str1, XCHAR ch2) throw();
friend bool operator==(PCXSTR psz1, const CStringT& str2) throw();
friend bool operator==(PCYSTR psz1, const CStringT& str2,) throw();
friend bool operator==(XCHAR ch1, const CStringT& str2,) throw();

Parâmetros

ch1
Um caractere ANSI ou Unicode para comparação.

ch2
Um caractere ANSI ou Unicode para comparação.

str1
Um CStringT para comparação.

str2
Um CStringT para comparação.

psz1
Um ponteiro para uma cadeia de caracteres terminada em nulo para comparação.

psz2
Um ponteiro para uma cadeia de caracteres terminada em nulo para comparação.

Comentários

Testa se uma cadeia de caracteres ou caractere no lado esquerdo é igual a uma cadeia de caracteres ou caractere no lado direito, e retorna TRUE ou FALSE, de acordo.

Exemplo

// typedef CStringT< TCHAR, StrTraitATL< TCHAR > > CAtlString;
CAtlString s1(_T("dog")), s2(_T("f")), s3(_T("dog"));

ASSERT(s1 == _T("dog"));
ASSERT(s2 == _T('f'));
ASSERT(s1 == s3);

CStringT::operator !=

Determina se duas cadeias de caracteres não são logicamente iguais.

friend bool operator!=(const CStringT& str1, const CStringT& str2) throw();
friend bool operator!=(const CStringT& str1, PCXSTR psz2) throw();
friend bool operator!=(const CStringT& str1, PCYSTR psz2) throw();
friend bool operator!=(const CStringT& str1, XCHAR ch2) throw();
friend bool operator!=(PCXSTR psz1, const CStringT& str2) throw();
friend bool operator!=(PCYSTR psz1, const CStringT& str2,) throw();
friend bool operator!=(XCHAR ch1, const CStringT& str2,) throw();

Parâmetros

ch1
Um caractere ANSI ou Unicode para concatenar com uma cadeia de caracteres.

ch2
Um caractere ANSI ou Unicode para concatenar com uma cadeia de caracteres.

str1
Um CStringT para comparação.

str2
Um CStringT para comparação.

psz1
Um ponteiro para uma cadeia de caracteres terminada em nulo para comparação.

psz2
Um ponteiro para uma cadeia de caracteres terminada em nulo para comparação.

Comentários

Testa se uma cadeia de caracteres ou caractere no lado esquerdo não é igual a uma cadeia de caracteres ou caractere no lado direito.

Exemplo

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;
CAtlString s1(_T("cat")), s2(_T("f")), s3(_T("horse"));

ASSERT(s1 != _T("dog"));
ASSERT(s2 != _T('t'));
ASSERT(s1 != s2);

CStringT::operator <

Determina se a cadeia de caracteres à esquerda do operador é menor que a cadeia de caracteres à direita.

friend bool operator<(const CStringT& str1, const CStringT& str2) throw();
friend bool operator<(const CStringT& str1, PCXSTR psz2) throw();
friend bool operator<(PCXSTR psz1, const CStringT& str2) throw();

Parâmetros

str1
Um CStringT para comparação.

str2
Um CStringT para comparação.

psz1
Um ponteiro para uma cadeia de caracteres terminada em nulo para comparação.

psz2
Um ponteiro para uma cadeia de caracteres terminada em nulo para comparação.

Comentários

Uma comparação lexicográfica entre cadeias de caracteres, caractere por caractere até:

  • Localiza dois elementos correspondentes diferentes e o resultado da comparação entre eles será considerado o resultado da comparação entre as cadeias de caracteres.

  • Não encontra nenhuma desigualdade, mas uma cadeia de caracteres tem mais caracteres do que a outra e a cadeia de caracteres mais curta é considerada menor do que a cadeia de caracteres mais longa.

  • Não encontra nenhuma desigualdade e percebe que as cadeias de caracteres têm o mesmo número de caracteres e então as cadeias de caracteres são iguais.

Exemplo

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;
CAtlString s1(_T("cat")), s2(_T("cats")), s3(_T("dogs"));

ASSERT(s1 < _T("dog"));
ASSERT(s1 < _T("cats"));
ASSERT(s2 < _T("cats and dogs"));
ASSERT(s2 < s3);

CStringT::operator >

Determina se a cadeia de caracteres à esquerda do operador é maior que a cadeia de caracteres à direita.

friend bool operator>(const CStringT& str1, const CStringT& str2) throw();
friend bool operator>(const CStringT& str1, PCXSTR psz2) throw();
friend bool operator>(PCXSTR psz1, const CStringT& str2) throw();

Parâmetros

str1
Um CStringT para comparação.

str2
Um CStringT para comparação.

psz1
Um ponteiro para uma cadeia de caracteres terminada em nulo para comparação.

psz2
Um ponteiro para uma cadeia de caracteres terminada em nulo para comparação.

Comentários

Uma comparação lexicográfica entre cadeias de caracteres, caractere por caractere até:

  • Localiza dois elementos correspondentes diferentes e o resultado da comparação entre eles será considerado o resultado da comparação entre as cadeias de caracteres.

  • Não encontra nenhuma desigualdade, mas uma cadeia de caracteres tem mais caracteres do que a outra e a cadeia de caracteres mais curta é considerada menor do que a cadeia de caracteres mais longa.

  • Não encontra nenhuma desigualdade e percebe que as cadeias de caracteres têm o mesmo número de caracteres, então as cadeias de caracteres são iguais.

Exemplo

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;
CAtlString s1(_T("cat")), s2(_T("cats")), s3(_T("dogs"));
ASSERT(_T("dog") > s1);
ASSERT(_T("cats") > s1);
ASSERT(_T("cats and dogs") > s2);
ASSERT(s3 > s2);

CStringT::operator <=

Determina se a cadeia de caracteres à esquerda do operador é menor ou igual à cadeia de caracteres à direita.

friend bool operator<=(const CStringT& str1, const CStringT& str2) throw();
friend bool operator<=(const CStringT& str1, PCXSTR psz2) throw();
friend bool operator<=(PCXSTR psz1, const CStringT& str2) throw();

Parâmetros

str1
Um CStringT para comparação.

str2
Um CStringT para comparação.

psz1
Um ponteiro para uma cadeia de caracteres terminada em nulo para comparação.

psz2
Um ponteiro para uma cadeia de caracteres terminada em nulo para comparação.

Comentários

Uma comparação lexicográfica entre cadeias de caracteres, caractere por caractere até:

  • Localiza dois elementos correspondentes diferentes e o resultado da comparação entre eles será considerado o resultado da comparação entre as cadeias de caracteres.

  • Não encontra nenhuma desigualdade, mas uma cadeia de caracteres tem mais caracteres do que a outra e a cadeia de caracteres mais curta é considerada menor do que a cadeia de caracteres mais longa.

  • Não encontra nenhuma desigualdade e percebe que as cadeias de caracteres têm o mesmo número de caracteres, então as cadeias de caracteres são iguais.

Exemplo

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;
CAtlString s1(_T("cat")), s2(_T("cats")), s3(_T("dogs"));

ASSERT(s1 <= _T("dog"));
ASSERT(s1 <= _T("cat"));
ASSERT(s3 <= _T("dogs and cats"));
ASSERT(s2 <= s3);

CStringT::operator >=

Determina se a cadeia de caracteres à esquerda do operador é maior ou igual à cadeia de caracteres à direita.

friend bool operator>=(const CStringT& str1, const CStringT& str2) throw();
friend bool operator>=(const CStringT& str1, PCXSTR psz2) throw();
friend bool operator>=(PCXSTR psz1, const CStringT& str2) throw();

Parâmetros

str1
Um CStringT para comparação.

str2
Um CStringT para comparação.

psz1
Um ponteiro para uma cadeia de caracteres para comparação.

psz2
Um ponteiro para uma cadeia de caracteres para comparação.

Comentários

Uma comparação lexicográfica entre cadeias de caracteres, caractere por caractere até:

  • Localiza dois elementos correspondentes diferentes e o resultado da comparação entre eles será considerado o resultado da comparação entre as cadeias de caracteres.

  • Não encontra nenhuma desigualdade, mas uma cadeia de caracteres tem mais caracteres do que a outra e a cadeia de caracteres mais curta é considerada menor do que a cadeia de caracteres mais longa.

  • Não encontra nenhuma desigualdade e percebe que as cadeias de caracteres têm o mesmo número de caracteres, então as cadeias de caracteres são iguais.

Exemplo

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;
CAtlString s1(_T("cat")), s2(_T("cats")), s3(_T("dogs"));

ASSERT(_T("dog") >= s1);
ASSERT(_T("cats and dogs") >= s2);
ASSERT(s3 >= s2);

CStringT::Remove

Remove todas as instâncias do caractere especificado da cadeia de caracteres.

int Remove(XCHAR chRemove);

Parâmetros

chRemove
O caractere a ser removido de uma cadeia de caracteres.

Valor de Devolução

A contagem de caracteres removidos da cadeia de caracteres. Zero se a cadeia de caracteres não for alterada.

Comentários

As comparações para o caractere diferenciam maiúsculas de minúsculas.

Exemplo

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString str(_T("This is a test."));
int n = str.Remove(_T('t'));
ASSERT(n == 2);
ASSERT(str == _T("This is a es."));

CStringT::Replace

Há duas versões de Replace. A primeira versão substitui uma ou mais cópias de uma substring usando outra substring. Ambas as substrings são terminadas em nulo. A segunda versão substitui uma ou mais cópias de um caractere usando outro caractere. Ambas as versões operam nos dados de caractere armazenados em CStringT.

int Replace(PCXSTR pszOld, PCXSTR pszNew);
int Replace(XCHAR chOld, XCHAR chNew);

Parâmetros

pszOld
Um ponteiro para uma cadeia de caracteres terminada em nulo a ser substituída por pszNew.

pszNew
Um ponteiro para uma cadeia de caracteres terminada em nulo que substitui pszOld.

chOld
O caractere a ser substituído por chNew.

chNew
O caractere substituindo chOld.

Valor de Devolução

Retorna o número de instâncias substituídas do caractere ou substring, ou zero se a cadeia de caracteres não for alterada.

Comentários

Replace pode alterar o tamanho da cadeia de caracteres porque pszNew e pszOld não precisam ter o mesmo tamanho e várias cópias da substring antiga podem ser alteradas para a nova. A função faz uma correspondência que diferencia maiúsculas de minúsculas.

Os exemplos de instâncias CStringT são CString, CStringA e CStringW.

Para CStringA, Replace funciona com caracteres ANSI ou de multibyte (MBCS). Para CStringW, Replace funciona com caracteres largos.

Para CString, o tipo de dados de caractere é selecionado no momento da compilação, com base em se as constantes na tabela a seguir são definidas.

Constante definida Tipo de dados de caractere
_UNICODE Caracteres largos
_MBCS Caracteres multibyte
Nenhum Caractere de byte único
Ambos Indefinido

Exemplo

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString strBang(_T("Everybody likes epee fencing"));
int n = strBang.Replace(_T("epee"), _T("foil"));
ASSERT(n == 1);

CStringT::ReverseFind

Pesquisa esse objeto CStringT para a última correspondência de um caractere.

int ReverseFind(XCHAR ch) const throw();

Parâmetros

ch
O caractere a ser pesquisado.

Valor de Devolução

O índice baseado em zero do último caractere nesse objeto CStringT que corresponde ao caractere solicitado, ou -1 se o caractere não for encontrado.

Comentários

A função é semelhante à função de tempo de execução strrchr.

Exemplo

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString s(_T("abcabc"));
ASSERT(s.ReverseFind(_T('b')) == 4);

Extrai os últimos caracteres nCount (da extremidade esquerda) desse objeto CStringT e retorna uma cópia da substring extraída.

CStringT Right(int nCount) const;

Parâmetros

nCount
O número de caracteres para extrair desse objeto CStringT.

Valor de Devolução

Um objeto CStringT que contém uma cópia do intervalo especificado de caracteres. O objeto CStringT retornado pode estar vazio.

Comentários

Se nCount exceder o tamanho da cadeia de caracteres, a cadeia de caracteres inteira será extraída. Right é semelhante à função Right Basic (exceto que os índices no Basic são baseados em zero).

Para conjuntos de caracteres multibyte (MBCS), nCount 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 caracteres.

Exemplo

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString s(_T("abcdef"));
ASSERT(s.Right(2) == _T("ef"));

CStringT::SetSysString

Realoca o BSTR apontado para pbstr e copia o conteúdo do objeto CStringT nele, incluindo o caractere NULL.

BSTR SetSysString(BSTR* pbstr) const;

Parâmetros

pbstr
Um ponteiro para uma cadeia de caracteres.

Valor de Devolução

A nova cadeia de caracteres.

Comentários

Dependendo do conteúdo do objeto CStringT, o valor do BSTR referenciado por pbstr poderá ser alterado. A função gerará um CMemoryException se a memória for insuficiente.

Essa função normalmente é usada para alterar o valor das cadeias de caracteres passadas por referência para o Automação.

Exemplo

BSTR bstr = ::SysAllocString(L"Golf is fun!");

// create a CAtlString and change the OLE
// string to the contents of the BSTR
// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString str(_T("Soccer is best!"));
BSTR bstr2 = str.SetSysString(&bstr);

// Now, both bstr and bstr2 reference a single instance of
// the "Soccer" string. The "Golf" string has been freed.
ASSERT(bstr2 == bstr);

CStringT::SpanExcluding

Extrai caracteres da cadeia de caracteres, começando com o primeiro caractere, que não estão no conjunto de caracteres identificados por pszCharSet.

CStringT SpanExcluding(PCXSTR pszCharSet) const;

Parâmetros

pszCharSet
Uma cadeia de caracteres interpretada como um conjunto de caracteres.

Valor de Devolução

Uma substring que contém caracteres na cadeia de caracteres que não estão em pszCharSet, começando com o primeiro caractere na cadeia de caracteres e terminando com o primeiro caractere encontrado na cadeia de caracteres que também está em pszCharSet (ou seja, começando com o primeiro caractere na cadeia de caracteres e até (mas excluindo) o primeiro caractere na cadeia de caracteres encontrado pszCharSet). Ele retornará a cadeia de caracteres inteira se nenhum caractere em pszCharSet for encontrado na cadeia de caracteres.

Comentários

SpanExcluding extrai e retorna todos os caracteres anteriores à primeira ocorrência de um caractere de pszCharSet (em outras palavras, o caractere de pszCharSet e todos os caracteres que o seguem na cadeia de caracteres não são retornados). Se nenhum caractere de pszCharSet for encontrado na cadeia de caracteres, SpanExcluding retornará toda a cadeia de caracteres.

Exemplo

// The string can be delimited by a semicolon(;),
//  a comma(,), a period(.), a dash(-),
// or an apostrophe(').
// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString src(_T("World Cup '98"));

_tprintf_s(_T("%s"),src.SpanExcluding(_T(";,.-'")));

CStringT::SpanIncluding

Extrai caracteres da cadeia de caracteres, começando com o primeiro caractere, que estão no conjunto de caracteres identificados por pszCharSet.

CStringT SpanIncluding(PCXSTR pszCharSet) const;

Parâmetros

pszCharSet
Uma cadeia de caracteres interpretada como um conjunto de caracteres.

Valor de Devolução

Uma substring que contém caracteres na cadeia de caracteres que estão em pszCharSet, começando com o primeiro caractere na cadeia de caracteres e terminando quando um caractere é encontrado na cadeia de caracteres que não está em pszCharSet. SpanIncluding retornará uma substring vazia se o primeiro caractere na cadeia de caracteres não estiver no conjunto especificado.

Comentários

Se o primeiro caractere da cadeia de caracteres não estiver no conjunto de caracteres, SpanIncluding retornará uma cadeia de caracteres vazia. Caso contrário, ele retorna uma sequência de caracteres consecutivos que estão no conjunto.

Exemplo

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString str(_T("cabbage"));
CAtlString res = str.SpanIncluding(_T("abc"));
ASSERT(res == _T("cabba"));
res = str.SpanIncluding(_T("xyz"));
ASSERT(res.IsEmpty());

CStringT::Tokenize

Localiza o próximo token em uma cadeia de caracteres de destino

CStringT Tokenize(PCXSTR pszTokens, int& iStart) const;

Parâmetros

pszTokens
Uma cadeia de caracteres que contém delimitadores de token. A ordem desses delimitadores não é importante.

iStart
O índice baseado em zero para iniciar a pesquisa.

Valor de Devolução

Um objeto CStringT que contém o valor do token atual.

Comentários

A função Tokenize localiza o próximo token na cadeia de caracteres de destino. O conjunto de caracteres em pszTokens especifica possíveis delimitadores do token a ser encontrado. Em cada chamada à Tokenize, a função é iniciada em iStart, ignora delimitadores à esquerda e retorna um objeto CStringT que contém o token atual, que é a cadeia de caracteres até o próximo caractere delimitador. O valor de iStart é atualizado para ser a posição após o caractere delimitador final, ou -1 se o final da cadeia de caracteres foi atingido. Mais tokens podem ser removidos do restante da cadeia de caracteres de destino por uma série de chamadas para Tokenize, usando iStart para manter o controle de onde na cadeia de caracteres o próximo token deve ser lido. Quando não houver mais tokens, a função retornará uma cadeia de caracteres vazia e iStart será definida como -1.

Ao contrário das funções de criação de token de CRT, como strtok_s, _strtok_s_l, wcstok_s, _wcstok_s_l, _mbstok_s, _mbstok_s_l, Tokenize não modifica a cadeia de caracteres de destino.

Exemplo

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;
CAtlString str(_T("%First Second#Third"));
CAtlString resToken;
int curPos = 0;

resToken= str.Tokenize(_T("% #"),curPos);
while (resToken != _T(""))
{
   _tprintf_s(_T("Resulting token: %s\n"), resToken);
   resToken = str.Tokenize(_T("% #"), curPos);
};

A saída desse exemplo é a seguinte:

Resulting Token: First
Resulting Token: Second
Resulting Token: Third

CStringT::Trim

Remove os caracteres à esquerda e à direita da cadeia de caracteres.

CStringT& Trim(XCHAR chTarget);
CStringT& Trim(PCXSTR pszTargets);
CStringT& Trim();

Parâmetros

chTarget
O caractere de destino a ser removido.

pszTargets
Um ponteiro para uma cadeia de caracteres que contém os caracteres de destino a serem removidos. Todas as ocorrências à esquerda e à direita de caracteres em pszTargets serão removidas do objeto CStringT.

Valor de Devolução

Retorna a cadeia de caracteres removida.

Comentários

Remove todas as ocorrências à esquerda e à direita de um dos seguintes:

  • O caractere especificado por chTarget.

  • Todos os caracteres encontrados na cadeia de caracteres especificada por pszTargets.

  • Espaço em branco.

Exemplo

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString str;
str = _T("******Soccer is best!?!?!?!?!");

_tprintf_s(_T("Before: \"%s\"\n"), (LPCTSTR)str);
_tprintf_s(_T("After : \"%s\"\n"), (LPCTSTR)str.Trim(_T("?!*")));

// Output:
// --------------------------
// Before: ******Soccer is best!?!?!?!?!
// After: Soccer is best

A saída desse exemplo é a seguinte:

Before: "******Soccer is best, but liquor is quicker!!!!!"
After : "Soccer is best, but liquor is quicker"

CStringT::TrimLeft

Remove os caracteres à esquerda da cadeia de caracteres.

CStringT& TrimLeft(XCHAR chTarget);
CStringT& TrimLeft(PCXSTR pszTargets);
CStringT& TrimLeft();

Parâmetros

chTarget
O caractere de destino a ser removido.

pszTargets
Um ponteiro para uma cadeia de caracteres que contém os caracteres de destino a serem removidos. Todas as ocorrências à esquerda dos caracteres em pszTargets serão removidas do objeto CStringT.

Valor de Devolução

A cadeia de caracteres removida resultante.

Comentários

Remove todas as ocorrências à esquerda e à direita de um dos seguintes:

  • O caractere especificado por chTarget.

  • Todos os caracteres encontrados na cadeia de caracteres especificada por pszTargets.

  • Espaço em branco.

Exemplo

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString str;
str = _T("\t\t   ****Soccer is best!");

_tprintf_s(_T("Before: \"%s\"\n"), (LPCTSTR)str);
_tprintf_s(_T("After: \"%s\"\n"), (LPCTSTR)str.TrimLeft(_T("\t *")));

// Output:
// --------------------------
// Before:     ****Soccer is best!
// After: Soccer is best!

CStringT::TrimRight

Remove os caracteres à direita da cadeia de caracteres.

CStringT& TrimRight(XCHAR chTarget);
CStringT& TrimRight(PCXSTR pszTargets);
CStringT& TrimRight();

Parâmetros

chTarget
O caractere de destino a ser removido.

pszTargets
Um ponteiro para uma cadeia de caracteres que contém os caracteres de destino a serem removidos. Todas as ocorrências à direita de caracteres em pszTargets serão removidas do objeto CStringT.

Valor de Devolução

Retorna o objeto CStringT que contém a cadeia de caracteres removida.

Comentários

Remove as ocorrências à direita de um dos seguintes:

  • O caractere especificado por chTarget.

  • Todos os caracteres encontrados na cadeia de caracteres especificada por pszTargets.

  • Espaço em branco.

A versão CStringT& TrimRight(XCHAR chTarget) aceita um parâmetro de caractere e remove todas as cópias desse caractere do final dos dados da cadeia de caracteres CStringT. Ela começa no final da cadeia de caracteres e trabalha no sentido de trás para frente. Ela para quando encontra um caractere diferente ou quando CStringT fica sem dados de caractere.

A versão CStringT& TrimRight(PCXSTR pszTargets) aceita uma cadeia de caracteres terminada em nulo que contém todos os diferentes caracteres a serem pesquisados. Ela remove todas as cópias desses caracteres no objeto CStringT. Ela começa no final da cadeia de caracteres e trabalha no sentido de trás para frente. Ela é interrompida quando encontra um caractere que não está na cadeia de caracteres de destino ou quando CStringT fica sem dados de caractere. Ela não tenta corresponder toda a cadeia de caracteres de destino a uma substring no final de CStringT.

A versão CStringT& TrimRight() não requer parâmetros. Ela remove todos os caracteres de espaço em branco à direita do final da cadeia de caracteres CStringT. Os caracteres de espaço em branco podem ser quebras de linha, espaços ou guias.

Exemplo

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString str;
str = _T("Soccer is best!?!?!?!?!");

_tprintf_s(_T("Before: \"%s\"\n"), (LPCTSTR)str);
_tprintf_s(_T("After : \"%s\"\n"), (LPCTSTR)str.TrimRight(_T("?!")));

// Output:
// --------------------------
// Before: Soccer is best!?!?!?!?!
// After: Soccer is best

Confira também

Gráfico da hierarquia
Classes compartilhadas ATL/MFC
Classe CSimpleStringT