Clase CSimpleStringT

Esta clase representa un objeto CSimpleStringT.

Sintaxis

template <typename BaseType>
class CSimpleStringT

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

Miembros

Definiciones de tipos públicas

Nombre	Descripción
CSimpleStringT::PCXSTR	Puntero a una cadena constante.
CSimpleStringT::PXSTR	Puntero a una cadena.

Constructores públicos

Nombre	Descripción
CSimpleStringT::CSimpleStringT	Construye objetos CSimpleStringT de varias maneras.
CSimpleStringT::~CSimpleStringT	Destructor.

Métodos públicos

Nombre	Descripción
CSimpleStringT::Append	Anexa un objeto CSimpleStringT a un objeto CSimpleStringT existente.
CSimpleStringT::AppendChar	Anexa un carácter a un objeto existente CSimpleStringT.
CSimpleStringT::CopyChars	Copia un carácter o caracteres en otra cadena.
CSimpleStringT::CopyCharsOverlapped	Copia un carácter o caracteres en otra cadena en la que los búferes se superponen.
CSimpleStringT::Empty	Fuerza a una cadena para que tenga una longitud de cero.
CSimpleStringT::FreeExtra	Libera cualquier memoria adicional asignada previamente por el objeto de cadena.
CSimpleStringT::GetAllocLength	Recupera la longitud asignada de un objeto CSimpleStringT.
CSimpleStringT::GetAt	Devuelve el carácter en una posición determinada.
CSimpleStringT::GetBuffer	Devuelve un puntero a los caracteres de CSimpleStringT.
CSimpleStringT::GetBufferSetLength	Devuelve un puntero a los caracteres en CSimpleStringT y trunca la longitud especificada.
CSimpleStringT::GetLength	Devuelve el número de caracteres en un objeto CSimpleStringT.
CSimpleStringT::GetManager	Recupera el administrador de memoria del objeto CSimpleStringT.
CSimpleStringT::GetString	Recupera la cadena de caracteres
CSimpleStringT::IsEmpty	Comprueba si un objeto CSimpleStringT no contiene caracteres.
CSimpleStringT::LockBuffer	Deshabilita el recuento de referencias y protege la cadena en el búfer.
CSimpleStringT::Preallocate	Asigna una cantidad específica de memoria para el búfer de caracteres.
CSimpleStringT::ReleaseBuffer	Libera el control del búfer devuelto por GetBuffer.
CSimpleStringT::ReleaseBufferSetLength	Libera el control del búfer devuelto por GetBuffer.
CSimpleStringT::SetAt	Establece un carácter en una posición determinada.
CSimpleStringT::SetManager	Establece el administrador de memoria de un objeto CSimpleStringT.
CSimpleStringT::SetString	Establece la cadena de un objeto CSimpleStringT.
CSimpleStringT::StringLength	Devuelve el número de caracteres en la cadena especificada.
CSimpleStringT::Truncate	Trunca la cadena en una longitud especificada.
CSimpleStringT::UnlockBuffer	Habilita el recuento de referencias y libera la cadena en el búfer.

Operadores públicos

Nombre	Descripción
CSimpleStringT::operator PCXSTR	Accede directamente a los caracteres almacenados en un objeto CSimpleStringTcomo una cadena de estilo C.
CSimpleStringT::operator[]	Devuelve el carácter en una posición determinada: sustitución de operador para GetAt.
CSimpleStringT::operator +=	Concatena una nueva cadena al final de una cadena existente.
CSimpleStringT::operator =	Asigna un nuevo valor a un objeto CSimpleStringT.

Comentarios

CSimpleStringT es la clase base para las distintas clases de cadenas admitidas por Visual C++. Proporciona soporte mínimo con la administración de memoria del objeto de cadena y la manipulación básica del búfer. Para obtener objetos de cadenas más avanzados, consulte CStringT Class.

Requisitos

Encabezado: atlsimpstr.h

CSimpleStringT::Append

Anexa un objeto CSimpleStringT a un objeto CSimpleStringT existente.

Sintaxis

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

Parámetros

strSrc
El objeto CSimpleStringT que se va a anexar.

pszSrc
Un puntero a una cadena que contiene los caracteres que se van a anexar.

nLength
Número de caracteres que se van a anexar.

Comentarios

Llame a este método para anexar un objeto CSimpleStringT existente a otro objetoCSimpleStringT.

Ejemplo

El siguiente ejemplo muestra el uso de CSimpleStringT::Append.

CAtlString basestr;
IAtlStringMgr* pMgr = basestr.GetManager();
CSimpleString str1(pMgr), str2(pMgr);
str1.SetString(_T("Soccer is"));
str2.SetString(_T(" an elegant game"));
str1.Append(str2);
ASSERT(_tcscmp(str1, _T("Soccer is an elegant game")) == 0);

CSimpleStringT::AppendChar

Anexa un carácter a un objeto existente CSimpleStringT.

Sintaxis

void AppendChar(XCHAR ch);

Parámetros

ch
El carácter que se va a anexar

Comentarios

Llame a esta función para anexar el carácter especificado al final de un objeto CSimpleStringT existente.

CSimpleStringT::CopyChars

Copia un carácter o caracteres a un objeto CSimpleStringT.

Sintaxis

static void CopyChars(
    XCHAR* pchDest,
    const XCHAR* pchSrc,
    int nChars) throw();
static void CopyChars(
    XCHAR* pchDest,
    size_t nDestLen,
    const XCHAR* pchSrc,
    int nChars) throw();

Parámetros

pchDest
Un puntero a la cadena de caracteres.

nDestLen
Tamaño de búfer del pchDest

pchSrc
Un puntero a una cadena que contiene los caracteres que se van a copiar.

nChars
El número de caracteres pchSrc que se van a copiar.

Comentarios

Llame a este método para copiar caracteres de pchSrc a la cadena pchDest.

Ejemplo

El siguiente ejemplo muestra el uso de CSimpleStringT::CopyChars.

CAtlString basestr;
IAtlStringMgr* pMgr = basestr.GetManager();
CSimpleString str(_T("xxxxxxxxxxxxxxxxxxx"), 20, pMgr);
const TCHAR* pszSrc = _T("Hello world!");
_tprintf_s(_T("%s\n"), str);
str.CopyChars(str.GetBuffer(), 20, pszSrc, 12);
_tprintf_s(_T("%s\n"), str);

La salida de este ejemplo es la siguiente:

xxxxxxxxxxxxxxxxxxx
Hello world!xxxxxxx

CSimpleStringT::CopyCharsOverlapped

Copia un carácter o caracteres a un objeto CSimpleStringT.

Sintaxis

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

Parámetros

pchDest
Un puntero a la cadena de caracteres.

pchSrc
Un puntero a una cadena que contiene los caracteres que se van a copiar.

nChars
El número de caracteres pchSrc que se van a copiar.

Comentarios

Llame a este método para copiar caracteres de pchSrc a la cadena pchDest. A diferencia de CopyChars, CopyCharsOverlapped proporciona un método seguro para copiar desde búferes de caracteres que podrían superponerse.

Ejemplo

Consulte el ejemplo de CSimpleStringT::CopyChars o el código fuente de CSimpleStringT::SetString (ubicado en atlsimpstr.h).

CSimpleStringT::CSimpleStringT

Construye un objeto CSimpleStringT.

Sintaxis

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

Parámetros

strSrc
Objeto CSimpleStringT existente que se va a copiar en este objeto CSimpleStringT.

pchSrc
Puntero a una matriz de caracteres de longitud nLength, no terminada en null.

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

nLength
Recuento del número de caracteres de pch.

pStringMgr
Un puntero al administrador de memoria del objeto CSimpleStringT. Para más información sobre IAtlStringMgr y la administración de memoria de CSimpleStringT, consulte Administración de memoria yCStringT.

Comentarios

Construye un nuevo objeto CSimpleStringT. Dado que los constructores copian los datos de entrada en un nuevo almacenamiento asignado, pueden producirse excepciones de memoria.

Ejemplo

En el ejemplo siguiente se muestra el uso de CSimpleStringT::CSimpleStringT mediante ATL typedef CSimpleString. CSimpleString es una especialización usada habitualmente de la plantilla CSimpleStringT de clase.

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

CSimpleString s1(pMgr);
// Empty string
CSimpleString s2(_T("cat"), pMgr);
// From a C string literal

CSimpleString s3(s2);
// Copy constructor
CSimpleString s4(s2 + _T(" ") + s3);

// From a string expression
CSimpleString s5(_T("xxxxxx"), 6, pMgr);
// s5 = "xxxxxx"

CSimpleStringT::Empty

Convierte este objeto CSimpleStringT en una cadena vacía y libera la memoria según corresponda.

Sintaxis

void Empty() throw();

Comentarios

Para obtener más información, consulteCadenas: CString Limpieza de excepciones.

Ejemplo

El siguiente ejemplo muestra el uso de CSimpleStringT::Empty.

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

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

CSimpleStringT::FreeExtra

Libera cualquier memoria adicional asignada previamente por la cadena, pero que ya no se usa.

Sintaxis

void FreeExtra();

Comentarios

Esto debería reducir la sobrecarga de memoria consumida por el objeto de cadenas. El método reasigna el búfer a la longitud exacta devuelta por GetLength.

Ejemplo

CAtlString basestr;
IAtlStringMgr* pMgr;

pMgr= basestr.GetManager();
ASSERT(pMgr != NULL);

// Create a CSimpleString with 28 characters
CSimpleString str(_T("Many sports are fun to play."), 28, pMgr);
_tprintf_s(_T("Alloc length is %d, String length is %d\n"),
   str.GetAllocLength(), str.GetLength());

// Assigning a smaller string won't cause CSimpleString to free its
// memory, because it assumes the string will grow again anyway.
str = _T("Soccer is best!");
_tprintf_s(_T("Alloc length is %d, String length is %d\n"),
   str.GetAllocLength(), str.GetLength());

// This call forces CSimpleString to release the extra
// memory it doesn't need.
str.FreeExtra();
_tprintf_s(_T("Alloc length is %d, String length is %d\n"),
   str.GetAllocLength(), str.GetLength());

La salida de este ejemplo es la siguiente:

Alloc length is 1031, String length is 1024
Alloc length is 1031, String length is 15
Alloc length is 15, String length is 15

CSimpleStringT::GetAllocLength

Recupera la longitud asignada de un objeto CSimpleStringT.

Sintaxis

int GetAllocLength() const throw();

Valor devuelto

El número de caracteres asignados para este objeto.

Comentarios

Llame a este método para determinar el número de caracteres asignados para el objeto CSimpleStringT. Consulte FreeExtra para obtener un ejemplo de llamada a esta función.

CSimpleStringT::GetAt

Devuelve el carácter de un objeto CSimpleStringT.

Sintaxis

XCHAR GetAt(int iChar) const;

Parámetros

iChar
Índice de base cero del carácter en el objeto CSimpleStringT. El parámetro iChar debe ser mayor o igual que 0 y menor que el valor devuelto por GetLength. De lo contrario, GetAt generará una excepción.

Valor devuelto

Un XCHAR que contiene el carácter en la posición especificada de la cadena.

Comentarios

Llame a este método para devolver el carácter especificado por iChar. El operador de subíndice sobrecargado ([]) es un alias práctico para GetAt. El terminador null se puede direccionar sin generar una excepción mediante GetAt. Sin embargo, no se cuenta por GetLengthy el valor devuelto es 0.

Ejemplo

En el siguiente ejemplo se muestra cómo usar CSimpleStringT::GetAt.

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

CSimpleStringT::GetBuffer

Devuelve un puntero al búfer de caracteres interno del objeto CSimpleStringT.

Sintaxis

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

Parámetros

nMinBufferLength
El número mínimo de caracteres que puede contener el búfer de caracteres. El valor no incluye espacio para un terminador null.

Si nMinBufferLength es mayor que la longitud del búfer actual, GetBuffer destruye el búfer actual, lo reemplaza por un búfer del tamaño solicitado y restablece el recuento de referencias de objeto a cero. Si anteriormente ha llamado a LockBuffer en este búfer, perderá el bloqueo del búfer.

Valor devuelto

Un puntero PXSTR al búfer de caracteres (terminado en null) del objeto.

Comentarios

Llame a este método para devolver los contenidos del búfer del objeto CSimpleStringT. El PXSTR devuelto no es una constante y, por tanto, permite la modificación directa de los contenidos de CSimpleStringT.

Si usa el puntero devuelto por GetBuffer para cambiar el contenido de la cadena, debe llamar ReleaseBuffer a para actualizar el estado interno de antes de CSimpleStringT usar cualquier otro CSimpleStringT método.

Es posible que la dirección devuelta por GetBuffer no sea válida después de la llamada a ReleaseBuffer porque las operaciones CSimpleStringT adicionales pueden hacer que el búfer CSimpleStringT se vuelva a asignar. El búfer no se reasigna si no cambia la longitud de CSimpleStringT.

La memoria del búfer se libera automáticamente cuando se destruye el objeto CSimpleStringT.

Si realiza un seguimiento de la longitud de la cadena, no debe anexar el carácter null de terminación. Sin embargo, debe especificar la longitud final de la cadena al liberar el búfer con ReleaseBuffer. Si anexa un carácter terminado en null, debe pasar -1 (valor predeterminado) para la longitud. ReleaseBuffer, a continuación determina la longitud del búfer.

Si no hay memoria suficiente para satisfacer la solicitud GetBuffer, este método genera un CMemoryException*.

Ejemplo

CSimpleString s(_T("abcd"), pMgr);
LPTSTR pBuffer = s.GetBuffer(10);
int sizeOfBuffer = s.GetAllocLength();

// Directly access CSimpleString buffer
_tcscpy_s(pBuffer, sizeOfBuffer, _T("Hello"));
ASSERT(_tcscmp(s, _T("Hello")) == 0);
s.ReleaseBuffer();

CSimpleStringT::GetBufferSetLength

Devuelve un puntero al búfer de caracteres interno para el objeto CSimpleStringT, truncando o aumentando su longitud si es necesario para que coincida exactamente con la longitud especificada en nLength.

Sintaxis

PXSTR GetBufferSetLength(int nLength);

Parámetros

nLength
El tamaño exacto del búfer de caracteres CSimpleStringT en caracteres.

Valor devuelto

Un puntero PXSTR al búfer de caracteres (terminado en null) del objeto.

Comentarios

Llame a este método para recuperar una longitud especificada del búfer interno del objeto CSimpleStringT. El puntero PXSTR devuelto no es const y, por tanto, permite la modificación directa de los contenidos CSimpleStringT.

Si usa el puntero devuelto por GetBufferSetLength para cambiar los contenidos de la cadena, llame a ReleaseBuffer para actualizar el estado interno de CSimpleStringT antes de usar otros métodosCSimpleStringT.

Es posible que la dirección devuelta por GetBufferSetLength no sea válida después de la llamada a ReleaseBuffer porque las operaciones CSimpleStringT adicionales pueden hacer que el búfer CSimpleStringT se vuelva a asignar. El búfer no se reasigna si no cambia la longitud de CSimpleStringT.

La memoria del búfer se libera automáticamente cuando se destruye el objeto CSimpleStringT.

Si realiza un seguimiento de la longitud de la cadena, no anexe el carácter terminado en null. Sin embargo, debe especificar la longitud final de la cadena al liberar el búfer con ReleaseBuffer. Si anexa un carácter terminado en null al llamar a ReleaseBuffer, pase -1 (valor predeterminado) para la longitud a ReleaseBuffery ReleaseBuffer realizará un strlen en el búfer para determinar su longitud.

Para obtener más información sobre el recuento de referencias, consulte los artículos siguientes:

• Administración de las vigencias de los objetos a través del recuento de referencias en el Windows SDK.
• Implementación del recuento de referencias en Windows SDK.
• Reglas para administrar recuentos de referencias en Windows SDK.

Ejemplo

El siguiente ejemplo muestra el uso de CSimpleStringT::GetBufferSetLength.

CSimpleString str(pMgr);
LPTSTR pstr = str.GetBufferSetLength(3);
pstr[0] = _T('C');
pstr[1] = _T('u');
pstr[2] = _T('p');
str.ReleaseBuffer();

str += _T(" soccer is best!");
ASSERT(_tcscmp(str, _T("Cup soccer is best!")) == 0);

CSimpleStringT::GetLength

Devuelve la cantidad de caracteres en el objeto CSimpleStringT.

Sintaxis

int GetLength() const throw();

Valor devuelto

Un recuento de los caracteres de la cadena.

Comentarios

Llame a este método para devolver el número de caracteres del objeto. El recuento no incluye un terminador null.

En el caso de los juegos de caracteres multibyte (MBCS), GetLength 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. Consulte FreeExtra para obtener un ejemplo de llamada a esta función.

CSimpleStringT::GetManager

Recupera el administrador de memoria del objeto CSimpleStringT.

Sintaxis

IAtlStringMgr* GetManager() const throw();

Valor devuelto

Puntero al administrador de memoria del objeto CSimpleStringT.

Comentarios

Llame a este método para recuperar el administrador de memoria usado por el objeto CSimpleStringT. Para más información sobre los administradores de memoria y las cadenas, consulte Administración de memoria con CStringTCStringT.

CSimpleStringT::GetString

Recupera la cadena de caracteres.

Sintaxis

PCXSTR GetString() const throw();

Valor devuelto

Un puntero a una cadena de caracteres terminada en null.

Comentarios

Llame a este método para recuperar la cadena de caracteres asociada al objeto CSimpleStringT.

Nota:

El puntero PCXSTR devuelto es const y no permite la modificación directa de los contenidos CSimpleStringT.

Ejemplo

El siguiente ejemplo muestra el uso de CSimpleStringT::GetString.

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

La salida de este ejemplo es la siguiente:

Cup soccer is best!

CSimpleStringT::IsEmpty

Comprueba un objeto CSimpleStringT para la condición vacía.

Sintaxis

bool IsEmpty() const throw();

Valor devuelto

Devuelve TRUE si el objeto CSimpleStringT tiene 0 longitud; de lo contrario FALSE.

Comentarios

Llame a este método para determinar si el objeto contiene una cadena vacía.

Ejemplo

El siguiente ejemplo muestra el uso de CSimpleStringT::IsEmpty.

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

CSimpleStringT::LockBuffer

Deshabilita el recuento de referencias y protege la cadena en el búfer.

Sintaxis

PXSTR LockBuffer();

Valor devuelto

Un puntero a un objeto CSimpleStringT o a una cadena terminada en null.

Comentarios

Llame a este método para bloquear el búfer del objeto CSimpleStringT. Al llamar a LockBuffer, se crea una copia de la cadena con -1 para el recuento de referencias. Cuando el valor de recuento de referencias es -1, la cadena del búfer se considera que está en un estado "bloqueado". Mientras está en estado bloqueado, la cadena está protegida de dos maneras:

• Ninguna otra cadena puede obtener una referencia a los datos de la cadena bloqueada, incluso si esa cadena está asignada a la cadena bloqueada.

• La cadena bloqueada nunca hará referencia a otra cadena, incluso si esa otra cadena se copia en la cadena bloqueada.

Al bloquear la cadena en el búfer, asegúrese de que la retención exclusiva de la cadena en el búfer permanecerá intacta.

Una vez que haya terminado con LockBuffer, llame a UnlockBuffer para restablecer el recuento de referencias a 1.

Nota:

Si llama a GetBuffer en un búfer bloqueado y establece el GetBuffer parámetro nMinBufferLength por encima de la longitud del búfer actual, perderá el bloqueo del búfer. Esta llamada a GetBuffer destruye el búfer actual, lo reemplaza por un búfer del tamaño solicitado y restablece el recuento de referencias a cero.

Para obtener más información sobre el recuento de referencias, consulte los artículos siguientes:

• Administración de las vigencias de los objetos a través del recuento de referencias en el Windows SDK

• Implementación del recuento de referencias en Windows SDK

• Reglas para administrar recuentos de referencias en Windows SDK

Ejemplo

El siguiente ejemplo muestra el uso de CSimpleStringT::LockBuffer.

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

CSimpleString str(_T("Hello"), pMgr);
TCHAR ch;

str.LockBuffer();
ch = str.GetAt(2);
_tprintf_s(_T("%c"), ch);
str.UnlockBuffer();

La salida de este ejemplo es la siguiente:

l

CSimpleStringT::operator[]

Llame a esta función para tener acceso a un solo carácter de la matriz de caracteres.

Sintaxis

XCHAR operator[](int iChar) const;

Parámetros

iChar
Índice de base cero de un carácter en la cadena.

Comentarios

El operador de subíndice sobrecargado ([]) devuelve un solo carácter especificado por el índice de base cero en iChar. Este operador es un sustituto práctico de la función miembro GetAt.

Nota:

Puede usar el operador de subíndice ([]) para obtener el valor de un carácter en un CSimpleStringT, pero no se puede usar para cambiar el valor de un carácter en un CSimpleStringT.

Ejemplo

El siguiente ejemplo muestra el uso de CSimpleStringT::operator [].

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

CSimpleStringT::operator []

Llame a esta función para tener acceso a un solo carácter de la matriz de caracteres.

Sintaxis

XCHAR operator[](int iChar) const;

Parámetros

iChar
Índice de base cero de un carácter en la cadena.

Comentarios

El operador de subíndice sobrecargado ([]) devuelve un solo carácter especificado por el índice de base cero en iChar. Este operador es un sustituto práctico de la función miembro GetAt.

Nota:

Puede usar el operador de subíndice ([]) para obtener el valor de un carácter en un CSimpleStringT, pero no se puede usar para cambiar el valor de un carácter en un CSimpleStringT.

CSimpleStringT::operator +=

Combina una nueva cadena o carácter al final de una cadena existente.

Sintaxis

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

Parámetros

pszSrc
Un puntero a una cadena terminada en null.

strSrc
Un puntero a un objeto CSimpleStringT existente.

ch
Carácter que se va a anexar.

Comentarios

El operador acepta otro objeto CSimpleStringT o un carácter. Tenga en cuenta que 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 al objeto CSimpleStringT.

Ejemplo

El siguiente ejemplo muestra el uso de CSimpleStringT::operator +=.

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

CSimpleStringT::operator =

Asigna un nuevo valor a un objeto CSimpleStringT.

Sintaxis

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

Parámetros

pszSrc
Un puntero a una cadena terminada en null.

strSrc
Un puntero a un objeto CSimpleStringT existente.

Comentarios

Si la cadena de destino (el lado izquierdo) ya es lo suficientemente grande como para almacenar los nuevos datos, no se realiza ninguna asignación de memoria nueva. Tenga en cuenta que las excepciones de memoria pueden producirse siempre que use el operador de asignación porque a menudo se asigna nuevo almacenamiento para contener el objeto CSimpleStringT resultante.

Ejemplo

El siguiente ejemplo muestra el uso de CSimpleStringT::operator =.

CSimpleString s1(pMgr), s2(pMgr);
// Empty CSimpleStringT objects

s1 = _T("cat");
// s1 = "cat"
ASSERT(_tcscmp(s1, _T("cat")) == 0);

s2 = s1;               // s1 and s2 each = "cat"
ASSERT(_tcscmp(s2, _T("cat")) == 0);

s1 = _T("the ") + s1;
// Or expressions
ASSERT(_tcscmp(s1, _T("the cat")) == 0);

s1 = _T("x");
// Or just individual characters
ASSERT(_tcscmp(s1, _T("x")) == 0);

CSimpleStringT::operator PCXSTR

Accede directamente a los caracteres almacenados en un objeto CSimpleStringTcomo una cadena de estilo C.

Sintaxis

operator PCXSTR() const throw();

Valor devuelto

Puntero de caracteres a los datos de la cadena.

Comentarios

No se copian caracteres; solo se devuelve un puntero. Tenga cuidado con este operador. Si cambia un objeto CString después de haber obtenido el puntero de carácter, puede provocar una reasignación de memoria que invalida el puntero.

Ejemplo

El siguiente ejemplo muestra el uso de CSimpleStringT::operator PCXSTR.

// If the prototype of a function is known to the compiler,
// the PCXSTR cast operator may be invoked implicitly.

CSimpleString strSports(L"Soccer is Best!", pMgr);
WCHAR sz[1024];

wcscpy_s(sz, strSports);

// If the prototype isn't known or is a va_arg prototype,
// you must invoke the cast operator explicitly. For example,
// the va_arg part of a call to swprintf_s() needs the cast:

swprintf_s(sz, 1024, L"I think that %s!\n", (PCWSTR)strSports);

// While the format parameter is known to be an PCXSTR and
// therefore doesn't need the cast:

swprintf_s(sz, 1024, strSports);

// Note that some situations are ambiguous. This line will
// put the address of the strSports object to stdout:

wcout << strSports;

// while this line will put the content of the string out:

wcout << (PCWSTR)strSports;

CSimpleStringT::PCXSTR

Puntero a una cadena constante.

Sintaxis

typedef ChTraitsBase< BaseType >::PCXSTR PCXSTR;

CSimpleStringT::Preallocate

Asigna una cantidad específica de bytes para el objeto CSimpleStringT.

Sintaxis

void Preallocate( int nLength);

Parámetros

nLength
El tamaño exacto del búfer de caracteres CSimpleStringT en caracteres.

Comentarios

Llame a este método para asignar un tamaño de búfer específico para el objeto CSimpleStringT.

CSimpleStringT genera una excepción STATUS_NO_MEMORY si no puede asignar espacio para el búfer de caracteres. De forma predeterminada, las funciones HeapAlloc de la API de WIN32 realizan la asignación de memoria o HeapReAlloc.

Ejemplo

El siguiente ejemplo muestra el uso de CSimpleStringT::Preallocate.

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

CSimpleString str(pMgr);
_tprintf_s(_T("Allocated length: %d\n"), str.GetAllocLength());
str.Preallocate(100);
_tprintf_s(_T("Allocated length: %d\n"), str.GetAllocLength());

La salida de este ejemplo es la siguiente:

Allocated length: 0
Allocated length: 103

CSimpleStringT::PXSTR

Puntero a una cadena.

Sintaxis

typedef ChTraitsBase< BaseType >::PXSTR PXSTR;

CSimpleStringT::ReleaseBuffer

Libera el control del búfer asignado por GetBuffer.

Sintaxis

void ReleaseBuffer(int nNewLength = -1);

Parámetros

nNewLength
Nueva longitud de la cadena en caracteres, sin contar un terminador null. Si la cadena termina en null, el valor predeterminado -1 establece el tamaño de CSimpleStringT en la longitud actual de la cadena.

Comentarios

Llame a este método para reasignar o liberar el búfer del objeto de cadena. Si sabe que la cadena del búfer termina en null, puede omitir el argumento nNewLength. Si la cadena no termina en null, use nNewLength para especificar su longitud. La dirección devuelta por GetBuffer no es válida después de la llamada a ReleaseBuffer o a cualquier otra operación CSimpleStringT.

Ejemplo

El siguiente ejemplo muestra el uso de CSimpleStringT::ReleaseBuffer.

const int bufferSize = 1024;
CSimpleString s(_T("abc"), pMgr);
LPTSTR p = s.GetBuffer(bufferSize);
_tcscpy_s(p, bufferSize, _T("abc"));

// use the buffer directly
ASSERT(s.GetLength() == 3);

// String length = 3
s.ReleaseBuffer();

// Surplus memory released, p is now invalid.
ASSERT(s.GetLength() == 3);

// Length still 3

CSimpleStringT::ReleaseBufferSetLength

Libera el control del búfer asignado por GetBuffer.

Sintaxis

void ReleaseBufferSetLength(int nNewLength);

Parámetros

nNewLength
La longitud de la cadena que se libera

Comentarios

Esta función es funcionalmente similar a ReleaseBuffer, salvo porque se debe pasar una longitud válida para el objeto de cadena.

CSimpleStringT::SetAt

Establece un único carácter de un objeto CSimpleStringT.

Sintaxis

void SetAt(int iChar, XCHAR ch);

Parámetros

iChar
Índice de base cero del carácter en el objeto CSimpleStringT. El parámetro iChar debe ser mayor o igual que 0 y menor que el valor devuelto por GetLength.

ch
El nuevo caracter.

Comentarios

Llame a este método para sobrescribir el carácter ubicado en iChar. Este método no ampliará la cadena si iChar supera los límites de la cadena existente.

Ejemplo

El siguiente ejemplo muestra el uso de CSimpleStringT::SetAt.

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

CSimpleStringT::SetManager

Especifica el administrador de memoria del objeto CSimpleStringT.

Sintaxis

void SetManager(IAtlStringMgr* pStringMgr);

Parámetros

pStringMgr
Un puntero al nuevo administrador de memoria.

Comentarios

Llame a este método para especificar un nuevo administrador de memoria usado por el objeto CSimpleStringT. Para más información sobre los administradores de memoria y las cadenas, consulte Administración de memoria con CStringTCStringT.

Ejemplo

El siguiente ejemplo muestra el uso de CSimpleStringT::SetManager.

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

CSimpleStringT::SetString

Establece la cadena de un objeto CSimpleStringT.

Sintaxis

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

Parámetros

pszSrc
Un puntero a una cadena terminada en null.

nLength
Recuento del número de caracteres de pszSrc.

Comentarios

Copie una cadena en el objeto CSimpleStringT. SetString sobrescribe los datos de cadena anteriores en el búfer.

Ambas versiones de SetString comprueban si pszSrc es un puntero null y, si es así, producen un error de E_INVALIDARG.

La versión de un parámetro de SetString espera que pszSrc apunte a una cadena terminada en null.

La versión de dos parámetros de SetString también espera que pszSrc sea una cadena terminada en null. Utiliza nLength como longitud de cadena, a menos que encuentre primero un terminador null.

La versión de dos parámetros de SetString también comprueba si pszSrc apunta a una ubicación en el búfer actual de CSimpleStringT. En este caso especial, SetString usa una función de copia de memoria que no sobrescribe los datos de cadena a medida que copia los datos de cadena de nuevo en su búfer.

Ejemplo

El siguiente ejemplo muestra el uso de CSimpleStringT::SetString.

CSimpleString s(_T("abcdef"), pMgr);
ASSERT(_tcscmp(s, _T("abcdef")) == 0);
s.SetString(_T("Soccer"), 6);
ASSERT(_tcscmp(s, _T("Soccer")) == 0);

CSimpleStringT::StringLength

Devuelve el número de caracteres en la cadena especificada.

Sintaxis

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

Parámetros

psz
Un puntero a una cadena terminada en null.

Valor devuelto

El número de caracteres de psz, sin contar un terminador null.

Comentarios

Llame a este método para recuperar el número de caracteres de la cadena a la que psz apunta.

Ejemplo

El siguiente ejemplo muestra el uso de CSimpleStringT::StringLength.

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

CSimpleStringT::Truncate

Trunca la cadena a la nueva longitud.

Sintaxis

void Truncate(int nNewLength);

Parámetros

nNewLength
La nueva longitud de la cadena.

Comentarios

Llame a este método para truncar los contenidos de la cadena a la nueva longitud.

Nota:

Esto no afecta a la longitud asignada del búfer. Para reducir o aumentar el búfer actual, consulte FreeExtra y Preallocate.

Ejemplo

El siguiente ejemplo muestra el uso de CSimpleStringT::Truncate.

CAtlString basestr;
IAtlStringMgr* pMgr = basestr.GetManager();
CSimpleString str(_T("abcdefghi"), pMgr);
_tprintf_s(_T("String length: %d / Allocated length: %d\n"), str.GetLength(), str.GetAllocLength());
_tprintf_s(_T("Contents: %s\n"), (LPCTSTR)str);
str.Truncate(4);
_tprintf_s(_T("String length: %d / Allocated length: %d\n"), str.GetLength(), str.GetAllocLength());
_tprintf_s(_T("Contents: %s\n"), (LPCTSTR)str);

La salida de este ejemplo es:

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

CSimpleStringT::UnlockBuffer

Desbloquea el búfer del objeto CSimpleStringT.

Sintaxis

void UnlockBuffer() throw();

Comentarios

Llame a este método para restablecer el recuento de referencias de la cadena a 1.

El destructor CSimpleStringT llama a UnlockBuffer automáticamente para asegurarse de que el búfer no está bloqueado cuando se llama al destructor. Para ver un ejemplo de este método, consulte LockBuffer.

CSimpleStringT::~CSimpleStringT

Destruye un objeto CSimpleStringT .

Sintaxis

~CSimpleStringT() throw();

Comentarios

Llame a este método para destruir el objeto CSimpleStringT.

Consulte también

Gráfico de jerarquías
Clases compartidas de ATL y MFC