CkString C Reference Documentation
CkString
Current Version: 10.1.0
The Chilkat string class.
Create/Dispose
HCkString instance = CkString_Create(); // ... CkString_Dispose(instance);
Creates an instance of the HCkString object and returns a handle ("void *" pointer). The handle is passed in the 1st argument for the functions listed on this page.
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
NumArabic
The number of Arabic characters contained in this string.
topNumAscii
The number of us-ascii characters contained in this string.
topNumCentralEuro
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.
topNumChinese
The number of Chinese characters contained in this string.
topNumCyrillic
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.
topNumGreek
The number of Greek characters contained in this string.
topNumHebrew
The number of Hebrew characters contained in this string.
topNumJapanese
The number of Japanese characters contained in this string.
topNumKorean
The number of Korean characters contained in this string.
topNumLatin
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.
Note: This is the number of chars that are Latin characters that do not fall in the us-ascii range. In other words, the 8bit Latin chars.
topNumThai
The number of Thai characters contained in this string.
topMethods
append
The str is appended to end of this instance.
topappendAnsi
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.
topappendChar
Appends a single ANSI character to the end of this instance.
topappendCurrentDateRfc822
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"
topappendDateRfc822
The dateTime is appended in RFC 822 format to the end of this instance.
topappendDateRfc822Gmt
The dateTime is appended in RFC 822 format using GMT to the end of this instance.
topappendEnc
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.
appendHexData
Converts the binary data to a hexidecimal string representation and appends to the end of this instance. The hex data is appended in 2-byte chunks with 16 bytes per line. For example:
6861 6C6C 6861 6C6C 6861 6C6C 6861 6C6C 6861 6C6C 6861 6C6C 6861 6C6C 6861 6C6C 6861 6C6C 6861 6C6C 6861 6C6C 6861 6C6Ctop
appendInt
Appends the decimal string representation of an integer to the end of this instance.
topappendLastWindowsError
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.
topappendN
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.
topappendNU
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).
topappendRandom
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".
topappendStr
Appends the contents of strObj to the end of this instance.
topappendU
Append a Unicode string to the CkString object.
topappendUtf8
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.
topbase64Decode
In-place base64 decodes the string and inteprets the results according to the character encoding specified.
base64DecodeW
The utf-16 version of base64Decode.
topbase64Encode
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.
base64EncodeW
The utf-16 version of base64Encode.
topbeginsWith
Return TRUE if this string begins with substr (case sensitive), otherwise returns FALSE.
topbeginsWithStr
Returns TRUE if the string begins with the contents of strObj. Otherwise returns FALSE. This method is case sensitive.
topbeginsWithW
The utf-16 version of beginsWith.
topcharAt
Returns the ANSI character at a specified index.The first character is at index 0.
topcharAtU
Return the Nth character as a Unicode character.
topchopAtFirstChar
Finds the first occurrence of ch and discards the characters at and following ch.
topchopAtStr
Finds the first occurrence of a substring and chops it at that point. The result is that the substring and all subsequent characters are removed from the string.
topclear
Clears the string. The string contains 0 characters after calling this method.
topclone
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.
Returns NULL on failure
topcompareStr
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.
topcontainsSubstring
Returns TRUE if the string contains the specified substring, otherwise returns FALSE. The string comparison is case-sensitive.
topcontainsSubstringNoCase
Same as containsSubstring except the matching is case insensitive.
topcontainsSubstringNoCaseW
The utf-16 version of containsSubstringNoCase.
topcontainsSubstringW
The utf-16 version of containsSubstring.
topcountCharOccurances
Returns the number of occurrences of the specified ANSI char.
topdecodeXMLSpecial
Decodes XML special characters. For example, < is converted to '<'
topdoubleValue
Converts the string to a double and returns the value.
topeliminateChar
Eliminate all occurrences of a particular ANSI character.
topencodeXMLSpecial
Encodes XML special characters. For example, '<' is converted to <
topendsWith
Returns TRUE if the string ends with substr (case-sensitive). Otherwise returns FALSE.
topendsWithStr
Returns TRUE if the string ends with the specified substring, otherwise returns FALSE.
topendsWithW
The utf-16 version of endsWith.
topentityDecode
Decodes any HTML entities found within the string, replacing them with the characters represented.
topentityEncode
HTML encodes any characters that are special to HTML or cannot be represented by 7-bit us-ascii.
topequals
Returns TRUE if the strings are equal, otherwise returns FALSE. (case-sensitive)
topequalsIgnoreCase
Returns TRUE if the strings are equal, otherwise returns FALSE. (case-insensitive)
topequalsIgnoreCaseStr
Returns TRUE if the strings are equal, otherwise returns FALSE (case-insensitive)
topequalsIgnoreCaseW
The utf-16 version of equalsIgnoreCase.
topequalsStr
Returns TRUE if the strings are equal, otherwise returns FALSE. (case-sensitive)
topequalsW
The utf-16 version of the "equals" method.
topgetChar
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.
Returns NULL on failure
topgetEnc
Returns the string as a null-terminated byte sequence in the character encoding specified by encoding. The encoding can be any encoding specified at the link below, except for charsets that contain 0 (null) bytes in individual character byte representations, such as utf-16, utf-32, etc.
getNumChars
Returns the number of characters in the string.
topgetSizeAnsi
Returns the size, in bytes, of the ANSI encoding of the string.
topgetSizeUnicode
Returns the size, in bytes, of the Unicode encoding of the string.
topgetSizeUtf8
Returns the size, in bytes, of the utf-8 encoding of the string.
topgetString
Returns the contents of this instance.
topgetStringAnsi
Returns the string as null-terminated ANSI.
topgetStringUtf8
Returns the string as null-terminated utf-8.
topgetUnicode
Return a pointer to memory containing the string in Unicode.
tophexDecode
Hex decodes a string and inteprets the bytes according to the character encoding specified.
hexDecodeW
The utf-16 version of hexDecode.
tophexEncode
Converts the string to the character encoding specified and replaces the string contents with the hex encoding of the character data.
hexEncodeW
The utf-16 version of hexEncode.
topindexOf
Returns the index of the first occurrence of a substring. Returns -1 if not found.
topindexOfStr
Returns the index of the first occurrence of a substring. Returns -1 if not found.
topindexOfW
The utf-16 version of "indexOf".
topintValue
Converts the string to an integer and returns the integer value.
topisEmpty
Returns TRUE if the string object is empty, otherwise returns FALSE.
toplastChar
Returns the last ANSI character in the string.
toploadFile
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.
loadFileW
matches
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.
topmatchesNoCase
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.
topmatchesNoCaseW
The utf-16 version of matchesNoCase.
topmatchesStr
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 occurrences of any character. This method is case-sensitive.
topmatchesW
The utf-16 version of the "matches" method.
topminimizeMemory
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.
topobfuscate
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.
topprepend
Prepends str to this instance.
topprependW
The utf-16 version of the "prepend" method.
toppunyDecode
In-place decodes the string from punycode.
toppunyEncode
In-place encodes the string to punycode.
topqpDecode
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.
qpDecodeW
The utf-16 version of the qpDecode method.
topqpEncode
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.
qpEncodeW
The utf-16 version of the qpEncode method.
topremoveAll
Removes all occurrences of substr.
topremoveCharOccurances
Removes all occurrences of a specific ANSI character from the string.
topremoveChunk
Removes a chunk of characters specified by starting index and length.
topremoveDelimited
Remove all occurrences of strings delimited by beginDelim and endDelim. Also removes the delimiters.
topremoveFirst
Removes the first occurrence of a substring.
topreplaceAll
Replaces all occurrences of a substring with another. The replacement string is allowed to be empty or different in length.
topreplaceAllOccurances
Replaces all occurrences of a substring with another substring. The replacement string is allowed to be empty or different in length.
topreplaceAllOccurancesW
The utf-16 version of the replaceAllOccurances method.
topreplaceChar
Replaces all occurrences of a specified ANSI character with another.
topreplaceFirst
Replaces the first occurrence of a substring with another. The replacement string is allowed to be empty or different in length.
topreplaceFirstOccurance
Replaces the first occurrence of a substring with another. The replacement string is allowed to be empty or different in length. (Chilkat is aware of the misspelling of the word "occurrence", but unfortunately it is too late to change..)
topreplaceFirstOccuranceW
The utf-16 version of replaceFirstOccurrance. (Chilkat is aware of the misspelling of the word "occurrence", but unfortunately it is too late to change..)
topsaveToFile
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.
saveToFileW
setStr
Replaces the contents of the string with another.
topsetString
Clears the contents of this instance and appends str.
topsetStringAnsi
Set the CkString object from an ANSI string.
topsetStringU
Set the CkString object from a Unicode string.
topsetStringUtf8
Set the string object from a utf-8 string.
topshorten
Discards the last N characters.
topsplit
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.
Returns NULL on failure
topsplit2
split2W
splitAtWS
substring
Returns a substring specified by starting character position and number of characters. (The 1st char is at index 0.)
Returns NULL on failure
toptoCRLF
Converts all line endings to CRLF.
toptokenize
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
Returns NULL on failure
toptokenizeW
toLF
Converts all line endings to bare-LF (Unix/Linux style line endings).
toptoLowerCase
Converts the string to lowercase.
toptoUpperCase
Converts the string to uppercase.
toptrim
Trim SPACE and Tab characters from both ends of the string.
toptrim2
Trim SPACE, Tab, CR, and LF characters from both ends of the string.
toptrimInsideSpaces
Replaces all tabs, CR's, and LF's, with SPACE chars, and removes extra SPACE's so there are no occurrences of more than one SPACE char in a row.
topunobfuscate
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.
topurlDecode
URL decodes the string and interprets the resulting byte data in the specified charset encoding.
urlDecodeW
The utf-16 version of the urlDecode method.
topurlEncode
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.
urlEncodeW
The utf-16 version of the urlEncode method.
top