CkString C Library Reference
CkString
* This is a freeware class/C library/library.
Create/Dispose
HCkString CkString_Create(void);
Creates an instance of the CkString 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.
C "Properties"
BOOL CkString_getUtf8(HCkString handle);
void CkString_putUtf8(HCkString handle, BOOL newVal);
When set to true, all "const char *" arguments are expected to be utf-8 strings. If set to false, the "const char *" arguments are expected to be ANSI strings.
C "Methods"
void CkString_append(HCkString handle, const char *s);
The inStr is appended to this string (the caller).
void CkString_appendAnsi(HCkString handle, const char *s);
Appends an ANSI string to the existing contents of the CkString object.
void CkString_appendChar(HCkString handle, char c);
Appends a single ANSI character to the string.
void CkString_appendCurrentDateRfc822(HCkString handle);
To be documented soon...
void CkString_appendDateRfc822(HCkString handle, SYSTEMTIME *sysTime);
The Date (dt) is appended in RFC 822 format to this string.
void CkString_appendEnc(HCkString handle, const char *s, const char *encoding);
Appends a string in any character encoding to the existing contents of the CkString object. Examples of character encodings are: Shift_JIS, windows-1255, iso-8859-2, gb2312, etc.
void CkString_appendHexData(HCkString handle, const unsigned char *data, int dataLen);
Convert the binary data to a hex string representation and append.
void CkString_appendInt(HCkString handle, int n);
Appends an integer to the string.
void CkString_appendLastWindowsError(HCkString handle);
For many Win32 SDK functions, such as CreateFile, error informationmust be retrieved by using the Win32 functions GetLastError and FormatMessage.This method calls these Win32 functions to format the error and append itto the string.
void CkString_appendN(HCkString handle, const char *s, int numBytes);
Appends N characters to the string.
void CkString_appendNU(HCkString handle, const wchar_t *unicode, int numChars);
Append N Unicode characters to a string.
void CkString_appendStr(HCkString handle, HCkString str);
Appends the contents of another CkString.
void CkString_appendU(HCkString handle, const wchar_t *unicode);
Append a Unicode string to the CkString object.
void CkString_appendUtf8(HCkString handle, const char *s);
Appends a UTF-8 string to the existing contents of the CkString object.
void CkString_base64Decode(HCkString handle, const char *charset);
In-place base64 decodes the string and inteprets the results according to the character encoding specified.
void CkString_base64Encode(HCkString handle, const char *charset);
In-place base64 encodes the string. Internally, the string is first converted to the character encoding specified and then base-64 encoded.
BOOL CkString_beginsWith(HCkString handle, const char *sSubstr);
Returns 1 if the string begins with substr. Otherwise returns 0.
BOOL CkString_beginsWithStr(HCkString handle, HCkString s);
Returns true if the string begins with the specified substring.
char CkString_charAt(HCkString handle, int idx);
Returns the ANSI character at a specified index.The first character is at index 0.
wchar_t CkString_charAtU(HCkString handle, int idx);
Return the Nth character as a Unicode character.
void CkString_chopAtFirstChar(HCkString handle, char c1);
Replace the first occurance of a specified ANSI character with a null terminator.
void CkString_chopAtStr(HCkString handle, HCkString str);
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 handle);
Clears the string. After calling this method, the string has 0 characters.
HCkString CkString_clone(HCkString handle);
Creates a copy of the string. Returns a null on failure
int CkString_compareStr(HCkString handle, HCkString str);
Compare two strings. A return value = 0 means they are equal. Return value = 1 indicates that calling object is less than argument. Return value = -1 indicates that calling object is greater than argument.
BOOL CkString_containsSubstring(HCkString handle, const char *pattern);
Returns true if the string contains the specified substring. The substring may be a wildcarded pattern containing the '*' character which matches 0 or more of any character. The matching is case-sensitive.
BOOL CkString_containsSubstringNoCase(HCkString handle, const char *pattern);
Same as containsSubstring except the matching is case insensitive.
int CkString_countCharOccurances(HCkString handle, char ch);
To be documented soon.
void CkString_decodeXMLSpecial(HCkString handle);
Decodes XML special characters.Example: < is converted to '<'
void CkString_eliminateChar(HCkString handle, char ansiChar, int startIndex);
Eliminate all occurances of a particular ANSI character.
void CkString_encodeXMLSpecial(HCkString handle);
Encodes XML special characters.Example: '<' is converted to <
BOOL CkString_endsWith(HCkString handle, const char *s);
Returns 1 if the string ends with subStr (case-sensitive). Otherwise returns 0.
BOOL CkString_endsWithStr(HCkString handle, HCkString s);
Returns true if the string ends with the specified substring.
void CkString_entityDecode(HCkString handle);
Decodes any HTML entities found within the string, replacing them with the characters represented.
void CkString_entityEncode(HCkString handle);
HTML encodes any characters that are special to HTML or cannot be represented by 7-bit us-ascii.
BOOL CkString_equals(HCkString handle, const char *s);
Returns true if the strings are equal. (case-sensitive)
BOOL CkString_equalsIgnoreCase(HCkString handle, const char *s);
Returns true if the strings are equal. (case-insensitive)
BOOL CkString_equalsIgnoreCaseStr(HCkString handle, HCkString s);
Returns true if the strings are equal. (case-insensitive)
BOOL CkString_equalsStr(HCkString handle, HCkString s);
Returns true if the strings are equal. (case-sensitive)
const char *CkString_getAnsi(HCkString handle);
Return a pointer to the memory containing the string in the ANSI character encoding.
HCkString CkString_getChar(HCkString handle, 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. Returns a null on failure
const char *CkString_getEnc(HCkString handle, const char *encoding);
Returns the string converted to any multi-byte character encoding. Examples of character encodings include Shift_JIS, iso-8859-7, windows-1256, etc.
int CkString_getNumChars(HCkString handle);
Returns the number of characters in the string.
int CkString_getSizeAnsi(HCkString handle);
Returns the size, in bytes, of the ANSI representation of the string.
int CkString_getSizeUnicode(HCkString handle);
Returns the size, in bytes, of the Unicode representation of the string.
int CkString_getSizeUtf8(HCkString handle);
Returns the size, in bytes, of the utf-8 representation of the string.
const char *CkString_getString(HCkString handle);
Returns a pointer to the memory containing the string. The caller should not delete this memory.
const wchar_t *CkString_getUnicode(HCkString handle);
Return a pointer to memory containing the string in Unicode.
const char *CkString_getStringUtf8(HCkString handle);
Return a pointer to memory containing the string in utf-8.
void CkString_hexDecode(HCkString handle, const char *charset);
Hex decodes a string and inteprets the bytes according to the character encoding specified.
void CkString_hexEncode(HCkString handle, const char *charset);
Converts the string to the character encoding specified and replaces the string contents with the hex encoding of the character data.
int CkString_indexOf(HCkString handle, const char *s);
Returns the index of the first occurance of a substring. Returns -1 if not found.
int CkString_indexOfStr(HCkString handle, HCkString s);
Returns the index of the first occurance of a substring. Returns -1 if not found.
int CkString_intValue(HCkString handle);
Returns the string converted to an integer value.
char CkString_lastChar(HCkString handle);
Returns the last ANSI character in the string.
BOOL CkString_loadFile(HCkString handle, const char *fileName, const char *charset);
Loads an entire text file into the string object. The character encoding of the text file is specified by charset. This method allows for text files in any charset to be loaded: utf-8, Unicode, Shift_JIS, iso-8859-1, etc.
BOOL CkString_matches(HCkString handle, const char *s);
Returns 1 if the string matches the pattern, which may contain one or more asterisk wildcard characters. Case-sensitivity is controlled by , where 1 = case sensitive, 0 = case insensitive. ASP String Patttern Matching
BOOL CkString_matchesStr(HCkString handle, HCkString str);
Returns true if the string matches a pattern. The pattern may contain any number of wildcard '*' characters which represent 0 or more occurances of any character.
void CkString_minimizeMemory(HCkString handle);
To be documented soon...
void CkString_prepend(HCkString handle, const char *s);
Prepends inStr to the string (i.e. to the caller).
void CkString_qpDecode(HCkString handle, const char *charset);
Quoted-printable decodes the string and interprets the resulting character data according to the charset (character encoding) specified. The result is that the quoted-printable string is in-place decoded.
void CkString_qpEncode(HCkString handle, const char *charset);
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.
int CkString_removeAll(HCkString handle, HCkString str);
Removes all occurances of a substring.
void CkString_removeCharOccurances(HCkString handle, char c);
Removes all occurances of a specific character from the string.
void CkString_removeChunk(HCkString handle, int charStartPos, int numChars);
Removes a chunk of characters specified by starting index and length.
BOOL CkString_removeFirst(HCkString handle, HCkString str);
Removes the first occurance of a substring.
int CkString_replaceAll(HCkString handle, HCkString str, HCkString replacement);
Replaces all occurances of substr with replacement. (case sensitive)
int CkString_replaceAllOccurances(HCkString handle, const char *pattern, const char *replacement);
Replaces all occurances of a substring with another substring. If the replacement substring can be empty or differ in length.
void CkString_replaceChar(HCkString handle, char c1, char c2);
Replaces all occurances of a specified ANSI character with another.
BOOL CkString_replaceFirst(HCkString handle, HCkString str, HCkString replacement);
Replaces the first occurance of substr with replacement. (case sensitive)
BOOL CkString_replaceFirstOccurance(HCkString handle, const char *pattern, const char *replacement);
Replaces the first occurance of a substring with another.
BOOL CkString_saveToFile(HCkString handle, const char *filename, const char *charset);
Saves the string to a file, using the character encoding specified by charset. This method allows for the string to be saved using character encodings such as "utf-8", "Unicode", "Shift-JIS", or anything else...
void CkString_setStr(HCkString handle, HCkString s);
Replaces the contents of the string with another.
void CkString_setString(HCkString handle, const char *s);
Same as clearing the string and appending.
void CkString_setStringAnsi(HCkString handle, const char *s);
Set the CkString object from an ANSI string.
void CkString_setStringU(HCkString handle, const wchar_t *unicode);
Set the CkString object from a Unicode string.
void CkString_setStringUtf8(HCkString handle, const char *s);
Set the string object from a utf-8 string.
void CkString_shorten(HCkString handle, int n);
Removes the final numChars from the string.
HCkStringArray CkString_split(HCkString handle, char splitChar, BOOL exceptDoubleQuoted, BOOL exceptEscaped, BOOL keepEmpty);
Splits a string into an array of strings using a delimiter character. If "exceptEscaped" is true, then escaped (with a backslash) delimiter chars are ignored. If "exceptDoubleQuoted" is true, then delimiter chars inside quotes are ignored. If keepEmpty is false, then empty strings are excluded from the array. Returns a null reference on failure
HCkStringArray CkString_split2(HCkString handle, const char *splitCharSet, BOOL exceptDoubleQuoted, BOOL exceptEscaped, BOOL keepEmpty);
Same as "split", except a set of characters can be used for delimiters. Returns a null reference on failure
HCkStringArray CkString_splitAtWS(HCkString handle);
Equivalent to split2(" \t\r\n",true,true,false) Returns a null reference on failure
HCkString CkString_substring(HCkString handle, int startCharIdx, int numChars);
Returns a substring specified by starting character position and number of characters. Returns a null on failure
void CkString_toCRLF(HCkString handle);
Make all end of lines a CRLF ("\r\n")
void CkString_toLF(HCkString handle);
Make all end of lines a "\n"
void CkString_toLowerCase(HCkString handle);
Converts the string to lowercase.
void CkString_toUpperCase(HCkString handle);
Converts the string to uppercase.
HCkStringArray CkString_tokenize(HCkString handle, 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 Returns a null reference on failure
void CkString_trim(HCkString handle);
Trim SPACE and Tab characters from both ends of the string.
void CkString_trim2(HCkString handle);
Trim SPACE, Tab, CR, and LF characters from both ends of the string.
void CkString_trimInsideSpaces(HCkString handle);
Finds and replaces all SPACE chracter runs to single SPACE characters.
void CkString_urlDecode(HCkString handle, const char *charset);
URL decodes the string and interprets the resulting byte data in the charset specified.
void CkString_urlEncode(HCkString handle, const char *charset);
URL encodes the string. The string is first converted to the charset specified, and those bytes are URL-encoded. The contents of the string are replaced with the URL-encoded result.
|