CString Class¶
Overview¶
Note
The CString class handles strings and string manipulation
The structure used for this class is CString
Quick Reference¶
Quick Ref |
void CString::CString(CString& stringSrc) |
void CString::CString(const char* lpsz) |
void CString::CString(char ch, int nLength) |
void CString::CString(const char* lpch, int nLength) |
void CString::~CString() |
void CString::AllocBuffer(int nLen) |
void CString::AllocCopy(CString& dest, int nCopyLen, int nCopyIndex, int nExtraLen) |
void CString::AssignCopy(int nSrcLen, const char* lpszSrcData) |
int CString::CompareNoCase(const char* lpsz) |
void CString::ConcatCopy(int nSrc1Len, const char* lpszSrc1Data, int nSrc2Len, const char* lpszSrc2Data) |
void CString::ConcatInPlace(int nSrcLen, const char* lpszSrcData) |
void CString::CopyBeforeWrite() |
int CString::Delete(int nIndex, int nCount) |
void CString::Empty() |
int CString::Find(char ch) |
int CString::Find(char ch, int nStart) |
int CString::Find(const char* lpszSub) |
int CString::Find(const char* lpszSub, int nStart) |
int CString::FindOneOf(const char* lpszCharSet) |
void __cdecl CString::Format(const char* lpszFormat, …) |
void CString::FormatV(const char* lpszFormat, char* argList) |
virtual void __cdecl CString::FreeData(CStringData* pData) |
char* CString::GetBuffer(int nMinBufLength) |
char* CString::GetBufferSetLength(int nNewLength) |
CString CString::Left(int nCount) |
int CString::LoadStringA(unsigned int nID) |
void CString::MakeLower() |
void CString::MakeUpper() |
void CString::MakeUpperUTF8() |
CString CString::Mid(int nFirst) |
CString CString::Mid(int nFirst, int nCount) |
virtual void __stdcall CString::Release(CStringData* pData) |
void CString::ReleaseBuffer(int nNewLength) |
int CString::Replace(char chOld, char chNew) |
int CString::Replace(const char* lpszOld, const char* lpszNew) |
int CString::ReverseFind(char ch) |
CString CString::Right(int nCount) |
void CString::SetAt(int nIndex, char ch) |
CString CString::SpanExcluding(const char* lpszCharSet) |
CString CString::SpanIncluding(const char* lpszCharSet) |
void CString::TrimLeft() |
void CString::TrimRight(char chTarget) |
void CString::TrimRight(const char* lpszTargetList) |
void CString::TrimRight() |
CString& CString::operator=(char ch) |
CString& CString::operator=(const char* lpsz) |
CString& CString::operator+=(char ch) |
CString& CString::operator+=(const char* lpsz) |
Constructors¶
Name |
Description |
Constructs a |
|
Destroys a |
CString::CString¶
Constructs a CString
object
void CString::CString(CString& stringSrc);
Parameters
CString& stringSrc - an existing
CString
object to be copied into thisCString
object
Remarks
Constructs a CString
object
CString::CString¶
Constructs a CString
object
void CString::CString(const char* lpsz);
Parameters
const char
* lpsz - long pointer to zero terminated string
Remarks
Constructs a CString
object
CString::CString¶
Constructs a CString
object
void CString::CString(
char ch,
int nLength);
Parameters
char
ch - a single characterint
nLength - set to1
Remarks
Constructs a CString
object
CString::CString¶
Constructs a CString
object
void CString::CString(
const char* lpch,
int nLength);
Parameters
const char
* lpch - a pointer to an array of characters of length nLength, not null-terminatedint
nLength - a count of the number of characters in lpch
Remarks
Constructs a CString
object
CString::~CString¶
Destroys the CString
object
void CString::~CString();
Remarks
Destroys the CString
object
Methods¶
Name |
Description |
Compares two strings (case insensitive) |
|
Deletes a character or characters from a string |
|
Searches a string for the first match of a character or substring |
|
Searches a string for the first character that matches |
|
Writes formatted data to a |
|
Formats a message string using a variable argument list |
|
Extracts the leftmost count of characters from a string |
|
Reads a Windows string resource |
|
Converts string to lowercase |
|
Converts string to uppercase |
|
Extracts a substring of characters from a string |
|
Replaces one or more copies of a substring in a string |
|
Searches a string for the last match of a character or substring |
|
Extracts the rightmost count of characters from a string |
|
Extracts characters from the string |
|
Extracts characters from the string |
|
Trims leading characters from the string |
|
Trims trailing characters from the string |
CString::AllocBuffer¶
void CString::AllocBuffer(int nLen);
Parameters
int
nLen -
Remarks
CString::AllocCopy¶
void CString::AllocCopy(
CString& dest,
int nCopyLen,
int nCopyIndex,
int nExtraLen);
Parameters
CString& dest -
int
nCopyLen -int
nCopyIndex -int
nExtraLen -
Remarks
CString::AssignCopy¶
void CString::AssignCopy(
int nSrcLen,
const char* lpszSrcData);
Parameters
int
nSrcLen -const char
* lpszSrcData -
Remarks
CString::CompareNoCase¶
Compares two strings (case insensitive)
int CString::CompareNoCase(const char* lpsz);
Parameters
const char
* lpsz - the other string used for comparison
Return Value
0
if the strings are identical (ignoring case), <0
if this CString
object is less than lpsz (ignoring case), or >0
if this CString
object is greater than lpsz (ignoring case)
CString::ConcatCopy¶
void CString::ConcatCopy(
int nSrc1Len,
const char* lpszSrc1Data,
int nSrc2Len,
const char* lpszSrc2Data);
Parameters
int
nSrc1Len -const char
* lpszSrc1Data -int
nSrc2Len -const char
* lpszSrc2Data -
Remarks
CString::ConcatInPlace¶
void CString::ConcatInPlace(
int nSrcLen,
const char* lpszSrcData);
Parameters
int
nSrcLen -const char
* lpszSrcData -
Remarks
CString::CopyBeforeWrite¶
void CString::CopyBeforeWrite();
Remarks
CString::Delete¶
Deletes a character or characters from a string starting with the character at the given index
int CString::Delete(
int nIndex,
int nCount);
Parameters
int
nIndex - the zero-based index of the first character in theCString
object to deleteint
nCount - the number of characters to be removed
Return Value
Returns an int
value - the length of the changed string
Remarks
If nCount is longer than the string, the rest of the string will be removed
CString::Empty¶
void CString::Empty();
Remarks
CString::Find¶
Searches this string for the first match of a character or substring
int CString::Find(char ch);
Parameters
char
ch - a single character to search for
Return Value
The zero-based index of the first character in this CString
object that matches the requested substring or characters; -1
if the substring or character is not found
Remarks
CString::Find¶
Searches this string for the first match of a character or substring
int CString::Find(
char ch,
int nStart);
Parameters
char
ch - a single character to search forint
nStart - the index of the character in the string to begin the search with, or0
to start from the beginning
Return Value
The zero-based index of the first character in this CString
object that matches the requested substring or characters; -1
if the substring or character is not found
Remarks
CString::Find¶
Searches this string for the first match of a character or substring
int CString::Find(const char* lpszSub);
Parameters
const char
* lpszSub - a substring to search for
Return Value
The zero-based index of the first character in this CString
object that matches the requested substring or characters; -1
if the substring or character is not found
Remarks
CString::Find¶
Searches this string for the first match of a character or substring
int CString::Find(
const char* lpszSub,
int nStart);
Parameters
const char
* lpszSub - a substring to search forint
nStart - the index of the character in the string to begin the search with, or0
to start from the beginning
Return Value
The zero-based index of the first character in this CString
object that matches the requested substring or characters; -1
if the substring or character is not found
Remarks
CString::FindOneOf¶
Searches this string for the first character that matches any character contained in lpszCharSet
int CString::FindOneOf(const char* lpszCharSet);
Parameters
const char
* lpszCharSet - string containing characters for matching
Return Value
The zero-based index of the first character in this string that is also in lpszCharSet; -1
if there is no match
Remarks
Finds the first occurrence of any of the characters in lpszCharSet
CString::Format¶
Writes formatted data to a CString
void __cdecl CString::Format(const char* lpszFormat, ...);
Parameters
const char
* lpszFormat - a format-control string… - optional arguments
Remarks
This function formats and stores a series of characters and values in the CString
. Each optional argument (if any) is converted and output according to the corresponding format specification in pszFormat
CString::FormatV¶
Formats a message string using a variable argument list
void CString::FormatV(
const char* lpszFormat,
char* argList);
Parameters
const char
* lpszFormat - points to the format-control string. It will be scanned for inserts and formatted accordingly. The format string is similar to run-time function printf-style format strings, except it allows for the parameters to be inserted in an arbitrary orderchar
* argList - pointer to a list of arguments
Remarks
Writes a formatted string and a variable list of arguments to a CString
CString::FreeData¶
virtual void __cdecl CString::FreeData(CStringData* pData);
Parameters
CStringData* pData -
Remarks
CString::GetBuffer¶
char* CString::GetBuffer(int nMinBufLength);
Parameters
int
nMinBufLength -
Return Value
Returns char*
Remarks
CString::GetBufferSetLength¶
char* CString::GetBufferSetLength(int nNewLength);
Parameters
int
nNewLength -
Return Value
Returns char*
Remarks
CString::Left¶
Extracts the leftmost nCount characters from this CString
object and returns a copy of the extracted substring
CString CString::Left(int nCount);
Parameters
int
nCount - the number of characters to extract from thisCString
object
Return Value
Returns a CString object that contains a copy of the specified range of characters. The returned CString
object may be empty
Remarks
If nCount exceeds the string length, then the entire string is extracted
CString::LoadStringA¶
Reads a Windows string resource, identified by nID, into an existing CString
object
int CString::LoadStringA(unsigned int nID);
Parameters
unsigned int
nID - a Windows string resource ID
Return Value
Nonzero if resource load was successful; otherwise 0
Remarks
Loads the string resource (nID) from the current module handle using the current language
CString::MakeLower¶
Converts the CString
object to a lowercase string
void CString::MakeLower();
CString::MakeUpper¶
Converts the CString
object to an uppercase string
void CString::MakeUpper();
CString::MakeUpperUTF8¶
void CString::MakeUpperUTF8();
Remarks
CString::Mid¶
Extracts a substring of length nCount characters from this CString
object, starting at position iFirst (zero-based)
CString CString::Mid(int nFirst);
Parameters
int
nFirst - the zero-based index of the first character in thisCString
object that is to be included in the extracted substring
Return Value
Returns a CString object that contains a copy of the specified range of characters. Note that the returned CString object may be empty
Remarks
The function returns a copy of the extracted substring
CString::Mid¶
Extracts a substring of length nCount characters from this CString
object, starting at position iFirst (zero-based)
CString CString::Mid(
int nFirst,
int nCount);
Parameters
int
nFirst - the zero-based index of the first character in thisCString
object that is to be included in the extracted substringint
nCount - the number of characters to extract from thisCString
object. If this parameter is not supplied, then the remainder of the string is extracted
Return Value
Returns a CString object that contains a copy of the specified range of characters. Note that the returned CString object may be empty
Remarks
The function returns a copy of the extracted substring
CString::Release¶
virtual void __stdcall CString::Release(CStringData* pData);
Parameters
CStringData* pData -
Remarks
CString::ReleaseBuffer¶
void CString::ReleaseBuffer(int nNewLength);
Parameters
int
nNewLength -
Remarks
CString::Replace¶
There are two versions of Replace.The first version replaces one or more copies of a substring by using another substring. Both substrings are null-terminated. The second version replaces one or more copies of a character by using another character. Both versions operate on the character data stored in CString
int CString::Replace(
char chOld,
char chNew);
Parameters
char
chOld - the character to be replaced by chNewchar
chNew - the character replacing chOld
Return Value
Returns an int
value - the number of replaced instances of the character or substring, or zero if the string is not changed.
Remarks
The function performs a case-sensitive match
CString::Replace¶
There are two versions of Replace.The first version replaces one or more copies of a substring by using another substring. Both substrings are null-terminated. The second version replaces one or more copies of a character by using another character. Both versions operate on the character data stored in CString
int CString::Replace(
const char* lpszOld,
const char* lpszNew);
Parameters
const char
* lpszOld - a pointer to a null-terminated string to be replaced by lpszNewconst char
* lpszNew - a pointer to a null-terminated string that replaces lpszOld
Return Value
Returns an int
value - the number of replaced instances of the character or substring, or zero if the string is not changed.
Remarks
Replace can change the string length because lpszNew and lpszOld do not have to be the same length, and several copies of the old substring can be changed to the new one. The function performs a case-sensitive match
CString::ReverseFind¶
Searches this CString
object for the last match of a character
int CString::ReverseFind(char ch);
Parameters
char
ch - the character to search for
Return Value
The zero-based index of the last character in this CString
object that matches the requested character, or -1
if the character is not found.
CString::Right¶
Extracts the last (that is, rightmost) nCount characters from this CString
object and returns a copy of the extracted substring.
CString CString::Right(int nCount);
Parameters
int
nCount - the number of characters to extract from thisCString
object
Return Value
Returns CString
Remarks
If nCount exceeds the string length, then the entire string is extracted
CString::SetAt¶
void CString::SetAt(int nIndex, char ch);
Parameters
int
nIndex -char
ch -
Remarks
CString::SpanExcluding¶
Extracts characters from the string, starting with the first character, that are not in the set of characters identified by lpszCharSet
CString CString::SpanExcluding(const char* lpszCharSet);
Parameters
const char
* lpszCharSet - a string interpreted as a set of characters
Return Value
Returns CString
Remarks
SpanExcluding extracts and returns all characters preceding the first occurrence of a character from lpszCharSet (in other words, the character from lpszCharSet and all characters following it in the string, are not returned). If no character from lpszCharSet is found in the string, then SpanExcluding returns the entire string.
CString::SpanIncluding¶
Extracts characters from the string, starting with the first character, that are in the set of characters identified by lpszCharSet
CString CString::SpanIncluding(const char* lpszCharSet);
Parameters
const char
* lpszCharSet - a string interpreted as a set of characters
Return Value
Returns CString
Remarks
If the first character of the string is not in the character set, then SpanIncluding returns an empty string. Otherwise, it returns a sequence of consecutive characters that are in the set
CString::TrimLeft¶
Trims leading characters from the string
CString::TrimLeft();
Remarks
Removes all leading and trailing occurrences of whitespace
CString::TrimRight¶
Trims trailing characters from the string
void CString::TrimRight(char chTarget);
Parameters
char
chTarget - the target character to be trimmed
Remarks
Removes trailing occurrences of whitespace
CString::TrimRight¶
Trims trailing characters from the string
void CString::TrimRight(const char* lpszTargetList);
Parameters
const char
* lpszTargetList - a pointer to a string containing the target characters to be trimmed. All trailing occurrences of characters in lpszTargetList will be trimmed from theCString
object
Remarks
Removes trailing occurrences of whitespace
CString::TrimRight¶
Trims trailing characters from the string
CString::TrimRight();
Remarks
Removes trailing occurrences of whitespace
Operators¶
Name |
Description |
Assigns a new value to the string |
|
Concatenates characters to the end of the string |
CString::operator=¶
Assigns a new value to the string
CString& CString::operator=(char ch);
Parameters
char
ch - an ANSI or Unicode character to assign to the string
Return Value
Remarks
The assignment operator accepts another CString
object, a character pointer, or a single character. You should be aware that memory exceptions can occur whenever you use this operator because new storage can be allocated
CString::operator=¶
Assigns a new value to the string
CString& CString::operator=(CString& stringSrc);
Parameters
CString& stringSrc - a
CString
to assign to this string
Return Value
Remarks
The assignment operator accepts another CString
object, a character pointer, or a single character. You should be aware that memory exceptions can occur whenever you use this operator because new storage can be allocated
CString::operator=¶
Assigns a new value to the string
CString& CString::operator=(const char* lpsz);
Parameters
const char* lpsz - a pointer to the original string being assigned
Return Value
Remarks
The assignment operator accepts another CString
object, a character pointer, or a single character. You should be aware that memory exceptions can occur whenever you use this operator because new storage can be allocated
CString::operator+=¶
Concatenates characters to the end of the string
CString& CString::operator+=(CString& string);
Parameters
CString& string - a
CString
to concatenate with a string or character
Return Value
Remarks
CString::operator+=¶
Concatenates characters to the end of the string
CString& CString::operator+=(char ch);
Parameters
char
ch - an ANSI or Unicode character to concatenate with a string
Return Value
Remarks
CString::operator+=¶
Concatenates characters to the end of the string
CString& CString::operator+=(const char* lpsz);
Parameters
const char
* lpsz - a pointer to a null-terminated string to concatenate with a string or character
Return Value
Remarks