RWAuditStreamBuffer

RWAuditStreamBuffer . streambuf

Synopsis

#include <rw/auditbuf.h>
#include <iostream.h>
RWAuditStreamBuffer buf(arguments)
ostream os(&buf); // may be used for ostreams
istream is(&buf); // or istreams of any kind

Description

Class RWAuditStreamBuffer is used to construct a stream, after which the RWAuditStreamBuffer instance will count all the bytes that pass through the stream. If constructed with a function pointer, RWAuditStreamBuffer will call that function with each byte that passes through the stream. The counting capacity provides for streams the equivalent of the RWCollectable method recursiveStoreSize() which is only available for RWFile.

Persistence

None

Short Example

#include <rw/auditbuf.h> #include <rw/bstream.h> #include <rw/pstream.h> #include <iostream.h> int main() { RWCollectable ct; fillCollectable(); // make a collection, somehow RWAuditStreamBuffer bcounter, pcounter; RWbostream bcount(&bcounter); //ctor takes streambuf pointer RWpostream pcount(&pcounter); //... bcount << ct; pcount << ct; cout << "We just counted " << bcounter << " bytes from an RWbostream." << endl; cout << "We just counted " << pcounter << " bytes from an RWpostream." << endl; return 0; }

Related Classes

RWAuditStreamBuffer may be used as the streambuf for any stream, including those derived from RWvostream or RWvistream, strstream, ifstream, ofstream, etc.

Global Typedef

typedef void (*RWauditFunction)(unsigned char, void*);

If you wish to do more than count each character handled by the buffer, you may provide an RWauditFunction to the constructor. The first parameter to this function is a byte provided by the stream. The second parameter is the address of the conter to be manipulated by RWAuditFunction.

Public Constructors

RWAuditStreamBuffer(RWauditFunction=0, void*=0);

Constructs a new RWAuditStreamBuffer that may be used only to examine and count every byte that passes into an ostream that has the RWAuditStreamBuffer instance as its streambuf. It will not forward the bytes to any stream, nor accept bytes from a stream. The second argument to the constructor allows you to supply storage for the byte count. It is optional.

RWAuditStreamBuffer(istream&, RWauditFunction=0, void*=0);

Constructs a new RWAuditStreamBuffer that passes bytes from the istream on which it is constructed to the istream that has the RWAuditStreamBuffer instance as its streambuf. A typical use would be to count or examine the bytes being input from a file through a stream derived from RWvistream. The second argument to the constructor allows you to supply storage for the byte count. It is optional.

RWAuditStreamBuffer(iostream&, RWauditFunction=0, void*=0);

Constructs a new RWAuditStreamBuffer that passes bytes to and from the iostream on which it is constructed to and from the istream that has the RWAuditStreamBuffer instance as its streambuf. A typical use would be to count or examine the bytes being transferred to and from a file used to store and retrieve changing data. The second argument to the constructor allows you to supply storage for the byte count. It is optional.

RWAuditStreamBuffer(ostream&, RWauditFunction=0, void*=0);

Constructs a new RWAuditStreamBuffer that passes bytes into the ostream on which it is constructed from the ostream that has the RWAuditStreamBuffer instance as its streambuf. A typical use would be to count or examine the bytes being output to a file through a stream derived from RWvostream. The second argument to the constructor allows you to supply storage for the byte count. It is optional.

RWAuditStreamBuffer(streambuf*, RWauditFunction=0, void*=0);

Constructs a new RWAuditStreamBuffer that passes bytes into the ostream on which it is constructed from the ostream that has the RWAuditStreamBuffer instance as its streambuf. A typical use would be to count or examine the bytes being output to a file through a stream derived from RWvostream. The second argument to the constructor allows you to supply storage for the byte count. It is optional.

Public Destructor

virtual ~RWAuditStreamBuffer();

We have provided an empty destructor since some compilers complain if there is no virtual destructor for a class that has virtual methods.

Public Member Operator

operator unsigned long();

Provides the count of bytes seen so far.

Public Member Function

unsigned long
reset(unsigned long value = 0);

Resets the count of bytes seen so far. Returns the current count.

Extended Example

#include <iostream.h> #include <fstream.h> #include <rw/auditbuf.h> #include <rw/pstream.h> #include <rw/cstring.h> void doCrc (unsigned char c, void* x) { *(unsigned char*)x ^= c; } int main() { if(1) { // just a block to control variable lifetime unsigned char check = '\0'; // create an output stream ofstream op("crc.pst");

// create an RWAuditStreamBuffer that will do CRC RWAuditStreamBuffer crcb(op,doCrc,&check); // create an RWpostream to put the data through. RWpostream p(&crcb); // now send some random stuff to the stream p << RWCString("The value of Tools.h++ is at least "); p << (int)4; p << RWCString(" times that of the next best library!\n") ; p << RWCString("Pi is about ") << (double)3.14159 << '.'; // finally, save the sum on the stream itself. p << (unsigned int)check; // alters check, _after_ saving it... // just for fun, print out some statistics: cout << "We just saved " << crcb << " bytes of data to the file." << endl; cout << "The checksum for those bytes was " <<check << endl; } // end of block // now read the data back in, checking to see if it survived. unsigned char check = '\0'; // create an instream ifstream ip("crc.pst"); // create an RWAuditStreamBuffer that will do CRC RWAuditStreamBuffer crcb(ip,doCrc,&check); // create an RWpistream to interpret the bytes RWpistream p(&crcb); RWCString first, mid1, mid2; int value; double pi; char pnc; unsigned int savedCRC; unsigned char matchCRC; // read in the data. Don\'t read the checksum yet! p >> first >> value >> mid1 >> mid2 >> pi >> pnc; // save the checksum matchCRC = check;

// Now it is safe to alter the running checksum by reading in // the one saved in the file. p >> savedCRC; if(savedCRC != matchCRC) { cout << "Checksum error. Saved CRC: " << savedCRC << " built CRC: " << matchCRC << dec << endl; } else { cout << "The message was: " << endl; cout << first << value << mid1 << mid2 << pi << pnc << endl; } // just for fun, print out some statistics: cout << "We just read " << crcb << " bytes of data from the file." << endl; cout << "The checksum was " << matchCRC << flush; cout << " and the saved checksum was " << savedCRC << endl; return 0; }

RWBag

RWBag . RWCollection . RWCollectable

Synopsis

typedef RWBag Bag;     // Smalltalk typedef .
#include <rw/rwbag.h>
RWBag h;

Description

Class RWBag corresponds to the Smalltalk class Bag. It represents a group of unordered elements, not accessible by an external key. Duplicates are allowed.

An object stored by RWBag must inherit abstract base class RWCollectable, with suitable definition for virtual functions hash() and isEqual() (see class RWCollectable). The function hash() is used to find objects with the same hash value, then isEqual() is used to confirm the match.

Class RWBag is implemented by using an internal hashed dictionary (RWHashDictionary) which keeps track of the number of occurrences of an item. If an item is added to the collection that compares equal (isEqual) to an existing item in the collection, then the count is incremented. Note that this means that only the first instance of a value is actually inserted: subsequent instances cause the occurrence count to be incremented. This behavior parallels the Smalltalk implementation of Bag.

Member function apply() and the iterator are called repeatedly according to the count for an item.

See class RWHashTable if you want duplicates to be stored, rather than merely counted.

Persistence

Polymorphic

Public Constructors

RWBag(size_t n = RWDEFAULT_CAPACITY);

Construct an empty bag with n buckets.

RWBag(const RWBag& b);

Copy constructor. A shallow copy of b will be made.

Public Member Operators

void
operator=(const RWBag& b);

Assignment operator. A shallow copy of b will be made.

RWBoolean
operator==(const RWBag& b) const;

Returns TRUE if self and bag b have the same number of total entries and if for every key in self there is a corresponding key in b which isEqual and which has the same number of entries.

Public Member Functions

virtual void
apply(RWapplyCollectable ap, void*);

Redefined from class RWCollection. This function has been redefined to apply the user-supplied function pointed to by ap to each member of the collection in a generally unpredictable order. If an item has been inserted more than once (i.e., more than one item isEqual), then apply() will be called that many times. The user-supplied function should not do anything that could change the hash value or the meaning of "isEqual" of the items.

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.

virtual size_t
entries() const;

Redefined from class RWCollection.

virtual RWCollectable*
find(const RWCollectable* target) const;

Redefined from class RWCollection. The first item that was inserted into the Bag and which equals target is returned or nil if no item is found. Hashing is used to narrow the search.

virtual unsigned
hash() const;

Inherited from class RWCollectable.

virtual RWCollectable*
insert(RWCollectable* c);

Redefined from class RWCollection. Inserts the item c into the collection and returns it, or if an item was already in the collection that isEqual to c, then returns the old item and increments its count.

RWCollectable*
insertWithOccurrences(RWCollectable* c,size_t n);

Inserts the item c into the collection with count n and returns it, or if an item was already in the collection that isEqual to c, then returns the old item and increments its count by n.

virtual RWClassID
isA() const;

Redefined from class RWCollectable to return __RWBAG.

virtual RWBoolean
isEmpty() const;

Redefined from class RWCollection.

virtual RWBoolean
isEqual(const RWCollectable* a) const;

Inherited from class RWCollectable.

virtual size_t
occurrencesOf(const RWCollectable* target) const;

Redefined from class RWCollection. Returns the number of items that are equal to the item pointed to by target.

virtual RWCollectable*
remove(const RWCollectable* target);

Redefined from class RWCollection. Removes and returns the item that isEqual to the item pointed to by target. Returns nil if no item was found.

virtual void
removeAndDestroy(const RWCollectable* target);

Redefined from class RWCollection. Removes the item that isEqual to the item pointed to by target. Destroys the item as well if it is the last occurrence in the collection.

void
resize(size_t n = 0);

Resizes the internal hash table to have n buckets. The overhead for this function is the hashing of every element in the collection. If n is zero, then an appropriate size will be picked automatically.

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.

RWBagIterator

RWBagIterator . RWIterator

Synopsis

#include <rw/rwbag.h>
RWBag b;
RWBagIterator it(b);

Description

Iterator for class RWBag, which allows sequential access to all the elements of RWBag. Note that because an RWBag is unordered, elements are not accessed in any particular order. If an item was inserted N times into the collection, then it will be visited N consecutive times.

Like 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.

Persistence

None

Public Constructor

RWBagIterator(const RWBag&);

Construct an iterator for an RWBag. After construction, the position of the iterator is undefined.

Public Member Operator

virtual RWCollectable*
operator()();

Redefined from class RWIterator. Advances the iterator to the next item and returns it. Returns nil when the end of the collection has been reached.

Public Member Functions

virtual RWCollectable*
findNext(const RWCollectable* target);

Redefined from class RWIterator. Moves iterator to the next item which isEqual to the object pointed to by target and returns it. Hashing is used to find the target. If no item is found, returns nil and the position of the iterator will be undefined.

virtual RWCollectable*
key() const;

Redefined from class RWIterator. Returns the item at the current iterator position.

virtual void
reset();

Redefined from class RWIterator. Resets the iterator to its starting state.

RWBench

Synopsis

#include <rw/bench.h>
(Abstract base class)

Description

This is an abstract class that can automate the process of benchmarking a piece of code. To use it, derive a class from RWBench, including a definition for the virtual function doLoop(unsigned long N). This function should perform N operations of the type that you are trying to benchmark. RWBench will call doLoop() over and over again until a preset amount of time has elapsed. It will then sum the total number of operations performed.

To run, construct an instance of your derived class and then call go(). Then call report() to get a standard summary. For many compilers, this summary will automatically include the compiler type and memory model. You can call ops(), outerLoops(), etc. for more detail.

If you wish to correct for overhead, then provide an idleLoop() function which should do all non-benchmark-related calculations.

Persistence

None

Example

This example benchmarks the time required to return a hash value for a Rogue Wave string versus a Borland string.

#include <rw/bench.h> /* Benchmark software */ #include <rw/cstring.h> /* Rogue Wave string class */ #include <stdlib.h>

#include <iostream.h> #include <rw/ctoken.h> #include <rw/regexp.h> // The string to be hashed: const char* cs = "A multi-character string with lots of words in it to be parsed out and searched for."; class TestBrute : public RWBench { public: TestBrute() { } virtual void doLoop(unsigned long n); virtual void idleLoop(unsigned long n); virtual void what(ostream& s) const { s << "Brute force string search: \n"; } }; class TestRW : public RWBench { public: TestRW() { } virtual void doLoop(unsigned long n); virtual void idleLoop(unsigned long n); virtual void what(ostream& s) const { s << "Rogue Wave search: \n"; } }; main(int argc, char* argv[]){ cout << "Testing string \n\"" << cs << "\"\n"; // Test brute force string search algorithm: TestBrute other; other.parse(argc, argv); other.go(); other.report(cout); // Test RW searching w/regular expressions: TestRW rw; rw.parse(argc, argv); rw.go(); rw.report(cout); return 0; }

void TestBrute::doLoop(unsigned long n){ RWCString string(cs); RWCTokenizer *tokener; RWCString token; tokener = new RWCTokenizer(string); while(n--){ if((token = (*tokener)()).isNull()) { delete tokener; tokener = new RWCTokenizer(string); token = (*tokener)(); } size_t j = 0; for(size_t i = 0; i < string.length() && j != token.length(); i++) { j = 0; while((j < token.length()) && (string[i+j]==token[j])) j++; } } delete tokener; } void TestRW::doLoop(unsigned long n){ RWCString string(cs); RWCTokenizer *tokener; RWCString token, result; RWCRegexp re(""); tokener = new RWCTokenizer(string); while(n--){ if((token = (*tokener)()).isNull())

{ delete tokener; tokener = new RWCTokenizer(string); token = (*tokener)(); } re = RWCRegexp(token); result = string(re); //Do the search! } delete tokener; } void TestBrute::idleLoop(unsigned long n){ RWCString string(cs); // Subtract out the overhead RWCTokenizer *tokener; RWCString token; tokener = new RWCTokenizer(string); while(n--){ if((token = (*tokener)()).isNull()) { delete tokener; tokener = new RWCTokenizer(string); token = (*tokener)(); } } delete tokener; } void TestRW::idleLoop(unsigned long n){ RWCString string(cs); //Subtract out the overhead RWCTokenizer *tokener; RWCString token, result; RWCRegexp re(""); tokener = new RWCTokenizer(string); while(n--){ if((token = (*tokener)()).isNull())

{ delete tokener; tokener = new RWCTokenizer(string); token = (*tokener)(); } re = RWCRegexp(token); } delete tokener; }

Program output:

Testing string "A multi-character string with lots of words in it to be parsed out and searched for." Borland C++ V4.0 Brute force string search: Iterations: 35 Inner loop operations: 1000 Total operations: 35000 Elapsed (user) time: 4.596 Kilo-operations per second: 7.61532 Borland C++ V4.0 Rogue Wave search: Iterations: 53 Inner loop operations: 1000 Total operations: 53000 Elapsed (user) time: 2.824 Kilo-operations per second: 18.7677

Public Constructors

RWBench(double duration = 5, unsigned long ILO=1000,
        const char* machine = 0);

The parameter duration is the nominal amount of time that the benchmark should take in seconds. The virtual function doLoop(unsigned long) will be called over and over again until at least this amount of time has elapsed. The parameter ILO is the number of "inner loop operations" that should be performed. This parameter will be passed in as parameter N to doLoop(N). Parameter machine is an optional null terminated string that should describe the test environment (perhaps the hardware the benchmark is being run on ).

Public Member Functions

virtual void
doLoop(unsigned long N)=0;

A pure virtual function whose actual definition should be supplied by the specializing class. This function will be repeatedly called until a time duration has elapsed. It should perform the operation to be benchmarked N times. See the example.

double
duration() const;

Return the current setting for the benchmark test duration. This should not be confused with function time() which returns the actual test time.

virtual void
go();

Call this function to run the benchmark.

virtual void
idleLoop(unsigned long N);

This function can help to correct the benchmark for overhead. The default definition merely executes a "for()" loop N times. See the example.

const char *
machine();

This function accesses the name of the machine which is passed into the benchmark object through parse().

virtual void
parse(int argc, char* argv[]);

This function allows an easy way to change the test duration, number of inner loops and machine description from the command line:

Argument	Type	Description
argv[1]	double	Duration (sec.)
argv[2]	unsigned long	No. of inner loops
argv[3]	const char*	Machine

void
parse(const char *);

This is a non-virtual function which provides the same service as parse(int argc, char * argv[]), but is designed for Windows users. It extracts tokens from the null-terminated command argument provided by Windows, then calls the virtual parse for ANSI C command arguments.

virtual void
report(ostream&) const;

Calling this function provides an easy and convenient way of getting an overall summary of the results of a benchmark.

double
setDuration(double t);

Change the test duration to time t.

unsigned long
setInnerLoops(unsigned long N);

Change the number of "inner loop operations" to N.

virtual void
what(ostream&) const;

You can supply a specializing version of this virtual function that provides some detail of what is being benchmarked. It is called by report() when generating a standard report.

void
where(ostream&) const;

This function will print information to the stream about the compiler and memory model that the code was compiled under.

unsigned long
innerLoops() const;

Returns the current setting for the number of inner loop operations that will be passed into function doLoop(unsigned long N) as parameter N.

double
time() const;

Returns the amount of time the benchmark took, corrected for overhead.

unsigned long
outerLoops() const;

Returns the number of times the function doLoop() was called.

double
ops() const;

Returns the total number of inner loop operations that were performed (the product of the number of times outerLoop() was called times the number of inner loop operations performed per call).

double
opsRate() const;

Returns the number of inner loop operations per second.

RWBinaryTree

RWBinaryTree . RWCollection . RWCollectable

Synopsis

typedef RWBinaryTree SortedCollection;   // Smalltalk typedef.
#include <rw/bintree.h>
RWBinaryTree bt;

Description

Class RWBinaryTree represents a group of ordered elements, internally sorted by the compareTo() function. Duplicates are allowed. An object stored by an RWBinaryTree must inherit abstract base class RWCollectable.

Persistence

Polymorphic

Public Constructors

RWBinaryTree();

Construct an empty sorted collection.

RWBinaryTree(const RWBinaryTree& t);

Copy constructor. Constructs a shallow copy from t. Member function balance() (see below) is called before returning.

virtual ~RWBinaryTree();

Redefined from RWCollection. Calls clear().

Public Member Operators

void
operator=(const RWBinaryTree& bt);

Sets self to a shallow copy of bt.

void
operator+=(const RWCollection ct);

Inserts each element of .ct into self. Note that using this operator to insert an already-sorted collection will result in creating a very unbalanced tree, possibly to the point of stack overflow.

RWBoolean
operator<=(const RWBinaryTree& bt) const;

Returns TRUE if self is a subset of the collection bt. That is, every item in self must compare equal to a unique item in bt.

RWBoolean
operator==(const RWBinaryTree& bt) const;

Returns TRUE if self and bt are equivalent. That is, they must have the same number of items and every item in self must compare equal to a unique item in bt.

Public Member Functions

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 smallest to largest. This supplied function should not do anything to the items that could change the ordering of the collection.

void
balance();

Special function to balance the tree. In a perfectly balanced binary tree with no duplicate elements, the number of nodes from the root to any external (leaf) node differs by at most one node. Since this collection allows duplicate elements, a perfectly balanced tree is not always possible. Preserves the order of duplicate elements.

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.

virtual size_t
entries() const;

Redefined from class RWCollection.

virtual RWCollectable*
find(const RWCollectable* target) const;

Redefined from class RWCollection. Returns the first item that compares equal to the item pointed to by target, or nil if no item was found.

virtual unsigned
hash() const;

Inherited from class RWCollectable.

unsigned
height() const;

Returns the number of nodes between the root node and the farthest leaf. A RWBinaryTree with one entry will have a height of 1. Note that the entire tree is traversed to discover this value.

virtual RWCollectable*
insert(RWCollectable* c);

Redefined from class RWCollection. Inserts the item c into the collection and returns it. Returns nil if the insertion was unsuccessful. The item c is inserted according to the value returned by compareTo(). insert() does not automatically balance the RWBinaryTree. Be careful not to insert() a long sequence of sorted items without calling balance() since the result will be very unbalanced (and therefore inefficient).

virtual RWClassID
isA() const;

Redefined from class RWCollectable to return __RWBINARYTREE.

virtual RWBoolean
isEmpty() const;

Redefined from class RWCollection.

virtual RWBoolean
isEqual(const RWCollectable* a) const;

Inherited from class RWCollectable.

virtual size_t
occurrencesOf(const RWCollectable* target) const;

Redefined from class RWCollection. Returns the number of items that compare equal to the item pointed to by target.

virtual RWCollectable*
remove(const RWCollectable* target);

Redefined from class RWCollection. Removes the first item that compares equal to the object pointed to by target and returns it. Returns nil if no item was found.

virtual void
removeAndDestroy(const RWCollectable* target);

Inherited from class RWCollection.

virtual void
restoreGuts(RWvistream&);
virtual void
restoreGuts(RWFile&);

Inherited from class RWCollection.

virtual void
saveGuts(RWvostream&) const;
virtual void
saveGuts(RWFile&) const;

Redefined from class RWCollection to store objects by level, rather than in order. This results in the tree maintaining its morphology.

RWStringID
stringID();

(acts virtual) Inherited from class RWCollectable.

RWBinaryTreeIterator

RWBinaryTreeIterator . RWIterator

Synopsis

// Smalltalk typedef:
typedef RWBinaryTreeIterator SortedCollectionIterator;
#include <rw/bintree.h>
RWBinaryTree bt;
RWBinaryTreeIterator iterate(bt);

Description

Iterator for class RWBinaryTree. Traverses the tree from the "smallest" to "largest" element, where "smallest" and "largest" are defined by the virtual function compareTo(). Note that this approach is generally less efficient than using the member function RWBinaryTree::apply().

Like 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.

Persistence

None

Public Constructor

RWBinaryTreeIterator(const RWBinaryTree&);

Constructs an iterator for an RWBinaryTree. Immediately after construction, the position of the iterator is undefined until positioned.

Public Member Operator

virtual RWCollectable*
operator()();

Redefined from class RWIterator. Advances iterator to the next "largest" element and returns a pointer to it. Returns nil when the end of the collection is reached.

Public Member Functions

virtual RWCollectable*
findNext(const RWCollectable* target);

Redefined from class RWIterator. Moves iterator to the next item which compares equal to the object pointed to by target and returns it. If no item is found, returns nil and the position of the iterator will be undefined.

virtual void
reset();

Redefined from class RWIterator. Resets iterator to its state at construction.

virtual RWCollectable*
key() const;

Redefined from class RWIterator. Returns the item at the current iterator position.

RWbistream

. RWvistream . RWios . RWvios

RWbistream

. ios

Synopsis

#include <rw/bstream.h>
RWbistream bstr(cin);        // Construct an RWbistream,
                             // using cin's streambuf

Description

Class RWbistream specializes the abstract base class RWvistream to restore variables stored in binary format by RWbostream.

You can think of it as a binary veneer over an associated streambuf. Because the RWbistream retains no information about the state of its associated streambuf, its use can be freely exchanged with other users of the streambuf (such as an istream or ifstream).

RWbistream can be interrogated as to the stream state using member functions good(), bad(), eof(), etc.

Persistence

None

Example

See RWbostream for an example of how the file "data.dat" might be created.

#include <rw/bstream.h> #include <fstream.h> main(){ ifstream fstr("data.dat"); // Open an input file RWbistream bstr(fstr); // Construct RWbistream from it int i; float f; double d; bstr >> i; // Restore an int that was stored in binary bstr >> f >> d; // Restore a float & double } END FILE

Public Constructors

RWbistream(streambuf* s);

Construct an RWbistream from the streambuf s. For DOS, this streambuf must have been opened in binary mode.

RWbistream(istream& str);

Construct an RWbistream using the streambuf associated with the istream str. For DOS, the streambuf must have been opened in binary mode. This can be done by specifying ios::binary as part of the second argument to the constructor for an ifstream. Using the example above, the line to create the ifstream would read, ifstream fstr("data.dat", ios::in | ios::binary); where the "|" is the binary OR operator.

Public Operators

virtual RWvistream&
operator>>(char& c);

Redefined from class RWvistream. Get the next char from the input stream and store it in c.

virtual RWvistream&
operator>>(wchar_t& wc);

Redefined from class RWvistream. Get the next wide char from the input stream and store it in wc.

virtual RWvistream&
operator>>(double& d);

Redefined from class RWvistream. Get the next double from the input stream and store it in d.

virtual RWvistream&
operator>>(float& f);

Redefined from class RWvistream. Get the next float from the input stream and store it in f.

virtual RWvistream&
operator>>(int& i);

Redefined from class RWvistream. Get the next int from the input stream and store it in i.

virtual RWvistream&
operator>>(long& l);

Redefined from class RWvistream. Get the next long from the input stream and store it in l.

virtual RWvistream&
operator>>(short& s);

Redefined from class RWvistream. Get the next short from the input stream and store it in s.

virtual RWvistream&
operator>>(unsigned char& c);

Redefined from class RWvistream. Get the next unsigned char from the input stream and store it in c.

virtual RWvistream&
operator>>(unsigned short& s);

Redefined from class RWvistream. Get the next unsigned short from the input stream and store it in s.

virtual RWvistream&
operator>>(unsigned int& i);

Redefined from class RWvistream. Get the next unsigned int from the input stream and store it in i.

virtual RWvistream&
operator>>(unsigned long& l);

Redefined from class RWvistream. Get the next unsigned long from the input stream and store it in l.

operator void*();

Inherited via RWvistream from RWvios.

Public Member Functions

virtual int
get();

Redefined from class RWvistream. Get and return the next char from the input stream. Returns EOF if end of file is encountered.

virtual RWvistream&
get(char& c);

Redefined from class RWvistream. Get the next char and store it in c.

virtual RWvistream&
get(wchar_t& wc);

Redefined from class RWvistream. Get the next wide char and store it in wc.

virtual RWvistream&
get(unsigned char& c);

Redefined from class RWvistream. Get the next unsigned char and store it in c.

virtual RWvistream&
get(char* v, size_t N);

Redefined from class RWvistream. Get a vector of chars and store them in the array beginning at v. If the restore operation stops prematurely, because there are no more data available on the stream, because an exception is thrown, or for some other reason; get stores what has already been retrieved from the stream into v, and sets the failbit.

virtual RWvistream&
get(wchar_t* v, size_t N);

Redefined from class RWvistream. Get a vector of wide chars and store them in the array beginning at v. If the restore operation stops prematurely, because there are no more data available on the stream, because an exception is thrown, or for some other reason; get stores what has already been retrieved from the stream into v, and sets the failbit.

virtual RWvistream&
get(double* v, size_t N);

Redefined from class RWvistream. Get a vector of doubles and store them in the array beginning at v. If the restore operation stops prematurely, because there are no more data available on the stream, because an exception is thrown, or for some other reason; get stores what has already been retrieved from the stream into v, and sets the failbit.

virtual RWvistream&
get(float* v, size_t N);

Redefined from class RWvistream. Get a vector of floats and store them in the array beginning at v. If the restore operation stops prematurely, because there are no more data available on the stream, because an exception is thrown, or for some other reason; get stores what has already been retrieved from the stream into v, and sets the failbit.

virtual RWvistream&
get(int* v, size_t N);

Redefined from class RWvistream. Get a vector of ints and store them in the array beginning at v. If the restore operation stops prematurely, because there are no more data available on the stream, because an exception is thrown, or for some other reason; get stores what has already been retrieved from the stream into v, and sets the failbit.

virtual RWvistream&
get(long* v, size_t N);

Redefined from class RWvistream. Get a vector of longs and store them in the array beginning at v. If the restore operation stops prematurely, because there are no more data available on the stream, because an exception is thrown, or for some other reason; get stores what has already been retrieved from the stream into v, and sets the failbit.

virtual RWvistream&
get(short* v, size_t N);

Redefined from class RWvistream. Get a vector of shorts and store them in the array beginning at v. If the restore operation stops prematurely, because there are no more data available on the stream, because an exception is thrown, or for some other reason; get stores what has already been retrieved from the stream into v, and sets the failbit.

virtual RWvistream&
get(unsigned char* v, size_t N);

Redefined from class RWvistream. Get a vector of unsigned chars and store them in the array beginning at v. If the restore operation stops prematurely, because there are no more data available on the stream, because an exception is thrown, or for some other reason; get stores what has already been retrieved from the stream into v, and sets the failbit.

virtual RWvistream&
get(unsigned short* v, size_t N);

Redefined from class RWvistream. Get a vector of unsigned shorts and store them in the array beginning at v. If the restore operation stops prematurely, because there are no more data available on the stream, because an exception is thrown, or for some other reason; get stores what has already been retrieved from the stream into v, and sets the failbit.

virtual RWvistream&
get(unsigned int* v, size_t N);

Redefined from class RWvistream. Get a vector of unsigned ints and store them in the array beginning at v. If the restore operation stops prematurely, because there are no more data available on the stream, because an exception is thrown, or for some other reason; get stores what has already been retrieved from the stream into v, and sets the failbit.

virtual RWvistream&
get(unsigned long* v, size_t N);

Redefined from class RWvistream. Get a vector of unsigned longs and store them in the array beginning at v. If the restore operation stops prematurely, because there are no more data available on the stream, because an exception is thrown, or for some other reason; get stores what has already been retrieved from the stream into v, and sets the failbit.

virtual RWvistream&
getString(char* s, size_t N);

Redefined from class RWvistream. 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 N- 1 characters have been read and the Nth character is not the string terminator, then the failbit of the stream will be set. In either case, the string will be terminated with a null byte.

virtual RWvistream&
getString(wchar_t* ws, size_t N);

Redefined from class RWvistream. Restores a wide character string from the input stream and stores it in the array beginning at ws. The function stops reading at the end of the string or after N-1 characters, whichever comes first. If N-1 characters have been read and the Nth character is not the string terminator, then the failbit of the stream will be set. In either case, the string will be terminated with a null byte.

RWBitVec

Synopsis

#include <rw/bitvec.h>
RWBitVec v;

Description

Class RWBitVec is a bitvector whose length can be changed at run time. Because this requires an extra level of indirection, this makes it slightly less efficient than classes RWGBitVec(size) or RWTBitVec<size>, whose lengths are fixed at compile time.

Persistence

Simple

Example

#include <rw/bitvec.h> #include <rw/rstream.h> main(){ // Allocate a vector with 20 bits, set to TRUE: RWBitVec av(20, TRUE); av(2) = FALSE; // Turn bit 2 off av.clearBit(7); // Turn bit 7 off av.setBit(2); // Turn bit 2 back on for(int i=11; i<=14; i++) av(i) = FALSE; cout << av << endl; // Print the vector out }

Program output:

[ 1 1 1 1 1 1 1 0 1 1 1 0 0 0 0 1 1 1 1 1 ]

Public Constructors

RWBitVec();

Construct a zero lengthed (null) vector.

RWBitVec(size_t N);

Construct a vector with N bits. The initial value of the bits is undefined.

RWBitVec(size_t N, RWBoolean initVal);

Construct a vector with N bits, each set to the Boolean value initVal.

RWBitVec(const RWByte* bp, size_t N);

Construct a vector with N bits, initialized to the data in the array of bytes pointed to by bp. This array must be at least long enough to contain N bits. The identifier RWByte is a typedef for an unsigned char.

RWBitVec(const RWBitVec& v);

Copy constructor. Uses value semantics -- the constructed vector will be a copy of v.

~RWBitVec();

The destructor. Releases any allocated memory.

Assignment Operators

RWBitVec&
operator=(const RWBitVec& v);

Assignment operator. Value semantics are used -- self will be a copy of v.

RWBitVec&
operator=(RWBoolean b);

Assignment operator. Sets every bit in self to the boolean value b.

RWBitVec&
operator&=(const RWBitVec& v);
RWBitVec&
operator^=(const RWBitVec& v);
RWBitVec&
operator|=(const RWBitVec& v);

Logical assignments. Set each element of self to the logical AND, XOR, or OR, respectively, of self and the corresponding bit in v. Self and v must have the same number of elements (i.e., be conformal) or an exception of type RWInternalErr will occur.

Indexing Operators

RWBitRef
operator[](size_t i);

Returns a reference to bit i of self. A helper class, RWBitRef, is used. The result can be used as an lvalue. The index i must be between 0 and the length of the vector less one. Bounds checking is performed. If the index is out of range, then an exception of type RWBoundsErr will occur.

RWBitRef
operator()(size_t i);

Returns a reference to bit i of self. A helper class, RWBitRef, is used. The result can be used as an lvalue. The index i must be between 0 and the length of the vector less one. Bounds checking is performed only if the preprocessor macro RWBOUNDS_CHECK has been defined before including the header file <rw/bitvec.h>. If so, and if the index is out of range, then an exception of type RWBoundsErr will occur.

RWBoolean
operator[](size_t i) const;

Returns the boolean value of bit i. The result cannot be used as an lvalue. The index i must be between 0 and the length of the vector less one. Bounds checking is performed. If the index is out of range, then an exception of type RWBoundsErr will occur.

RWBoolean
operator()(size_t i) const;

Returns the boolean value of bit i. The result cannot be used as an lvalue. The index i must be between 0 and the length of the vector less one. Bounds checking is performed only if the preprocessor macro RWBOUNDS_CHECK has been defined before including the header file <rw/bitvec.h>. If so, and if the index is out of range, then an exception of type RWBoundsErr will occur.

Logical Operators

RWBoolean
operator==(const RWBitVec& u) const;

Returns TRUE if self and v have the same length and if each bit of self is set to the same value as the corresponding bit in v. Otherwise, returns FALSE.

RWBoolean
operator!=(const RWBitVec& u) const;

Returns FALSE if self and v have the same length and if each bit of self is set to the same value as the corresponding bit in v. Otherwise, returns TRUE.

RWBoolean
operator==(RWBoolean b) const;

Returns TRUE if every bit of self is set to the boolean value b. Otherwise FALSE.

RWBoolean
operator!=(RWBoolean b) const;

Returns FALSE if every bit of self is set to the boolean value b. Otherwise TRUE.

Public Member Functions

void
clearBit(size_t i);

Clears (i.e., sets to FALSE) the bit with index i. The index i must be between 0 and the length of the vector less one. No bounds checking is performed. The following are equivalent, although clearBit(size_t) is slightly smaller and faster than using operator()(size_t):

   a(i) = FALSE;
   a.clearBit(i);
const RWByte*
data() const;

Returns a const pointer to the raw data of self. Should be used with care.

size_t
firstFalse() const;

Returns the index of the first FALSE bit in self. Returns RW_NPOS if there is no FALSE bit.

size_t
firstTrue() const;

Returns the index of the first TRUE bit in self. Returns RW_NPOS if there is no TRUE bit.

unsigned
hash() const;

Returns a value suitable for hashing.

RWBoolean
isEqual(const RWBitVec& v) const;

Returns TRUE if self and v have the same length and if each bit of self is set to the same value as the corresponding bit in v. Otherwise, returns FALSE.

size_t
length() const;

Returns the number of bits in the vector.

ostream&
printOn(ostream& s) const;

Print the vector v on the output stream s. See the example above for a sample of the format.

void
resize(size_t N);

Resizes the vector to have length N. If this results in a lengthening of the vector, the additional bits will be set to FALSE.

istream&
scanFrom(istream&);

Read the bit vector from the input stream s. The vector will dynamically be resized as necessary. The vector should be in the same format printed by member function printOn(ostream&).

void
setBit(size_t i);

Sets (i.e., sets to TRUE) the bit with index i. The index i must be between 0 and size-1. No bounds checking is performed. The following are equivalent, although setBit(size_t) is slightly smaller and faster than using operator()(size_t):

   a(i) = TRUE;
   a.setBit(i);
RWBoolean
testBit(size_t i) const;

Tests the bit with index i. The index i must be between 0 and size-1. No bounds checking is performed. The following are equivalent, although testBit(size_t) is slightly smaller and faster than using

  operator()(size_t):
   if( a(i) )              doSomething();
   if( a.testBit(i) )      doSomething();

Related Global Functions

RWBitVec
operator!(const RWBitVec& v);

Unary operator that returns the logical negation of vector v.

RWBitVec
operator&(const RWBitVec&,const RWBitVec&);
RWBitVec
operator^(const RWBitVec&,const RWBitVec&);
RWBitVec
operator|(const RWBitVec&,const RWBitVec&);

Returns a vector that is the logical AND, XOR, or OR of the vectors v1 and v2. The two vectors must have the same length or an exception of type RWInternalErr will occur.

ostream&
operator<<(ostream& s, const RWBitVec& v);

Calls v.printOn(s).

istream&
operator>>(istream& s, RWBitVec& v);

Calls v.scanFrom(s).

RWvostream&
operator<<(RWvostream&, const RWBitVec& vec);
RWFile&
operator<<(RWFile&,     const RWBitVec& vec);

Saves the RWBitVec vec to a virtual stream or RWFile, respectively.

RWvistream&
operator>>(RWvistream&, RWBitVec& vec);
RWFile&
operator>>(RWFile&,     RWBitVec& vec);

Restores an RWBitVec into vec from a virtual stream or RWFile, respectively, replacing the previous contents of vec.

size_t
sum(const RWBitVec& v);

Returns the total number of bits set in the vector v.

RWbostream

. RWvostream . RWios . RWvios

RWbostream

. ios

Synopsis

#include <rw/bstream.h>
// Construct an RWbostream, using cout's streambuf:
RWbostream bstr(cout);

Description

Class RWbostream specializes the abstract base class RWvostream to store variables in binary format. The results can be restored by using its counterpart RWbistream.

You can think of it as a binary veneer over an associated streambuf. Because the RWbostream retains no information about the state of its associated streambuf, its use can be freely exchanged with other users of the streambuf (such as ostream or ofstream).

Note that variables should not be separated with white space. Such white space would be interpreted literally and would have to be read back in as a character string.

RWbostream can be interrogated as to the stream state using member functions good(), bad(), eof(), etc.

Persistence

None

Example

See RWbistream for an example of how the file "data.dat" might be read back in.

#include <rw/bstream.h> #include <fstream.h> main(){ ofstream fstr("data.dat"); // Open an output file RWbostream bstr(fstr); // Construct an RWbostream from it int i = 5; float f = 22.1; double d = -0.05; bstr << i; // Store an int in binary bstr << f << d; // Store a float & double }

Public Constructors

RWbostream(streambuf* s);

Construct an RWbostream from the streambuf s. For DOS, the streambuf must have been opened in binary mode.

RWbostream(ostream& str);

Construct an RWbostream from the streambuf associated with the output stream str. For DOS, the streambuf must have been opened in binary mode. This can be done by specifying ios::binary as part of the second argument to the constructor for an ofstream. Using the example above, the line to create the ofstream would read, ofstream fstr("data.dat", ios::out | ios::binary); where the "|" is the binary OR operator.

Public Destructor

virtual ~RWvostream();

This virtual destructor allows specializing classes to deallocate any resources that they may have allocated.

Public Operators

virtual RWvostream&
operator<<(const char* s);

Redefined from class RWvostream. Store the character string starting at s to the output stream in binary. The character string is expected to be null terminated.

virtual RWvostream&
operator<<(const wchar_t* ws);

Redefined from class RWvostream. Store the wide character string starting at ws to the output stream in binary. The wide character string is expected to be null terminated.

virtual RWvostream&
operator<<(char c);

Redefined from class RWvostream. Store the char c to the output stream in binary.

virtual RWvostream&
operator<<(wchar_t wc);

Redefined from class RWvostream. Store the wide char wc to the output stream in binary.

virtual RWvostream&
operator<<(unsigned char c);

Redefined from class RWvostream. Store the unsigned char c to the output stream in binary.

virtual RWvostream&
operator<<(double d);

Redefined from class RWvostream. Store the double d to the output stream in binary.

virtual RWvostream&
operator<<(float f);

Redefined from class RWvostream. Store the float f to the output stream in binary.

virtual RWvostream&
operator<<(int i);

Redefined from class RWvostream. Store the int i to the output stream in binary.

virtual RWvostream&
operator<<(unsigned int i);

Redefined from class RWvostream. Store the unsigned int i to the output stream in binary.

virtual RWvostream&
operator<<(long l);

Redefined from class RWvostream. Store the long l to the output stream in binary.

virtual RWvostream&
operator<<(unsigned long l);

Redefined from class RWvostream. Store the unsigned long l to the output stream in binary.

virtual RWvostream&
operator<<(short s);

Redefined from class RWvostream. Store the short s to the output stream in binary.

virtual RWvostream&
operator<<(unsigned short s);

Redefined from class RWvostream. Store the unsigned short s to the output stream in binary.

operator void*();
Inherited via RWvostream from RWvios.

Public Member Functions

virtual RWvostream&
flush();

Send the contents of the stream buffer to output immediately.

virtual RWvostream&
put(char c);

Redefined from class RWvostream. Store the char c to the output stream.

virtual RWvostream&
put(wchar_t wc);

Redefined from class RWvostream. Store the wide character wc to the output stream.

virtual RWvostream&
put(unsigned char c);

Redefined from class RWvostream. Store the unsigned char c to the output stream.

virtual RWvostream&
put(const char* p, size_t N);

Redefined from class RWvostream. Store the vector of chars starting at p to the output stream in binary.

virtual RWvostream&
put(const wchar_t* p, size_t N);

Redefined from class RWvostream. Store the vector of wide chars starting at p to the output stream in binary.

virtual RWvostream&
put(const unsigned char* p, size_t N);

Redefined from class RWvostream. Store the vector of unsigned chars starting at p to the output stream in binary.

virtual RWvostream&
put(const short* p, size_t N);

Redefined from class RWvostream. Store the vector of shorts starting at p to the output stream in binary.

virtual RWvostream&
put(const unsigned short* p, size_t N);

Redefined from class RWvostream. Store the vector of unsigned shorts starting at p to the output stream in binary.

virtual RWvostream&
put(const int* p, size_t N);

Redefined from class RWvostream. Store the vector of ints starting at p to the output stream in binary.

virtual RWvostream&
put(const unsigned int* p, size_t N);

Redefined from class RWvostream. Store the vector of unsigned ints starting at p to the output stream in binary.

virtual RWvostream&
put(const long* p, size_t N);

Redefined from class RWvostream. Store the vector of longs starting at p to the output stream in binary.

virtual RWvostream&
put(const unsigned long* p, size_t N);

Redefined from class RWvostream. Store the vector of unsigned longs starting at p to the output stream in binary.

virtual RWvostream&
put(const float* p, size_t N);

Redefined from class RWvostream. Store the vector of floats starting at p to the output stream in binary.

virtual RWvostream&
put(const double* p, size_t N);

Redefined from class RWvostream. Store the vector of doubles starting at p to the output stream in binary.

virtual RWvostream&
putString(const char* p, size_t N);

Redefined from class RWvostream. Data is formatted as a string containing N characters.

virtual RWvostream&
putString(const char*s, size_t N);

Store the character string, including embedded nulls, starting at s to the output string.

RWBTree

RWBTree . RWCollection . RWCollectable

Synopsis

#include <rw/btree.h>
RWBTree a;

Description

Class RWBTree represents a group of ordered elements, not accessible by an external key. Duplicates are not allowed. An object stored by class RWBTree must inherit abstract base class RWCollectable -- the elements are ordered internally according to the value returned by virtual function compareTo() (see class RWCollectable).

This class has certain advantages over class RWBinaryTree. First, the B-tree is automatically balanced. (With class RWBinaryTree, you must call member function balance() explicitly to balance the tree.) Nodes are never allowed to have less than a certain number of items (called the order). The default order is 50, but may be changed by resetting the value of the static constant "order" in the header file <btree.h> and recompiling. Larger values will result in shallower trees, but less efficient use of memory.

Because many keys are held in a single node, class RWBTree also tends to fragment memory less.

Persistence

Polymorphic

Public Constructors

RWBTree();

Construct an empty B-tree.

RWBTree(const RWBTree& btr);

Construct self as a shallow copy of btr.

Public Destructor
virtual
~RWBTree();

Redefined from RWCollection. Calls clear().

Public Member Operators

void
operator=(const RWBTree& btr);

Set self to a shallow copy of btr.

RWBoolean
operator<=(const RWBTree& btr) const;

Returns TRUE if self is a subset of btr. That is, for every item in self, there must be an item in btr that compares equal.

---

Note - If you inherit from RWBTree in the presence of the Standard C++ Library, we recommend that you override this operator and explicitly forward the call. Overload resolution in C++ will choose the Standard Library provided global operators over inherited class members. These global definitions are not appropriate for set-like partial orderings.

---

RWBoolean
operator==(const RWBTree& btr) const;

Returns TRUE if self and btr are equivalent. That is, they must have the same number of items and for every item in self, there must be an item in btr that compares equal.

Public Member Functions

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 smallest to largest. This supplied function should not do anything to the items that could change the ordering of the collection.

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.

virtual size_t
entries() const;

Redefined from class RWCollection.

virtual RWCollectable*
find(const RWCollectable* target) const;

Redefined from class RWCollection. The first item that compares equal to the object pointed to by target is returned or nil if no item is found.

virtual unsigned
hash() const;

Inherited from class RWCollectable.

unsigned
height() const;

Special member function of this class. Returns the height of the tree, defined as the number of nodes traversed while descending from the root node to an external (leaf) node.

virtual RWCollectable*
insert(RWCollectable* c);

Redefined from class RWCollection. Inserts the item c into the collection and returns it. The item c is inserted according to the value returned by compareTo(). If an item is already in the collection which isEqual to c, then the old item is returned and the new item is not inserted. Otherwise returns nil if the insertion was unsuccessful.

virtual RWClassID
isA() const;

Redefined from class RWCollectable to return __RWBTREE.

virtual RWBoolean
isEmpty() const;

Redefined from class RWCollection.

virtual RWBoolean
isEqual(const RWCollectable* a) const;

Inherited from class RWCollectable.

virtual size_t
occurrencesOf(const RWCollectable* target) const;

Redefined from class RWCollection. Returns the number of items that compare equal to target. Since duplicates are not allowed, this function can only return 0 or 1.

virtual RWCollectable*
remove(const RWCollectable* target);

Redefined from class RWCollection. Removes and returns the first item that compares equal to the object pointed to by target. Returns nil if no item was found.

virtual void
removeAndDestroy(const RWCollectable* target);

Inherited from class RWCollection.

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.

RWBTreeDictionary

RWBTreeDictionary . RWBTree . RWCollection . RWCollectable

Synopsis

#include <rw/btrdict.h>
RWBTreeDictionary a;

Description

Dictionary class implemented as a B-tree, for the storage and retrieval of key-value pairs. Both the keys and values must inherit abstract base class RWCollectable -- the elements are ordered internally according to the value returned by virtual function compareTo() of the key (see class RWCollectable). Duplicate keys are not allowed.

The B-tree is balanced. That is, nodes are never allowed to have less than a certain number of items (called the order). The default order is 50, but may be changed by resetting the value of the static constant "order" in the header file <btree.h> and recompiling. Larger values will result in shallower trees, but less efficient use of memory.

Persistence

Polymorphic

Public Constructors

RWBTreeDictionary();

Constructs an empty B-tree dictionary.

Public Member Operators

RWBoolean
operator<=(const RWBTreeDictionary& btr) const;

Returns TRUE if self is a subset of btr. That is, for every item in self, there must be an item in btr that compares equal. This operator is not explicitly present unless you are compiling with an implementation of the C++ Standard Library. Normally it is inherited from RWBTree.

---

Note - If you inherit from RWBTreeDictionary in the presence of the C++ Standard Library, we recommend that you override this operator and explicitly forward the call. Overload resolution in C++ will choose the Standard Library provided global operators over inherited class members. These global definitions are not appropriate for set-like partial orderings.

---

Public Member Functions

void
applyToKeyAndValue(RWapplyKeyAndValue ap,void*);

Redefined from class RWCollection. Applies the user-supplied function pointed to by ap to each key-value pair of the collection, in order, from smallest to largest.

RWBinaryTree
asBinaryTree();
RWBag
asBag() const;
RWSet
asSet() const;
RWOrdered
asOrderedCollection() const;
RWBinaryTree
asSortedCollection() const:

Converts the RWBTreeDictionary to an RWBag, RWSet, RWOrdered, or an RWBinaryTree. Note that since a dictionary contains pairs of keys and values, the result of this call will be a container holding RWCollectableAssociations. Note also that the return value is a copy of the data. This can be very expensive for large collections. Consider using operator+=() to insert each RWCollectableAssociation from this dictionary into a collection of your choice.

virtual RWspace
binaryStoreSize() const;

Inherited from class RWCollection.

virtual void
clear();

Redefined from class RWCollection. Removes all key-value pairs from the collection.

virtual void
clearAndDestroy();

Redefined from class RWCollection. Removes all key-value pairs in the collection, and deletes both the key and the value.

virtual int
compareTo(const RWCollectable* a) const;

Inherited from class RWCollectable.

virtual RWBoolean
contains(const RWCollectable* target) const;

Inherited from class RWCollection.

virtual size_t
entries() const;

Redefined from class RWCollection.

virtual RWCollectable*
find(const RWCollectable* target) const;

Redefined from class RWCollection. Returns the key in the collection which compares equal to the object pointed to by target, or nil if no key is found.

RWCollectable*
findKeyAndValue(const RWCollectable* target,
                RWCollectable*& v) const;

Returns the key in the collection which compares equal to the object pointed to by target, or nil if no key was found. The value is put in v. You are responsible for defining v before calling this function.

RWCollectable*
findValue(const RWCollectable* target) const;

Returns the value associated with the key which compares equal to the object pointed to by target, or nil if no key was found.

RWCollectable*
findValue(const RWCollectable* target,
          RWCollectable* newValue);

Returns the value associated with the key which compares equal to the object pointed to by target, or nil if no key was found. Replaces the value with newValue (if a key was found).

virtual unsigned
hash() const;

Inherited from class RWCollectable.

unsigned
height() const;

Inherited from class RWBTree.

RWCollectable*
insertKeyAndValue(RWCollectable* key,RWCollectable* value);

Adds a key-value pair to the collection and returns the key if successful, nil if the key is already in the collection.

virtual RWClassID
isA() const;

Redefined from class RWCollectable to return __RWBTREEDICTIONARY.

virtual RWBoolean
isEmpty() const;

Inherited from class RWBTree.

virtual RWBoolean
isEqual(const RWCollectable* a) const;

Inherited from class RWCollectable.

virtual size_t
occurrencesOf(const RWCollectable* target) const;

Redefined from class RWCollection. Returns the number of keys that compare equal with target. Because duplicates are not allowed, this function can only return 0 or 1.

virtual RWCollectable*
remove(const RWCollectable* target);

Redefined from class RWCollection. Removes the key and value pair for which the key compares equal to the object pointed to by target. Returns the key, or nil if no match was found.

virtual void
removeAndDestroy(const RWCollectable* target);

Redefined from class RWCollection. Removes and deletes the key and value pair for which the key compares equal to the object pointed to by target. Note that both the key and the value are deleted. Does nothing if the key is not found.

RWCollectable*
removeKeyAndValue(const RWCollectable* target,
                  RWCollectable*& v);

Removes the key and value pair for which the key compares equal to the object pointed to by target. Returns the key, or nil if no match was found. The value is put in v. You are responsible for defining v before calling this function.

virtual void
restoreGuts(RWvistream&);
virtual void
restoreGuts(RWFile&);
virtual void
saveGuts(RWvostream&) const;
virtual void
saveGuts(RWFile&) const;

Inherited from class RWCollection.

virtual RWCollection*
select(RWtestCollectable testfunc, void* x) const;

Evaluates the function pointed to by tst for the key of each item in the RWBTreeDictionary. It inserts keys and values for which the function returns TRUE into a new RWBTreeDictionary allocated off the heap and returns a pointer to this new collection. Because the new dictionary is allocated off the heap, you are responsible for deleting it when done. This is not a virtual function.

virtual RWCollection*
select(RWtestCollectablePair testfunc, void* x) const;

Evaluates the function pointed to by tst for both the key and the value of each item in the RWBTreeDictionary. It inserts keys and values for which the function returns TRUE into a new RWBTreeDictionary allocated off the heap and returns a pointer to this new collection. Because the new dictionary is allocated off the heap, you are responsible for deleting it when done. This is not a virtual function.

RWStringID
stringID();

(acts virtual) Inherited from class RWCollectable.

RWBTreeOnDisk

Synopsis

typedef long RWstoredValue ;
typedef int (*RWdiskTreeCompare)(const char*, const char*,
                                 size_t);

#include <rw/disktree.h>
#include <rw/filemgr.h>
RWFileManager fm("filename.dat");
RWBTreeOnDisk bt(fm);

Description

Class RWBTreeOnDisk represents an ordered collection of associations of keys and values, where the ordering is determined by comparing keys using an external function. The user can set this function. Duplicate keys are not allowed. Given a key, the corresponding value can be found.

This class is specifically designed for managing a B-tree in a disk file. Keys, defined to be arrays of chars, and values, defined by the typedef RWstoredValue, are stored and retrieved from a B-tree. The values can represent offsets to locations in a file where objects are stored.

The key length is set by the constructor. By default, this value is 16 characters. By default, keys are null-terminated. However, the tree can be used with embedded nulls, allowing multibyte and binary data to be used as keys. To do so you must:

• Specify TRUE for parameter ignoreNull in the constructor (see below);
• Make sure all buffers used for keys are at least as long as the key length (remember, storage and comparison will not stop with a null value);
• Use a comparison function (such as memcmp()) that ignores nulls.

This class is meant to be used with class RWFileManager which manages the allocation and deallocation of space in a disk file.

When you construct an RWBTreeOnDisk you give the location of the root node in the constructor as argument start. If this value is RWNIL (the default) then the location will be retrieved from the RWFileManager using function start() (see class RWFileManager). You can also use the enumeration createMode to set

whether to use an existing tree (creating one if one doesn't exist) or to force the creation of a new tree. The location of the resultant root node can be retrieved using member function baseLocation().

More than one B-tree can exist in a disk file. Each must have its own separate root node. This can be done by constructing more than one RWBTreeOnDisk, each with createMode set to create.

The order of the B-tree can be set in the constructor. Larger values will result in shallower trees, but less efficient use of disk space. The minimum number of entries in a node can also be set. Smaller values may result in less time spent balancing the tree, but less efficient use of disk space.

Persistence

None

Enumerations

enum styleMode {V6Style, V5Style};

This enumeration is used by the constructor to allow backwards compatibility with older V5.X style trees, which supported only 16-byte key lengths. It is used only when creating a new tree. If opening a tree for update, its type is determined automatically at runtime.

V6Style	Initialize a new tree using V6.X style trees. This is the default.
V5Style	Initialize a new tree using V5.X style trees. In this case, the key length is fixed at 16 bytes.

enum createMode {autoCreate, create};

This enumeration is used by the constructor to determine whether to force the creation of a new tree.

autoCreate	Look in the location given by the constructor argument start for the root node. If valid, use it. Otherwise, allocate a new tree. This is the default.
create	Forces the creation of a new tree. The argument start is ignored.

Public Constructor

RWBTreeOnDisk(RWFileManager& f,
              unsigned nbuf        = 10,
              createMode omode     = autoCreate,
              unsigned keylen      = 16,
              RWBoolean ignoreNull = FALSE,
              RWoffset start       = RWNIL,
              styleMode smode      = V6Style,
              unsigned halfOrder   = 10,
              unsigned minFill     = 10);

Construct a B-tree on disk. The parameters are as follows:

f	The file in which the B-tree is to be managed. This is the only required parameter.
nbuf	The maximum number of nodes that can be cached in memory.
omode	Determines whether to force the creation of a new tree or whether to attempt to open an existing tree for update (the default).
keylen	The length of a key in bytes. Ignored when opening an existing tree.
ignoreNull	Controls whether to allow embedded nulls in keys. If FALSE (the default), then keys end with a terminating null. If TRUE, then all keylen bytes are significant. Ignored when opening an existing tree.
start	Where to find the root node. If set to RWNIL (the default), then uses the value returned by the RWFileManager's start() member function. Ignored when creating a new tree.
smode	Sets the type of B-tree to create, allowing backwards compatibility (see above). The default specifies new V6.X style B-trees. Ignored when opening an existing tree.
halfOrder	One half the order of the B-tree (that is, one half the number of entries in a node). Ignored when opening an existing tree.
minFill	The minimum number of entries allowed in a node (must be less than or equal to halfOrder). Ignored when opening an existing tree.

Public Member Functions

void
applyToKeyAndValue((*ap)(const char*,RWstoredValue), void* x);

Visits all items in the collection in order, from smallest to largest, calling the user-provided function pointed to by ap with the key and value as arguments. This function should have the prototype:

    void yourApplyFunction(const char* ky,
                                RWstoredValue val,void* x);

The function yourApplyFunction may not change the key. The value x can be anything and is passed through from the call to applyToKeyAndValue(). This member function may throw an RWFileErr exception.

RWoffset
baseLocation() const;

Returns the offset of this tree's starting location within the RWFileManager. This is the value you will pass to a constructor as the start argument when you want to open one of several trees stored in one managed file.

unsigned
cacheCount() const;

Returns the maximum number of nodes that may currently be cached.

unsigned
cacheCount(unsigned newcount);

Sets the number of nodes that should be cached to newcount. Returns the old number.

void
clear();

Removes all items from the collection.This member function may throw an RWFileErr exception.

RWBoolean
contains(const char* ky) const;

Returns TRUE if the tree contains a key that is equal to the string pointed to by ky, and FALSE otherwise. This member function may throw an RWFileErr exception.

size_t
entries();

Returns the number of items in the RWBTreeOnDisk. This member function may throw an RWFileErr exception.

RWoffset
extraLocation(RWoffset newlocation);

Sets the location where this RWBTreeOnDisk keeps your own application-specific information to newlocation. Returns the previous value.

RWBoolean
findKey( const char* ky, RWCString& foundKy)const ;

Returns TRUE if ky is found, otherwise FALSE. If successful, the found key is returned as a reference in foundKy. This member function may throw an RWFileErr exception.

RWBoolean
findKeyAndValue( const char* ky,
                 RWCString& foundKy,
                 RWStoredValue& foundVal)const ;

Returns TRUE if ky is found, otherwise FALSE. If successful, the found key is returned as a reference in foundKy, and the value is returned as a reference in foundVal. This member function may throw an RWFileErr exception.

RWstoredValue
findValue(const char* ky)const;

Returns the value for the key that compares equal to the string pointed to by ky. Returns RWNIL if no key is found. This member function may throw an RWFileErr exception.

int
height();

Returns the height of the RWBTreeOnDisk. A possible exception is RWFileErr.

int
insertKeyAndValue(const char* ky,RWstoredValue v);

Adds a key-value pair to the B-tree. Returns TRUE for successful insertion, FALSE otherwise. A possible exception is RWFileErr.

unsigned
keyLength() const;

Return the length of the keys for this RWBtreeOnDisk. This number is set when the tree is first constructed and cannot be changed.

unsigned
minOrder()const;

Return the minimum number of items that may be found in any non-root node in this RWBtreeOnDisk. This number is set when the tree is first constructed and cannot be changed.

unsigned
nodeSize() const;

Returns the number of bytes used by each node of this RWBTreeOnDisk. This number is calculated from the length of the keys and the order of the tree, and cannot be changed. We make it available to you for your calculations about how many nodes to cache.

unsigned
order()const;

Return half the maximum number of items that may be stored in any node in this RWBtreeOnDisk. This number is set when the tree is first constructed and cannot be changed. This method should have been renamed "halfOrder" but is still called "order" for backward compatibility.

RWBoolean
isEmpty() const;

Returns TRUE if the RWBTreeOnDisk is empty, otherwise FALSE.

void
remove(const char* ky);

Removes the key and value pair that has a key which matches ky. This member function may throw an RWFileErr exception.

RWBoolean
replaceValue(const RWCString& key,
             const RWstoredValue newval,
             RWstoredValue& oldVal);

Attempts to replace the RWstoredValue now associated with key by the value newval. If successful, the previous value is returned by reference in oldVal; and the methed returns TRUE. Otherwise, returns FALSE.

RWdiskTreeCompare
setComparison(RWdiskTreeCompare fun);

Changes the comparison function to fun and returns the old function. This function must have prototype:

   int yourFun(const char* key1, const char* key2, size_t N);

It should return a number less than zero, equal to zero, or greater than zero depending on whether the first argument is less than, equal to or greater than the second argument, respectively. The third argument is the key length. Possible choices (among others) are strncmp() (the default), or strnicmp() (for case-independent comparisons).

RWBufferedPageHeap

RWBufferedPageHeap . RWVirtualPageHeap

Synopsis

#include <rw/bufpage.h>
(Abstract base class )

Description

This is an abstract base class that represents an abstract page heap buffered through a set of memory buffers. It inherits from the abstract base class RWVirtualPageHeap, which represents an abstract page heap.

RWBufferedPageHeap will supply and maintain a set of memory buffers. Specializing classes should supply the actual physical mechanism to swap pages in and out of these buffers by supplying definitions for the pure virtual functions swapIn(RWHandle, void*) and swapOut(RWHandle, void*).

The specializing class should also supply appropriate definitions for the public functions allocate() and deallocate(RWHandle).

For a sample implementation of a specializing class, see class RWDiskPageHeap.

Persistence

None

Public Constructor

RWBufferedPageHeap(unsigned pgsize, unsigned nbufs=10);

Constructs a buffered page heap with page size pgsize. The number of buffers (each of size pgsize) that will be allocated on the heap will be nbufs. If there is insufficient memory to satisfy the request, then the state of the resultant object as returned by member function isValid() will be FALSE, otherwise, TRUE.

Protected Member Functions

virtual RWBoolean
swapIn(RWHandle h, void* buf)  = 0;
virtual RWBoolean
swapOut(RWHandle, h void* buf) = 0;

It is the responsibility of the specializing class to supply definitions for these two pure virtual functions. Function swapOut() should copy the page with handle h from the buffer pointed to by buf to the swapping medium. Function swapIn() should copy the page with handle h into the buffer pointed to by buf.

Public Member Functions

virtual RWHandle
allocate() = 0;

It is the responsibility of the specializing class to supply a definition for this pure virtual function. The specializing class should allocate a page and return a unique handle for it. It should return zero if it cannot satisfy the request. The size of the page is set by the constructor.

virtual
~RWBufferedPageHeap();

Deallocates all internal buffers.

RWBoolean
isValid();

Returns TRUE if self is in a valid state. A possible reason why the object might not be valid is insufficient memory to allocate the internal buffers.

virtual void
deallocate(RWHandle h);

Redefined from class RWVirtualPageHeap. It is never an error to call this function with argument zero. Even though this is not a pure virtual function, it is the responsibility of the specializing class to supply an appropriate definition for this function. All this definition does is release any buffers associated with the handle h. Just as the actual page allocation is done by the specializing class through virtual function allocate(), so must the actual deallocation be done by overriding deallocate().

virtual void
dirty(RWHandle h);

Redefined from class RWVirtualPageHeap.

virtual void*
lock(RWHandle h);

Redefined from class RWVirtualPageHeap.

virtual void
unlock(RWHandle h);

Redefined from class RWVirtualPageHeap.

RWCacheManager

Synopsis

#include <rw/cacheman.h>
RWFile f("file.dat");       // Construct a file
RWCacheManager(&f, 100);    // Cache 100 byte blocks to file.dat

Description

Class RWCacheManager caches fixed length blocks to and from an associated RWFile. The block size can be of any length and is set at construction time. The number of cached blocks can also be set at construction time.

Writes to the file may be deferred. Use member function flush() to have any pending writes performed.

Persistence

None

Example

#include <rw/cacheman.h> #include <rw/rwfile.h> struct Record { int i; float f; char str[15]; }; main(){ RWoffset loc; RWFile file("file.dat"); // Construct a file // Construct a cache, using 20 slots for struct Record: RWCacheManager cache(&file, sizeof(Record), 20); Record r; // ... cache.write(loc, &r); // ... cache.read(loc, &r); }

Public Constructor

RWCacheManager(RWFile* file, unsigned blocksz,
               unsigned mxblks = 10);

Construct a cache for the RWFile pointed to by file. The length of the fixed-size blocks is given by blocksz. The number of cached blocks is given by mxblks. If the total number of bytes cached would exceed the maximum value of an unsigned int, then RWCacheManager will quietly decide to cache a smaller number of blocks.

Public Destructor

~RWCacheManager();

Performs any pending I/O operations (i.e., calls flush()) and deallocates any allocated memory.

Public Member Functions

RWBoolean
flush();

Perform any pending I/O operations. Returns TRUE if the flush was successful, FALSE otherwise.

void
invalidate();

Invalidate the cache.

RWBoolean
read(RWoffset locn, void* dat);

Return the data located at offset locn of the associated RWFile. The data is put in the buffer pointed to by dat. This buffer must be at least as long as the block size specified when the cache was constructed. Returns TRUE if the operation was successful, otherwise FALSE.

RWBoolean
write(RWoffset locn, void* dat);

Write the block of data pointed to by dat to the offset locn of the associated RWFile. The number of bytes written is given by the block size specified when the cache was constructed. The actual write to disk may be deferred. Use member function flush() to perform any pending output. Returns TRUE if the operation was successful, otherwise FALSE.

RWCLIPstreambuf

RWCLIPstreambuf . streambuf

Synopsis

#include <rw/winstrea.h>
#include <iostream.h>
iostream str( new RWCLIPstreambuf() );

Description

Class RWCLIPstreambuf is a specialized streambuf that gets and puts sequences of characters to Microsoft Windows global memory. It can be used to exchange data through Windows clipboard facility.

The class has two modes of operation: dynamic and static. In dynamic mode, memory is allocated and reallocated as needed. 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 for "insertions," i.e., clipboard "cuts" and "copies." 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 for "extractions," i.e., clipboard "pastes."

In dynamic mode, the RWCLIPstreambuf "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 RWCLIPstreambuf destructor to free any allocated memory. After the call to str(), it becomes the user's responsibility.

In static mode, the user 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.

Persistence

None

Example

//Instructions: compile as a Windows program. //Run this program, then using your favorite text editor or word //processor, select paste and see the result! #include <rw/winstrea.h> #include <stdlib.h> #include <iostream.h> #include <windows.h> void postToClipboard(HWND owner); main() { postToClipboard(NULL); return 0; } // PASS YOUR WINDOW HANDLE TO THIS FUNCTION THEN PASS YOUR VALUES // TO THE CLIPBOARD USING ostr. void postToClipboard(HWND owner) { //Build the clipstream buffer on the heap RWCLIPstreambuf* buf = new RWCLIPstreambuf(); ostream ostr(buf); double d = 12.34; ostr << "Some text to be exchanged through the clipboard.\n"; ostr << "Might as well add a double: " << d << endl; ostr.put('\0'); // Include the terminating null // Lock the streambuf, get its handle: HANDLE hMem = buf->str(); OpenClipboard(owner);

EmptyClipboard(); SetClipboardData(CF_TEXT, hMem); CloseClipboard(); // Don't delete the buffer!. Windows is now responsible for it. }

The owner of the clipboard is passed in as parameter "owner". A conventional ostream is created, except that it uses an RWCLIPstreambuf as its associated streambuf. It can be used much like any other ostream, such as cout, except that characters will be inserted into Windows global memory.

Some text and a double is inserted into the ostream. Finally, member function str() is called which returns a Windows HANDLE. The clipboard is then opened, emptied, and the new data put into it with format CF_TEXT which, in this case, is appropriate because a simple ostream was used to format the output. If a specializing virtual streams class such as RWbostream or RWpostream had been used instead, the format is not so simple. In this case, the user might want to register his or her own format, using the Windows function RegisterClipboardFormat().

Public Constructors

RWCLIPstreambuf();

Constructs an empty RWCLIPstreambuf 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.

RWCLIPstreambuf(HANDLE hMem);

Constructs an RWCLIPstreambuf in static mode, using the memory block with global handle hMem. The effect of gets and puts beyond the size of this memory block is unspecified.

Public Destructor

~RWCLIPstreambuf();

If member function str() has not been called, the destructor unlocks the handle and, if in dynamic mode, also frees it.

Public Member Functions

Because RWCLIPstreambuf inherits from streambuf, any of the latter's member functions can be used. Furthermore, RWCLIPstreambuf has been designed to be analogous to strstreambuf. However, note that the return type of str() is a HANDLE, rather than a char*.

HANDLE
str();

Returns an (unlocked) HANDLE to the global memory being used. The RWCLIPstreambuf should now be regarded as "frozen": the effect of inserting any more characters is undefined. If the RWCLIPstreambuf 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 RWCLIPstreambuf.

RWCollectable

Synopsis

typedef RWCollectable Object;  // Smalltalk typedef
#include <rw/collect.h>

Description

Class RWCollectable is an abstract base class for collectable objects. This class contains virtual functions for identifying, hashing, comparing, storing and retrieving collectable objects. While these virtual functions have simple default definitions, objects that inherit this base class will typically redefine one or more of them.

Persistence

Polymorphic

Virtual Functions

virtual
~RWCollectable();

All functions that inherit class RWCollectable have virtual destructors. This allows them to be deleted by such member functions as removeAndDestroy() without knowing their type.

virtual RWspace
binaryStoreSize() const;

Returns the number of bytes used by the virtual function saveGuts(RWFile&) to store an object. Typically, this involves adding up the space required to store all primitives, plus the results of calling recursiveStoreSize() for all objects inheriting from RWCollectable. See the Tool.h++ User's Guide Section entitled "Virtual Function binaryStoreSize" for details.

virtual int
compareTo(const RWCollectable*) const;

The function compareTo() is necessary to sort the items in a collection. If p1 and p2 are pointers to RWCollectable objects, the statement

p1->compareTo(p2);

should return:

0 if *p1 "is equal to" *p2;

>0 if *p1 is "larger" than *p2;

<0 if *p1 is "smaller" than *p2.

Note that the meaning of "is equal to," "larger" and "smaller" is left to the user. The default definition provided by the base class is based on the addresses, i.e.,

return this == p2 ? 0 : (this > p2 ? 1 : -1);

and is probably not very useful.

virtual unsigned
hash() const;

Returns a hash value. This function is necessary for collection classes that use hash table look-up. The default definition provided by the base class hashes the object's address:

return (unsigned)this;

It is important that the hash value be the same for all objects which return TRUE to isEqual().

virtual RWClassID
isA() const;

Returns a class identification number (typedef'd to be an unsigned short). The default definition returns __RWCOLLECTABLE. Identification numbers greater than or equal to 0x8000 (hex) are reserved for Rogue Wave objects. User defined classes should define isA() to return a number between 0 and 0x7FFF.

virtual RWBoolean
isEqual(const RWCollectable* t) const;

Returns TRUE if collectable object "matches" object at address t. The default definition is:

return this == t;

i.e., both objects have the same address (a test for identity). The definition may be redefined in any consistent way.

virtual RWCollectable*
newSpecies() const;

Allocates a new object off the heap of the same type as self and returns a pointer to it. You are responsible for deleting the object when done with it.

virtual void
restoreGuts(RWFile&);

Read an object's state from a binary file, using class RWFile, replacing the previous state.

virtual void
restoreGuts(RWvistream&);

Read an object's state from an input stream, replacing the previous state.

virtual void
saveGuts(RWFile&) const;

Write an object's state to a binary file, using class RWFile.

virtual void
saveGuts(RWvostream&) const;

Write an object's state to an output stream.

RWStringID
stringID();

Returns the identification string for the class. Acts virtual, although it is 1 not.

RWspace
recursiveStoreSize() const;

Returns the number of bytes required to store the object using the global operator

RWFile& operator<<(RWFile&, const RWCollectable&);

Recursively calls binaryStoreSize(), taking duplicate objects into account.

Static Public Member Functions

static RWClassID
classID(const RWStringID& name);

Returns the result of looking up the RWClassID associated with name in the global RWFactory.

static RWClassID
classIsA();

Returns the RWClassID of this class.

static RWBoolean
isAtom(RWClassID id);

Returns TRUE if id is the RWClassID that is associated with an RWCollectable class that has a programmer-chosen RWStringID.

static RWspace
nilStoreSize();

Returns the number of bytes required to store a rwnil pointer in an RWFile.

Related Global Operators

RWvostream&
operator<<(RWvostream&, const RWCollectable& obj);
RWFile&
operator<<(RWFile&,     const RWCollectable& obj);

Saves the object obj to a virtual stream or RWFile, respectively. Recursively calls the virtual function saveGuts(), taking duplicate objects into account. See the Tools.h++ User's Guide section entitled "Persistence" for more information.

RWvistream&
operator>>(RWvistream&, RWCollectable& obj);
RWFile&
operator>>(RWFile&,     RWCollectable& obj);

Restores an object inheriting from RWCollectable into obj from a virtual stream or RWFile, respectively, replacing the previous contents of obj. Recursively calls the virtual function restoreGuts(), taking duplicate objects into account. See the Tools.h++ User's Guide section entitled "Persistence" for more information. Various exceptions that could be thrown are RWInternalErr (if the RWFactory does not know how to make the object), and RWExternalErr (corrupted stream or file).

RWvistream&
operator>>(RWvistream&, RWCollectable*& obj);
RWFile&
operator>>(RWFile&,     RWCollectable*& obj);

Looks at the next object on the input stream or RWFile, respectively, and either creates a new object of the proper type off the heap and returns a pointer to it, or else returns a pointer to a previously read instance. Recursively calls the virtual function restoreGuts(), taking duplicate objects into account. If an object is created off the heap, then you are responsible for deleting it. See the Tools.h++ User's Guide section entitled "Persistence" for more information. Various exceptions that could be thrown are RWInternalErr (if the RWFactory does not know how to make the object), and RWExternalErr (corrupted stream or file). In case an exception is thrown during this call, the pointer to the partly restored object will probably be lost, and memory will leak. For this reason, you may prefer to use the static methods tryRecursiveRestore() documented above.

RWCollectableAssociation

RWCollectableAssociation . RWCollectable

Synopsis

#include <rw/collass.h>

Description

RWCollectableAssociation inherits class RWCollectable. Used internally to associate a key with a value in the Tools.h++ "dictionary" collection classes. Comparison and equality testing are forwarded to the key part of the association.

Persistence

Polymorphic

Related Classes

The "dictionary containers" RWBTreeDictionary, RWHashDictionary, and RWIdentityDictionary make use of RWCollectableAssociation. When any of their contents is dealt with as an RWCollectable, as when operator+=() or asBag() etc. is used, the RWCollectableAssociation will be exposed.

Public Constructors

RWCollectableAssociation();
RWCollectableAssociation(RWCollectable* k, RWCollectable* v);

Construct an RWCollectableAssociation with the given key and value.

Public Destructor

virtual ~RWCollectableAssociation();
virtual RWspace
binaryStoreSize() const;

Redefined from class RWCollectable.

Public Member Functions

virtual int
compareTo(const RWCollectable* c) const;

Redefined from class RWCollectable. Returns the results of calling key()->compareTo(c).

virtual unsigned
hash() const;

Redefined from class RWCollectable. Returns the results of calling

  key()->hash().
virtual RWClassID
isA() const;

Redefined from class RWCollectable to return __RWCOLLECTABLEASSOCIATION.

virtual RWBoolean
isEqual(const RWCollectable* c) const;

Redefined from class RWCollectable. Returns the results of calling

  key()->isEqual(c).
RWCollectable*
key() const;

Returns the key part of the association.

RWCollectable*
value() const;

Returns the value part of the association.

RWCollectable*
value(RWCollectable* ct);

Sets the value to ct and returns the old value.

virtual void
restoreGuts(RWvistream&);
virtual void
restoreGuts(RWFile&);
virtual void
saveGuts(RWvostream&) const;
virtual void
saveGuts(RWFile&) const;

Redefined from class RWCollectable.

RWCollectableDate

. RWCollectable

RWCollectableDate

. RWDate

Synopsis

typedef RWCollectableDate Date;  // Smalltalk typedef
#include <rw/colldate.h>
RWCollectableDate  d;

Description

Collectable Dates. Inherits classes RWDate and RWCollectable. This class is useful when dates are used as keys in the "dictionary" collection classes, or if dates are stored and retrieved as RWCollectables. The virtual functions of the base class RWCollectable have been redefined.

Persistence

Polymorphic

Public Constructors

RWCollectableDate();
RWCollectableDate(unsigned long julianDate);
RWCollectableDate(unsigned day, unsigned year);
RWCollectableDate(unsigned day, unsigned month, unsigned year);
RWCollectableDate(unsigned day, const char* mon,
                  unsigned year,const RWLocale&
                  locale = RWLocale::global());
RWCollectableDate(istream& s, const RWLocale& locale =
                  RWLocale::global());
RWCollectableDate(const RWCString& str,const RWLocale&
                  locale = RWLocale::global());
RWCollectableDate(const RWTime& t, const RWZone& zone =
                  RWZone::local());
RWCollectableDate(const struct tm* tmb);
RWCollectableDate(const RWDate& d);

Calls the corresponding constructor of the base class RWDate.

Public Member Functions

virtual RWspace
binaryStoreSize() const;

Redefined from class RWCollectable.

virtual int
compareTo(const RWCollectable* c) const;

Redefined from class RWCollectable. Returns the results of calling

  RWDate::compareTo.
virtual unsigned
hash() const;

Redefined from class RWCollectable. Returns the results of calling

  RWDate::hash().
virtual RWClassID
isA() const;

Redefined from class RWCollectable to return __RWCOLLECTABLEDATE.

virtual RWBoolean
isEqual(const RWCollectable* t) const;

Redefined from class RWCollectable. Returns the results of calling operator==() for the base class RWDate by using appropriate casts.

virtual void
restoreGuts(RWvistream&);
virtual void
restoreGuts(RWFile&);
virtual void
saveGuts(RWvostream&) const;
virtual void
saveGuts(RWFile&) const;

Redefined from class RWCollectable.

RWStringID
stringID();

(acts virtual) Inherited from class RWCollectable.

RWCollectableInt

. RWCollectable

RWCollectableInt

. RWInteger

Synopsis

typedef RWCollectableInt Integer;  // Smalltalk typedef
#include <rw/collint.h>
RWCollectableInt  i;

Description

Collectable integers. Inherits classes RWInteger and RWCollectable. This class is useful when integers are used as keys in the "dictionary" collection classes, or if integers are stored and retrieved as RWCollectables. The virtual functions of the base class RWCollectable have been redefined.

Persistence

Polymorphic

Public Constructors

RWCollectableInt();

Calls the appropriate base class constructor. See RWInteger::RWInteger().

RWCollectableInt(int i);

Calls the appropriate base class constructor. See RWInteger::RWInteger(int).

Public Member Functions

virtual RWspace
binaryStoreSize() const;

Redefined from class RWCollectable.

virtual int
compareTo(const RWCollectable* c) const;

Redefined from class RWCollectable. Returns the difference between self and the RWCollectableInt pointed to by c.

virtual unsigned
hash() const;

Redefined from class RWCollectable. Returns the RWCollectableInt's value as an unsigned, to be used as a hash value.

virtual RWClassID
isA() const;

Redefined from class RWCollectable to return __RWCOLLECTABLEINT.

virtual RWBoolean
isEqual(const RWCollectable* c) const;

Redefined from class RWCollectable. Returns TRUE if self has the same value as the RWCollectableInt at address c.

virtual void
restoreGuts(RWvistream&);
virtual void
restoreGuts(RWFile&);
virtual void
saveGuts(RWvostream&) const;
virtual void
saveGuts(RWFile&) const;

Redefined from class RWCollectable.

RWStringID
stringID();

(acts virtual) Inherited from class RWCollectable.

RWCollectableString

. RWCollectable

RWCollectableString

. RWCString

Synopsis

typedef RWCollectableString String;  // Smalltalk typedef
#include <rw/collstr.h>
RWCollectableString  c;

Description

Collectable strings. This class is useful when strings are stored and retrieved as RWCollectables, or when they are used as keys in the "dictionary" collection classes. Class RWCollectableString inherits from both class RWCString and class RWCollectable. The virtual functions of the base class RWCollectable have been redefined.

Persistence

Polymorphic

Public Constructors

RWCollectableString();

Construct an RWCollectableString with zero characters.

RWCollectableString(const RWCString& s);

Construct an RWCollectableString from the RWCString s.

RWCollectableString(const char* c);

Conversion from character string.

RWCollectableString(const RWCSubString&);

Conversion from sub-string.

RWCollectableString(char c, size_t N);

Construct an RWCollectableString with N characters (default blanks).

Public Member Functions

virtual RWspace
binaryStoreSize() const;

Redefined from class RWCollectable.

virtual int
compareTo(const RWCollectable* c) const;

Redefined from class RWCollectable. returns the result of RWCString::compareTo(*(const String*)c, RWCString::exact). This compares strings lexicographically, with case considered. It would be possible to define , for instance, CaseFoldedString which did comparisons ignoring case. We have deliberately left this as an exercise for two reasons: Because it is both easy to do and not universally needed; and because the presence of both RWCollectableStrings and such a CaseFoldedString in any kind of sorted collection has the potential for very confusing behavior, since the result of a comparison would depend on the order in which the comparison was done.

virtual unsigned
hash() const;

Redefined from class RWCollectable. Calls RWCString::hash() and returns the results.

virtual RWClassID
isA() const;

Redefined from class RWCollectable to return __RWCOLLECTABLESTRING.

virtual RWBoolean
isEqual(const RWCollectable* c) const;

Redefined from class RWCollectable. Calls RWCString::operator==() (i.e., the equivalence operator) with c as the argument and returns the results.

virtual void
restoreGuts(RWvistream&);
virtual void
restoreGuts(RWFile&);
virtual void
saveGuts(RWvostream&) const;
virtual void
saveGuts(RWFile&) const;

Redefined from class RWCollectable.

RWStringID
stringID();

(acts virtual) Inherited from class RWCollectable.

RWCollectableTime

. RWCollectable

RWCollectableTime

. RWTime

Synopsis

typedef RWCollectableTime ;  // Smalltalk typedef
#include <rw/colltime.h>
RWCollectableTime  t;

Description

Inherits classes RWTime and RWCollectable. This class is useful when times are used as keys in the "dictionary" collection classes, or if times are stored and retrieved as RWCollectables. The virtual functions of the base class RWCollectable have been redefined.

Persistence

Polymorphic

Public Constructors

RWCollectableTime();
RWCollectableTime(unsigned long s);
RWCollectableTime(unsigned hour, unsigned minute,
                  unsigned sec = 0,const RWZone&
                  zone = RWZone::local());
RWCollectableTime(const RWDate& day, unsigned hour=0,
                  unsigned minute=0, unsigned sec = 0,
                  const RWZone& zone = RWZone::local());
RWCollectableTime(const RWDate& day, const RWCString& str,
                  const RWZone& zone = RWZone::local(),
                  const RWLocale& locale = RWLocale::global());
RWCollectableTime(const struct tm* tmb,
                  const RWZone& zone = RWZone::local());

Calls the corresponding constructor of RWTime.

Public Member Functions

virtual RWspace
binaryStoreSize() const;

Redefined from class RWCollectable.

virtual int
compareTo(const RWCollectable* c) const;

Redefined from class RWCollectable. Returns the results of calling

  RWTime::compareTo.
virtual unsigned
hash() const;

Redefined from class RWCollectable. Returns the results of calling

  RWTime::hash().
virtual RWClassID
isA() const;

Redefined from class RWCollectable to return __RWCOLLECTABLETIME.

virtual RWBoolean
isEqual(const RWCollectable* c) const;

Redefined from class RWCollectable. Returns the results of calling operator==() for the base class RWTime by using appropriate casts.

virtual void
restoreGuts(RWvistream&);
virtual void
restoreGuts(RWFile&);
virtual void
saveGuts(RWvostream&) const;
virtual void
saveGuts(RWFile&) const;

Redefined from class RWCollectable.

RWStringID
stringID();

(acts virtual) Inherited from class RWCollectable.

RWCollection

RWCollection . RWCollectable

Synopsis

#include <rw/colclass.h>
typedef RWCollection Collection;   // Smalltalk typedef

Description

Class RWCollection is an abstract base class for the Smalltalk-like collection classes. The class contains virtual functions for inserting and retrieving pointers to RWCollectable objects into the collection classes. Virtual functions are also provided for storing and reading the collections to files and streams. Collections that inherit this base class will typically redefine one or more of these functions.

In the documentation below, pure virtual functions are indicated by "= 0" in their declaration. These functions must be defined in derived classes. For these functions the description is intended to be generic -- all inheriting collection classes generally follow the described pattern. Exceptions are noted in the documentation for the particular class.

For many other functions, a suitable definition is provided by RWCollection and a deriving class may not need to redefine the function. Examples are contains() or restoreGuts().

Persistence

Polymorphic

Public Member Operators

void
operator+=(const RWCollection&);
void
operator-=(const RWCollection&);

Adds or removes, respectively, each item in the argument to or from self. Using operator+=(somePreSortedCollection) on an RWBinaryTree can cause that tree to become unbalanced; possibly to the point of stack overflow.

Public Member Functions

virtual
~RWCollection();

Null definition (does nothing).