VString is a string container class that should help to eliminate almost all use of char buffer and char* and their inherent dangers, in the Vault APIs and most source code. More...

#include <vstring.h>

Public Types
typedef VStringIterator < VString & >	iterator
typedef VStringIterator< const VString & >	const_iterator
typedef VStringIterator < VString & >	reverse_iterator
typedef VStringIterator< const VString & >	const_reverse_iterator
Public Member Functions
	VString ()
	Constructs an empty string.
	VString (const VChar &c)
	Constructs a string from a character.
	VString (const VString &s)
	"Copy Constructor" -- constructs from another VString.
	VString (char c)
	Constructs a string from a char.
	VString (char *s)
	Constructs a string from a C string.
	VString (const std::wstring &ws)
	Constructs from a "wide" string, converting from UTF-16/32 to our internal UTF-8.
	VString (const VCodePoint &cp)
	Constructs a string from a Unicode code point (a single character value).
	~VString ()
	Destructor.
VString &	operator= (const VString &s)
	Basic assignment operator.
VString &	operator= (const VString *s)
	Assign from a pointer to VString.
VString &	operator= (const VCodePoint &cp)
	Assigns from a Unicode code point (a single character value).
VString &	operator= (const VChar &c)
	Assigns the string from a character.
VString &	operator= (char c)
	Assigns the string from a char.
VString &	operator= (const char *s)
	Assigns the string from a C string.
VString &	operator= (const std::wstring &ws)
	Assigns the string from a "wide" string, converting from UTF-16/32 to our internal UTF-8.
VString &	operator= (int i)
	Assigns the string from an int.
VString &	operator= (Vu8 i)
	Assigns the string from a Vu8.
VString &	operator= (Vs8 i)
	Assigns the string from a Vs8.
VString &	operator= (Vu16 i)
	Assigns the string from a Vu16.
VString &	operator= (Vs16 i)
	Assigns the string from a Vs16.
VString &	operator= (Vu32 i)
	Assigns the string from a Vu32.
VString &	operator= (Vu64 i)
	Assigns the string from a Vu64.
VString &	operator= (Vs64 i)
	Assigns the string from a Vs64.
VString &	operator= (VDouble d)
	Assigns the string from a VDouble.
VString	operator+ (const char c) const
	Creates a string from this string + (appending) a char.
VString	operator+ (const char *s) const
	Creates a string from this string + (appending) a (const char*) buffer.
VString	operator+ (const std::wstring &ws) const
	Creates a string from this string + (appending) "wide" string, converting it from UTF-16/32 to our internal UTF-8.
VString	operator+ (const VString &s) const
	Creates a string from this string + (appending) another string.
VString	operator+ (const VCodePoint &cp) const
	Creates a string from this string + (appending) a unicode code point.
VString &	operator+= (const VChar &c)
	Appends a character to the string.
VString &	operator+= (const VString &s)
	Appends another string to the string.
VString &	operator+= (char c)
	Appends a char to the string.
VString &	operator+= (const char *s)
	Appends a C string to the string.
VString &	operator+= (const std::wstring &ws)
	Appends a "wide" string to the string, converting it from UTF-16/32 to our internal UTF-8.
VString &	operator+= (const VCodePoint &cp)
	Appends to the string from a Unicode code point (a single character value).
VString &	operator+= (int i)
	Appends to the string from an int.
VString &	operator+= (Vu8 i)
	Appends to the string from a Vu8.
VString &	operator+= (Vs8 i)
	Appends to the string from a Vs8.
VString &	operator+= (Vu16 i)
	Appends to the string from a Vu16.
VString &	operator+= (Vs16 i)
	Appends to the string from a Vs16.
VString &	operator+= (Vu32 i)
	Appends to the string from a Vu32.
VString &	operator+= (Vu64 i)
	Appends to the string from a Vu64.
VString &	operator+= (Vs64 i)
	Appends to the string from a Vs64.
VString &	operator+= (VDouble f)
	Appends to the string from a VDouble.
void	readFromIStream (std::istream &in)
	Builds the string by reading from an istream.
void	appendFromIStream (std::istream &in)
	Appends to the string by reading from an istream.
iterator	begin ()
const_iterator	begin () const
iterator	end ()
const_iterator	end () const
reverse_iterator	rbegin ()
const_reverse_iterator	rbegin () const
reverse_iterator	rend ()
const_reverse_iterator	rend () const
void	insert (const VCodePoint &cp, const VString::iterator &position)
	Inserts the specified code point into the string at the specified iterator position, moving the remaining part of the string later in the buffer.
void	insert (const VString &s, const VString::iterator &position)
	Inserts the specified string into the string at the specified iterator position, moving the remaining part of the string later in the buffer.
void	insert (char c, const VString::iterator &position)
	Inserts the specified character into the string at the specified iterator position, moving the remaining part of the string later in the buffer.
void	insert (const VCodePoint &cp, int offset=0)
	Inserts the specified code point into the string at the specified offset (default is at the front of the string), moving the remaining part of the string later in the buffer.
void	insert (const VString &s, int offset=0)
	Inserts the specified string into the string at the specified offset (default is at the front of the string), moving the remaining part of the string later in the buffer.
void	insert (char c, int offset=0)
	Inserts the specified character into the string at the specified offset (default is at the front of the string), moving the remaining part of the string later in the buffer.
int	getNumCodePoints () const
	Returns the number of code points in the string.
int	length () const
	Returns the string length in bytes.
void	truncateCodePoints (int maxNumCodePoints)
	Truncates the string to specified number of code points; if the string is already that length or less, nothing happens.
void	truncateLength (int maxLength)
	Truncates the string to specified length; if the string is already that length or less, nothing happens.
bool	isEmpty () const
	Returns true if the string length is zero.
bool	isNotEmpty () const
	Returns true if the string length is non-zero.
VChar	at (int i) const
	Returns the character at the specified index.
VChar	operator[] (int i) const
	Returns the character at the specified index.
char &	operator[] (int i)
	Returns a reference to the char at the specified index, which can be assigned to.
char	charAt (int i) const
	Returns the char at the specified index.
	operator const char * () const
	Coerces the string to a C string, for use with APIs that take a const char* parameter.
const char *	chars () const
	Returns the string as a C string, for use with APIs that take a const char* parameter.
std::wstring	toUTF16 () const
	Returns a "wide" string built from the VString, converting from our internal UTF-8 to UTF-16 code units.
bool	equalsIgnoreCase (const VString &s) const
	Returns true if this string is equal to the specified string, ignoring case, using strcmp semantics.
bool	equalsIgnoreCase (const char *s) const
	Returns true if this string is equal to the specified C string, ignoring case, using strcmp semantics.
int	compare (const VString &s) const
	Returns the comparison value of this string and the supplied string, using strcmp semantics.
int	compare (const char *s) const
	Returns the comparison value of this string and the supplied C string, using strcmp semantics.
int	compareIgnoreCase (const VString &s) const
	Returns the comparison value of this string and the supplied string, ignoring case, using strcmp semantics.
int	compareIgnoreCase (const char *s) const
	Returns the comparison value of this string and the supplied C string, ignoring case, using strcmp semantics.
bool	startsWith (const VString &s) const
	Returns true if this string starts with the specified string.
bool	startsWithIgnoreCase (const VString &s) const
	Returns true if this string starts with the specified string (ignoring case).
bool	startsWith (const VCodePoint &cp) const
	Returns true if this string starts with the specified code point.
bool	startsWith (char c) const
	Returns true if this string starts with the specified char.
bool	endsWith (const VString &s) const
	Returns true if this string ends with the specified string.
bool	endsWithIgnoreCase (const VString &s) const
	Returns true if this string ends with the specified string (ignoring case).
bool	endsWith (const VCodePoint &cp) const
	Returns true if this string ends with the specified code point.
bool	endsWith (char c) const
	Returns true if this string ends with the specified char.
VString::const_iterator	find (const VCodePoint &cp) const
	Returns an iterator pointing to the first occurrence of the specified code point within the string.
VString::iterator	find (const VCodePoint &cp)
VString::const_iterator	find (const VCodePoint &cp, const VString::const_iterator &startPosition, const VString::const_iterator &endPosition) const
	Returns an iterator pointing to the first occurrence of the specified code point within the string, bounded by the specified start and end iterator positions.
VString::iterator	find (const VCodePoint &cp, const VString::iterator &startPosition, const VString::iterator &endPosition)
int	indexOf (char c, int fromIndex=0) const
	Returns the index of the first occurrence of the specified character.
int	indexOfIgnoreCase (char c, int fromIndex=0) const
	Returns the index of the first occurrence of the specified character, using a case-insensitive comparison.
int	indexOf (const VString &s, int fromIndex=0) const
	Returns the index of the first occurrence of the specified string.
int	indexOfIgnoreCase (const VString &s, int fromIndex=0) const
	Returns the index of the first occurrence of the specified string, using a case-insensitive comparison.
int	lastIndexOf (char c, int fromIndex=-1) const
	Returns the index of the last occurrence of the specified character.
int	lastIndexOfIgnoreCase (char c, int fromIndex=-1) const
	Returns the index of the last occurrence of the specified character, using a case-insensitive comparison.
int	lastIndexOf (const VString &s, int fromIndex=-1) const
	Returns the index of the last occurrence of the specified string.
int	lastIndexOfIgnoreCase (const VString &s, int fromIndex=-1) const
	Returns the index of the last occurrence of the specified string, using a case-insensitive comparison.
bool	regionMatches (int thisIndex, const VString &otherString, int otherIndex, int regionLength, bool caseSensitive=true) const
	Returns true if the specified range of this string matches the specified range of the specified string.
bool	contains (char c, int fromIndex=0) const
	Returns true if the specified character exists in this string.
bool	containsIgnoreCase (char c, int fromIndex=0) const
	Returns true if the specified character exists in this string, using a case-insensitive match.
bool	contains (const VString &s, int fromIndex=0) const
	Returns true if the specified string exists in this string.
bool	containsIgnoreCase (const VString &s, int fromIndex=0) const
	Returns true if the specified string exists in this string, using a case-insensitive match.
int	replace (const VString &searchString, const VString &replacementString, bool caseSensitiveSearch=true)
	Replaces every occurrence of the specified search string with the supplied replacement string.
int	replace (const VCodePoint &searchChar, const VCodePoint &replacementChar, bool caseSensitiveSearch=true)
	Replaces every occurrence of the specified search string with the supplied replacement string.
void	toLowerCase ()
	Folds the string to lower case using tolower().
void	toUpperCase ()
	Folds the string to upper case using toupper().
int	parseInt () const
	Parses the string as an integer.
Vs64	parseS64 () const
	Parses the string as a Vs64 integer.
Vu64	parseU64 () const
	Parses the string as a Vu64 integer.
VDouble	parseDouble () const
	Parses the string as a VDouble integer.
void	set (int i, const VChar &c)
	Sets the character at the specified index to the specified value.
void	getSubstring (VString &toString, int startIndex, int endIndex=-1) const
	Copies a substring of this string to a target string.
void	getSubstring (VString &toString, VString::const_iterator rangeStart, VString::const_iterator rangeEnd) const
void	substringInPlace (int startIndex, int endIndex=-1)
	Makes a substring of this string in place (contrast with getSubstring(), which puts the substring into a different object).
void	split (VStringVector &result, const VCodePoint &delimiter, int limit=0, bool stripTrailingEmpties=true) const
	Splits the string into pieces using a specified delimiter character.
VStringVector	split (const VCodePoint &delimiter, int limit=0, bool stripTrailingEmpties=true) const
	Convenience version of split() that returns the vector.
void	trim ()
	Strips leading and trailing whitespace from the string.
void	copyToBuffer (char *toBuffer, int bufferSize) const
	Copies the string's chars to the specified buffer, plus a null terminator byte; the number of bytes copied (including null terminator) is limited to the specified buffer size.
void	copyFromBuffer (const char *fromBuffer, int startIndex, int endIndex)
	Sets the string by copying a number of characters from the source buffer.
void	copyFromCString (const char *fromBuffer)
	Sets the string by copying a C string from the source buffer.
void	copyToPascalString (char *pascalBuffer) const
	Copies the string's chars to the specified Pascal string buffer, using the Pascal string format (length byte plus data).
void	copyFromPascalString (const char *pascalBuffer)
	Sets the string by copying a Pascal string from the source buffer.
void	setFourCharacterCode (Vu32 fourCharacterCode)
	Sets the string from a "four character code".
Vu32	getFourCharacterCode () const
	Returns the "four character code" represented by the string.
void	preflight (int stringLength)
	Ensures that the buffer is big enough to hold the specified string length.
void	preflightWithSimulatedFailure ()
	Simulates what happens if preflight() fails to allocate the buffer due to lack of memory.
char *	buffer ()
	Returns the string's char buffer pointer.
Vu8 *	getDataBuffer ()
	Returns the string's buffer pointer as a Vu8 pointer, which is a type directly compatible with the various stream data reading APIs.
const Vu8 *	getDataBufferConst () const
	Returns the string's buffer pointer as a const Vu8 pointer, which is a type directly compatible with the various stream data writing APIs.
char *	orphanDataBuffer ()
	Transfers ownership of the string's buffer to the caller and sets the string to empty (with no buffer).
void	postflight (int stringLength)
	Syncs the internal data to the specified length, setting the length and writing a null terminator into the buffer.
Static Public Member Functions
static const VString &	EMPTY ()
	Returns a reference to the read-only empty VString constant.
static const VString &	NATIVE_LINE_ENDING ()
	Returns a reference to the read-only VString constant holding the platform-native line ending character(s).
static const VString &	UNIX_LINE_ENDING ()
	Returns a reference to the read-only VString constant holding the Unix-style 0x0A line ending character.
static const VString &	MAC_CLASSIC_LINE_ENDING ()
	Returns a reference to the read-only VString constant holding the classic Mac Classic-style 0x0D line ending character.
static const VString &	DOS_LINE_ENDING ()
	Returns a reference to the read-only VString constant holding the DOS-style 0x0D0A line ending characters.
Friends
class	VStringUnit
	Let it examine our internals under test.
bool	operator== (const VString &lhs, const VString &rhs)
	Compares lhs and rhs for equality.
bool	operator== (const VString &lhs, const char *rhs)
	Compares lhs and rhs for equality.
bool	operator== (const char *lhs, const VString &rhs)
	Compares lhs and rhs for equality.
bool	operator== (const VString &lhs, char rhs)
	Compares s and c for equality.
bool	operator!= (const VString &lhs, const VString &rhs)
	Compares lhs and rhs for inequality.
bool	operator!= (const VString &lhs, const char *rhs)
	Compares lhs and rhs for inequality.
bool	operator!= (const char *lhs, const VString &rhs)
	Compares lhs and rhs for inequality.
bool	operator!= (const VString &lhs, char rhs)
	Compares lhs and rhs for inequality.
bool	operator< (const VString &lhs, const VString &rhs)
	Compares lhs and rhs.
bool	operator< (const VString &lhs, const char *rhs)
	Compares lhs and rhs.
bool	operator< (const char *lhs, const VString &rhs)
	Compares lhs and rhs.
bool	operator<= (const VString &lhs, const VString &rhs)
	Compares lhs and rhs.
bool	operator<= (const VString &lhs, const char *rhs)
	Compares lhs and rhs.
bool	operator<= (const char *lhs, const VString &rhs)
	Compares lhs and rhs.
bool	operator>= (const VString &lhs, const VString &rhs)
	Compares lhs and rhs.
bool	operator>= (const VString &lhs, const char *rhs)
	Compares lhs and rhs.
bool	operator>= (const char *lhs, const VString &rhs)
	Compares lhs and rhs.
bool	operator> (const VString &lhs, const VString &rhs)
	Compares lhs and rhs.
bool	operator> (const VString &lhs, const char *rhs)
	Compares lhs and rhs.
bool	operator> (const char *lhs, const VString &rhs)
	Compares lhs and rhs.

Detailed Description

VString is a string container class that should help to eliminate almost all use of char buffer and char* and their inherent dangers, in the Vault APIs and most source code.

VString objects can be created from raw char buffers, by formatting, or by reserving space and later assigning. Methods and operators are provided for concatenation, comparison, assignment, conversion, array access, searching, and formatting.

Methods that modify the string will expand the buffer as necessary, so you don't have to worry about overflowing the buffer. If the buffer needs to be expanded but the object is unable to expand it, a VException will be thrown.

Definition at line 189 of file vstring.h.

Constructor & Destructor Documentation

VString::VString ( const VChar & c )

Constructs a string from a character.

Parameters:

c	the character

Definition at line 86 of file vstring.cpp.

References ASSERT_INVARIANT, VChar::charValue(), and preflight().

VString::VString ( const VString & s )

"Copy Constructor" -- constructs from another VString.

Parameters:

s	the string to copy

Definition at line 97 of file vstring.cpp.

References ASSERT_INVARIANT, copyToBuffer(), length(), and preflight().

VString::VString ( char c ) [explicit]

Constructs a string from a char.

The explicit keyword is to prevent the previous VString s(n) meaning of preflight string to size "n" from compiling.

Parameters:

c the char

Definition at line 111 of file vstring.cpp.

References ASSERT_INVARIANT, and preflight().

VString::VString ( char * s )

Constructs a string from a C string.

Note that if strict formatting is off, the param is not marked const so that we avoid ambiguous linkage vs. the const param in the vararg ctor below.

Parameters:

s	pointer to C string to copy

Definition at line 125 of file vstring.cpp.

References ASSERT_INVARIANT, NULL, and VCHAR_NULL_TERMINATOR.

VString::VString ( const std::wstring & ws )

Constructs from a "wide" string, converting from UTF-16/32 to our internal UTF-8.

Parameters:

ws	the wide string to copy

Definition at line 206 of file vstring.cpp.

References ASSERT_INVARIANT.

VString::VString ( const VCodePoint & cp )

Constructs a string from a Unicode code point (a single character value).

Parameters:

cp	the code point to use

Definition at line 247 of file vstring.cpp.

References ASSERT_INVARIANT, and VCodePoint::toString().

Member Function Documentation

const VString & VString::NATIVE_LINE_ENDING ( ) [static]

Returns a reference to the read-only VString constant holding the platform-native line ending character(s).

If we are running on DOS/Windows it will be 0x0D0A. If we are running on Unix (including Mac OS X) it will be 0x0A. This is normally what you should use if you need to explicitly reference the preferred text file line ending for the current platform. In the rare case where you need to use a particular format (for example, if writing a file with a platform- or format-specific style, then you could use one of the platform specific accessors that are defined below.

Definition at line 52 of file vstring.cpp.

const VString & VString::UNIX_LINE_ENDING ( ) [static]

Returns a reference to the read-only VString constant holding the Unix-style 0x0A line ending character.

This is also what we consider the "native" line ending on Mac OS X.

Definition at line 62 of file vstring.cpp.

const VString & VString::MAC_CLASSIC_LINE_ENDING ( ) [static]

Returns a reference to the read-only VString constant holding the classic Mac Classic-style 0x0D line ending character.

Note that this is different from our "native" Unix-style line ending on Mac OS X.

Definition at line 68 of file vstring.cpp.

VString & VString::operator= ( const VString & s )

Basic assignment operator.

Parameters:

s	the string to copy

Definition at line 262 of file vstring.cpp.

References ASSERT_INVARIANT, copyToBuffer(), length(), and preflight().

VString & VString::operator= ( const VString * s )

Assign from a pointer to VString.

Parameters:

s	the string pointer to copy

Definition at line 281 of file vstring.cpp.

References ASSERT_INVARIANT, copyToBuffer(), length(), NULL, and preflight().

VString & VString::operator= ( const VCodePoint & cp )

Assigns from a Unicode code point (a single character value).

Parameters:

cp	the code point to use

Definition at line 338 of file vstring.cpp.

References ASSERT_INVARIANT, and VCodePoint::toString().

VString & VString::operator= ( const VChar & c )

Assigns the string from a character.

Parameters:

c	the character

Definition at line 348 of file vstring.cpp.

References ASSERT_INVARIANT, VChar::charValue(), and preflight().

VString & VString::operator= ( char c )

Assigns the string from a char.

Parameters:

c the char

Definition at line 360 of file vstring.cpp.

References ASSERT_INVARIANT, and preflight().

VString & VString::operator= ( const char * s )

Assigns the string from a C string.

Parameters:

s	pointer to the C string to copy

Definition at line 372 of file vstring.cpp.

References ASSERT_INVARIANT, NULL, and preflight().

VString & VString::operator= ( const std::wstring & ws )

Assigns the string from a "wide" string, converting from UTF-16/32 to our internal UTF-8.

Parameters:

ws	the wide string to copy

Definition at line 393 of file vstring.cpp.

References ASSERT_INVARIANT.

VString & VString::operator= ( int i )

Assigns the string from an int.

Parameters:

i	the integer value to be formatted

Definition at line 403 of file vstring.cpp.

References ASSERT_INVARIANT.

VString & VString::operator= ( Vu8 i )

Assigns the string from a Vu8.

Parameters:

i	the integer value to be formatted

Definition at line 413 of file vstring.cpp.

References ASSERT_INVARIANT.

VString & VString::operator= ( Vs8 i )

Assigns the string from a Vs8.

Parameters:

i	the integer value to be formatted

Definition at line 423 of file vstring.cpp.

References ASSERT_INVARIANT.

VString & VString::operator= ( Vu16 i )

Assigns the string from a Vu16.

Parameters:

i	the integer value to be formatted

Definition at line 433 of file vstring.cpp.

References ASSERT_INVARIANT.

VString & VString::operator= ( Vs16 i )

Assigns the string from a Vs16.

Parameters:

i	the integer value to be formatted

Definition at line 443 of file vstring.cpp.

References ASSERT_INVARIANT.

VString & VString::operator= ( Vu32 i )

Assigns the string from a Vu32.

Parameters:

i	the integer value to be formatted

Definition at line 453 of file vstring.cpp.

References ASSERT_INVARIANT.

VString & VString::operator= ( Vu64 i )

Assigns the string from a Vu64.

Parameters:

i	the integer value to be formatted

Definition at line 475 of file vstring.cpp.

References ASSERT_INVARIANT.

VString & VString::operator= ( Vs64 i )

Assigns the string from a Vs64.

Parameters:

i	the integer value to be formatted

Definition at line 486 of file vstring.cpp.

References ASSERT_INVARIANT.

VString & VString::operator= ( VDouble d )

Assigns the string from a VDouble.

Parameters:

d	the double value to be formatted

Definition at line 497 of file vstring.cpp.

References ASSERT_INVARIANT.

VString VString::operator+ ( const char c ) const

Creates a string from this string + (appending) a char.

Parameters:

c	the char to append

Definition at line 507 of file vstring.cpp.

References chars().

VString VString::operator+ ( const char * s ) const

Creates a string from this string + (appending) a (const char*) buffer.

Parameters:

s	the string to append

Definition at line 512 of file vstring.cpp.

References chars().

VString VString::operator+ ( const std::wstring & ws ) const

Creates a string from this string + (appending) "wide" string, converting it from UTF-16/32 to our internal UTF-8.

Parameters:

ws	the wide string to append

Definition at line 517 of file vstring.cpp.

References VString().

VString VString::operator+ ( const VString & s ) const

Creates a string from this string + (appending) another string.

Parameters:

s	the string to append

Definition at line 523 of file vstring.cpp.

References chars().

VString VString::operator+ ( const VCodePoint & cp ) const

Creates a string from this string + (appending) a unicode code point.

Parameters:

cp	the code point to append

Definition at line 536 of file vstring.cpp.

References VCodePoint::toString().

VString & VString::operator+= ( const VChar & c )

Appends a character to the string.

Parameters:

c	the character

Definition at line 542 of file vstring.cpp.

References ASSERT_INVARIANT, VChar::charValue(), and preflight().

VString & VString::operator+= ( const VString & s )

Appends another string to the string.

Parameters:

s	the string to copy

Definition at line 554 of file vstring.cpp.

References ASSERT_INVARIANT, chars(), length(), and preflight().

VString & VString::operator+= ( char c )

Appends a char to the string.

Parameters:

c the char

Definition at line 571 of file vstring.cpp.

References ASSERT_INVARIANT, and preflight().

VString & VString::operator+= ( const char * s )

Appends a C string to the string.

Parameters:

s	pointer to the C string to copy

Definition at line 583 of file vstring.cpp.

References ASSERT_INVARIANT, and preflight().

VString & VString::operator+= ( const std::wstring & ws )

Appends a "wide" string to the string, converting it from UTF-16/32 to our internal UTF-8.

Parameters:

ws	pointer to the wide string to copy

Definition at line 597 of file vstring.cpp.

VString & VString::operator+= ( const VCodePoint & cp )

Appends to the string from a Unicode code point (a single character value).

Parameters:

cp	the code point to use

Definition at line 620 of file vstring.cpp.

References ASSERT_INVARIANT, and VCodePoint::toString().

VString & VString::operator+= ( int i )

Appends to the string from an int.

Parameters:

i	the integer value to be formatted

Definition at line 631 of file vstring.cpp.

References ASSERT_INVARIANT, and VSTRING_INT.

VString & VString::operator+= ( Vu8 i )

Appends to the string from a Vu8.

Parameters:

i	the integer value to be formatted

Definition at line 641 of file vstring.cpp.

References ASSERT_INVARIANT, and VSTRING_U8.

VString & VString::operator+= ( Vs8 i )

Appends to the string from a Vs8.

Parameters:

i	the integer value to be formatted

Definition at line 651 of file vstring.cpp.

References ASSERT_INVARIANT, and VSTRING_S8.

VString & VString::operator+= ( Vu16 i )

Appends to the string from a Vu16.

Parameters:

i	the integer value to be formatted

Definition at line 661 of file vstring.cpp.

References ASSERT_INVARIANT, and VSTRING_U16.

VString & VString::operator+= ( Vs16 i )

Appends to the string from a Vs16.

Parameters:

i	the integer value to be formatted

Definition at line 671 of file vstring.cpp.

References ASSERT_INVARIANT, and VSTRING_S16.

VString & VString::operator+= ( Vu32 i )

Appends to the string from a Vu32.

Parameters:

i	the integer value to be formatted

Definition at line 681 of file vstring.cpp.

References ASSERT_INVARIANT, and VSTRING_U32.

VString & VString::operator+= ( Vu64 i )

Appends to the string from a Vu64.

Parameters:

i	the integer value to be formatted

Definition at line 703 of file vstring.cpp.

References ASSERT_INVARIANT, and VSTRING_U64.

VString & VString::operator+= ( Vs64 i )

Appends to the string from a Vs64.

Parameters:

i	the integer value to be formatted

Definition at line 714 of file vstring.cpp.

References ASSERT_INVARIANT, and VSTRING_S64.

VString & VString::operator+= ( VDouble f )

Appends to the string from a VDouble.

Parameters:

f	the float value to be formatted

Definition at line 725 of file vstring.cpp.

References ASSERT_INVARIANT, and VSTRING_DOUBLE.

void VString::readFromIStream ( std::istream & in )

Builds the string by reading from an istream.

Parameters:

in	the input stream

Definition at line 735 of file vstring.cpp.

References appendFromIStream(), ASSERT_INVARIANT, and EMPTY().

void VString::appendFromIStream ( std::istream & in )

Appends to the string by reading from an istream.

Parameters:

in	the input stream

Definition at line 745 of file vstring.cpp.

References ASSERT_INVARIANT.

void VString::insert	(	const VCodePoint &	cp,
		const VString::iterator &	position
	)

Inserts the specified code point into the string at the specified iterator position, moving the remaining part of the string later in the buffer.

Thus the length of the string increases by the length of the code point. To append, you are better off using operator+=. Note that the iterator position does not change during this insert.

Parameters:

cp	the code point to insert
position	the position to insert at

Definition at line 844 of file vstring.cpp.

void VString::insert	(	const VString &	s,
		const VString::iterator &	position
	)

Inserts the specified string into the string at the specified iterator position, moving the remaining part of the string later in the buffer.

Thus the length of the string increases by the length of the string being inserted To append, you are better off using operator+=. Note that the iterator position does not change during this insert.

Parameters:

s	the string to insert
position	the position to insert at

Definition at line 848 of file vstring.cpp.

References insert().

void VString::insert	(	char	c,
		const VString::iterator &	position
	)

Inserts the specified character into the string at the specified iterator position, moving the remaining part of the string later in the buffer.

Thus the length of the string increases by 1. To append, you are better off using operator+=. Note that the iterator position does not change during this insert.

Parameters:

c	the character to insert
position	the position to insert at

Definition at line 852 of file vstring.cpp.

References insert().

void VString::insert	(	const VCodePoint &	cp,
		int	offset = `0`
	)

Inserts the specified code point into the string at the specified offset (default is at the front of the string), moving the remaining part of the string later in the buffer.

Thus the length of the string increases by 1 character. To append, you are better off using operator+=.

Parameters:

cp	the code point to insert
offset	the buffer location to insert in front of

Definition at line 856 of file vstring.cpp.

References insert(), and VString().

void VString::insert	(	const VString &	s,
		int	offset = `0`
	)

Inserts the specified string into the string at the specified offset (default is at the front of the string), moving the remaining part of the string later in the buffer.

Thus the length of the string increases by the length of the string being inserted. To append, you are better off using operator+=.

Parameters:

s	the string to insert
offset	the location to insert in front of

Definition at line 860 of file vstring.cpp.

References ASSERT_INVARIANT, chars(), length(), postflight(), preflight(), V_MAX, and V_MIN.

void VString::insert	(	char	c,
		int	offset = `0`
	)

Inserts the specified character into the string at the specified offset (default is at the front of the string), moving the remaining part of the string later in the buffer.

Thus the length of the string increases by 1 character. To append, you are better off using operator+=.

Parameters:

c	the char to insert
offset	the location to insert in front of

Definition at line 896 of file vstring.cpp.

References ASSERT_INVARIANT, length(), postflight(), preflight(), V_MAX, and V_MIN.

int VString::getNumCodePoints ( ) const

Returns the number of code points in the string.

Note that this is not the same as the number of bytes.

Returns:: the number of code points in the string

Definition at line 921 of file vstring.cpp.

References ASSERT_INVARIANT.

int VString::length ( ) const

Returns the string length in bytes.

Note that this is not the same as the number of code points.

Returns:: the string length in bytes

Definition at line 931 of file vstring.cpp.

References ASSERT_INVARIANT.

void VString::truncateCodePoints ( int maxNumCodePoints )

Truncates the string to specified number of code points; if the string is already that length or less, nothing happens.

Parameters:

maxNumCodePoints the number of code points to truncate to

Definition at line 937 of file vstring.cpp.

References ASSERT_INVARIANT, and getNumCodePoints().

void VString::truncateLength ( int maxLength )

Truncates the string to specified length; if the string is already that length or less, nothing happens.

Parameters:

maxLength the length to truncate to

Definition at line 948 of file vstring.cpp.

References ASSERT_INVARIANT, and length().

bool VString::isEmpty ( ) const

Returns true if the string length is zero.

Returns:: true if the string length is zero

Definition at line 958 of file vstring.cpp.

References ASSERT_INVARIANT.

bool VString::isNotEmpty ( ) const

Returns true if the string length is non-zero.

Returns:: true if the string length is non-zero

Definition at line 964 of file vstring.cpp.

References ASSERT_INVARIANT.

VChar VString::at ( int i ) const

Returns the character at the specified index.

If the index is out of range, a VException is thrown.

Parameters:

i	the index (0 to length-1)

Returns:: the character

Definition at line 970 of file vstring.cpp.

References ASSERT_INVARIANT, and VChar::NULL_CHAR().

VChar VString::operator[] ( int i ) const

Returns the character at the specified index.

If the index is out of range, a VException is thrown.

Parameters:

i	the index (0 to length-1)

Returns:: the character

Definition at line 982 of file vstring.cpp.

References ASSERT_INVARIANT, and VChar::NULL_CHAR().

char & VString::operator[] ( int i )

Returns a reference to the char at the specified index, which can be assigned to.

If the index is out of range, a VException is thrown.

Parameters:

i	the index (0 to length-1)

Returns:: the character

Definition at line 994 of file vstring.cpp.

References ASSERT_INVARIANT.

char VString::charAt ( int i ) const

Returns the char at the specified index.

If the index is out of range, a VException is thrown.

Parameters:

i	the index (0 to length-1)

Returns:: the char

Definition at line 1004 of file vstring.cpp.

References ASSERT_INVARIANT.

VString::operator const char * ( ) const

Coerces the string to a C string, for use with APIs that take a const char* parameter.

In fact, this coercion returns the string buffer pointer.

Returns:: the char buffer pointer

Definition at line 1016 of file vstring.cpp.

References ASSERT_INVARIANT.

const char * VString::chars ( ) const

Returns the string as a C string, for use with APIs that take a const char* parameter.

The result is a const pointer, so the caller cannot modify the string. In fact, this coercion returns the string buffer pointer. This is the same as operator const char*, but is explicit. You need an explicit method like this when passing to an API that does not have sufficient type information, such as vararg calls like printf and sprintf.

Example: printf("string='%s'\n", myString->chars());

In the example above, simply passing myString would result in garbage output, because printf would not know how to treat myString other than as a pointer value.

Returns:: the char buffer pointer

Definition at line 1022 of file vstring.cpp.

References ASSERT_INVARIANT.

std::wstring VString::toUTF16 ( ) const

Returns a "wide" string built from the VString, converting from our internal UTF-8 to UTF-16 code units.

One code unit per wchar_t element.

Returns:: the wstring formed as UTF16 code units

Definition at line 1028 of file vstring.cpp.

References ASSERT_INVARIANT, and VCodePoint::toUTF16WideString().

bool VString::equalsIgnoreCase ( const VString & s ) const

Returns true if this string is equal to the specified string, ignoring case, using strcmp semantics.

Parameters:

s	the string to compare with

Returns:: true if the strings are equal, case-insensitive

Definition at line 1057 of file vstring.cpp.

References ASSERT_INVARIANT, and chars().

bool VString::equalsIgnoreCase ( const char * s ) const

Returns true if this string is equal to the specified C string, ignoring case, using strcmp semantics.

Parameters:

s	the C string to compare with

Returns:: true if the strings are equal, case-insensitive

Definition at line 1063 of file vstring.cpp.

References ASSERT_INVARIANT, and compareIgnoreCase().

int VString::compare ( const VString & s ) const

Returns the comparison value of this string and the supplied string, using strcmp semantics.

Parameters:

s	the string to compare with

Returns:: <0, 0, or >0, depending on how the strings compare

Definition at line 1069 of file vstring.cpp.

References ASSERT_INVARIANT, and chars().

int VString::compare ( const char * s ) const

Returns the comparison value of this string and the supplied C string, using strcmp semantics.

Parameters:

s	the C string to compare with

Returns:: <0, 0, or >0, depending on how the strings compare

Definition at line 1075 of file vstring.cpp.

References ASSERT_INVARIANT.

int VString::compareIgnoreCase ( const VString & s ) const

Returns the comparison value of this string and the supplied string, ignoring case, using strcmp semantics.

Parameters:

s	the string to compare with

Returns:: <0, 0, or >0, depending on how the strings compare

Definition at line 1081 of file vstring.cpp.

References ASSERT_INVARIANT, and chars().

int VString::compareIgnoreCase ( const char * s ) const

Returns the comparison value of this string and the supplied C string, ignoring case, using strcmp semantics.

Parameters:

s	the C string to compare with

Returns:: <0, 0, or >0, depending on how the strings compare

Definition at line 1087 of file vstring.cpp.

References ASSERT_INVARIANT.

bool VString::startsWith ( const VString & s ) const

Returns true if this string starts with the specified string.

Parameters:

s	the string to compare with

Returns:: true if this string starts with the specified string

Definition at line 1093 of file vstring.cpp.

References ASSERT_INVARIANT, length(), and regionMatches().

bool VString::startsWithIgnoreCase ( const VString & s ) const

Returns true if this string starts with the specified string (ignoring case).

Parameters:

s	the string to compare with

Returns:: true if this string starts with the specified string (ignoring case)

Definition at line 1099 of file vstring.cpp.

References ASSERT_INVARIANT, length(), and regionMatches().

bool VString::startsWith ( const VCodePoint & cp ) const

Returns true if this string starts with the specified code point.

Parameters:

cp	the code point to compare with

Returns:: true if this string starts with the specified code point

Definition at line 1105 of file vstring.cpp.

References ASSERT_INVARIANT, getDataBufferConst(), and VCodePoint::getUTF8Length().

bool VString::startsWith ( char c ) const

Returns true if this string starts with the specified char.

Parameters:

c	the char to compare with

Returns:: true if this string starts with the specified char

Definition at line 1115 of file vstring.cpp.

References ASSERT_INVARIANT.

bool VString::endsWith ( const VString & s ) const

Returns true if this string ends with the specified string.

Parameters:

s	the string to compare with

Returns:: true if this string ends with the specified string

Definition at line 1125 of file vstring.cpp.

References ASSERT_INVARIANT, length(), and regionMatches().

bool VString::endsWithIgnoreCase ( const VString & s ) const

Returns true if this string ends with the specified string (ignoring case).

Parameters:

s	the string to compare with

Returns:: true if this string ends with the specified string (ignoring case)

Definition at line 1131 of file vstring.cpp.

References ASSERT_INVARIANT, length(), and regionMatches().

bool VString::endsWith ( const VCodePoint & cp ) const

Returns true if this string ends with the specified code point.

Parameters:

cp	the code point to compare with

Returns:: true if this string ends with the specified code point

Definition at line 1137 of file vstring.cpp.

References ASSERT_INVARIANT, and VCodePoint::getUTF8Length().

bool VString::endsWith ( char c ) const

Returns true if this string ends with the specified char.

Parameters:

c	the char to compare with

Returns:: true if this string ends with the specified char

Definition at line 1148 of file vstring.cpp.

References ASSERT_INVARIANT.

VString::const_iterator VString::find ( const VCodePoint & cp ) const

Returns an iterator pointing to the first occurrence of the specified code point within the string.

Parameters:

cp	the code point to search for

Returns:: an iterator pointing to the found code point, or end() if not found

Definition at line 1158 of file vstring.cpp.

References ASSERT_INVARIANT.

VString::const_iterator VString::find	(	const VCodePoint &	cp,
		const VString::const_iterator &	startPosition,
		const VString::const_iterator &	endPosition
	)		const

Returns an iterator pointing to the first occurrence of the specified code point within the string, bounded by the specified start and end iterator positions.

Parameters:

cp	the code point to search for
startPosition	the start iterator position to search; begin() means search from the start of the string
endPosition	the end iterator position to search; end() means search to the end of the string

Returns:: an iterator pointing to the found code point, or end() if not found

Definition at line 1174 of file vstring.cpp.

References ASSERT_INVARIANT.

int VString::indexOf	(	char	c,
		int	fromIndex = `0`
	)		const

Returns the index of the first occurrence of the specified character.

Parameters:

c	the character to search for
fromIndex	index in this string to start the search from

Returns:: the index where the character was found, or -1 if not found

Definition at line 1198 of file vstring.cpp.

References ASSERT_INVARIANT.

int VString::indexOfIgnoreCase	(	char	c,
		int	fromIndex = `0`
	)		const

Returns the index of the first occurrence of the specified character, using a case-insensitive comparison.

Parameters:

c	the character to search for
fromIndex	index in this string to start the search from

Returns:: the index where the character was found, or -1 if not found

Definition at line 1213 of file vstring.cpp.

References ASSERT_INVARIANT, and VChar::equalsIgnoreCase().

int VString::indexOf	(	const VString &	s,
		int	fromIndex = `0`
	)		const

Returns the index of the first occurrence of the specified string.

Parameters:

s	the string to look for
fromIndex	index in this string to start the search from

Returns:: the index where the string was found, or -1 if not found

Definition at line 1228 of file vstring.cpp.

References ASSERT_INVARIANT, length(), and regionMatches().

int VString::indexOfIgnoreCase	(	const VString &	s,
		int	fromIndex = `0`
	)		const

Returns the index of the first occurrence of the specified string, using a case-insensitive comparison.

Parameters:

s	the string to look for
fromIndex	index in this string to start the search from

Returns:: the index where the string was found, or -1 if not found

Definition at line 1245 of file vstring.cpp.

References ASSERT_INVARIANT, length(), and regionMatches().

int VString::lastIndexOf	(	char	c,
		int	fromIndex = `-1`
	)		const

Returns the index of the last occurrence of the specified character.

Parameters:

c	the character to search for
fromIndex	index in this string to start the backward search from, with -1 indicating a search from the end

Returns:: the index where the character was found, or -1 if not found

Definition at line 1263 of file vstring.cpp.

References ASSERT_INVARIANT.

int VString::lastIndexOfIgnoreCase	(	char	c,
		int	fromIndex = `-1`
	)		const

Returns the index of the last occurrence of the specified character, using a case-insensitive comparison.

Parameters:

c	the character to search for
fromIndex	index in this string to start the backward search from, with -1 indicating a search from the end

Returns:: the index where the character was found, or -1 if not found

Definition at line 1280 of file vstring.cpp.

References ASSERT_INVARIANT, and VChar::equalsIgnoreCase().

int VString::lastIndexOf	(	const VString &	s,
		int	fromIndex = `-1`
	)		const

Returns the index of the last occurrence of the specified string.

Parameters:

s	the string to look for
fromIndex	index in this string to start the backward search from, with -1 indicating a search from the end

Returns:: the index where the string was found, or -1 if not found

Definition at line 1297 of file vstring.cpp.

References ASSERT_INVARIANT, length(), and regionMatches().

int VString::lastIndexOfIgnoreCase	(	const VString &	s,
		int	fromIndex = `-1`
	)		const

Returns the index of the last occurrence of the specified string, using a case-insensitive comparison.

Parameters:

s	the string to look for
fromIndex	index in this string to start the backward search from, with -1 indicating a search from the end

Returns:: the index where the string was found, or -1 if not found

Definition at line 1315 of file vstring.cpp.

References ASSERT_INVARIANT, length(), and regionMatches().

bool VString::regionMatches	(	int	thisIndex,
		const VString &	otherString,
		int	otherIndex,
		int	regionLength,
		bool	caseSensitive = `true`
	)		const

Returns true if the specified range of this string matches the specified range of the specified string.

If the characters in the ranges do not match, or if either range goes past the end of either string, then the result is false.

Parameters:

thisIndex	the start index (0 to this this->length()-1) in this string to start the match
otherString	the string to match
otherIndex	the start index (0 to other otherString.length()-1) in the other string to start the match
regionLength	the number of characters to compare
caseSensitive	true if the comparison should be case-sensitive

Returns:: true if the ranges match

Definition at line 1333 of file vstring.cpp.

References ASSERT_INVARIANT, chars(), and length().

bool VString::contains	(	char	c,
		int	fromIndex = `0`
	)		const

Returns true if the specified character exists in this string.

Parameters:

c	the character to search for
fromIndex	index in this string to start the search from

Returns:: true if the character was found

Definition at line 1358 of file vstring.cpp.

References ASSERT_INVARIANT, and indexOf().

bool VString::containsIgnoreCase	(	char	c,
		int	fromIndex = `0`
	)		const

Returns true if the specified character exists in this string, using a case-insensitive match.

Parameters:

c	the character to search for
fromIndex	index in this string to start the search from

Returns:: true if the character was found

Definition at line 1364 of file vstring.cpp.

References ASSERT_INVARIANT, and indexOfIgnoreCase().

bool VString::contains	(	const VString &	s,
		int	fromIndex = `0`
	)		const

Returns true if the specified string exists in this string.

Parameters:

s	the string to look for
fromIndex	index in this string to start the search from

Returns:: true if the string was found

Definition at line 1370 of file vstring.cpp.

References ASSERT_INVARIANT, and indexOf().

bool VString::containsIgnoreCase	(	const VString &	s,
		int	fromIndex = `0`
	)		const

Returns true if the specified string exists in this string, using a case-insensitive match.

Parameters:

s	the string to look for
fromIndex	index in this string to start the search from

Returns:: true if the string was found

Definition at line 1376 of file vstring.cpp.

References ASSERT_INVARIANT, and indexOfIgnoreCase().

int VString::replace	(	const VString &	searchString,
		const VString &	replacementString,
		bool	caseSensitiveSearch = `true`
	)

Replaces every occurrence of the specified search string with the supplied replacement string.

Returns the number of replacements performed, which may be zero.

Parameters:

searchString	the string to search for
replacementString	the string to replace the search string with
caseSensitiveSearch	true if the search match should be case-sensitive

Returns:: the number of replaced occurrences

Definition at line 1382 of file vstring.cpp.

References ASSERT_INVARIANT, chars(), indexOf(), indexOfIgnoreCase(), and length().

int VString::replace	(	const VCodePoint &	searchChar,
		const VCodePoint &	replacementChar,
		bool	caseSensitiveSearch = `true`
	)

Replaces every occurrence of the specified search string with the supplied replacement string.

Returns the number of replacements performed, which may be zero.

Parameters:

searchChar	the character to search for
replacementChar	the character to replace the search character with
caseSensitiveSearch	true if the search match should be case-sensitive

Returns:: the number of replaced occurrences

Definition at line 1447 of file vstring.cpp.

References ASSERT_INVARIANT, replace(), and VCodePoint::toString().

int VString::parseInt ( ) const

Parses the string as an integer.

The range must fall within the signed integer range (typically 32 bits, but possibly more, and theoretically less). The allowed format is ([+|-][0*][0-9]). That is, a leading plus or minus sign is allowed, as are leading zeroes, followed by digits. If the string is empty, the value is zero. If the string contains an invalid character sequence or evaluates to an out-of-range integer, VRangeException is thrown. This function is similar in purpose to atoi().

Definition at line 1479 of file vstring.cpp.

References ASSERT_INVARIANT.

Vs64 VString::parseS64 ( ) const

Parses the string as a Vs64 integer.

The range must fall within the 64-bit signed integer range. The allowed format is ([+|-][0*][0-9]). That is, a leading plus or minus sign is allowed, as are leading zeroes, followed by digits. If the string is empty, the value is zero. If the string contains an invalid character sequence, VRangeException is thrown. This function is similar in purpose to atoi().

Definition at line 1504 of file vstring.cpp.

References ASSERT_INVARIANT.

Vu64 VString::parseU64 ( ) const

Parses the string as a Vu64 integer.

The range must fall within the 64-bit unsigned integer range. The allowed format is ([+][0*][0-9]). That is, a leading plus sign is allowed, as are leading zeroes, followed by digits. If the string is empty, the value is zero. If the string contains an invalid character sequence, VRangeException is thrown. This function is similar in purpose to atoi().

Definition at line 1512 of file vstring.cpp.

References ASSERT_INVARIANT.

VDouble VString::parseDouble ( ) const

Parses the string as a VDouble integer.

The string must conform to the specification of strtod() given by ISO C and POSIX IEEE 1003.1. In the case of an illegal string, VRangeException is thrown. This function is similar in purpose to (and my rely on) sscanf() using the "%lf" format. An empty string is deemed to have the value 0.0.

Definition at line 1520 of file vstring.cpp.

References ASSERT_INVARIANT.

void VString::set	(	int	i,
		const VChar &	c
	)

Sets the character at the specified index to the specified value.

If the index is out of range, a VException is thrown.

Parameters:

i	the index (0 to length-1)
c	the new character value

Definition at line 1536 of file vstring.cpp.

References ASSERT_INVARIANT, and VChar::charValue().

void VString::getSubstring	(	VString &	toString,
		int	startIndex,
		int	endIndex = `-1`
	)		const

Copies a substring of this string to a target string.

The start index is inclusive, that is it is the index of the first character copied; zero means to copy from the start of the string. The stop index is exclusive, that is it is one past the index of the last character copied; the default value of -1 means to copy all the way to the end of the string. Thus with the defaults you get the whole string.

Parameters:

toString	the string to copy the specified substring into
startIndex	index of the first char to copy, inclusive
endIndex	index of the last char to copy, exclusive (end-start is the length)

Definition at line 1548 of file vstring.cpp.

References ASSERT_INVARIANT, copyFromBuffer(), length(), V_MAX, and V_MIN.

void VString::substringInPlace	(	int	startIndex,
		int	endIndex = `-1`
	)

Makes a substring of this string in place (contrast with getSubstring(), which puts the substring into a different object).

The start index is inclusive, that is it is the index of the first character taken; zero means the start of the string is unchanged. The stop index is exclusive, that is it is one past the index of the last character copied; the default value of -1 means the end of the string is unchanged, other than the fact that the string may be shortened. Thus with the defaults the string is not changed at all. This function is guaranteed not to fail or reallocate memory, because it only shrinks the string and thus at most just moves bytes towards the start of the buffer and updates the length field.

Parameters:

startIndex	index of the first char to copy, inclusive
endIndex	index of the last char to copy, exclusive (end-start is the length)

Definition at line 1572 of file vstring.cpp.

References ASSERT_INVARIANT, length(), V_MAX, and V_MIN.

void VString::split	(	VStringVector &	result,
		const VCodePoint &	delimiter,
		int	limit = `0`,
		bool	stripTrailingEmpties = `true`
	)		const

Splits the string into pieces using a specified delimiter character.

Trailing empty strings are omitted in the output. The intent is to behave similarly to Java String.split().

Parameters:

result	this string vector is cleared and then fill with the result
delimiter	the character that delimits the split points
limit	if non-zero, the max number of result items; if the string has more elements than that, the trailing part of the string is collapsed into one element (including delimiters)
stripTrailingEmpties	if true, any empty strings at the end of the resulting list are discarded (this is the Java String.split() behavior)

Definition at line 1597 of file vstring.cpp.

References ASSERT_INVARIANT, EMPTY(), getSubstring(), and isNotEmpty().

VStringVector VString::split	(	const VCodePoint &	delimiter,
		int	limit = `0`,
		bool	stripTrailingEmpties = `true`
	)		const

Convenience version of split() that returns the vector.

Will likely incur copy overhead compared to the non-returning version, so use the other version in time-critical code.

Parameters:

delimiter	the character that delimits the split points
limit	if non-zero, the max number of result items; if the string has more elements than that, the trailing part of the string is collapsed into one element (including delimiters)
stripTrailingEmpties	if true, any empty strings at the end of the resulting list are discarded (this is the Java String.split() behavior)

Returns:: a vector of split result strings

Definition at line 1633 of file vstring.cpp.

References ASSERT_INVARIANT, and split().

void VString::trim ( )

Strips leading and trailing whitespace from the string.

Whitespace as implemented here is defined as ASCII byte values <= 0x20 as well as 0x7F.

Definition at line 1641 of file vstring.cpp.

References ASSERT_INVARIANT, and NULL.

void VString::copyToBuffer	(	char *	toBuffer,
		int	bufferSize
	)		const

Copies the string's chars to the specified buffer, plus a null terminator byte; the number of bytes copied (including null terminator) is limited to the specified buffer size.

That is, if bufferSize is N, and this string's length is greater than (N-1), some characters will not be copied. The target buffer always gets null terminated.

Parameters:

toBuffer	the char buffer to copy into
bufferSize	the size of the target buffer; limits size of resulting copied string

Definition at line 1697 of file vstring.cpp.

References ASSERT_INVARIANT, NULL, and VCHAR_NULL_TERMINATOR.

void VString::copyFromBuffer	(	const char *	fromBuffer,
		int	startIndex,
		int	endIndex
	)

Sets the string by copying a number of characters from the source buffer.

Parameters:

fromBuffer	the char buffer to copy from
startIndex	the offset in the buffer to start from, inclusive (0 starts at first character)
endIndex	the offset in the buffer to stop at, exclusive (end-start is the length, thus strlen(fromBuffer) will copy to the last character).

Definition at line 1714 of file vstring.cpp.

References ASSERT_INVARIANT, postflight(), and preflight().

void VString::copyFromCString ( const char * fromBuffer )

Sets the string by copying a C string from the source buffer.

Same as copyFromBuffer(b, 0, strlen(b));

Parameters:

fromBuffer the char buffer to copy from

Definition at line 1733 of file vstring.cpp.

References copyFromBuffer().

void VString::copyToPascalString ( char * pascalBuffer ) const

Copies the string's chars to the specified Pascal string buffer, using the Pascal string format (length byte plus data).

The caller is responsible for making sure that the buffer is big enough to hold 1 + this->length() bytes, up to a maximum of 256 total bytes.

Parameters:

pascalBuffer the Pascal string buffer to copy into

Definition at line 1737 of file vstring.cpp.

References ASSERT_INVARIANT, and V_MIN.

void VString::copyFromPascalString ( const char * pascalBuffer )

Sets the string by copying a Pascal string from the source buffer.

Parameters:

pascalBuffer the Pascal string buffer to copy from

Definition at line 1750 of file vstring.cpp.

References ASSERT_INVARIANT, postflight(), and preflight().

void VString::setFourCharacterCode ( Vu32 fourCharacterCode )

Sets the string from a "four character code".

The input is simply a 32-bit integer whose 4 bytes are treated as ASCII characters (most significant byte becomes the first character of the string, etc.). An exception is thrown if any of the input bytes is zero, since that would cause a null terminator byte to be part of the string's character data.

Definition at line 1762 of file vstring.cpp.

References ASSERT_INVARIANT, and copyFromBuffer().

Vu32 VString::getFourCharacterCode ( ) const

Returns the "four character code" represented by the string.

The first four characters of the string are used to compose a 32-bit integer (the first character of the string becomes the most significant byte, etc.). If the string has fewer than 4 characters, the result is padded out to 4 characters with spaces (0x20).

Definition at line 1782 of file vstring.cpp.

References ASSERT_INVARIANT.

void VString::preflight ( int stringLength )

Ensures that the buffer is big enough to hold the specified string length.

If preflight needs to reallocate the buffer and is unable to do so, a VException is thrown.

Parameters:

stringLength the length of the string that will need to fit in the buffer

Definition at line 1808 of file vstring.cpp.

References ASSERT_INVARIANT.

void VString::preflightWithSimulatedFailure ( )

Simulates what happens if preflight() fails to allocate the buffer due to lack of memory.

This is used by the unit test code for platforms that we have not been able to get to fail by passing a huge buffer size to preflight().

Definition at line 1891 of file vstring.cpp.

References ASSERT_INVARIANT.

char * VString::buffer ( )

Returns the string's char buffer pointer.

This method should only be used in special circumstances by code that is also calling preflight() and postflight() to manage the buffer. The pointer is non-const, for the purpose of allowing the caller to manipulate the buffer under the preflight/postflight rules.

Returns:: the buffer pointer

Definition at line 1897 of file vstring.cpp.

References ASSERT_INVARIANT.

Vu8 * VString::getDataBuffer ( )

Returns the string's buffer pointer as a Vu8 pointer, which is a type directly compatible with the various stream data reading APIs.

So this method lets the caller avoid a reinterpret_cast that is often otherwise needed when doing stream reads into the string data buffer. This method should only be used in special circumstances by code that is also calling preflight() and postflight() to manage the buffer. The returned pointer is non-const, for the purpose of allowing the caller to manipulate the buffer under the preflight/postflight rules.

Returns:: the buffer pointer

Definition at line 1903 of file vstring.cpp.

References ASSERT_INVARIANT.

const Vu8 * VString::getDataBufferConst ( ) const

Returns the string's buffer pointer as a const Vu8 pointer, which is a type directly compatible with the various stream data writing APIs.

So this method lets the caller avoid a reinterpret_cast that is often otherwise needed when doing stream writes from the string data buffer.

Returns:: the buffer pointer

Definition at line 1909 of file vstring.cpp.

References ASSERT_INVARIANT.

char * VString::orphanDataBuffer ( )

Transfers ownership of the string's buffer to the caller and sets the string to empty (with no buffer).

This is a way of extracting a char buffer from a VString such that the VString can be destructed and the caller retains the buffer. If the VString is an empty string such that it doesn't have a heap buffer, this function will create and return a buffer containing a null-terminated C string, so you do not need to check for a NULL function result; however, it is more efficient if you avoid calling this function when the VString is an empty string.

Returns:: a buffer pointer, which is now owned by the caller and no longer referenced by the VString object (which is now an "empty" string)

Definition at line 1915 of file vstring.cpp.

References ASSERT_INVARIANT, and NULL.

void VString::postflight ( int stringLength )

Syncs the internal data to the specified length, setting the length and writing a null terminator into the buffer.

Again, this should only be used in special circumstances by callers who are using preflight() and buffer() to do something with the buffer that cannot be done via the normal public API.

Definition at line 1946 of file vstring.cpp.

References ASSERT_INVARIANT.

Friends And Related Function Documentation

bool operator==	(	const VString &	lhs,
		const VString &	rhs
	)		`[friend]`

Compares lhs and rhs for equality.

Parameters:

lhs	a string
rhs	a string

Returns:: true if lhs and rhs are equal according to strcmp()

Definition at line 1408 of file vstring.h.

bool operator==	(	const VString &	lhs,
		const char *	rhs
	)		`[friend]`

Compares lhs and rhs for equality.

Parameters:

lhs	a string
rhs	a C string

Returns:: true if lhs and rhs are equal according to strcmp()

Definition at line 1409 of file vstring.h.

bool operator==	(	const char *	lhs,
		const VString &	rhs
	)		`[friend]`

Compares lhs and rhs for equality.

Parameters:

lhs	a C string
rhs	a string

Returns:: true if lhs and rhs are equal according to strcmp()

Definition at line 1410 of file vstring.h.

bool operator==	(	const VString &	lhs,
		char	rhs
	)		`[friend]`

Compares s and c for equality.

Parameters:

lhs	a string
rhs	a char

Returns:: true if lhs is one character in length, the character being rhs

Definition at line 1411 of file vstring.h.

bool operator!=	(	const VString &	lhs,
		const VString &	rhs
	)		`[friend]`

Compares lhs and rhs for inequality.

Parameters:

lhs	a string
rhs	a string

Returns:: true if lhs and rhs are not equal according to strcmp()

Definition at line 1413 of file vstring.h.

bool operator!=	(	const VString &	lhs,
		const char *	rhs
	)		`[friend]`

Compares lhs and rhs for inequality.

Parameters:

lhs	a string
rhs	a C string

Returns:: true if lhs and rhs are not equal according to strcmp()

Definition at line 1414 of file vstring.h.

bool operator!=	(	const char *	lhs,
		const VString &	rhs
	)		`[friend]`

Compares lhs and rhs for inequality.

Parameters:

lhs	a C string
rhs	a string

Returns:: true if lhs and rhs are not equal according to strcmp()

Definition at line 1415 of file vstring.h.

bool operator!=	(	const VString &	lhs,
		char	rhs
	)		`[friend]`

Compares lhs and rhs for inequality.

Parameters:

lhs	a string
rhs	a char

Returns:: true if lhs is NOT one character in length, or if its sole character is not rhs

Definition at line 1416 of file vstring.h.

bool operator<	(	const VString &	lhs,
		const VString &	rhs
	)		`[friend]`

Compares lhs and rhs.

Parameters:

lhs	a string
rhs	a string

Returns:: true if lhs < rhs according to strcmp()

Definition at line 1418 of file vstring.h.

bool operator<	(	const VString &	lhs,
		const char *	rhs
	)		`[friend]`

Compares lhs and rhs.

Parameters:

lhs	a string
rhs	a C string

Returns:: true if lhs < rhs according to strcmp()

Definition at line 1419 of file vstring.h.

bool operator<	(	const char *	lhs,
		const VString &	rhs
	)		`[friend]`

Compares lhs and rhs.

Parameters:

lhs	a C string
rhs	a string

Returns:: true if lhs < rhs according to strcmp()

Definition at line 1420 of file vstring.h.

bool operator<=	(	const VString &	lhs,
		const VString &	rhs
	)		`[friend]`

Compares lhs and rhs.

Parameters:

lhs	a string
rhs	a string

Returns:: true if lhs <= rhs according to strcmp()

Definition at line 1422 of file vstring.h.

bool operator<=	(	const VString &	lhs,
		const char *	rhs
	)		`[friend]`

Compares lhs and rhs.

Parameters:

lhs	a string
rhs	a C string

Returns:: true if lhs <= rhs according to strcmp()

Definition at line 1423 of file vstring.h.

bool operator<=	(	const char *	lhs,
		const VString &	rhs
	)		`[friend]`

Compares lhs and rhs.

Parameters:

lhs	a C string
rhs	a string

Returns:: true if lhs <= rhs according to strcmp()

Definition at line 1424 of file vstring.h.

bool operator>=	(	const VString &	lhs,
		const VString &	rhs
	)		`[friend]`

Compares lhs and rhs.

Parameters:

lhs	a string
rhs	a string

Returns:: true if lhs >= rhs according to strcmp()

Definition at line 1426 of file vstring.h.

bool operator>=	(	const VString &	lhs,
		const char *	rhs
	)		`[friend]`

Compares lhs and rhs.

Parameters:

lhs	a string
rhs	a C string

Returns:: true if lhs >= rhs according to strcmp()

Definition at line 1427 of file vstring.h.

bool operator>=	(	const char *	lhs,
		const VString &	rhs
	)		`[friend]`

Compares lhs and rhs.

Parameters:

lhs	a C string
rhs	a string

Returns:: true if lhs >= rhs according to strcmp()

Definition at line 1428 of file vstring.h.

bool operator>	(	const VString &	lhs,
		const VString &	rhs
	)		`[friend]`

Compares lhs and rhs.

Parameters:

lhs	a string
rhs	a string

Returns:: true if lhs > rhs according to strcmp()

Definition at line 1430 of file vstring.h.

bool operator>	(	const VString &	lhs,
		const char *	rhs
	)		`[friend]`

Compares lhs and rhs.

Parameters:

lhs	a string
rhs	a C string

Returns:: true if lhs > rhs according to strcmp()

Definition at line 1431 of file vstring.h.

bool operator>	(	const char *	lhs,
		const VString &	rhs
	)		`[friend]`

Compares lhs and rhs.

Parameters:

lhs	a C string
rhs	a string

Returns:: true if lhs > rhs according to strcmp()

Definition at line 1432 of file vstring.h.

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

Public Types

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation