struct CCL::IString

Overview

Platform-independent Unicode string interface using 16 bit code units in UTF-16 encoding. More…

#include <istring.h>

struct IString: public CCL::IUnknown
{
    // structs

    struct CharData;

    // methods

    virtual tbool CCL_API isEmpty () const = 0;
    virtual int CCL_API getLength () const = 0;
    virtual uchar CCL_API getCharAt (int index) const = 0;
    virtual tresult CCL_API getChars (CharData& data) const = 0;
    virtual tresult CCL_API releaseChars (CharData& data) const = 0;
    virtual tresult CCL_API copyTo (uchar* charBuffer, int bufferSize) const = 0;

    virtual tresult CCL_API toCString (
        TextEncoding encoding,
        char* cString,
        int cStringSize,
        int* bytesWritten = nullptr
    ) const = 0;

    virtual tresult CCL_API toPascalString (
        TextEncoding encoding,
        unsigned char* pString,
        int pStringSize
    ) const = 0;

    virtual int CCL_API compare (const IString* otherString, int flags = 0) const = 0;
    virtual int CCL_API compareChars (const uchar* charBuffer, int count = -1) const = 0;
    virtual tbool CCL_API equals (const IString* otherString) const = 0;
    virtual tbool CCL_API equalsChars (const uchar* charBuffer, int count = -1) const = 0;
    virtual int CCL_API findSubString (const IString* otherString, int flags = 0) const = 0;
    virtual IString*CCL_API createSubString (int index, int count = -1) const = 0;

    virtual IStringTokenizer*CCL_API tokenize (
        const IString* delimiters,
        int flags = 0
    ) const = 0;

    virtual IString*CCL_API cloneString () const = 0;
    virtual void*CCL_API createNativeString () const = 0;
    virtual void CCL_API releaseNativeString (void* nativeString) const = 0;
    virtual IStringPrivateData CCL_API getPrivateData () const = 0;
    virtual unsigned int CCL_API getHashCode () const = 0;
    virtual tbool CCL_API isNormalized (NormalizationForm form) const = 0;
    virtual tresult CCL_API assignChars (const uchar* charBuffer, int count = -1) = 0;

    virtual tresult CCL_API appendCString (
        TextEncoding encoding,
        const char* cString,
        int count = -1
    ) = 0;

    virtual tresult CCL_API appendPascalString (
        TextEncoding encoding,
        const unsigned char* pString
    ) = 0;

    virtual tresult CCL_API appendChars (const uchar* charBuffer, int count = -1) = 0;
    virtual tresult CCL_API appendString (const IString* otherString) = 0;
    virtual tresult CCL_API appendRepeated (const IString* otherString, int count) = 0;
    virtual tresult CCL_API appendNativeString (const void* nativeString) = 0;
    virtual tresult CCL_API insert (int index, const IString* otherString) = 0;
    virtual tresult CCL_API remove (int index, int count = -1) = 0;
    virtual tresult CCL_API truncate (int index) = 0;
    virtual void CCL_API trimWhitespace () = 0;
    virtual void CCL_API toUppercase () = 0;
    virtual void CCL_API toLowercase () = 0;
    virtual void CCL_API capitalize () = 0;

    virtual int CCL_API replace (
        const IString* searchString,
        const IString* replacementString,
        int flags = 0
    ) = 0;

    virtual void CCL_API substitute (int flags = 0) = 0;
    virtual tresult CCL_API normalize (NormalizationForm form) = 0;
};

Inherited Members

public:
    // methods

    virtual tresult CCL_API queryInterface (UIDRef iid, void** ptr) = 0;
    virtual unsigned int CCL_API retain () = 0;
    virtual unsigned int CCL_API release () = 0;

Detailed Documentation

Platform-independent Unicode string interface using 16 bit code units in UTF-16 encoding.

Methods

virtual tbool CCL_API isEmpty () const = 0

Returns true if string is empty.

virtual int CCL_API getLength () const = 0

Returns string length in code units.

virtual uchar CCL_API getCharAt (int index) const = 0

Returns code unit at specified position or null if out of range.

virtual tresult CCL_API getChars (CharData& data) const = 0

Direct access to character data, might cause a temporary copy to be created.

virtual tresult CCL_API releaseChars (CharData& data) const = 0

Release character data, always call in pair after getChars().

virtual tresult CCL_API copyTo (uchar* charBuffer, int bufferSize) const = 0

Copy string to external character buffer, size is in characters (uchar, not bytes).

virtual tresult CCL_API toCString (
    TextEncoding encoding,
    char* cString,
    int cStringSize,
    int* bytesWritten = nullptr
) const = 0

Convert to C-String in specified encoding, size includes 0 termination byte.

virtual tresult CCL_API toPascalString (
    TextEncoding encoding,
    unsigned char* pString,
    int pStringSize
) const = 0

Convert to Pascal string (with length byte) in specified encoding, size includes length byte.

virtual int CCL_API compare (const IString* otherString, int flags = 0) const = 0

Compare this with other string, returns CompareResult.

virtual int CCL_API compareChars (const uchar* charBuffer, int count = -1) const = 0

Compare this with given Unicode text, returns CompareResult.

virtual tbool CCL_API equals (const IString* otherString) const = 0

Compare for equality with other string (usually faster than full comparison).

virtual tbool CCL_API equalsChars (const uchar* charBuffer, int count = -1) const = 0

Compare for equality with given Unicode text (usually faster than full comparison).

virtual int CCL_API findSubString (const IString* otherString, int flags = 0) const = 0

Returns code unit index of substring occurance in this string, or -1 if not found.

virtual IString*CCL_API createSubString (int index, int count = -1) const = 0

Creates a copy of this string, starting at the specified index with count characters.

virtual IStringTokenizer*CCL_API tokenize (
    const IString* delimiters,
    int flags = 0
) const = 0

Break string into tokens at given delimiters.

virtual IString*CCL_API cloneString () const = 0

Creates a copy of this string.

virtual void*CCL_API createNativeString () const = 0

Create an OS-specific representation of this string Windows: BSTR macOS/iOS: CFStringRef Android: jstring Linux : 8 bit characters in system encoding.

virtual void CCL_API releaseNativeString (void* nativeString) const = 0

Release OS-specific string representation created via createNativeString().

virtual IStringPrivateData CCL_API getPrivateData () const = 0

Returns private data for debugging purpose.

virtual unsigned int CCL_API getHashCode () const = 0

Hash string to integer value.

virtual tbool CCL_API isNormalized (NormalizationForm form) const = 0

Check if string is normalized according to given form.

virtual tresult CCL_API assignChars (const uchar* charBuffer, int count = -1) = 0

Assign a piece of Unicode text.

virtual tresult CCL_API appendCString (
    TextEncoding encoding,
    const char* cString,
    int count = -1
) = 0

Append C-String in specified encoding.

virtual tresult CCL_API appendPascalString (
    TextEncoding encoding,
    const unsigned char* pString
) = 0

Append Pascal string (with length byte) in specified encoding.

virtual tresult CCL_API appendChars (const uchar* charBuffer, int count = -1) = 0

Append a piece of Unicode text.

virtual tresult CCL_API appendString (const IString* otherString) = 0

Append another string’s text.

virtual tresult CCL_API appendRepeated (const IString* otherString, int count) = 0

Appends count repetitions of a string.

virtual tresult CCL_API appendNativeString (const void* nativeString) = 0

Append text from native string, see createNativeString() for OS-specific types.

virtual tresult CCL_API insert (int index, const IString* otherString) = 0

Insert string at specified position.

virtual tresult CCL_API remove (int index, int count = -1) = 0

Remove a range of characters, -1 truncates the string at specified position.

virtual tresult CCL_API truncate (int index) = 0

Truncate string at specified position.

virtual void CCL_API trimWhitespace () = 0

Remove leading and trailing whitespaces.

virtual void CCL_API toUppercase () = 0

Change all alphabetical characters to uppercase.

virtual void CCL_API toLowercase () = 0

Change all alphabetical characters to lowercase.

virtual void CCL_API capitalize () = 0

Changes the first character in each word to uppercase.

virtual int CCL_API replace (
    const IString* searchString,
    const IString* replacementString,
    int flags = 0
) = 0

Replace all occurances of a substring, returns number of instances replaced.

virtual void CCL_API substitute (int flags = 0) = 0

Changes characters to similar ones within the ASCII set, can change length.

virtual tresult CCL_API normalize (NormalizationForm form) = 0

Normalize characters according to to given form.