Rogue Wave banner
Previous fileTop of documentContentsIndexNext file

RWCString

Data Type and Member Function Indexes
(exclusive of constructors and destructors)

Synopsis

#include <rw/cstring.h>
RWCString a;

Description

Class RWCString offers very powerful and convenient facilities for manipulating strings that are just as efficient as the familiar standard C <string.h> functions.

Although the class is primarily intended to be used to handle single-byte character sets (SBCS; such as ASCII or ISO Latin-1), with care it can be used to handle multibyte character sets (MBCS). There are two things that must be kept in mind when working with MBCS:

Parameters of type "const char*" must not be passed a value of zero. This is detected in the debug version of the library.

The class is implemented using a technique called copy on write. With this technique, the copy constructor and assignment operators still reference the old object and hence are very fast. An actual copy is made only when a "write" is performed, that is if the object is about to be changed. The net result is excellent performance, but with easy-to-understand copy semantics.

A separate class RWCSubString supports substring extraction and modification operations.

RWCString and Mutexes

Class RWCString uses a single mutex to protect string reference counts. When run in a multithreaded, multiprocessor environment contention for RWCString’s single mutex can cause performance issues.

To address RWCString-related performance issues that may occur in a multithreaded, multiprocessor environment, we have provided a macro, RW_CSTRING_MUTEX_COUNT. This macro lets you adjust RWCString to use any number of mutexes. You use the macro by creating a custom configuration in Software Parts Manager that defines the macro and sets it equal to the desired number of mutexes (-DRW_CSTRING_MUTEX_COUNT=X). You then build your Tools.h++ library with the new configuration.


This feature should only be used in a multithreaded, multiprocessor environment when your code is RWCString intensive. In other circumstances, changing the number of mutexes available will negatively affect performance.

To help you determine the optimal number of mutexes, we provide a second macro, RW_CSTRING_MUTEX_COUNT_INFO, that makes available the function printStringMutexCount(). The new function prints a usage histogram for the pool of mutexes. By reviewing the histogram you can determine the best number of mutexes for your environment. To use the printStringMutexCount() function, update your custom configuration to include the macro definition -DRW_CSTRING_MUTEX_COUNT_INFO. You can remove the second macro definition from your library after determining the best number of mutexes.

A tip of the Rogue Wave hat goes to Lexis-Nexis for their help with this.

Persistence

Simple

Example

#include <rw/re.h>
#include <rw/rstream.h>

main(){
  RWCString a("There is no joy in Beantown.");

  cout << a << endl << "becomes...." << endl;

  RWCRExpr re("[A-Z][a-z]*town");  // Any capitalized "town"
  a.replace(re, "Redmond");
  cout << a << endl;
}

Program output:

There is no joy in Redmond.

Enumerations

enum RWCString::caseCompare { exact, ignoreCase }
enum RWCString::scopeType { one, all }

Public Constructors

RWCString();
RWCString(const char* cs);
RWCString(const char* cs, size_t N);
RWCString(RWSize_T ic);
RWCString(const RWCString& str);
RWCString(const RWCSubString& ss);
RWCString(char c);
RWCString(char c, size_t N);

Type Conversion

operator
const char*() const;

Assignment Operators

RWCString&
operator=(const char* cs);
RWCString&
operator=(const RWCString& str);
RWCString&
operator+=(const char* cs);
RWCString&
operator+=(const RWCString& str);

Indexing Operators

char&
operator[](size_t i);
char
operator[](size_t i) const;
char&
operator()(size_t i);
char
operator()(size_t i) const;
RWCSubString
operator()(size_t start, size_t len);
const RWCSubString
operator()(size_t start, size_t len) const;
RWCSubString
operator()(const RWCRExpr& re, size_t start=0);
const RWCSubString
operator()(const RWCRExpr& re, size_t start=0) const;
RWCSubString
operator()(const RWCRegexp& re, size_t start=0);
const RWCSubString
operator()(const RWCRegexp& re, size_t start=0) const;

Public Member Functions

RWCString&
append(const char* cs);
RWCString&
append(const char* cs, size_t N);
RWCString&
append(char c, size_t N);
RWCString&
append(const RWCString& cstr);
RWCString&
append(const RWCString& cstr, size_t N);
size_t
binaryStoreSize() const;
size_t
capacity() const;
size_t
capacity(size_t capac);
int
collate(const char* str) const;
int
collate(const RWCString& str) const;
int
compareTo(const char* str, caseCompare = RWCString::exact) const;
int
compareTo(const RWCString& str, 
          caseCompare = RWCString::exact) const;
RWBoolean
contains(const char* str, caseCompare = RWCString::exact)
         const;
RWBoolean
contains(const RWCString& cs, 
         caseCompare = RWCString::exact) const;
const char*
data() const;
size_t
first(char c) const;
size_t
first(char c, size_t) const;
size_t
first(const char* str) const;
size_t
first(const char* str, size_t N) const;
unsigned
hash(caseCompare = RWCString::exact) const;
size_t
index(const char* pat,size_t i=0, 
      caseCompare = RWCString::exact) const;
size_t
index(const RWCString& pat,size_t i=0, 
      caseCompare = RWCString::exact) const;
size_t
index(const char* pat, size_t patlen,size_t i, 
      caseCompare cmp) const;
size_t
index(const RWCString& pat, size_t patlen,size_t i,
      caseCompare cmp) const;
size_t
index(const RWCRExpr& re, size_t i=0) const;
size_t
index(const RWCRegexp& re, size_t i=0) const;
size_t
index(const RWCRExpr& re,size_t* ext,size_t i=0) const;
size_t
index(const RWCRegexp& re,size_t* ext,size_t i=0) const;
RWCString&
insert(size_t pos, const char* cs);
RWCString&
insert(size_t pos, const char* cs, size_t N);
RWCString&
insert(size_t pos, const RWCString& str);
RWCString&
insert(size_t pos, const RWCString& str, size_t N);
RWBoolean
isAscii() const;
RWBoolean
isNull() const;
size_t
last(char c) const;
size_t
last(char c, size_t N) const;
size_t
length() const;
RWCSubString
match(const RWCRExpr& re, size_t start=0);
const RWCSubString
match(const RWCRExpr& re, size_t start=0) const;
size_t
mbLength() const;
RWCString&
prepend(const char* cs);
RWCString&
prepend(const char* cs, size_t N);
RWCString&
prepend(char c, size_t N);
RWCString&
prepend(const RWCString& str);
RWCString&
prepend(const RWCString& cstr, size_t N);
istream&
readFile(istream& s);
istream&
readLine(istream& s, RWBoolean skipWhite = TRUE);
istream&
readString(istream& s);
istream&
readToDelim(istream& s, char delim='\n');
istream&
readToken(istream& s);
RWCString&
remove(size_t pos);
RWCString&
remove(size_t pos, size_t N);
RWCString&
replace(size_t pos, size_t N, const char* cs);
RWCString&
replace(size_t pos, size_t N1,const char* cs, size_t N2);
RWCString&
replace(size_t pos, size_t N, const RWCString& str);
RWCString&
replace(size_t pos, size_t N1,const RWCString& str, size_t N2);
replace(const RWCRExpr& pattern, const char* replacement, 
        scopeType scope=one);
replace(const RWCRExpr& pattern, 
        const RWCString& replacement,scopeType scope=one);
void
resize(size_t n);
RWCSubString
strip(stripType s = RWCString::trailing, char c = ' ');
const RWCSubString
strip(stripType s = RWCString::trailing, char c = ' ') 
const;
RWCSubString
subString(const char* cs, size_t start=0,
          caseCompare = RWCString::exact);
const RWCSubString
subString(const char* cs, size_t start=0,
          caseCompare = RWCString::exact) const;
void
toLower();
void
toUpper();

Static Public Member Functions

static unsigned
hash(const RWCString& str);
static size_t
initialCapacity(size_t ic = 15);
static size_t
maxWaste(size_t mw = 15);
static size_t
resizeIncrement(size_t ri = 16);

Related Global Operators

RWBoolean
operator==(const RWCString&, const char*     );
RWBoolean
operator==(const char*,      const RWCString&);
RWBoolean
operator==(const RWCString&, const RWCString&);
RWBoolean
operator!=(const RWCString&, const char*     );
RWBoolean
operator!=(const char*,      const RWCString&);
RWBoolean
operator!=(const RWCString&, const RWCString&);
RWBoolean
operator< (const RWCString&, const char*     );
RWBoolean
operator< (const char*,      const RWCString&);
RWBoolean
operator< (const RWCString&, const RWCString&);
RWBoolean
operator> (const RWCString&, const char*     );
RWBoolean
operator> (const char*,      const RWCString&);
RWBoolean
operator> (const RWCString&, const RWCString&);
RWBoolean
operator<=(const RWCString&, const char*     );
RWBoolean
operator<=(const char*,      const RWCString&);
RWBoolean
operator<=(const RWCString&, const RWCString&);
RWBoolean
operator>=(const RWCString&, const char*     );
RWBoolean
operator>=(const char*,      const RWCString&);
RWBoolean
operator>=(const RWCString&, const RWCString&);
RWCString
operator+(const RWCString&, const RWCString&);
RWCString
operator+(const char*,      const RWCString&);
RWCString
operator+(const RWCString&, const char*     );
ostream&
operator<<(ostream& s, const RWCString&);
istream&
operator>>(istream& s, RWCString& str);
RWvostream&
operator<<(RWvostream&, const RWCString& str);
RWFile&
operator<<(RWFile&,     const RWCString& str);
RWvistream&
operator>>(RWvistream&, RWCString& str);
RWFile&
operator>>(RWFile&,     RWCString& str);

Related Global Functions

RWCString
strXForm(const RWCString&);
RWCString
toLower(const RWCString& str);
RWCString
toUpper(const RWCString& str);

Global Logical Operators

RWBoolean
operator==(const RWCString&,    const RWCSubString&);
RWBoolean
operator==(const RWCSubString&, const RWCString&   );
RWBoolean
operator!=(const RWCString&,    const RWCString&   );
RWBoolean
operator!=(const RWCString&,    const RWCSubString&);
RWBoolean
operator!=(const RWCSubString&, const RWCString&   );
RWBoolean
operator!=(const char*,         const RWCString&   );
RWBoolean
operator!=(const RWCString&,    const char*        );


Previous fileTop of documentContentsIndexNext file
©Copyright 1999, Rogue Wave Software, Inc.
Send mail to report errors or comment on the documentation.