La clase CString - Funciones miembro

Aunque es recomendable saber qué está pasando cada vez que utilizamos un objeto CString, el manejo general se realiza a través de su funciones miembro y opcionalmente los operadores sobrecargados.

Algunas de las funciones miembro más importantes son:

|| Prototipo || Descripción ||
|| int GetLength() const; || Retorna el número de bytes que ocupa la cadena, sin tener en cuenta el terminador '\0'. Concretamente, lo único que retona es el valor del campo "nDataLength" de la estructura CStringData asociada.
Hay que tener en cuenta que en compilaciones UNICODE, cada carácter ocupa 2 bytes, por lo que si almacenamos una cadena de 4 caracteres, GetLength() retornará 8 bytes.
Es una función "const", es decir: informativa, que no modifica el estado del objeto. ||
|| BOOL IsEmpty() const; || Retorna true si la cadena está vacía, es decir si el número de bytes que retorna GetLength() es 0. ||
|| void Empty(); || Vacía el contenido del objeto, liberando la estructura interna CStringData si no está compartida con otros objetos. ||
|| TCHAR GetAt( IN int nIndex) const; || Retorna el valor del carácter número "nIndex", empezando desde el índice 0.
La llamada a esta función es equivalente al uso de operador [].
Internamente, GetAt(x) no hace más que retornar la posición x del buffer interno, es decir: m_pchData[x]. ||
|| void SetAt( IN int nIndex, IN TCHAR ch); || Establece el valor del carácter "nIndex", empezando a contar desde el índice 0.
La llamada a esta función es equivalente a asignar un valor a través del uso del operador [].
Si "nIndex" es mayor que el número de caracteres existentes, la cadena no crecerá para almacenar dicho valor. ||
|| int Compare( IN LPCTSTR lpsz) const; || Retorna 0 si el valor de la cadena "lpsz" es igual al valor almacenado por el objeto, un valor negativo si el objeto es menor que "lpsz" y un valor positivo si el objeto es mayor que "lpsz".
Esta función tiene en cuenta las mayúsculas y minúsculas, aunque se puede utilizar la función CompareNoCase() para ignorar las mayúsculas/minúsculas en la comparación. ||
|| int Collate( IN LPCTSTR lpsz) const; || Retorna 0 si el valor de la cadena "lpsz" es igual al valor almacenado por el objeto, un valor negativo si el objeto es menor que "lpsz" y un valor positivo si el objeto es mayor que "lpsz".
Esta función tiene en cuenta las mayúsculas y minúsculas, aunque se puede utilizar la función CollateNoCase() para ignorar las mayúsculas/minúsculas en la comparación.
Para decidir si una cadena es menor que otra, tiene en cuenta el conjunto de caracteres locales del equipo. ||
|| CString Mid( IN int nFirst, IN OPTIONAL int nCount) const; || Retorna un objeto CString con la cadena resultante de extraer, empezando en 0, desde la posición "nFirst" hasta una longitud de "nCount" caracteres.
Si no se indica el parámetro "nCount", se retornará hasta el final de la cadena.
También se pueden utilizar las funciones Right(nCount) y Left(nCount) para extraer "nCount" caracteres desde la derecha o izquierda respectivamente. ||
|| CString SpanExcluding( IN LPCTSTR lpszCharSet) const; || Retorna un objeto CString que es la subcadena del objeto "this".
Esta subcadena comienza en el primer carácter no existente en el conjunto de caracteres representado por "lpszCharSet", y continúa hasta el primero que coincida con algudo de "lpszCharSet".
Esta función es muy útil para trocear cadenas hasta cierto delimitador, como lo haría un parser.

---

Por ejemplo: CString cadena = "trozo1;trozo2,trozo3,trozo4"; se muestra "trozo1", ya que trocea hasta el primer carácter que encuentra en el conjunto. AfxMessageBox( cadena.SpanExcluding(";,"), 0, 0 ); También existe la función contraria: SpanIncluding, que retorna la cadena desde el primer carácter que se encuentre en el subconunto, hasta el siguiente que no aparezca: CString cadena = "hola mundo"; se muestra la cadena "hola mu", porque el conjunto de caracteres contiene las vocales y las consonantes "h", "l" y "m". AfxMessageBox( cadena.SpanIncluding("aeiouhlm"), 0, 0 ); || || void MakeUpper(); void MakeLower(); || Convierte todos los caracteres de la cadena a mayúsculas o minúsculas. ||
|| void FreeExtra(); || Libera el espacio sobrante dentro del caché interno del objeto CString. Esto provoca que el tamaño del buffer interno se ajuste al tamaño de la cadena contenida, por lo que si se amplía el contenido, será necesario reservar un nuevo buffer. ||
|| int Remove( IN TCHAR chRemove); || Elimina todas las ocurrencias del carácter "chRemove" del contenido del objeto. Retorna el número de caracteres eliminados. ||
|| int Delete( IN int nIndex IN DEFAULT int nCount = 1); || Elimina "nCount" caracteres desde la posición "nIndex" (empezando en 0). ||
|| int Insert( IN int nIndex IN TCHAR ch); int Insert( IN int nIndex IN LPCTSTR pstr); || Inserta la cadena o carácter pasado por parámetro en la posición "nIndex" (a partir de 0) del contenido de la cadena. Si el índice es mayor que la longitud de la cadena, se insertará al final, es decir: se concatenará. ||
|| void AFX_CDECL Format( IN LPCTSTR lpszFormat, ...); void AFX_CDECL FormatMessage( IN LPCTSTR lpszFormat, ...); void FormatV( IN LPCTSTR lpszFormat, IN va_list argList); || Modifica el contenido del objeto aplicando un formato, del mismo modo que con las funciones de C: sprinf(), wsprinft() y wsvprintf().
FormatMessage() utiliza la función del API Win32 ::FormatMessage(), mientras que Format() llama a FormatV(), la cual acaba utilizando vsprintf() para realizar la convesión. ||
|| int Replace( IN TCHAR chOld, IN TCHAR chNew); int Replace( IN LPCTSTR lpszOld, IN LPCTSTR lpszNew); || Reemplaza todas las ocurrencias de "chOld" o "lpszOld" por "chNew" o "lpszNew". ||
|| void TrimLeft(); void TrimRight(); || Elimina todos los espacios a la izquierda/derecha de la cadena. ||
|| int Find( IN TCHAR ch, IN OPTIONAL int nStart); int Find( IN LPCTSTR lpszSub, IN OPTIONAL int nStart); || Busca el carácter "ch" o la subcadena "lpszSub" a partir de la posición "nStart" (comenzando en 0). Si no se indica "nStart", comenzará desde el principio de la cadena.
También existe la función ReverseFind() que busca un carácter dado comenzando desde el final de la cadena, y FindOneOf() que busca cualquier carácter coindicente con un subconjunto dado. ||
|| LPTSTR GetBuffer( IN int nMinBufLength); int ReleaseBuffer( IN DEFAULT int nNewLength = -1); || Retorna un puntero a la cadena almacenada internamiente por el objeto CString. Después de utilizar la cadena, es necesario liberar el buffer a través de ReleaseBuffer.
Más abajo se da información sobre cómo tratar objetos CString como punteros a char de al estilo "C". ||
|| LPTSTR GetBuffer( IN int nMinBufLength); int ReleaseBuffer( IN DEFAULT int nNewLength = -1); || Retorna un puntero a la cadena almacenada internamiente por el objeto CString. Después de utilizar la cadena, es necesario liberar el buffer a través de ReleaseBuffer.
Más abajo se da información sobre cómo tratar objetos CString como punteros a char de al estilo "C". ||
|| LPTSTR LockBuffer(); void UnlockBuffer(); || Desactiva el contador de referencias, y crea una copia de la cadena que retorna como puntero.
Cuando se termine de manipular la copia, es necesario restablecer el contador de referencias, a través de UnlockBuffer(). ||