CkString C Reference Documentation

CkString

The Chilkat string class.

Create/Dispose

HCkString CkString_Create(void);

Creates an instance of the HCkString object and returns a handle (i.e. a "void *" pointer). The handle is passed in the 1st argument for the functions listed on this page.

void CkString_Dispose(HCkString handle);

Objects created by calling CkString_Create must be freed by calling this method. A memory leak occurs if a handle is not disposed by calling this function. Also, any handle returned by a Chilkat "C" function must also be freed by the application by calling the appropriate Dispose method, such as CkString_Dispose.

Properties

int CkString_getNumArabic(HCkString cHandle);

Introduced in version 9.5.0.25

The number of Arabic characters contained in this string.

int CkString_getNumAscii(HCkString cHandle);

Introduced in version 9.5.0.25

The number of us-ascii characters contained in this string.

int CkString_getNumCentralEuro(HCkString cHandle);

Introduced in version 9.5.0.25

The number of Central European and Eastern European characters found in this string. These are characters specific to Polish, Czech, Slovak, Hungarian, Slovene, Croatian, Serbian (Latin script), Romanian and Albanian.

int CkString_getNumChinese(HCkString cHandle);

Introduced in version 9.5.0.25

The number of Chinese characters contained in this string.

int CkString_getNumCyrillic(HCkString cHandle);

Introduced in version 9.5.0.25

The number of Cyrillic characters contained in this string. The Cyrillic alphabet also called azbuka, from the old name of the first two letters) is actually a family of alphabets, subsets of which are used by certain East and South Slavic languages "” Belarusian, Bulgarian, Macedonian, Russian, Rusyn, Serbian and Ukrainian"”as well as many other languages of the former Soviet Union, Asia and Eastern Europe.

int CkString_getNumGreek(HCkString cHandle);

Introduced in version 9.5.0.25

The number of Greek characters contained in this string.

int CkString_getNumHebrew(HCkString cHandle);

Introduced in version 9.5.0.25

The number of Hebrew characters contained in this string.

int CkString_getNumJapanese(HCkString cHandle);

Introduced in version 9.5.0.25

The number of Japanese characters contained in this string.

int CkString_getNumKorean(HCkString cHandle);

Introduced in version 9.5.0.25

The number of Korean characters contained in this string.

int CkString_getNumLatin(HCkString cHandle);

Introduced in version 9.5.0.25

The number of Latin characters contained in this string. Latin characters include all major Western European languages, such as German, Spanish, French, Italian, Nordic languages, etc.

int CkString_getNumThai(HCkString cHandle);

Introduced in version 9.5.0.25

The number of Thai characters contained in this string.

Methods

void CkString_append(HCkString cHandle, const char *str);

The str is appended to end of this instance.

void CkString_appendAnsi(HCkString cHandle, const char *str);

Appends an ANSI string to the end of this instance. str should always be a null terminated ANSI string regardless of the Utf8 property setting.

void CkString_appendChar(HCkString cHandle, char c);

Appends a single ANSI character to the end of this instance.

void CkString_appendCurrentDateRfc822(HCkString cHandle);

Appends the current date/time to the end of this instance. The date/time is formatted according to the RFC822 standard, which is the typical format used in the "Date" header field of email. For example: "Fri, 27 Jul 2012 17:41:41 -0500"

void CkString_appendDateRfc822(HCkString cHandle, SYSTEMTIME *dateTime);

The dateTime is appended in RFC 822 format to the end of this instance.

void CkString_appendDateRfc822Gmt(HCkString cHandle, SYSTEMTIME *dateTime);

The dateTime is appended in RFC 822 format using GMT to the end of this instance.

void CkString_appendEnc(HCkString cHandle, const char *str, const char *charsetEncoding);

Appends a string of any character encoding to the end of this instance. Examples of charsetEncoding are: Shift_JIS, windows-1255, iso-8859-2, gb2312, etc. The str should point to a null-terminated string that uses the charset specified by charsetEncoding.

Supported Character Encodings

void CkString_appendHexData(HCkString cHandle, const unsigned char *byteData, unsigned long numBytes);

Converts the binary data to a hexidecimal string representation and appends to the end of this instance.

void CkString_appendInt(HCkString cHandle, int n);

Appends the decimal string representation of an integer to the end of this instance.

void CkString_appendLastWindowsError(HCkString cHandle);

For many Win32 Platform SDK functions, such as CreateFile, error information must be retrieved by using the Win32 functions GetLastError and FormatMessage. This method calls these Win32 functions to format the error and appends it to the string.

This method would only be used by Win32 applications that call Platform SDK functions.

void CkString_appendN(HCkString cHandle, const char *str, unsigned long numBytes);

Appends N bytes of character data to the end of this instance. If the Utf8 property is set to TRUE, then str should point to characters in the utf-8 encoding, otherwise it should point to characters using the ANSI encoding. Note: numBytes is not necessarily the number of characters. It is the length, in bytes, of the string to be appended. This method exists to allow for non-null terminated strings to be appended.

void CkString_appendNU(HCkString cHandle, const wchar_t *wideStr, int numChars);

Append N Unicode characters to the end of this instance. The wideStr points to the 2-byte per char Unicode string. The numChars is the number of Unicode characters to be appended (not the number of bytes).

void CkString_appendRandom(HCkString cHandle, int numBytes, const char *encoding);

Appends numBytes random bytes to the end of this instance. Because arbitrary byte values in the range 0 to 255 do not necessarily represent valid characters, the bytes must be encoded to a string friendly representation such as hex, base64, etc. The encoding specifies the encoding to be used. Possible values are "hex", "base64", "quoted-printable", "asc", or "url".

void CkString_appendStr(HCkString cHandle, HCkString strObj);

Appends the contents of strObj to the end of this instance.

void CkString_appendU(HCkString cHandle, const wchar_t *unicode);

Append a Unicode string to the CkString object.

void CkString_appendUtf8(HCkString cHandle, const char *str);

Appends a utf-8 string to the existing contents of this instance. str should always be a null terminated utf-8 string regardless of the Utf8 property setting.

void CkString_base64Decode(HCkString cHandle, const char *charsetEncoding);

In-place base64 decodes the string and inteprets the results according to the character encoding specified.

Supported Character Encodings

void CkString_base64DecodeW(HCkString cHandle, const wchar_t *charsetEncoding);

The utf-16 version of base64Decode.

void CkString_base64Encode(HCkString cHandle, const char *charsetEncoding);

In-place base64 encodes the string. Internally, the string is first converted to the character encoding specified and then base-64 encoded. Typical charsetEncoding values are "utf-8", "ANSI", "iso-8859-1", etc.

Supported Character Encodings

void CkString_base64EncodeW(HCkString cHandle, const wchar_t *charsetEncoding);

The utf-16 version of base64Encode.

BOOL CkString_beginsWith(HCkString cHandle, const char *substr);

Return TRUE if this string begins with substr (case sensitive), otherwise returns FALSE.

BOOL CkString_beginsWithStr(HCkString cHandle, HCkString strObj);

Returns TRUE if the string begins with the contents of strObj. Otherwise returns FALSE. This method is case sensitive.

BOOL CkString_beginsWithW(HCkString cHandle, const wchar_t *str);

The utf-16 version of beginsWith.

char CkString_charAt(HCkString cHandle, int idx);

Returns the ANSI character at a specified index.The first character is at index 0.

wchar_t CkString_charAtU(HCkString cHandle, int idx);

Return the Nth character as a Unicode character.

void CkString_chopAtFirstChar(HCkString cHandle, char ch);

Finds the first occurance of ch and discards the characters at and following ch.

void CkString_chopAtStr(HCkString cHandle, HCkString subStrObj);

Finds the first occurance of a substring and chops it at that point. The result is that the substring and all subsequent characters are removed from the string.

void CkString_clear(HCkString cHandle);

Clears the string. The string contains 0 characters after calling this method.

HCkString CkString_clone(HCkString cHandle);

Creates a copy of the string. As with any newly created Chilkat object instance returned by a Chilkat method, the returned CkString object must be deleted by the calling application.

int CkString_compareStr(HCkString cHandle, HCkString str);

Compare two strings. A return value = 0 means they are equal. Return value = 1 indicates that calling object is lexicographically less than argument. Return value = -1 indicates that calling object is lexicographically greater than argument.

BOOL CkString_containsSubstring(HCkString cHandle, const char *substr);

Returns TRUE if the string contains the specified substring, otherwise returns FALSE. The string comparison is case-sensitive.

BOOL CkString_containsSubstringNoCase(HCkString cHandle, const char *substr);

Same as containsSubstring except the matching is case insensitive.

BOOL CkString_containsSubstringNoCaseW(HCkString cHandle, const wchar_t *substr);

The utf-16 version of containsSubstringNoCase.

BOOL CkString_containsSubstringW(HCkString cHandle, const wchar_t *substr);

The utf-16 version of containsSubstring.

int CkString_countCharOccurances(HCkString cHandle, char ch);

Returns the number of occurances of the specified ANSI char.

void CkString_decodeXMLSpecial(HCkString cHandle);

Decodes XML special characters. For example, &lt; is converted to '<'

double CkString_doubleValue(HCkString cHandle);

Converts the string to a double and returns the value.

void CkString_eliminateChar(HCkString cHandle, char ansiChar, int startIndex);

Eliminate all occurances of a particular ANSI character.

void CkString_encodeXMLSpecial(HCkString cHandle);

Encodes XML special characters. For example, '<' is converted to &lt;

BOOL CkString_endsWith(HCkString cHandle, const char *substr);

Returns TRUE if the string ends with substr (case-sensitive). Otherwise returns FALSE.

BOOL CkString_endsWithStr(HCkString cHandle, HCkString substrObj);

Returns TRUE if the string ends with the specified substring, otherwise returns FALSE.

BOOL CkString_endsWithW(HCkString cHandle, const wchar_t *s);

The utf-16 version of endsWith.

void CkString_entityDecode(HCkString cHandle);

Decodes any HTML entities found within the string, replacing them with the characters represented.

void CkString_entityEncode(HCkString cHandle);

HTML encodes any characters that are special to HTML or cannot be represented by 7-bit us-ascii.

BOOL CkString_equals(HCkString cHandle, const char *str);

Returns TRUE if the strings are equal, otherwise returns FALSE. (case-sensitive)

BOOL CkString_equalsIgnoreCase(HCkString cHandle, const char *str);

Returns TRUE if the strings are equal, otherwise returns FALSE. (case-insensitive)

BOOL CkString_equalsIgnoreCaseStr(HCkString cHandle, HCkString strObj);

Returns TRUE if the strings are equal, otherwise returns FALSE (case-insensitive)

BOOL CkString_equalsIgnoreCaseW(HCkString cHandle, const wchar_t *s);

The utf-16 version of equalsIgnoreCase.

BOOL CkString_equalsStr(HCkString cHandle, HCkString strObj);

Returns TRUE if the strings are equal, otherwise returns FALSE. (case-sensitive)

BOOL CkString_equalsW(HCkString cHandle, const wchar_t *s);

The utf-16 version of the "equals" method.

HCkString CkString_getChar(HCkString cHandle, int idx);

Returns a new CkString object containing the Nth character. (Note, it does not contain the Nth byte, but the Nth character.) For languages such as Chinese, Japanese, etc. individual characters are represented by multiple or varying number of bytes.

int CkString_getNumChars(HCkString cHandle);

Returns the number of characters in the string.

int CkString_getSizeAnsi(HCkString cHandle);

Returns the size, in bytes, of the ANSI encoding of the string.

int CkString_getSizeUnicode(HCkString cHandle);

Returns the size, in bytes, of the Unicode encoding of the string.

int CkString_getSizeUtf8(HCkString cHandle);

Returns the size, in bytes, of the utf-8 encoding of the string.

const char *CkString_getString(HCkString cHandle);

const char *CkString_getString(HCkString cHandle);

Returns the contents of this instance.

Returns NULL on failure

const char *CkString_getStringAnsi(HCkString cHandle);

const char *CkString_getStringAnsi(HCkString cHandle);

Returns the string as null-terminated ANSI.

Returns NULL on failure

const char *CkString_getStringUtf8(HCkString cHandle);

const char *CkString_getStringUtf8(HCkString cHandle);

Returns the string as null-terminated utf-8.

Returns NULL on failure

const wchar_t *CkString_getUnicode(HCkString cHandle);

Return a pointer to memory containing the string in Unicode.

void CkString_hexDecode(HCkString cHandle, const char *charsetEncoding);

Hex decodes a string and inteprets the bytes according to the character encoding specified.

Supported Character Encodings

void CkString_hexDecodeW(HCkString cHandle, const wchar_t *charsetEncoding);

The utf-16 version of hexDecode.

void CkString_hexEncode(HCkString cHandle, const char *charsetEncoding);

Converts the string to the character encoding specified and replaces the string contents with the hex encoding of the character data.

Supported Character Encodings

void CkString_hexEncodeW(HCkString cHandle, const wchar_t *charsetEncoding);

The utf-16 version of hexEncode.

int CkString_indexOf(HCkString cHandle, const char *substr);

Returns the index of the first occurance of a substring. Returns -1 if not found.

int CkString_indexOfStr(HCkString cHandle, HCkString substrObj);

Returns the index of the first occurance of a substring. Returns -1 if not found.

int CkString_indexOfW(HCkString cHandle, const wchar_t *s);

The utf-16 version of "indexOf".

int CkString_intValue(HCkString cHandle);

Converts the string to an integer and returns the integer value.

BOOL CkString_isEmpty(HCkString cHandle);

Returns TRUE if the string object is empty, otherwise returns FALSE.

char CkString_lastChar(HCkString cHandle);

Returns the last ANSI character in the string.

BOOL CkString_loadFile(HCkString cHandle, const char *path, const char *charsetEncoding);

Load the contents of a text file into the CkString object. The string is cleared before loading. The character encoding of the text file is specified by charsetEncoding. This method allows for text files in any charset to be loaded: utf-8, Unicode, Shift_JIS, iso-8859-1, etc.

Returns TRUE for success, FALSE for failure.

Supported Character Encodings

BOOL CkString_loadFileW(HCkString cHandle, const wchar_t *path, const wchar_t *charsetEncoding);

The utf-16 version of loadFile.

Returns TRUE for success, FALSE for failure.

BOOL CkString_matches(HCkString cHandle, const char *strPattern);

Returns TRUE if the string matches the strPattern, which may contain one or more asterisk wildcard characters. Returns FALSE if the string does not match. This method is case-sensitive.

BOOL CkString_matchesNoCase(HCkString cHandle, const char *strPattern);

Returns TRUE if the string matches the strPattern, which may contain one or more asterisk wildcard characters. Returns FALSE if the string does not match. This method is case-insensitive.

BOOL CkString_matchesNoCaseW(HCkString cHandle, const wchar_t *s);

The utf-16 version of matchesNoCase.

BOOL CkString_matchesStr(HCkString cHandle, HCkString strPatternObj);

Returns TRUE if the string matches a pattern, otherwise returns FALSE. The pattern may contain any number of wildcard '*' characters which represent 0 or more occurances of any character. This method is case-sensitive.

BOOL CkString_matchesW(HCkString cHandle, const wchar_t *s);

The utf-16 version of the "matches" method.

void CkString_minimizeMemory(HCkString cHandle);

Minimizes the amount of memory consumed by this object. For example, consider the following: A CkString object is loaded with the contents of a text file. The "replaceAllOccurances" method is called, replacing longer substrings with shorter replacements. The actual string length will become shorter than the internal buffer space that is allocated. The minimizeMemory method will, if necessary, allocate a new internal buffer that is exactly the size needed to hold the current contents of the string, copy the string to the new internal buffer, and deallocate the old buffer.

void CkString_obfuscate(HCkString cHandle);

Obfuscates the string. (The unobfuscate method can be called to reverse the obfuscation to restore the original string.)

The Chilkat string obfuscation algorithm works by taking the utf-8 bytes of the string, base64 encoding it, and then scrambling the letters of the base64 encoded string. It is deterministic in that the same string will always obfuscate to the same result. It is not a secure way of encrypting a string. It is only meant to be a simple means of transforming a string into something unintelligible.

void CkString_prepend(HCkString cHandle, const char *str);

Prepends str to this instance.

void CkString_prependW(HCkString cHandle, const wchar_t *s);

The utf-16 version of the "prepend" method.

void CkString_punyDecode(HCkString cHandle);

Introduced in version 9.5.0.52

In-place decodes the string from punycode.

Punycode Encoding / Decoding

void CkString_punyEncode(HCkString cHandle);

Introduced in version 9.5.0.52

In-place encodes the string to punycode.

Punycode Encoding / Decoding

void CkString_qpDecode(HCkString cHandle, const char *charsetEncoding);

Quoted-printable decodes the string and interprets the resulting character data according to the specified character encoding. The result is that the quoted-printable string is in-place decoded.

Supported Character Encodings

void CkString_qpDecodeW(HCkString cHandle, const wchar_t *charset);

The utf-16 version of the qpDecode method.

void CkString_qpEncode(HCkString cHandle, const char *charsetEncoding);

Quoted-printable encodes the string. The string is first converted to the charset specified, and those bytes are QP-encoded. The contents of the string are replaced with the QP-encoded result.

Supported Character Encodings

void CkString_qpEncodeW(HCkString cHandle, const wchar_t *charset);

The utf-16 version of the qpEncode method.

int CkString_removeAll(HCkString cHandle, HCkString substr);

Removes all occurances of substr.

void CkString_removeCharOccurances(HCkString cHandle, char ch);

Removes all occurances of a specific ANSI character from the string.

void CkString_removeChunk(HCkString cHandle, int charStartPos, int numChars);

Removes a chunk of characters specified by starting index and length.

void CkString_removeDelimited(HCkString cHandle, const char *beginDelim, const char *endDelim, BOOL caseSensitive);

Introduced in version 9.5.0.52

Remove all occurances of strings delimited by beginDelim and endDelim. Also removes the delimiters.

BOOL CkString_removeFirst(HCkString cHandle, HCkString substr);

Removes the first occurance of a substring.

int CkString_replaceAll(HCkString cHandle, HCkString findStrObj, HCkString replaceStrObj);

Replaces all occurances of a substring with another. The replacement string is allowed to be empty or different in length.

int CkString_replaceAllOccurances(HCkString cHandle, const char *findStr, const char *replaceStr);

Replaces all occurances of a substring with another substring. The replacement string is allowed to be empty or different in length.

int CkString_replaceAllOccurancesW(HCkString cHandle, const wchar_t *pattern, const wchar_t *replacement);

The utf-16 version of the replaceAllOccurances method.

void CkString_replaceChar(HCkString cHandle, char findCh, char replaceCh);

Replaces all occurances of a specified ANSI character with another.

BOOL CkString_replaceFirst(HCkString cHandle, HCkString findStrObj, HCkString replaceStrObj);

Replaces the first occurance of a substring with another. The replacement string is allowed to be empty or different in length.

BOOL CkString_replaceFirstOccurance(HCkString cHandle, const char *findStr, const char *replaceStr);

Replaces the first occurance of a substring with another. The replacement string is allowed to be empty or different in length.

BOOL CkString_replaceFirstOccuranceW(HCkString cHandle, const wchar_t *pattern, const wchar_t *replacement);

The utf-16 version of replaceFirstOccurance.

BOOL CkString_saveToFile(HCkString cHandle, const char *path, const char *charsetEncoding);

Saves the string to a file using the character encoding specified by charsetEncoding. If a file of the same name exists, it is overwritten. For charsets such as "utf-8", "utf-16", or others that have a possible BOM/preamble, the preamble is output by default. To exclude the BOM/preamble, prepend "no-bom-" to the charset name. For example "no-bom-utf-8".

Returns TRUE for success, FALSE for failure.

Supported Character Encodings

BOOL CkString_saveToFileW(HCkString cHandle, const wchar_t *path, const wchar_t *charset);

The utf-16 version of the saveToFile method.

Returns TRUE for success, FALSE for failure.

void CkString_setStr(HCkString cHandle, HCkString s);

Replaces the contents of the string with another.

void CkString_setString(HCkString cHandle, const char *str);

Clears the contents of this instance and appends str.

void CkString_setStringAnsi(HCkString cHandle, const char *s);

Set the CkString object from an ANSI string.

void CkString_setStringU(HCkString cHandle, const wchar_t *unicode);

Set the CkString object from a Unicode string.

void CkString_setStringUtf8(HCkString cHandle, const char *s);

Set the string object from a utf-8 string.

void CkString_shorten(HCkString cHandle, int n);

Discards the last N characters.

HCkStringArray CkString_split(HCkString cHandle, char delimiterChar, BOOL exceptDoubleQuoted, BOOL exceptEscaped, BOOL keepEmpty);

Splits a string into a collection of strings using a delimiter character. If exceptEscaped is TRUE, then delimiter chars escaped with a backslash are ignored. If exceptDoubleQuoted is TRUE, then delimiter chars inside quotes are ignored. If keepEmpty is FALSE, then empty strings are excluded from being added to the returned CkStringArray object.

HCkStringArray CkString_split2(HCkString cHandle, const char *delimiterChars, BOOL exceptDoubleQuoted, BOOL exceptEscaped, BOOL keepEmpty);

Same as "split", except a set of characters can be used for delimiters.

HCkStringArray CkString_split2W(HCkString cHandle, const wchar_t *splitCharSet, BOOL exceptDoubleQuoted, BOOL exceptEscaped, BOOL keepEmpty);

The utf-16 version of the split2 method.

HCkStringArray CkString_splitAtWS(HCkString cHandle);

Equivalent to split2(" \t\r\n",true,true,false)

HCkString CkString_substring(HCkString cHandle, int startCharIndex, int numChars);

Returns a substring specified by starting character position and number of characters. (The 1st char is at index 0.)

void CkString_toCRLF(HCkString cHandle);

Converts all line endings to CRLF.

void CkString_toLF(HCkString cHandle);

Converts all line endings to bare-LF (Unix/Linux style line endings).

void CkString_toLowerCase(HCkString cHandle);

Converts the string to lowercase.

void CkString_toUpperCase(HCkString cHandle);

Converts the string to uppercase.

HCkStringArray CkString_tokenize(HCkString cHandle, const char *punctuation);

Tokenizes a string. The string is split at whitespace characters, and any single punctuation character is returned as a separate token. For example, this string:
CkStringArray *CkString::tokenize(char *punctuation) const

is tokenized to

CkStringArray
*
CkString
:
:
tokenize
(
*
punctuation
)
const

HCkStringArray CkString_tokenizeW(HCkString cHandle, const wchar_t *punctuation);

The utf-16 version of the "tokenize" method.

void CkString_trim(HCkString cHandle);

Trim SPACE and Tab characters from both ends of the string.

void CkString_trim2(HCkString cHandle);

Trim SPACE, Tab, CR, and LF characters from both ends of the string.

void CkString_trimInsideSpaces(HCkString cHandle);

Replaces all tabs, CR's, and LF's, with SPACE chars, and removes extra SPACE's so there are no occurances of more than one SPACE char in a row.

void CkString_unobfuscate(HCkString cHandle);

Unobfuscates the string.

The Chilkat string obfuscation algorithm works by taking the utf-8 bytes of the string, base64 encoding it, and then scrambling the letters of the base64 encoded string. It is deterministic in that the same string will always obfuscate to the same result. It is not a secure way of encrypting a string. It is only meant to be a simple means of transforming a string into something unintelligible.

void CkString_urlDecode(HCkString cHandle, const char *charsetEncoding);

URL decodes the string and interprets the resulting byte data in the specified charset encoding.

Supported Character Encodings

void CkString_urlDecodeW(HCkString cHandle, const wchar_t *charsetEncoding);

The utf-16 version of the urlDecode method.

void CkString_urlEncode(HCkString cHandle, const char *charsetEncoding);

URL encodes the string. The string is first converted to the specified charset encoding, and those bytes are URL-encoded. The contents of the string are replaced with the URL-encoded result.

Supported Character Encodings

void CkString_urlEncodeW(HCkString cHandle, const wchar_t *charsetEncoding);

The utf-16 version of the urlEncode method.