MCString Class Reference

Reference counted string. More...

#include <mcllib/MCString.h>

Inheritance diagram for MCString:

List of all members.

Public Types
typedef IMPLTYPE	const_iterator
	const iterator type.
enum	EStripWsWhere { MCWSHEAD, MCWSTAIL, MCWSBOTH }
	Enum describing where to strip white space from string. More...
typedef const char *	IMPLTYPE
	Character type.
typedef unsigned long	size_t
	Size type.
Public Member Functions
const_iterator	begin () const
	Obtain an interator to the beginning of the string.
IMPLTYPE	c_str () const
	Obtain a pointer to the beginning of the string (as a C-style null terminated string).
int	cmp (const MCString &mcs, bool ignoreCase=false) const
	Compare this string with another string.
const_iterator	end () const
	Obtain an interator to the end of the string.
void	erase ()
	Erase the contents of the string.
int	find (char c, int start=0) const
	Find the first occurence of a character in a string.
unsigned long	getCount () const
	debug for getting ref count
size_t	length () const
	Obtain the length of the string.
	MCString (IMPLTYPE pStr, size_t length)
	Construct a string from a character pointer and a length.
	MCString (IMPLTYPE pStr)
	Construct a string from a character pointer.
	MCString ()
	Construct an empty string.
	operator IMPLTYPE () const
	Obtain a pointer to the beginning of the string (as a C-style null terminated string).
bool	operator!= (const MCString &mcs) const
	Test two strings for inequality.
bool	operator< (const MCString &mcs) const
	Test if this string is less than another string.
bool	operator== (const MCString &mcs) const
	Test two strings for equality.
int	rfind (char c, int start=0) const
	Find the last occurence of a character in a string.
size_t	size () const
	Obtain the length of the string.
void	stripws (EStripWsWhere where=MCWSBOTH)
	Strip white space from one or both ends of a string.
MCString	substr (int start, int length=0) const
	Obtain a substring of the string.
	~MCString ()
	Destroy string.

---

Detailed Description

Reference counted string.

This string type forms the basis for all contained string data (e.g. in exceptions), where leak-free reference counting is needed. It is null terminated to make c_str, begin/end etc. easier to use. It uses reference counting internally so can potentially reduce memory allocation. Additionally, it handles empty strings without allocating any memory on the heap (only the stack memory used for the MCString object).

---

Member Typedef Documentation

typedef IMPLTYPE const_iterator

const iterator type. Note that only constant iterators are provided because the string data must not be changed via the iterator.

---

Member Enumeration Documentation

enum EStripWsWhere

Enum describing where to strip white space from string. Enumeration values: MCWSHEAD  Strip white space from the head of the string. MCWSTAIL  Strip white space from the tail of the string. MCWSBOTH  Strip white space from both the head and tail of the string.

---

Constructor & Destructor Documentation

MCString (   )

Construct an empty string. No (extra) memory is allocated.

~MCString (   )

Destroy string. This reduces the reference count on the contained data by one, freeing it if no references remain.

MCString (  IMPLTYPE  pStr  )

Construct a string from a character pointer. Parameters: pStr  a C-style null terminated character string or NULL. If pStr is not NULL then all characters up to the first null terminator character are copied to the string. If pStr is NULL or points to a character string of zero length, an empty string is constructed (see MCString()).

MCString (  IMPLTYPE  pStr, size_t  length )

Construct a string from a character pointer and a length. Parameters: pStr  points to a character string. If pStr is NULL an empty string is constructed (see MCString()). length  the length of the character string. length characters are copied from pStr, including any null characters. If length is zero an empty string is constructed (see MCString()).

---

Member Function Documentation

const_iterator begin (   )  const

Obtain an interator to the beginning of the string. Returns: a constant iterator to beginning of string

IMPLTYPE c_str (   )  const

Obtain a pointer to the beginning of the string (as a C-style null terminated string). If the string was constructed using the MCString(str, len) the returned pointer may include a null terminator before the end of the string specified by len. Convenience function for compatibility with std::string Returns: a pointer to the beginning of the string

int cmp (  const MCString &  mcs, bool  ignoreCase = false )  const

Compare this string with another string. Operates like strcmp(). Parameters: mcs  the string to compare against ignoreCase  if true case insensitive comparison is performed Returns: an integer indicating if this string is less then, equal to or greater than mcs. A return of zero indicates this == mcs. A negative number indicates this < mcs. A positive number indicates this > mcs.

const_iterator end (   )  const

Obtain an interator to the end of the string. Returns: a constant iterator to end of string

void erase (   )

Erase the contents of the string. Any other references to the same contained string are unaffected. This effectively reduces the reference count on the contained data by one, freeing it if no references remain.

int find (  char  c, int  start = 0 )  const

Find the first occurence of a character in a string. Parameters: c  the character to search for start  the position to start the search from. The search proceeds forwards from this position to the end of the string. Returns: the position in the string at which c was found. If c does not exist in the string then -1 is returned.

size_t length (   )  const

Obtain the length of the string. Returns: the length of the string

operator IMPLTYPE (   )  const

Obtain a pointer to the beginning of the string (as a C-style null terminated string). If the string was constructed using the MCString(str, len) the returned pointer may include a null terminator before the end of the string specified by len. Returns: a pointer to the beginning of the string

bool operator!= (  const MCString &  mcs  )  const

Test two strings for inequality. Parameters: mcs  the string to compare against Returns: true if this != mcs.

bool operator< (  const MCString &  mcs  )  const

Test if this string is less than another string. This is useful for sorting and to allow strings to be used in STL containers. Parameters: mcs  the string to compare against Returns: true if this < mcs (lexically).

bool operator== (  const MCString &  mcs  )  const

Test two strings for equality. Returns: true if this == mcs.

int rfind (  char  c, int  start = 0 )  const

Find the last occurence of a character in a string. Parameters: c  the character to search for start  the position to start the search from. The search proceeds backwards from this position to the beginning of the string. Returns: the position in the string at which c was found. If c does not exist in the string then -1 is returned.

size_t size (   )  const

Obtain the length of the string. This is provided for std::string compatibility Returns: the length of the string

void stripws (  EStripWsWhere  where = MCWSBOTH  )

Strip white space from one or both ends of a string. If the string has no white space (according to the value of where) then the string is unaffected. If the string has no non-white space characters, the effect is the same as calling erase() on the string (the string is erased). If the string is modified or erased, any references to the original string are unaffected and this MCString is the only reference to the new string. Parameters: where  determines which end to strip white space from. It can be the start (head), the end (tail) or both ends.

MCString substr (  int  start, int  length = 0 )  const

Obtain a substring of the string. Parameters: start  is the starting position (from zero). Negative values for start are relative to the end of the string. length  is the length of the required substring. Negative values for length mean relative to the length of the string. A zero value for length means to the end of the string. Returns: a new string containing the required data

---