Cass 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:
Because characters can be more than one byte long, the number of bytes in a string can, in general, be greater than the number of characters in the string. Use function RWCString::length() to get the number of bytes in a string, function RWCString::mbLength() to get the number of characters. Note that the latter is much slower because it must determine the number of bytes in every character. Hence, if the string is known to be nothing but SBCS, then RWCString::length() is much to be preferred.
One or more bytes of a multibyte character can be zero. Hence, MBCS cannot be counted on being null terminated. In practice, it is a rare MBCS that uses embedded nulls. Nevertheless, you should be aware of this and program defensively. In any case, class RWCString can handle embedded nulls.
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.
#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. |
enum RWCString::caseCompare { exact, ignoreCase }
Used to specify whether comparisons, searches, and hashing functions should use case sensitive (exact) or case-insensitive (ignoreCase) semantics.
enum RWCString::scopeType { one, all }
Used to specify whether regular expression replace replaces the first one substring matched by the regular expression or replaces all substrings matched by the regular expression.
RWCString();
Creates a string of length zero (the null string).
RWCString(const char* cs);
Conversion from the null-terminated character string cs. The created string will copy the data pointed to by cs, up to the first terminating null. This function is incompatible with cs strings with embedded nulls. This function may be incompatible with cs MBCS strings.
RWCString(const char* cs, size_t N);
Constructs a string from the character string cs. The created string will copy the data pointed to by cs. Exactly N bytes are copied, including any embedded nulls. Hence, the buffer pointed to by cs must be at least N bytes long.
RWCString(RWSize_T ic);
Creates a string of length zero (the null string). The string's capacity (that is, the size it can grow to without resizing) is given by the parameter ic. We recommend creating an RWSize_T value from a numerical constant to pass into this constructor. While RWSize_T knows how to convert size_t's to itself, conforming compilers will chose the conversion to char instead.
RWCString(const RWCString& str);
Copy constructor. The created string will copy str's data.
RWCString(const RWCSubString& ss);
Conversion from sub-string. The created string will copy the substring represented by ss.
RWCString(char c);
Constructs a string containing the single character c.
RWCString(char c, size_t N);
Constructs a string containing the character c repeated N times.
operator const char*() const;
Access to the RWCString's data as a null terminated string. This data is owned by the RWCString and may not be deleted or changed. If the RWCString object itself changes or goes out of scope, the pointer value previously returned may (will!) become invalid. While the string is null-terminated, note that its length is still given by the member function length(). That is, it may contain embedded nulls.
RWCString& operator=(const char* cs);
Assignment operator. Copies the null-terminated character string pointed to by cs into self. Returns a reference to self. This function is incompatible with cs strings with embedded nulls. This function may be incompatible with cs MBCS strings.
RWCString& operator=(const RWCString& str);
Assignment operator. The string will copy str's data. Returns a reference to self.
RWCString& operator+=(const char* cs);
Append the null-terminated character string pointed to by cs to self. Returns a reference to self. This function is incompatible with cs strings with embedded nulls. This function may be incompatible with cs MBCS strings.
RWCString& operator+=(const RWCString& str);
Append the string str to self. Returns a reference to self.
char& operator[](size_t i); char operator[](size_t i) const;
Return the ith byte. The first variant can be used as an lvalue. The index i must be between 0 and the length of the string less one. Bounds checking is performed — if the index is out of range then an exceptionof type RWBoundsErr will occur.
char& operator()(size_t i); char operator()(size_t i) const;
Return the ith byte. The first variant can be used as an lvalue. The index i must be between 0 and the length of the string less one. Bounds checking is performed if the pre-processor macro RWBOUNDS_CHECK has been defined before including <rw/cstring.h>. In this case, if the index is out of range, then an exception of type RWBoundsErr will occur.
RWCSubString operator()(size_t start, size_t len); const RWCSubString operator()(size_t start, size_t len) const;
Substring operator. Returns an RWCSubString of self with length len, starting at index start. The first variant can be used as an lvalue. The sum of start plus len must be less than or equal to the string length. If the library was built using the RWDEBUG flag, and start and len are out of range, then an exception of type RWBoundsErr will occur.
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;
Returns the first substring starting after index start that matches the regular expression re. If there is no such substring, then the null substring is returned. The first variant can be used as an lvalue.
Note that if you wish to use operator()(const RWCRExpr&...) you must instead use match(constRWCRExpr&...) described below. The reason for this is that we are presently retaining RWCRegexp but operator(const RWCRExpr&...) and operator(const RWCRegexp) are ambiguous in the case of RWCString::operator("string"). In addition, operator(const char *) and operator(size_t) are ambiguous in the case of RWCString::operator(0).This function is incompatible with cs strings with embedded nulls. This function may be incompatible with cs MBCS strings.
RWCString& append(const char* cs);
Append a copy of the null-terminated character string pointed to by cs to self. Returns a reference to self. This function is incompatible with cs strings with embedded nulls. This function may be incompatible with cs MBCS strings.
RWCString& append(const char* cs, size_t N);
Append a copy of the character string cs to self. Exactly N bytes are copied, including any embedded nulls. Hence, the buffer pointed to by cs must be at least N bytes long. Returns a reference to self.
RWCString& append(char c, size_t N);
Append N copies of the character c to self. Returns a reference to self.
RWCString& append(const RWCString& cstr);
Append a copy of the string cstr to self. Returns a reference to self.
RWCString& append(const RWCString& cstr, size_t N);
Append the first N bytes or the length of cstr (whichever is less) of cstr to self. Returns a reference to self.
size_t binaryStoreSize() const;
Returns the number of bytes necessary to store the object using the global function:
RWFile& operator<<(RWFile&, const RWCString&);
size_t capacity() const;
Return the current capacity of self. This is the number of bytes the string can hold without resizing.
size_t capacity(size_t capac);
Hint to the implementation to change the capacity of self to capac. Returns the actual capacity.
int collate(const char* str) const; int collate(const RWCString& str) const;
Returns an int less then, greater than, or equal to zero, according to the result of calling the standard C library function ::strcoll() on self and the argument str. This supports locale-dependent collation. Provided only on platforms that provide ::strcoll(). This function is incompatible with strings with embedded nulls.
int compareTo(const char* str, caseCompare = RWCString::exact) const; int compareTo(const RWCString& str, caseCompare = RWCString::exact) const;
Returns an int less than, greater than, or equal to zero, according to the result of calling the standard C library function memcmp() on self and the argument str. Case sensitivity is according to the caseCompare argument, and may be RWCString::exact or RWCString::ignoreCase. If caseCompare is RWCString::exact, then this function works for all string types. Otherwise, this function is incompatible with MBCS strings. This function is incompatible with const char* strings with embedded nulls. This function may be incompatible with const char* MBCS strings.
RWBoolean contains(const char* str, caseCompare = RWCString::exact) const; RWBoolean contains(const RWCString& cs, caseCompare = RWCString::exact) const;
Pattern matching. Returns TRUE if str occurs in self. Case sensitivity is according to the caseCompare argument, and may be RWCString::exact or RWCString::ignoreCase. If caseCompare is RWCString::exact, then this function works for all string types. Otherwise, this function is incompatible with MBCS strings. This function is incompatible with const char* strings with embedded nulls. This function may be incompatible with const char* MBCS strings.
const char* data() const;
Access to the RWCString's data as a null terminated string. This datum is owned by the RWCString and may not be deleted or changed. If the RWCString object itself changes or goes out of scope, the pointer value previously returned will become invalid. While the string is null terminated, note that its length is still given by the member function length(). That is, it may contain embedded nulls.
size_t first(char c) const;
Returns the index of the first occurence of the character c in self. Returns RW_NPOS if there is no such character or if there is an embedded null prior to finding c. This function is incompatible with strings with embedded nulls. This function is incompatible with MBCS strings.
size_t first(char c, size_t) const;
Returns the index of the first occurence of the character c in self. Continues to search past embedded nulls. Returns RW_NPOS if there is no such character. This function is incompatible with MBCS strings.
size_t first(const char* str) const;
Returns the index of the first occurence in self of any character in str. Returns RW_NPOS if there is no match or if there is an embedded null prior to finding any character from str. This function is incompatible with strings with embedded nulls. This function may be incompatible with MBCS strings.
size_t first(const char* str, size_t N) const;
Returns the index of the first occurence in self of any character in str. Exactly N bytes in str are checked including any embedded nulls so str must point to a buffer containing at least N bytes. Returns RW_NPOS if there is no match.
unsigned hash(caseCompare = RWCString::exact) const;
Returns a suitable hash value. If caseCompare is RWCString::ignoreCase then this function will be incompatible with MBCS strings.
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;
Pattern matching. Starting with index i, searches for the first occurrence of pat in self and returns the index of the start of the match. Returns RW_NPOS if there is no such pattern. Case sensitivity is according to the caseCompare argument; it defaults to RWCString::exact. If caseCompare is RWCString::exact, then this function works for all string types. Otherwise, this function is incompatible with MBCS strings.
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;
Pattern matching. Starting with index i, searches for the first occurrence of the first patlen bytes from pat in self and returns the index of the start of the match. Returns RW_NPOS if there is no such pattern. Case sensitivity is according to the caseCompare argument. If caseCompare is RWCString::exact, then this function works for all string types. Otherwise, this function is incompatible with MBCS strings.
size_t index(const RWCRExpr& re, size_t i=0) const; size_t index(const RWCRegexp& re, size_t i=0) const;
Regular expression matching. Returns the index greater than or equal to i of the start of the first pattern that matches the regular expression re. Returns RW_NPOS if there is no such pattern. This function is incompatible with MBCS strings.
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;
Regular expression matching. Returns the index greater than or equal to i of the start of the first pattern that matches the regular expression re. Returns RW_NPOS if there is no such pattern. The length of the matching pattern is returned in the variable pointed to by ext. This function is incompatible with strings with embedded nulls. This function may be incompatible with MBCS strings.
RWCString& insert(size_t pos, const char* cs);
Insert a copy of the null-terminated string cs into self at byte position pos, thus expanding the string. Returns a reference to self. This function is incompatible with cs strings with embedded nulls. This function may be incompatible with cs MBCS strings.
RWCString& insert(size_t pos, const char* cs, size_t N);
Insert a copy of the first N bytes of cs into self at byte position pos, thus expanding the string. Exactly N bytes are copied, including any embedded nulls. Hence, the buffer pointed to by cs must be at least N bytes long. Returns a reference to self.
RWCString& insert(size_t pos, const RWCString& str);
Insert a copy of the string str into self at byte position pos. Returns a reference to self.
RWCString& insert(size_t pos, const RWCString& str, size_t N);
Insert a copy of the first N bytes or the length of str (whichever is less) of str into self at byte position pos. Returns a reference to self.
RWBoolean isAscii() const;
Returns TRUE if self contains no bytes with the high bit set.
RWBoolean isNull() const;
Returns TRUE if this is a zero lengthed string (i.e., the null string).
size_t last(char c) const;
Returns the index of the last occurrence in the string of the character c. Returns RW_NPOS if there is no such character or if there is an embedded null to the right of c in self. This function is incompatible with strings with embedded nulls. This function may be incompatible with MBCS strings.
size_t last(char c, size_t N) const;
Returns the index of the last occurrence in the string of the character c. Continues to search past embedded nulls. Returns RW_NPOS if there is no such character. This function is incompatible with MBCS strings.
size_t length() const;
Return the number of bytes in self. Note that if self contains multibyte characters, then this will not be the number of characters.
RWCSubString match(const RWCRExpr& re, size_t start=0); const RWCSubString match(const RWCRExpr& re, size_t start=0) const;
Returns the first substring starting after index start that matches the regular expression re. If there is no such substring, then the null substring is returned. The first variant can be used as an lvalue. Note that this is used in place of operator()(const RWCRegexp&...) if you want to use extended regular expressions.
size_t mbLength() const;
Return the number of multibyte characters in self, according to the Standard C function ::mblen(). Returns RW_NPOS if a bad character is encountered. Note that, in general, mbLength() £ length(). Provided only on platforms that provide ::mblen().
RWCString& prepend(const char* cs);
Prepend a copy of the null-terminated character string pointed to by cs to self. Returns a reference to self. This function is incompatible with cs strings with embedded nulls. This function may be incompatible with cs MBCS strings.
RWCString& prepend(const char* cs, size_t N);
Prepend a copy of the character string cs to self. Exactly N bytes are copied, including any embedded nulls. Hence, the buffer pointed to by cs must be at least N bytes long. Returns a reference to self.
RWCString& prepend(char c, size_t N);
Prepend N copies of character c to self. Returns a reference to self.
RWCString& prepend(const RWCString& str);
Prepends a copy of the string str to self. Returns a reference to self.
RWCString& prepend(const RWCString& cstr, size_t N);
Prepend the first N bytes or the length of cstr (whichever is less) of cstr to self. Returns a reference to self.
istream& readFile(istream& s);
Reads characters from the input stream s, replacing the previous contents of self, until EOF is reached. Null characters are treated the same as other characters.
istream& readLine(istream& s, RWBoolean skipWhite = TRUE);
Reads characters from the input stream s, replacing the previous contents of self, until a newline (or an EOF) is encountered. The newline is removed from the input stream but is not stored. Null characters are treated the same as other characters. If the skipWhite argument is TRUE, then whitespace is skipped (using the iostream library manipulator ws) before saving characters.
istream& readString(istream& s);
Reads characters from the input stream s, replacing the previous contents of self, until an EOF or null terminator is encountered. If the number of bytes remaining in the stream is large, you should resize the RWCString to approximately the number of bytes to be read prior to using this method. See "Implementation Details" in the User's Guide for more information. This function is incompatible with strings with embedded nulls. This function may be incompatible with MBCS strings.
istream& readToDelim(istream& s, char delim='\n');
Reads characters from the input stream s, replacing the previous contents of self, until an EOF or the delimiting character delim is encountered. The delimiter is removed from the input stream but is not stored. Null characters are treated the same as other characters. If delim is `\0' then this function is incompatible with strings with embedded nulls. If delim is `\0' then this function may be incompatible with MBCS strings.
istream& readToken(istream& s);
Whitespace is skipped before saving characters. Characters are then read from the input stream s, replacing previous contents of self, until trailing whitespace or an EOF is encountered. The whitespace is left on the input stream. Null characters are treated the same as other characters. Whitespace is identified by the standard C library function isspace(). This function is incompatible with MBCS strings.
RWCString& remove(size_t pos);
Removes the bytes from the byte position pos, which must be no greater than length(), to the end of string. Returns a reference to self.
RWCString& remove(size_t pos, size_t N);
Removes N bytes or to the end of string (whichever comes first) starting at the byte position pos, which must be no greater than length(). Returns a reference to self.
RWCString& replace(size_t pos, size_t N, const char* cs);
Replaces N bytes or to the end of string (whichever comes first) starting at byte position pos, which must be no greater than length(), with a copy of the null-terminated string cs. Returns a reference to self. This function is incompatible with cs strings with embedded nulls. This function may be incompatible with cs MBCS strings.
RWCString& replace(size_t pos, size_t N1,const char* cs, size_t N2);
Replaces N1 bytes or to the end of string (whichever comes first) starting at byte position pos, which must be no greater than length(), with a copy of the string cs. Exactly N2 bytes are copied, including any embedded nulls. Hence, the buffer pointed to by cs must be at least N2 bytes long. Returns a reference to self.
RWCString& replace(size_t pos, size_t N, const RWCString& str);
Replaces N bytes or to the end of string (whichever comes first) starting at byte position pos, which must be no greater than length(), with a copy of the string str. Returns a reference to self.
RWCString& replace(size_t pos, size_t N1,const RWCString& str, size_t N2);
Replaces N1 bytes or to the end of string (whichever comes first) starting at position pos, which must be no greater than length(), with a copy of the first N2 bytes, or the length of str (whichever is less), from str. Returns a reference to self.
replace(const RWCRExpr& pattern, const char* replacement, scopeType scope=one); replace(const RWCRExpr& pattern, const RWCString& replacement,scopeType scope=one);
Replaces substring matched by pattern with replacement string. pattern is the new extended regular expression. scope is one of {one, all} and controls whether all matches of pattern are replaced with replacement or just the first one match is replaced. replacement is the replacement pattern for the string. Here's an example:
RWCString s("hahahohoheehee");
s.replace(RWCRExpr("(ho)+","HAR"); // s == "hahaHARheehee"
This function is incompatible with const char* replacement strings with embedded nulls. This function may be incompatible with const char*replacement MBCS strings.
void resize(size_t n);
Changes the length of self to n bytes, adding blanks or truncating as necessary.
RWCSubString strip(stripType s = RWCString::trailing, char c = ` `); const RWCSubString strip(stripType s = RWCString::trailing, char c = ` `) const;
Returns a substring of self where the character c has been stripped off the beginning, end, or both ends of the string. The first variant can be used as an lvalue. The enum stripType can take values:
Table 3-1. Possible enum stripType values
stripType | Meaning |
|---|---|
leading | Remove characters at beginning |
trailing | Remove characters at end |
both | Remove characters at both ends |
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;
Returns a substring representing the first occurence of the null-terminated string pointed to by "cs". The first variant can be used as an lvalue. Case sensitivity is according to the caseCompare argument; it defaults to RWCString::exact. If caseCompare is RWCString::ignoreCase then this function is incompatible with MBCS strings. This function is incompatible with cs strings with embedded nulls. This function may be incompatible with cs MBCS strings.
void toLower();
Changes all upper-case letters in self to lower-case, using the standard C library facilities declared in <ctype.h>.This function is incompatible with MBCS strings.
void toUpper();
Changes all lower-case letters in self to upper-case, using the standard C library facilities declared in <ctype.h>. This function is incompatible with MBCS strings.
static unsigned hash(const RWCString& str);
Returns the hash value of str as returned by str.hash(RWCString::exact).
static size_t initialCapacity(size_t ic = 15);
Sets the minimum initial capacity of an RWCString, and returns the old value. The initial setting is 15 bytes. Larger values will use more memory, but result in fewer resizes when concatenating or reading strings. Smaller values will waste less memory, but result in more resizes.
static size_t maxWaste(size_t mw = 15);
Sets the maximum amount of unused space allowed in a string should it shrink, and returns the old value. The initial setting is 15 bytes. If more than mw bytes are wasted, then excess space will be reclaimed.
static size_t resizeIncrement(size_t ri = 16);
Sets the resize increment when more memory is needed to grow a string. Returns the old value. The initial setting is 16 bytes.
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&);
Logical equality and inequality. Case sensitivity is exact. This function is incompatible with const char* strings with embedded nulls. This function may be incompatible with const char* MBCS strings.
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&);
Comparisons are done lexicographically, byte by byte. Case sensitivity is exact. Use member collate() or strxfrm() for locale sensitivity. This function is incompatible with const char* strings with embedded nulls. This function may be incompatible with const char* MBCS strings.
RWCString operator+(const RWCString&, const RWCString&); RWCString operator+(const char*, const RWCString&); RWCString operator+(const RWCString&, const char* );
Concatenation operators. This function is incompatible with const char* strings with embedded nulls. This function may be incompatible with const char* MBCS strings.
ostream& operator<<(ostream& s, const RWCString&);
Output an RWCString on ostream s.
istream& operator>>(istream& s, RWCString& str);
Calls str.readToken(s). That is, a token is read from the input stream s. This function is incompatible with MBCS strings.
RWvostream& operator<<(RWvostream&, const RWCString& str); RWFile& operator<<(RWFile&, const RWCString& str);
Saves string str to a virtual stream or RWFile, respectively.
RWvistream& operator>>(RWvistream&, RWCString& str); RWFile& operator>>(RWFile&, RWCString& str);
Restores a string into str from a virtual stream or RWFile, respectively, replacing the previous contents of str.
RWCString strXForm(const RWCString&);
Returns the result of applying ::strxfrm() to the argument string, to allow quicker collation than RWCString::collate(). Provided only on platforms that provide ::strxfrm(). This function is incompatible with strings with embedded nulls.
RWCString toLower(const RWCString& str);
Returns a version of str where all upper-case characters have been replaced with lower-case characters. Uses the standard C library function tolower(). This function is incompatible with MBCS strings.
RWCString toUpper(const RWCString& str);
Returns a version of str where all lower-case characters have been replaced with upper-case characters. Uses the standard C library function toupper(). This function is incompatible with MBCS strings.
The class RWCSubString allows some subsection of an RWCString to be addressed by defining a starting position and an extent. For example the 7th through the 11th elements, inclusive, would have a starting position of 7 and an extent of 5. The specification of a starting position and extent can also be done in your behalf by such functions as RWCString::strip() or the overloaded function call operator taking a regular expression as an argument. There are no public constructors —RWCSubStrings are constructed by various functions of the RWCString class and then destroyed immediately.
A zero length substring is one with a defined starting position and an extent of zero. It can be thought of as starting just before the indicated character, but not including it. It can be used as an lvalue. A null substring is also legal and is frequently used to indicate that a requested substring, perhaps through a search, does not exist. A null substring can be detected with member function isNull(). However, it cannot be used as an lvalue.
#include <rw/cstring.h>
#include <rw/rstream.h>
main(){
RWCString s("What I tell you is true.");
// Create a substring and use it as an lvalue:
s(19, 0) = "three times ";
cout << s << endl;
} |
Program Output:
What I tell you is three times true. |
RWCSubString& operator=(const RWCString&);
Assignment from an RWCString. The statements:
RWCString a;
RWCString b;
...
b(2, 3) = a;
will copy a's data into the substring b(2,3). The number of elements need not match: if they differ, b will be resized appropriately. Sets self's extent to be the length of the assigned RWCString. If self is the null substring, then the statement has no effect. Returns a reference to self.
RWCSubString& operator=(const RWCSubString&);
Assignment from an RWCSubString. The statements:
RWCString a;
RWCString b;
...
b(2, 3) = a(5,5);
will copy 5 characters of a's data into the substring b(2,3). The number of elements need not match: if they differ, b will be resized appropriately. Sets self's extent to be the extent of the assigned RWCSubString. If self is the null substring, then the statement has no effect. Returns a reference to self.
RWCSubString& operator=(const char*);
Assignment from a character string. Example:
RWCString str("Mary had a lamb");
char dat[] = "Perrier";
str(11,4) = dat; // "Mary had a Perrier"
Note that the number of characters selected need not match: if they differ, str will be resized appropriately. Sets self's extent to be the strlen() of the assigned character string. If self is the null substring, then the statement has no effect. Returns a reference to self.
char& operator[](size_t i); char operator[](size_t i) const;
Returns the ith character of the substring. The first variant can be used as an lvalue, the second cannot. The index i must be between zero and the length of the substring, less one. Bounds checking is performed: if the index is out of range, then an exception of type RWBoundsErr will occur.
char& operator()(size_t i); char operator()(size_t i) const;
Returns the ith character of the substring. The first variant can be used as an lvalue, the second cannot. The index i must be between zero and the length of the substring, less one. Bounds checking is enabled by defining the pre-processor macro RWBOUNDS_CHECK before including <rw/cstring.h>. In this case, if the index is out of range, then an exception of type RWBoundsErr will occur.
RWBoolean isNull() const;
Returns TRUE if this is a null substring.
size_t length() const;
Returns the extent (i.e., length) of the RWCSubString.
RWBoolean operator!() const;
Returns TRUE if this is a null substring.
size_t start() const;
Returns the starting element of the RWCSubString.
void toLower();
Changes all upper-case letters in self to lower-case. Uses the standard C library function tolower().
void toUpper();
Changes all lower-case letters in self to upper-case. Uses the standard C library function toupper().
RWBoolean operator==(const RWCSubString&, const RWCSubString&); RWBoolean operator==(const RWCString&, const RWCSubString&); RWBoolean operator==(const RWCSubString&, const RWCString& ); RWBoolean operator==(const char*, const RWCSubString&); RWBoolean operator==(const RWCSubString&, const char* );
Returns TRUE if the substring is lexicographically equal to the character string or RWCString argument. Case sensitivity is exact.
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* );
Returns the negation of the respective operator==().
#include <rw/ctoken.h>
RWCString str("a string of tokens");
RWCTokenizer(str); // Lex the above string |
Class RWCTokenizer is designed to break a string up into separate tokens, delimited by an arbitrary "white space." It can be thought of as an iterator for strings and as an alternative to the ANSI C function strtok() which has the unfortunate side effect of changing the string being tokenized.
#include <rw/ctoken.h>
#include <rw/rstream.h>
main(){
RWCString a("Something is rotten in the state of Denmark");
RWCTokenizer next(a); // Tokenize the string a
RWCString token; // Will receive each token
// Advance until the null string is returned:
while (!(token=next()).isNull())
cout << token << "\n";
} |
Program Output:
Something
is
rotten
in
the
state
of
Denmark |
RWCSubString operator();
Advance to the next token and return it as a substring. The tokens are delimited by any of the four characters in " \t\n\0". (space, tab, newline and null).
RWCSubString operator()(const char* s);
Advance to the next token and return it as a substring. The tokens are delimited by any character in s, or any embedded null.
RWCSubString operator()(const char* s,size_t num);
Advance to the next token and return it as a substring. The tokens are delimited by any of the first num characters in s. Buffer s may contain nulls, and must contain at least num characters. Tokens will not be delimited by nulls unless s contains nulls.
Class RWDate represents a date, stored as a Julian day number. The member function isValid() can be used to determine whether an RWDate is a valid date. For example, isValid() would return FALSE for the date 29 February 1991 because 1991 is not a leap year. See "Using Class RWDate" in the Tools.h++ User's Guide.
RWDate's can be converted to and from RWTime's, and to and from the Standard C library type struct tm defined in <time.h>.
Note that using a 2-digit year specifier in your code may lead to less-than-perfect behavior at the turn of the century. We urge you to create programs that are "millenially correct" by using 4-digit year specifiers.
Note that because the default constructor for this class creates an instance holding the current date, constructing a large array of RWDate may be slow.
RWDate v[5000]; // Figures out the current date 5000 times |
Those with access to the Standard C++ Library-based versions of the Tools.h++ template collections should consider the following:
// Figures out the current date just once: RWTValOrderedVector<RWDate> v(5000, RWDate()); |
Thanks to the smart allocation scheme of the standard collections, the above declaration will result in only one call to the default constructor followed by 5000 invocations of the copy constructor. In the case of RWDate, the copy constructor amounts to an assignment of one long to another, resulting in faster creation than the simple array.
#include <rw/rwdate.h>
#include <rw/rstream.h>
main(){
// Today's date
RWDate d;
// Last Sunday's date:
RWDate lastSunday = d.previous("Sunday");
cout << d << endl << lastSunday << endl;
} |
Program Output:
03/22/91 03/17/91 |
RWDate();
Default constructor. Constructs an RWDate with the present date.
RWDate(const RWDate&);
Copy constructor.
RWDate(unsigned day, unsigned year);
Constructs an RWDate with a given day of the year and a given year. The member function isValid() can be used to test whether the results are a valid date.
RWDate(unsigned day, unsigned month, unsigned year);
Constructs an RWDate with the given day of the month, month of the year, and year. Days should be 1-31, months should be 1–12, and the year may be specified as (for example) 1990, or 90. The member function isValid() can be used to test whether the results are a valid date.
RWDate(unsigned day, const char* mon, unsigned year, const RWLocale& locale = RWLocale::global());
Constructs an RWDate with the given day of the month, month and year. The locale argument is used to convert the month name. Days should be 1-31, months may be specified as (for example): January, JAN, or Jan, and the year may be specified as (for example) 1990, or 90. The member function isValid() can be used to test whether the results are a valid date.
RWDate(istream& s,const RWLocale& locale = RWLocale::global());
A full line is read, and converted to a date by the locale argument. The member function isValid() must be used to test whether the results are a valid date. Because RWLocale cannot rigorously check date input, dates created in this way should also be reconfirmed by the user.
RWDate(const RWCString& str, const RWLocale& locale = RWLocale::global());
The string str is converted to a date. The member function isValid() must be used to test whether the results are a valid date. Because RWLocale cannot rigorously check date input, dates created in this way should also be reconfirmed by the user.
RWDate(const RWTime& t, const RWZone& zone = RWZone::local());
Constructs an RWDate from an RWTime. The time zone used defaults to local. The member function isValid() must be used to test whether the results are a valid date.
RWDate(const struct tm*);
Constructs an RWDate from the contents of the struct tm argument members tm_year, tm_mon, and tm_mday. Note that the numbering of months and years used in struct tm differs from that used for RWDate and RWTime operations. struct tm is declared in the standard include file <time.h>.
RWDate(unsigned long jd);
Construct a date from the Julian Day number jd. Note that it is possible to construct a valid RWDate which represents a day previous to the beginning of the Gregorian calendar for some locality. Rogue Wave doesn't know the specifics for your locality, so will not enforce an arbitrary cutoff for "validity."
RWDate& operator=(const RWDate&);
Assignment operator.
RWDate operator++();
Prefix increment operator. Adds one day to self, then return the result.
RWDate operator--();
Prefix decrement operator. Subtracts one day from self, then returns the result.
RWDate operator++(int);
Postfix increment operator. Adds one day to self, returning the initial value.
RWDate operator--(int);
Postfix decrement operator. Subtracts one day from self, returning the initial value.
RWDate& operator+=(unsigned long s);
Adds s days to self, returning self.
RWDate& operator-=(unsigned long s);
Substracts s days from self, returning self.
RWCString asString(char format = `x', const RWLocale& = RWLocale::global()) const;
Returns the date as a string, formatted by the RWLocale argument. Formats are as defined in the standard C library function strftime().
RWCString asString(const char* format, const RWLocale& = RWLocale::global()) const;
Returns the date as a string, formatted by the RWLocale argument. Formats are as defined in the standard C library function strftime().
RWBoolean between(const RWDate& a, const RWDate& b) const;
Returns TRUE if this RWDate is between a and b, inclusive.
size_t binaryStoreSize() const;
Returns the number of bytes necessary to store the object using the global function
RWFile& operator<<(RWFile&, const RWDate&);
int compareTo(const RWDate* d) const;
Compares self to the RWDate pointed to by d and returns:
0 if self == *d;
1 if self > *d;
–1 if self < *d.
unsigned day() const;
Returns the day of the year (1-366) for this date.
unsigned dayOfMonth() const;
Returns the day of the month (1-31) for this date.
void extract(struct tm*) const;
Returns with the struct tm argument filled out completely, with the time members set to 0 and tm_isdst set to -1. Note that the encoding for months and days of the week used in struct tm differs from that used elsewhere in RWDate. If the date is invalid, all fields are set to -1.
unsigned firstDayOfMonth() const;
Returns the day of the year (1-366) corresponding to the first day of this RWDate's month and year.
unsigned firstDayOfMonth(unsigned month) const;
Returns the day of the year (1-366) corresponding to the first day of the month month (1–12) in this RWDate's year.
unsigned hash() const;
Returns a suitable hashing value.
RWBoolean isValid() const;
Returns TRUE if this is a valid date, FALSE otherwise.
The following two functions are provided as a service to users who need to manipulate the date representation directly. The julian day number is not the Julian date!. The julian day number is calculated using Algorithm 199 from Communications of the ACM, Volume 6, No. 8, (Aug. 1963), p. 444 and is valid for any valid Gregorian date in the Gregorian calendar. The Gregorian calendar was first introduced on Sep. 14, 1752, and was adopted at various times in various places.
unsigned long julian() const;
Returns the value of the julian day number.
void julian(unsigned long j);
Changes the value of the julian day number to j.
RWBoolean leap() const;
Returns TRUE if the year of this RWDate is a leap year.
RWDate max(const RWDate& t) const;
Returns the later date of self or t.
RWDate min(const RWDate& t) const;
Returns the earlier date of self or t.
unsigned month() const;
Returns the month (1–12) for this date.
RWCString monthName(const RWLocale& = RWLocale::global()) const;
Returns the name of the month for this date, according to the optional RWLocale argument.
RWDate next(unsigned dayNum) const;
Returns the date of the next numbered day of the week, where Monday = 1, ..., Sunday = 7. The variable dayNum must be between 1 and 7, inclusive.
RWDate next(const char* dayName, const RWLocale& = RWLocale::global()) const;
Returns the date of the next dayName (for example, the date of the previous Monday) The weekday name is interpreted according to the RWLocale argument.
RWDate previous(unsigned dayNum) const;
Returns the date of the previous numbered day of the week, where Monday = 1, ..., Sunday = 7. The variable dayNum must be between 1 and 7, inclusive.
RWDate previous(const char* dayName, const RWLocale& = RWLocale::global()) const;
Returns the date of the previous dayName (for example, the date of the previous Monday) The weekday name is interpreted according to the RWLocale argument.
RWCString weekDayName(const RWLocale& = RWLocale::global()) const;
Returns the name of the day of the week for this date, according to the optional RWLocale argument.
unsigned weekDay() const;
Returns the number of the day of the week for this date, where Monday = 1, ..., Sunday = 7.
unsigned year() const;
Returns the year of this date.
static unsigned dayOfWeek(const char* dayName, const RWLocale& = RWLocale::global());
Returns the number of the day of the week corresponding to the given dayName. "Monday" = 1, ..., "Sunday" = 7. Names are interpreted by the RWLocale argument. Returns 0 if no match is found.
static unsigned daysInMonthYear(unsigned month, unsigned year);
Returns the number of days in a given month and year. Returns 0 if month is not between 1 and 12 inclusive.
static unsigned daysInYear(unsigned year);
Returns the number of days in a given year.
static RWBoolean dayWithinMonth(unsigned monthNum, unsigned dayNum, unsigned year);
Returns TRUE if a day (1-31) is within a given month in a given year.
static unsigned hash(const RWDate& d);
Returns the hash value of d as returned by d.hash().
static unsigned indexOfMonth(const char* monthName, const RWLocale& = RWLocale::global());
Returns the number of the month (1–12) corresponding to the given monthName. Returns 0 for no match.
static unsigned long jday(unsigned mon, unsigned day, unsigned year);
Returns the Julian day corresponding to the given month (1–12), day (1-31) and year. Returns zero (0) if the date is invalid.
static RWCString nameOfMonth(unsigned monNum, const RWLocale& = RWLocale::global());
Returns the name of month monNum (January = 1, ..., December = 12), formatted for the given locale.
static RWBoolean leapYear(unsigned year);
Returns TRUE if a given year is a leap year.
static RWDate now();
Returns today's date.
static RWCString weekDayName(unsigned dayNum, const RWLocale& = RWLocale::global());
Returns the name of the day of the week dayNum (Monday = 1, ..., Sunday = 7), formatted for the given locale.
RWBoolean operator<(const RWDate& d1, const RWDate& d2);
Returns TRUE if the date d1 is before d2.
RWBoolean operator<=(const RWDate& d1, const RWDate& d2);
Returns TRUE if the date d1 is before or the same as d2.
RWBoolean operator>(const RWDate& d1, const RWDate& d2);
Returns TRUE if the date d1 is after d2.
RWBoolean operator>=(const RWDate& d1, const RWDate& d2);
Returns TRUE if the date d1 is after or the same as d2.
RWBoolean operator==(const RWDate& d1, const RWDate& d2);
Returns TRUE if the date d1 is the same as t2.
RWBoolean operator!=(const RWDate& d1, const RWDate& d2);
Returns TRUE if the date d1 is not the same as d2.
RWDate operator+(const RWDate& d, unsigned long s); RWDate operator+(unsigned long s, const RWDate& d);
Returns the date s days in the future from the date d.
unsigned long operator-(const RWDate& d1, const RWDate& d2);
If d1>d2, returns the number of days between d1 and d2. Otherwise, the result is implementation defined.
RWDate operator-(const RWDate& d, unsigned long s);
Returns the date s days in the past from d.
ostream& operator<<(ostream& s, const RWDate& d);
Outputs the date d on ostream s, according to the locale imbued in the stream (see class RWLocale), or by RWLocale::global() if none.
istream& operator>>(istream& s, RWDate& t);
Reads t from istreams. One full line is read, and the string contained is converted according to the locale imbued in the stream (see class RWLocale), or by RWLocale::global() if none. The function RWDate::isValid() must be used to test whether the results are a valid date.
RWvostream& operator<<(RWvostream&, const RWDate& date); RWFile& operator<<(RWFile&, const RWDate& date);
Saves the date date to a virtual stream or RWFile, respectively.
RWvistream& operator>>(RWvistream&, RWDate& date); RWFile& operator>>(RWFile&, RWDate& date);
Restores the date into date from a virtual stream or RWFile, respectively, replacing the previous contents of date.
RWDDEstreambuf ->- RWCLIPstreambuf ->- streambuf |
#include <rw/winstrea.h> #include <iostream.h> iostream str( new RWDDEstreambuf(CF_TEXT, TRUE, TRUE, TRUE) ) ; |
Class RWDDEstreambuf is a specialized streambuf that gets and puts sequences of characters to Microsoft Windows global memory that has been allocated with the GMEM_DDESHARE flag. It can be used to exchange data through the Windows Dynamic Data Exchange (DDE) facility.
The class has two modes of operation: dynamic and static. In dynamic mode, memory is allocated and reallocated on an as-needed basis. If too many characters are inserted into the internal buffer for its present size, then it will be resized and old characters copied over into any new memory as necessary. This is transparent to the user. It is expected that this mode would be used primarily by the DDE server. In static mode, the buffer streambuf is constructed from a specific piece of memory. No reallocations will be done. It is expected that this mode would be used primarily by the DDE client.
In dynamic mode, the RWDDEstreambuf "owns" any allocated memory until the member function str() is called, which "freezes" the buffer and returns an unlocked Windows handle to it. The effect of any further insertions is undefined. Until str() has been called, it is the responsibility of the RWDDEstreambuf destructor to free any allocated memory. After the call to str(), it becomes the user's responsibility.
In static mode, the user always has the responsibility for freeing the memory handle. However, because the constructor locks and dereferences the handle, you should not free the memory until either the destructor or str() has been called, either of which will unlock the handle.
Note that although the user may have the "responsibility" for freeing the memory, whether it is the client or the server that actually does the call to GlobalFree() will depend on the DDE "release" flag.
This is an example of how the class might be used by a DDE server.
#include <rw/winstrea.h>
#include <iostream.h>
#include <windows.h>
#include <dde.h>
BOOL
postToDDE(HWND hwndServer, HWND hwndClient) {
RWDDEstreambuf* buf =
new RWDDEstreambuf(CF_TEXT, TRUE, TRUE, TRUE);
ostream ostr(buf);
double d = 12.34;
ostr << "Some text to be exchanged through the DDE.\n";
ostr << "The double you requested is: " << d << endl;
ostr.put(0); // Include the terminating null
// Lock the streambuf, get its handle:
HANDLE hMem = buf->str();
// Get an identifying atom:
ATOM aItem = GlobalAddAtom("YourData");
if(!PostMessage(hwndClient, WM_DDE_DATA, hwndServer,
MAKELONG(hMem, aItem))){
// Whoops! The message post failed, perhaps because
// the client terminated. Now we are responsible
// for deallocating the memory:
if( hMem != NULL )
GlobalFree(hMem);
GlobalDeleteAtom(aItem);
return FALSE;
}
return TRUE;
} |
The handle of the DDE server is passed in as parameter hwndServer, the handle of the client as parameter hwndClient. An ostream is created, using an RWDDEstreambuf as its associated streambuf. The results can be used much like any other ostream, such as cout, except that characters will be inserted into Windows global memory, from where they can be transferred through the DDE. Note the parameters used in the constructor. These should be studied below as they have important ramifications on how memory allocations are handled through the DDE. In particular, parameter fRelease, if TRUE, states that the client will be responsible for deallocating the memory when done. The defaults also specify fAckReqTRUE, meaning that the client will acknowledge receiving the message: you must be prepared to receive it.
Some text and a double is inserted into the ostream. Member function str() is then called which unlocks and returns a Windows HANDLE. Once we have called str(), we are responsible for this memory and must either free it when done, or pass on that responsibility to someone else. In this case, it will be passed on to the client.
An atom is then constructed to identify the data. The DDE data, along with its identifying atom, is then posted. If the post fails, then we have been unable to foist our responsbility for the global memory onto someone else and will have to free it (along with the atom) ourselves.
RWDDEstreambuf(WORD cfFormat = CF_TEXT, BOOL fResponse = TRUE BOOL fAckReq = TRUE BOOL fRelease = TRUE);
Constructs an empty RWDDEstreambuf in dynamic mode. The results can be used anywhere any other streambuf can be used. Memory to accomodate new characters will be allocated as needed.
The four parameters are as defined by the Windows Reference, Volume 2 (in particular, see the section DDE Message Directory). Parameter cfFormat specifies the format of the data being inserted into the streambuf. These formats are the same as used by SetClipboardData(). If a specializing virtual streams class such as RWbostream or RWpostream is used to perform the actual character insertions instead of a simple ostream, the format may not be so simple. In this case, the user might want to register his or her own format, using the Windows function RegisterClipboardFormat().
For the meaning of the other three parameters see below, and/or the Windows reference manuals.
RWDDEstreambuf(HANDLE hMem);
Constructs an RWDDEstreambuf in static mode, using the memory block with global handle hMem. The effect of gets and puts beyond the size of this block is unspecified. The format of the DDE transfer, and the specifics of DDE acknowledgments, memory allocations, etc., can be obtained by using the member functions defined below.
~RWDDEstreambuf();
If member function str() has not been called, the destructor unlocks the handle and, if in dynamic mode, also frees it.
Because RWDDEstreambuf inherits from streambuf, any of the latter's member functions can be used. Furthermore, RWDDEstreambuf has been designed to be analogous to streambuf. However, note that the return type of str() is a HANDLE, rather than a char*.
BOOL ackReq() const;
Returns whether this DDE exchange requests an acknowledgement. See the Windows Reference, Volume 2, for more information.
WORD format() const;
Returns the format of this DDE exchange (e.g., CF_TEXT for text exchange, etc.). See the Windows Reference, Volume 2, for more information.
BOOL release() const;
Returns TRUE if the client is responsible for the release of of the memory returned by str(). See the Windows Reference, Volume 2, for more information.
BOOL response() const;
Returns TRUE if this data is in response to a WM_DDE_REQUEST message. Otherwise, it is in response to a WM_DDE_ADVISE message. See the Windows Reference, Volume 2, for more information.
HANDLE str();
Returns an (unlocked) HANDLE to the global memory being used. The RWDDEstreambuf should now be regarded as "frozen": the effect of inserting any more characters is undefined. If the RWDDEstreambuf was constructed in dynamic mode, and nothing has been inserted, then the returned HANDLE may be NULL. If it was constructed in static mode, then the returned handle will be the handle used to construct the RWDDEstreambuf.
RWDiskPageHeap ->- RWBufferedPageHeap ->- RWVirtualPageHeap |
#include <rw/diskpage.h>
unsigned nbufs;
unsigned pagesize;
RWDiskPageHeap heap("filename", nbufs, pagesize) ; |
Class RWDiskPageHeap is a specializing type of buffered page heap. It swaps its pages to disk as necessary.
In this example, 100 nodes of a linked list are created and strung together. The list is then walked, confirming that it contains 100 nodes. Each node is a single page. The "pointer" to the next node is actually the handle for the next page.
#include <rw/diskpage.h>
#include <rw/rstream.h>
struct Node {
int key;
RWHandlenext;
};
RWHandle head = 0;
const int N = 100; // Exercise 100 Nodes
main() {
// Construct a disk-based page heap with page size equal
// to the size of Node and with 10 buffers:
RWDiskPageHeap heap(0, 10, sizeof(Node));
// Build the linked list:
for (int i=0; i<N; i++){
RWHandle h = heap.allocate();
Node* newNode = (Node*)heap.lock(h);
newNode->key = i;
newNode->next = head;
head = h;
heap.dirty(h);
heap.unlock(h);
}
// Now walk the list:
unsigned count = 0;
RWHandle nodeHandle = head;
while(nodeHandle){
Node* node = (Node*)heap.lock(nodeHandle);
RWHandle nextHandle = node->next;
heap.unlock(nodeHandle);
heap.deallocate(nodeHandle);
nodeHandle = nextHandle;
count++;
}
cout << "List with " << count << " nodes walked.\n";
return 0;
} |
Program Output:
List with 100 nodes walked. |
RWDiskPageHeap(const char* filename = 0, unsigned nbufs = 10, unsigned pgsize = 512);
Constructs a new disk-based page heap. The heap will use a file with filename filename, otherwise it will negotiate with the operating system for a temporary filename. The number of buffers, each the size of the page size, will be nbufs. No more than this many pages can be locked at any one time. The size of each page is given by pgsize. To see whether a valid RWDiskPageHeap has been constructed, call member function isValid().
virtual ~RWDiskPageHeap();
Returns any resources used by the disk page heap back to the operating system. All pages should have been deallocated before the destructor is called.
virtual RWHandle allocate();
Redefined from class RWVirtualPageHeap. Allocates a page off the disk page heap and returns a handle for it. If there is no more space (for example, the disk is full) then returns zero.
virtual void deallocate(RWHandle h);
Redefined from class RWBufferedPageHeap. Deallocate the page associated with handle h. It is not an error to deallocate a zero handle.
virtual void dirty(RWHandle h);
Inherited from RWBufferedPageHeap.
RWBoolean isValid() const;
Returns TRUE if this is a valid RWDiskPageHeap.
virtual void* lock(RWHandle h);
Inherited from RWBufferedPageHeap.
virtual void unlock(RWHandle h);
Inherited from RWBufferedPageHeap.
RWDlistCollectables ->- RWSequenceable ->- RWCollection ->-... ...->- RWCollectable |
Class RWDlistCollectables represents a group of ordered items, not accessible by an external key. Duplicates are allowed. The ordering of elements is determined externally, generally by the order of insertion and removal. An object stored by RWDlistCollectables must inherit abstract base class RWCollectable.
Class RWDlistCollectables is implemented as a doubly-linked list, which allows for efficient insertion and removal, as well as for movement in either direction.
RWDlistCollectables();
Constructs an empty doubly-linked list.
RWDlistCollectables (RWCollectable* a);
Constructs a linked list with a single item a.
RWBoolean operator==(const RWDlistCollectables& d) const;
Returns TRUE if self and d have the same number of items and if for every item in self, the corresponding item in the same position in disEqual to it.
virtual Collectable* append(RWCollectable*);
Redefined from RWSequenceable. Inserts the item at the end of the collection and returns it. Returns nil if the insertion was unsuccesful.
virtual void apply(RWapplyCollectable ap, void*);
Redefined from class RWCollection to apply the user-supplied function pointed to by ap to each member of the collection, in order, from first to last.
virtual RWCollectable*& at(size_t i); virtual const RWCollectable* at(size_t i) const;
Redefined from class RWSequenceable. The index must be between zero and the number of items in the collection less one, or an exception of type RWBoundsErr will occur. Note that for a linked list, these functions must traverse all the links, making them not particularly efficient.
virtual RWspace binaryStoreSize() const;
Inherited from class RWCollection.
virtual void clear();
Redefined from class RWCollection.
virtual void clearAndDestroy();
Inherited from class RWCollection.
virtual int compareTo(const RWCollectable* a) const;
Inherited from class RWCollectable.
virtual RWBoolean contains(const RWCollectable* target) const;
Inherited from class RWCollection.
RWBoolean containsReference(const RWCollectable* e) const;
Returns true if the list contains an item that is identical to the item pointed to by e (that is, that has the address e).
virtual size_t entries() const;
Redefined from class RWCollection.
virtual RWCollectable* find(const RWCollectable* target) const;
Redefined from class RWCollection. The first item that isEqual to the item pointed to by target is returned, or nil if no item is found.
RWCollectable* findReference(const RWCollectable* e) const;
Returns the first item that is identical to the item pointed to by e (that is, that has the address e), or nil if none is found.
virtual RWCollectable* first() const;
Redefined from class RWSequenceable. Returns the item at the beginning of the list.
RWCollectable* get();
Returns and removes the item at the beginning of the list.
virtual unsigned hash() const;
Inherited from class RWCollectable.
virtual size_t index(const RWCollectable* c) const;
Redefined from class RWSequenceable. Returns the index of the first item that isEqual to the item pointed to by c, or RW_NPOS if there is no such index.
virtual RWCollectable* insert(RWCollectable* c);
Redefined from class RWCollection. Adds the item to the end of the collection and returns it. Returns nil if the insertion was unsuccessful.
void insertAt(size_t indx, RWCollectable* e);
Redefined from class RWSequenceable. Adds a new item to the collection at position indx. The item previously at position i is moved to i+1, etc. The index indx must be between 0 and the number of items in the collection, or an exception of type RWBoundsErr will occur.
virtual RWClassID isA() const;
Redefined from class RWCollectable to return __RWDLISTCOLLECTABLES.
virtual RWBoolean isEmpty() const;
Redefined from class RWCollection.
virtual RWCollectable* last() const;
Redefined from class RWSequenceable. Returns the item at the end of the list.
virtual size_t occurrencesOf(const RWCollectable* target) const;
Redefined from class RWCollection. Returns the number of items that isEqual to the item pointed to by target.
size_t occurrencesOfReference(const RWCollectable* e) const;
Returns the number of items that are identical to the item pointed to by e (that is, that have the address e).
virtual RWCollectable* prepend(RWCollectable*);
Redefined from class RWSequenceable. Adds the item to the beginning of the collection and returns it. Returns nil if the insertion was unsuccessful.
virtual RWCollectable* remove(const RWCollectable* target);
Redefined from class RWCollection. Removes and returns the first item that isEqual to the item pointed to by target. Returns nil if there is no such item.
virtual void removeAndDestroy(const RWCollectable* target);
Inherited from class RWCollection.
RWCollectable* removeReference(const RWCollectable* e);
Removes and returns the first item that is identical to the item pointed to by e (that is, that has the address e). Returns nil if there is no such item.
virtual void restoreGuts(RWvistream&); virtual void restoreGuts(RWFile&); virtual void saveGuts(RWvostream&) const; virtual void saveGuts(RWFile&) const;
Inherited from class RWCollection.
RWStringID stringID();
(acts virtual) Inherited from class RWCollectable.
RWDlistCollectablesIterator ->- RWIterator |
Iterator for class RWDlistCollectables. Traverses the linked-list from the first (head) to the last (tail) item. Functions are provided for moving in either direction.
As with all Rogue Wave iterators, the "current item" is undefined immediately after construction — you must define it by using operator() or some other (valid) operation.
Once the iterator has advanced beyond the end of the collection it is no longer valid — continuing to use it will bring undefined results.
RWDlistCollectablesIterator (RWDlistCollectables& d);
Construct an RWDlistCollectablesIterator from an RWDlistCollectables. Immediately after construction, the position of the iterator is undefined.
virtual RWCollectable* operator()();
Redefined from class RWIterator. Advances the iterator to the next item and returns it. Returns nil when the end of the list is reached.
void operator++();
Advances the iterator one item.
void operator--();
Moves the iterator back one item.
void operator+=(size_t n);
Advances the iterator n items.
void operator-=(size_t n);
Moves the iterator back n items.
RWBoolean atFirst() const;
Returns TRUE if the iterator is at the beginning of the list, otherwise FALSE;
RWBoolean atLast() const;
Returns TRUE if the iterator is at the end of the list, otherwise FALSE;
virtual RWCollectable* findNext(const RWCollectable* target);
Redefined from class RWIterator. Moves iterator to the next item which isEqual to the item pointed to by target and returns it. If no item is found, returns nil and the position of the iterator will be undefined.
RWCollectable* findNextReference(const RWCollectable* e);
Moves iterator to the next item which is identical to the item pointed to by e (that is, that has address e) and returns it. If no item is found, returns nil and the position of the iterator will be undefined.
RWCollectable* insertAfterPoint(RWCollectable* a);
Insert item a after the current cursor position and return the item. The cursor's position will be unchanged.
virtual RWCollectable* key() const;
Redefined from class RWIterator. Returns the item at the current iterator position.
RWCollectable* remove();
Removes and returns the item at the current cursor position. Afterwards, the iterator will be positioned at the previous item in the list.
RWCollectable* removeNext(const RWCollectable* target);
Moves iterator to the next item in the list which isEqual to the item pointed to by target, removes it from the list and returns it. Afterwards, the iterator will be positioned at the previous item in the list. If no item is found, returns nil and the position of the iterator will be undefined.
RWCollectable* removeNextReference(const RWCollectable* e);
Moves iterator to the next item in the list which is identical to the item pointed to by e (that is, that has address e), removes it from the list and returns it. Afterwards, the iterator will be positioned at the previous item in the list. If no item is found, returns nil and the position of the iterator will be undefined.
virtual void reset();
Redefined from class RWIterator. Resets the iterator. Afterwards, the position of the iterator will be undefined.
void toFirst();
Moves the iterator to the beginning of the list.
void toLast();
Moves the iterator to the end of the list.
...->- ios RWeistream ->- RWbistream... ...->- RWvistream ->- RWvios |
#include <rw/estream.h>
RWeistream estr(cin); // Construct an RWeistream,
// using cin's streambuf |
Class RWeistream specializes the base class RWbistream to restore values previously stored by RWeostream.
The endian streams, RWeistream and RWeostream, offer an efficient compromise between the portable streams (RWpistream, RWpostream) and the binary streams (RWbistream, RWbostream). By compensating for differences in big-endian vs. little-endian formats, as well as sizes of the various integral types, the endian streams offer portability without incurring the stream-size overhead of translating values into a series of printable characters. For example, data stored in little-endian format by an RWeostream object in a DOS program can be retrieved by an RWeistream object on any of several machines, regardless of its native endian format or the sizes of its integral types. Endian streams will work properly when shared among a group of platforms that:
Share a common size and representation (apart from endian format) for types float and double;
Use two's complement format for negative integral values.
As with the portable streams, care must be taken when storing or retrieving variables of type char. Endian stream methods treat chars as numbers except where the method description explicitly states that the char is being treated, instead, as a character. See the entry for RWpostream for an example of this distinction. Data stored in an integral type on one platform may be too large to fit into that type on a receiving platform. If so, the RWeistream's failbit will be set.
Endian streams can be interrogated as to the stream state using member functions good(), bad(), eof(), etc.
See RWeostream for an example of how the file "data.dat" might be created.
#include <rw/estream.h>
#include <fstream.h>
main()
{
ifstream fstr("data.dat"); // Open an input file
RWeistream estr(fstr); // Construct an RWeistream from it
// (For DOS: RWeistream estr(fstr, ios::binary)
int i;
float f;
double d;
estr >> i; // Restore an int that was stored in binary,
// without regard to size or endian format.
estr >> f >> d; // Restore a float & double without regard to
// endian formats.
}
|
RWeistream(streambuf* s);
Construct an RWeistream from the streambuf s. For DOS, this streambuf must have been created in binary mode. Throw exception RWStreamErr if not a valid endian stream.
RWeistream(istream& str);
Construct an RWeistream using the streambuf associated with the istream str. For DOS, the str must have been opened in binary mode. Throw exception RWStreamErr if not a valid endian stream.
virtual int get(); virtual RWvistream& get(char& c); virtual RWvistream& get(unsigned char& c); virtual RWvistream& get(char* v, size_t N); virtual RWvistream& get(unsigned char* v, size_t N);
Inherited from class RWbistream.
virtual RWvistream& get(wchar_t& wc);
Redefined from class RWbistream. Get the next wchar_t from the input stream and store it in wc, compensating for any differences in size or endian format between the stream and the current environment. Set the failbit if the value in the stream is too large to be stored in wc.
virtual RWvistream& get(wchar_t* v, size_t N);
Redefined from class RWbistream. Get a vector of wchar_ts and store it in the array beginning at v, compensating for any differences in size or endian format between the stream and the current environment. If the restore stops prematurely, store whatever possible in v, and set the failbit. Also set the failbit if any values in the stream are too large to be stored in an element of v.
virtual RWvistream& get(double* v, size_t N);
Redefined from class RWbistream. Get a vector of doubles and store them in the array beginning at v, compensating for any difference in endian format between the stream and the current environment. If the restore stops prematurely, store whatever possible in v, and set the failbit.
virtual RWvistream& get(float* v, size_t N);
Redefined from class RWbistream. Get a vector of floats and store them in the array beginning at v, compensating for any difference in endian format between the stream and the current environment. If the restore stops prematurely, store whatever possible in v, and set the failbit.
virtual RWvistream& get(int* v, size_t N);
Redefined from class RWbistream. Get a vector of ints and store them in the array beginning at v, compensating for any differences in size or endian format between the stream and the current environment. If the restore stops prematurely, store whatever possible in v, and set the failbit. Also set the failbit if any values in the stream are too large to be stored in an element of v.
virtual RWvistream& get(long* v, size_t N);
Redefined from class RWbistream. Get a vector of longs and store them in the array beginning at v, compensating for any differences in size or endian format between the stream and the current environment. If the restore stops prematurely, store whatever possible in v, and set the failbit. Also set the failbit if any values in the stream are too large to be stored in an element of v.
virtual RWvistream& get(short* v, size_t N);
Redefined from class RWbistream. Get a vector of shorts and store them in the array beginning at v, compensating for any differences in size or endian format between the stream and the current environment. If the restore stops prematurely, store whatever possible in v, and set the failbit. Also set the failbit if any values in the stream are too large to be stored in an element of v.
virtual RWvistream& get(unsigned short* v, size_t N);
Redefined from class RWbistream. Get a vector of unsigned shorts and store them in the array beginning at v. If the restore stops prematurely, store whatever possible in v, and set the failbit. Also set the failbit if any values in the stream are too large to be stored in an element of v.
virtual RWvistream& get(unsigned int* v, size_t N);
Redefined from class RWbistream. Get a vector of unsigned ints and store them in the array beginning at v, compensating for any differences in size or endian format between the stream and the current environment. If the restore stops prematurely, store whatever possible in v, and set the failbit. Also set the failbit if any values in the stream are too large to be stored in an element of v.
virtual RWvistream& get(unsigned long* v, size_t N);
Redefined from class RWbistream. Get a vector of unsigned longs and store them in the array beginning at v, compensating for any differences in size or endian format between the stream and the current environment If the restore stops prematurely, store whatever possible in v, and set the failbit. Also set the failbit if any values in the stream are too large to be stored in an element of v.
virtual RWvistream& getString(char* s, size_t N);
Redefined from class RWbistream. Restores a character string from the input stream and stores it in the array beginning at s. The function stops reading at the end of the string or after N-1 characters, whichever comes first. If the latter, then the failbit of the stream will be set, and the remaining characters of the string will be extracted from the stream and thrown away. In either case, the string will be terminated with a null byte. If the size of the string is too large to be represented by a variable of type size_t in the current environment, the badbit of the stream will be set, and no characters will be extracted. Note that the elements of the string are treated as characters, not numbers.
virtual RWvistream& operator>>(char& c);
Redefined from class RWbistream. Get the next char from the input stream and store it in c. Note that c is treated as a character, not a number.
virtual RWvistream& operator>>(wchar_t& wc);
Redefined from class RWbistream. Get the next wchar_t from the input stream and store it in wc, compensating for any differences in size or endian format between the stream and the current environment. Set the failbit if the value in the stream is too large to be stored in wc.
virtual RWvistream& operator>>(double& d);
Redefined from class RWbistream. Get the next double from the input stream and store it in d, compensating for any difference in endian format between the stream and the current environment.
virtual RWvistream& operator>>(float& f);
Redefined from class RWbistream. Get the next float from the input stream and store it in f, compensating for any difference in endian format between the stream and the current environment.
virtual RWvistream& operator>>(int& i);
Redefined from class RWbistream. Get the next int from the input stream and store it in i, compensating for any differences in size or endian format between the stream and the current environment. Set the failbit if the value in the stream is too large to be stored in i.
virtual RWvistream& operator>>(long& l);
Redefined from class RWbistream. Get the next long from the input stream and store it in l, compensating for any differences in size or endian format between the stream and the current environment. Set the failbit if the value in the stream is too large to be stored in l.
virtual RWvistream& operator>>(short& s);
Redefined from class RWbistream. Get the next short from the input stream and store it in s, compensating for any differences in size or endian format between the stream and the current environment. Set the failbit if the value in the stream is too large to be stored in s.
virtual RWvistream& operator>>(unsigned char& c);
Redefined from class RWbistream. Get the next unsigned char from the input stream and store it in c. Note that c is treated as a character, not a number.
virtual RWvistream& operator>>(unsigned short& s);
Redefined from class RWbistream. Get the next unsigned short from the input stream and store it in s, compensating for any differences in size or endian format between the stream and the current environment. Set the failbit if the value in the stream is too large to be stored in s.
virtual RWvistream& operator>>(unsigned int& i);
Redefined from class RWbistream. Get the next unsigned int from the input stream and store it in i, compensating for any differences in size or endian format between the stream and the current environment. Set the failbit if the value in the stream is too large to be stored in i.
virtual RWvistream& operator>>(unsigned long& l);
Redefined from class RWbistream. Get the next unsigned long from the input stream and store it in l, compensating for any differences in size or endian format between the stream and the current environment. Set the failbit if the value in the stream is too large to be stored in l.
RWeostream::EndianstreamEndian();
Return the endian format (RWeostream::BigEndian or RWeostream::LittleEndian) of numeric values, as represented in the stream.
size_t streamSizeofInt();
Return the size of ints, as represented in the stream.
size_t streamSizeofLong();
Return the size of longs, as represented in the stream.
size_t streamSizeofShort();
Return the size of shorts, as represented in the stream.
size_t streamSizeofSizeT();
Return the size of size_ts, as represented in the stream.
size_t streamSizeofWchar();
Returns the size of wchar_ts, as represented in the stream.
... ->- ios
RWeostream...
... ->- RWbostream ->- RWvostream ->- RWvios |
#include <rw/estream.h> // Construct an RWeostream that uses cout's streambuf, // and writes out values in little-endian format: RWeostream estr(cout, RWeostream::LittleEndian); |
Class RWeostream specializes the base class RWbostream to store values in a portable binary format. The results can be restored via its counterpart, RWeistream.
See the entry for RWeistream for a general description of the endian stream classes.
See RWeistream for an example of how the file "data.dat" might be read.
#include <rw/estream.h>
#include <fstream.h>
main()
{
ofstream fstr("data.dat"); // Open an output file
RWeostream estr(fstr); // Construct an RWeostream from it
// (For DOS: RWeistream estr(fstr, ios::binary)
int i = 5;
float f = 22.1;
double d = -0.05;
estr << i; // Store an int, float, and double
estr << f << d; // using the native endian format
} |
enum RWeostream::Endian { LittleEndian, BigEndian, HostEndian }
Used to specify the format that RWeostreams should use to represent numeric values in the stream. HostEndian means to use the native format of the current environment.
RWeostream(streambuf* s, Endian fmt = HostEndian);
Construct an RWeostream from the streambuf s. Values placed into the stream will have an endian format given by fmt. For DOS, the streambuf must have been created in binary mode. Throw exception RWStreamErr if streambuf s is not empty.
RWeostream(ostream& str, Endian fmt = HostEndian);
Construct an RWeostream from the streambuf associated with the output stream str. Values placed into the stream will have an endian format given by fmt. For DOS, the str must have been opened in binary mode. Throw exception RWStreamErr if streambuf s is not empty.
virtual ~RWvostream();
This virtual destructor allows specializing classes to deallocate any resources that they may have allocated.
virtual RWvostream& flush();
Send the contents of the stream buffer to output immediately.
virtual RWvostream& operator<<(const char* s);
Redefined from class RWbostream. Store the character string starting at s to the output stream. The character string is expected to be null terminated. Note that the elements of s are treated as characters, not as numbers.
virtual RWvostream& operator<<(char c);
Redefined from class RWbostream. Store the charc to the output stream. Note that c is treated as a character, not a number.
virtual RWvostream& operator<<(wchar_t wc);
Redefined from class RWbostream. Store the wchar_twc to the output stream in binary, using the appropriate endian representation.
virtual RWvostream& operator<<(unsigned char c);
Redefined from class RWbostream. Store the unsigned charc to the output stream. Note that c is treated as a character, not a number.
virtual RWvostream& operator<<(double d);
Redefined from class RWbostream. Store the doubled to the output stream in binary, using the appropriate endian representation.
virtual RWvostream& operator<<(float f);
Redefined from class RWbostream. Store the floatf to the output stream in binary, using the appropriate endian representation.
virtual RWvostream& operator<<(int i);
Redefined from class RWbostream. Store the inti to the output stream in binary, using the appropriate endian representation.
virtual RWvostream& operator<<(unsigned int i);
Redefined from class RWbostream. Store the unsigned inti to the output stream in binary, using the appropriate endian representation.
virtual RWvostream& operator<<(long l);
Redefined from class RWbostream. Store the longl to the output stream in binary, using the appropriate endian representation.
virtual RWvostream& operator<<(unsigned long l);
Redefined from class RWbostream. Store the unsigned longl to the output stream in binary, using the appropriate endian representation.
virtual RWvostream& operator<<(short s);
Redefined from class RWbostream. Store the shorts to the output stream in binary, using the appropriate endian representation.
virtual RWvostream& operator<<(unsigned short s);
Redefined from class RWbostream. Store the unsigned shorts to the output stream in binary, using the appropriate endian representation.
virtual RWvostream& put(char c); virtual RWvostream& put(unsigned char c); virtual RWvostream& put(const char* p, size_t N);
Inherited from class RWbostream.
virtual RWvostream& put(wchar_t wc);
Redefined from class RWbostream. Store the wchar_t wc to the output stream in binary, using the appropriate endian representation.
virtual RWvostream& put(const wchar_t* p, size_t N);
Redefined from class RWbostream. Store the vector of wchar_ts starting at p to the output stream in binary, using the appropriate endian representation.
virtual RWvostream& put(const unsigned char* p, size_t N);
Redefined from class RWbostream. Store the vector of unsigned chars starting at p to the output stream in binary, using the appropriate endian representation.
virtual RWvostream& put(const short* p, size_t N);
Redefined from class RWbostream. Store the vector of shorts starting at p to the output stream in binary, using the appropriate endian representation.
virtual RWvostream& put(const unsigned short* p, size_t N);
Redefined from class RWbostream. Store the vector of unsigned shorts starting at p to the output stream in binary, using the appropriate endian representation.
virtual RWvostream& put(const int* p, size_t N);
Redefined from class RWbostream. Store the vector of ints starting at p to the output stream in binary, using the appropriate endian representation.
virtual RWvostream& put(const unsigned int* p, size_t N);
Redefined from class RWbostream. Store the vector of unsigned ints starting at p to the output stream in binary, using the appropriate endian representation.
virtual RWvostream& put(const long* p, size_t N);
Redefined from class RWbostream. Store the vector of longs starting at p to the output stream in binary, using the appropriate endian representation.
virtual RWvostream& put(const unsigned long* p, size_t N);
Redefined from class RWbostream. Store the vector of unsigned longs starting at p to the output stream in binary, using the appropriate endian representation.
virtual RWvostream& put(const float* p, size_t N);
Redefined from class RWbostream. Store the vector of floats starting at p to the output stream in binary, using the appropriate endian representation.
virtual RWvostream& put(const double* p, size_t N);
Redefined from class RWbostream. Store the vector of doubles starting at p to the output stream in binary, using the appropriate endian representation.
virtual RWvostream& putString(const char*s, size_t N);
Store the character string, including embedded nulls, starting at s to the output string.