BALL::Substring Class Reference
[String]

A substring class. More...

#include <string.h>

List of all members.

Classes
class	InvalidSubstring
	Exception thrown if an invalid substring is accessed. More...
class	UnboundSubstring
	Exception thrown if an unbound substring is accessed. More...
Public Member Functions
Constructors and Destructors
	Substring ()
	Default constructor.
	Substring (const Substring &substring, bool deep=true)
	Copy constructor.
	Substring (const String &string, Index from=0, Size len=String::EndPos) throw (Exception::IndexUnderflow, Exception::IndexOverflow)
	Create a substring from a string and two indices.
virtual	~Substring ()
	Destructor.
void	destroy ()
	Clear the substrings contents.
virtual void	clear ()
	Clear the substrings contents.
Converters
	operator String () const throw (Substring::UnboundSubstring)
	Convert a substring to a string.
String	toString () const throw (Substring::UnboundSubstring)
	Convert a substring to a string.
Binding and Unbinding Substrings
Substring &	bind (const String &string, Index from=0, Size len=String::EndPos) throw (Exception::IndexUnderflow, Exception::IndexOverflow)
	Bind the substring to a string.
Substring &	bind (const Substring &substring, Index from=0, Size len=String::EndPos) throw (Exception::IndexUnderflow, Exception::IndexOverflow)
	Bind the substring to the same string another substring is bound to.
void	unbind ()
	unbinds the substring from the string it is bound to
String *	getBoundString ()
	Return a pointer to the bound String.
const String *	getBoundString () const
	Retunrs a const pointer to the bound String.
Assignment
void	set (const String &string) throw (Substring::UnboundSubstring)
	Sets the substring to a certain string.
void	set (const Substring &s) throw (Substring::UnboundSubstring)
	Copies a substring from another substring.
void	set (const char *char_ptr, Size size=String::EndPos) throw (Substring::UnboundSubstring, Exception::NullPointer, Exception::SizeUnderflow)
	Assigns a substring from a char pointer.
const Substring &	operator= (const String &string) throw (Substring::UnboundSubstring)
	String assignment operator.
const Substring &	operator= (const Substring &substring) throw (Substring::UnboundSubstring)
	Substring assignment operator.
const Substring &	operator= (const char *char_ptr) throw (Substring::UnboundSubstring, Exception::NullPointer)
	char pointer assignment operator
Accessors and Mutators
char *	c_str () throw (Substring::UnboundSubstring)
	Return a pointer to the substring's contents.
const char *	c_str () const throw (Substring::UnboundSubstring)
	Return a const pointer to the substring's contents.
Index	getFirstIndex () const throw (Substring::UnboundSubstring)
	Return the first index of the substring.
Index	getLastIndex () const throw (Substring::UnboundSubstring)
	Return the last index of the substring This means the end point in the bound string.
Size	size () const
	Return the substring size.
char &	operator[] (Index index) throw (Substring::UnboundSubstring, Exception::IndexUnderflow, Exception::IndexOverflow)
	Mutable random access to a character of the substring.
char	operator[] (Index index) const throw (Substring::UnboundSubstring, Exception::IndexUnderflow, Exception::IndexOverflow)
	Random access to a character of the substring (const method).
Substring &	toLower () throw (Substring::UnboundSubstring)
	Converts the substring to lower case characters.
Substring &	toUpper () throw (Substring::UnboundSubstring)
	Converts the substring to lower case characters.
Predicates
bool	isBound () const
	Return true, if the substring is bound to a String.
bool	isEmpty () const
	Return true, if the substring is empty or unbound.
Debugging and Diagnostics
bool	isValid () const
	Return true, if the string is bound to a string and its indices are valid.
void	dump (std::ostream &s=std::cout, Size depth=0) const throw (Substring::UnboundSubstring)
	Dumps the substring object (including the values of its private members).
Protected Member Functions
void	validateRange_ (Index &from, Size &len) const throw (Exception::IndexUnderflow, Exception::IndexOverflow)
Friends
class	String
Stream I/O
BALL_EXPORT friend std::ostream &	operator<< (std::ostream &s, const Substring &substring)
	Writes the substring to a stream.
Comparison Operators
BALL_EXPORT friend bool	operator== (const String &string, const Substring &substring) throw (Substring::UnboundSubstring)
	Return true, if the contents of the substring and the string are equal.
BALL_EXPORT friend bool	operator!= (const String &string, const Substring &substring) throw (Substring::UnboundSubstring)
	Return true, if the contents of the substring and the string are not equal.
bool	operator== (const Substring &substring) const throw (Substring::UnboundSubstring)
	returns true, if the contents of the two substrings are equal
bool	operator!= (const Substring &substring) const throw (Substring::UnboundSubstring)
	Return true, if the contents of the two substrings are not equal.
bool	operator== (const String &string) const throw (Substring::UnboundSubstring)
	Return true, if the contents of the substring and the string are equal.
bool	operator!= (const String &string) const throw (Substring::UnboundSubstring)
	Return true, if the contents of the substring and the string are not equal.
bool	operator== (const char *char_ptr) const throw (Substring::UnboundSubstring, Exception::NullPointer)
	Return true, if the contents of the substring are equal to the contents of the C-string.
bool	operator!= (const char *char_ptr) const throw (Substring::UnboundSubstring, Exception::NullPointer)
	Return true, if the contents of the substring are not equal to the contents of the C-string.
bool	operator== (char c) const throw (Substring::UnboundSubstring)
	Return true, if the substring has length 1 and contains the given char.
bool	operator!= (char c) const throw (Substring::UnboundSubstring)
	Return true, if the substring is differnet from the given char.

---

Detailed Description

A substring class.

The Substring class represents an efficient way to deal with substrings of String . Each Substring is bound to an instance of String and is defined by a start and end index. It can be used like a String (with several restrictions) but only affects the given range of the string it is bount to.

---

Constructor & Destructor Documentation

BALL::Substring::Substring

(

)

Default constructor.

Create an empty string.

BALL::Substring::Substring	(	const Substring &	substring,
		bool	deep = true
	)

Copy constructor.

Create a substring from another substring.

Parameters:

	substring	the substring to be copied
	deep	ignored

BALL::Substring::Substring	(	const String &	string,
		Index	from = 0,
		Size	len = String::EndPos
	)			throw (Exception::IndexUnderflow, Exception::IndexOverflow)

Create a substring from a string and two indices.

Parameters:

	string	the string the substring is bound to.
	from	the start index of the substring
	len	the length of the substring (default EndPos: to the end of the string)

virtual BALL::Substring::~Substring

(

)

[virtual]

Destructor.

Destruct the substring.

---

Member Function Documentation

Substring& BALL::Substring::bind	(	const Substring &	substring,
		Index	from = 0,
		Size	len = String::EndPos
	)			throw (Exception::IndexUnderflow, Exception::IndexOverflow)

Bind the substring to the same string another substring is bound to.

Parameters:

substring

the substring that is bound to a string

Substring& BALL::Substring::bind	(	const String &	string,
		Index	from = 0,
		Size	len = String::EndPos
	)			throw (Exception::IndexUnderflow, Exception::IndexOverflow)

Bind the substring to a string.

Parameters:

	string	the string to bind to
	from	the start position in the string (default is the beginning of the string)
	len	the substring's length (default is to the end of the string)

virtual void BALL::Substring::clear

(

)

[virtual]

Clear the substrings contents.

Unbind the substring from its string and set the start and the end position to 0.

void BALL::Substring::destroy

(

)

Clear the substrings contents.

Unbind the substring from its string and set the start and the end position to 0.

Index BALL::Substring::getFirstIndex

(

)

const throw (Substring::UnboundSubstring)

Return the first index of the substring.

This means the starting point in the bound string.

bool BALL::Substring::isValid

(

)

const

Return true, if the string is bound to a string and its indices are valid.

Valid indices means that the first index is not greater than the last index, both indices are non-negative and lesser than the size of the bound string.

BALL::Substring::operator String

(

)

const throw (Substring::UnboundSubstring)

Convert a substring to a string.

Return a copy of the substring's contents.

String BALL::Substring::toString

(

)

const throw (Substring::UnboundSubstring)

Convert a substring to a string.

Return a copy of the substring's contents.