ost::String Class Reference

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

#include <string.h>

Inheritance diagram for ost::String:

List of all members.

Public Types
typedef size_t	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 (std::string string)
	Create a String from std::string.
	String (const String &str, size_t offset, size_t len=npos)
	Create a new string from a subset of another string.
	String (size_t size, const char *format,...)
	Create a string from formatted text input.
	String (size_t count, const char fill= ' ')
	Fill a new string with character data.
virtual	~String ()
	Destroy the string...
const char *	getIndex (size_t index) const
	Get a string pointer to string content based on an indexed offset.
char *	getText (void) const
	Get the text of a string.
long	getValue (long defvalue=0l) const
	Get the value of a string.
bool	getBool (bool defbool=false) const
	Get the bool flag of a string.
const size_t	getLength (void) const
	Get the assigned length of string.
const size_t	getSize (void) const
	Get the allocation size of the string variable.
bool	isEmpty (void) const
	Return true if string is empty.
void	resize (size_t size)
	Re-allocate buffer space for string.
void	clear (void)
	Clear the contents of the entire string.
char	at (ssize_t offset) const
	Return a character at a known offset.
unsigned	count (const String &s, size_t offset=0) const
	Count the number of occurences of a specific string within our string.
unsigned	count (const char *s, size_t offset=0, size_t len=0) const
	Count the number of occurrences of a specific text pattern within our string.
String	token (const char *delim=" \t\n\r", size_t offset=0)
	Extract a new string as a token from the current string.
size_t	find (const String &s, size_t offset=0, unsigned instance=1) const
	Find the index to the nth instance of a substring in our string.
size_t	rfind (const String &s, size_t offset=0) const
	Find last occurence of a substring in our string.
size_t	find (const char *s, size_t offset=0, size_t len=0, unsigned count=1) const
	Find the index to the nth instance of text in our string.
size_t	rfind (const char *s, size_t offset=0, size_t 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 (size_t chars)
	Chop n leading characters from a string.
void	trim (size_t count)
	Trim n trailing characters from a string.
void	erase (size_t start, size_t len=npos)
	Erase a portion of string.
void	insert (size_t start, const char *text, size_t len=0)
	Insert text into a string.
void	insert (size_t start, const String &str)
	Insert other string into our string.
void	replace (size_t start, size_t len, const char *text, size_t count=0)
	Replace text at a specific position in the string with new text.
void	replace (size_t start, size_t len, const String &string)
	Replace text at a specific position in the string with new string,.
size_t	find (unsigned instance, const char *text, size_t offset=0, size_t len=0) const
	A more convenient version of find for nth occurences, by putting the instance first.
size_t	find (unsigned instance, const String &string, size_t offset=0) const
	A more convenient version of find for nth occurences, by putting the instance first.
String	substr (size_t start, size_t len) const
	Return a new string that contains a specific substring of the current string.
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.
size_t	length (void) const
	Get length as if null terminated string.
size_t	size (void) const
	Get actual length of string data.
size_t	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, size_t count=0)
	Append text to the end of the current string.
void	append (size_t size, const char *format,...)
	Append formatted text to the end of the current string.
void	append (const char *str, size_t offset, size_t 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 ind) const
	Extract a character by array indexing.
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.
String &	operator+= (const std::string &str)
	Append operator.
bool	operator< (const String &str) const
bool	operator< (const char *str) const
bool	operator> (const String &str) const
bool	operator> (const char *str) const
bool	operator<= (const String &str) const
bool	operator<= (const char *str) const
bool	operator>= (const String &str) const
bool	operator>= (const char *str) const
bool	operator== (const String &str) const
bool	operator== (const char *str) const
bool	operator!= (const String &str) const
bool	operator!= (const char *str) const
String &	operator+= (int i)
	Append operator.
String &	operator+= (unsigned int i)
String &	operator+= (long l)
String &	operator+= (unsigned long l)
String &	operator+= (float f)
String &	operator+= (double d)
String &	operator+= (short s)
String &	operator+= (unsigned short s)
String &	operator= (int i)
	Assignment operator.
String &	operator= (unsigned int i)
String &	operator= (long l)
String &	operator= (unsigned long l)
String &	operator= (float f)
String &	operator= (double d)
String &	operator= (short s)
String &	operator= (unsigned short s)
String &	operator= (const String &original)
bool	operator *= (const String &str) const
	Test if string is contained in our string.
bool	operator *= (const char *str) const
	Test if text is contained in our string.
Public Attributes
const char *(	index )(size_t ind) const
	Return an indexed string based on the index, such as from a find.
Static Public Attributes
const size_t	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, size_t 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.
const char *	set (size_t size, const char *format,...)
	Set the content of the string variable to that of a formatted printf style string.
void	copy (const String &str)
	Impliment the copy constructor, used internally.
void	init (void)
	Used to initialize a string object.
size_t	setSize (size_t size)
	Set the size of allocated space in the string variable (capacity) to a known value.
void	setLength (size_t len)
	Set the length value of the string content.
virtual int	compare (const char *text, size_t len=0, size_t index=0) const
	A derivable low level comparison operator.
size_t	search (const char *text, size_t clen=0, size_t offset=0) const
	An internal method used to search for a substring starting at a known offset.
Static Protected Member Functions
char *	getSpace (size_t size)
	Used to fetch memory, if needed, based on the size, from the pager, or the system heap.
Static Protected Attributes
const unsigned	minsize
const unsigned	slotsize
const unsigned	pagesize
const unsigned	slotlimit
const unsigned	slotcount
Friends
class	StringObject
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', size_t 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.
__EXPORT int	strprintf (String &str, size_t size, const char *format,...)
	Print values directly into a string 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 size_t ost::String::size_type

---

Constructor & Destructor Documentation

ost::String::String (   )

Construct an empty string.

ost::String::String (  const String &  original  )

Copy constructor. Parameters: original  string to copy from.

ost::String::String (  const char *  str  )

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

ost::String::String (  std::string  string  )

Create a String from std::string. Parameters: string  from std::string to copy from.

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

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

ost::String::String (  size_t  size, const char *  format,   ... )

Create a string from formatted text input. Parameters: size  to allocate for our new string. format  of data to input.

ost::String::String (  size_t  count, const char  fill = ' ' )

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

virtual ost::String::~String (   )  [virtual]

Destroy the string...

---

Member Function Documentation

void ost::String::add (  char  c  )

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

void ost::String::append (  const String &  str  )

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

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

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

void ost::String::append (  size_t  size, const char *  format,   ... )

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

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

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

char ost::String::at (  ssize_t  offset  )  const

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

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

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

size_t ost::String::capacity (  void   )  const [inline]

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

void ost::String::chop (  size_t  chars  )  [inline]

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

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

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

void ost::String::clear (  void   )

Clear the contents of the entire string.

void ost::String::compact (  void   )  [inline]

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

virtual int ost::String::compare (  const char *  text, size_t  len = 0, size_t  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  text to compare. len  length of text to compare. index  offset from start of string, used in searchs.

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

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

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

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

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

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

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

Alternate get text method. Returns: string data.

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

Return true if string is empty.

void ost::String::erase (  size_t  start, size_t  len = npos )

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

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

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

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

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

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

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

size_t ost::String::find (  const String &  s, size_t  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: s  string to search for. offset  offset to start at. instance  instance to look for.

bool ost::String::getBool (  bool  defbool = false  )  const

Get the bool flag of a string. Returns: boolean value.

const char* ost::String::getIndex (  size_t  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 size_t ost::String::getLength (  void   )  const

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

const size_t ost::String::getSize (  void   )  const

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

char* ost::String::getSpace (  size_t  size  )  [static, 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* ost::String::getText (  void   )  const

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

long ost::String::getValue (  long  defvalue = 0l  )  const

Get the value of a string. Returns: string value as number.

void ost::String::init (  void   )  [protected]

Used to initialize a string object.

void ost::String::insert (  size_t  start, const String &  str )

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

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

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

bool ost::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 ost::String::isEmpty (  void   )  const

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

size_t ost::String::length (  void   )  const [inline]

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

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

Test if text is contained in our string.

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

Test if string is contained in our string.

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

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

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

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

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

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

String& ost::String::operator+= (  unsigned short  s  )  [inline]

String& ost::String::operator+= (  short  s  )  [inline]

String& ost::String::operator+= (  double  d  )  [inline]

String& ost::String::operator+= (  float  f  )  [inline]

String& ost::String::operator+= (  unsigned long  l  )  [inline]

String& ost::String::operator+= (  long  l  )  [inline]

String& ost::String::operator+= (  unsigned int  i  )  [inline]

String& ost::String::operator+= (  int  i  )  [inline]

Append operator.

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

Append operator.

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

Append operator.

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

Append operator.

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

Append operator.

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

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

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

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

String& ost::String::operator= (  const String &  original  )  [inline]

String& ost::String::operator= (  unsigned short  s  )  [inline]

String& ost::String::operator= (  short  s  )  [inline]

String& ost::String::operator= (  double  d  )  [inline]

String& ost::String::operator= (  float  f  )  [inline]

String& ost::String::operator= (  unsigned long  l  )  [inline]

String& ost::String::operator= (  long  l  )  [inline]

String& ost::String::operator= (  unsigned int  i  )  [inline]

String& ost::String::operator= (  int  i  )  [inline]

Assignment operator.

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

Assign our string for c string.

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

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

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

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

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

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

const char ost::String::operator[] (  unsigned  ind  )  const [inline]

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

void ost::String::replace (  size_t  start, size_t  len, const String &  string )

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

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

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

void ost::String::resize (  size_t  size  )

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

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

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

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

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

size_t ost::String::search (  const char *  text, size_t  clen = 0, size_t  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  text to search for. clen  length of search text. offset  offset to start from.

const char* ost::String::set (  size_t  size, const char *  format,   ... )  [protected]

Set the content of the string variable to that of a formatted printf style string. Parameters: size  of string data to set. format  of string to write into object.

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

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

const char* ost::String::set (  const char *  str, size_t  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: str  string to set. len  length of string if passed.

void ost::String::setLength (  size_t  len  )  [protected]

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

size_t ost::String::setSize (  size_t  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.

size_t ost::String::size (  void   )  const [inline]

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

void ost::String::strip (  const char *  cs  )

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

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

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

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

Alternate get text method. Returns: string data.

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

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

void ost::String::trim (  size_t  count  )

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

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

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

---

Friends And Related Function Documentation

__EXPORT std::istream& getline (  std::istream &  is, String &  str, char  delim = '\n', size_t  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: is  stream to read. str  string to save into. delim  deliminator to use. size  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.

friend class StringObject [friend]

__EXPORT int strprintf (  String &  str, size_t  size, const char *  format,   ... )  [friend]

Print values directly into a string variable. Returns: character count. Parameters: str  object reference to use. size  of string required. format  of data.

---

Member Data Documentation

const char*( ost::String::index)(size_t ind) 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: ind  index or offset to use.

const unsigned ost::String::minsize [static, protected]

const size_t ost::String::npos [static]

const unsigned ost::String::pagesize [static, protected]

const unsigned ost::String::slotcount [static, protected]

const unsigned ost::String::slotlimit [static, protected]

const unsigned ost::String::slotsize [static, protected]

---

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

• string.h

---