ost::String Class Reference

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

#include <string.h>

Inheritance diagram for ost::String:

ost::SString 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.
Stringoperator+= (const String &str)
 Append operator.
Stringoperator+= (char c)
 Append operator.
Stringoperator+= (const char *str)
 Append operator.
Stringoperator+= (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
Stringoperator+= (int i)
 Append operator.
Stringoperator+= (unsigned int i)
Stringoperator+= (long l)
Stringoperator+= (unsigned long l)
Stringoperator+= (float f)
Stringoperator+= (double d)
Stringoperator+= (short s)
Stringoperator+= (unsigned short s)
Stringoperator= (int i)
 Assignment operator.
Stringoperator= (unsigned int i)
Stringoperator= (long l)
Stringoperator= (unsigned long l)
Stringoperator= (float f)
Stringoperator= (double d)
Stringoperator= (short s)
Stringoperator= (unsigned short s)
Stringoperator= (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.

Static Public Attributes

static 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

static 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

static const unsigned minsize
static const unsigned slotsize
static const unsigned pagesize
static const unsigned slotlimit
static 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.

static 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 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:
Generated on Sat Dec 8 03:02:36 2007 for GNU CommonC++ by  doxygen 1.4.6