VizKit::VisualString Class Reference

#include <VisualString.h>

Inherits VizKit::VisualObject.

Inherited by VizKit::VisualStyledString.

Collaboration diagram for VizKit::VisualString:

List of all members.

Classes
struct	VisualStringSubstringPointer
Public Member Functions
	VisualString ()
	VisualString (const char *const aStringVal, sint32 numberOfBytes=-1)
	VisualString (const uint16 *const aStringVal, sint32 aNumberOfCharacters=-1)
	VisualString (ConstStringDataRef aStringVal)
void	initWithUTF8String (const char *const aStringVal)
void	initWithUTF8Buffer (const char *const aStringVal, uint32 numberOfBytes)
void	initWithUTF16String (const uint16 *const aStringVal)
void	initWithUTF16Buffer (const uint16 *const aStringVal, uint32 aNumberOfCharacters)
bool	initWithContentsOfFile (VisualFile &aFile)
bool	initWithContentsOfURL (const char *const aURL, const VisualItemIdentifier &anId)
bool	initWithConstStringDataRef (ConstStringDataRef constStringDataRef)
	~VisualString ()
	VisualString (const VisualString &other)
VisualString &	operator= (const VisualString &other)
bool	operator< (const VisualString &other) const
bool	operator== (const VisualString &other) const
bool	operator!= (const VisualString &other) const
const VisualString &	operator+ (const VisualString &other)
const VisualString &	operator+ (const char *charString)
virtual VisualString *	clone (void) const
void	clear (void)
uint32	getNumberOfCharacters (void) const
uint32	getNumberOfNonWhitespaceCharacters (void) const
bool	isEmpty (void) const
uint32	getNumberOfWords (void) const
uint32	getNumberOfLines (void) const
VisualString *	createStringWithLine (uint32 index) const
VisualString *	createStringWithWord (uint32 index) const
ConstStringDataRef	getCharactersPointer (void) const
const char *const	getUtf8Representation (void)
const uint16 *const	getUtf16Representation (void)
VisualString	getSubstring (uint32 startIdx, uint32 numberOfSubstringCharacters) const
void	normalizeLineEndings ()
void	writeDebugLog (void) const
std::vector< VisualString >	splitWithDelimiter (const VisualString &delimiter)
void	trim (void)
virtual void	dataLoadDidEnd (const VisualItemIdentifier &identifier)
Static Public Member Functions
static VisualString *	createJoinedString (std::vector< VisualString > stringVector)
static VisualString *	createWithUTF8String (const char *const aStringVal)
static VisualString *	createWithUTF8Buffer (const char *const aStringVal, uint32 numberOfBytes)
static VisualString *	createWithUTF16String (const uint16 *const aStringVal)
static VisualString *	createWithUTF16Buffer (const uint16 *const aStringVal, uint32 aNumberOfCharacters)
static VisualString *	createWithContentsOfFile (VisualFile &aFile)
static VisualString *	createWithContentsOfURL (const char *const aURL, const VisualItemIdentifier &anId)
static VisualString *	createWithConstStringDataRef (ConstStringDataRef constStringDataRef)
Protected Member Functions
void	copy (const VisualString &other)
Private Types
typedef std::vector < VisualStringSubstringPointer >	ArrayOfSubstringPointers
Private Member Functions
void	calcStatistics (void)
uint16	getCharacterAtIndex (uint32 index) const
bool	characterIsNewlineCharacter (uint16 character)
bool	characterIsWhitespaceCharacter (uint16 character)
Private Attributes
StringDataRef	theString
char *	utf8representation
uint16 *	utf16representation
uint32	numberOfCharacters
uint32	numberOfNonWhitespaceCharacters
uint32	numberOfWords
uint32	numberOfLines
ArrayOfSubstringPointers	arrayOfLines
ArrayOfSubstringPointers	arrayOfWords

---

Detailed Description

Unicode string without styling or formatting information.

---

Member Typedef Documentation

typedef std::vector<VisualStringSubstringPointer> VizKit::VisualString::ArrayOfSubstringPointers [private]

VisualStringSubstringPointers can be collected in a vector of structs.

---

Constructor & Destructor Documentation

VisualString::VisualString

(

)

The constructor.

VisualString::VisualString	(	const char *const	aStringVal,
		sint32	numberOfBytes = -1
	)

A constructor that constructs a VisualString with a pointer to an UTF-8 string and the number of bytes of the string.

Parameters:

	aStringVal	A pointer to the UTF-8 encoded char string value.
	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::VisualString	(	const uint16 *const	aStringVal,
		sint32	aNumberOfCharacters = -1
	)

A constructor that constructs a VisualString with a pointer to a wchar_t string and the number of characters of the string.

Parameters:

	aStringVal	A pointer to the wchar_t string value.
	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::VisualString

(

ConstStringDataRef

aStringVal

)

A constructor that constructs a VisualString from a ConstStringDataRef.

Parameters:

aStringVal

A string value in ConstStringDataRef data format.

Remarks:

ConstStringDataRef is the cross-platform data format of VisualString's internal string buffer.

VisualString::~VisualString

(

)

The destructor.

VisualString::VisualString

(

const VisualString &

other

)

Copy constructor.

Parameters:

other

Another VisualString.

---

Member Function Documentation

void VisualString::calcStatistics

(

void

)

[private]

The number of lines and words are calculated and stored internally.

bool VisualString::characterIsNewlineCharacter

(

uint16

character

)

[private]

Returns true if character is new line character.

Parameters:

character

The character to inspect.

Returns:

True if character is new line character, false if not.

bool VisualString::characterIsWhitespaceCharacter

(

uint16

character

)

[private]

Returns true if character is whitespace character.

Parameters:

character

The character to inspect.

Returns:

True if character is whitespace character, false if not.

void VisualString::clear

(

void

)

Resets internally used variables and releases allocated memory.

VisualString * VisualString::clone

(

void

)

const [virtual]

Copies the current VisualString and returns a pointer to a new VisualString.

Implements VizKit::VisualObject.

Reimplemented in VizKit::VisualStyledString.

void VisualString::copy

(

const VisualString &

other

)

[protected]

Copy method for assignment operator and copy constructor.

Parameters:

other

Another VisualString.

VisualString * VisualString::createJoinedString

(

std::vector< VisualString >

stringVector

)

[static]

Joins the strings of the vector to create a joined string. The items of the vector are separated by newline.

Parameters:

stringVector

The vector of strings.

Returns:

A VisualString.

VisualString * VisualString::createStringWithLine

(

uint32

index

)

const

Returns one line of the string.

Parameters:

index

The requested line number. The first line has an index of 0.

Returns:

One line of the string.

Remarks:

The caller has to delete the VisualString.

VisualString * VisualString::createStringWithWord

(

uint32

index

)

const

Returns one word of the string.

Parameters:

index

The requested index number. The first word has an index of 0.

Returns:

One word of the string.

Remarks:

The caller has to delete the VisualString.

VisualString * VisualString::createWithConstStringDataRef

(

ConstStringDataRef

constStringDataRef

)

[static]

Creates a VisualString with a platform native string data type (CFStringRef on Mac, wchar_t pointer on Windows).

Parameters:

constStringDataRef

On Mac a CFStringRef, on Windows a wchar_t pointer.

VisualString * VisualString::createWithContentsOfFile

(

VisualFile &

aFile

)

[static]

Creates a VisualString from the contents of a file.

Parameters:

aFile

Reference to a file.

Remarks:

The file is opened, the content is read as a string, then the file is closed again.

VisualString * VisualString::createWithContentsOfURL	(	const char *const	aURL,
		const VisualItemIdentifier &	anId
	)			[static]

Creates a VisualString with the contents of a URL.

Parameters:

	aURL	A URL (aka URI).
	anId	An identifier.

VisualString * VisualString::createWithUTF16Buffer	(	const uint16 *const	aStringVal,
		uint32	aNumberOfCharacters
	)			[static]

Creates a VisualString from a pointer to an UTF-16 string buffer.

Parameters:

	aStringVal	A pointer to the UTF-16 encoded char string buffer.
	aNumberOfCharacters	The number of characters of the UTF-16 encoded char string buffer.

Remarks:

The caller has to delete the VisualString.

VisualString * VisualString::createWithUTF16String

(

const uint16 *const

aStringVal

)

[static]

Creates a VisualString from a pointer to an UTF-16 string.

Parameters:

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.

VisualString * VisualString::createWithUTF8Buffer	(	const char *const	aStringVal,
		uint32	numberOfBytes
	)			[static]

Creates a VisualString from a pointer to an UTF-8 string buffer.

Parameters:

	aStringVal	A pointer to the UTF-8 encoded char string buffer.
	numberOfBytes	The number of bytes of the UTF-8 encoded char string buffer.

Remarks:

The caller has to delete the VisualString.

VisualString * VisualString::createWithUTF8String

(

const char *const

aStringVal

)

[static]

Creates a VisualString from a pointer to an UTF-8 string.

Parameters:

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.

void VisualString::dataLoadDidEnd

(

const VisualItemIdentifier &

identifier

)

[virtual]

Notification that the loading of data ended.

Parameters:

identifier

The identifier of the data load request.

Reimplemented from VizKit::VisualObject.

uint16 VisualString::getCharacterAtIndex

(

uint32

index

)

const [private]

Returns a single character of the string data.

Parameters:

index

The position of the character in the string. First position starts with 0.

Returns:

A single character of the string data.

ConstStringDataRef VisualString::getCharactersPointer

(

void

)

const

Returns a pointer to the internal string data.

Returns:

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.

uint32 VisualString::getNumberOfCharacters

(

void

)

const

Returns the number of characters of the string.

Returns:

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 VisualString::getNumberOfLines

(

void

)

const

Returns the number of lines of the string.

Returns:

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 VisualString::getNumberOfNonWhitespaceCharacters

(

void

)

const

Returns the number of non-whitespace characters of the string.

Returns:

The number of non-whitespace characters of the string.

uint32 VisualString::getNumberOfWords

(

void

)

const

Returns the number of words of the string.

Returns:

The number of words of the string.

VisualString VisualString::getSubstring	(	uint32	startIdx,
		uint32	numberOfSubstringCharacters
	)			const

Returns a substring of the VisualString.

Parameters:

	startIdx	The 0-based start index of the requested substring.
	numberOfSubstringCharacters	The number of characters to include in the substring.

const uint16 *const VisualString::getUtf16Representation

(

void

)

Returns a pointer to a 16-bit buffer with utf-16 encoded string data.

Returns:

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 char *const VisualString::getUtf8Representation

(

void

)

Returns a pointer to a char buffer with utf-8 encoded string data.

Returns:

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.

bool VisualString::initWithConstStringDataRef

(

ConstStringDataRef

constStringDataRef

)

Initializes a VisualString with a platform native string data type (CFStringRef on Mac, wchar_t pointer on Windows).

Parameters:

constStringDataRef

On Mac a CFStringRef, on Windows a wchar_t pointer.

bool VisualString::initWithContentsOfFile

(

VisualFile &

aFile

)

Initializes a VisualString from the contents of a file.

Parameters:

aFile

Reference to a file.

Returns:

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 VisualString::initWithContentsOfURL	(	const char *const	aURL,
		const VisualItemIdentifier &	anId
	)

Initializes a VisualString with the contents of a URL.

Parameters:

	anId	An identifier.
	aURL	A URL (aka URI).

void VisualString::initWithUTF16Buffer	(	const uint16 *const	aStringVal,
		uint32	aNumberOfCharacters
	)

Initializes a VisualString with a pointer to an UTF-16 string buffer.

Parameters:

	aStringVal	A pointer to the UTF-16 encoded char string buffer.
	aNumberOfCharacters	The number of characters of the UTF-16 encoded char string buffer.

void VisualString::initWithUTF16String

(

const uint16 *const

aStringVal

)

Initializes a VisualString with a pointer to an UTF-16 string.

Parameters:

aStringVal

A pointer to the UTF-16 encoded char string value.

Remarks:

The string must be terminated with a NULL byte.

void VisualString::initWithUTF8Buffer	(	const char *const	aStringVal,
		uint32	numberOfBytes
	)

Initializes a VisualString with a pointer to an UTF-8 string buffer.

Parameters:

	aStringVal	A pointer to the UTF-8 encoded char string buffer.
	numberOfBytes	The number of bytes of the UTF-8 encoded char string buffer.

void VisualString::initWithUTF8String

(

const char *const

aStringVal

)

Initializes a VisualString with a pointer to an UTF-8 string.

Parameters:

aStringVal

A pointer to the UTF-8 encoded char string value.

Remarks:

The string must be terminated with a NULL byte.

bool VisualString::isEmpty

(

void

)

const

Returns true if the number of non-whitespace characters of the string is 0.

Returns:

True if the number of non-whitespace characters of the string is 0.

void VisualString::normalizeLineEndings

(

)

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

bool VisualString::operator!=

(

const VisualString &

other

)

const

Inequality operator.

Parameters:

other

Another VisualString.

const VisualString & VisualString::operator+

(

const VisualString &

other

)

Plus operator appends another string.

Parameters:

other

Another VisualString.

const VisualString & VisualString::operator+

(

const char *

charString

)

Plus operator appends an 8-bit char string.

Parameters:

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.

bool VisualString::operator<

(

const VisualString &

other

)

const

Less than operator.

Parameters:

other

Another VisualString.

Remarks:

The less than operator is used by std::map for find() and sorting (if VisualString is used as key_type).

VisualString & VisualString::operator=

(

const VisualString &

other

)

Assignment operator.

bool VisualString::operator==

(

const VisualString &

other

)

const

Equality operator.

Parameters:

other

Another VisualString.

std::vector< VisualString > VisualString::splitWithDelimiter

(

const VisualString &

delimiter

)

Returns an array of strings by splitting the string with a separator string (delimiter).

Parameters:

delimiter

The string to use as separator.

Returns:

An array with VisualStrings.

void VisualString::trim

(

void

)

Remove whitespace characters from the start and end of the string.

void VisualString::writeDebugLog

(

void

)

const

Writes information about the VisualString to the log file.

Remarks:

Useful for debuggin and tracing purposes.

---

Member Data Documentation

ArrayOfSubstringPointers VizKit::VisualString::arrayOfLines [private]

The lines (rows) of the VisualString collected as substrings.

ArrayOfSubstringPointers VizKit::VisualString::arrayOfWords [private]

The words of the VisualString collected as substrings.

uint32 VizKit::VisualString::numberOfCharacters [private]

The number of characters of the string.

uint32 VizKit::VisualString::numberOfLines [private]

The number of lines of the string.

uint32 VizKit::VisualString::numberOfNonWhitespaceCharacters [private]

The number of characters of the string.

uint32 VizKit::VisualString::numberOfWords [private]

The number of words of the string.

StringDataRef VizKit::VisualString::theString [private]

A pointer to the internally stored string data.

uint16* VizKit::VisualString::utf16representation [private]

Optionally available utf-16 representation of string data.

char* VizKit::VisualString::utf8representation [private]

Optionally available utf-8 representation of string data.

---

The documentation for this class was generated from the following files:

• Tools/VisualString.h
• Tools/VisualString.cpp