String Class Reference

This is a generic and portable string class. Generic string class. More...

#include <string.h>

Inheritance diagram for String:

List of all members.

Public Types
typedef unsigned	size_type
Public Member Functions
	String ()
	Construct an empty string.
	String (const String &original)
	Copy constructor.
	String (const char *str)
	Create a string from a cstring.
	String (const String &str, unsigned offset, unsigned len=npos)
	Create a new string from a subset of another string.
	String (unsigned count, const char *str)
	Create a string of a known size, and optionally fill with content.
	String (unsigned count, char fill= ' ')
	Fill a new string with character data.
virtual	~String ()
	Destroy the string...
const char *	getIndex (unsigned index) const
	Get a string pointer to string content based on an indexed offset.
char *	getText (void) const
	Get the text of a string.
const unsigned	getLength (void) const
	Get the assigned length of string.
const unsigned	getSize (void) const
	Get the allocation size of the string variable.
bool	isEmpty (void) const
	Return true if string is empty.
void	resize (unsigned size)
	Re-allocate buffer space for string.
void	clear (void)
	Clear the contents of the entire string.
char	at (int offset) const
	Return a character at a known offset.
unsigned	count (const String &s, unsigned offset=0) const
	Count the number of occurences of a specific string within our string.
unsigned	count (const char *s, unsigned offset=0, unsigned len=0) const
	Count the number of occurrences of a specific text pattern within our string.
String	token (const char *delim="\t\n\r", unsigned offset=0)
	Extract a new string as a token from the current string.
unsigned	find (const String &s, unsigned offset=0, unsigned instance=1) const
	Find the index to the nth instance of a substring in our string.
unsigned	rfind (const String &s, unsigned offset=0) const
	Find last occurence of a substring in our string.
unsigned	find (const char *s, unsigned offset=0, unsigned len=0, unsigned count=1) const
	Find the index to the nth instance of text in our string.
unsigned	rfind (const char *s, unsigned offset=0, unsigned len=0) const
	Find last occurence of a text in our string.
void	trim (const char *cs)
	Trim trailing characters from a string.
void	chop (const char *cs)
	Chop leading characters from a string.
void	strip (const char *cs)
	Strip lead and trailing characters from a string.
void	chop (unsigned count)
	Chop n leading characters from a string.
void	trim (unsigned count)
	Trim n trailing characters from a string.
void	erase (unsigned start, unsigned len=npos)
	Erase a portion of string.
void	insert (unsigned start, const char *text, unsigned len=0)
	Insert text into a string.
void	insert (unsigned start, const String &str)
	Insert other string into our string.
void	replace (unsigned start, unsigned len, const char *text, unsigned count=0)
	Replace text at a specific position in the string with new text.
void	replace (unsigned start, unsigned len, const String &s)
	Replace text at a specific position in the string with new string,.
unsigned	find (unsigned instance, const char *text, unsigned offset=0, unsigned len=0) const
	A more convenient version of find for nth occurences, by putting the instance first.
unsigned	find (unsigned instance, const String &s, unsigned offset=0) const
	A more convenient version of find for nth occurences, by putting the instance first.
String	substr (unsigned start, unsigned len) const
	Return a new string that contains a specific substring of the current string.
const char *	index (unsigned idx) const
	Return an indexed string based on the index, such as from a find.
void	compact (void)
	Reduce the size of the string allocation to the minimum needed based on the current effective length.
char *	c_str (void) const
	Old ANSI C++ compatible string pointer extraction.
	operator char * () const
	Get our string data through dereference operator.
bool	operator! (void) const
	Logical test for string empty.
char *	text (void) const
	Alternate get text method.
char *	data (void) const
	Alternate get text method.
unsigned	length (void) const
	Get length as if null terminated string.
unsigned	size (void) const
	Get actual length of string data.
unsigned	capacity (void) const
	Get space allocated to hold current string.
bool	empty (void) const
	Return true if string is empty.
void	append (const char *str, unsigned count=0)
	Append text to the end of the current string.
void	append (const char *str, unsigned offset, unsigned count)
	Append text into the current string.
void	add (char c)
	Add a character to the end of a string.
void	append (const String &str)
	Append string to the end of the current string.
const char	operator[] (unsigned index) const
	Extract a character by array indexing.
void	operator= (const String &str)
	Assign our string from another string.
const char *	operator= (const char *str)
	Assign our string for c string.
String &	operator+= (const String &str)
	Append operator.
String &	operator+= (char c)
	Append operator.
String &	operator+= (const char *str)
	Append operator.
bool	operator< (const String &str)
bool	operator< (const char *str)
bool	operator> (const String &str)
bool	operator> (const char *str)
bool	operator<= (const String &str)
bool	operator<= (const char *str)
bool	operator>= (const String &str)
bool	operator>= (const char *str)
bool	operator== (const String &str)
bool	operator== (const char *str)
bool	operator!= (const String &str)
bool	operator!= (const char *str)
bool	operator *= (const String &str)
	Test if string is contained in our string.
bool	operator *= (const char *str)
	Test if text is contained in our string.
Static Public Attributes
const unsigned	npos
Protected Member Functions
bool	isBig (void) const
	Determine if string is allocated in local variable or an external reference.
const char *	set (const char *str, unsigned len=0)
	Set the content of the string variable to the specified string value, and use smart re-allocation strategies if appropriate to shrink the size of the variable.
void	set (const String &str)
	Set the content of the string variable to that of another variable.
void	copy (const String &str)
	Impliment the copy constructor, used internally.
void	init (void)
	Used to initialize a string object.
char *	getSpace (unsigned size)
	Used to fetch memory, if needed, based on the size, from the pager, or the system heap.
unsigned	setSize (unsigned size)
	Set the size of allocated space in the string variable (capacity) to a known value.
void	setLength (unsigned len)
	Set the length value of the string content.
virtual int	compare (const char *text, unsigned len=0, unsigned index=0) const
	A derivable low level comparison operator.
unsigned	search (const char *text, unsigned clen=0, unsigned offset=0) const
	An internal method used to search for a substring starting at a known offset.
Static Protected Attributes
const unsigned	minsize
const unsigned	slotsize
const unsigned	pagesize
const unsigned	slotlimit
const unsigned	slots
Friends
class	MemPager
__EXPORT String	operator+ (const String &s1, const String &s2)
	Add two strings and return a temporary object.
__EXPORT String	operator+ (const String &s1, const char *s2)
__EXPORT String	operator+ (const char *s1, const String &s2)
__EXPORT String	operator+ (const String &s1, const char c2)
__EXPORT String	operator+ (const char c1, const String &s2)
__EXPORT std::istream &	getline (std::istream &is, String &str, char delim= '\n', unsigned size=0)
	Fetch input from a std::istream into the current string variable until either the string variable is filled (based on current length) or the deliminator is read.
__EXPORT std::ostream &	operator<< (std::ostream &os, const String &str)
	Stream the content of our string variable directly to a C++ streaming source.
std::istream &	operator>> (std::istream &is, String &str)
	Stream input into our variable.

---

Detailed Description

This is a generic and portable string class. Generic string class.

It uses optimized memory allocation strategies to efficiently handle smaller string content by grouping strings into 32 byte aligned slots that can be re-allocated from a free list directly.

While meant to cover the basic functionality of the ANSI C++ string class in form and function, this class offers some important enhancements, including the ability to derive class type specific versions of itself. The latter might be used to derive a unicode string, a string for data and time data types, or to add case insensitive comparisons, for example.

Author:

David Sugar <dyfet@ostel.com>

---

Member Typedef Documentation

typedef unsigned String::size_type

---

Constructor & Destructor Documentation

String::String (   )

Construct an empty string.

String::String (  const String &  original  )  [inline]

Copy constructor. Parameters: string  to copy from.

String::String (  const char *  str  )

Create a string from a cstring. Parameters: text  to set with.

String::String (  const String &  str, unsigned  offset, unsigned  len = npos )

Create a new string from a subset of another string. Parameters: prior  string. offset  to start of data in prior string. length  of our substring.

String::String (  unsigned  count, const char *  str )

Create a string of a known size, and optionally fill with content. Parameters: size  to allocate for our new string. content  to put into it.

String::String (  unsigned  count, char  fill = ' ' )

Fill a new string with character data. Parameters: size  of new string. char  to fill string with.

virtual String::~String (   )  [virtual]

Destroy the string...

---

Member Function Documentation

void String::add (  char  c  )

Add a character to the end of a string. Parameters: char  to add.

void String::append (  const String &  str  )

Append string to the end of the current string. Parameters: string  to append.

void String::append (  const char *  str, unsigned  offset, unsigned  count )

Append text into the current string. Parameters: text  to append. offset  to overlay. size  of text to append.

void String::append (  const char *  str, unsigned  count = 0 )

Append text to the end of the current string. Parameters: text  to append. size  of text to append.

char String::at (  int  offset  )  const

Return a character at a known offset. Returns: character at offset.

char* String::c_str (  void   )  const [inline]

Old ANSI C++ compatible string pointer extraction. Returns: string data.

unsigned String::capacity (  void   )  const [inline]

Get space allocated to hold current string. Returns: space of memory buffer from heap or local.

void String::chop (  unsigned  count  )  [inline]

Chop n leading characters from a string. Parameters: count  to chop.

void String::chop (  const char *  cs  )  [inline]

Chop leading characters from a string. Parameters: list  of chars to chop.

void String::clear (  void   )

Clear the contents of the entire string.

void String::compact (  void   )  [inline]

Reduce the size of the string allocation to the minimum needed based on the current effective length.

virtual int String::compare (  const char *  text, unsigned  len = 0, unsigned  index = 0 )  const [protected, virtual]

A derivable low level comparison operator. This can be used to create custom comparison data types in derived string classes. Returns: 0 if match, or value for ordering. Parameters: text  to compare. length  of text to compare. offset  from start of string, used in searchs.

void String::copy (  const String &  str  )  [protected]

Impliment the copy constructor, used internally. Will always create a minimum sized string allocation. Parameters: string  to copy from.

unsigned String::count (  const char *  s, unsigned  offset = 0, unsigned  len = 0 )  const

Count the number of occurrences of a specific text pattern within our string. Returns: count of instances. Parameters: offset  to start from. length  of text pattern if specified.

unsigned String::count (  const String &  s, unsigned  offset = 0 )  const

Count the number of occurences of a specific string within our string. Returns: count of instances. Parameters: string  to test. offset  to start from.

char* String::data (  void   )  const [inline]

Alternate get text method. Returns: string data.

bool String::empty (  void   )  const [inline]

Return true if string is empty.

void String::erase (  unsigned  start, unsigned  len = npos )

Erase a portion of string. Parameters: starting  index to erase from. number  of characters to erase.

unsigned String::find (  unsigned  instance, const String &  s, unsigned  offset = 0 )  const [inline]

A more convenient version of find for nth occurences, by putting the instance first. Parameters: nth  instance to look for. string  to look for. offset  to start at.

unsigned String::find (  unsigned  instance, const char *  text, unsigned  offset = 0, unsigned  len = 0 )  const [inline]

A more convenient version of find for nth occurences, by putting the instance first. Parameters: nth  instance to look for. text  to look for. offset  to start at. length  of text.

unsigned String::find (  const char *  s, unsigned  offset = 0, unsigned  len = 0, unsigned  count = 1 )  const

Find the index to the nth instance of text in our string. Returns: index of found substring. Parameters: string  to search for. offset  to start at. size  of string text. instance  to look for.

unsigned String::find (  const String &  s, unsigned  offset = 0, unsigned  instance = 1 )  const

Find the index to the nth instance of a substring in our string. Returns: index of found substring. Parameters: string  to search for. offset  to start at. instance  to look for.

const char* String::getIndex (  unsigned  index  )  const

Get a string pointer to string content based on an indexed offset. A NULL is returned if the index is outsize of range. Returns: string content or NULL if invalid index. Parameters: index

const unsigned String::getLength (  void   )  const

Get the assigned length of string. Returns: string length.

const unsigned String::getSize (  void   )  const

Get the allocation size of the string variable. Returns: allocation size.

char* String::getSpace (  unsigned  size  )  [protected]

Used to fetch memory, if needed, based on the size, from the pager, or the system heap. Returns: string pointer to space. Parameters: size  of space needed.

char* String::getText (  void   )  const

Get the text of a string. Returns: string content.

const char* String::index (  unsigned  idx  )  const [inline]

Return an indexed string based on the index, such as from a find. If out of range, a NULL string is returned. Returns: pointer to string data from our string, Parameters: index  or offset to use.

void String::init (  void   )  [protected]

Used to initialize a string object.

void String::insert (  unsigned  start, const String &  str )

Insert other string into our string. Parameters: string  offset to insert at. string  to insert.

void String::insert (  unsigned  start, const char *  text, unsigned  len = 0 )

Insert text into a string. Parameters: starting  offset to insert at. text  to insert. size  of text to insert.

bool String::isBig (  void   )  const [inline, protected]

Determine if string is allocated in local variable or an external reference. Returns: true if external heap is used.

bool String::isEmpty (  void   )  const

Return true if string is empty. Returns: true if string is empty string.

unsigned String::length (  void   )  const [inline]

Get length as if null terminated string. Returns: cstring length.

bool String::operator *= (  const char *  str  )

Test if text is contained in our string.

bool String::operator *= (  const String &  str  )

Test if string is contained in our string.

String::operator char * (   )  const [inline]

Get our string data through dereference operator. Returns: string data.

bool String::operator! (  void   )  const [inline]

Logical test for string empty. Returns: true if is empty.

bool String::operator!= (  const char *  str  )

bool String::operator!= (  const String &  str  )

String& String::operator+= (  const char *  str  )  [inline]

Append operator.

String& String::operator+= (  char  c  )  [inline]

Append operator.

String& String::operator+= (  const String &  str  )  [inline]

Append operator.

bool String::operator< (  const char *  str  )

bool String::operator< (  const String &  str  )

bool String::operator<= (  const char *  str  )

bool String::operator<= (  const String &  str  )

const char* String::operator= (  const char *  str  )  [inline]

Assign our string for c string.

void String::operator= (  const String &  str  )  [inline]

Assign our string from another string.

bool String::operator== (  const char *  str  )

bool String::operator== (  const String &  str  )

bool String::operator> (  const char *  str  )

bool String::operator> (  const String &  str  )

bool String::operator>= (  const char *  str  )

bool String::operator>= (  const String &  str  )

const char String::operator[] (  unsigned  index  )  const [inline]

Extract a character by array indexing. Returns: character code.

void String::replace (  unsigned  start, unsigned  len, const String &  s )

Replace text at a specific position in the string with new string,. Parameters: starting  offset to replace at. length  of text to remove. string  to replace with.

void String::replace (  unsigned  start, unsigned  len, const char *  text, unsigned  count = 0 )

Replace text at a specific position in the string with new text. Parameters: starting  offset to replace at. length  of text to remove. text  to replace with. size  of replacement text.

void String::resize (  unsigned  size  )

Re-allocate buffer space for string. Parameters: new  size to use.

unsigned String::rfind (  const char *  s, unsigned  offset = 0, unsigned  len = 0 )  const

Find last occurence of a text in our string. Returns: index of last instance found, Parameters: string  to search for. offset  to start from. size  of string to look for.

unsigned String::rfind (  const String &  s, unsigned  offset = 0 )  const

Find last occurence of a substring in our string. Returns: index of last instance found, Parameters: string  to search for. offset  to start from.

unsigned String::search (  const char *  text, unsigned  clen = 0, unsigned  offset = 0 )  const [protected]

An internal method used to search for a substring starting at a known offset. Used by find and count methods. Returns: npos if fails, or offset to text found. Parameters: text  to search for. length  of search text. offset  to start from.

void String::set (  const String &  str  )  [protected]

Set the content of the string variable to that of another variable. Uses the string set method. Parameters: string  to copy from.

const char* String::set (  const char *  str, unsigned  len = 0 )  [protected]

Set the content of the string variable to the specified string value, and use smart re-allocation strategies if appropriate to shrink the size of the variable. Parameters: string  to set. length  of string if passed.

void String::setLength (  unsigned  len  )  [protected]

Set the length value of the string content. Parameters: size  in bytes.

unsigned String::setSize (  unsigned  size  )  [protected]

Set the size of allocated space in the string variable (capacity) to a known value. The value is recomputed and adjusted based on allocation method. Parameters: size  in bytes.

unsigned String::size (  void   )  const [inline]

Get actual length of string data. Returns: actual size of string.

void String::strip (  const char *  cs  )

Strip lead and trailing characters from a string. Parameters: list  of chars to strip.

String String::substr (  unsigned  start, unsigned  len )  const [inline]

Return a new string that contains a specific substring of the current string. Returns: new string. Parameters: starting  offset for extracted substring. length  of substring.

char* String::text (  void   )  const [inline]

Alternate get text method. Returns: string data.

String String::token (  const char *  delim = "\t\n\r", unsigned  offset = 0 )

Extract a new string as a token from the current string. Returns: string containing token. Parameters: offset  to start from. deliminator  characters.

void String::trim (  unsigned  count  )

Trim n trailing characters from a string. Parameters: count  to trim.

void String::trim (  const char *  cs  )  [inline]

Trim trailing characters from a string. Parameters: list  of chars to trim.

---

Friends And Related Function Documentation

__EXPORT std::istream& getline (  std::istream &  is, String &  str, char  delim = '\n', unsigned  size = 0 )  [friend]

Fetch input from a std::istream into the current string variable until either the string variable is filled (based on current length) or the deliminator is read. Parameters: stream  to read. string  to save into. deliminator  to use. optional  size limitor.

friend class MemPager [friend]

__EXPORT String operator+ (  const char  c1, const String &  s2 )  [friend]

__EXPORT String operator+ (  const String &  s1, const char  c2 )  [friend]

__EXPORT String operator+ (  const char *  s1, const String &  s2 )  [friend]

__EXPORT String operator+ (  const String &  s1, const char *  s2 )  [friend]

__EXPORT String operator+ (  const String &  s1, const String &  s2 )  [friend]

Add two strings and return a temporary object.

__EXPORT std::ostream& operator<< (  std::ostream &  os, const String &  str )  [friend]

Stream the content of our string variable directly to a C++ streaming source.

std::istream& operator>> (  std::istream &  is, String &  str )  [friend]

Stream input into our variable.

---

Member Data Documentation

const unsigned String::minsize [static, protected]

const unsigned String::npos [static]

const unsigned String::pagesize [static, protected]

const unsigned String::slotlimit [static, protected]

const unsigned String::slots [static, protected]

const unsigned String::slotsize [static, protected]

---

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

• string.h

---