| /* |
| * Project: VizKit |
| * Version: 2.3 |
| |
| * Date: 20090823 |
| * File: VisualString.h |
| * |
| */ |
| |
| /*************************************************************************** |
| |
| Copyright (c) 2004-2009 Heiko Wichmann (http://www.imagomat.de/vizkit) |
| |
| |
| This software is provided 'as-is', without any expressed or implied warranty. |
| In no event will the authors be held liable for any damages |
| arising from the use of this software. |
| |
| Permission is granted to anyone to use this software for any purpose, |
| including commercial applications, and to alter it and redistribute it |
| freely, subject to the following restrictions: |
| |
| 1. The origin of this software must not be misrepresented; |
| you must not claim that you wrote the original software. |
| If you use this software in a product, an acknowledgment |
| in the product documentation would be appreciated |
| but is not required. |
| |
| 2. Altered source versions must be plainly marked as such, |
| and must not be misrepresented as being the original software. |
| |
| 3. This notice may not be removed or altered from any source distribution. |
| |
| ***************************************************************************/ |
| |
| #ifndef VisualString_h |
| #define VisualString_h |
| |
| |
| #include "VisualTypes.h" |
| #include "VisualObject.h" |
| #include <vector> |
| |
| #if TARGET_OS_MAC |
| #include <CoreFoundation/CFString.h> // CFStringRef |
| #endif |
| |
| |
| namespace VizKit { |
| |
| #if TARGET_OS_MAC |
| typedef CFMutableStringRef StringDataRef; |
| typedef CFStringRef ConstStringDataRef; |
| #endif |
| #if TARGET_OS_WIN |
| typedef wchar_t* StringDataRef; |
| typedef const wchar_t* const ConstStringDataRef; |
| #endif |
| |
| class VisualFile; // Forward declaration (to avoid include of header file). |
| |
| /** |
| * Unicode string without styling or formatting information. |
| */ |
| class VisualString : public VisualObject { |
| |
| public: |
| |
| /** |
| * The constructor. |
| */ |
| VisualString(); |
| |
| /** |
| * A constructor that constructs a VisualString with a pointer to an UTF-8 string and the number of bytes of the string. |
| * @param aStringVal A pointer to the UTF-8 encoded char string value. |
| * @param numberOfBytes Optional indication of number of bytes of the char string. |
| * @remarks If the number of bytes is not specified, the string must be terminated with a NULL byte. The number of bytes is evaluated by calling strlen() then. |
| */ |
| VisualString(const char* const aStringVal, sint32 numberOfBytes = -1); |
| |
| /** |
| * A constructor that constructs a VisualString with a pointer to a wchar_t string and the number of characters of the string. |
| * @param aStringVal A pointer to the wchar_t string value. |
| * @param aNumberOfCharacters The number of characters of the char string. |
| * @remarks If the number of characters is not specified, the string must be terminated with a NULL byte. The number of characters is evaluated by calling sizeof() then. |
| */ |
| VisualString(const uint16* const aStringVal, sint32 aNumberOfCharacters = -1); |
| |
| /** |
| * A constructor that constructs a VisualString from a ConstStringDataRef. |
| * @param aStringVal A string value in ConstStringDataRef data format. |
| * @remarks ConstStringDataRef is the cross-platform data format of VisualString's internal string buffer. |
| */ |
| VisualString(ConstStringDataRef aStringVal); |
| |
| /** |
| * Initializes a VisualString with a pointer to an UTF-8 string. |
| * @param aStringVal A pointer to the UTF-8 encoded char string value. |
| * @remarks The string must be terminated with a NULL byte. |
| */ |
| void initWithUTF8String(const char* const aStringVal); |
| |
| /** |
| * Initializes a VisualString with a pointer to an UTF-8 string buffer. |
| * @param aStringVal A pointer to the UTF-8 encoded char string buffer. |
| * @param numberOfBytes The number of bytes of the UTF-8 encoded char string buffer. |
| */ |
| void initWithUTF8Buffer(const char* const aStringVal, uint32 numberOfBytes); |
| |
| /** |
| * Initializes a VisualString with a pointer to an UTF-16 string. |
| * @param aStringVal A pointer to the UTF-16 encoded char string value. |
| * @remarks The string must be terminated with a NULL byte. |
| */ |
| void initWithUTF16String(const uint16* const aStringVal); |
| |
| /** |
| * Initializes a VisualString with a pointer to an UTF-16 string buffer. |
| * @param aStringVal A pointer to the UTF-16 encoded char string buffer. |
| * @param aNumberOfCharacters The number of characters of the UTF-16 encoded char string buffer. |
| */ |
| void initWithUTF16Buffer(const uint16* const aStringVal, uint32 aNumberOfCharacters); |
| |
| /** |
| * Initializes a VisualString from the contents of a file. |
| * @param aFile Reference to a file. |
| * @return True on success, false on failure. |
| * @remarks The file is opened, the content is read as an UTF-8 encoded string, then the file is closed again. |
| */ |
| bool initWithContentsOfFile(VisualFile& aFile); |
| |
| /** |
| * Initializes a VisualString with the contents of a URL. |
| * @param anId An identifier. |
| * @param aURL A URL (aka URI). |
| */ |
| bool initWithContentsOfURL(const char* const aURL, const VisualItemIdentifier& anId); |
| |
| /** |
| * Initializes a VisualString with a platform native string data type (CFStringRef on Mac, wchar_t pointer on Windows). |
| * @param constStringDataRef On Mac a CFStringRef, on Windows a wchar_t pointer. |
| */ |
| bool initWithConstStringDataRef(ConstStringDataRef constStringDataRef); |
| |
| /** |
| * The destructor. |
| */ |
| ~VisualString(); |
| |
| /** |
| * Copy constructor. |
| * @param other Another VisualString. |
| */ |
| VisualString(const VisualString& other); |
| |
| /** |
| * Assignment operator. |
| */ |
| VisualString& operator=(const VisualString& other); |
| |
| /** |
| * Less than operator. |
| * @param other Another VisualString. |
| * @remarks The less than operator is used by std::map for find() and sorting (if VisualString is used as key_type). |
| */ |
| bool operator<(const VisualString& other) const; |
| |
| /** |
| * Equality operator. |
| * @param other Another VisualString. |
| */ |
| bool operator==(const VisualString& other) const; |
| |
| /** |
| * Inequality operator. |
| * @param other Another VisualString. |
| */ |
| bool operator!=(const VisualString& other) const; |
| |
| /** |
| * Plus operator appends another string. |
| * @param other Another VisualString. |
| */ |
| const VisualString& operator+(const VisualString& other); |
| |
| /** |
| * Plus operator appends an 8-bit char string. |
| * @param charString Pointer to 8-bit character string. |
| * @remarks The charString must be NULL-terminated so that strlen can determine the correct length of the string. |
| */ |
| const VisualString& operator+(const char* charString); |
| |
| /** |
| * Copies the current VisualString and returns a pointer to a new VisualString. |
| */ |
| virtual VisualString* clone(void) const; |
| |
| /** Resets internally used variables and releases allocated memory. */ |
| void clear(void); |
| |
| /** |
| * Returns the number of characters of the string. |
| * @return The number of characters of the string. |
| * @remarks The number of characters are not the number of bytes in memory but the number of glyphs or code points. |
| */ |
| uint32 getNumberOfCharacters(void) const; |
| |
| /** |
| * Returns the number of non-whitespace characters of the string. |
| * @return The number of non-whitespace characters of the string. |
| */ |
| uint32 getNumberOfNonWhitespaceCharacters(void) const; |
| |
| /** |
| * Returns true if the number of non-whitespace characters of the string is 0. |
| * @return True if the number of non-whitespace characters of the string is 0. |
| */ |
| bool isEmpty(void) const; |
| |
| /** |
| * Returns the number of words of the string. |
| * @return The number of words of the string. |
| */ |
| uint32 getNumberOfWords(void) const; |
| |
| /** |
| * Returns the number of lines of the string. |
| * @return The number of lines of the string. |
| * @remarks The number of lines is evaluated by counting the number of lines that contain at least one non-whitespace character. |
| */ |
| uint32 getNumberOfLines(void) const; |
| |
| /** |
| * Returns one line of the string. |
| * @param index The requested line number. The first line has an index of 0. |
| * @return One line of the string. |
| * @remarks The caller has to delete the VisualString. |
| */ |
| VisualString* createStringWithLine(uint32 index) const; |
| |
| /** |
| * Returns one word of the string. |
| * @param index The requested index number. The first word has an index of 0. |
| * @return One word of the string. |
| * @remarks The caller has to delete the VisualString. |
| */ |
| VisualString* createStringWithWord(uint32 index) const; |
| |
| /** |
| * Returns a pointer to the internal string data. |
| * @return A pointer to the internal string data. |
| * @remarks On Mac the string data is stored as a CFString. On Windows the string data is stored as a wchar_t type. |
| */ |
| ConstStringDataRef getCharactersPointer(void) const; |
| |
| /** |
| * Returns a pointer to a char buffer with utf-8 encoded string data. |
| * @return A pointer to a char buffer with utf-8 encoded string data. |
| * @remarks The memory is owned by VisualString and deallocated on destruct of VisualString instance. |
| */ |
| const char* const getUtf8Representation(void); |
| |
| /** |
| * Returns a pointer to a 16-bit buffer with utf-16 encoded string data. |
| * @return A pointer to a 16-bit buffer with utf-16 encoded string data. |
| * @remarks The memory is owned by VisualString and deallocated on destruct of VisualString instance. |
| */ |
| const uint16* const getUtf16Representation(void); |
| |
| /** |
| * Returns a substring of the VisualString. |
| * @param startIdx The 0-based start index of the requested substring. |
| * @param numberOfSubstringCharacters The number of characters to include in the substring. |
| */ |
| VisualString getSubstring(uint32 startIdx, uint32 numberOfSubstringCharacters) const; |
| |
| /** |
| * Normalizes the line endings of the string. |
| * @remarks Line endings can be incorrect when transfering audio files from MacOS to Windows (Windows expects line ending to consist of CR+LF). |
| */ |
| void normalizeLineEndings(); |
| |
| /** |
| * Writes information about the VisualString to the log file. |
| * @remarks Useful for debuggin and tracing purposes. |
| */ |
| void writeDebugLog(void) const; |
| |
| /** |
| * Returns an array of strings by splitting the string with a separator string (delimiter). |
| * @param delimiter The string to use as separator. |
| * @return An array with VisualStrings. |
| */ |
| std::vector<VisualString> splitWithDelimiter(const VisualString& delimiter); |
| |
| /** |
| * Remove whitespace characters from the start and end of the string. |
| */ |
| void trim(void); |
| |
| /** |
| * Joins the strings of the vector to create a joined string. The items of the vector are separated by newline. |
| * @param stringVector The vector of strings. |
| * @return A VisualString. |
| */ |
| static VisualString* createJoinedString(std::vector<VisualString> stringVector); |
| |
| /** |
| * Creates a VisualString from a pointer to an UTF-8 string. |
| * @param aStringVal A pointer to the UTF-8 encoded char string value. |
| * @remarks The string must be terminated with a NULL byte. The caller has to delete the VisualString. |
| */ |
| static VisualString* createWithUTF8String(const char* const aStringVal); |
| |
| /** |
| * Creates a VisualString from a pointer to an UTF-8 string buffer. |
| * @param aStringVal A pointer to the UTF-8 encoded char string buffer. |
| * @param numberOfBytes The number of bytes of the UTF-8 encoded char string buffer. |
| * @remarks The caller has to delete the VisualString. |
| */ |
| static VisualString* createWithUTF8Buffer(const char* const aStringVal, uint32 numberOfBytes); |
| |
| /** |
| * Creates a VisualString from a pointer to an UTF-16 string. |
| * @param aStringVal A pointer to the UTF-16 encoded char string value. |
| * @remarks The string must be terminated with a NULL byte. The caller has to delete the VisualString. |
| */ |
| static VisualString* createWithUTF16String(const uint16* const aStringVal); |
| |
| /** |
| * Creates a VisualString from a pointer to an UTF-16 string buffer. |
| * @param aStringVal A pointer to the UTF-16 encoded char string buffer. |
| * @param aNumberOfCharacters The number of characters of the UTF-16 encoded char string buffer. |
| * @remarks The caller has to delete the VisualString. |
| */ |
| static VisualString* createWithUTF16Buffer(const uint16* const aStringVal, uint32 aNumberOfCharacters); |
| |
| /** |
| * Creates a VisualString from the contents of a file. |
| * @param aFile Reference to a file. |
| * @remarks The file is opened, the content is read as a string, then the file is closed again. |
| */ |
| static VisualString* createWithContentsOfFile(VisualFile& aFile); |
| |
| /** |
| * Creates a VisualString with the contents of a URL. |
| * @param aURL A URL (aka URI). |
| * @param anId An identifier. |
| */ |
| static VisualString* createWithContentsOfURL(const char* const aURL, const VisualItemIdentifier& anId); |
| |
| /** |
| * Creates a VisualString with a platform native string data type (CFStringRef on Mac, wchar_t pointer on Windows). |
| * @param constStringDataRef On Mac a CFStringRef, on Windows a wchar_t pointer. |
| */ |
| static VisualString* createWithConstStringDataRef(ConstStringDataRef constStringDataRef); |
| |
| /** |
| * Notification that the loading of data ended. |
| * @param identifier The identifier of the data load request. |
| */ |
| virtual void dataLoadDidEnd(const VisualItemIdentifier& identifier); |
| |
| protected: |
| |
| /** |
| * Copy method for assignment operator and copy constructor. |
| * @param other Another VisualString. |
| */ |
| void copy(const VisualString& other); |
| |
| private: |
| |
| /** A pointer to the internally stored string data. */ |
| StringDataRef theString; |
| |
| /** Optionally available utf-8 representation of string data. */ |
| char* utf8representation; |
| |
| /** Optionally available utf-16 representation of string data. */ |
| uint16* utf16representation; |
| |
| /** The number of characters of the string. */ |
| uint32 numberOfCharacters; |
| |
| /** The number of characters of the string. */ |
| uint32 numberOfNonWhitespaceCharacters; |
| |
| /** The number of words of the string. */ |
| uint32 numberOfWords; |
| |
| /** The number of lines of the string. */ |
| uint32 numberOfLines; |
| |
| /** Substring of the VisualString with start position and length. */ |
| typedef struct { |
| sint32 startIndex; /**< The start position of the substring. */ |
| uint32 numberOfCharacters; /**< The length in number of characters. */ |
| } VisualStringSubstringPointer; |
| |
| /** VisualStringSubstringPointers can be collected in a vector of structs. */ |
| typedef std::vector<VisualStringSubstringPointer> ArrayOfSubstringPointers; |
| |
| /** The lines (rows) of the VisualString collected as substrings. */ |
| ArrayOfSubstringPointers arrayOfLines; |
| |
| /** The words of the VisualString collected as substrings. */ |
| ArrayOfSubstringPointers arrayOfWords; |
| |
| /** The number of lines and words are calculated and stored internally. */ |
| void calcStatistics(void); |
| |
| /** |
| * Returns a single character of the string data. |
| * @param index The position of the character in the string. First position starts with 0. |
| * @return A single character of the string data. |
| */ |
| uint16 getCharacterAtIndex(uint32 index) const; |
| |
| /** |
| * Returns true if character is new line character. |
| * @param character The character to inspect. |
| * @return True if character is new line character, false if not. |
| */ |
| bool characterIsNewlineCharacter(uint16 character); |
| |
| /** |
| * Returns true if character is whitespace character. |
| * @param character The character to inspect. |
| * @return True if character is whitespace character, false if not. |
| */ |
| bool characterIsWhitespaceCharacter(uint16 character); |
| |
| }; |
| |
| /** Constant VisualString. */ |
| typedef const VisualString ConstVisualString; |
| |
| } |
| |
| #endif /* VisualString_h */ |