Unicode string without styling or formatting information. More...

#include <VisualString.h>

Inheritance diagram for VizKit::VisualString:

Classes
struct	VisualStringSubstringPointer
	Substring of the VisualString with start position and length. More...
Public Member Functions
	VisualString ()
	The constructor.
	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.
	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.
	VisualString (ConstStringDataRef aStringVal)
	A constructor that constructs a VisualString from a ConstStringDataRef.
void	initWithUTF8String (const char *const aStringVal)
	Initializes a VisualString with a pointer to an UTF-8 string.
void	initWithUTF8Buffer (const char *const aStringVal, size_t numberOfBytes)
	Initializes a VisualString with a pointer to an UTF-8 string buffer.
void	initWithUTF16String (const uint16 *const aStringVal)
	Initializes a VisualString with a pointer to an UTF-16 string.
void	initWithUTF16Buffer (const uint16 *const aStringVal, size_t aNumberOfCharacters)
	Initializes a VisualString with a pointer to an UTF-16 string buffer.
bool	initWithContentsOfFile (VisualFile &aFile)
	Initializes a VisualString from the contents of a file.
bool	initWithContentsOfURL (const char *const aURL, const VisualItemIdentifier &anId)
	Initializes a VisualString with the contents of a URL.
bool	initWithConstStringDataRef (ConstStringDataRef constStringDataRef)
	Initializes a VisualString with a platform native string data type (CFStringRef on Mac, wchar_t pointer on Windows).
	~VisualString ()
	The destructor.
	VisualString (const VisualString &other)
	Copy constructor.
VisualString &	operator= (const VisualString &other)
	Assignment operator.
bool	operator< (const VisualString &other) const
	Less than operator.
bool	operator== (const VisualString &other) const
	Equality operator.
bool	operator!= (const VisualString &other) const
	Inequality operator.
const VisualString &	operator+ (const VisualString &other)
	Plus operator appends another string.
const VisualString &	operator+ (const char *charString)
	Plus operator appends an 8-bit char string.
virtual VisualString *	clone (void) const
	Copies the current VisualString and returns a pointer to a new VisualString.
void	clear (void)
	Resets internally used variables and releases allocated memory.
size_t	getNumberOfCharacters (void) const
	Returns the number of characters of the string.
uint32	getNumberOfNonWhitespaceCharacters (void) const
	Returns the number of non-whitespace characters of the string.
bool	isEmpty (void) const
	Returns true if the number of non-whitespace characters of the string is 0.
uint32	getNumberOfWords (void) const
	Returns the number of words of the string.
uint32	getNumberOfLines (void) const
	Returns the number of lines of the string.
VisualString *	createStringWithLine (uint32 index) const
	Returns one line of the string.
VisualString *	createStringWithWord (uint32 index) const
	Returns one word of the string.
ConstStringDataRef	getCharactersPointer (void) const
	Returns a pointer to the internal string data.
const char *const	getUtf8Representation (void)
	Returns a pointer to a char buffer with utf-8 encoded string data.
const uint16 *const	getUtf16Representation (void)
	Returns a pointer to a 16-bit buffer with utf-16 encoded string data.
VisualString	getSubstring (uint32 startIdx, uint32 numberOfSubstringCharacters) const
	Returns a substring of the VisualString.
void	normalizeLineEndings ()
	Normalizes the line endings of the string.
void	writeDebugLog (void) const
	Writes information about the VisualString to the log file.
std::vector< VisualString >	splitWithDelimiter (const VisualString &delimiter)
	Returns an array of strings by splitting the string with a separator string (delimiter).
void	trim (void)
	Remove whitespace characters from the start and end of the string.
virtual void	dataLoadDidEnd (const VisualItemIdentifier &identifier)
	Notification that the loading of data ended.
Static Public Member Functions
static VisualString *	createJoinedString (std::vector< VisualString > stringVector)
	Joins the strings of the vector to create a joined string.
static VisualString *	createWithUTF8String (const char *const aStringVal)
	Creates a VisualString from a pointer to an UTF-8 string.
static VisualString *	createWithUTF8Buffer (const char *const aStringVal, uint32 numberOfBytes)
	Creates a VisualString from a pointer to an UTF-8 string buffer.
static VisualString *	createWithUTF16String (const uint16 *const aStringVal)
	Creates a VisualString from a pointer to an UTF-16 string.
static VisualString *	createWithUTF16Buffer (const uint16 *const aStringVal, uint32 aNumberOfCharacters)
	Creates a VisualString from a pointer to an UTF-16 string buffer.
static VisualString *	createWithContentsOfFile (VisualFile &aFile)
	Creates a VisualString from the contents of a file.
static VisualString *	createWithContentsOfURL (const char *const aURL, const VisualItemIdentifier &anId)
	Creates a VisualString with the contents of a URL.
static VisualString *	createWithConstStringDataRef (ConstStringDataRef constStringDataRef)
	Creates a VisualString with a platform native string data type (CFStringRef on Mac, wchar_t pointer on Windows).
Protected Member Functions
void	copy (const VisualString &other)
	Copy method for assignment operator and copy constructor.
Private Types
typedef std::vector < VisualStringSubstringPointer >	ArrayOfSubstringPointers
	VisualStringSubstringPointers can be collected in a vector of structs.
Private Member Functions
void	calcStatistics (void)
	The number of lines and words are calculated and stored internally.
uint16	getCharacterAtIndex (size_t index) const
	Returns a single character of the string data.
bool	characterIsNewlineCharacter (uint16 character)
	Returns true if character is new line character.
bool	characterIsWhitespaceCharacter (uint16 character)
	Returns true if character is whitespace character.
Private Attributes
StringDataRef	theString
	A pointer to the internally stored string data.
char *	utf8representation
	Optionally available utf-8 representation of string data.
uint16 *	utf16representation
	Optionally available utf-16 representation of string data.
size_t	numberOfCharacters
	The number of characters of the string.
uint32	numberOfNonWhitespaceCharacters
	The number of characters of the string.
uint32	numberOfWords
	The number of words of the string.
uint32	numberOfLines
	The number of lines of the string.
ArrayOfSubstringPointers	arrayOfLines
	The lines (rows) of the VisualString collected as substrings.
ArrayOfSubstringPointers	arrayOfWords
	The words of the VisualString collected as substrings.

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 ( size_t 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.

size_t 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,
		size_t	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,
		size_t	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.

size_t 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:

vizkit/source/Tools/VisualString.h
vizkit/source/Tools/VisualString.cpp

Classes

Public Member Functions

Static Public Member Functions

Protected Member Functions

Private Types

Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation