CStringT Classe

Esta classe representa um CStringT objeto.

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

StringTraits
Determina se a classe string precisa de suporte à biblioteca C Run-Time (CRT) e onde os recursos de cadeia de caracteres estão localizados. Pode ser um dos seguintes:

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

  A classe requer suporte a CRT e procura cadeias de caracteres de recursos 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 a CRT e procura cadeias de caracteres de recursos 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 CRT e procura cadeias de caracteres de recursos usando o algoritmo de pesquisa MFC padrão.

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

  A classe não requer suporte a CRT e procura cadeias de caracteres de recursos usando o algoritmo de pesquisa MFC padrão.

Membros

Construtores Públicos

Métodos Públicos

Operadores

Observações

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

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

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

Se estiver a utilizar numa aplicação ATL:

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

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

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

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

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

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

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

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

• Gerenciamento de memória personalizado para buffers de cadeia de caracteres. Para obter mais informações, consulte Gerenciamento de memória e CStringT.

Tipos predefinidos CStringT

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

Hierarquia de herança

CSimpleStringT

CStringT

Requerimentos

CStringT::AllocSysString

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

BSTR AllocSysString() const;

Valor de retorno

A cadeia de caracteres recém-alocada.

Observações

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

Geralmente, se essa cadeia de caracteres é passada para uma função COM como um [in] parâmetro, isso requer que o chamador libere a cadeia de caracteres. Isso pode ser feito usando , conforme SysFreeStringdescrito no SDK do Windows. Para obter mais informações, consulte Alocando e liberando memória para um BSTRarquivo .

Para obter mais informações sobre funções de alocação OLE no Windows, consulte 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 neste CStringT objeto do conjunto de caracteres ANSI para o conjunto de caracteres OEM.

void AnsiToOem();

Observações

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

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.

Observações

Esta função formata e acrescenta uma série de caracteres e valores no CStringT. Cada argumento opcional (se houver) é convertido e acrescentado de acordo com a especificação de formato correspondente no pszFormat ou a partir 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 _tcscollde texto genérico .

int Collate(PCXSTR psz) const throw();

Parâmetros

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

Valor de retorno

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

Observações

A função _tcscollde texto genérico , que é definida em TCHAR.H, mapeia para strcoll, wcscollou , dependendo _mbscolldo conjunto de caracteres definido em tempo de compilação. Cada função faz uma comparação sensível a 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, consulte strcoll, wcscoll, , _mbscoll, _strcoll_l, _wcscoll_l, _mbscoll_l.

CStringT::CollateNoCase

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

int CollateNoCase(PCXSTR psz) const throw();

Parâmetros

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

Valor de retorno

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

Observações

A função _tcscollde texto genérico , que é definida em TCHAR.H, mapeia para stricoll, wcsicollou , dependendo _mbsicolldo conjunto de caracteres definido em tempo de compilação. Cada função faz uma comparação sem diferenciação de 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, consulte 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 retorno

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

Observações

A função _tcscmpde texto genérico , que é definida em TCHAR.H, mapeia para strcmp, wcscmpou , dependendo _mbscmpdo conjunto de caracteres definido em tempo de compilação. Cada função faz uma comparação sensível a maiúsculas e minúsculas das cadeias de caracteres e não é afetada pela localidade. Para obter mais informações, consulte strcmp, wcscmp, _mbscmp.

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

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 (sem distinção entre maiúsculas e minúsculas).

int CompareNoCase(PCXSTR psz) const throw();

Parâmetros

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

Valor de retorno

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

Observações

A função _tcsicmpde texto genérico , que é definida em TCHAR.H, é mapeada para _stricmp, _wcsicmp ou _mbsicmp, dependendo do conjunto de caracteres definido em tempo de compilação. Cada função faz uma comparação das cadeias de caracteres sem diferenciação de maiúsculas e minúsculas. A comparação depende do LC_CTYPE aspeto da localidade, mas não LC_COLLATE. Para obter mais informações, consulte _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 comprimento nLength, não terminado nulo.

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

ch
Um único personagem.

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

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

strSrc
Um objeto existente CStringT a ser copiado para este CStringT objeto. Para obter mais informações sobre CThisString e CThisSimpleString, consulte a seção Observações.

varSrc
Um objeto variante a ser copiado para este CStringT objeto.

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

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

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

pString
Um identificador para um CStringT objeto.

Observações

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

• CStringT(LPCSTRlpsz): Constrói um Unicode CStringT a partir de uma cadeia de caracteres ANSI. Você também pode usar esse construtor para carregar um recurso de cadeia de caracteres, conforme mostrado no exemplo abaixo.

• CStringT(LPCWSTRlpsz): Constrói um CStringT a partir de uma cadeia de caracteres Unicode.

• CStringT(const unsigned char*psz): Permite construir um CStringT de um ponteiro para unsigned char.

O strSrc parâmetro pode ser um CStringT ou CThisSimpleString objeto. Para CStringT, use uma de suas instanciações padrão (CString, CStringA, ou CStringW); para CThisSimpleString, use um this ponteiro. CThisSimpleStringdeclara uma instância da Class, que é uma classe de cadeia de CSimpleStringTcaracteres menor com menos funcionalidade interna do que a CStringT classe.

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

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

~CStringT() throw();

Observações

Destrói o CStringT objeto.

CStringT::Delete

Exclui um caractere ou caracteres de uma cadeia de caracteres que começa com o caractere no índice determinado.

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

Parâmetros

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

nCount
O número de caracteres a serem removidos.

Valor de retorno

O comprimento da cadeia de caracteres alterada.

Observações

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
Uma substring para pesquisar.

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

ch
Um único caractere para pesquisar.

Valor de retorno

O índice baseado em zero do primeiro caractere neste CStringT objeto que corresponde à substring ou caracteres solicitados; -1 se a substring ou caractere não for encontrado.

Observações

A função está sobrecarregada para aceitar caracteres únicos (semelhante à função strchrde tempo de execução) e cadeias de caracteres (semelhante 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

Procura nesta cadeia de caracteres o primeiro caractere que corresponda a qualquer caractere contido no pszCharSet.

int FindOneOf(PCXSTR pszCharSet) const throw();

Parâmetros

pszCharSet
String contendo caracteres para correspondência.

Valor de retorno

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

Observações

Localiza a primeira ocorrência de qualquer 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 da mesma forma que sprintf_s formata dados em uma matriz de caracteres 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.

Observações

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

A chamada falhará se o próprio objeto string for oferecido como um parâmetro para Format. Por exemplo, o código a seguir causará 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, consulte Sintaxe de especificação de formato: printf e wprintf funções.

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á digitalizado para inserções e formatado de acordo. A cadeia de caracteres de formato é semelhante às cadeias de caracteres de formato de estilo de função printfde tempo de execução, exceto que permite que os parâmetros sejam inseridos em uma ordem arbitrária.

argument
Argumentos opcionais.

Observações

A função requer uma definição de mensagem como entrada. A definição de mensagem é determinada por pszFormat ou a partir do recurso de cadeia de caracteres identificado por nFormatID. A função copia o texto da mensagem formatada para o CStringT objeto, processando quaisquer sequências de inserção incorporadas, se solicitado.

Cada inserção deve ter um parâmetro correspondente seguindo o pszFormat parâmetro ou nFormatID . Dentro do texto da mensagem, várias sequências de escape são suportadas para formatar dinamicamente a mensagem. Para obter mais informações, consulte a função Windows FormatMessage 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á digitalizado para inserções e formatado de acordo. A cadeia de caracteres de formato é semelhante às cadeias de caracteres de formato de estilo de função printfde tempo de execução, exceto que permite que os parâmetros sejam inseridos em uma ordem arbitrária.

pArgList
Ponteiro para uma lista de argumentos.

Observações

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 CStringT objeto, processando quaisquer sequências de inserção incorporadas, se solicitado.

Para obter mais informações, consulte a função Windows FormatMessage 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á digitalizado para inserções e formatado de acordo. A cadeia de caracteres de formato é semelhante às cadeias de caracteres de formato de estilo de função printfde tempo de execução, exceto que permite que os parâmetros sejam inseridos em uma ordem arbitrária.

args
Ponteiro para uma lista de argumentos.

Observações

Grava uma cadeia de caracteres formatada e uma lista variável de argumentos em uma CStringT cadeia de caracteres da mesma forma 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 retorno

Diferente de zero se for bem-sucedido; caso contrário, 0.

Observações

Recupera o valor da variável especificada do bloco de ambiente do processo de chamada. O valor está na forma 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 determinado 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 inserido.

Valor de retorno

O comprimento da cadeia de caracteres alterada.

Observações

O iIndex parâmetro 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 do que o comprimento da string, a função irá concatenar a string presente 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 mais nCount à esquerda deste CStringT objeto e retorna uma cópia da substring extraída.

CStringT Left(int nCount) const;

Parâmetros

nCount
O número de caracteres a serem extraídos desse CStringT objeto.

Valor de retorno

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

Observações

Se nCount exceder o comprimento da cadeia de caracteres, toda a cadeia de caracteres será extraída. Left é semelhante à função Basic Left .

Para conjuntos de caracteres de vários bytes (MBCS), nCount trata cada sequência de 8 bits como um caractere, de modo que nCount retorna o número de caracteres de vários bytes multiplicado 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 existente CStringT .

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
Um ID de recurso de cadeia de caracteres do Windows.

wLanguageID
O idioma do recurso de cadeia de caracteres.

Valor de retorno

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

Observações

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

Exemplo

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

CAtlString s;
s.LoadString(IDS_APP_TITLE);   

CStringT::MakeLower

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

CStringT& MakeLower();

Valor de retorno

A cadeia de caracteres minúscula 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 CStringT objeto.

CStringT& MakeReverse();

Valor de retorno

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 CStringT objeto em uma cadeia de caracteres maiúsculas.

CStringT& MakeUpper();

Valor de retorno

A cadeia de caracteres maiúscula resultante.

Observações

Exemplo

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

CAtlString s(_T("abc"));

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

CStringT::Mid

Extrai uma substring de caracteres de comprimento nCount deste CStringT objeto, 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 neste CStringT objeto que deve ser incluído na substring extraída.

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

Valor de retorno

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

Observações

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

Para conjuntos de caracteres multibyte (MBCS), nCount refere-se a cada caractere de 8 bits, ou seja, um byte principal e trail 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 neste CStringT objeto do conjunto de caracteres OEM para o conjunto de caracteres ANSI.

void OemToAnsi();

Observações

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

Exemplo

Veja o exemplo para 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 esta cadeia de caracteres.

str
Uma referência a um objeto CThisSimpleString.

bMFCDLL
Um booleano especificando se o projeto é uma DLL MFC ou não.

BaseType
O tipo base de cadeia de caracteres.

var
Um objeto variante para atribuir a essa cadeia de caracteres.

ch
Um caractere ANSI ou Unicode para atribuir à cadeia de caracteres.

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

Observações

O operador de atribuição aceita outro CStringT objeto, um ponteiro de caractere ou um único caractere. Exceções de memória podem ocorrer sempre que você usar esse operador porque um novo armazenamento pode ser alocado.

Para obter informações sobre CThisSimpleStringo , consulte a seção Comentários do CStringT::CStringT.

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
A CStringT para concatenar com uma cadeia de caracteres ou caractere.

str2
A CStringT para concatenar com uma cadeia de caracteres ou caractere.

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

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

Observações

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

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 booleano especificando se o projeto é uma DLL MFC ou não.

BaseType
O tipo base de cadeia de caracteres.

var
Um objeto variante para concatenar 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
A CStringT para concatenar a esta cadeia de caracteres.

Observações

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

Para obter informações sobre CThisSimpleStringo , consulte a seção Comentários do CStringT::CStringT.

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
A CStringT para comparação.

str2
A 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.

Observações

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
A CStringT para comparação.

str2
A 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.

Observações

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 no lado esquerdo do operador é menor do que a cadeia de caracteres no lado direito.

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
A CStringT para comparação.

str2
A 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.

Observações

Uma comparação lexicográfica entre cordas, caractere por caractere até:

• Ele encontra dois caracteres correspondentes desiguais, e o resultado de sua comparação é tomado como o resultado da comparação entre as cadeias de caracteres.

• Ele não encontra desigualdades, mas uma string tem mais caracteres do que a outra, e a string mais curta é considerada menor do que a string mais longa.

• Ele não encontra desigualdades e descobre que as cadeias de caracteres têm o mesmo número de caracteres, e assim 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 no lado esquerdo do operador é maior do que a cadeia de caracteres no lado direito.

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
A CStringT para comparação.

str2
A 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.

Observações

Uma comparação lexicográfica entre cordas, caractere por caractere até:

• Ele encontra dois caracteres correspondentes desiguais, e o resultado de sua comparação é tomado como o resultado da comparação entre as cadeias de caracteres.

• Ele não encontra desigualdades, mas uma string tem mais caracteres do que a outra, e a string mais curta é considerada menor do que a string mais longa.

• Ele não encontra desigualdades e descobre que as cadeias de caracteres têm o mesmo número de caracteres, então as cadeias 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 no lado esquerdo do operador é menor ou igual à cadeia de caracteres no lado direito.

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
A CStringT para comparação.

str2
A 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.

Observações

Uma comparação lexicográfica entre cordas, caractere por caractere até:

• Ele encontra dois caracteres correspondentes desiguais, e o resultado de sua comparação é tomado como o resultado da comparação entre as cadeias de caracteres.

• Ele não encontra desigualdades, mas uma string tem mais caracteres do que a outra, e a string mais curta é considerada menor do que a string mais longa.

• Ele não encontra desigualdades e descobre que as cadeias de caracteres têm o mesmo número de caracteres, então as cadeias 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 no lado esquerdo do operador é maior ou igual à cadeia de caracteres no lado direito.

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
A CStringT para comparação.

str2
A 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.

Observações

Uma comparação lexicográfica entre cordas, caractere por caractere até:

• Ele encontra dois caracteres correspondentes desiguais, e o resultado de sua comparação é tomado como o resultado da comparação entre as cadeias de caracteres.

• Ele não encontra desigualdades, mas uma string tem mais caracteres do que a outra, e a string mais curta é considerada menor do que a string mais longa.

• Ele não encontra desigualdades e descobre que as cadeias de caracteres têm o mesmo número de caracteres, então as cadeias 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 retorno

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

Observações

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

Existem duas versões do 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 caracteres armazenados no 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ído por pszNew.

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

chOld
O caractere a ser substituído por chNew.

chNew
O caractere substituindo chOld.

Valor de retorno

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

Observações

Replace pode alterar o comprimento da cadeia de caracteres porque pszNew e pszOld não precisa ser o mesmo comprimento, 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.

Exemplos de CStringT instâncias são CString, CStringAe CStringW.

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

Para CString, o tipo de dados de caractere é selecionado em tempo de compilação, com base na definição das constantes na tabela a seguir.

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

Procura neste CStringT objeto a última correspondência de um personagem.

int ReverseFind(XCHAR ch) const throw();

Parâmetros

ch
O personagem a procurar.

Valor de retorno

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

Observações

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

Exemplo

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

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

CStringT::Right

Extrai os últimos caracteres (ou seja, os mais à direita) nCount desse CStringT objeto e retorna uma cópia da subcadeia de caracteres extraída.

CStringT Right(int nCount) const;

Parâmetros

nCount
O número de caracteres a serem extraídos desse CStringT objeto.

Valor de retorno

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

Observações

Se nCount exceder o comprimento da cadeia de caracteres, toda a cadeia de caracteres será extraída. Right é semelhante à função Basic Right (exceto que os índices em 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 principal e trail 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 e pbstr copia o CStringT conteúdo do objeto para ele, incluindo o NULL personagem.

BSTR SetSysString(BSTR* pbstr) const;

Parâmetros

pbstr
Um ponteiro para uma cadeia de caracteres.

Valor de retorno

A nova cadeia de caracteres.

Observações

Dependendo do conteúdo do CStringT objeto, o valor do BSTR referenciado por pbstr pode mudar. A função lança um CMemoryException se a memória insuficiente existe.

Esta função é normalmente usada para alterar o valor de cadeias de caracteres passadas por referência para 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 retorno

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

Observações

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

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

_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 retorno

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

Observações

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 retorno

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

Observações

A Tokenize função 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 para Tokenize a função começa em iStart, ignora os delimitadores à esquerda e retorna um CStringT objeto que contém o token atual, que é a cadeia de caracteres até o próximo caractere delimitador. O valor de é atualizado para ser a posição após o caractere delimitador final, ou -1 se o final da cadeia de iStart caracteres foi atingido. Mais tokens podem ser quebrados do resto da string de destino por uma série de chamadas para Tokenize, usando iStart para manter o controle de onde na string 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 do CRT tokenize funções como strtok_s, _strtok_s_l, , wcstok_s, _wcstok_s_l_mbstok_s, , _mbstok_s_l, não Tokenize 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 deste exemplo é a seguinte:

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

CStringT::Trim

Corta 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 cortado.

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

Valor de retorno

Retorna a cadeia de caracteres cortada.

Observações

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

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

CStringT::TrimLeft

Corta os caracteres principais da cadeia de caracteres.

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

Parâmetros

chTarget
O caractere de destino a ser cortado.

pszTargets
Um ponteiro para uma cadeia de caracteres que contém os caracteres de destino a serem cortados. Todas as ocorrências principais de caracteres serão pszTargets cortadas do CStringT objeto.

Valor de retorno

A cadeia de caracteres cortada resultante.

Observações

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

Corta 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 cortado.

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

Valor de retorno

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

Observações

Remove 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 CStringT& TrimRight(XCHAR chTarget) versão aceita um parâmetro de caractere e remove todas as cópias desse caractere do final dos dados da cadeia de CStringT caracteres. Começa no final da corda e trabalha em direção à frente. Ele para quando encontra um caractere diferente ou quando CStringT fica sem dados de caracteres.

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

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

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

Ver também

Gráfico de Hierarquia
Classes compartilhadas ATL/MFC
CSimpleStringT Classe