String Class Reference

This class is a container for strings composed of 8-bit ASCII characters. More...

#include <String.h>

Inheritance diagram for String:

[legend]Collaboration diagram for String:

[legend]List of all members.

Public Member Functions
	String ()
	String (const char ch)
	String constructor with a character argument.
	String (const char *initCstr)
	String constructor with a C-string argument.
	String (const String &Str)
	String copy constructor.
SubString	operator() (const size_t start, const size_t len)
	Sub-string operator: this function supports the left hand side (l-value) form for the sub-string operation.
size_t	strlen ()
	strlen does not include the null at the end of the string
size_t	getRefCnt ()
	Return the reference count.
int	compareTo (const char *Cstr)
	Compare the character string in "this" object with the argument Cstr.
String &	resize (const size_t new_size)
	Set the string length of the String to newSize.
	operator const char * () const
	This operator allows the assignment of a String to a const char .
String &	operator= (const char ch)
	Assign a character to a String.
String &	operator= (const char *Cstr)
	Assign a C-string to a String.
String &	operator= (const SubString &sub)
	Assign a SubString to a String.
String	operator+ (const char *Cstr)
	operator +: String("abcd") + " efgh"
String	operator+ (String &s)
	operator +: String("abcd") + String(" efgh")
String	operator+ (const char ch)
	operator+ : String + ch
String	operator+ (const SubString &sub)
	Append a String and a SubString.
String &	operator+= (const char *Cstr)
	Concatenate a C string on to the end of the String object.
String &	operator+= (String &s)
	Concatenate two String objects.
String &	operator+= (const char ch)
	Append a character to the end of "this" string.
bool	operator== (const char *Cstr)
bool	operator== (String &s)
bool	operator!= (const char *Cstr)
bool	operator!= (String &s)
bool	operator<= (const char *Cstr)
bool	operator<= (String &s)
bool	operator>= (const char *Cstr)
bool	operator>= (String &s)
bool	operator< (const char *Cstr)
bool	operator< (String &s)
bool	operator> (const char *Cstr)
bool	operator> (String &s)
Protected Member Functions
void	init (const char *initCstr)
	Initialize the underlying data structure for a String container from a C string.
size_t	length ()
	Return the number of data elements (characters) consumed by the String.
void	appendCString (const char *CStr)
	Append a C string at the end of the character string stored in the String object.
void	appendString (String &Str)
	Append the characters from "s" onto the end of the characters stored in the String object.
void	newEmptyString ()
	Make "this" into an empty String.
void	newSharedData ()
	Allocate a new SharedData object which contains a copy of the old data.
int	Cstrcmp (const char *s1, const char *s2)
	Compare two C strings pointed to by const char * pointers.
int	compareTo (String &s)
	Compare two strings for equality.
Private Attributes
friend	SubString

---

Detailed Description

This class is a container for strings composed of 8-bit ASCII characters.

This class uses reference counts and copy-on-write to improve memory use and, perhaps, performance.

This is the version 3.0 of this class. This class was originally modeled after the Rogue Wave RWCString class (using the documentation available on the Rogue Wave web site).

Why Yet Another String Container

Although I like the Rogue Wave class and the RWCString class in particular, I don't use the Rogue Wave classes in the software I write for Bear Products International. There are several reasons for this. I did not want to pay the Rogue Wave license fees, which are high for a Cave based software developer. Nor did I want to force anyone who licenses my software to also Rogue Wave license fees (sorry guys). I also wanted software that was as transparent as possible. Rogue Wave classes tend to be incompletely documented and it is not always easy to fully understand the way a particular class functions.

Rogue Wave is not the only alternative when it comes to reference counted String containers. The Microsoft Foundation Classes include a string container and some versions of the STL template library implement the STL string container as a reference counted object. Each of these alternatives has some draw back. Microsoft Foundation Class code is not portable outside of Windoz. Also, with the new .NET framework, it seems possible that Microsoft would at some point phase out the Foundation Classes. The reference counted versions of the STL string container that I'm aware of also incur a license fee, although not as steep as Rogue Wave (the Dinkumware STL library is one example of an STL implementation that includes reference counted strings).

Finally, to quote Bjarne Staroustrup

Writing string classes has great educational value...
Chapter 20, The C++ Programming Language, third edition Bjarne Staroustrup

The String class implements a sub-string (string section) operation which results in a SubString object. As a result, the String and SubString classes are closely related.

This class comes with a set of regression tests. I recommend that you run these regression tests with your compiler, on your system. Not all compilers implement C++ in the same way.

Author:

Ian Kaplan www.bearcave.com

Definition at line 99 of file String.h.

---

Constructor & Destructor Documentation

String::String (   )  [inline]

Definition at line 182 of file String.h. References CharArray. : CharArray() {}

String::String (  const char  ch  )  [inline]

String constructor with a character argument. Definition at line 186 of file String.h. References CharArray, and RCArray< char >::value. : CharArray() { if (ch != '\0') { value->data.append( ch ); value->data.append('\0'); } }

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

String constructor with a C-string argument. Definition at line 196 of file String.h. References CharArray, and init(). : CharArray() { init( initCstr ); }

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

String copy constructor. Definition at line 205 of file String.h. References CharArray, and RCArray< char >::value. : CharArray() { value = Str.value; }

---

Member Function Documentation

void String::appendCString (  const char *  CStr  )  [protected]

Append a C string at the end of the character string stored in the String object. The character data stored in a String object should be terminated by a null character (''). The null terminator for the "this" string will be overwritten by the first character of CStr. Reference count and allocation issues should be taken care of by the code that calls this function. Definition at line 67 of file String.C. References length(), and RCArray< char >::value. Referenced by operator+(), and operator+=(). { if (CStr != 0) { size_t len = length(); if (len > 0) { // if there is a null at the end of the string // (which there should be) write over it. if (value->data[len-1] == '\0') { value->data[len-1] = *CStr++; } } while (*CStr) { value->data.append( *CStr++ ); } value->data.append('\0'); } } // appendCString

void String::appendString (  String &  s  )  [protected]

Append the characters from "s" onto the end of the characters stored in the String object. Note that when String 's' is appended to the String object the null that terminates 's' should be appended as well. Reference count and allocation issues should be taken care of by the code that calls this function. Definition at line 97 of file String.C. References length(), and RCArray< char >::value. Referenced by operator+(), and operator+=(). { size_t i = 0; size_t len = s.length(); size_t thisLen = length(); // length of "this" String if (thisLen > 0 && len > 0) { // write over the null character if (value->data[thisLen-1] == '\0') { value->data[thisLen-1] = s.value->data[i]; i++; } } // if while (i < len) { char ch = s.value->data[i]; value->data.append( ch ); i++; } // while } // appendString

int String::compareTo (  const char *  Cstr  )  [inline]

Compare the character string in "this" object with the argument Cstr. if (this < Cstr) return -1; if (this == Cstr) return 0; if (this > Cstr) return 1; Definition at line 324 of file String.h. References Cstrcmp(). { const char *pThisCStr = *this; return Cstrcmp( pThisCStr, Cstr ); }

int String::compareTo (  String &  s  )  [protected]

Compare two strings for equality. Definition at line 122 of file String.C. References Cstrcmp(), length(), and RCArray< char >::value. Referenced by operator!=(), operator<(), operator<=(), operator==(), operator>(), and operator>=(). { if (length() == 0 && s.length() == 0) { // Both String objects contain no data and so are // equal return 0; } if (value == s.value) { // The two String objects point to the same shared data return 0; } const char *pThisCStr = *this; const char *Cstr = s; return Cstrcmp( pThisCStr, Cstr ); } // compareTo

int String::Cstrcmp (  const char *  pThisCStr, const char *  Cstr )  [protected]

Compare two C strings pointed to by const char * pointers. Return 1 if *pThisCStr is greater than *Cstr, -1 if pThisCstr is less than *Cstr and 0 if *pThisCstr is equal to *Cstr. Definition at line 204 of file String.C. Referenced by compareTo(). { int rslt; if (pThisCStr == 0) { if (Cstr == 0) rslt = 0; // both this and CStr are null else { if (::strlen( Cstr ) == 0) rslt = 0; // compare to an empty string ("") else rslt = -1; // this < Cstr } } else { // pThisCStr != 0 if (Cstr == 0) rslt = 1; // this > Cstr else // pThis != 0 && Cstr != 0 rslt = strcmp(pThisCStr, Cstr ); } return rslt; } // Cstrcmp

size_t String::getRefCnt (   )  [inline]

Return the reference count. This useful primarily for debug and verification. In the perfect world of bug free software the reference count could be entirely hidden. Reimplemented from RCArray< char >. Definition at line 229 of file String.h. References RCArray< char >::getRefCnt(). Referenced by checkRefCnt(), checkRefCntVal(), subStrAssign(), subStrRefCnt(), subStrSection(), test_arrayop(), test_assign(), test_constructors(), test_insert(), test_plus(), test_plus_equal(), and test_substring(). { return CharArray::getRefCnt(); }

void String::init (  const char *  initCstr  )  [protected]

Initialize the underlying data structure for a String container from a C string. Definition at line 41 of file String.C. References RCArray< char >::value. Referenced by String(). { if (initCstr != 0) { char ch; for (ch = *initCstr; ch != '\0'; ch = *initCstr) { value->data.append( ch ); initCstr++; } value->data.append( ch ); } }

size_t String::length (  void   )  [inline, protected]

Return the number of data elements (characters) consumed by the String. This includes the null character. So length() == strlen() + 1 Definition at line 217 of file String.h. References RCArray< char >::length(). Referenced by appendCString(), appendString(), compareTo(), and resize(). { return CharArray::length(); }

void String::newEmptyString (   )  [protected]

Make "this" into an empty String. If "this" is shared, allocate a new SharedData object. If "this" is not shared, set the length to zero. Definition at line 278 of file String.C. References RCArray< char >::value. Referenced by operator=(), and resize(). { if (value->isShared()) { value = new SharedData(); } else { value->data.set_size(0); } } // newEmptyString

void String::newSharedData (   )  [inline, protected]

Allocate a new SharedData object which contains a copy of the old data. Note that this code relies on the fact that value is a "smart pointer" which will decrement the reference count and deallocate the space if the reference count is zero. Definition at line 306 of file String.h. References RCArray< char >::value. Referenced by operator+(), operator+=(), and resize(). { value = new SharedData( value->data ); }

String::operator const char * (   )  const

This operator allows the assignment of a String to a const char . For example, in the code below a is assigned to pStr in the code below: String a("wierd operator"); const char *pStr; pStr = a; The compiler fills in the cast (e.g., const char *), it does not have to be explicit. That is we don't have to write pStr = (const char *)a; -- unnecessary cast A C++ compiler should issue an error if an attempt is made to assign a String object to a "char *". The data pointed to by the address returned by this operator should never be changed since it belongs to the String object. Definition at line 256 of file String.C. References RCArray< char >::value. { const char *pCstr = ""; size_t len = value->data.length(); if (len > 0) { if (value->data[len-1] != '\0') { // then add a NULL terminator value->data.append('\0'); } pCstr = value->data.getData(); } return pCstr; } // operator const char *

bool String::operator!= (  String &  s  )  [inline]

Definition at line 155 of file String.h. References compareTo(). { return (compareTo( s ) != 0); }

bool String::operator!= (  const char *  Cstr  )  [inline]

Definition at line 154 of file String.h. References compareTo(). { return (compareTo( Cstr ) != 0); }

SubString String::operator() (  const size_t  start, const size_t  len )  [inline]

Sub-string operator: this function supports the left hand side (l-value) form for the sub-string operation. For example: String a("abcdefghijkl"); a(4, 5) = "12345"; The String object "a" now contains "abcd12345jkl" This function returns a SubString object. The SubString object supports the assignment operator, which will assign the C-string to a Definition at line 255 of file String.h. { SubString subStr( *this, start, len ); return subStr; }

String String::operator+ (  const SubString &  sub  )  [inline]

Append a String and a SubString. String a = "abcde"; // indices: 01234567 String b = "123 5678"; String c = a + b(3,4); // result will be "abcde 567" Definition at line 275 of file String.h. { String section = sub; String result = *this + section; return result; } // operator +

String String::operator+ (  const char  ch  )  [inline]

operator+ : String + ch Append a String and a character. Definition at line 410 of file String.h. { char buf[4]; buf[0] = ch; buf[1] = '\0'; String tmp; tmp = *this + buf; // call String + Cstr return tmp; } // operator +

String String::operator+ (  String &  s  )  [inline]

operator +: String("abcd") + String(" efgh") Definition at line 389 of file String.h. References appendString(), and newSharedData(). { String tmp; tmp.newSharedData(); tmp.appendString( *this ); tmp.appendString( s ); return tmp; } // operator +

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

operator +: String("abcd") + " efgh" Create a new String object which contains the concatenation of the two operand strings (self and the argument "s"). The reference count for the new String object will be zero. If it is assigned then it will be incremented. Example: String a("abcd"); String b = a + " efgh"; When these statements are executed String 'a' will contain "abcd" and String 'b' will contain "abcd efgh". The reference count for both String objects will be 1. Definition at line 373 of file String.h. References appendCString(), and appendString(). { String tmp; tmp.appendString( *this ); tmp.appendCString( Cstr ); return tmp; } // operator +

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

Append a character to the end of "this" string. Definition at line 338 of file String.h. { char buf[4]; buf[0] = ch; buf[1] = '\0'; *this += buf; // call String += Cstr return *this; } // operator +=

String & String::operator+= (  String &  s  )

Concatenate two String objects. Definition at line 375 of file String.C. References appendString(), newSharedData(), and RCArray< char >::value. { if (s.value->data.length() > 0) { if (value->isShared()) { newSharedData(); } // If there is a null character, delete it so we don't // append after the null. size_t len = value->data.length(); if (len > 0 && value->data[len-1] == '\0') { value->data.remove(); } appendString( s ); } return *this; } // operator +=

String & String::operator+= (  const char *  Cstr  )

Concatenate a C string on to the end of the String object. For example: String s("abcd "); s += "efgh"; will result in "s" containing "abcd efgh". Definition at line 352 of file String.C. References appendCString(), newSharedData(), and RCArray< char >::value. { if (value->isShared()) { newSharedData(); } // If there is a null character, delete it so we don't // append after the null. size_t len = value->data.length(); if (len > 0 && value->data[len-1] == '\0') value->data.remove(); appendCString( Cstr ); return *this; } // operator +=

bool String::operator< (  String &  s  )  [inline]

Definition at line 161 of file String.h. References compareTo(). { return (compareTo( s ) < 0); }

bool String::operator< (  const char *  Cstr  )  [inline]

Definition at line 160 of file String.h. References compareTo(). { return (compareTo( Cstr ) < 0); }

bool String::operator<= (  String &  s  )  [inline]

Definition at line 157 of file String.h. References compareTo(). { return (compareTo( s ) <= 0); }

bool String::operator<= (  const char *  Cstr  )  [inline]

Definition at line 156 of file String.h. References compareTo(). { return (compareTo( Cstr ) <= 0); }

String & String::operator= (  const SubString &  sub  )  [inline]

Assign a SubString to a String. For example: String a = "lazy dog"; String b = a(5, 3); Definition at line 292 of file String.h. { *this = (String)sub; return *this; } // operator =

String & String::operator= (  const char *  Cstr  )

Assign a C-string to a String. The String(C-string) constructor could be used for this. However, using this default generates code which is more inefficient. The write() function is used here since it properly handles the String shared data. If a null string is assigned to a String, the result will be the same as if an empty String were assigned. For example: char *pCstr = 0; String a = "fubar"; a = pCstr; // same as if "" were assigned Definition at line 323 of file String.C. References newEmptyString(), and RCArray< char >::value. { newEmptyString(); if (Cstr != 0) { char ch; for (ch = *Cstr; ch != '\0'; ch = *Cstr) { value->data.append(ch); Cstr++; } value->data.append(ch); } return *this; } // operator= (String = C-string)

String & String::operator= (  const char  ch  )

Assign a character to a String. Definition at line 293 of file String.C. References newEmptyString(), and RCArray< char >::value. { newEmptyString(); if (ch != '\0') { value->data.append( ch ); value->data.append('\0'); } return *this; } // operator= (String = char)

bool String::operator== (  String &  s  )  [inline]

Definition at line 153 of file String.h. References compareTo(). { return (compareTo( s ) == 0); }

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

Definition at line 152 of file String.h. References compareTo(). { return (compareTo( Cstr ) == 0); }

bool String::operator> (  String &  s  )  [inline]

Definition at line 163 of file String.h. References compareTo(). { return (compareTo( s ) > 0); }

bool String::operator> (  const char *  Cstr  )  [inline]

Definition at line 162 of file String.h. References compareTo(). { return (compareTo( Cstr ) > 0); }

bool String::operator>= (  String &  s  )  [inline]

Definition at line 159 of file String.h. References compareTo(). { return (compareTo( s ) >= 0); }

bool String::operator>= (  const char *  Cstr  )  [inline]

Definition at line 158 of file String.h. References compareTo(). { return (compareTo( Cstr ) >= 0); }

String & String::resize (  const size_t  newSize  )

Set the string length of the String to newSize. This will be the size returned by String::strlen(). So the actual amount of data allocated will be newSize+1 to account for the null character, assuming that newSize > 0. If newSize == 0, strlen() will be zero and the number of data elements will be zero. The private function length() will return new_size + 1, since the String data is terminated by a null character. If the String is expanded, the String will be padded with spaces. If the reference count of the String object is greater than one, a unique copy will be made when it is resized, since other copies should be unaffected. Definition at line 158 of file String.C. References length(), newEmptyString(), newSharedData(), and RCArray< char >::value. Referenced by test_resize(). { if (newSize == 0) { newEmptyString(); } else { // newSize > 0 size_t new_len = newSize + 1; size_t old_len = length(); if (value->isShared()) { if (new_len >= old_len) { // this will copy the data into a new shared data object newSharedData(); value->data.set_size( new_len ); } else { // new_len < old_len RCPtr<SharedData> new_value = new SharedData(); for (size_t i = 0; i < newSize; i++) { new_value->data.append( value->data[i] ); } new_value->data.append('\0'); // note: smart pointer assignment value = new_value; } } else { value->data.set_size( new_len ); } for (size_t i = old_len-1; i < new_len-1; i++) { value->data[i] = ' '; } value->data[ new_len-1 ] = '\0'; } return *this; } // resize

size_t String::strlen (   )  [inline]

strlen does not include the null at the end of the string Definition at line 433 of file String.h. References RCArray< char >::value. Referenced by SubString::operator=(), subStrAssign(), subStrSection(), test_constructors(), test_resize(), and test_substring(). { int len = value->data.length(); if (len > 0 && value->data[len-1] == '\0') len--; return len; }

---

Member Data Documentation

friend String::SubString [private]

Definition at line 103 of file String.h.

---

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

• String.h
• String.C

---