CkString Ruby Programming
Reference Documentation
CkString
The Chilkat string class.
Object Creation
obj = Chilkat::CkString.new()
Properties
# Returns a boolean value
get_Utf8( )
# b is a boolean (input)
put_Utf8( b )
When set to true, all "const char *" arguments are interpreted as utf-8 strings. If set to false (the default), then "const char *" arguments are interpreted as ANSI strings.
Also, when set to true, and Chilkat method returning a "const char *" is returning the utf-8 representation. If set to false, all "const char *" return values are ANSI strings.
Methods
# str is a string (input)
append( str )
The str is appended to end of this instance.
# str is a string (input)
appendAnsi( 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.
# c is a char (input)
appendChar( c )
Appends a single ANSI character to the end of this instance.
appendCurrentDateRfc822( )
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"
# str is a string (input)
# charsetEncoding is a string (input)
appendEnc( str, 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
# byteData is a string (input)
# numBytes is an integer (input)
appendHexData( byteData, numBytes )
Converts the binary data to a hexidecimal string representation and appends to the end of this instance.
# n is an integer (input)
appendInt( n )
Appends the decimal string representation of an integer to the end of this instance.
# str is a string (input)
# numBytes is an integer (input)
appendN( str, 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.
# strObj is a CkString (input)
appendStr( strObj )
Appends the contents of strObj to the end of this instance.
# str is a string (input)
appendUtf8( 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.
# charsetEncoding is a string (input)
base64Decode( charsetEncoding )
In-place base64 decodes the string and inteprets the results according to the character encoding specified. Supported Character Encodings
# charsetEncoding is a string (input)
base64Encode( 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
# substr is a string (input)
# Returns a boolean value
beginsWith( substr )
Return true if this string begins with substr (case sensitive), otherwise returns false.
# strObj is a CkString (input)
# Returns a boolean value
beginsWithStr( strObj )
Returns true if the string begins with the contents of strObj. Otherwise returns false. This method is case sensitive. Returns true for success, false for failure.
# idx is an integer (input)
# Returns a char
charAt( idx )
Returns the ANSI character at a specified index.The first character is at index 0. Returns a null on failure
# ch is a char (input)
chopAtFirstChar( ch )
Finds the first occurance of ch and discards the characters at and following ch.
# subStrObj is a CkString (input)
chopAtStr( 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. Returns true for success, false for failure.
clear( )
Clears the string. The string contains 0 characters after calling this method.
# Returns a CkString
clone( )
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 a null on failure
# str is a CkString (input)
# Returns an integer value
compareStr( 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. Returns true for success, false for failure.
# substr is a string (input)
# Returns a boolean value
containsSubstring( substr )
Returns true if the string contains the specified substring, otherwise returns false. The string comparison is case-sensitive.
# substr is a string (input)
# Returns a boolean value
containsSubstringNoCase( substr )
Same as containsSubstring except the matching is case insensitive.
# ch is a char (input)
# Returns an integer value
countCharOccurances( ch )
Returns the number of occurances of the specified ANSI char.
decodeXMLSpecial( )
Decodes XML special characters. For example, < is converted to '<'
# Returns a floating point value
doubleValue( )
Converts the string to a double and returns the value.
# ansiChar is a char (input)
# startIndex is an integer (input)
eliminateChar( ansiChar, startIndex )
Eliminate all occurances of a particular ANSI character.
encodeXMLSpecial( )
Encodes XML special characters. For example, '<' is converted to <
# substr is a string (input)
# Returns a boolean value
endsWith( substr )
Returns true if the string ends with substr (case-sensitive). Otherwise returns false.
# substrObj is a CkString (input)
# Returns a boolean value
endsWithStr( substrObj )
Returns true if the string ends with the specified substring, otherwise returns false. Returns true for success, false for failure.
entityDecode( )
Decodes any HTML entities found within the string, replacing them with the characters represented.
entityEncode( )
HTML encodes any characters that are special to HTML or cannot be represented by 7-bit us-ascii.
# str is a string (input)
# Returns a boolean value
equals( str )
Returns true if the strings are equal, otherwise returns false. (case-sensitive)
# str is a string (input)
# Returns a boolean value
equalsIgnoreCase( str )
Returns true if the strings are equal, otherwise returns false. (case-insensitive)
# strObj is a CkString (input)
# Returns a boolean value
equalsIgnoreCaseStr( strObj )
Returns true if the strings are equal, otherwise returns false (case-insensitive) Returns true for success, false for failure.
# strObj is a CkString (input)
# Returns a boolean value
equalsStr( strObj )
Returns true if the strings are equal, otherwise returns false. (case-sensitive) Returns true for success, false for failure.
# Returns a string
getAnsi( )
Return a pointer to the memory containing the string in the ANSI character encoding. Returns a null on failure
# idx is an integer (input)
# Returns a CkString
getChar( 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
# charsetEncoding is a string (input)
# Returns a string
getEnc( charsetEncoding )
Returns the string converted to any multi-byte character encoding. Examples of character encodings include Shift_JIS, iso-8859-7, windows-1256, etc. Returns a null on failure Supported Character Encodings
# Returns an integer value
getNumChars( )
Returns the number of characters in the string.
# Returns an integer value
getSizeAnsi( )
Returns the size, in bytes, of the ANSI encoding of the string.
# Returns an integer value
getSizeUtf8( )
Returns the size, in bytes, of the utf-8 encoding of the string.
# Returns a string
getString( )
Returns the contents of this instance. Returns a null on failure
# Returns a string
getUtf8( )
Return a pointer to memory containing the string in utf-8. Returns a null on failure
# charsetEncoding is a string (input)
hexDecode( charsetEncoding )
Hex decodes a string and inteprets the bytes according to the character encoding specified. Supported Character Encodings
# charsetEncoding is a string (input)
hexEncode( 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
# substr is a string (input)
# Returns an integer value
indexOf( substr )
Returns the index of the first occurance of a substring. Returns -1 if not found.
# substrObj is a CkString (input)
# Returns an integer value
indexOfStr( substrObj )
Returns the index of the first occurance of a substring. Returns -1 if not found. Returns true for success, false for failure.
# Returns an integer value
intValue( )
Converts the string to an integer and returns the integer value.
# Returns a char
lastChar( )
Returns the last ANSI character in the string. Returns a null on failure
# path is a string (input)
# charsetEncoding is a string (input)
# Returns a boolean value
loadFile( path, 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
# strPattern is a string (input)
# Returns a boolean value
matches( 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.
# strPatternObj is a CkString (input)
# Returns a boolean value
matchesStr( 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. Returns true for success, false for failure.
# str is a string (input)
prepend( str )
Prepends str to this instance.
# charsetEncoding is a string (input)
qpDecode( 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
# charsetEncoding is a string (input)
qpEncode( 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
# substr is a CkString (input)
# Returns an integer value
removeAll( substr )
Removes all occurances of substr. Returns true for success, false for failure.
# ch is a char (input)
removeCharOccurances( ch )
Removes all occurances of a specific ANSI character from the string.
# charStartPos is an integer (input)
# numChars is an integer (input)
removeChunk( charStartPos, numChars )
Removes a chunk of characters specified by starting index and length.
# substr is a CkString (input)
# Returns a boolean value
removeFirst( substr )
Removes the first occurance of a substring. Returns true for success, false for failure.
# findStrObj is a CkString (input)
# replaceStrObj is a CkString (input)
# Returns an integer value
replaceAll( findStrObj, replaceStrObj )
Replaces all occurances of a substring with another. The replacement string is allowed to be empty or different in length. Returns true for success, false for failure.
# findStr is a string (input)
# replaceStr is a string (input)
# Returns an integer value
replaceAllOccurances( findStr, replaceStr )
Replaces all occurances of a substring with another substring. The replacement string is allowed to be empty or different in length.
# findCh is a char (input)
# replaceCh is a char (input)
replaceChar( findCh, replaceCh )
Replaces all occurances of a specified ANSI character with another.
# findStrObj is a CkString (input)
# replaceStrObj is a CkString (input)
# Returns a boolean value
replaceFirst( findStrObj, replaceStrObj )
Replaces the first occurance of a substring with another. The replacement string is allowed to be empty or different in length. Returns true for success, false for failure.
# findStr is a string (input)
# replaceStr is a string (input)
# Returns a boolean value
replaceFirstOccurance( findStr, replaceStr )
Replaces the first occurance of a substring with another. The replacement string is allowed to be empty or different in length.
# path is a string (input)
# charsetEncoding is a string (input)
# Returns a boolean value
saveToFile( path, 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. Returns true for success, false for failure. Supported Character Encodings
# s is a CkString (input)
setStr( s )
Replaces the contents of the string with another. Returns true for success, false for failure.
# str is a string (input)
setString( str )
Clears the contents of this instance and appends str.
# s is a string (input)
setStringAnsi( s )
Set the CkString object from an ANSI string.
# s is a string (input)
setStringUtf8( s )
Set the string object from a utf-8 string.
# n is an integer (input)
shorten( n )
Discards the last N characters.
# delimiterChar is a char (input)
# exceptDoubleQuoted is a boolean (input)
# exceptEscaped is a boolean (input)
# keepEmpty is a boolean (input)
# Returns a CkStringArray
split( delimiterChar, exceptDoubleQuoted, exceptEscaped, 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. Returns a null reference on failure
# delimiterChars is a string (input)
# exceptDoubleQuoted is a boolean (input)
# exceptEscaped is a boolean (input)
# keepEmpty is a boolean (input)
# Returns a CkStringArray
split2( delimiterChars, exceptDoubleQuoted, exceptEscaped, keepEmpty )
Same as "split", except a set of characters can be used for delimiters. Returns a null reference on failure
# Returns a CkStringArray
splitAtWS( )
Equivalent to split2(" \t\r\n",true,true,false) Returns a null reference on failure
# startCharIndex is an integer (input)
# numChars is an integer (input)
# Returns a CkString
substring( startCharIndex, numChars )
Returns a substring specified by starting character position and number of characters. (The 1st char is at index 0.) Returns a null on failure
toCRLF( )
Converts all line endings to CRLF.
toLF( )
Converts all line endings to bare-LF (Unix/Linux style line endings).
toLowerCase( )
Converts the string to lowercase.
toUpperCase( )
Converts the string to uppercase.
# punctuation is a char (input)
# Returns a CkStringArray
tokenize( 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
trim( )
Trim SPACE and Tab characters from both ends of the string.
trim2( )
Trim SPACE, Tab, CR, and LF characters from both ends of the string.
trimInsideSpaces( )
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.
# charsetEncoding is a string (input)
urlDecode( charsetEncoding )
URL decodes the string and interprets the resulting byte data in the specified charset encoding. Supported Character Encodings
# charsetEncoding is a string (input)
urlEncode( 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
|