Clase CStringT

  • Artículo

Esta clase representa un objeto CStringT.

Sintaxis

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

Parámetros

BaseType
Tipo de carácter de la clase de cadena. Puede ser uno de los siguientes:

  • char (para cadenas de caracteres ANSI).

  • wchar_t (para cadenas de caracteres Unicode).

  • TCHAR (para cadenas de caracteres ANSI y Unicode).

StringTraits
Determina si la clase de cadena necesita compatibilidad con la biblioteca C Run-Time (CRT) y dónde se encuentran los recursos de cadena. Puede ser uno de los siguientes:

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

    La clase requiere compatibilidad con CRT y busca cadenas de recursos en el módulo especificado por m_hInstResource (un miembro de la clase de módulo de la aplicación).

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

    La clase no requiere compatibilidad con CRT y busca cadenas de recursos en el módulo especificado por m_hInstResource (un miembro de la clase de módulo de la aplicación).

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

    La clase requiere compatibilidad con CRT y busca cadenas de recursos mediante el algoritmo de búsqueda de MFC estándar.

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

    La clase no requiere compatibilidad con CRT y busca cadenas de recursos mediante el algoritmo de búsqueda estándar de MFC.

Miembros

Constructores públicos

Nombre Descripción
CStringT::CStringT Construye un objeto CStringT de varias maneras.
CStringT::~CStringT Destruye un objeto CStringT .

Métodos públicos

Nombre Descripción
CStringT::AllocSysString Asigna un objeto BSTR a partir de los datos de CStringT.
CStringT::AnsiToOem Realiza una conversión local del juego de caracteres ANSI en el juego de caracteres OEM.
CStringT::AppendFormat Anexa datos con formato a un objeto CStringT existente.
CStringT::Collate Compara dos cadenas (distinción entre mayúsculas y minúsculas, usa información específica de la configuración regional).
CStringT::CollateNoCase Compara dos cadenas (sin distinción entre mayúsculas y minúsculas, usa información específica de la configuración regional).
CStringT::Compare Compara dos cadenas (distinción entre mayúsculas y minúsculas).
CStringT::CompareNoCase Compara dos cadenas (sin distinción entre mayúsculas y minúsculas).
CStringT::Delete Elimina uno o varios caracteres de una cadena.
CStringT::Find Busca un carácter o subcadena dentro de una cadena más grande.
CStringT::FindOneOf Busca el primer carácter coincidente de un juego de caracteres.
CStringT::Format Aplica formato a la cadena como hace sprintf.
CStringT::FormatMessage Aplica formato a una cadena de mensaje.
CStringT::FormatMessageV Aplica formato a una cadena de mensaje mediante una lista de argumentos variables.
CStringT::FormatV Aplica formato a la cadena mediante una lista variable de argumentos.
CStringT::GetEnvironmentVariable Establece la cadena en el valor de la variable de entorno especificada.
CStringT::Insert Inserta un solo carácter o una subcadena en el índice especificado dentro de la cadena.
CStringT::Left Extrae la parte izquierda de una cadena.
CStringT::LoadString Carga un objeto existente CStringT desde un recurso de Windows.
CStringT::MakeLower Convierte todos los caracteres de esta cadena en caracteres en minúsculas.
CStringT::MakeReverse Invierte la cadena.
CStringT::MakeUpper Convierte todos los caracteres de esta cadena en caracteres en mayúsculas.
CStringT::Mid Extrae la parte central de una cadena.
CStringT::OemToAnsi Realiza una conversión local del juego de caracteres OEM en el juego de caracteres ANSI.
CStringT::Remove Quita los caracteres indicados de una cadena.
CStringT::Replace Reemplaza los caracteres indicados por otros caracteres.
CStringT::ReverseFind Busca un carácter dentro de una cadena más grande; comienza desde el final.
CStringT::Right Extrae la parte derecha de una cadena.
CStringT::SetSysString Establece un objeto BSTR existente con datos de un objeto CStringT.
CStringT::SpanExcluding Extrae caracteres de la cadena, empezando por el primer carácter, que no están en el juego de caracteres identificados por pszCharSet.
CStringT::SpanIncluding Extrae una subcadena que contiene solo los caracteres de un juego.
CStringT::Tokenize Extrae los tokens especificados en una cadena de destino.
CStringT::Trim Quita todos los caracteres de espacio en blanco iniciales y finales de una cadena.
CStringT::TrimLeft Recorta todos los caracteres de espacio en blanco iniciales de la cadena.
CStringT::TrimRight Recorta los caracteres de espacio en blanco de la cadena.

Operadores

Nombre Descripción
CStringT::operator = Asigna un nuevo valor a un objeto CStringT.
CStringT::operator + Concatena dos cadenas, o un carácter y una cadena.
CStringT::operator += Concatena una nueva cadena al final de una cadena existente.
CStringT::operator == Determina si dos cadenas son lógicamente iguales.
CStringT::operator != Determina si dos cadenas no son lógicamente iguales.
CStringT::operator < Determina si la cadena al lado izquierdo del operador es menor que la cadena al lado derecho.
CStringT::operator > Determina si la cadena al lado izquierdo del operador es mayor que la cadena al lado derecho.
CStringT::operator <= Determina si la cadena al lado izquierdo del operador es menor o igual que la cadena al lado derecho.
CStringT::operator >= Determina si la cadena al lado izquierdo del operador es mayor o igual que la cadena al lado derecho.

Comentarios

CStringT hereda de CSimpleStringT Class. Las características avanzadas, como la manipulación de caracteres, el orden y la búsqueda, se implementan mediante CStringT.

Nota:

Los objetos CStringT son capaces de producir excepciones. Esto ocurre si, por cualquier motivo, un objeto CStringT se queda sin memoria.

Un objeto CStringT consta de una secuencia de caracteres de longitud variable. CStringT proporciona funciones y operadores que usan una sintaxis similar a la de Basic. Los operadores de concatenación y comparación, junto con la administración simplificada de memoria, hacen que los objetos CStringT sean más fáciles de usar que las matrices de caracteres ordinarios.

Nota:

Aunque es posible crear instancias de CStringT que contengan caracteres NULL insertados, se recomienda no hacerlo. Llamar a métodos y operadores de objetos CStringT que contienen caracteres NULL insertados puede generar resultados no deseados.

Mediante diferentes combinaciones de los parámetros BaseType y StringTraits, los objetos CStringT pueden aparecer en los siguientes tipos, que han sido predefinidos por las bibliotecas ATL.

Si se usan en una aplicación ATL:

CString, CStringA y CStringW se exportan desde el archivo DLL de MFC (MFC90.DLL), nunca desde archivos DLL de usuario. Esto se hace para evitar que CStringT se defina varias veces.

Nota:

Si el código contiene la solución alternativa para los errores del enlazador que se describen en Exportación de clases de cadena mediante CStringT, debe quitar ese código. Ya no es necesario.

Los siguientes tipos de cadena están disponibles en aplicaciones basadas en MFC:

Tipo CStringT Declaración
CStringA Cadena de tipo de caracteres ANSI compatible con CRT.
CStringW Cadena de tipo de caracteres Unicode compatible con CRT.
CString Tipos de caracteres ANSI y Unicode compatibles con CRT.

Los siguientes tipos de cadena están disponibles en proyectos donde se define ATL_CSTRING_NO_CRT:

Tipo CStringT Declaración
CAtlStringA Cadena de tipo de carácter ANSI sin compatibilidad con CRT.
CAtlStringW Cadena de tipo de carácter Unicode sin compatibilidad con CRT.
CAtlString Tipos de caracteres ANSI y Unicode sin compatibilidad con CRT.

Los siguientes tipos de cadena están disponibles en proyectos donde no se define ATL_CSTRING_NO_CRT:

Tipo CStringT Declaración
CAtlStringA Cadena de tipo de caracteres ANSI compatible con CRT.
CAtlStringW Cadena de tipo de caracteres Unicode compatible con CRT.
CAtlString Tipos de caracteres ANSI y Unicode compatibles con CRT.

Los objetos CString también tienen las siguientes características:

  • Los objetos CStringT pueden crecer debido a las operaciones de concatenación.

  • Los objetos CStringT siguen la "semántica de valor". Piense en un objeto CStringT como una cadena real, no como puntero a una cadena.

  • Puede sustituir libremente objetos CStringT por los argumentos de función PCXSTR.

  • Administración de memoria personalizada para búferes de cadenas. Para más información, consulte Administración de memoria y CStringT.

Tipos predefinidos de CStringT

Dado que CStringT usa un argumento de plantilla para definir el tipo de carácter (o wchar_tchar) admitido, los tipos de parámetros de método pueden ser complicados en ocasiones. Para simplificar este problema, se define y se usa un conjunto de tipos predefinidos en toda la clase CStringT. En la tabla siguiente se muestran los diversos tipos:

Nombre Descripción
XCHAR Carácter único (o wchar_tchar) con el mismo tipo de carácter que el objeto CStringT.
YCHAR Carácter único (o wchar_tchar) con el tipo de carácter opuesto al del objeto CStringT.
PXSTR Puntero a una cadena de caracteres (o wchar_tchar) con el mismo tipo de carácter que el objeto CStringT.
PYSTR Puntero a una cadena de caracteres (o wchar_tchar) con el tipo de carácter opuesto al del objeto CStringT.
PCXSTR Puntero a una cadena de caracteres const (o wchar_tchar) con el mismo tipo de carácter que el objeto CStringT.
PCYSTR Puntero a una cadena de caracteres const (o wchar_tchar) con el tipo de carácter opuesto al del objeto CStringT.

Nota:

El código donde se usó previamente métodos no documentados de CString (como AssignCopy) debe reemplazarse por código donde se usen los siguientes métodos documentados de CStringT (como GetBuffer o ReleaseBuffer). Estos métodos se heredan de CSimpleStringT.

Jerarquía de herencia

CSimpleStringT

CStringT

Requisitos

Encabezado Se usa para
cstringt.h Objetos de cadena solo de MFC
atlstr.h Objetos de cadena que no son MFC

CStringT::AllocSysString

Asigna una cadena compatible con Automation del tipo BSTR y copia en ella el contenido del objeto CStringT, incluido el carácter nulo de terminación.

BSTR AllocSysString() const;

Valor devuelto

Cadena recién asignada.

Comentarios

En los programas de MFC, se produce una excepción CMemoryException Class si no hay memoria suficiente. En los programas ATL, se produce una excepción CAtlException. Esta función se usa normalmente para devolver cadenas para Automation.

Normalmente, si esta cadena se pasa a una función COM como un parámetro [in],es necesario que el autor de la llamada libere la cadena. Esto se puede hacer mediante SysFreeString, como se describe en Windows SDK. Para más información, consulte Asignación y liberación de memoria para BSTR.

Para más información sobre las funciones de asignación OLE en Windows, consulte SysAllocString en Windows SDK.

Ejemplo

El siguiente ejemplo muestra el 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

Convierte todos los caracteres de este objeto CStringT del juego de caracteres ANSI al juego de caracteres OEM.

void AnsiToOem();

Comentarios

La función no está disponible si se define _UNICODE.

Ejemplo

// 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

Anexa datos con formato a un objeto CStringT existente.

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

Parámetros

pszFormat
Cadena de control de formato.

nFormatID
Identificador de recurso de cadena que contiene la cadena de control de formato.

argument
Argumentos opcionales.

Comentarios

Esta función aplica formato a una serie de caracteres y valores en CStringT y los anexa. Cada argumento opcional (si lo hay) se convierte y anexa según la especificación de formato correspondiente en pszFormat o desde el recurso de cadena identificado por nFormatID.

Ejemplo

// 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 dos cadenas mediante la función de texto genérico _tcscoll.

int Collate(PCXSTR psz) const throw();

Parámetros

psz
La otra cadena usada para la comparación.

Valor devuelto

Cero si las cadenas son idénticas, < 0 si este objeto CStringT es menor que psz o > 0 si este objeto CStringT es mayor que psz.

Comentarios

La función de texto genérico _tcscoll, que se define en TCHAR.H, se asigna a strcoll, wcscoll o _mbscoll, según el juego de caracteres definido en tiempo de compilación. Cada una de estas funciones realiza una comparación que distingue mayúsculas y minúsculas de las cadenas, de acuerdo con la página de códigos actualmente en uso. Para más información, consulte strcoll, wcscoll, _mbscoll, _strcoll_l, _wcscoll_l, _mbscoll_l.

CStringT::CollateNoCase

Compara dos cadenas mediante la función de texto genérico _tcscoll.

int CollateNoCase(PCXSTR psz) const throw();

Parámetros

psz
La otra cadena usada para la comparación.

Valor devuelto

Cero si las cadenas son idénticas, < 0 si este objeto CStringT es menor que psz o > 0 si este objeto CStringT es mayor que psz (en todos los casos, se omite la distinción entre mayúsculas y minúsculas).

Comentarios

La función de texto genérico _tcscoll, que se define en TCHAR.H, se asigna a stricoll, wcsicoll o _mbsicoll, según el juego de caracteres definido en tiempo de compilación. Cada una de estas funciones realiza una comparación sin distinguir mayúsculas de minúsculas de las cadenas, de acuerdo con la página de códigos actualmente en uso. Para más información, consulte strcoll, wcscoll, _mbscoll, _strcoll_l, _wcscoll_l, _mbscoll_l.

Ejemplo

// 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 dos cadenas (distinción entre mayúsculas y minúsculas).

int Compare(PCXSTR psz) const;

Parámetros

psz
La otra cadena usada para la comparación.

Valor devuelto

Cero si las cadenas son idénticas, < 0 si este objeto CStringT es menor que psz o > 0 si este objeto CStringT es mayor que psz.

Comentarios

La función de texto genérico _tcscmp, que se define en TCHAR.H, se asigna a strcmp, wcscmp o _mbscmp, según el juego de caracteres definido en tiempo de compilación. Cada función realiza una comparación que distingue mayúsculas de minúsculas de las cadenas y no se ve afectada por la configuración regional. Para obtener más información, consulte strcmp, wcscmp, _mbscmp.

Si la cadena contiene valores NULL insertados, para fines de comparación, la cadena se considera truncada en el primer carácter nulo insertado.

Ejemplo

El siguiente ejemplo muestra el 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 dos cadenas (sin distinción entre mayúsculas y minúsculas).

int CompareNoCase(PCXSTR psz) const throw();

Parámetros

psz
La otra cadena usada para la comparación.

Valor devuelto

Cero si las cadenas son idénticas, < 0 si este objeto CStringT es menor que psz o > 0 si este objeto CStringT es mayor que psz (en todos los casos, se omite la distinción entre mayúsculas y minúsculas).

Comentarios

La función de texto genérico _tcsicmp, que se define en TCHAR.H, se asigna a _stricmp, _wcsicmp o _mbsicmp, según el juego de caracteres definido en tiempo de compilación. Cada función hace una comparación sin distinción entre mayúsculas y minúsculas de las cadenas. La comparación depende del aspecto de LC_CTYPE de la configuración regional, pero no de LC_COLLATE. Para más información, consulte _stricmp, _wcsicmp, _mbsicmp, _stricmp_l, _wcsicmp_l, _mbsicmp_l.

Ejemplo

// 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

Construye un 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
Puntero a una matriz de caracteres de longitud nLength, no terminada en NULL.

nLength
Recuento del número de caracteres de pch.

ch
Un solo carácter.

pszSrc
Cadena terminada en NULL que se va a copiar en este objeto CStringT.

pStringMgr
Puntero al administrador de memoria del objeto CStringT. Para más información sobre IAtlStringMgr y la administración de memoria de CStringT, consulte Administración de memoria con CStringT.

strSrc
Objeto CStringT existente que se va a copiar en este objeto CStringT. Para más información sobre CThisString y CThisSimpleString, consulte la sección de comentarios.

varSrc
Un objeto VARIANT que se va a copiar en este objeto CStringT.

BaseType
Tipo de carácter de la clase de cadena. Puede ser uno de los siguientes:

char (para cadenas de caracteres ANSI).

wchar_t (para cadenas de caracteres Unicode).

TCHAR (para cadenas de caracteres ANSI y Unicode).

bMFCDLL
Valor booleano que especifica si el proyecto es un archivo DLL de MFC (TRUE) o no (FALSE).

SystemString
Debe ser System::String y el proyecto debe compilarse con /clr.

pString
Controlador para el objeto CStringT.

Comentarios

Dado que los constructores copian los datos de entrada en un nuevo almacenamiento asignado, pueden producirse excepciones de memoria. Algunos de estos constructores actúan como funciones de conversión. Esto le permite sustituir, por ejemplo, un objeto LPTSTR donde se espera un objeto CStringT.

  • CStringT( LPCSTRlpsz ): construye un objeto CStringT Unicode a partir de una cadena ANSI. También puede usar este constructor para cargar un recurso de cadena como se muestra en el ejemplo siguiente.

  • CStringT(LPCWSTRlpsz ): construye un objeto CStringT a partir de una cadena Unicode.

  • CStringT( const unsigned char*psz ): permite construir un objeto CStringT a partir de un puntero a unsigned char.

Nota:

Defina la macro _CSTRING_DISABLE_NARROW_WIDE_CONVERSION para desactivar la conversión implícita de cadenas entre cadenas ANSI y Unicode. La macro se excluye de constructores de compilación que admiten la conversión.

El parámetro strSrc puede ser un objeto CStringT o CThisSimpleString. Para CStringT, use una de sus instancias predeterminadas (CString, CStringA o CStringW); para CThisSimpleString, use un puntero this. CThisSimpleString declara una instancia de la clase CSimpleStringT, que es una clase de cadena más pequeña con menos funcionalidad integrada que la clase CStringT.

El operador de sobrecarga CSimpleStringT<>&() construye un objeto CStringT a partir de una declaración CSimpleStringT.

Nota:

Aunque es posible crear instancias de CStringT que contengan caracteres NULL insertados, se recomienda no hacerlo. Llamar a métodos y operadores de objetos CStringT que contienen caracteres NULL insertados puede generar resultados no deseados.

Ejemplo

// 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

Destruye el objeto CStringT.

~CStringT() throw();

Comentarios

Destruye el objeto CStringT.

CStringT::Delete

Elimina uno o varios caracteres de una cadena a partir del carácter situado en el índice especificado.

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

Parámetros

iIndex
El índice de base cero del primer carácter del objeto CStringT que se elimina.

nCount
Número de caracteres que se van a quitar.

Valor devuelto

Longitud de la cadena modificada.

Comentarios

Si nCount es mayor que la cadena, se quitará el resto de la cadena.

Ejemplo

// 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

Busca en esta cadena la primera coincidencia de un carácter o subcadena.

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

Parámetros

pszSub
Subcadena que se busca.

iStart
Índice del carácter de la cadena con el que se va a comenzar la búsqueda, o 0 para comenzar desde el principio.

ch
Un solo carácter que se va a buscar.

Valor devuelto

Índice de base cero del primer carácter de este objeto CStringT que coincide con la subcadena o los caracteres solicitados; -1 si no se encuentra la subcadena o el carácter.

Comentarios

La función se sobrecarga para aceptar caracteres individuales (similar a la función strchr en tiempo de ejecución ) y cadenas (similar a strstr).

Ejemplo

// 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

Busca en esta cadena el primer carácter que coincida con cualquier carácter contenido en pszCharSet.

int FindOneOf(PCXSTR pszCharSet) const throw();

Parámetros

pszCharSet
Cadena que contiene caracteres con los que buscar coincidencias.

Valor devuelto

Índice de base cero del primer carácter de esta cadena que también está en pszCharSet; -1 si no hay ninguna coincidencia.

Comentarios

Busca la primera aparición de cualquiera de los caracteres de pszCharSet.

Ejemplo

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

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

CStringT::Format

Escribe datos con formato en un objeto CStringT la misma manera que sprintf_s aplica formato a los datos en una matriz de caracteres de estilo C.

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

Parámetros

nFormatID
Identificador de recurso de cadena que contiene la cadena de control de formato.

pszFormat
Cadena de control de formato.

argument
Argumentos opcionales.

Comentarios

La función aplica formato a una serie de caracteres y valores de CStringT y los almacena. Cada argumento opcional (si existe) se convierte y genera según la especificación de formato correspondiente en pszFormat o desde el recurso de cadena identificado por nFormatID.

Se producirá un error en la llamada si el propio objeto de cadena se ofrece como parámetro a Format. Por ejemplo, el código siguiente provocará resultados imprevisibles:

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

Para más información, consulte Sintaxis de especificación de formato: printf funciones wprintf y .

Ejemplo

// 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

Aplica formato a una cadena de mensaje.

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

Parámetros

nFormatID
Identificador de recurso de cadena que contiene el texto del mensaje sin formato.

pszFormat
Apunta a la cadena de control de formato. Se examinarán las inserciones y se le aplicara formato en consecuencia. La cadena de formato es similar a las cadenas de formato de estilo printf de las funciones en tiempo de ejecución, excepto que permite insertar los parámetros en un orden arbitrario.

argument
Argumentos opcionales.

Comentarios

La función requiere una definición de mensaje como entrada. La definición del mensaje viene determinada por pszFormat o por el recurso de cadena identificado por nFormatID. La función copia el texto del mensaje con formato en el objeto CStringT y procesa las secuencias de inserción insertadas si se solicita.

Nota:

FormatMessage intenta asignar memoria del sistema para la cadena a la que se acaba de aplicar formato. Si se produce un error en este intento, se inicia automáticamente una excepción de memoria.

Cada inserción debe tener un parámetro correspondiente después del parámetro pszFormat o nFormatID. Dentro del texto del mensaje, se admiten varias secuencias de escape para aplicar formato al mensaje de forma dinámica. Para más información, consulte la función FormatMessage en Windows SDK.

Ejemplo

// 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

Aplica formato a una cadena de mensaje mediante una lista de argumentos variables.

void FormatMessageV(PCXSTR pszFormat, va_list* pArgList);

Parámetros

pszFormat
Apunta a la cadena de control de formato. Se examinarán las inserciones y se le aplicara formato en consecuencia. La cadena de formato es similar a las cadenas de formato de estilo printf de las funciones en tiempo de ejecución, excepto que permite insertar los parámetros en un orden arbitrario.

pArgList
Puntero a una lista de argumentos.

Comentarios

La función requiere una definición de mensaje como entrada, determinada por pszFormat. La función copia el texto del mensaje con formato y una lista variable de argumentos en el objeto CStringT, y se procesan las secuencias de inserción insertadas si se solicita.

Nota:

FormatMessageV llama a CStringT::FormatMessage, que intenta asignar memoria del sistema a la cadena a la que se acaba de aplicar formato. Si se produce un error en este intento, se inicia automáticamente una excepción de memoria.

Para más información, consulte la función FormatMessage en Windows SDK.

CStringT::FormatV

Aplica formato a una cadena de mensaje mediante una lista de argumentos variables.

void FormatV(PCXSTR pszFormat, va_list args);

Parámetros

pszFormat
Apunta a la cadena de control de formato. Se examinarán las inserciones y se le aplicara formato en consecuencia. La cadena de formato es similar a las cadenas de formato de estilo printf de las funciones en tiempo de ejecución, excepto que permite insertar los parámetros en un orden arbitrario.

args
Puntero a una lista de argumentos.

Comentarios

Escribe una cadena con formato y una lista variable de argumentos en una cadena CStringT de la misma manera que vsprintf_s aplica formato a los datos de una matriz de caracteres de estilo C.

Ejemplo

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

Establece la cadena en el valor de la variable de entorno especificada.

BOOL GetEnvironmentVariable(PCXSTR pszVar);

Parámetros

pszVar
Puntero a una cadena terminada en NULL que especifica la variable de entorno.

Valor devuelto

Si es correcta, su valor es distinto de cero. En caso contrario, es cero.

Comentarios

Recupera el valor de la variable especificada del bloque de entorno del proceso de llamada. El valor tiene la forma de una cadena de caracteres terminada en NULL.

Ejemplo

// 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

Inserta un solo carácter o una subcadena en el índice especificado dentro de la cadena.

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

Parámetros

iIndex
Índice del carácter antes del cual tendrá lugar la inserción.

psz
Puntero a la subcadena que se va a insertar.

ch
Carácter que se va a insertar.

Valor devuelto

Longitud de la cadena modificada.

Comentarios

El parámetro iIndex identifica el primer carácter que se moverá para dejar espacio para el carácter o la subcadena. Si nIndex es cero, la inserción se producirá antes de toda la cadena. Si nIndex es mayor que la longitud de la cadena, la función concatenará la cadena actual y el nuevo material proporcionado por ch o psz.

Ejemplo

// 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

Extrae los caracteres nCount situados más a la izquierda de este objeto CStringT y devuelve una copia de la subcadena extraída.

CStringT Left(int nCount) const;

Parámetros

nCount
Número de caracteres que se va a extraer de este objeto CStringT.

Valor devuelto

El objeto CStringT que contiene una copia del rango de caracteres especificado. El objeto CStringT devuelto puede estar vacío.

Comentarios

Si nCount supera la longitud de la cadena, se extrae la cadena completa. Left es similar a la función Left de Basic.

En los juegos de caracteres multibyte (MBCS), nCount trata cada secuencia de 8 bits como un carácter, de modo que nCount devuelve el número de caracteres multibyte multiplicado por dos.

Ejemplo

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

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

CStringT::LoadString

Lee un recurso de cadena de Windows, identificado por nID, en un objeto CStringT existente.

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

Parámetros

hInstance
Identificador de la instancia del módulo.

nID
Un identificador de recurso de cadena de Windows.

wLanguageID
Idioma del recurso de cadena.

Valor devuelto

Distinto de cero si la carga de recursos se realizó correctamente; de lo contrario, 0.

Comentarios

Carga el recurso de cadena (nID) del módulo especificado (hInstance) mediante el idioma especificado (wLanguage).

Ejemplo

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

CAtlString s;
s.LoadString(IDS_APP_TITLE);

CStringT::MakeLower

Convierte el objeto CStringT en una cadena en minúsculas.

CStringT& MakeLower();

Valor devuelto

Cadena en minúsculas resultante.

Ejemplo

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

CAtlString s(_T("ABC"));

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

CStringT::MakeReverse

Invierte el orden de los caracteres del objeto CStringT.

CStringT& MakeReverse();

Valor devuelto

Cadena invertida resultante.

Ejemplo

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

CAtlString s(_T("abc"));

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

CStringT::MakeUpper

Convierte el objeto CStringT en una cadena en mayúsculas.

CStringT& MakeUpper();

Valor devuelto

Cadena en mayúsculas resultante.

Comentarios

Ejemplo

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

CAtlString s(_T("abc"));

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

CStringT::Mid

Extrae una subcadena de caracteres de longitud nCount de este objeto CStringT, empezando por la posición iFirst (con base cero).

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

Parámetros

iFirst
Índice de base cero del primer carácter de este objeto CStringT que se va a incluir en la subcadena extraída.

nCount
Número de caracteres que se va a extraer de este objeto CStringT. Si no se proporciona este parámetro, se extrae el resto de la cadena.

Valor devuelto

El objeto CStringT que contiene una copia del rango de caracteres especificado. El objeto CStringT devuelto puede estar vacío.

Comentarios

La función devuelve una copia de la subcadena extraída. Mid es similar a la función Mid de Basic (excepto que los índices de Basic están basados en uno).

En el caso de los juegos de caracteres multibyte (MBCS), nCount hace referencia a cada carácter de 8 bits; es decir, un byte inicial y final en un carácter multibyte se cuenta como dos caracteres.

Ejemplo

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

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

CStringT::OemToAnsi

Convierte todos los caracteres de este objeto CStringT del juego de caracteres OEM en el juego de caracteres ANSI.

void OemToAnsi();

Comentarios

Esta función no está disponible si se define _UNICODE.

Ejemplo

Vea el ejemplo de CStringT::AnsiToOem.

CStringT::operator =

Asigna un nuevo valor a la cadena.

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
Objeto CStringT se va a asignar a esta cadena.

str
Referencia a un objeto CThisSimpleString.

bMFCDLL
Valor booleano que especifica si el proyecto es un archivo DLL de MFC o no.

BaseType
Tipo base de la cadena.

var
Objeto VARIANT que se va a asignar a esta cadena.

ch
Carácter ANSI o Unicode que se va a asignar a la cadena.

pszSrc
Puntero a la cadena original que se va a asignar.

Comentarios

El operador de asignación acepta otro objeto CStringT, un puntero de caracteres o un solo carácter. Se pueden producir excepciones de memoria cada vez que se usa este operador porque se puede asignar un nuevo almacenamiento.

Para más información sobre CThisSimpleString, consulte la sección de comentarios de CStringT::CStringT.

Nota:

Aunque es posible crear instancias de CStringT que contengan caracteres NULL insertados, se recomienda no hacerlo. Llamar a métodos y operadores de objetos CStringT que contienen caracteres NULL insertados puede generar resultados no deseados.

CStringT::operator +

Concatena dos cadenas o un carácter y una cadena.

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
Carácter ANSI o Unicode que se va a concatenar con una cadena.

ch2
Carácter ANSI o Unicode que se va a concatenar con una cadena.

str1
Objeto CStringT que se va a concatenar con una cadena o un carácter.

str2
Objeto CStringT que se va a concatenar con una cadena o un carácter.

psz1
Puntero a una cadena terminada en NULL para concatenar con una cadena o un carácter.

psz2
Puntero a una cadena para concatenar con una cadena o un carácter.

Comentarios

Hay siete formas de sobrecarga de la función CStringT::operator+. La primera versión concatena dos objetos CStringT existentes. Las dos siguientes concatenan un objeto CStringT y una cadena terminada en NULL. Las dos siguientes concatenan un objeto CStringT y un carácter ANSI. Las dos últimas concatenan un objeto CStringT y un carácter Unicode.

Nota:

Aunque es posible crear instancias de CStringT que contengan caracteres NULL insertados, se recomienda no hacerlo. Llamar a métodos y operadores de objetos CStringT que contienen caracteres NULL insertados puede generar resultados no deseados.

Ejemplo

// 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 al final de la cadena.

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
Referencia a un objeto CThisSimpleString.

bMFCDLL
Valor booleano que especifica si el proyecto es un archivo DLL de MFC o no.

BaseType
Tipo base de la cadena.

var
Objeto VARIANT que se va a concatenar con esta cadena.

ch
Carácter ANSI o Unicode que se va a concatenar con una cadena.

pszSrc
Puntero a la cadena original que se va a concatenar.

strSrc
Objeto CStringT que se va a concatenar con esta cadena.

Comentarios

El operador acepta otro objeto CStringT, un puntero de caracteres o un solo carácter. Las excepciones de memoria pueden producirse siempre que use este operador de concatenación porque se puede asignar un nuevo almacenamiento para los caracteres agregados a este objeto CStringT.

Para más información sobre CThisSimpleString, consulte la sección de comentarios de CStringT::CStringT.

Nota:

Aunque es posible crear instancias de CStringT que contengan caracteres NULL insertados, se recomienda no hacerlo. Llamar a métodos y operadores de objetos CStringT que contienen caracteres NULL insertados puede generar resultados no deseados.

Ejemplo

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

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

CStringT::operator ==

Determina si dos cadenas son lógicamente iguales.

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
Un carácter ANSI o Unicode para la comparación.

ch2
Un carácter ANSI o Unicode para la comparación.

str1
Objeto CStringT para la comparación.

str2
Objeto CStringT para la comparación.

psz1
Puntero a una cadena terminada en NULL para la comparación.

psz2
Puntero a una cadena terminada en NULL para la comparación.

Comentarios

Comprueba si una cadena o un carácter del lado izquierdo es igual a una cadena o un carácter del lado derecho y devuelve TRUE o FALSE en consecuencia.

Ejemplo

// 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 si dos cadenas son lógicamente iguales.

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
Carácter ANSI o Unicode que se va a concatenar con una cadena.

ch2
Carácter ANSI o Unicode que se va a concatenar con una cadena.

str1
Objeto CStringT para la comparación.

str2
Objeto CStringT para la comparación.

psz1
Puntero a una cadena terminada en NULL para la comparación.

psz2
Puntero a una cadena terminada en NULL para la comparación.

Comentarios

Comprueba si una cadena o un carácter del lado izquierdo no es igual a una cadena o un carácter del lado derecho.

Ejemplo

// 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 si la cadena del lado izquierdo del operador es menor que la cadena del lado derecho.

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
Objeto CStringT para la comparación.

str2
Objeto CStringT para la comparación.

psz1
Puntero a una cadena terminada en NULL para la comparación.

psz2
Puntero a una cadena terminada en NULL para la comparación.

Comentarios

En una comparación lexicográfica, se realiza una comparación entre cadenas carácter por carácter hasta que:

  • Encuentra dos caracteres correspondientes distintos y el resultado de la comparación se toma como el resultado de la comparación entre las cadenas.

  • No encuentra ninguna desigualdad, pero una cadena tiene más caracteres que la otra y la cadena más corta se considera menor que la cadena más larga.

  • No encuentra ninguna desigualdad y encuentra que las cadenas tienen el mismo número de caracteres, por lo que las cadenas son iguales.

Ejemplo

// 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 si la cadena al lado izquierdo del operador es mayor que la cadena al lado derecho.

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
Objeto CStringT para la comparación.

str2
Objeto CStringT para la comparación.

psz1
Puntero a una cadena terminada en NULL para la comparación.

psz2
Puntero a una cadena terminada en NULL para la comparación.

Comentarios

En una comparación lexicográfica, se realiza una comparación entre cadenas carácter por carácter hasta que:

  • Encuentra dos caracteres correspondientes distintos y el resultado de la comparación se toma como el resultado de la comparación entre las cadenas.

  • No encuentra ninguna desigualdad, pero una cadena tiene más caracteres que la otra y la cadena más corta se considera menor que la cadena más larga.

  • No encuentra ninguna desigualdad y encuentra que las cadenas tienen el mismo número de caracteres, por lo que las cadenas son iguales.

Ejemplo

// 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 si la cadena al lado izquierdo del operador es menor o igual que la cadena al lado derecho.

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
Objeto CStringT para la comparación.

str2
Objeto CStringT para la comparación.

psz1
Puntero a una cadena terminada en NULL para la comparación.

psz2
Puntero a una cadena terminada en NULL para la comparación.

Comentarios

En una comparación lexicográfica, se realiza una comparación entre cadenas carácter por carácter hasta que:

  • Encuentra dos caracteres correspondientes distintos y el resultado de la comparación se toma como el resultado de la comparación entre las cadenas.

  • No encuentra ninguna desigualdad, pero una cadena tiene más caracteres que la otra y la cadena más corta se considera menor que la cadena más larga.

  • No encuentra ninguna desigualdad y encuentra que las cadenas tienen el mismo número de caracteres, por lo que las cadenas son iguales.

Ejemplo

// 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 si la cadena al lado izquierdo del operador es mayor o igual que la cadena al lado derecho.

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
Objeto CStringT para la comparación.

str2
Objeto CStringT para la comparación.

psz1
Puntero a una cadena para la comparación.

psz2
Puntero a una cadena para la comparación.

Comentarios

En una comparación lexicográfica, se realiza una comparación entre cadenas carácter por carácter hasta que:

  • Encuentra dos caracteres correspondientes distintos y el resultado de la comparación se toma como el resultado de la comparación entre las cadenas.

  • No encuentra ninguna desigualdad, pero una cadena tiene más caracteres que la otra y la cadena más corta se considera menor que la cadena más larga.

  • No encuentra ninguna desigualdad y encuentra que las cadenas tienen el mismo número de caracteres, por lo que las cadenas son iguales.

Ejemplo

// 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

Quita todas las instancias del carácter especificado de la cadena.

int Remove(XCHAR chRemove);

Parámetros

chRemove
Carácter que se va a quitar de una cadena.

Valor devuelto

Recuento de caracteres quitados de la cadena. Cero si la cadena no cambia.

Comentarios

Las comparaciones del carácter distinguen mayúsculas de minúsculas.

Ejemplo

// 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

Hay dos versiones de Replace. La primera versión reemplaza una o varias copias de una subcadena mediante otra subcadena. Ambas subcadenas terminan con valores NULL. La segunda versión reemplaza una o varias copias de un carácter mediante otro carácter. Ambas versiones funcionan en los datos de caracteres almacenados en CStringT.

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

Parámetros

pszOld
Puntero a una cadena terminada en NULL que se va a reemplazar por pszNew.

pszNew
Puntero a una cadena terminada en NULL que reemplaza a pszOld.

chOld
Carácter que se va a reemplazar por chNew.

chNew
Carácter que reemplaza a chOld.

Valor devuelto

Devuelve el número de instancias reemplazadas del carácter o subcadena, o cero si la cadena no cambia.

Comentarios

Replace puede cambiar la longitud de la cadena porque pszNew y pszOld no tienen que tener la misma longitud, y se pueden cambiar varias copias de la subcadena antigua por la nueva. La función realiza una coincidencia que distingue mayúsculas de minúsculas.

Ejemplos de instancias de CStringT son CString, CStringA y CStringW.

Para CStringA, Replace funciona con caracteres ANSI o multibyte (MBCS). Para CStringW, Replace funciona con caracteres anchos.

Para CString, el tipo de datos de caracteres se selecciona en tiempo de compilación, en función de si se definen las constantes de la tabla siguiente.

Constante definida Tipo de datos char
_UNICODE Caracteres anchos
_MBCS Caracteres multibyte
Neither Caracteres de un solo byte
Ambos Undefined

Ejemplo

// 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

Busca en este objeto CStringT la última coincidencia de un carácter.

int ReverseFind(XCHAR ch) const throw();

Parámetros

ch
El carácter que se va a buscar.

Valor devuelto

Índice de base cero del último carácter de este objeto CStringT que coincide con el carácter solicitado o -1 si no se encuentra el carácter.

Comentarios

La función es similar a la función strrchr en tiempo de ejecución.

Ejemplo

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

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

Extrae los últimos nCount caracteres (es decir, los situados más a la derecha) de este objeto CStringT y devuelve una copia de la subcadena extraída.

CStringT Right(int nCount) const;

Parámetros

nCount
Número de caracteres que se va a extraer de este objeto CStringT.

Valor devuelto

El objeto CStringT que contiene una copia del rango de caracteres especificado. El objeto CStringT devuelto puede estar vacío.

Comentarios

Si nCount supera la longitud de la cadena, se extrae la cadena completa. Right es similar a la función Right de Basic (excepto que los índices de Basic son de base cero).

En el caso de los juegos de caracteres multibyte (MBCS), nCount hace referencia a cada carácter de 8 bits; es decir, un byte inicial y final en un carácter multibyte se cuenta como dos caracteres.

Ejemplo

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

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

CStringT::SetSysString

Reasigna el objeto BSTR al que apunta pbstr y copia el contenido del objeto CStringT en él, incluido el carácter NULL.

BSTR SetSysString(BSTR* pbstr) const;

Parámetros

pbstr
Un puntero a la cadena de caracteres.

Valor devuelto

La nueva cadena.

Comentarios

Dependiendo del contenido del objeto CStringT, el valor de BSTR al que hace referencia pbstr puede cambiar. La función produce una excepción CMemoryException si no existe memoria suficiente.

Normalmente, esta función se usa para cambiar el valor de las cadenas pasadas por referencia para Automation.

Ejemplo

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

Extrae caracteres de la cadena, empezando por el primer carácter, que no están en el juego de caracteres identificados por pszCharSet.

CStringT SpanExcluding(PCXSTR pszCharSet) const;

Parámetros

pszCharSet
Cadena interpretada como un juego de caracteres.

Valor devuelto

Subcadena que contiene caracteres de la cadena que no están en pszCharSet, empezando por el primer carácter de la cadena y finalizando con el primer carácter encontrado en la cadena que también está en pszCharSet (es decir, empezando por el primer carácter de la cadena y hasta el primer carácter [este excluido] de la cadena que se encuentra en pszCharSet). Devuelve toda la cadena si no se encuentra ningún carácter de pszCharSet en la cadena.

Comentarios

SpanExcluding extrae y devuelve todos los caracteres anteriores a la primera aparición de un carácter de pszCharSet (es decir, el carácter de pszCharSet y todos los caracteres que lo siguen en la cadena, no se devuelven). Si no se encuentra ningún carácter de pszCharSet en la cadena, SpanExcluding devuelve toda la cadena.

Ejemplo

// 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

Extrae caracteres de la cadena, empezando por el primer carácter, que se encuentran en el juego de caracteres identificados por pszCharSet.

CStringT SpanIncluding(PCXSTR pszCharSet) const;

Parámetros

pszCharSet
Cadena interpretada como un juego de caracteres.

Valor devuelto

Subcadena que contiene caracteres de la cadena que están en pszCharSet, empezando por el primer carácter de la cadena y finalizando cuando se encuentra un carácter en la cadena que no está en pszCharSet. SpanIncluding devuelve una subcadena vacía si el primer carácter de la cadena no está en el juego especificado.

Comentarios

Si el primer carácter de la cadena no está en el juego de caracteres, SpanIncluding devuelve una cadena vacía. De lo contrario, devuelve una secuencia de caracteres consecutivos que se encuentran en el juego.

Ejemplo

// 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

Busca el siguiente token en una cadena de destino.

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

Parámetros

pszTokens
Cadena que contiene delimitadores de token. El orden de estos delimitadores no es importante.

iStart
Índice de base cero para comenzar la búsqueda.

Valor devuelto

Objeto CStringT que contiene el valor de token actual.

Comentarios

La función Tokenize busca el siguiente token en la cadena de destino. El juego de caracteres de pszTokens especifica los delimitadores posibles del token que se van a buscar. En cada llamada a Tokenize la función comienza en iStart, omite los delimitadores iniciales y devuelve un objeto CStringT que contiene el token actual, que es la cadena de caracteres hasta el siguiente carácter delimitador. El valor de iStart se actualiza para que sea la posición que sigue al carácter delimitador final o -1 si se alcanzó el final de la cadena. Se pueden separar más tokens del resto de la cadena de destino mediante una serie de llamadas a Tokenize, utilizando iStart para mantener la pista de en qué parte de la cadena se debe leer el siguiente token. Cuando no haya más tokens, la función devolverá una cadena vacía y iStart se establecerá en -1.

A diferencia de las funciones de división en tokens de CRT, como strtok_s, _strtok_s_l, wcstok_s, _wcstok_s_l, _mbstok_s, _mbstok_s_l, Tokenize no modifica la cadena de destino.

Ejemplo

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

La salida de este ejemplo es la siguiente:

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

CStringT::Trim

Recorta los caracteres iniciales y finales de la cadena.

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

Parámetros

chTarget
Carácter de destino que se va a recortar.

pszTargets
Puntero a una cadena que contiene los caracteres de destino que se van a recortar. Todas las apariciones iniciales y finales de caracteres de pszTargets se recortarán del objeto CStringT.

Valor devuelto

Devuelve la cadena recortada.

Comentarios

Quita todas las apariciones iniciales y finales de uno de los siguientes:

  • Carácter especificado por chTarget.

  • Todos los caracteres encontrados en la cadena especificada por pszTargets.

  • Espacio en blanco.

Ejemplo

// 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

La salida de este ejemplo es la siguiente:

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

CStringT::TrimLeft

Recorta los caracteres iniciales de la cadena.

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

Parámetros

chTarget
Carácter de destino que se va a recortar.

pszTargets
Puntero a una cadena que contiene los caracteres de destino que se van a recortar. Todas las apariciones iniciales de caracteres de pszTargets se recortarán del objeto CStringT.

Valor devuelto

Cadena recortada resultante.

Comentarios

Quita todas las apariciones iniciales y finales de uno de los siguientes:

  • Carácter especificado por chTarget.

  • Todos los caracteres encontrados en la cadena especificada por pszTargets.

  • Espacio en blanco.

Ejemplo

// 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

Recorta los caracteres finales de la cadena.

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

Parámetros

chTarget
Carácter de destino que se va a recortar.

pszTargets
Puntero a una cadena que contiene los caracteres de destino que se van a recortar. Todas las apariciones finales de caracteres de pszTargets se recortarán del objeto CStringT.

Valor devuelto

Devuelve el objeto CStringT que contiene la cadena recortada.

Comentarios

Quita las apariciones finales de uno de los siguientes:

  • Carácter especificado por chTarget.

  • Todos los caracteres encontrados en la cadena especificada por pszTargets.

  • Espacio en blanco.

La versión CStringT& TrimRight(XCHAR chTarget) acepta parámetros de un carácter y quita todas las copias de ese carácter del final de los datos de cadena CStringT. Comienza desde el final de la cadena y funciona hacia delante. Se detiene cuando encuentra un carácter diferente o cuando CStringT se queda sin datos de caracteres.

La versión CStringT& TrimRight(PCXSTR pszTargets) acepta una cadena terminada en NULL que contiene todos los caracteres diferentes que se van a buscar. Quita todas las copias de esos caracteres del objeto CStringT. Comienza al final de la cadena y funciona hacia delante. Se detiene cuando encuentra un carácter que no está en la cadena de destino o cuando CStringT se queda sin datos de caracteres. No intenta hacer coincidir toda la cadena de destino con una subcadena al final de CStringT.

La versión CStringT& TrimRight() no requiere parámetros. Recorta los caracteres de espacio en blanco finales del final de la cadena CStringT. Los caracteres de espacio en blanco pueden ser saltos de línea, espacios o tabulaciones.

Ejemplo

// 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

Consulte también

Gráfico de jerarquías
Clases compartidas de ATL y MFC
CSimpleStringT (clase)