You are looking at an old revision of the page string. This revision was created by Natalie Adams.
initial page
Intro
The string class implements dynamically allocated reference-counted 8-bit character strings. The string class is a mixture of L-type and null-terminated strings: it has both the length indicator and the terminating null-symbol. The length of a string is theoretically limited to INT_MAX, and practically is limited to the amount of virtual memory space available to the application.
A string object itself contains only a reference to the first character of the string buffer. A string object can be implicitly converted to a null-terminated string, either a variable or passed as an actual parameter, thus allowing to combine both PTypes strings and traditional C strings in your application. A string object converted to char* or const char* never returns NULL pointers: it guarantees to always point to some data, even if the string is zero-sized.
The reference counting mechanism works transparently (known also as copy-on-write) and safely with regard to multithreading. You can manipulate string objects as if each object had its own copy of string data. Whenever you modify a string object the library safely detaches the buffer from all other string objects that may be using the same buffer and creates a unique copy so that changes won't affect the other "holders" of this string.
NOTE on multithreading: the dynamic string objects themselves are NOT thread-safe. In other words, each thread can manipulate objects (variables) of type string only within their scope. However, it is safe to pass strings as (copy) parameters when, for example, sending a message to a concurrent thread through a message queue. Whenever the recipient thread tries to modify the string, the shared data buffer is safely detached.
The string class is declared in <ptypes.h>.
Constructor/destructors
#includeclass string { string(); string(const string&); string(char); string(const char*); string(const char*, int); ~string(); }
Operators
#includeclass string { // assignment string& operator =(const char*); string& operator =(char); string& operator =(const string&); friend void assign(string&, const char* buf, int len); // concatenation string& operator +=(const char*); string& operator +=(char); string& operator +=(const string&); string operator +(const char*) const; string operator +(char) const; string operator +(const string&) const; friend string operator +(const char*, const string&); friend string operator +(char c, const string&); // comparison bool operator ==(const char*) const; bool operator ==(char) const; bool operator ==(const string&) const; bool operator !=(const char*) const; bool operator !=(char c) const; bool operator !=(const string&) const; // indexed character access, 0-based char& string::operator[] (int index); const char& string::operator[] (int index) const; }
A string object can be constructed in 5 different ways:
- default constructor string() creates an empty string.
- copy constructor string(const string& s) creates a copy of the given string s. Actually this constructor only increments the reference count by 1 and no memory allocation takes place.
- string(char c) constructs a new string consisting of one character c.
- string(const char* s) constructs a new string object from a null-terminated string. If s is either NULL or is a pointer to a null character, an empty string object is created. This constructor can be used to assign a string literal to a string object (see examples below).
- string(const char* s, int len) copies len bytes of data from buffer s to the newly allocated string buffer.
Destructor ~string() decrements the reference count for the given string buffer and removes it from the dynamic memory if necessary.
Examples:
string s1; // empty string string s2 = s1; // copy string s3 = 'A'; // single character string s4 = "ABCabc"; // string literal char* p = "ABCabc"; string s5 = p; // null-terminated string string s6(p, 3); // buffer/length