CkoString Objective-C Reference Documentation

CkoString

The Chilkat string class.

Properties

Methods

- (void)append:(NSString *)str

The str is appended to end of this instance.

- (void)appendAnsi:(NSString *)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)appendChar:(UNKNOWN_ARG_TYPE1)[char]

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

- (void)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"

- (void)appendDateRfc822:(NSDate *)dateTime

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

- (void)appendDateRfc822Gmt:(NSDate *)dateTime

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

- (void)appendEnc:(NSString *)str
    charsetEncoding:(NSString *)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)appendHexData:(NSData *)byteData
    numBytes:(NSNumber *)numBytes

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

- (void)appendInt:(NSNumber *)n

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

- (void)appendN:(NSString *)str
    numBytes:(NSNumber *)numBytes

Appends N bytes of character data to the end of this instance. If the Utf8 property is set to YES, 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)appendNU:(UNKNOWN_ARG_TYPE1)[const wchar_t *]

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)appendRandom:(NSNumber *)numBytes
    encoding:(NSString *)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)appendStr:(NSString *)strObj

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

- (void)appendU:(UNKNOWN_ARG_TYPE1)[const wchar_t *]

Append a Unicode string to the CkString object.

- (void)appendUtf8:(NSString *)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)base64Decode:(NSString *)charsetEncoding

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

Supported Character Encodings

- (void)base64DecodeW:(UNKNOWN_ARG_TYPE1)[const wchar_t *]

The wchar_t version of base64Decode.

- (void)base64Encode:(NSString *)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)base64EncodeW:(UNKNOWN_ARG_TYPE1)[const wchar_t *]

The wchar_t version of base64Encode.

- (BOOL)beginsWith:(NSString *)substr

Return YES if this string begins with substr (case sensitive), otherwise returns NO.

- (BOOL)beginsWithStr:(NSString *)strObj

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

- (BOOL)beginsWithW:(UNKNOWN_ARG_TYPE1)[const wchar_t *]

The wchar_t version of beginsWith.

- UNKNOWN_RETURN_TYPE - (char)

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

- UNKNOWN_RETURN_TYPE - (wchar_t)

Return the Nth character as a Unicode character.

- (void)chopAtFirstChar:(UNKNOWN_ARG_TYPE1)[char]

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

- (void)chopAtStr:(NSString *)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)clear

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

- (CkoString *)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.

- (NSNumber *)compareStr:(NSString *)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)containsSubstring:(NSString *)substr

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

- (BOOL)containsSubstringNoCase:(NSString *)substr

Same as containsSubstring except the matching is case insensitive.

- (BOOL)containsSubstringNoCaseW:(UNKNOWN_ARG_TYPE1)[const wchar_t *]

The wchar_t version of containsSubstringNoCase.

- (BOOL)containsSubstringW:(UNKNOWN_ARG_TYPE1)[const wchar_t *]

The wchar_t version of containsSubstring.

- (NSNumber *)countCharOccurances:(UNKNOWN_ARG_TYPE1)[char]

Returns the number of occurances of the specified ANSI char.

- (void)decodeXMLSpecial

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

- (NSNumber *)doubleValue

Converts the string to a double and returns the value.

- (void)eliminateChar:(UNKNOWN_ARG_TYPE1)[char]

Eliminate all occurances of a particular ANSI character.

- (void)encodeXMLSpecial

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

- (BOOL)endsWith:(NSString *)substr

Returns YES if the string ends with substr (case-sensitive). Otherwise returns NO.

- (BOOL)endsWithStr:(NSString *)substrObj

Returns YES if the string ends with the specified substring, otherwise returns NO.

- (BOOL)endsWithW:(UNKNOWN_ARG_TYPE1)[const wchar_t *]

The wchar_t version of endsWith.

- (void)entityDecode

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

- (void)entityEncode

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

- (BOOL)equals:(NSString *)str

Returns YES if the strings are equal, otherwise returns NO. (case-sensitive)

- (BOOL)equalsIgnoreCase:(NSString *)str

Returns YES if the strings are equal, otherwise returns NO. (case-insensitive)

- (BOOL)equalsIgnoreCaseStr:(NSString *)strObj

Returns YES if the strings are equal, otherwise returns NO (case-insensitive)

- (BOOL)equalsIgnoreCaseW:(UNKNOWN_ARG_TYPE1)[const wchar_t *]

The wchar_t version of equalsIgnoreCase.

- (BOOL)equalsStr:(NSString *)strObj

Returns YES if the strings are equal, otherwise returns NO. (case-sensitive)

- (BOOL)equalsW:(UNKNOWN_ARG_TYPE1)[const wchar_t *]

The wchar_t version of the "equals" method.

- (CkoString *)getChar:(NSNumber *)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.

- (NSNumber *)getNumChars

Returns the number of characters in the string.

- (NSNumber *)getSizeAnsi

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

- (NSNumber *)getSizeUnicode

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

- (NSNumber *)getSizeUtf8

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

- UNKNOWN_RETURN_TYPE - (const wchar_t *)

Return a pointer to memory containing the string in Unicode.

- (void)hexDecode:(NSString *)charsetEncoding

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

Supported Character Encodings

- (void)hexDecodeW:(UNKNOWN_ARG_TYPE1)[const wchar_t *]

The wchar_t version of hexDecode.

- (void)hexEncode:(NSString *)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)hexEncodeW:(UNKNOWN_ARG_TYPE1)[const wchar_t *]

The wchar_t version of hexEncode.

- (NSNumber *)indexOf:(NSString *)substr

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

- (NSNumber *)indexOfStr:(NSString *)substrObj

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

- (NSNumber *)indexOfW:(UNKNOWN_ARG_TYPE1)[const wchar_t *]

The wchar_t version of "indexOf".

- (NSNumber *)intValue

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

- (BOOL)isEmpty

Returns YES if the string object is empty, otherwise returns NO.

- UNKNOWN_RETURN_TYPE - (char)

Returns the last ANSI character in the string.

- (BOOL)loadFile:(NSString *)path
    charsetEncoding:(NSString *)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)loadFileW:(UNKNOWN_ARG_TYPE1)[const wchar_t *]

The wchar_t version of loadFile.

Returns true for success, false for failure.

- (BOOL)matches:(NSString *)strPattern

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

- (BOOL)matchesNoCase:(NSString *)strPattern

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

- (BOOL)matchesNoCaseW:(UNKNOWN_ARG_TYPE1)[const wchar_t *]

The wchar_t version of matchesNoCase.

- (BOOL)matchesStr:(NSString *)strPatternObj

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

- (BOOL)matchesW:(UNKNOWN_ARG_TYPE1)[const wchar_t *]

The wchar_t version of the "matches" method.

- (void)minimizeMemory

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)obfuscate

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)prepend:(NSString *)str

Prepends str to this instance.

- (void)prependW:(UNKNOWN_ARG_TYPE1)[const wchar_t *]

The wchar_t version of the "prepend" method.

- (void)qpDecode:(NSString *)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)qpDecodeW:(UNKNOWN_ARG_TYPE1)[const wchar_t *]

The wchar_t version of the qpDecode method.

- (void)qpEncode:(NSString *)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)qpEncodeW:(UNKNOWN_ARG_TYPE1)[const wchar_t *]

The wchar_t version of the qpEncode method.

- (NSNumber *)removeAll:(NSString *)substr

Removes all occurances of substr.

- (void)removeCharOccurances:(UNKNOWN_ARG_TYPE1)[char]

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

- (void)removeChunk:(NSNumber *)charStartPos
    numChars:(NSNumber *)numChars

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

- (BOOL)removeFirst:(NSString *)substr

Removes the first occurance of a substring.

- (NSNumber *)replaceAll:(NSString *)findStrObj
    replaceStrObj:(NSString *)replaceStrObj

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

- (NSNumber *)replaceAllOccurances:(NSString *)findStr
    replaceStr:(NSString *)replaceStr

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

- (NSNumber *)replaceAllOccurancesW:(UNKNOWN_ARG_TYPE1)[const wchar_t *]

The wchar_t version of the replaceAllOccurances method.

- (void)replaceChar:(UNKNOWN_ARG_TYPE1)[char]

Replaces all occurances of a specified ANSI character with another.

- (BOOL)replaceFirst:(NSString *)findStrObj
    replaceStrObj:(NSString *)replaceStrObj

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

- (BOOL)replaceFirstOccurance:(NSString *)findStr
    replaceStr:(NSString *)replaceStr

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

- (BOOL)replaceFirstOccuranceW:(UNKNOWN_ARG_TYPE1)[const wchar_t *]

To be documented soon...

- (BOOL)saveToFile:(NSString *)path
    charsetEncoding:(NSString *)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

- (BOOL)saveToFileW:(UNKNOWN_ARG_TYPE1)[const wchar_t *]

The wchar_t version of the saveToFile method.

Returns true for success, false for failure.

- (void)setStr:(NSString *)s

Replaces the contents of the string with another.

- (void)setString:(NSString *)str

Clears the contents of this instance and appends str.

- (void)setStringAnsi:(NSString *)s

Set the CkString object from an ANSI string.

- (void)setStringU:(UNKNOWN_ARG_TYPE1)[const wchar_t *]

Set the CkString object from a Unicode string.

- (void)setStringUtf8:(NSString *)s

Set the string object from a utf-8 string.

- (void)shorten:(NSNumber *)n

Discards the last N characters.

- (CkoStringArray *)split:(UNKNOWN_ARG_TYPE1)[char]

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

- (CkoStringArray *)split2:(NSString *)delimiterChars
    exceptDoubleQuoted:(BOOL)exceptDoubleQuoted
    exceptEscaped:(BOOL)exceptEscaped
    keepEmpty:(BOOL)keepEmpty

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

- (CkoStringArray *)split2W:(UNKNOWN_ARG_TYPE1)[const wchar_t *]

The wchar_t version of the split2 method.

- (CkoStringArray *)splitAtWS

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

- (CkoString *)substring:(NSNumber *)startCharIndex
    numChars:(NSNumber *)numChars

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

- (void)toCRLF

Converts all line endings to CRLF.

- (void)toLF

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

- (void)toLowerCase

Converts the string to lowercase.

- (void)toUpperCase

Converts the string to uppercase.

- (CkoStringArray *)tokenize:(NSString *)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

- (CkoStringArray *)tokenizeW:(UNKNOWN_ARG_TYPE1)[const wchar_t *]

The wchar_t version of the "tokenize" method.

- (void)trim

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

- (void)trim2

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

- (void)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.

- (void)unobfuscate

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)urlDecode:(NSString *)charsetEncoding

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

Supported Character Encodings

- (void)urlDecodeW:(UNKNOWN_ARG_TYPE1)[const wchar_t *]

The wchar_t version of the urlDecode method.

- (void)urlEncode:(NSString *)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)urlEncodeW:(UNKNOWN_ARG_TYPE1)[const wchar_t *]

The wchar_t version of the urlEncode method.