Liren Large Software Subsidy 7/07.iso/c/c221/2.ddi/DOC/TOOLS4_2.DOC

Text File | 1992-04-01 | 315.7 KB | 12,514 lines

                                     Part 2:
                                    Tools.h++
                                 Class Reference











                                                        Class Reference



          Because C++ is still a young language, there is no standard
          way to structure a reference manual for a class or group of
          classes.  The reference is presented here as an alphabetical
          listing of classes with their member and global functions
          grouped in categories according to their general use.  The
          categories are not a part of the C++ language, but do provide
          a way of organizing the many functions.
          Each class includes a brief description, an illustration
          showing its inheritance hierarchy, and a synopsis, indicating
          the header file(s) and Smalltalk typedef (if appropriate)
          associated with the class.  The synopsis also shows a
          declaration and definition of a class object, and any typedefs
          that are used.
          Member functions for each class are listed alphabetically.
          Member functions fall into three general types:
          1. Functions that are unique to a class.  The complete
             documentation for these functions is presented in the
             class where they occur.  An example is balance(), a member
             of the class BinaryTree.
          2. Functions that are inherited from a base class without
             being redefined.  The complete documentation for these
             functions is presented in the defining base class.  An
             example is clearAndDestroy(), for class RWBinaryTree,
             which is inherited from class RWCollection.
          3. Functions that are redefined in a derived class.  These
             are usually virtual functions.  The documentation for
             these functions usually directs you to the base class, but
             may also mention peculiarities that are relevant to the
             derived class.  An example is apply(), for class
             RWBinaryTree.
          There are two general methods for finding an object within a
          collection:
          1. One can find an object that is identical to a key (i.e.,
             with the same address).  Member functions that work this
             way generally have names like findReference(), or
             occurrencesOfReference(), etc.  For some of the collection
             classes, this is the only way that you can find an object.
             These types of collections have the word "Identity" in
             their name (RWIdentitySet and RWIdentityDictionary).

Tools.h++ Class Library     165








                      CLASS REFERENCE

          2. One can look for an object that is equal to a key.  Here,
             there are two different techniques.  The first is to find
             an object that returns true for a "tester" function,
             perhaps using a hash value to narrow the search.  For the
             Smalltalk-like classes, the tester function is the virtual
             function isEqual().  For the generic collection classes, a
             user-defined tester function must be provided.  The second
             technique is to look for an object that compares equal to
             a key.  These collection functions are sorted collections
             that use the virtual function compareTo() to sort their
             items.  An object is considered to have been "found" when
             compareTo() returns zero.  In the documentation that
             follows, the first technique will be referred to as
             finding an object that isEqual to, the second as compares
             equal to.
          Throughout the documentation, there is frequent reference to
          "self." This should be understood to mean *this.




























Rogue Wave      Tools.h++ Class Library                  166








                      CLASS REFERENCE



class GBitVec(size)




Synopsis  #include <gbitvec.h>
          declare(GBitVec,size)

          GBitVec(size) a;



Descripti GBitVec(size) is a bit vector of fixed length size.  The length
on        cannot be changed dynamically (see class RWBitVec if you need a
          bit vector whose length can be changed at run time).  Objects of
          type GBitVec(size) are declared with macros defined in the
          standard C++ header file <generic.h>.
          Bits are numbered from 0 through size-1, inclusive.
          No copy constructor has been defined.  Hence, copies use the
          default copy constructor (i.e., a bitwise copy will be made).























Rogue Wave      Tools.h++ Class Library                  167








                      CLASS REFERENCE

Example   In this example, a bit vector 24 bits long is declared and exercised:
          #include <gbitvec.h>
          declare(GBitVec,24)        // declare a 24 bit long vector

          main()

          {

            GBitVec(24) a, b;        // Allocate two vectors.

            a(2) = TRUE;             // Set bit 2 (the third bit) of a on.

            b(3) = TRUE;             // Set bit 3 (the fourth bit) of b on.

            GBitVec c = a ^ b;       // Set c to the XOR of a and b.

          }



Public    GBitVec(size)();
construct Construct a bit vector size elements long, with all bits
ors       initialized to FALSE.

          GBitVec(size)(RWBoolean f);
          Construct a bit vector size elements long, with all bits
          initialized to f.

   GBitVec(size)(unsigned long v);
Construct a bit vector size elements long, initialized to the bits
of v. If size is greater than sizeof(v), the extra bits will be set
to zero.


AssignmentGBitVec(sz)&        operator=(const GBitVec(sz)& v);
operators Set each element of self to the corresponding bit value of v.
          Return a reference to self.

   GBitVec(sz)&     operator=(RWBoolean f);
Set all elements of self to the boolean value f.





Rogue Wave      Tools.h++ Class Library                  168








                      CLASS REFERENCE

   GBitVec(sz)&     operator&=(const GBitVec(sz)& v);
   GBitVec(sz)&     operator^=(const GBitVec(sz)& v);
   GBitVec(sz)&     operator|=(const GBitVec(sz)& v);
Logical assignments.  Set each element of self to the logical AND,
XOR, or OR, respectively, of self and the corresponding bit in v.


Indexing  RWBitRef            operator[](int i);
operators Returns a reference to the i'th bit of self.  This reference can be
          used as an lvalue.  The index i must be between 0 and sz-1,
          inclusive.  Bounds checking will occur.

   RWBitRef         operator()(int i);
Returns a reference to the i'th bit of self.  This reference can be
used as an lvalue.  The index i must be between 0 and sz-1,
inclusive.  No bounds checking is done.


Logical   RWBoolean           operator==(const GBitVec(sz)& v) const;
operators Returns TRUE if each bit of self is set to the same value as the
          corresponding bit in v.  Otherwise, returns FALSE.

   RWBoolean        operator!=(const GBitVec(sz)& v) const;
Returns FALSE if each bit of self is set to the same value as the
corresponding bit in v.  Otherwise, returns TRUE.


Public    void                clearBit(int i);
member    Clears (i.e., sets to FALSE) the bit with index i.  The index i
functions must be between 0 and size-1.  No bounds checking is performed.
          The following are equivalent, although clearBit(int) is slightly
          smaller and faster than using operator()(int):

                 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.

   void             setBit(int 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(int) is slightly smaller

Rogue Wave      Tools.h++ Class Library                  169








                      CLASS REFERENCE

and faster than using operator()(int)

                 a(i) = TRUE;
                 a.setBit(i);

   RWBoolean        testBit(int 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(int) is slightly smaller and faster than using
operator()(int):

                 if( a(i) )       doSomething();
                 if( testBit(i) ) doSomething();



Related   GBitVec(sz) operator&(const GBitVec(sz)& v1, const GBitVec(sz)& v2);
global    GBitVec(sz) operator^(const GBitVec(sz)& v1, const GBitVec(sz)& v2);
functions GBitVec(sz) operator|(const GBitVec(sz)& v1, const GBitVec(sz)& v2);
          Return the logical AND, XOR, and OR, respectively, of vectors v1
          and v2.
























Rogue Wave      Tools.h++ Class Library                  170








                      CLASS REFERENCE



class GDlist(type)                                   GDlist(type)
                                                           |
                                                        RWDlist
                                                           |
                                                        RWSlist

Synopsis  #include <gdlist.h>
          declare(GDlist, type)

          GDlist(type) a;



Descripti Class GDlist(type) represents a group of ordered elements of type
on        type, not accessible by an external key.  Duplicates are allowed.
          This class is implemented as a doubly-linked list.  Objects of type
          GDlist(type) are declared with macros defined in the standard C++
          header file <generic.h>.
          Objects stored and retrieved with class GDlist(type) do not
          need to inherit class RWCollectable.  However, in order to
          find a particular item within the collection, a user-provided
          global "tester" function is required to test for a "match",
          definable in any consistent way.  This function should have
          prototype:
            RWBoolean yourTesterFunction(const type* c, const void* d);

          The argument c is a candidate within the collection to be
          tested for a match.  The argument d is for your convenience
          and will be passed to yourTesterFunction().  The function
          should return TRUE if a "match" is found between c and d.
          In order to simplify the documentation below, an imaginary
          typedef
            typedef void (*yourTester)(const type*, const void*);

          has been used for this tester function.








Rogue Wave      Tools.h++ Class Library                  171








                      CLASS REFERENCE

Example   #include <gdlist.h>
          #include <rstream.h>

          declare(GDlist,int)  /* Declare a list of ints */

          main()
          {
            GDlist(int) list;                 // Define a list of ints

            list.insert(new int(5)); // Insert some ints
            list.insert(new int(7));
            list.insert(new int(1));
            list.prepend(new int(11));

            GDlistIterator(int) next(list);

            while( int* ip = next() )
              cout << *ip << NL;              // Print out the members
          }

          Program output:
             11

             5

             7

                       1



Public       GDlist(type)();
constructors Construct an empty collection.

   GDlist(type)(type* a);
Construct a collection with one entry a.

   GDlist(type)(const GDlist(type)& a);
Copy constructor.  A shallow copy of a is made.






Rogue Wave      Tools.h++ Class Library                  172








                      CLASS REFERENCE


Assignmentvoid                operator=(const GDlist(type)& a);
operator  Assignment operator.  A shallow copy of a is made.


Public    type*               append(type* a);
member    Adds an item to the end of the collection.  Returns nil if the
functions insertion was unsuccessful.

   void             apply( (*ap)(type*, void*), void* );
Visits all the items in the collection in order, from first to last,
calling the user-provided function pointed to by ap for each item.
This function should have prototype:

                    void yourApplyFunction(type* c, void*);

and can perform any operation on the object at address c.  The last
argument is useful for passing data to the apply function.

   type*&           at(int i);
Allows access to the i'th element of the collection.  If i is out of
range then an exception with error TOOL_INDEX will occur.  This
variant can be used as an lvalue.

   const type*      at(int i) const;
Allows access to the i'th element of the collection.  If i is out of
range then nil is returned.

   void             clear();
Removes all items in the collection.

   RWBoolean        contains(yourTester t, const void* d) const;
Returns TRUE if the collection contains an item for which the user-
defined function pointed to by t finds a match with d.

   RWBoolean        containsReference(const type* e) const;
Returns TRUE if the collection contains an item with the address e.

   unsigned         entries() const;
Returns the number of items in the collection.

   type*            find(yourTester t, const void* d) const;
Returns the first item in the collection for which the user-provided
function pointed to by t finds a match with d, or nil if no item is

Rogue Wave      Tools.h++ Class Library                  173








                      CLASS REFERENCE

found.

   type*            findReference(const type* e) const;
Returns the first item in the collection with the address e, or nil
if no item is found.

   type*            first() const;
Returns the first item of the collection.

   type*            get();
Returns and removes the first item of the collection.

   type*            insert(type* e);
Adds an item to the end of the collection and returns it.  Returns
nil if the insertion was unsuccessful.

   type*            insertAfter(int i, type* e);
Adds an item after the i'th item of the collection and returns it.
Returns nil if the insertion was unsuccessful.

   RWBoolean        isEmpty() const;
Returns TRUE if the collection is empty, otherwise FALSE.

   type*            last() const;
Returns the last item of the collection.

   unsigned    occurrencesOf(yourTester t, const void* d) const;
Returns the number of occurrences in the collection for which the
user-provided function pointed to by t finds a match with d.

   unsigned   occurrencesOfReference(const type* e) const;
Returns the number of items in the collection with the address e.

   type*            prepend(type* a);
Adds an item to the beginning of the collection.  Returns nil if the
insertion was unsuccessful.

   type*            remove(yourTester t, const void* d);
Removes and returns the first item from the collection for which the
user-provided function pointed to by t finds a match with d, or
returns nil if no item is found.

   type*            removeReference(const type* e);
Removes and returns the first item from the collection with the

Rogue Wave      Tools.h++ Class Library                  174








                      CLASS REFERENCE

address e, or returns nil if no item is found.












































Rogue Wave      Tools.h++ Class Library                  175








                      CLASS REFERENCE



class GDlistIterator(type)                    GDlistIterator(type)
                                                       |
                                                RWDlistIterator
                                                       |
                                                RWSlistIterator

Synopsis  #include <gdlist.h>
          declare(GDlist, type)

          GDlist(type) a;
          GDlistIterator(type) I(a);



Descripti Iterator for class GDlist(type), which allows sequential access to
on        all the elements of a doubly-linked list.  Elements are accessed
          in order, in either direction.
          In order to simplify the documentation below, an imaginary
          typedef
            typedef void (*yourTester)(const type*, const void*);

          has been used.  See the documentation for class GDlist(type)
          for an explanation of this function.

Example   See class GDlist(type)



Public    GDlistIterator(type)( GDlist(type)& list);
construct Construct an iterator for the GDlist(type) list.  Immediately
or        after construction, the iterator is positioned at the last link.


Public    type*               operator()();
member    Advances the iterator to the next item and returns it.  Returns
operators nil if at the end of the collection.

   void             operator++();
Advances the iterator one item.  This operator wraps around to the
start of the list.



Rogue Wave      Tools.h++ Class Library                  176








                      CLASS REFERENCE

   void             operator--();
Moves the iterator back one item.  This operator wraps around to the
end of the list.

   void             operator+=(int n);
Advances the iterator n items.  This operator wraps around to the
start of the list.

   void             operator-=(int n);
Moves the iterator back n items.  This operator wraps around to the
end of the list.


Public    RWBoolean           atFirst() const;
member    Returns TRUE if the iterator is at the start of the list,
functions FALSE otherwise;

          RWBoolean           atLast() const;
          Returns TRUE if the iterator is at the end of the list, FALSE
          otherwise;

   type*            findNext(yourTester t,const type* d);
Moves the iterator to the next item for which the function pointed
to by t finds a match with d and returns it.  Returns nil if no
match is found, in which case the position of the iterator will be
undefined.

   type*            findNextReference(const type* e);
Moves the iterator to the next item with the address e and returns
it.  Returns nil if no match is found, in which case the position of
the iterator will be undefined.

   type*            insertAfterPoint(type* a);
Adds item a after the current iterator position and return the item.
The position of the iterator is left unchanged.

   type*            key() const;
Returns the item at the current iterator position.

   type*            remove();
Removes and returns the item at the current cursor position.
Iterator will be positioned at the next item in list.



Rogue Wave      Tools.h++ Class Library                  177








                      CLASS REFERENCE

   type*            removeNext(yourTester t, const type* d);
Moves the iterator to the next item for which the function pointed
to by t finds a "match" with d and removes and returns it.  Returns
nil if no match is found, in which case the position of the iterator
will be undefined.

   type*            removeNextReference(const type* a);
Moves the iterator to the next item with the address e and removes
and returns it.  Returns nil if no match is found, in which case the
position of the iterator will be undefined.

   void             toFirst();
Moves the iterator to the start of the list.

   void             toLast();
Moves the iterator to the end of the list.





























Rogue Wave      Tools.h++ Class Library                  178








                      CLASS REFERENCE



class GQueue(type)                                  GQueue(type)
                                                          |
                                                       RWSlist



Synopsis  #include <gqueue.h>
          declare(GQueue, type)

          GQueue(type) a;



Descripti Class GQueue(type) represents a group of ordered elements, not
on        accessible by an external key.  A GQueue(type) is a first in,
          first out (FIFO) sequential list for which insertions are made at
          one end (the "tail"), but all removals are made at the other (the
          "head").  Hence, the ordering is determined externally by the
          ordering of the insertions.  Duplicates are allowed. This class is
          implemented as a singly-linked list.  Objects of type GQueue(type)
          are declared with macros defined in the standard C++ header file
          <generic.h>.
          Objects stored and retrieved with class GQueue(type) do not
          need to inherit class RWCollectable.  However, in order to
          find a particular item within the collection, a user-provided
          global "tester" function is required to test for a "match",
          definable in any consistent way.  This function should have
          prototype:
            RWBoolean yourTesterFunction(const type* c, const void* d);

          The argument c is a candidate within the collection to be
          tested for a match.  The argument d is for your convenience
          and will be passed to yourTesterFunction().  The function
          should return TRUE if a "match" is found between c and d.
          In order to simplify the documentation below, an imaginary
          typedef
            typedef void (*yourTester)(const type*, const void*);

          has been used for this tester function.




Rogue Wave      Tools.h++ Class Library                  179








                      CLASS REFERENCE

Public    GQueue(type)();
construct Construct an empty queue.
ors

   GQueue(type)(type* a);
Construct a queue with one entry a.

   GQueue(type)(const GQueue(type)& q);
Copy constructor.  A shallow copy of q is made.


Assignmentvoid                operator=(const GQueue(type)& q);
operator  Assignment operator.  A shallow copy of q is
          made.


Public    type*               append(type* a);
member    Adds a to the end of the queue and returns it.
functions Returns nil if the insertion was unsuccessful.

          void                clear();
          Removes all items from the queue.

   RWBoolean        contains(yourTester t, const void* d) const;
Returns TRUE if the queue contains an item for which the user-
defined function pointed to by t finds a match with d.

   RWBoolean        containsReference(const type* e) const;
Returns TRUE if the queue contains an item with the address e.

   int              entries() const;
Returns the number of items in the queue.

   type*            first() const;
Returns the first item in the queue, or nil if the queue is empty.

   type*            get();
Returns and removes the first item in the queue.  Returns nil if the
queue is empty.

   RWBoolean        isEmpty() const;
Returns TRUE if the queue is empty, otherwise FALSE.



Rogue Wave      Tools.h++ Class Library                  180








                      CLASS REFERENCE

   type*            insert(type* a);
Calls append(type*) with a as the argument.

   type*            last();
Returns the last (most recently inserted) item in the queue, or nil
if the queue is empty.

   unsigned    occurrencesOf(yourTester t, const void* d) const;
Returns the number of items in the queue for which the user-provided
function pointed to by t finds a match with d.

   unsigned   occurrencesOfReference(const type* e) const;
Returns the number of items in the queue with the address e.
































Rogue Wave      Tools.h++ Class Library                  181








                      CLASS REFERENCE



class GSlist(type)                          GSlist(type)
                                                  |
                                               RWSlist



Synopsis  #include <gslist.h>
          declare(GSlist, type)

          GSlist(type) a;



Descripti Class GSlist(type) represents a group of ordered elements of
on        type type, not accessible by an external key.  Duplicates are
          allowed.  This class is implemented as a singly-linked list.
          Objects of type GSlist(type) are declared with macros defined in
          the standard C++ header file <generic.h>.
          Objects stored and retrieved with class GSlist(type) do not
          need to inherit class RWCollectable.  However, in order to
          find a particular item within the collection, a user-provided
          global "tester" function is required to test for a "match",
          definable in any consistent way.  This function should have
          prototype:
            RWBoolean yourTesterFunction(const type* c, const void* d);

          The argument c is a candidate within the collection to be
          tested for a match.  The argument d is for your convenience
          and will be passed to yourTesterFunction().  The function
          should return TRUE if a "match" is found between c and d.
          In order to simplify the documentation below, an imaginary
          typedef
            typedef void (*yourTester)(const type*, const void*);

          has been used for this tester function.

Public    GSlist(type)();
construct Construct an empty collection.
ors

   GSlist(type)(type* a);
Construct a collection with one entry a.

Rogue Wave      Tools.h++ Class Library                  182








                      CLASS REFERENCE

   GSlist(type)(const GSlist(type)& a);
Copy constructor.  A shallow copy of a is made.


Assignment void                operator=(const GSlist(type)&);
operator   Assignment operator.  A shallow copy of a is made.


Public    type*               append(type* a);
member    Adds an item to the end of the collection and
functions returns it.  Returns nil if the insertion was
          unsuccessful.

   void             apply( (*ap)(type*, void*), void* );
Visits all the items in the collection in order, from first to last,
calling the user-provided function pointed to by ap for each item.
This function should have prototype:

                    void yourApplyFunction(type* c, void*);

and can perform any operation on the object at address c.  The last
argument is useful for passing data to the apply function.

   type*&           at(int i);
Allows access to the i'th element of the collection.  If i is out of
range then an exception with error TOOL_INDEX will occur.  This
variant can be used as an lvalue.

   const type*      at(int i) const;
Allows access to the i'th element of the collection.  If i is out of
range then nil is returned.

   void             clear();
Removes all items in the collection.

   RWBoolean        contains(yourTester t, const void* d) const;
Returns TRUE if the collection contains an item for which the user-
defined function pointed to by t finds a match with d.

   RWBoolean        containsReference(const type* e) const;
Returns TRUE if the collection contains an item with the address e.

   unsigned         entries() const;
Returns the number of items in the collection.

Rogue Wave      Tools.h++ Class Library                  183








                      CLASS REFERENCE

   type*            find(yourTester t, const void* d) const;
Returns the first item in the collection for which the user-provided
function pointed to by t finds a match with d, or nil if no item is
found.

   type*            findReference(const type* e) const;
Returns the first item in the collection with the address e, or nil
if no item is found.

   type*            first() const;
Returns the first item of the collection.

   type*            get();
Returns and removes the first item of the collection.

   type*            insert(type* e);
Adds an item to the end of the collection and returns it.  Returns
nil if the insertion was unsuccessful.

   type*            insertAfter(int i, type* e);
Adds an item after the i'th item of the collection and returns it.
Returns nil if the insertion was unsuccessful.

   RWBoolean        isEmpty() const;
Returns TRUE if the collection is empty, otherwise FALSE.

   type*            last() const;
Returns the last item of the collection.

   unsigned    occurrencesOf(yourTester t, const void* d) const;
Returns the number of occurrences in the collection for which the
user-provided function pointed to by t finds a match with d.

   unsigned    occurrencesOfReference(const type* e) const;
Returns the number of items in the collection with the address e.

   type*            prepend(const type* a);
Adds an item to the beginning of the collection and returns it.
Returns nil if the insertion was unsuccessful.

   type*            remove(yourTester t, const void* d);
Removes and returns the first item from the collection for which the
user-provided function pointed to by t finds a match with d, or
returns nil if no item is found.

Rogue Wave      Tools.h++ Class Library                  184








                      CLASS REFERENCE

   type*            removeReference(const type* e);
Removes and returns the first item from the collection with the
address e, or returns nil if no item is found.










































Rogue Wave      Tools.h++ Class Library                  185








                      CLASS REFERENCE



class GSlistIterator(type)                   GSlistIterator(type)
                                                       |
                                                RWSlistIterator



Synopsis  #include <gslist.h>
          declare(GSlist, type)

          GSlist(type) a;
          GSlistIterator(type) I(a);



Descripti Iterator for class GSlist(type), which allows sequential
on        access to all the elements of a singly-linked list.
          Elements are accessed in order, in either direction.
          In order to simplify the documentation below, an imaginary
          typedef
            typedef void (*yourTester)(const type*, const void*);

          has been used.  See the documentation for class GSlist(type)
          for an explanation of this function.

Public    GSlistIterator(type)( GSlist(type)& list);
construct Construct an iterator for the GSlist(type) list.  Immediately
or        after construction, the iterator is positioned at the last
          link.


Public    type*               operator()();
member    Advances the iterator to the next item and returns it.
operators Returns nil if at the end of the collection.

   void             operator++();
Advances the iterator one item.  This operator wraps around to the
start of the list.

   void             operator+=(int n);
Advances the iterator n items.  This operator wraps around to the
start of the list.


Rogue Wave      Tools.h++ Class Library                  186








                      CLASS REFERENCE


Public    RWBoolean           atFirst() const;
member    Returns TRUE if the iterator is at the start of the list,
functions FALSE otherwise;

   RWBoolean        atLast() const;
Returns TRUE if the iterator is at the end of the list, FALSE
otherwise;

   type*            findNext(yourTester t,const type* d);
Moves the iterator to the next item for which the function pointed
to by t finds a match with d and returns it.  Returns nil if no
match is found, in which case the position of the iterator will be
undefined.

   type*            findNextReference(const type* e);
Moves the iterator to the next item with the address e and returns
it.  Returns nil if no match is found, in which case the position of
the iterator will be undefined.

   type*            insertAfterPoint(type* a);
Adds item a after the current iterator position and return the item.
The position of the iterator is left unchanged.

   type*            key() const;
Returns the item at the current iterator position.

   type*            remove();
Removes and returns the item at the current cursor position.
Iterator will be positioned at the next item in list.  In a singly-
linked list, this is an inefficient operation because the entire
list must be traversed, looking for the link before the link to be
removed.

   type*            removeNext(yourTester t, const type* d);
Moves the iterator to the next item for which the function pointed
to by t finds a "match" with d and removes and returns it.  Returns
nil if no match is found, in which case the position of the iterator
will be undefined.

   type*            removeNextReference(const type* e);
Moves the iterator to the next item with the address e and removes
and returns it.  Returns nil if no match is found, in which case the
position of the iterator will be undefined.

Rogue Wave      Tools.h++ Class Library                  187








                      CLASS REFERENCE

   void             toFirst();
Moves the iterator to the start of the list.

   void             toLast();
Moves the iterator to the end of the list.








































Rogue Wave      Tools.h++ Class Library                  188








                      CLASS REFERENCE



class GSortedVector(val)                     GSortedVector(val)
                                                     |
                                                GVector(val)



Synopsis  #include <gsortvec.h>
          declare(GSortedVector,val)
          implement(GSortedVector, val)

          GSortedVector(val) v;      // A sorted vector of val's.



Descripti Class GSortedVector(val) represents a vector of elements of
on        type val, sorted using an insertion sort.  The elements can
          be retrieved using an index or a search.  Duplicates are
          allowed. Objects of type GSortedVector(val) are declared
          with macros defined in the standard C++ header file
          <generic.h>.  Note that class GSortedVector(val) differs
          from most of the other generic collection classes in that
          vectors of the type are constructed, rather than pointers
          to the type.
          For each type of GSortedVector, you must include one (and only
          one) call to the macro implement somewhere in your code.
          Note that because GSortedVector(val) uses GVector(val) as a
          base class, declaring a sorted vector of type val will also
          declare a GVector of type val (see the description for
          GVector(val)).  Implementing a sorted vector of type val will
          also implement its GVector counterpart.
          Insertions and retrievals are done using a binary search.
          Note that the constructor of a GSortedVector(val) requires a
          pointer to a "comparison function".  This function should have
          prototype:
            int comparisonFunction(const val* a, const val* b);

          and should return an int less than, greater than, or equal to
          zero, depending on whether the item pointed to by a is less
          than, greater than, or equal to the item pointed to by b.




Rogue Wave      Tools.h++ Class Library                  189








                      CLASS REFERENCE


Example   Here's an example of a sorted vector of ints:

            #include <gsortvec.h>

            #include <rstream.h>

            // Declare and implement a sorted vector of ints.
            // Note that as a side effect, this will also declare
            // and implement a GVector(int)

            declare(GSortedVector,int)
            implement(GSortedVector,int)

            // Declare and define the "comparison function":

            int compFun(const int* a, const int* b)
            {

              return *a - *b;

            }

            main()

            {
              // Declare and define an instance,
              // using the comparison function 'compFun':

              GSortedVector(int) avec(compFun);

              // Do some insertions:
              avec.insert(3);           // 3
              avec.insert(17);          // 3 17
              avec.insert(5);           // 3  5 17

              cout << avec(1);          // Prints '5'
              cout << avec.index(17);   // Prints '2'
            }






Rogue Wave      Tools.h++ Class Library                  190








                      CLASS REFERENCE

Public    GSortedVector(val)( int (*f)(const val*, const val*) );
construct Construct a sorted vector of elements of type val, using the
ors       comparison function pointed to by f.  The initial capacity of
          the vector will be set by the value RWDEFAULT_CAPACITY.  The
          capacity will automatically be increased should too many items
          be inserted.

   GSortedVector(val)(int (*f)(const val*, const val*), unsigned N);
Construct a sorted vector of elements of type val, using the
comparison function pointed to by f.  The initial capacity of the
vector will be N.  The capacity will automatically be increased
should too many items be inserted.


Public    val                 operator()(int i) const;
member    Return the i'th value in the vector.  The index i must be
functions between 0 and the length of the vector less one.  No bounds
          checking is performed.

   val              operator[](int i) const;
Return the i'th value in the vector.  The index i must be between 0
and the length of the vector less one.  Bounds checking is
performed.

   int              index(val v);
Return the index of the item with value v.  The value "-1" is
returned if the value does not occur in the vector.  A binary
search, using the comparison function, is done to find the value.
If duplicates are present, the index of the first instance is
returned.

   RWBoolean        insert(val v);
Insert the new value v into the vector.  A binary search, using the
comparison function, is performed to determine where to insert the
value.  The item will be inserted after any duplicates.  If the
insertion causes the vector to exceed its capacity, it will
automatically be resized by an amount given by RWDEFAULT_RESIZE.

   unsigned         length() const;
Returns the number of items in the vector (this should not be
confused with the vector's capacity).

   void             resize(unsigned newCapacity);
Resizes the vector to have a new capacity newCapacity or the present

Rogue Wave      Tools.h++ Class Library                  191








                      CLASS REFERENCE

length of the vector, whichever is greater.  I.e., the capacity of a
vector cannot be reduced to less than its length.











































Rogue Wave      Tools.h++ Class Library                  192








                      CLASS REFERENCE



class GStack(type)                              GStack(type)
                                                     |
                                                  RWSlist



Synopsis  #include <gstack.h>
          declare(GStack,type)

          GStack(type) a;



Descripti Class GStack(type) represents a group of ordered elements,
on        not accessible by an external key.  A GStack(type) is a
          last in, first out (LIFO) sequential list for which
          insertions and removals are made at the beginning of the
          list.  Hence, the ordering is determined externally by the
          ordering of the insertions.  Duplicates are allowed. This
          class is implemented as a singly-linked list.  Objects of
          type GStack(type) are declared with macros defined in the
          standard C++ header file <generic.h>.
          Objects stored and retrieved with class GStack(type) do not
          need to inherit class RWCollectable.  However, in order to
          find a particular item within the collection, a user-provided
          global "tester" function is required to test for a "match",
          definable in any consistent way.  This function should have
          prototype:
            RWBoolean yourTesterFunction(const type* c, const void* d);

          The argument c is a candidate within the collection to be
          tested for a match.  The argument d is for your convenience
          and will be passed to yourTesterFunction().  The function
          should return TRUE if a "match" is found between c and d.
          In order to simplify the documentation below, an imaginary
          typedef
            typedef void (*yourTester)(const type*, const void*);

          has been used for this tester function.




Rogue Wave      Tools.h++ Class Library                  193








                      CLASS REFERENCE

Public    GStack(type)();
construct Construct an empty stack.
ors

   GStack(type)(type* a);
Construct a stack with one entry a.

   GStack(type)(const GStack(type)& a);
Copy constructor.  A shallow copy of a is made.


Assignmen void                operator=(const GStack(type)& a);
t         Assignment operator.  A shallow copy of a is made.
operator


Public    void                clear();
member    Removes all items from the stack.
functions
          RWBoolean           contains(yourTester t, const void* d) const;
          Returns TRUE if the stack contains an item for which the
          user-defined function pointed to by t finds a match with d.

   RWBoolean        containsReference(const type* e) const;
Returns TRUE if the stack contains an item with the address e.

   int              entries() const;
Returns the number of items in the stack.

   RWBoolean        isEmpty() const;
Returns TRUE if the stack is empty, otherwise FALSE.

   unsigned   occurrencesOf(yourTester t, const void* d) const;
Returns the number of items in the stack for which the user-provided
function pointed to by t finds a match with d.

   unsigned   occurrencesOfReference(const type* e) const;
Returns the number of items in the stack with the address e.

   type*            pop();
Removes and returns the item at the top of the stack, or returns nil
if the stack is empty.



Rogue Wave      Tools.h++ Class Library                  194








                      CLASS REFERENCE

   void             push(type* a);
Adds an item to the top of the stack.

   type*            top() const;
Returns the item at the top of the stack or nil if the stack is
empty.







































Rogue Wave      Tools.h++ Class Library                  195








                      CLASS REFERENCE



class GVector(val)





Synopsis  #include <gvector.h>
          declare(GVector,val)
          implement(GVector,val)

          GVector(val) a;     // A Vector of val's.



Descripti Class GVector(val) represents a group of ordered elements,
on        accessible by an index.  Duplicates are allowed. This class
          is implemented as an array.  Objects of type GVector(val)
          are declared with macros defined in the standard C++ header
          file <generic.h>.  Note that class GVector(val) differs from
          most of the other generic collection classes in that vectors
          of any type are constructed, rather than pointers to the
          type.
          For each type of GVector, you must include one (and only one)
          call to the macro implement, somewhere in your code.

Public    GVector(val)();
construct Construct an empty vector.
ors

   GVector(val)(unsigned n);
Construct a vector with length n. Contents are undefined.

   GVector(val)(unsigned n, val v);
Construct a vector with length n. Each element is assigned the value
v.  This will require that either val is a built in type (double,
int, etc.) or that an assignment operation be legal for it.

   GVector(val)(GVector(val)& s);
Copy constructor.  The entire vector is copied.  This results in a
deep copy.



Rogue Wave      Tools.h++ Class Library                  196








                      CLASS REFERENCE


Public    void                operator=(GVector(val)& s);
member    Assignment operator.  The entire vector is copied.  This
operators results in a deep copy.

          val&                operator()(int i);
          Returns a reference to the the i'th element of self.

   val&             operator[](int i);
Returns a reference to the the i'th element of self, with bounds
checking.


Public    unsigned            length() const;
member    Returns the length of the vector.
functions
          void                resize(unsigned n);
          Resize the vector.  If the vector shrinks, it will be
          truncated.  If the vector grows, then the value of the
          additional elements will be undefined.

























Rogue Wave      Tools.h++ Class Library                  197








                      CLASS REFERENCE



class RWBag                                     RWBag
                                                  |
                                            RWCollection
                                                  |
                                            RWCollectable

Synopsis  typedef RWBag Bag;  // Smalltalk typedef.

          #include <rwbag.h>
          RWBag h;



Descripti Class RWBag is the simplest kind of collection and corresponds to
on        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 separate identities are not stored.  Instead,
          a pointer to the first item is stored and then all subsequent
          insertions of isEqual objects merely cause the count to be
          incremented.
          Member function apply() and the iterator are called repeatedly
          according to the count for an item.

Public    RWBag(unsigned n = 101);
construct Construct an empty bag with an internal dictionary with
ors       a size that is the next highest prime number that is
          greater than or equal to n.

   RWBag(const RWBag& b);
Copy constructor.  A shallow copy of b will be made.


Rogue Wave      Tools.h++ Class Library                  198








                      CLASS REFERENCE


Public    void                operator=(const RWBag& b);
member    Assignment operator.  A shallow copy of b will be made.
operators
          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    virtual void        apply(applyCollectable ap, void*)
member    Redefined from class RWCollection.  This function has been
functions 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 of the items.

   virtual unsigned 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 unsigned 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.


Rogue Wave      Tools.h++ Class Library                  199








                      CLASS REFERENCE

   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 , unsigned 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 ClassID  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 unsigned 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);
Inherited from class RWCollection.

   void             resize(unsigned n = 0);
Resizes the internal hash table to the next highest prime number
above n, or, if n==0, to the next prime number greater than twice
the current size.






Rogue Wave      Tools.h++ Class Library                  200








                      CLASS REFERENCE

   virtual void     restoreGuts(RWvistream&);
   virtual void     restoreGuts(RWFile&);
   virtual void     saveGuts(RWvostream&) const;
   virtual void     saveGuts(RWFile&) const;
Inherited from class RWCollection.

   static RWCollectable*  restoreFrom(RWvistream&);
   static RWCollectable*  restoreFrom(RWFile&);
   void                   saveOn(RWvostream&) const;
   void                   saveOn(RWFile&) const;
Inherited from class RWCollectable.


































Rogue Wave      Tools.h++ Class Library                  201








                      CLASS REFERENCE



class RWBagIterator                            RWBagIterator
                                                     |
                                                 RWIterator



Synopsis  #include <rwbag.h>

          RWBag b;
          RWBagIterator it(b);



Descripti Iterator for class RWBag, which allows sequential access to
on        all the elements of RWBag.  Note that because a 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 times.

Public    RWBagIterator(const RWBag&);
construct Construct an iterator for a RWBag.  After construction,
or        the position of the iterator is undefined.


Public    virtual RWCollectable*    operator()();
member    Redefined from class RWIterator.  Advances the iterator
operator  to the next item and returns it. Returns nil when the
          end of the collection is reached.


Public    virtual RWCollectable*  findNext(const RWCollectable* target);
member    Redefined from class RWIterator.  Moves iterator to the
functions 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.



Rogue Wave      Tools.h++ Class Library                  202








                      CLASS REFERENCE

   virtual void     reset();
Redefined from class RWIterator.  Resets the iterator to its
starting state.










































Rogue Wave      Tools.h++ Class Library                  203








                      CLASS REFERENCE



class RWBinaryTree                               RWBinaryTree
                                                      |
                                                 RWCollection
                                                      |
                                                RWCollectable


Synopsis  typedef RWBinaryTree SortedCollection;   // Smalltalk typedef.

          #include <bintree.h>
          RWBinaryTree bt;



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

Public    RWBinaryTree();
construct Construct an empty sorted collection.
ors

   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().














Rogue Wave      Tools.h++ Class Library                  204








                      CLASS REFERENCE


Public    void  operator=(const RWBinaryTree& bt);
member    Sets self to a shallow copy of bt.
operators
          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 an 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 an item in bt.


Public    virtual void   apply(applyCollectable ap, void*)
member    Redefined from class RWCollection to apply the user-supplied
functions 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 balances 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 1 node.  Since
this collection allows duplicate elements, a perfectly balanced tree
is not always possible.

   virtual unsigned 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.



Rogue Wave      Tools.h++ Class Library                  205








                      CLASS REFERENCE

   virtual RWBoolean      contains(const RWCollectable* target) const;
Inherited from class RWCollection.

   virtual unsigned 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.

   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().

   virtual ClassID  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 unsigned 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&);
Redefined from class RWCollection to balance the binary tree after

Rogue Wave      Tools.h++ Class Library                  206








                      CLASS REFERENCE

reading the elements.

   virtual void     saveGuts(RWvostream&) const;
   virtual void     saveGuts(RWFile&) const;
Inherited from class RWCollection.

   static        RWCollectable*    restoreFrom(RWvistream&);
   static        RWCollectable*    restoreFrom(RWFile&);
   void             saveOn(RWvostream&) const;
   void             saveOn(RWFile&) const;
Inherited from class RWCollectable.


































Rogue Wave      Tools.h++ Class Library                  207








                      CLASS REFERENCE



class RWBinaryTreeIterator              RWBinaryTreeIterato
                                                  r
                                                  |
                                             RWIterator


Synopsis  // Smalltalk typedef:
          typedef RWBinaryTreeIterator SortedCollectionIterator;

          #include <bintree.h>
          RWBinaryTree bt;
          RWBinaryTreeIterator iterate(bt);



Descripti Iterator for class RWBinaryTree.  Traverses the tree from the
on        "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().

Public    RWBinaryTreeIterator(const RWBinaryTree&);
construct Constructs an iterator for a RWBinaryTree.  Immediately
or        after construction, the position of the iterator is
          undefined until positioned.


Public    virtual                RWCollectable*      operator()();
member    Redefined from class RWIterator.  Advances iterator to the
operator  next "largest" element and returns a pointer to it.  Returns
          nil when the end of the collection is reached.


Public    virtual RWCollectable*    findNext(const RWCollectable* target);
member    Redefined from class RWIterator.  Moves iterator to the next
functions 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.

Rogue Wave      Tools.h++ Class Library                  208








                      CLASS REFERENCE

   virtual         RWCollectable*   key() const;
Redefined from class RWIterator.  Returns the item at the current
iterator position.










































Rogue Wave      Tools.h++ Class Library                  209








                      CLASS REFERENCE



class RWbistream                                    RWbistream
                                                         |
                                                    RWvistream
                                                         |
                                                        ios

                                           (V2.X style iostreams, only)

Synopsis  #include <bstream.h>

          RWbistream bstr(cin);      // Construct a RWbistream, using cin's
          streambuf



Descripti Class RWbistream specializes the abstract base class RWvistream
on        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).
          The restore is independent of whether the compiler is using
          AT&T V1.2 style "streams", or the newer V2.X style "iostreams"
          -- the user need not be concerned with which style is actually
          being used.  See class RWvistream for details.
          RWbistream can be interrogated as to the stream state using
          member functions good(), bad(), eof(), etc.














Rogue Wave      Tools.h++ Class Library                  210








                      CLASS REFERENCE

Example  This example assumes that V2.X style "iostreams" are being used. See
         RWbostream for an example of how the file "data.dat" might be created.
          #include <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
          }



Public    RWbistream(streambuf* s);
onstructo Construct a RWbistream from the streambuf s.
rs

   RWbistream(istream& str);
Construct a RWbistream using the streambuf associated with the
istream str.


Public    virtual int         get();
member    Redefined from class RWvistream.  Get and return the next
functions character 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(unsigned char& c);
Redefined from class RWvistream.  Get the next unsigned char and
store it in c.

   virtual RWvistream&    get(char* v, unsigned N);
Redefined from class RWvistream.  Get a vector of char's and store

Rogue Wave      Tools.h++ Class Library                  211








                      CLASS REFERENCE

then in the array beginning at v.  If the restore is stopped
prematurely, get stores whatever it can in v, and sets the failbit.
Note that the vector is treated as a vector of numbers, not
characters.  If you wish to restore a character string, use function
getString(char*, int).

   virtual RWvistream&    get(double* v, unsigned N);
Redefined from class RWvistream.  Get a vector of double's and store
then in the array beginning at v.  If the restore is stopped
prematurely, get stores whatever it can in v, and sets the failbit.

   virtual RWvistream&    get(float* v, unsigned N);
Redefined from class RWvistream.  Get a vector of float's and store
then in the array beginning at v.  If the restore is stopped
prematurely, get stores whatever it can in v, and sets the failbit.

   virtual RWvistream&    get(int* v, unsigned N);
Redefined from class RWvistream.  Get a vector of int's and store
then in the array beginning at v.  If the restore is stopped
prematurely, get stores whatever it can in v, and sets the failbit.

   virtual RWvistream&    get(long* v, unsigned N);
Redefined from class RWvistream.  Get a vector of long's and store
then in the array beginning at v.  If the restore is stopped
prematurely, get stores whatever it can in v, and sets the failbit.

   virtual RWvistream&    get(short* v, unsigned N);
Redefined from class RWvistream.  Get a vector of short's and store
then in the array beginning at v.  If the restore is stopped
prematurely, get stores whatever it can in v, and sets the failbit.

   virtual RWvistream&    get(unsigned char* v, unsigned N);
Redefined from class RWvistream.  Get a vector of unsigned char's
and store then in the array beginning at v.  If the restore is
stopped prematurely, get stores whatever it can in v, and sets the
failbit.  Note that the vector is treated as a vector of numbers,
not characters.  If you wish to restore a character string, use
function getString(char*, int).

   virtual RWvistream&    get(unsigned short* v, unsigned N);
Redefined from class RWvistream.  Get a vector of unsigned short's
and store then in the array beginning at v.  If the restore is
stopped prematurely, get stores whatever it can in v, and sets the
failbit.

Rogue Wave      Tools.h++ Class Library                  212








                      CLASS REFERENCE

   virtual RWvistream&    get(unsigned int* v, unsigned N);
Redefined from class RWvistream.  Get a vector of unsigned int's and
store then in the array beginning at v.  If the restore is stopped
prematurely, get stores whatever it can in v, and sets the failbit.

   virtual RWvistream&    get(unsigned long* v, unsigned N);
Redefined from class RWvistream.  Get a vector of unsigned long's
and store then in the array beginning at v.  If the restore is
stopped prematurely, get stores whatever it can in v, and sets the
failbit.

   virtual RWvistream&    getString(char* s, unsigned 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 the latter, then the failbit
of the stream will be set.  In either case, the string will be
terminated with a null byte.

   virtual RWvistream&    operator>>(char& c);
Redefined from class RWvistream.  Get the next character from the
input stream and store it in c.

   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.



Rogue Wave      Tools.h++ Class Library                  213








                      CLASS REFERENCE

   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.






























Rogue Wave      Tools.h++ Class Library                  214








                      CLASS REFERENCE



class RWBitVec





Synopsis  #include <bitvec.h>

          RWBitVec v;



Descripti Class RWBitVec is a bitvector whose length can be changed
on        dynamically at run time.  Because this requires an extra level
          of indirection, this makes it slightly less efficient than
          class GBitVec(size), whose length is fixed at compile time.

Example   #include <bitvec.h>
          #include <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 << NL;        // Print the vector out
          }

          Program output:






Rogue Wave      Tools.h++ Class Library                  215








                      CLASS REFERENCE

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




Public    RWBitVec();
constructoConstruct a zero lengthed (null) vector.
rs

   RWBitVec(unsigned N);
Construct a vector with N bits.  The initial value of the bits is
undefined.

   RWBitVec(unsigned N, RWBoolean initVal);
Construct a vector with N bits, each set to the Boolean value
initVal.

   RWBitVec(const RWByte* bp, unsigned 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 RWBitVec&           operator=(const RWBitVec& v);
operators  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,

Rogue Wave      Tools.h++ Class Library                  216








                      CLASS REFERENCE

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 will occur with error number TOOL_NEVECL.


Indexing  RWBitRef            operator[](int i);
operators 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 will occur with error value
          TOOL_INDEX.

   RWBitRef         operator()(int 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 BOUNDS_CHECK has been
defined before including the header file bitvec.h.  If so, and if
the index is out of range, then an exception will occur with error
value TOOL_INDEX.

   RWBoolean        operator[](int 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 will occur with error value TOOL_INDEX.

   RWBoolean        operator()(int 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 BOUNDS_CHECK has been defined before including the header file
bitvec.h.  If so, and if the index is out of range, then an
exception will occur with error value TOOL_INDEX.


Logical   RWBoolean           operator==(const RWBitVec& u) const;
operators 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

Rogue Wave      Tools.h++ Class Library                  217








                      CLASS REFERENCE

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    void                clearBit(int i);
member    Clears (i.e., sets to FALSE) the bit with index i.  The index
functions i must be between 0 and the length of the vector less one.
          No bounds checking is performed.  The following are
          equivalent, although clearBit(int) is slightly smaller and
          faster than using operator()(int):
                 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.

   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.

   unsigned         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(unsigned 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.


Rogue Wave      Tools.h++ Class Library                  218








                      CLASS REFERENCE

   void             restoreFrom(RWvistream& s);
Restores a vector that was stored using member function
storeOn(RWvostream&).

   void             restoreFrom(RWFile& f);
Restores a vector stored on a RWFile using member function
storeOn(RWFile&).

   void             saveOn(RWVostream& s) const;
Stores self to a virtual output stream.

   void             saveOn(RWFile& f) const;
Stores self to an RWFile.

   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(int i);           // Set bit 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(int) is slightly smaller
and faster than using operator()(int):
                 a(i) = TRUE;
                 a.setBit(i);

   RWBoolean        testBit(int 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(int) is slightly smaller and faster than using
operator()(int):
                 if( a(i) )       doSomething();
                 if( testBit(i) ) doSomething();











Rogue Wave      Tools.h++ Class Library                  219








                      CLASS REFERENCE

Related   RWBitVec            operator!(const RWBitVec& v);
global    Unary operator that returns the logical negation of vector
functions 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 will occur with error number TOOL_NEVECL.

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

   istream&         operator>>(istream& s, RWBitVec& v);
Calls v.scanFrom(s).

   int              sum(const RWBitVec& v);
Returns the total number of bits set in the vector v.


























Rogue Wave      Tools.h++ Class Library                  220








                      CLASS REFERENCE



class RWbostream                                     RWbostream
                                                         |
                                                     RWvostream
                                                         |
                                                        ios

                                            (V2.X style iostreams, only)

Synopsis  #include <bstream.h>

          // Construct a RWbostream, using cout's streambuf:
          RWbostream bstr(cout);



Descripti Class RWbostream specializes the abstract base class RWvostream
on        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 whitespace.
          Such whitespace would be interpreted literally and would have
          to be read back in as a character string.
          Storage is independent of whether the compiler is using AT&T
          V1.2 style "streams", or the newer V2.X style "iostreams" --
          the user need not be concerned with which style is actually
          being used.  See class RWvostream for details.
          RWbostream can be interrogated as to the stream state using
          member functions good(), bad(), eof(), etc.











Rogue Wave      Tools.h++ Class Library                  221








                      CLASS REFERENCE

Example   This example assumes that V2.X style "iostreams" are being used.
          See RWbistream for an example of how the file "data.dat" might be
          read back in.
          #include <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    RWbostream(streambuf* s);
construct Construct a RWbostream from the streambuf s.
ors

   RWbostream(ostream& str);
Construct a RWbostream from the streambuf associated with the output
stream str.


Public    virtual RWvostream& operator<<(const char* s);
member    Redefined from class RWvostream.  Store the character
functions string starting at s to the output stream in binary.  The
          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.  Note that c is treated as a character, not a
number.

   virtual RWvostream&    operator<<(unsigned char c);
Redefined from class RWvostream.  Store the unsigned char c to the
output stream in binary.  Note that c is treated as a character, not
a number.

Rogue Wave      Tools.h++ Class Library                  222








                      CLASS REFERENCE

   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.

   virtual RWvostream&    put(char c);
Redefined from class RWvostream.  Store the character c to the
output stream, preserving its value in binary.

   virtual RWvostream&    put(unsigned char c);
Redefined from class RWvostream.  Store the character c to the
output stream, preserving its value in binary.

   virtual RWvostream&    put(const char* p, unsigned N);
Redefined from class RWvostream.  Store the vector of chars starting
at p to the output stream in binary.  The characters should be
treated as literal numbers (i.e., not as a character string).

Rogue Wave      Tools.h++ Class Library                  223








                      CLASS REFERENCE

   virtual RWvostream&    put(const unsigned char* p, unsigned N);
Redefined from class RWvostream.  Store the vector of unsigned chars
starting at p to the output stream in binary.  The characters should
be treated as literal numbers (i.e., not as a character string).

   virtual RWvostream&    put(const short* p, unsigned 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, unsigned 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, unsigned 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, unsigned 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, unsigned 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, unsigned 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, unsigned 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, unsigned N);
Redefined from class RWvostream.  Store the vector of doubles
starting at p to the output stream in binary.









Rogue Wave      Tools.h++ Class Library                  224








                      CLASS REFERENCE



class RWBTree                                         RWBTree
                                                         |
                                                    RWCollection
                                                         |
                                                   RWCollectable

Synopsis  #include <btree.h>
          RWBTree a;



Descripti Class RWBTree represents a group of ordered elements, not
on        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.

Public    RWBTree();
construct Construct an empty B-Tree.
or

   RWBTree(const RWBTree& btr);
Construct self as a shallow copy of btr.

   virtual          ~RWBTree();
Redefined from RWCollection.  Calls clear().





Rogue Wave      Tools.h++ Class Library                  225








                      CLASS REFERENCE


Public    void                operator=(const RWBTree& btr);
member    Set self to a shallow copy of btr.
operators
          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.

   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    virtual void          apply(applyCollectable ap, void*)
member    Redefined from class RWCollection to apply the user-supplied
functions 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         unsigned   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         unsigned   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.

Rogue Wave      Tools.h++ Class Library                  226








                      CLASS REFERENCE

   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.  Returns nil if the insertion was
unsuccessful.  The item c is inserted according to the value
returned by compareTo().

   virtual ClassID  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 unsigned 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.

   static        RWCollectable*    restoreFrom(RWvistream&);
   static        RWCollectable*    restoreFrom(RWFile&);

Rogue Wave      Tools.h++ Class Library                  227








                      CLASS REFERENCE

   void             saveOn(RWvostream&) const;
   void             saveOn(RWFile&) const;
Inherited from class RWCollectable.










































Rogue Wave      Tools.h++ Class Library                  228








                      CLASS REFERENCE



class RWBTreeDictionary                          RWBTreeDictionary
                                                         |
                                                      RWBTree
                                                         |
                                                   RWCollection
                                                         |
                                                   RWCollectable

Synopsis  #include <btrdict.h>

          RWBTreeDictionary a;



Descripti Dictionary class implemented as a B-Tree, for the storage and
on        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.

Public    RWBTreeDictionary();
construct Constructs an empty B-Tree dictionary.
ors


Public    void    applyToKeyAndValue(applyKeyAndValue ap, void*)
member    Applies the user-supplied function pointed to by ap to each
functions key-value pair of the collection, in order, from smallest to
          largest.

   virtual unsigned binaryStoreSize() const
Inherited from class RWCollection.

   virtual void     clear();
Redefined from class RWCollection.  Removes all key-value pairs from

Rogue Wave      Tools.h++ Class Library                  229








                      CLASS REFERENCE

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 unsigned entries() const;
Redefined from class RWCollection.

   virtual         RWCollectable*   find(const RWCollectable* key) 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,

Rogue Wave      Tools.h++ Class Library                  230








                      CLASS REFERENCE

                    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 ClassID  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 unsigned 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.

   static        RWCollectable*    restoreFrom(RWvistream&);
   static        RWCollectable*    restoreFrom(RWFile&);

Rogue Wave      Tools.h++ Class Library                  231








                      CLASS REFERENCE

   void             saveOn(RWvostream&) const;
   void             saveOn(RWFile&) const;
Inherited from class RWCollectable.










































Rogue Wave      Tools.h++ Class Library                  232








                      CLASS REFERENCE



class RWBTreeOnDisk





Synopsis  typedef             long   storedValue;

          #include <disktree.h>
          #include <filemgr.h>

          RWFileManager fm("filename.dat");
          RWBTreeOnDisk bt(fm);



Descripti Class RWBTreeOnDisk represents an ordered collection of associations
on        of keys and values, where the ordering is determined internally by
          comparing keys lexicographically.  Values are accessible by using
          external keys (i.e., matches are determined by comparing strings).
          Duplicate keys are not allowed.
          This class is specifically designed for managing a B-Tree on a
          disk file.  Keys, defined to be arrays of chars, and values,
          defined by the typedef storedValue, are stored and retrieved
          from a B-Tree.  The values can represent offsets to locations
          in a file where objects are stored.  Keys are defined to be a
          maximum of 16 characters long.  This may be varied by changing
          KEY_SIZE in the header file disktree.h and recompiling.
          This class is meant to be used with class RWFileManager which
          manages the allocation and deallocation of space on a disk
          file.












Rogue Wave      Tools.h++ Class Library                  233








                      CLASS REFERENCE

Public    RWBTreeOnDisk(RWFileManager& f)
construct Construct a B-Tree on disk.  The RWFileManager f must be
or        constructed first.  If the RWFileManager is constructed from an
          old file, the RWBTreeOnDisk is constructed with the old B-Tree;
          if the RWFileManager is constructed from a new file,  an empty B-
          Tree is initialized on the file.


Public    void applyToKeyAndValue((*ap)(const char*,   storedValue),
member    void* x);
functions 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
          prototype:
             void yourApplyFunction(const char* ky, storedValue val,
             void* x);

The  function yourApplyFunction cannot change the key.  The value x
can be anything and is passed through from the call to
applyToKeyAndValue(). Possible exceptions that can occur are
TOOL_READERR and TOOL_SEEKERR.

   void             clear();
Removes all items from the collection.  Possible exceptions that can
occur are TOOL_READERR, TOOL_WRITEERR and TOOL_SEEKERR.

   unsigned         entries();
Returns the number of items in the RWBTreeOnDisk.  Possible
exceptions that can occur are TOOL_READERR and TOOL_SEEKERR.

   storedValue      find(const char* ky);
Returns the value for the key that compares equal to the string
pointed to by ky.  Returns NIL if no key is found.  Possible
exceptions that can occur are TOOL_READERR and TOOL_SEEKERR.

   int              height();
Returns the height of the RWBTreeOnDisk.  Possible exceptions that
can occur are TOOL_READERR and TOOL_SEEKERR.

   int              insertKeyAndValue(const char* ky, storedValue v);
Adds a key-value pair to the B-Tree.  Returns TRUE for successful
insertion, FALSE otherwise.  Possible exceptions that can occur are
TOOL_READERR, TOOL_WRITEERR and TOOL_SEEKERR.


Rogue Wave      Tools.h++ Class Library                  234








                      CLASS REFERENCE

   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.
Possible exceptions that can occur are TOOL_READERR, TOOL_WRITEERR
and TOOL_SEEKERR.






































Rogue Wave      Tools.h++ Class Library                  235








                      CLASS REFERENCE



class RWCacheManager





Synopsis  #include <cacheman.h>

          RWFile f("file.dat");       // Construct a file
          RWCacheManager(&f, 100);    // Cache 100 byte blocks to file.dat



Descripti Class RWCacheManager caches fixed length blocks to and from an
on        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 cache may be deferred.  Use member function
          flush() to have any pending writes performed.
























Rogue Wave      Tools.h++ Class Library                  236








                      CLASS REFERENCE

Example   #include <cacheman.h>

          #include <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    RWCacheManager(RWFile* file, unsigned blocksz, unsigned mxblks = 10);
construct Construct a cache for the RWFile pointed to by file.  The length
or        of the fixed-size blocks is given by blocksz.  The number of
          cached blocks is given by mxblks.

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



Rogue Wave      Tools.h++ Class Library                  237








                      CLASS REFERENCE


Public    RWBoolean           flush();
member    Perform any pending I/O operations.  Returns TRUE if the flush
functions 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.























Rogue Wave      Tools.h++ Class Library                  238








                      CLASS REFERENCE



class RWCLIPstreambuf                            RWCLIPstreambuf
                                                        |
                                                    streambuf



Synopsis  #include <winstrea.h>
          #include <iostream.h>

          iostream str( new RWCLIPstreambuf() );



Descripti Class RWCLIPstreambuf is a specialized streambuf that gets and puts
on        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 on an as-
          needed basis.  If too many characters are inserted into the
          internal buffer for its present size, then it will be resized
          and old characters copied over into any new memory as
          necessary.  This is transparent to the user.  It is expected
          that this mode would be used primarily 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.



Rogue Wave      Tools.h++ Class Library                  239








                      CLASS REFERENCE

Example   #include <winstrea.h>
          #include <iostream.h>
          #include <windows.h>

          postToClipboard(HWND owner)

          {

            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();

          }

          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

Rogue Wave      Tools.h++ Class Library                  240








                      CLASS REFERENCE

          RegisterClipboardFormat().

Public    RWCLIPstreambuf();
construct Constructs an empty RWCLIPstreambuf in dynamic mode.  The results
ors       can be used anywhere any other streambuf can be used.  Memory to
          accomodate new characters will be allocated as needed.

   RWCLIPstreambuf(HANDLE hMem)
Constructs a 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.

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


Public    Because RWCLIPstreambuf inherits from streambuf, any of the latter's
member    member functions can be used.  Furthermore, RWCLIPstreambuf has been
functions 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.















Rogue Wave      Tools.h++ Class Library                  241








                      CLASS REFERENCE



class RWCollectable





Synopsis  typedef RWCollectable Object; // Smalltalk typedef

          #include <collect.h>



Descripti Class RWCollectable is an abstract base class for collectable
on        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.

Virtual   virtual             ~RWCollectable()
functions 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 unsigned binaryStoreSize() const;
Should return the number of bytes necessary to store the object
using RWCollectable::saveOn(RWFile&).  The default definition,
provided by RWCollectable, returns zero.

   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.


Rogue Wave      Tools.h++ Class Library                  242








                      CLASS REFERENCE

Note that the meaning of "is equal to", "larger" and "smaller" is
left to the user.  The default condition 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 condition provided
by the base class is based on the addresses, i.e.,
                    return (unsigned)this;

   virtual         ClassID    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 matching condition 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.

   virtual         RWvistream&      restoreGuts(RWvistream&);
Read an object's state from an input stream.

   virtual         void       saveGuts(RWFile&) const;
Write an object's state to a binary file, using class RWFile.



Rogue Wave      Tools.h++ Class Library                  243








                      CLASS REFERENCE

   virtual void     saveGuts(RWvostream&) const;
Write an object's state to an output stream.

   static        RWCollectable*    restoreFrom(RWvistream&);
   static        RWCollectable*    restoreFrom(RWFile&);
Looks at the next object on the input stream or RWFile 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.  Note that this is a static function -- it should not be
called for any particular instance of an object.  See Section 15.9
for a complete description.  If a corrupted stream is encountered
then an exception will occur with error TOOL_STREAM.  If a corrupted
RWFile is encountered, then an exception will occur with error
TOOL_MAGIC (i.e., bad magic number).































Rogue Wave      Tools.h++ Class Library                  244








                      CLASS REFERENCE

   void             saveOn(RWvostream&) const;
   void             saveOn(RWFile&) const;
Stores an object while maintaining its morphology.  See Section 15.9
for a complete description.

   unsigned         shallowStoreSize() const;
Returns the number of bytes required to store the object using
RWCollectable::saveOn(RWFile&).  Recursively calls
binaryStoreSize(), taking duplicate objects into account.




































Rogue Wave      Tools.h++ Class Library                  245








                      CLASS REFERENCE



class RWCollectableDate                          RWCollectableDate
                                                     |         |
                                               RWCollectable  RWDate



Synopsis  typedef RWCollectableDate Date;    // Smalltalk typedef

          #include <colldate.h>

          RWCollectableDate  d;



Descripti Collectable Dates.  Inherits classes RWDate and RWCollectable.
on        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.

Public    RWCollectableDate();
construct Calls the appropriate base class constructor.  See
ors       RWDate::RWDate().

   RWCollectableDate(dayTy d, yearTy y);
Calls the appropriate base class constructor. See
RWDate::RWDate(dayTy d, yearTy y).

   RWCollectableDate(dayTy d, const char* month, yearTy y);
Calls the appropriate base class constructor.

See RWDate::RWDate(dayTy d, const char* month, yearTy y).

   RWCollectableDate(dayTy d, monthTy month, yearTy y);
Calls the appropriate base class constructor.

See RWDate::RWDate(dayTy d, monthTy month, yearTy y).

   RWCollectableDate(istream& s);
Calls the appropriate base class constructor.  See
RWDate::RWDate(istream& s).


Rogue Wave      Tools.h++ Class Library                  246








                      CLASS REFERENCE

   RWCollectableDate(const RWTime& t);
Calls the appropriate base class constructor.  See
RWDate::RWDate(const RWTime&).


Public    virtual unsigned    binaryStoreSize() const;
member    Redefined from class RWCollectable.  Returns the number of
functions bytes necessary to store the object using
          RWCollectable::saveOn(RWFile&).

   virtual int      compareTo(const RWCollectable* c) const;
Redefined from class RWCollectable.  Returns _1, 0 or 1, depending
on whether self's date is less than, equal to, or greater than the
RWCollectableDate pointed to by c.

   virtual unsigned hash() const;
Redefined from class RWCollectable.  Returns the
RWCollectableDates's value as an unsigned, to be used as a hash
value:

   virtual ClassID  isA() const;
Redefined from class RWCollectable to return __RWCOLLECTABLEDATE.

   virtual RWBoolean      isEqual(const RWCollectable* t) const;
Redefined from class RWCollectable.  Returns TRUE if self has the
same date as the RWCollectableDate at address t.

   virtual void     restoreGuts(RWvistream&);
   virtual void     restoreGuts(RWFile&);
   virtual void     saveGuts(RWvostream&) const;
   virtual void     saveGuts(RWFile&) const;
Redefined from class RWCollectable.  Generally, these functions call
the appropriate member function in RWDate.  For example,
restoreGuts(RWvistream&) calls RWDate::restoreFrom(RWvistream&).











Rogue Wave      Tools.h++ Class Library                  247








                      CLASS REFERENCE



class RWCollectableInt                          RWCollectableInt
                                             |        |
                                        RWCollectableRWInteger



Synopsis  typedef RWCollectableInt Integer;  // Smalltalk typedef

          #include <collint.h>

          RWCollectableInt  i;



Descripti Collectable integers.  Inherits classes RWInteger and RWCollectable.
on        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.

Public    RWCollectableInt();
construct Calls the appropriate base class constructor.  See
ors       RWInteger::RWInteger().

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


Public    virtual unsigned    binaryStoreSize() const;
member    Redefined from class RWCollectable.  Returns the number of bytes
functions necessary to store the object using
          RWCollectable::saveOn(RWFile&).

   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.


Rogue Wave      Tools.h++ Class Library                  248








                      CLASS REFERENCE

   virtual ClassID  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.







































Rogue Wave      Tools.h++ Class Library                  249








                      CLASS REFERENCE

   virtual void     restoreGuts(RWvistream&);
   virtual void     restoreGuts(RWFile&);
   virtual void     saveGuts(RWvostream&) const;
   virtual void     saveGuts(RWFile&) const;
Redefined from class RWCollectable.  Generally, these functions call
the appropriate member function in RWInteger.  For example,
restoreGuts(RWvistream&) calls RWInteger::restoreFrom(RWvistream&).






































Rogue Wave      Tools.h++ Class Library                  250








                      CLASS REFERENCE



class RWCollectableString                         RWCollectableString
                                                        |    |
                                                RWCollectable  RWString



Synopsis  typedef RWCollectableString String;     // Smalltalk typedef

          #include <collstr.h>

          RWCollectableString  c;



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

Public    RWCollectableString();
construct Construct a RWCollectableString with zero characters.
ors

   RWCollectableString(const RWString& s);
Construct a RWCollectableString from the RWString s.  The created
string will reference s's data.

   RWCollectableString(const char* c);
Conversion from character string.  The created string will copy the
data pointed to by c.

   RWCollectableString(const RWSubString&);
Conversion from sub-string.  The created string will copy the
substring's data.

   RWCollectableString(unsigned N, char c = ' ');
Construct a RWCollectableString with N characters (default blanks).





Rogue Wave      Tools.h++ Class Library                  251








                      CLASS REFERENCE


Public    virtual unsigned    binaryStoreSize() const;
member    Redefined from class RWCollectable.  Returns the number of bytes
functions necessary to store the object using
          RWCollectable::saveOn(RWFile&).

   virtual int      compareTo(const RWCollectable* c) const;
Redefined from class RWCollectable.  Calls RWString::compareTo()
with c as the argument and returns the results.  This compares
strings lexicographically.  Case insensitive comparisons can be made
by calling RWString::setCaseSensitive() first.

   virtual unsigned hash() const;
Redefined from class RWCollectable.  Calls RWString::hash() and
returns the results.  Case insensitive hashings can be made by
calling RWString::setCaseSensitive() first.

   virtual ClassID  isA() const;
Redefined from class RWCollectable to return __RWCOLLECTABLESTRING.

   virtual RWBoolean      isEqual(const RWCollectable* c) const;
Redefined from class RWCollectable.  Calls RWString::operator==()
(i.e., the equivalence operator) with c as the argument and returns
the results.  Case insensitive matches can be made by calling
RWString::setCaseSensitive() first.

   virtual void     restoreGuts(RWvistream&);
   virtual void     restoreGuts(RWFile&);
   virtual void     saveGuts(RWvostream&) const;
   virtual void     saveGuts(RWFile&) const;
Redefined from class RWCollectable.  Generally, these functions call
the appropriate member function in RWString.  For example,
restoreGuts(RWvistream&) calls RWString::restoreFrom(RWvistream&).












Rogue Wave      Tools.h++ Class Library                  252








                      CLASS REFERENCE



class RWCollectableTime                           RWCollectableTime
                                             |         |
                                        RW CollectableRWTime



Synopsis  typedef RWCollectableTime Time;    // Smalltalk typedef

          #include <colltime.h>

          RWCollectableTime  t;



Descripti Inherits classes RWTime and RWCollectable.  This class is useful when
on        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.

Public    RWCollectableTime();
construct Calls the appropriate base class constructor.  See
ors       RWTime::RWTime().

   RWCollectableTime(clockTy s);
Calls the appropriate base class constructor.  See
RWTime::RWTime(clockTy).

   RWCollectableTime(hourTy h, minuteTy m, secondTy s = 0);
Calls the appropriate base class constructor.
See RWTime::RWTime(hourTy, minuteTy, secondTy).

   RWCollectableTime (const RWDate&, hourTy h = 0,
                      minuteTy m = 0, secondTy s = 0);
Calls the appropriate base class constructor.
See RWTime::RWTime(const RWDate&, hourTy, minuteTy, secondTy).








Rogue Wave      Tools.h++ Class Library                  253








                      CLASS REFERENCE


Public    virtual unsigned    binaryStoreSize() const;
member    Redefined from class RWCollectable.  Returns the number of bytes
functions necessary to store the object using RWCollectable::saveOn(RWFile&).

   virtual int      compareTo(const RWCollectable* c) const;
Redefined from class RWCollectable.  Calls RWTime::compareTo() with
c as the argument and returns the results.

   virtual unsigned hash() const;
Redefined from class RWCollectable.  Calls RWTime::hash() and
returns the results.

   virtual ClassID  isA() const;
Redefined from class RWCollectable to return __RWCOLLECTABLETIME.

   virtual RWBoolean      isEqual(const RWCollectable* c) const;
Redefined from class RWCollectable.  Calls RWTime::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.  Generally, these functions call
the appropriate member function in RWTime.  For example,
restoreGuts(RWvistream&) calls RWTime::restoreFrom(RWvistream&).

















Rogue Wave      Tools.h++ Class Library                  254








                      CLASS REFERENCE



class RWCollection                                   RWCollection
                                                           |
                                                     RWCollectable



Synopsis  #include <colclass.h>

          typedef RWCollection Collection;   // Smalltalk typedef



Descripti Class RWCollection is an abstract base class for the Smalltalk_-like
on        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().














Rogue Wave      Tools.h++ Class Library                  255








                      CLASS REFERENCE

Public    void                operator+=(const RWCollection&);
member    void                operator-=(const RWCollection&);
operators Adds or removes, respectively, each item in the argument from
          self.


Public    virtual             ~RWCollection();
member    Null definition (does nothing).
functions
          virtual void        apply(applyCollectable ap, void*) = 0;
          This function applies the user-supplied function pointed to
          by ap to each member of the collection.  This function
          should have prototype
                    void yourApplyFunction(RWCollectable* c, void*);

The function yourApplyFunction() can perform any operation on the
item at address c that does not change the ordering of the
collection.  Client data may be passed to this function by using the
second argument.


























Rogue Wave      Tools.h++ Class Library                  256








                      CLASS REFERENCE

   RWBag            asBag() const;
   RWSet            asSet() const;
   RWOrdered        asOrderedCollection() const;
   RWBinaryTree     asSortedCollection() const
Allows any collection to be converted to a RWBag, RWSet, RWOrdered,
or a RWBinaryTree.

   virtual unsigned binaryStoreSize() const;
Redefined from class RWCollectable.  Returns the total number of
bytes required to store the collection to a binary file using a
false deep copy (i.e., the instance variables of the collection are
copies of the original instance variables, but this copying is not
done recursively).  For each object in the collection, this function
calls shallowStoreSize(), adding up the results.  Use
shallowStoreSize() if you want the number of bytes required to store
the collection using saveOn() -- the more usual case.

   virtual void     clear() = 0;
Removes all objects from the collection.  Does not delete the
objects themselves.

   virtual void     clearAndDestroy();
Removes all objects from the collection and deletes them.  Takes
into account duplicate objects within a collection and only deletes
them once.  However, it does not take into account objects shared
between different collections.  Either do not use this function if
you will be sharing objects between separate collections, or put all
collections that could be sharing objects into one single "super-
collection" and call clearAndDestroy() from that.

   virtual int      compareTo(const RWCollectable* a) const;
Inherited from class RWCollectable.

   virtual RWBoolean      contains(const RWCollectable* target) const;
Returns TRUE if the collection contains an item where the virtual
function find() returns non-nil.

   virtual unsigned entries() const = 0;
Returns the total number of items in the collection.

   virtual       RWCollectable*   find(const RWCollectable* target) const = 0;
Returns a pointer to the first item in the collection which
"matches" the object pointed to by target or nil if no item was
found.  For most collections, an item "matches" the target if either

Rogue Wave      Tools.h++ Class Library                  257








                      CLASS REFERENCE

isEqual() or compareTo() find equivalence, whichever is appropriate
for the actual collection type.  However, the "identity collections"
(i.e., RWIdentitySet and RWIdentityDictionary) look for an item with
the same address (i.e., "is identical to").

   virtual unsigned hash() const;
Inherited from class RWCollectable.

   virtual         RWCollectable*   insert(RWCollectable* e) = 0;
Adds an item to the collection and returns a pointer to it.  If the
item is already in the collection, some items return the old
instance, others return nil.

   virtual ClassID  isA() const;
Redefined from class RWCollectable to return __RWCOLLECTION.

   virtual RWBoolean      isEmpty() const = 0;
Returns TRUE if the collection is empty, otherwise returns FALSE.

   virtual RWBoolean      isEqual(const RWCollectable* a) const;
Inherited from class RWCollectable.

   virtual unsigned occurrencesOf(const RWCollectable* t) const = 0;
Returns the number of items in the collection which are "matches" t.
See function find() for a definition of matches.

   virtual void     restoreGuts(RWFile&);
Redefined to call RWCollectable::restoreFrom(RWFile&), followed by
insert(RWCollectable*) for each item in the collection.

   virtual void     restoreGuts(RWvistream&);
Redefined to call RWCollectable::restoreFrom(RWvistream&), followed
by insert(RWCollectable*) for each item in the collection.

   RWCollectable*   remove(const RWCollectable* target) = 0;
Removes and returns a pointer to the first item in the collection
which "matches" the object pointed to by target.  Returns nil if no
object was found.  Does not delete the object.

   virtual void     removeAndDestroy(const RWCollectable* target);
Removes and deletes the first item in the collection which "matches"
the object pointed to by target.



Rogue Wave      Tools.h++ Class Library                  258








                      CLASS REFERENCE

   RWCollection*    select(testCollectable tst, void x) const;
Evaluates the function pointed to by tst for each item in the
collection.  It inserts those items for which the function returns
TRUE into a new collection allocated off the heap of the same type
as self and returns a pointer to this new collection.  Because the
new collection is allocated off the heap, you are responsible for
deleting it when done.

   static        RWCollectable*    restoreFrom(RWvistream&);
   static        RWCollectable*    restoreFrom(RWFile&);
   void             saveOn(RWvostream&) const;
   void             saveOn(RWFile&) const;
Inherited from class RWCollectable.

   virtual void     saveGuts(RWFile&);
Redefined to call RWCollectable::saveOn(RWFile&) for each item in
the collection.

   virtual void     saveGuts(RWvostream&);
Redefined to call RWCollectable::saveOn(RWvostream&) for each item
in the collection.
























Rogue Wave      Tools.h++ Class Library                  259








                      CLASS REFERENCE



class RWDate





Synopsis  typedef unsigned           dayTy;
          typedef unsigned           monthTy;
          typedef unsigned           yearTy;
          typedef unsigned long      julTy;

          #include <rwdate.h>
          RWDate a;           // Construct today's date



Descripti Class RWDate represents a date, stored as a Julian day number.
on        The member function isValid() can be used to determine whether
          an RWDate is a valid date.  For example, isValid() would
          return FALSE for the date 29  February 1991 because 1991 is
          not a leap year.
          RWDate's can be converted to and from RWTime's.

Example   #include <rwdate.h>
          #include <rstream.h>

          main()
          {
            // Today's date
            RWDate d;

            // Last Sunday's date:
            RWDate lastSunday = d.previous("Sunday");

            cout << d << NL << lastSunday << NL;
          }

          Program output:
            March 22, 1991
            March 17, 1991



Rogue Wave      Tools.h++ Class Library                  260








                      CLASS REFERENCE

Public    RWDate();
construct Constructs an RWDate with the current date.
ors

   RWDate(dayTy d, yearTy y);
Constructs an RWDate with a given day of the year and a given year.
The member function isValid() can be used to test whether the
results are a valid date.

   RWDate(dayTy h, const char* month, yearTy y);
Constructs an RWDate with the given day of the month, month and
year.

Days should be 1-31, months may be specified as (for example):
January, JAN, or Jan, and the year may be specified as (for example)
1990, or 90.  The member function isValid() can be used to test
whether the results are a valid date.

   RWDate(dayTy h, monthTy month, yearTy y);
Constructs an RWDate with the given day of the month, month and
year.  Days should be 1-31, months should be 1_12, and the year may
be specified as (for example) 1990, or 90.  The member function
isValid() can be used to test whether the results are a valid date.

   RWDate(istream& s);
Constructs an RWDate by reading information from an input stream.
The date may be any of the following forms:

                   dd-mmm-      mm/dd/yy       mmm dd,
                      yy                          yy

            e.     10-MAR-       3/10/86      March 10,
            g:        86                         1986

Any non-alphanumeric character may be used as a delimiter.  The
member function isValid() can be used to test whether the results
are a valid date.

   RWDate(const RWTime& t);
Constructs an RWDate from an RWTime.  The member function isValid()
can be used to test whether the results are a valid date.




Rogue Wave      Tools.h++ Class Library                  261








                      CLASS REFERENCE


Public    RWBoolean           operator<(const RWDate& t) const;
member    Returns TRUE if RWDate is less than t.
operators
          RWBoolean           operator<=(const RWDate& t) const;
          Returns TRUE if RWDate is less than or equal to t.

   RWBoolean        operator>(const RWDate& t) const;
Returns TRUE if self is greater than t.

   RWBoolean        operator>=(const RWDate& t) const;
Returns TRUE if self is greater than or equal to t.

   RWBoolean        operator==(const RWDate& t) const;
Returns TRUE if self is equal to t.

   RWBoolean        operator!=(const RWDate& t) const;
Returns TRUE if self is not equal to t.

   void             operator++();
Add 1 day to self.

   void             operator--();
Subtract 1 day from self.

   void             operator+=(int s);
Add s days to self.

   void             operator-=(int s);
Substract s days from self.

   julTy            operator-(const RWDate& t) const;
Returns the number of days between self and t.


Public    RWBoolean   between(const RWDate& a, const RWDate& b) const;
member    Returns TRUE if this RWDate is between a and b
functions
          unsigned   binaryStoreSize() const;
          Returns the number of bytes necessary to store the object using
          RWDate::saveOn(RWFile&).

   int              compareTo(const RWDate* d) const;
Compares self to the RWDate pointed to by d and returns:

Rogue Wave      Tools.h++ Class Library                  262








                      CLASS REFERENCE

                0   if
                    self
                    ==
                    *d;
                1   if
                    self
                    > *d;
               _1   if
                    self
                    < *d.

   dayTy            day() const;
Returns the day of the year (1-365) for this date.

   dayTy            dayOfMonth() const;
Returns the day of the month (1-31) for this date.

   dayTy            firstDayOfMonth() const;
Returns the day of the year (1-336) corresponding to the first day
of this RWDate's month and year.

   dayTy            firstDayOfMonth(monthTy m) const;
Returns the day of the year (1-336) corresponding to the first day
of the month m (1_12) in this RWDate's year.

   unsigned         hash() const;
Returns a suitable hashing value.

   RWBoolean        isValid() const;
Returns TRUE if this is a valid date, FALSE otherwise.

   RWBoolean        leap() const;
Returns TRUE if the year of this RWDate is a leap year.

   RWDate           max(const RWDate& t) const;
Returns the greater of self or t.  For example, if t1 and t2 are
RWDates,

                    cout << t1.max(t2);

will print the greater date.

   RWDate           min(const RWDate& t) const;
Returns the lesser of self or t.

Rogue Wave      Tools.h++ Class Library                  263








                      CLASS REFERENCE

   monthTy          month() const;
Returns the month (1_12) for this date.

   const char*      nameOfDay() const;
Returns the name of the day (e.g., Tuesday) for this date.

   const char*      nameOfMonth() const;
Returns the name of the month (e.g., March) for this date.

   RWDate           previous(const char* dayName) const;
Returns the date of the previous dayName (for example, the date of
the previous Monday).

   void             restoreFrom(RWvistream& s);
Reads an RWDate that was stored with saveOn(RWvostream&) from the
input stream s.

   void             restoreFrom(RWFile& s);
Reads an RWDate that was stored with storeOn() from the RWFile s.

   void             saveOn(RWvostream& s) const;
Stores an RWDate on the output stream s.

   void             saveOn(RWFile& s) const;
Stores an RWDate in binary format on RWFile s.

   dayTy            weekDay() const;
Returns the number of the day of the week for this date, where
Monday = 1, ..., Sunday = 7.

   yearTy           year() const;
Returns the year of this date.


Static    static const char*  dayName(dayTy weekDayNumber);
member    Returns a string name for the weekday number.  Returns nil if
functions weekDayNumber is outside the range of 1 through 7.

   static dayTy     dayOfWeek(const char* dayName);
Returns the number of the day of the week corresponding to the given
dayName.  "Monday" = 1, "Sunday" = 7.  Returns 0 if no match found.

   static dayTy     daysInYear(yearTy);
Returns the number of days in a given year.

Rogue Wave      Tools.h++ Class Library                  264








                      CLASS REFERENCE

   static RWBoolean dayWithinMonth(monthTy, dayTy, yearTy);
Returns TRUE if a day (1-31) is within a given month in a given
year.

   static monthTy   indexOfMonth(const char* monthName);
Returns the number of the month (1_12) corresponding to the given
monthName.  Returns 0 for no match.

   static julTy     jday(monthTy, dayTy, yearTy);
Returns the Julian day corresponding to the given month (1_12), day
(1-31) and year.  Returns zero (0) if the date is invalid.

   static RWBoolean leapYear(yearTy);
Returns TRUE if a given year is a leap year.

   static const char*     monthName(monthTy monthNumber);
Returns a string name for the month number.  Returns nil if
monthNumber is outside the range 1 through 12.

   static void      setPrintOption(howToPrint h = normal);
Sets the formatting style for printing of dates with the <<
operator.  "RWDate::howToPrint" is an enumeration, where:

          howToPrint          Example
          normal              January 12, 1989
          terse               1-Jan-89
          numbers             1/12/89
          europeanNumbers     12/1/89
          european            12 January 1989



Related   RWDate              operator+(const RWDate& t, int s);
global    RWDate              operator+(int s, const RWDate& t);
operators Returns the date s days in the future.

   RWDate           operator-(const RWDate& t, int s);
Returns the date s days in the past.

   ostream&         operator<<(ostream& s, const RWDate& t);
Outputs the date t on ostream s, in the form specified by
setPrintOption().



Rogue Wave      Tools.h++ Class Library                  265








                      CLASS REFERENCE

   istream&         operator>>(istream& s, RWDate& t);
Reads t from istream s.  The date may be any of the following forms:

                  dd-mmm-      mm/dd/yy      mmm dd, yy
                    yy

          e.g     10-MAR-       3/10/86       March 10,
           :        86                          1986

Any non-alphanumeric character may be used as a delimiter.  If an
invalid date is encountered, the stream state will be set to "bad".
The function RWDate::isValid() can also be used to test whether the
results are a valid date.
































Rogue Wave      Tools.h++ Class Library                  266








                      CLASS REFERENCE



class RWDDEstreambuf                                RWDDEstreambuf
                                                           |
                                                       streambuf



Synopsis  #include <winstrea.h>
          #include <iostream.h>

          iostream str( new RWDDEstreambuf() );



Descripti Class RWDDEstreambuf is a specialized streambuf that gets and
on        puts sequences of characters to Microsoft Windows_ global memory
          that has been allocated with the GMEM_DDESHARE flag.  It can be
          used to exchange data through the Windows Dynamic Data Exchange
          (DDE) facility.
          The class has two modes of operation: dynamic and static.  In
          dynamic mode, memory is allocated and reallocated on an as-
          needed basis.  If too many characters are inserted into the
          internal buffer for its present size, then it will be resized
          and old characters copied over into any new memory as
          necessary.  This is transparent to the user.  It is expected
          that this mode would be used primarily by the DDE server.  In
          static mode, the buffer streambuf is constructed from a
          specific piece of memory.  No reallocations will be done.  It
          is expected that this mode would be used primarily by the DDE
          client.
          In dynamic mode, the RWDDEstreambuf "owns" any allocated
          memory until the member function str() is called, which
          "freezes" the buffer and returns an unlocked Windows handle to
          it.  The effect of any further insertions is undefined.  Until
          str() has been called, it is the responsibility of the
          RWDDEstreambuf destructor to free any allocated memory.  After
          the call to str(), it becomes the user's responsibility.
          In static mode, the user has the responsibility for freeing
          the memory handle.  However, because the constructor locks and
          dereferences the handle, you should not free the memory until
          either the destructor or str() has been called, either of
          which will unlock the handle.
          Note that although the user may have the "responsibility" for

Rogue Wave      Tools.h++ Class Library                  267








                      CLASS REFERENCE

          freeing the memory, whether it is the client or the server
          that actually does the call to GlobalFree() will depend on the
          DDE "release" flag.










































Rogue Wave      Tools.h++ Class Library                  268








                      CLASS REFERENCE

Example   This is an example of how the class might be used by a DDE server.
          #include <winstrea.h>
          #include <iostream.h>
          #include <windows.h>
          #include <dde.h>

          BOOL
          postToDDE(HWND hwndServer, HWND hwndClient)

          {

            RWDDEstreambuf* buf = new RWDDEstreambuf();

            ostream ostr(buf);

            double d = 12.34;

            ostr << "Some text to be exchanged through the DDE.\n";
            ostr << "The double you requested is: " << d << endl;

            ostr.put(\0);            // Include the terminating null

            // Lock the streambuf, get its handle:

            HANDLE hMem = buf->str();

            // Get an identifying atom:
            ATOM aItem = GlobalAddAtom("YourData");

            if(!PostMessage(hwndClient, WM_DDE_DATA, hwndServer,
                                     MAKELONG(hMem, aItem)){
              // Whoops!  The message post failed, perhaps because
              // the client terminated.  Now we are responsible

              // for deallocating the memory:

              if( hMem != NULL )

                GlobalFree(hMem);

              GlobalDeleteAtom(aItem);

              return FALSE;

            }
Rogue Wave      Tools.h++ Class Library                  269
            return TRUE;

          }








                      CLASS REFERENCE

          The handle of the DDE server is passed in as parameter
          hwndServer, the handle of the client as parameter hwndClient.
          An ostream is created, using an RWDDEstreambuf as its
          associated streambuf.  The results can be used much like any
          other ostream, such as cout, except that characters will be
          inserted into Windows global memory, from where they can be
          transferred through the DDE.  Note that we have used all
          default parameters for the constructor.  These should be
          studied below as they have important ramifications on how
          memory allocations are handled through the DDE.  In
          particular, parameter fRelease, if TRUE, states that the
          client will be responsible for deallocating the memory when
          done.  The defaults also specify fAckReq TRUE, meaning that
          the client will acknowledge the message receipt: you must be
          prepared to receive it.
          Some text and a double is inserted into the ostream.  Member
          function str() is then called which unlocks and returns a
          Windows HANDLE.  Once we have called str(), we are responsible
          for this memory and must either free it when done, or pass on
          that responsibility to someone else.  In this case, it will be
          passed on to the client.
          An atom is then constructed to identify the data.  The DDE
          data, along with its identifying atom, is then posted.  If the
          post fails, then we have been unable to foister our
          responsbility for the global memory onto someone else and will
          have to free it (along with the atom) ourselves.

Public    RWDDEstreambuf(     WORD cfFormat = CF_TEXT,
construct                     BOOL fResponse = TRUE
ors                           BOOL fAckReq = TRUE
                              BOOL fRelease = TRUE);
          Constructs an empty RWDDEstreambuf in dynamic mode.  The
          results can be used anywhere any other streambuf can be
          used.  Memory to accomodate new characters will be
          allocated as needed.

The four parameters are as defined by the Windows Reference, Volume
2 (in particular, see the section DDE Message Directory).  Parameter
cfFormat specifies the format of the data being inserted into the
streambuf.  These formats are the same as used by
SetClipboardData().  If a specializing virtual streams class such as
RWbostream or RWpostream is used to perform the actual character
insertions instead of a simple ostream, the format may not be so
simple.  In this case, the user might want to register his or her

Rogue Wave      Tools.h++ Class Library                  270








                      CLASS REFERENCE

own format, using the Windows function RegisterClipboardFormat().

For the meaning of the other three parameters see below, and/or the
Windows reference manuals.

   RWDDEstreambuf(HANDLE hMem)
Constructs a RWDDEstreambuf in static mode, using the memory block
with global handle hMem.  The effect of gets and puts beyond the
size of this block is unspecified.  The format of the DDE transfer,
and the specifics of DDE acknowledgments, memory allocations, etc.,
can be obtained by using the member functions defined below.

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


Public    Because RWDDEstreambuf inherits from streambuf, any of the latter's
member    member functions can be used.  Furthermore, RWDDEstreambuf has been
functions designed to be analogous to strstreambuf.  However, note that the
          return type of str() is a HANDLE, rather than a char*.
   BOOL             ackReq() const;
Returns whether this DDE exchange requests an acknowledgement.  See
the Windows Reference, Volume 2, for more information.

   WORD             format() const;
Returns the format of this DDE exchange (e.g., CF_TEXT for text
exchange, etc.).  See the Windows Reference, Volume 2, for more
information.

   BOOL             release() const;
Returns TRUE if the client is responsible for the release of of the
memory returned by str().  See the Windows Reference, Volume 2, for
more information.

   BOOL             response() const;
Returns TRUE if this data is in response to a WM_DDE_REQUEST
message.  Otherwise, it is in response to a WM_DDE_ADVISE message.
See the Windows Reference, Volume 2, for more information.

   HANDLE           str();
Returns an (unlocked) HANDLE to the global memory being used.  The
RWDDEstreambuf should now be regarded as "frozen": the effect of
inserting any more characters is undefined.  If the RWDDEstreambuf

Rogue Wave      Tools.h++ Class Library                  271








                      CLASS REFERENCE

was constructed in dynamic mode, and nothing has been inserted, then
the returned HANDLE may be NULL.  If it was constructed in static
mode, then the returned handle will be the handle used to construct
the RWDDEstreambuf.









































Rogue Wave      Tools.h++ Class Library                  272








                      CLASS REFERENCE



class RWDlistCollectables                   RWDlistCollectables
                                            |          |
                                        RWSequenceableRWDlist
                                            |          |
                                            RWCollection RWSlist
                                            |
                                        RWCollectable

Synopsis  #include <dlistcol.h>
          RWDlistCollectables a;



Descripti Class RWDlistCollectables represents a group of ordered items, not
on        accessible by an external key.  Duplicates are allowed.  The
          ordering of elements is determined externally, generally by the
          order of insertion and removal.  An object stored by
          RWDlistCollectables must inherit abstract base class RWCollectable.
          Class RWDlistCollectables is implemented as a doubly-linked
          list, which allows for efficient insertion and removal, as
          well as for movement in either direction.

Public    RWDlistCollectables();
construct Constructs an empty doubly-linked list.
ors

   RWDlistCollectables (const RWCollectable* a);
Constructs a linked-list with a single item a.















Rogue Wave      Tools.h++ Class Library                  273








                      CLASS REFERENCE


Public    RWBoolean    operator==(const RWDlistCollectables& d) const;
member    Returns TRUE if self and d have the same number of items and if
operators for every item in self, the corresponding item in the same
          position in d isEqual to it.


Public    virtual                Collectable*     append(RWCollectable*);
member    Redefined from RWSequenceable.  Inserts the item at the end of
functions the collection and returns it.  Returns nil if the insertion
          was unsuccesful.

   virtual void     apply(applyCollectable ap, void*)
Redefined from class RWCollection to apply the user-supplied
function pointed to by ap to each member of the collection, in
order, from first to last.

   virtual         RWCollectable*&  at(int i);
   virtual const RWCollectable                       *  at(int i) const;
Redefined from class RWSequenceable.  Note that for a linked-list,
these functions must traverse all the links, making them not
particularly efficient.

   virtual unsigned binaryStoreSize() const;
Inherited from class RWCollection.

   virtual void     clear();
Redefined from class RWCollection.

   virtual void     clearAndDestroy();
Inherited from class RWCollection.

   virtual int      compareTo(const RWCollectable* a) const;
Inherited from class RWCollectable.

   virtual RWBoolean      contains(const RWCollectable* target) const;
Inherited from class RWCollection.

   RWBoolean        containsReference(const RWCollectable* e) const;
Returns true if the list contains an item that is identical to the
item pointed to by e (that is, that has the address e).

   virtual         unsigned   entries() const;
Redefined from class RWCollection.

Rogue Wave      Tools.h++ Class Library                  274








                      CLASS REFERENCE

   virtual         RWCollectable*   find(const RWCollectable* target) const;
Redefined from class RWCollection.  The first item that isEqual to
the item pointed to by target is returned, or nil if no item is
found..

   RWCollectable*   findReference(const RWCollectable* e) const;
Returns the first item that is identical to the item pointed to by e
(that is, that has the address e), or nil if none is found.

   virtual         RWCollectable*   first() const;
Redefined from class RWSequenceable.  Returns the item at the
beginning of the list.

   RWCollectable*   get();
Returns and removes the item at the beginning of the list.

   virtual unsigned hash() const;
Inherited from class RWCollectable.

   virtual int      index(const RWCollectable* c) const;
Redefined from class RWSequenceable.  Returns the index of the first
item that isEqual to the item pointed to by c.

   virtual         RWCollectable*   insert(RWCollectable* c);
Redefined from class RWCollection.  Adds the item to the end of the
collection and returns it.  Returns nil if the insertion was
unsuccessful.

   virtual         RWCollectable*   insertAfter(int i, RWCollectable* c);
Redefined from class RWSequenceable.  Inserts and returns the object
pointed to by c after the item at index i.  Returns nil if the
insertion was unsuccessful.

   virtual ClassID  isA() const;
Redefined from class RWCollectable to return __RWDLISTCOLLECTABLES.

   virtual RWBoolean      isEmpty() const;
Redefined from class RWCollection.

   virtual         RWCollectable*   last() const;
Redefined from class RWSequenceable.  Returns the item at the end of
the list.



Rogue Wave      Tools.h++ Class Library                  275








                      CLASS REFERENCE

   virtual unsigned occurrencesOf(const RWCollectable* target) const;
Redefined from class RWCollection.  Returns the number of items that
isEqual to the item pointed to by target.

   unsigned            occurrencesOfReference  (const RWCollectable* e) const;
Returns the number of items that are identical to the item pointed
to by e (that is, that have the address e).

   virtual         RWCollectable*   prepend(RWCollectable*);
Redefined from class RWSequenceable.  Adds the item to the beginning
of the collection and returns it.  Returns nil if the insertion was
unsuccessful.

   virtual         RWCollectable*   remove(const RWCollectable* target);
Redefined from class RWCollection.  Removes and returns the first
item that isEqual to the item pointed to by target.  Returns nil if
there is no such item.

   virtual         void       removeAndDestroy(const RWCollectable* target);
Inherited from class RWCollection.

   RWCollectable*   removeReference(const RWCollectable* e);
Removes and returns the first item that is identical to the item
pointed to by e (that is, that has the address e).  Returns nil if
there is no such item.

   virtual void     restoreGuts(RWvistream&);
   virtual void     restoreGuts(RWFile&);
   virtual void     saveGuts(RWvostream&) const;
   virtual void     saveGuts(RWFile&) const;
Inherited from class RWCollection.














Rogue Wave      Tools.h++ Class Library                  276








                      CLASS REFERENCE

   static        RWCollectable*    restoreFrom(RWvistream&);
   static        RWCollectable*    restoreFrom(RWFile&);
   void             saveOn(RWvostream&) const;
   void             saveOn(RWFile&) const;
Inherited from class RWCollectable.








































Rogue Wave      Tools.h++ Class Library                  277








                      CLASS REFERENCE



class RWDlistCollectablesIterator        RWDlistCollectablesIterator
                                              |         |
                                         RWIteratorRWDlistIterator
                                                        |
                                                 RWSlistIterator

Synopsis  #include <dlistcol.h>
          RWDlistCollectables d;
          RWDlistCollectablesIterator it(d);



Descripti Iterator for class RWDlistCollectables. Traverses the linked-list
on        from the first (head) to the last (tail) item.  Functions are
          provided for moving in either direction.
          #include <dlistcol.h>



          RWDlistCollectablesIterator (RWDlistCollectables& d);
Public    Construct a RWDlistCollectablesIterator from a
construct RWDlistCollectables.  Immediately after construction, the
or        iterator is positioned at the last link of d.


Public    virtual                RWCollectable*      operator()();
member    Redefined from class RWIterator.  Advances the iterator to the
operators next item and returns it.  Returns nil when the end of the list
          is reached.

   void             operator++();
Advances the iterator one item.  This operator wraps around to the
start of list.

   void             operator--();
Moves the iterator back one item.  This operator wraps around to the
end of the list.

   void             operator+=(int n);
Advances the iterator n items.  This operator wraps around to the
start of the list.


Rogue Wave      Tools.h++ Class Library                  278








                      CLASS REFERENCE

   void             operator-=(int n);
Moves the iterator back n items.  This operator wraps around to the
end of the list.


Public    RWBoolean           atFirst() const;
member    Returns TRUE if the iterator is at the beginning of the
functions list, otherwise FALSE;

   RWBoolean        atLast() const;
Returns TRUE if the iterator is at the end of the list, otherwise
FALSE;

   virtual         RWCollectable*   findNext(const RWCollectable* target);
Redefined from class RWIterator.  Moves iterator to the next item
which isEqual to the item pointed to by target and returns it.  If
no item is found, returns nil and the position of the iterator will
be undefined.

   RWCollectable*   findNextReference(const RWCollectable* e);
Moves iterator to the next item which is identical to the item
pointed to by e (that is, that has address e) and returns it.  If no
item is found, returns nil and the position of the iterator will be
undefined.

   RWCollectable*   insertAfterPoint(RWCollectable* a);
Insert item a after the current cursor position and return the item.
The cursor's position will be unchanged.

   virtual         RWCollectable*   key() const;
Redefined from class RWIterator.  Returns the item at the current
iterator position.

   RWCollectable*   remove();
Removes and returns the item at the current cursor position.
Afterwards, the iterator will be positioned at the next item in the
list.

   RWCollectable*   removeNext(const RWCollectable* target);
Moves iterator to the next item in the list which isEqual to the
item pointed to by target, removes it from the list and returns it.
Afterwards, the iterator will be positioned at the next item in the
list.  If no item is found, returns nil and the position of the
iterator will be undefined.

Rogue Wave      Tools.h++ Class Library                  279








                      CLASS REFERENCE

   RWCollectable*   removeNextReference(const RWCollectable* e);
Moves iterator to the next item in the list which is identical to
the item pointed to by e (that is, that has address e), removes it
from the list and returns it.  Afterwards, the iterator will be
positioned at the next item in the list.  If no item is found,
returns nil and the position of the iterator will be undefined.

   virtual void     reset();
Redefined from class RWIterator.  Resets the iterator.  Afterwards,
the iterator will be positioned at the last item in the list.

   void             toFirst();
Moves the iterator to the beginning of the list.

   void             toLast();
Moves the iterator to the end of the list.





























Rogue Wave      Tools.h++ Class Library                  280








                      CLASS REFERENCE



class RWErrObject





Synopsis  #include <rwerr.h>

          RWErrObject obj(TOOL_INDEX, RWFATAL, __RWORDERED);     // Sample use



Descripti This class is used by the Rogue Wave exception handling facility.
on        It is "thrown" by an exception, to be "caught" by the catch phrase.
          At the time of this writing, no compiler manufacturer has actually
          implemented exception handling, so the default handler merely
          prints out the error message and aborts.
          The default error handler can be changed.  See Section 16.1.4
          in the Tools.h++ User's Guide for instructions.
























Rogue Wave      Tools.h++ Class Library                  281








                      CLASS REFERENCE

Example   This example changes the default error handler:
          #include <rwerr.h>
          #include <rstream.h>
          #include <stdlib.h>

          void myHandler(RWErrObject eobj, va_list arglist);

          main()
          {
            setRWErrHandler(myHandler);  // Change the default handler

            // ...
          }

          void myHandler(RWErrObject eobj, va_list arglist)
          {
            cerr << "Boy, did you screw up!\n";
            cerr << "You had error number " << eobj.number() << NL;
            cerr << "Caused by class " << eobj.classID() << NL;

            exit(eobj.severity());
          }

          Of course, this is a pretty simple handler -- it did not check
          to see whether the routine throwing the exception specified a
          default disposition.  It just aborts.  Also, it did not make
          use of any auxilary information in the va_list.

Public    RWErrObject(RWErrNo n, RWSeverity sever=RWDEFAULT,
construct              ClassID cl=__GLOBAL);
or        Construct an error object with error number n and disposition
          sever.  The class causing the exception is given by cl.


Public    RWErrNo             number() const;
member    Returns the error number of this error object.
functions
          RWSeverity          severity() const;
          Returns the disposition of this error.

   ClassID          classID() const;
Returns the class that invoked this exception.



Rogue Wave      Tools.h++ Class Library                  282








                      CLASS REFERENCE


Related   RWErrHandler   setRWErrHandler(RWErrHandler routine);
global    Changes the default error handler to the function pointed to
functions by routine and returns a pointer to the old error handler.
          The function pointed to by routine should have prototype:

                 void yourRoutine(RWErrObject, va_list);

where "va_list" is a variable argument list, defined in <stdarg.h>.




































Rogue Wave      Tools.h++ Class Library                  283








                      CLASS REFERENCE



class RWFactory





Synopsis  typedef unsigned short  ClassID;
          typedef RWCollectable*  (*userCreator)();
          #include <factory.h>

          RWFactory theFactory;



Descripti Class RWFactory can create an instance of a RWCollectable object,
on        given a class ID.  It does this by maintaining a table of class
          ID's and associated "creator function".  A creator function has
          prototype:
                    RWCollectable* aCreatorFunction();

          This function should create an instance of a particular class.
          For a given ClassID tag, the appropriate function is selected,
          invoked and the resultant pointer returned.  Because any
          object created this way is created off the heap, you are
          responsible for deleting it when done.
          There is a one-of-a-kind global RWFactory pointed to by the
          pointer theFactory.  It is guaranteed to have creator
          functions in it for all of the classes referenced by your
          program.  See also Section 15.10.11.














Rogue Wave      Tools.h++ Class Library                  284








                      CLASS REFERENCE

Example   #include <factory.h>
          #include <rstream.h>

          main()
          {
            // Create a new RWBag off the heap, using the Class ID __RWBAG.
            // "theFactory" points to the predefined global factory:

            RWBag* b = (RWBag*)theFactory->create(__RWBAG);

            b->insert( new CollectableDate );   // Insert today's date
            // ...
            b->clearAndDestroy();    // Cleanup: first delete members,
            delete b;  // then the bag itself
          }



Public    RWFactory();
construct Construct an RWFactory.
ors


Public    void   addFunction(userCreator uc, ClassID id);
member    Adds to the RWFactory the global function pointed to by uc,
functions which creates an instance of an object with ClassID id.

   RWCollectable*   create(ClassID id) const;
Allocates a new instance of the class with ClassID id off the heap
and returns a pointer to it.  Returns nil if id does not exist.
Because this instance is allocated off the heap, you are responsible
for deleting it when done.

   userCreator      getFunction(ClassID id) const;
Returns from the RWFactory a pointer to the global function
associated with ClassID id.  Returns nil if id does not exist.

   void             removeFunction(ClassID id);
Removes from the RWFactory the global function associated with
ClassID id.  If id does not exist in the factory, no action is
taken.




Rogue Wave      Tools.h++ Class Library                  285








                      CLASS REFERENCE



class RWFile





Synopsis  #include <rwfile.h>

          RWFile f("filename");



Descripti Class RWFile encapsulates standard file operations.  This class
on        is based on class PFile of the Interviews Class Library (1987,
          Stanford University).  The member function names begin with
          upper case letters in order to maintain compatibility with class
          PFile .
          Class RWFile has been modified (and modernized) by Rogue Wave
          to use "const" modifiers, and to port to MS-DOS.

Public    RWFile(const char* filename);
construct Construct an RWFile with file filename.  This constructor will
ors       open a binary file called filename for read/write, creating it
          if it does not already exist.  If the file cannot be created an
          exception with error CORE_OPERR will occur.

   ~RWFile();
Performs any pending I/O operations and closes the file.


Public    long                CurrOffset();
member    Returns the current position, in bytes from the start of the
functions file, of the file pointer.

   RWBoolean        Eof();
Returns TRUE if an end-of-file has been encountered.

   RWBoolean        Erase();
Erases the contents but does not close the file.  Returns TRUE if
the operation was successful.



Rogue Wave      Tools.h++ Class Library                  286








                      CLASS REFERENCE

   RWBoolean        Error();
Returns TRUE if a file I/O error has occurred.

   RWBoolean        Exists();
Returns TRUE if the file exists and has read/write permission.

   RWBoolean        Exists(const char* filename);
Returns TRUE if an RWFile with name filename exists, with read/write
permission.

   RWBoolean        Flush();
Perform any pending I/O operations.  Returns TRUE if successful.

   const char*      GetName();
Returns the file name.

   RWBoolean        IsEmpty();
Returns TRUE if the file contains no data, else returns FALSE.

   RWBoolean        Read(char& c);
   RWBoolean        Read(short& i);
   RWBoolean        Read(int& i);
   RWBoolean        Read(long& i);
   RWBoolean        Read(unsigned char& c);
   RWBoolean        Read(unsigned short& i);
   RWBoolean        Read(unsigned int& i);
   RWBoolean        Read(unsigned long& i);
   RWBoolean        Read(float& f);
   RWBoolean        Read(double& d);
Reads the indicated built-in type.  Returns TRUE if the read is
successful.

   RWBoolean        Read(char* i, int count);
   RWBoolean        Read(short* i, int count);
   RWBoolean        Read(int* i, int count);
   RWBoolean        Read(long* i, int count);
   RWBoolean        Read(unsigned char* i, int count);
   RWBoolean        Read(unsigned int* i, int count);
   RWBoolean        Read(float* i, int count);
   RWBoolean        Read(double* i, int count);
Reads count instances of the indicated built-in type into a block
pointed to by i.  Returns TRUE if the read is successful.  Note that
you are responsible for declaring i and for allocating the necessary
storage before calling this function.

Rogue Wave      Tools.h++ Class Library                  287








                      CLASS REFERENCE

   RWBoolean        Read(char* string);
Reads a character string, including the terminating null character,
into a block pointed to by string.  Returns TRUE if the read is
successful.  Note that you are responsible for declaring string and
for allocating the necessary storage before calling this function.
Beware of overflow when using this function.

   RWBoolean        SeekTo(long offset);
Repositions the file pointer to offset bytes from the start of the
file.  Returns TRUE if the operation is successful.

   RWBoolean        SeekToBegin();
Repositions the file pointer to the start of the file.  Returns TRUE
if the operation is successful.

   RWBoolean        SeekToEnd();
Repositions the file pointer to the end of the file.  Returns TRUE
if the operation is successful.

   RWBoolean        Write(char i);
   RWBoolean        Write(short i);
   RWBoolean        Write(int i);
   RWBoolean        Write(long i);
   RWBoolean        Write(unsigned char i);
   RWBoolean        Write(unsigned short i);
   RWBoolean        Write(unsigned int i);
   RWBoolean        Write(unsigned long i);
   RWBoolean        Write(float f);
   RWBoolean        Write(double d);
Writes the appropriate built-in type.  Returns TRUE if the write is
successful.

   RWBoolean        Write(const char* i, int count);
   RWBoolean        Write(const short* i, int count);
   RWBoolean        Write(const int* i, int count);
   RWBoolean        Write(const long* i, int count);
   RWBoolean        Write(const unsigned char* i, int count);
   RWBoolean        Write(const unsigned int* i, int count);
   RWBoolean        Write(const float* i, int count);
   RWBoolean        Write(const double* i, int count);
Writes count instances of the indicated built-in type from a block
pointed to by i.  Returns TRUE if the write is successful.



Rogue Wave      Tools.h++ Class Library                  288








                      CLASS REFERENCE

   RWBoolean        Write(const char* string);
Writes a character string, including the terminating null character,
from a block pointed to by string.  Returns TRUE if the write is
successful.  Beware of non-terminated strings when using this
function.








































Rogue Wave      Tools.h++ Class Library                  289








                      CLASS REFERENCE



class RWFileManager                                   RWFileManager
                                                            |
                                                          RWFile



Synopsis  typedef   long             RWoffset;
          typedef   unsigned  RWspace;  // (typically)

          #include <filemgr.h>
          RWFileManager f("file.dat");



Descripti Class RWFileManager allocates and deallocates storage in a disk
on        file.  It does this by maintaining a linked list of free space
          within the file.  NOTE:  Class RWFileManager inherits class
          RWFile as a public base class, hence all the public member
          functions of RWFile are visible to RWFileManager.  They are not
          listed here.

Public    RWFileManager(const char* filename);
construct Construct a RWFileManager for the file with path name
or        filename.  The RWFileManager can be constructed with an old
          file or it can create a new file.  If it is constructed with
          an old file, then the file must have been originally created
          by a RWFileManager.  Possible exceptions that can occur are
          TOOL_WRITEERR, TOOL_READERR, or TOOL_FLIST.


Public    RWoffset            allocate(RWspace s);
member    Allocates s bytes of storage in the file.  Returns the offset
functions to the start of the storage location.  The very first
          allocation for the file is considered "special" and can be
          returned at any later time by the function start().  Possible
          exceptions that can occur are TOOL_WRITEERR, TOOL_READERR and
          TOOL_SEEKERR.

   void             deallocate(RWoffset t);
Deallocates (frees) the storage space starting at offset t.  This
space must have been previously allocated by a call to allocate().
The very first allocation ever made in the file is considered

Rogue Wave      Tools.h++ Class Library                  290








                      CLASS REFERENCE

"special" and cannot be deallocated.  Possible exceptions that can
occur are TOOL_WRITEERR, TOOL_READERR and TOOL_SEEKERR.

   RWoffset         endData();
Returns the offset of the last space allocated on this file.  If no
space has every been allocated, returns NIL.

   RWoffset         start();
Returns the offset of the first space ever allocated for this file.
If no space has every been allocated, returns NIL.  This is
typically used to "get started" and find the rest of the data in the
file.

































Rogue Wave      Tools.h++ Class Library                  291








                      CLASS REFERENCE



class RWHashDictionary                    RWHashDictionary
                                                  |
                                                RWSet
                                                  |
                                            RWCollection
                                                  |
                                            RWCollectable


Synopsis  typedef RWHashDictionary Dictionary;

           // Smalltalk typedef.

          #include <hashdict.h>
          RWHashDictionary  a;



Descripti A RWHashDictionary represents a group of unordered values,
on        accessible by external keys.  Duplicate keys are not allowed.
          Class RWHashDictionary is implemented as a hash table of
          associations of keys and values.  Both the key and the value must
          inherit from abstract the base class RWCollectable, with a
          suitable definition of the virtual function hash() and isEqual()
          for the key.
          This class corresponds to the Smalltalk class Dictionary.
          When the hash table becomes greater than 2/3 full, it will
          automatically resize to the next prime number greater that
          twice the present table size.

Public    RWHashDictionary(unsigned n = 101);
construct Construct an empty hashed dictionary with a size that is the next
ors       highest prime number that is greater than or equal to n.

   RWHashDictionary(const RWHashDictionary& hd);
Copy constructor.  A shallow copy of the collection hd is made.







Rogue Wave      Tools.h++ Class Library                  292








                      CLASS REFERENCE


Public    void                operator=(const RWHashDictionary& hd);
member    Assignment operator.  A shallow copy of the collection hd is
operators made.

          RWBoolean           operator<=(const RWHashDictionary& hd) const;
          Returns TRUE if for every key-value pair in self, there is a
          corresponding key in hd that isEqual.  Their corresponding
          values must also be equal.

   RWBoolean        operator==(const RWHashDictionary& hd) const;
Returns TRUE if self and hd have the same number of entries and if
for every key-value pair in self, there is a corresponding key in hd
that isEqual.  Their corresponding values must also be equal.


Public    void                applyToKeyAndValue(applyKeyAndValue ap, void*)
member    Applies the user-supplied function pointed to by ap to each key-
functions value pair of the collection.  Items are not visited in any
          particular order.

   virtual unsigned binaryStoreSize() const;
Inherited from class RWCollection.

   virtual void     clear();
Redefined from class RWCollection.  Removes all key-value pairs in
the collection.

   virtual void     clearAndDestroy();
Redefined from class RWCollection.  Removes all key-value pairs in
the collection, and deletes 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 unsigned entries() const;
Inherited from class RWSet.

   virtual         RWCollectable*   find(const RWCollectable* target) const;
Redefined from class RWCollection.  Returns the key which isEqual to
the object pointed to by target, or nil if no key was found.

Rogue Wave      Tools.h++ Class Library                  293








                      CLASS REFERENCE

   RWCollectable*   findKeyAndValue(const RWCollectable* target,
                    RWCollectable*& v) const;
Returns the key which isEqual to the item 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 isEqual to the item
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 isEqual to the item
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.

   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 ClassID  isA() const;
Redefined from class RWCollectable to return __RWHASHDICTIONARY.

   virtual RWBoolean      isEmpty() const;
Inherited from class RWSet.

   virtual RWBoolean      isEqual(const RWCollectable* a) const;
Inherited from class RWCollectable.

   virtual         unsigned   occurrencesOf(const RWCollectable* target) const;
Inherited from class RWSet.  Returns the number of keys which
isEqual to the item pointed to by 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
where the key isEqual to the item pointed to by target.  Returns the
key, or nil if no match was found.



Rogue Wave      Tools.h++ Class Library                  294








                      CLASS REFERENCE

   virtual void     removeAndDestroy(const RWCollectable* target);
Redefined from class RWCollection.  Removes and deletes the key and
value pair where the key isEqual to the item 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 where the key isEqual to the item
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.

   void             resize(unsigned n = 0);
Inherited from class RWSet.

   virtual void     restoreGuts(RWvistream&);
   virtual void     restoreGuts(RWFile&);
   virtual void     saveGuts(RWvostream&) const;
   virtual void     saveGuts(RWFile&) const;
Inherited from class RWCollection.

   static        RWCollectable*    restoreFrom(RWvistream&);
   static        RWCollectable*    restoreFrom(RWFile&);
   void             saveOn(RWvostream&) const;
   void             saveOn(RWFile&) const;
Inherited from class RWCollectable.


















Rogue Wave      Tools.h++ Class Library                  295








                      CLASS REFERENCE



class RWHashDictionaryIterator             RWHashDictionaryItera
                                                    tor
                                                     |
                                               RWSetIterator
                                                     |
                                                RWIterator

Synopsis  #include <hashdict.h>

          RWHashDictionary           hd;
          RWHashDictionaryIterator   iter(hd);



Descripti Iterator ;for class RWHashDictionary, allowing sequential
on        access to all the elements of RWHashDictionary.  Since
          RWHashDictionary is unordered, elements are not accessed in any
          particular order.

Public    RWHashDictionaryIterator(RWHashDictionary&);
construct Construct an iterator for a RWHashDictionary collection.
or        Immediately after construction, the position of the iterator
          is undefined until positioned.


Public    virtual                RWCollectable*      operator()();
member    Redefined from class RWIterator.  Advances the iterator to the
operator  next key-value pair and returns the key.  Returns nil if the
          cursor is at the end of the collection.  Use member function
          value() to recover the value.


Public    virtual    RWCollectable*     findNext(const RWCollectable* target);
member    Redefined from class RWIterator.  Moves the iterator to the
functions next key-value pair where the key isEqual to the object pointed
          to by target.  Returns the key or nil if no key was found.

   virtual         RWCollectable*   key() const;
Redefined from class RWIterator.  Returns the key at the current
iterator position.



Rogue Wave      Tools.h++ Class Library                  296








                      CLASS REFERENCE

   RWCollectable*   remove();
Removes the key-value pair at the current iterator position.
Returns the key, or nil if there was no key-value pair.

   RWCollectable*   removeNext(const RWCollectable* target);
Moves the iterator to the next key-value pair where the key isEqual
to the object pointed to by target.  Removes the key-value pair,
returning the key or nil if there was no match.

   virtual void     reset();
Redefined from class RWIterator.  Inherited from class
RWSetIterator.  Resets the iterator to its initial state.

   RWCollectable*   value() const;
Returns the value at the current iterator position.

   RWCollectable*   value(RWCollectable* newValue) const;
Replaces the value at the current iterator position and returns the
old value.


























Rogue Wave      Tools.h++ Class Library                  297








                      CLASS REFERENCE



class RWIdentityDictionary              RWIdentityDictionar
                                                  y
                                                  |
                                          RWHashDictionary
                                                  |
                                                RWSet
                                                  |
                                            RWCollection
                                                  |
                                            RWCollectable


Synopsis  #include <idendict.h>
          typedef RWIdentityDictionary IdentityDictionary; // Smalltalk typedef

          RWIdentityDictionary a;



Descripti The class RWIdentityDictionary is implemented as a hash table, for
on        the storage and retrieval of key-value pairs.  Class
          RWIdentityDictionary is similar to class RWHashDictionary except
          that items are found by requiring that they be identical (i.e.,
          have the same address) as the key, rather than being equal (i.e.,
          test true for isEqual()).
          Both keys and values must inherit from the abstract base class
          RWCollectable.
          The iterator for this class is RWHashDictionaryIterator.

Public    RWIdentityDictionary(unsigned n = 101);
construct Construct an empty identity dictionary with a hash table with n
or        entries.


Public    The user interface to this class is identical to class
member    RWHashDictionary and is not reproduced here.  The only difference
functions between the classes is that keys are found on the basis of
          identity rather than equality, and that the virtual function isA()
          returns __RWIDENTITYDICTIONARY, the ClassId for
          RWIdentityDictionary.



Rogue Wave      Tools.h++ Class Library                  298








                      CLASS REFERENCE



class RWIdentitySet                         RWIdentitySet
                                                  |
                                                RWSet
                                                  |
                                            RWCollection
                                                  |
                                            RWCollectable

Synopsis  #include <idenset.h>
          typedef RWIdentitySet IdentitySet;

          // Smalltalk typedef
          RWIdentitySet a;



Descripti The class RWIdentitySet is similar to class RWSet except that
on        items are found by requiring that they be identical (i.e., have
          the same address) as the key, rather than being equal (i.e., test
          true for isEqual()).
          The iterator for this class is RWSetIterator.

Public    RWIdentitySet(unsigned n = 101);
construct Construct an empty identity set with a hash table having n
or        entries.


Public    The user interface to this class is identical to class RWSet and
member    is not reproduced here.  The only difference between the classes
functions is that keys are found on the basis of identity rather than
          equality, and that the virtual function isA() returns
          __RWIDENTITYSET, the ClassId for RWIdentitySet.











Rogue Wave      Tools.h++ Class Library                  299








                      CLASS REFERENCE



class RWInteger





Synopsis  #include <rwint.h>

          RWInteger i;



Descripti Integer class.  This class is useful as a base class for
on        classes that use integers as keys in dictionaries, etc.

Public    RWInteger();
construct Construct a RWInteger with value zero (0).
ors

   RWInteger(int i);
Construct a RWInteger with value i.  Serves as a type conversion
from int.


Type      operator            int();
conversionType conversion to int.


Public    unsigned            binaryStoreSize() const;
member    Returns the number of bytes necessary to store the object
functions using RWInteger::saveOn(RWFile&).

   void             restoreFrom(RWvistream& s);
Reads an RWInteger that was stored with saveOn() from the input
stream s.

   void             restoreFrom(RWFile& s);
Reads an RWInteger that was stored with saveOn() from the RWFile s.

   void             saveOn(RWvostream& s) const;
Stores an RWInteger on the output stream s.


Rogue Wave      Tools.h++ Class Library                  300








                      CLASS REFERENCE

   void             saveOn(RWFile& s) const;
Stores an RWInteger in binary format on RWFile s.

   int              value() const;
Returns the value of the RWInteger.

   int              value(int newval);
Changes the value of the RWInteger to newval and returns the old
value.


Related   ostream&            operator<<(ostream& o, const RWInteger& x);
Global    Output x to ostream o.
Operators
          istream&            operator>>(istream& i, RWInteger& x);
          Input x from istream i.





























Rogue Wave      Tools.h++ Class Library                  301








                      CLASS REFERENCE



class RWIterator





Synopsis  #include <iterator.h>

          typedef RWIterator Iterator;  // "Smalltalk" typedef



Descripti Class RWIterator is an abstract base class for iterators used by
on        the Smalltalk_-like collection classes.  The class contains virtual
          functions for positioning and resetting the iterator.  They are all
          pure virtual functions, meaning that deriving classes must supply a
          definition.  The descriptions below are intended to be generic --
          all inheriting iterators generally follow the described pattern.

Public    virtual RWCollectable*   findNext(const RWCollectable* target) = 0;
virtual   Moves the iterator forward to the next item which "matches" the
functions object pointed to by target and returns it or nil if no item
          was found.  For most collections, an item "matches" the target
          if either isEqual() or compareTo() find equivalence, whichever
          is appropriate for the actual collection type.  However, when
          an iterator is used with an "identity collection" (i.e.,
          RWIdentitySet and RWIdentityDictionary), it looks for an item
          with the same address (i.e., "is identical to").

   virtual         RWCollectable*   key() const = 0;
Returns the item at the current iterator position.

   virtual         RWCollectable*   operator()() = 0;
Advances the iterator and returns the next item, or nil if the end
of the collection has been reached.

   virtual         void       reset() = 0;
Resets the iterator to the state it had immediately after
construction.




Rogue Wave      Tools.h++ Class Library                  302








                      CLASS REFERENCE



class RWOrdered                               RWOrdered
                                                  |
                                           RWSequenceable
                                                  |
                                            RWCollection
                                                  |
                                            RWCollectable

Synopsis  #include <ordcltn.h>

          RWOrdered a;



Descripti Class RWOrdered represents a group of ordered items, accessible by
on        an index number, but not accessible by an external key.
          Duplicates are allowed.  The ordering of elements is determined
          externally, generally by the order of insertion and removal.  An
          object stored by RWOrdered must inherit from the abstract base
          class RWCollectable.
          Class RWOrdered is implemented as a vector of pointers,
          allowing for more efficient traversing of the collection than
          the linked list classes RWSlistCollectables and
          RWDlistCollectables, but slower insertion in the center of the
          collection.

Public    RWOrdered(int size = 101);
construct Construct an RWOrdered with initially size entries.
ors


Public    RWBoolean           operator==(const RWOrdered& od) const;
member    Returns TRUE if for every item in self, the corresponding item
operators in od at the same index isEqual.  The two collections must also
          have the same number of members.

   RWCollectable*&  operator[](int i);
Returns the i'th element in the collection.  If i is out of range,
an exception will occur with error TOOL_INDEX.  The results of this
function can be used as an lvalue.



Rogue Wave      Tools.h++ Class Library                  303








                      CLASS REFERENCE

   RWCollectable*&  operator()(int i);
Returns the i'th element in the collection.  Bounds checking is
enabled by defining the preprocessor directive BOUNDS_CHECK before
including the header file ordcltn.h.  In this case, if i is out of
range, an exception will occur with error TOOL_INDEX.  .  The
results of this function can be used as an lvalue.


Public    virtual                RWCollectable*      append(RWCollectable*);
member    Redefined from class RWSequenceable.  Adds the item to the
functions end of the collection and returns it.  Returns nil if the
          insertion was unsuccessful.

   virtual void     apply(applyCollectable ap, void* x);
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 order, from first to last.

   virtual RWCollectable*&at(int i);
   virtual const RWCollectable*  at(int i) const;
Redefined from class RWSequenceable.

   virtual unsigned 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 unsigned entries() const;
Redefined from class RWCollection.

   virtual         RWCollectable*   find(const RWCollectable* target) const;
Redefined from class RWCollection.  Returns the first item that
isEqual to the item pointed to by target, or nil if no item was
found..

Rogue Wave      Tools.h++ Class Library                  304








                      CLASS REFERENCE

   virtual         RWCollectable*   first() const;
Refined from class RWSequenceable.  Returns the first item in the
collection.

   virtual unsigned hash() const;
Inherited from class RWCollectable.

   virtual int      index(const RWCollectable*) const;
Refined from class RWSequenceable.

   virtual         RWCollectable*   insert(RWCollectable* c);
Redefined from class RWCollection.  Adds the item to the end of the
collection and returns it.  Returns nil if the insertion was
unsuccessful.

   virtual         RWCollectable*   insertAfter(int i, RWCollectable* c);
Redefined from class RWSequenceable.  Inserts and returns the object
pointed to by c after the item at index i.  Returns nil if i is out
of bounds or the insertion was otherwise unsuccessful.

   virtual ClassID  isA() const;
Redefined from class RWCollectable to return __RWORDERED.

   virtual RWBoolean      isEmpty() const;
Redefined from class RWCollection.

   virtual RWBoolean      isEqual(const RWCollectable* a) const;
Inherited from class RWCollectable.

   virtual         RWCollectable*   last() const;
Refined from class RWSequenceable.  Returns the last item in the
collection.

   virtual unsigned occurrencesOf(const RWCollectable* target) const;
Redefined from class RWCollection.  Returns the number of items that
compare isEqual to the item pointed to by target.

   RWCollectable*   prepend(RWCollectable*);
Redefined from class RWSequenceable.  Adds the item to the beginning
of the collection and returns it.  Returns nil if the insertion was
unsuccessful.

   void             push(RWCollectable* c);
This is an alternative implementation of a stack to class

Rogue Wave      Tools.h++ Class Library                  305








                      CLASS REFERENCE

RWSlistCollectablesStack.  The item pointed to by c is put at the
end of the collection.

   RWCollectable*   pop();
This is an alternative implementation of a stack to class
RWSlistCollectablesStack.  The last item in the collection is
removed and returned.  If there are no items in the collection, nil
is returned.

   virtual         RWCollectable*   remove(const RWCollectable* target);
Redefined from class RWCollection.  Removes the first item that
isEqual to the item pointed to by target and returns it.  Returns
nil if no item was found.

   virtual void     removeAndDestroy(const RWCollectable* target);
Inherited from class RWCollection.

   RWCollectable*   top() const;
This is an alternative implementation of a stack to class
RWSlistCollectablesStack.  The last item in the collection is
returned.  If there are no items in the collection, nil is returned.
























Rogue Wave      Tools.h++ Class Library                  306








                      CLASS REFERENCE



class RWOrderedIterator                        RWOrderedIterator
                                                       |
                                                   RWIterator



Synopsis  #include <ordcltn.h>

          RWOrdered a;
          RWOrderedIterator iter(a);



Descripti Iterator for class RWOrdered.  Traverses the collection from
on        the first to the last item.

Public    RWOrderedIterator(const RWOrdered& a);
construct Construct a RWOrderedIterator from a RWOrdered.
ors       Immediately after construction the position of the
          iterator is undefined.


Public    virtual                RWCollectable*      operator()();
member    Redefined from class RWIterator.  Advances the iterator to
operator  the next item and returns it. Returns nil when the end of
          the collection is reached.


Public    virtual RWCollectable*      findNext(const RWCollectable*);
member    Redefined from class RWIterator.  Moves iterator to the
functions next item which isEqual to the item pointed to by target
          and returns it.  If no item is found, returns nil and the
          position of the iterator will be undefined.

   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.


Rogue Wave      Tools.h++ Class Library                  307








                      CLASS REFERENCE



class RWpistream                             RWpistream
                                                  |
                                             RWvistream
                                                  |
                                                 ios

                                             (V2.X style
                                          iostreams, only)

Synopsis  #include <pstream.h>

          RWpistream pstr(cin);

          // Construct a RWpistream, using cin's streambuf



Descripti Class RWpistream specializes the abstract base class RWvistream
on        to restore variables stored in a portable ASCII format by
          RWpostream.
          You can think of RWpistream and RWpostream as an ASCII veneer
          over an associated streambuf which are responsbile for
          formatting variables and escaping characters such that the
          results can be interchanged between any machines.  As such,
          they are slower than their binary counterparts RWbistream and
          RWbostream which are more machine dependent.  Because
          RWpistream and RWpostream retain no information about the
          state of their associated streambufs, their use can be freely
          exchanged with other users of the streambuf (such as istream
          or ifstream).
          The restore is independent of whether the compiler is using
          AT&T V1.2 style "streams", or the newer V2.X style "iostreams"
          -- the user need not be concerned with which style is actually
          being used.  See class RWvistream for details.
          RWpistream can be interrogated as to the stream state using
          member functions good(), bad(), eof(), etc.







Rogue Wave      Tools.h++ Class Library                  308








                      CLASS REFERENCE

Example   This example assumes that V2.X style "iostreams" are being used.
          See RWpostream for an example of how to create an input stream for
          this program.
          #include <pstream.h>

          main()
          {
            // Construct a RWpistream to use standard input
            RWpistream pstr(cin);

            int i;
            float f;
            double d;

            char string[80];

            pstr >> i; // Restore an int that was stored in binary
            pstr >> f >> d;     // Restore a float & double
            pstr.getString(string, 80);  // Restore a character string
          }



Public    RWpistream(streambuf* s);
construct Initialize a RWpistream from the streambuf s.
ors

   RWpistream(istream& str);
Initialize a RWpistream using the streambuf associated with the
istream str.


Public    virtual int         get();
member    Redefined from class RWvistream.  Get and return the next
functions character 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(unsigned char& c);
Redefined from class RWvistream.  Get the next unsigned char and
store it in c.

Rogue Wave      Tools.h++ Class Library                  309








                      CLASS REFERENCE

   virtual RWvistream&    get(char* v, unsigned N);
Redefined from class RWvistream.  Get a vector of char's and store
then in the array beginning at v.  If the restore is stopped
prematurely, get stores whatever it can in v, and sets the failbit.
Note that the vector is treated as a vector of numbers, not
characters.  If you wish to restore a character string, use function
getString(char*, int).






































Rogue Wave      Tools.h++ Class Library                  310








                      CLASS REFERENCE

   virtual RWvistream&    get(double* v, unsigned N);
Redefined from class RWvistream.  Get a vector of double's and store
then in the array beginning at v.  If the restore is stopped
prematurely, get stores whatever it can in v, and sets the failbit.

   virtual RWvistream&    get(float* v, unsigned N);
Redefined from class RWvistream.  Get a vector of float's and store
then in the array beginning at v.  If the restore is stopped
prematurely, get stores whatever it can in v, and sets the failbit.

   virtual RWvistream&    get(int* v, unsigned N);
Redefined from class RWvistream.  Get a vector of int's and store
then in the array beginning at v.  If the restore is stopped
prematurely, get stores whatever it can in v, and sets the failbit.

   virtual RWvistream&    get(long* v, unsigned N);
Redefined from class RWvistream.  Get a vector of long's and store
then in the array beginning at v.  If the restore is stopped
prematurely, get stores whatever it can in v, and sets the failbit.

   virtual RWvistream&    get(short* v, unsigned N);
Redefined from class RWvistream.  Get a vector of short's and store
then in the array beginning at v.  If the restore is stopped
prematurely, get stores whatever it can in v, and sets the failbit.

   virtual RWvistream&    get(unsigned char* v, unsigned N);
Redefined from class RWvistream.  Get a vector of unsigned char's
and store then in the array beginning at v.  If the restore is
stopped prematurely, get stores whatever it can in v, and sets the
failbit.  Note that the vector is treated as a vector of numbers,
not characters.  If you wish to restore a character string, use
function getString(char*, int).

   virtual RWvistream&    get(unsigned short* v, unsigned N);
Redefined from class RWvistream.  Get a vector of unsigned short's
and store then in the array beginning at v.  If the restore is
stopped prematurely, get stores whatever it can in v, and sets the
failbit.

   virtual RWvistream&    get(unsigned int* v, unsigned N);
Redefined from class RWvistream.  Get a vector of unsigned int's and
store then in the array beginning at v.  If the restore is stopped
prematurely, get stores whatever it can in v, and sets the failbit.


Rogue Wave      Tools.h++ Class Library                  311








                      CLASS REFERENCE

   virtual RWvistream&    get(unsigned long* v, unsigned N);
Redefined from class RWvistream.  Get a vector of unsigned long's
and store then in the array beginning at v.  If the restore is
stopped prematurely, get stores whatever it can in v, and sets the
failbit.

   virtual RWvistream&    getString(char* s, unsigned 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 the latter, then the failbit
of the stream will be set.  In either case, the string will be
terminated with a null byte.  If the input stream has been
corrupted, then an exception with error CORE_SYNSTREAM will occur.

   virtual RWvistream&    operator>>(char& c);
Redefined from class RWvistream.  Get the next character from the
input stream and store it in c.

   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.



Rogue Wave      Tools.h++ Class Library                  312








                      CLASS REFERENCE

   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.


































Rogue Wave      Tools.h++ Class Library                  313








                      CLASS REFERENCE



class RWpostream                                     RWpostream
                                                         |
                                                     RWvostream
                                                         |
                                                        ios

                                            (V2.X style iostreams, only)

Synopsis  #include <pstream.h>

          // Construct a RWpostream, using cout's streambuf:
          RWBostream pstr(cout);



Descripti Class RWpostream specializes the abstract base class RWvostream
on        to store variables in a portable ASCII format.  The results can
          be restored by using its counterpart RWpistream.
          You can think of RWpistream and RWpostream as an ASCII veneer
          over an associated streambuf which are responsbile for
          formatting variables and escaping characters such that the
          results can be interchanged between any machines.  As such,
          they are slower than their binary counterparts RWbistream and
          RWbostream which are more machine dependent.  Because
          RWpistream and RWpostream retain no information about the
          state of their associated streambufs, their use can be freely
          exchanged with other users of the streambuf (such as istream
          or ifstream).
          Class RWpostream will escape any special characters such as
          tabs or newlines such that they will be read in correctly by
          RWpistream.
          Note that variables should not be separated with whitespace.
          Such whitespace would be interpreted literally and would have
          to be read back in as a character string.
          Storage is independent of whether the compiler is using AT&T
          V1.2 style "streams", or the newer V2.X style "iostreams" --
          the user need not be concerned with which style is actually
          being used.  See class RWvostream for details.
          RWpostream can be interrogated as to the stream state using
          member functions good(), bad(), eof(), etc.



Rogue Wave      Tools.h++ Class Library                  314








                      CLASS REFERENCE

Example   This example assumes that V2.X style "iostreams" are being used.
          See RWpistream for an example of how to read back in the results of
          this program.  The symbol "o" is intended to represent a control-G,
          or bell.
          #include <pstream.h>

          main()
          {
            // Construct a RWpostream to use standard output:
            RWpostream pstr(cout);

            int i = 5;
            float f = 22.1;
            double d = -0.05;

            char string[]
                    = "A string with\ttabs,\nnewlines and a o bell.";

            pstr << i; // Store an int in binary
            pstr << f << d;     // Store a float & double
            pstr << string;     // Store a string
          }

          Program output:
            5
            22.1
            -0.05
            "A string with\ttabs,\nnewlines and a \x07 bell."



Public    RWpostream(streambuf* s);
construct Initialize a RWpostream from the streambuf s.
ors

   RWpostream(ostream& str);
Initialize a RWpostream from the streambuf associated with the
output stream str.







Rogue Wave      Tools.h++ Class Library                  315








                      CLASS REFERENCE


Public    virtual RWvostream& operator<<(const char* s);
member    Redefined from class RWvostream.  Store the character string
functions starting at s to the output stream using a portable format.
          The 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 using a portable format.  Note that c is treated as a
character, not a number.

   virtual RWvostream&    operator<<(unsigned char c);
Redefined from class RWvostream.  Store the unsigned char c to the
output stream using a portable format.  Note that c is treated as a
character, not a number.

   virtual RWvostream&    operator<<(double d);
Redefined from class RWvostream.  Store the double d to the output
stream using a portable format.

   virtual RWvostream&    operator<<(float f);
Redefined from class RWvostream.  Store the float f to the output
stream using a portable format.

   virtual RWvostream&    operator<<(int i);
Redefined from class RWvostream.  Store the int i to the output
stream using a portable format.

   virtual RWvostream&    operator<<(unsigned int i);
Redefined from class RWvostream.  Store the unsigned int i to the
output stream using a portable format.

   virtual RWvostream&    operator<<(long l);
Redefined from class RWvostream.  Store the long l to the output
stream using a portable format.

   virtual RWvostream&    operator<<(unsigned long l);
Redefined from class RWvostream.  Store the unsigned long l to the
output stream using a portable format.

   virtual RWvostream&    operator<<(short s);
Redefined from class RWvostream.  Store the short s to the output
stream using a portable format.


Rogue Wave      Tools.h++ Class Library                  316








                      CLASS REFERENCE

   virtual RWvostream&    operator<<(unsigned short s);
Redefined from class RWvostream.  Store the unsigned short s to the
output stream using a portable format.

   virtual RWvostream&    put(char c);
Redefined from class RWvostream.  Store the character c to the
output stream, preserving its value using a portable format.

   virtual RWvostream&    put(unsigned char c);
Redefined from class RWvostream.  Store the character c to the
output stream, preserving its value using a portable format.

   virtual RWvostream&    put(const char* p, unsigned N);
Redefined from class RWvostream.  Store the vector of chars starting
at p to the output stream using a portable format.  The characters
should be treated as literal numbers (i.e., not as a character
string).

   virtual RWvostream&    put(const unsigned char* p, unsigned N);
Redefined from class RWvostream.  Store the vector of unsigned chars
starting at p to the output stream using a portable format.  The
characters should be treated as literal numbers (i.e., not as a
character string).

   virtual RWvostream&    put(const short* p, unsigned N);
Redefined from class RWvostream.  Store the vector of shorts
starting at p to the output stream using a portable format.

   virtual RWvostream&    put(const unsigned short* p, unsigned N);
Redefined from class RWvostream.  Store the vector of unsigned
shorts starting at p to the output stream using a portable format.

   virtual RWvostream&    put(const int* p, unsigned N);
Redefined from class RWvostream.  Store the vector of ints starting
at p to the output stream using a portable format.

   virtual RWvostream&    put(const unsigned int* p, unsigned N);
Redefined from class RWvostream.  Store the vector of unsigned ints
starting at p to the output stream using a portable format.

   virtual RWvostream&    put(const long* p, unsigned N);
Redefined from class RWvostream.  Store the vector of longs starting
at p to the output stream using a portable format.


Rogue Wave      Tools.h++ Class Library                  317








                      CLASS REFERENCE

   virtual RWvostream&    put(const unsigned long* p, unsigned N);
Redefined from class RWvostream.  Store the vector of unsigned longs
starting at p to the output stream using a portable format.

   virtual RWvostream&    put(const float* p, unsigned N);
Redefined from class RWvostream.  Store the vector of floats
starting at p to the output stream using a portable format.

   virtual RWvostream&    put(const double* p, unsigned N);
Redefined from class RWvostream.  Store the vector of doubles
starting at p to the output stream using a portable format.


































Rogue Wave      Tools.h++ Class Library                  318








                      CLASS REFERENCE



class RWRegexp





Synopsis  #include <regexp.h>

          RWRegexp re(".*\.doc");    // Matches filename with suffix ".doc"



Descripti Class RWRegexp represents a regular expression.  The constructor
on        "compiles" the expression into a form that can be used more
          efficiently.  The results can then be used for string searches
          using class RWString.
          The regular expression (RE) is constucted as follows:
          The following rules determine one-character REs that match a
          single character:
          1.1Any character that is not a special character (to be
             defined) matches itself.
          1.2A backslash (\) followed by any special character matches
             the literal character itself.  I.e., this "escapes" the
             special character.
          1.3The "special characters" are:
               +    *    ?    .    [    ]    ^    $
          1.4The period (.) matches any character except the newline.
             E.g., ".umpty" matches either "Humpty" or "Dumpty".
          1.5A set of characters enclosed in brackets ([]) is a one-
             character RE that matches any of the characters in that
             set.  E.g., "[akm]" matches either an "a", "k", or "m".  A
             range of characters can be indicated with a dash.  E.g.,
             "[a-z]" matches any lower-case letter.  However, if the
             first character of the set is the caret (^), then the RE
             matches any character except those in the set.  It does
             not match the empty string.  Example: [^akm] matches any
             character except  "a", "k", or "m".  The caret loses its
             special meaning if it is not the first character of the
             set.
          The following rules can be used to build a multicharacter RE.
          2.1A one-character RE followed by an asterisk (*) matches
             zero or more occurrences of the RE.  Hence, [a-z]* matches

Rogue Wave      Tools.h++ Class Library                  319








                      CLASS REFERENCE

             zero or more lower-case characters.
          2.2A one-character RE followed by a plus (+) matches one or
             more occurrences of the RE.  Hence, [a-z]+ matches one or
             more lower-case characters.
          2.3A question mark (?) is an optional element.  The
             preceeding RE can occur zero or once in the string -- no
             more.  E.g. xy?z matches either xyz or xz.
          2.4The concatenation of REs is a RE that matches the
             corresponding concatenation of strings.  E.g., [A-Z][a-z]*
             matches any capitalized word.
          Finally, the entire regular expression can be anchored to
          match only the beginning or end of a line:
          3.1If the caret (^) is at the beginning of the RE, then the
             matched string must be at the beginning of a line.
          3.2If the dollar sign ($) is at the end of the RE, then the
             matched string must be at the end of the line.
          The following escape codes can be used to match control
          characters:
               \b   backspace
               \e   ESC (escape)
               \f   formfeed
               \n   newline
               \r   carriage return
               \t   tab
               \xdddthe literal hex number 0xddd
               \^C  Control code.  E.g. \^D is "control-D"



















Rogue Wave      Tools.h++ Class Library                  320








                      CLASS REFERENCE

Example   #include <regexp.h>
          #include <rwstring.h>
          #include <rstream.h>

          main()
          {
            RWString aString("Hark! Hark! the lark");

            // A regular expression matching any lower-case word
            // starting with "l":
            RWRegexp reg("l[a-z]*");

            cout << aString(reg) << NL;               // Prints "lark"
          }



Public    RWRegexp(const char* pat);
construct Construct a regular expression from the pattern given by pat.
ors       The status of the results can be found by using member
          function status().

   RWRegexp(const RWRegexp& r);
Copy constructor.  Uses value semantics -- self will be a copy of r.

   ~RWRegexp();
Destructor.  Releases any allocated memory.


Assignmen RWRegexp&           operator=(const RWRegexp&);
t         Uses value semantics -- sets self to a copy of r.
operators

   RWRegexp&        operator=(const char* pat);
Recompiles self to the pattern given by pat.  The status of the
results can be found by using member function status().









Rogue Wave      Tools.h++ Class Library                  321








                      CLASS REFERENCE


Public    int         index(const RWString& str, int* len, int start=0) const;
member    Returns the index of the first instance in the string str that
functions matches the regular expression compiled in self.  The search
          starts at index start.  The length of the matching pattern is
          returned in the int pointed to by len.  If the library has
          been compiled with the DEBUG flag and an invalid regular
          expression is used for the search, an exception with error
          code TOOL_BADRE will be thrown.  Otherwise, the results are
          undefined.  Note that this member function is relatively
          clumsy to use -- class RWString offers a better interface to
          regular expression searches.

   statVal  status();
Returns the status of the regular expression:

               statVal             Meaning
               RWRegexp::OK        No errors
               RWRegexp::ILLEG     Pattern was illegal
               AL
               RWRegexp::TOOLO     Pattern exceeded
               NG                  maximum length























Rogue Wave      Tools.h++ Class Library                  322








                      CLASS REFERENCE



class RWSequenceable                                          RWSequenceable
                                                                    |
                                                               RWCollection
                                                                    |
                                                              RWCollectable


Synopsis  #include <seqcltn.h>

        typedef RWSequenceable SequenceableCollection;    // Smalltalk typedef



Descripti Class RWSequenceable is an abstract base class for collections that
on        can be accessed via an index.  It inherits class RWCollection as a
          public base class and adds a few extra virtual functions.  This
          documentation only describes these extra functions.

Public    RWCollectable*          append(RWCollectable*) = 0;
member    Adds the item to the end of the collection and returns it.  Returns
functions nil if the insertion was unsuccessful.

   virtual RWCollectable*&at(int i);
Allows access to the i'th element of the collection.  If i is out of
range then an exception with error TOOL_INDEX will occur.  This
variant can be used as an lvalue.

   virtual const RWCollectable                       *  at(int i) const;
Allows access to the i'th element of the collection.  If i is out of
range then nil is returned.

   virtual         RWCollectable*   first() const = 0;
Returns the first item in the collection.

   virtual         int        index(const RWCollectable* c) const = 0;
Returns the index number of the first item that "matches" the item
pointed to by c.  If there is no such item, returns _1.  For most
collections, an item "matches" the target if either isEqual() or
compareTo() find equivalence, whichever is appropriate for the
actual collection type.



Rogue Wave      Tools.h++ Class Library                  323








                      CLASS REFERENCE

   virtual         RWCollectable*   insertAfter(int i, RWCollectable* c) = 0;
Inserts and returns the object pointed to by c after the item at
index i.  Returns nil if the insertion was unsuccessful.

   virtual         RWCollectable*   last() const = 0;
Returns the last item in the collection.

   RWCollectable*   prepend(RWCollectable*) = 0;
Adds the item to the beginning of the collection and returns it.
Returns nil if the insertion was unsuccessful.



































Rogue Wave      Tools.h++ Class Library                  324








                      CLASS REFERENCE



class RWSet                                           RWSet
                                                        |
                                                   RWCollection
                                                        |
                                                  RWCollectable

Synopsis  typedef RWSet Set;         // Smalltalk typedef.
          #include <rwset.h>

          RWSet h;



Descripti Class RWSet represents a group of unordered elements, not
on        accessible by an external key, where duplicates are not allowed.
          It corresponds to the Smalltalk class Set.
          An object stored by RWSet 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.
          An item c is considered to be "already in the collection" if
          there is a member of the collection for which isEqual(c)
          returns TRUE.  In this case, the message insert(c) will not
          add it, thus insuring that there are no duplicates.
          The iterator for this class is RWSetIterator.

Public    RWSet (unsigned n = 101);
construct An empty hash table is constructed with a size that is the
ors       next highest prime number that is greater than or equal to
          n.

   RWSet (const RWSet & h);
Copy constructor.  Makes a shallow copy of the collection h.

   virtual          ~RWSet();
Calls clear().






Rogue Wave      Tools.h++ Class Library                  325








                      CLASS REFERENCE


Public    void                operator=(const RWSet& h);
member    Assignment operator.  Makes a shallow copy of the collection h.
operators
          RWBoolean           operator==(const RWSet& h);
          Returns TRUE if self and a have the same number of elements and
          if for every key in self there is a corresponding key in h which
          isEqual.

   RWBoolean        operator!=(const RWSet& h);
Returns the negation of operator==(), above.

   RWBoolean        operator<=(const RWSet& h);
Returns TRUE  if self is a subset of h, that is, every element of
self has a counterpart in h which isEqual.


Public    virtual void        apply(applyCollectable ap, void*)
member    Redefined from class RWCollection to apply the user-supplied
functions function pointed to by ap to each member of the collection in a
          (generally) unpredictable order.  This supplied function should
          not do anything to the items that could change the ordering of
          the collection.

   virtual unsigned 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 unsigned entries() const;
Redefined from class RWCollection.

   virtual         RWCollectable*   find(const RWCollectable* target) const;
Redefined from class RWCollection.  Returns the item in self which

Rogue Wave      Tools.h++ Class Library                  326








                      CLASS REFERENCE

isEqual to the item pointed to by target 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.  Adds c to the collection and
returns it.  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.

   virtual ClassID  isA() const;
Redefined from class RWCollectable to return __RWSET.

   virtual RWBoolean      isEmpty() const;
Redefined from class RWCollection.

   virtual RWBoolean      isEqual(const RWCollectable* a) const;
Inherited from class RWCollectable.

   virtual unsigned occurrencesOf(const RWCollectable* target) const;
Redefined from class RWCollection.  Returns the number of entries
that isEqual to the item pointed to by target.  Because duplicates
are not allowed for this collection, only 0 or 1 can be returned.

   virtual         RWCollectable*   remove(const RWCollectable* target);
Redefined from class RWCollection.  Returns and removes the item
that isEqual to the item pointed to by target, or nil if there is no
item.

   virtual         void       removeAndDestroy(const RWCollectable* target);
Inherited from class RWCollection.

   void             resize(unsigned n = 0);
Resizes the internal hashing table to the next highest prime number
that is greater than or equal to n.  If n==0, then the next highest
prime number greater than or equal to the present size.

   virtual void     restoreGuts(RWvistream&);
   virtual void     restoreGuts(RWFile&);
   virtual void     saveGuts(RWvostream&) const;
   virtual void     saveGuts(RWFile&) const;
Inherited from class RWCollection.

Rogue Wave      Tools.h++ Class Library                  327








                      CLASS REFERENCE

   static        RWCollectable*    restoreFrom(RWvistream&);
   static        RWCollectable*    restoreFrom(RWFile&);
   void             saveOn(RWvostream&) const;
   void             saveOn(RWFile&) const;
Inherited from class RWCollectable.








































Rogue Wave      Tools.h++ Class Library                  328








                      CLASS REFERENCE



class RWSetIterator                         RWSetIterator
                                                  |
                                             RWIterator



Synopsis  #include <rwset.h>
          RWSet h;
          RWSetIterator it(h);



Descripti Iterator for class RWSet, which allows sequential access to all
on        the elements of RWSet.  Note that because a RWSet is unordered,
          elements are not accessed in any particular order.

Public    RWSetIterator(RWSet&);
construct Construct an iterator for an RWSet.  After construction, the
or        position of the iterator is undefined.


Public    virtual                RWCollectable*      operator()();
member    Redefined from class RWIterator.  Advances the iterator to the
operator  next item and returns it. Returns nil when the end of the
          collection is reached.


Public    virtual RWCollectable*      findNext(const RWCollectable* target);
member    Redefined from class RWIterator.  Moves iterator to the next
functions item which isEqual to the item 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.

   RWCollectable*   remove();
Remove the item at the current iterator position from the
collection.



Rogue Wave      Tools.h++ Class Library                  329








                      CLASS REFERENCE

   RWCollectable*   removeNext(const RWCollectable*);
Moves the iterator to the next item which isEqual to the item
pointed to by target, removes it from the collection 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         void       reset();
Redefined from class RWIterator.  Resets the iterator to its
starting state.




































Rogue Wave      Tools.h++ Class Library                  330








                      CLASS REFERENCE



class RWSlistCollectables                  RWSlistCollectables
                                             |         |
                                        RWSequenceableRWSlist
                                             |
                                        RWCollection
                                             |
                                        RWCollectable


Synopsis  typedef RWSlistCollectables LinkedList;

          // Smalltalk typedef

          #include <slistcol.h>
          RWSlistCollectables a;



Descripti Class RWSlistCollectables represents a group of ordered elements,
on        without keyed access.  Duplicates are allowed.   The ordering of
          elements is determined externally, by the order of insertion and
          removal.  An object stored by RWSlistCollectables must inherit
          abstract base class RWCollectable.
          The virtual function isEqual() (see class RWCollectable) is
          required to find a match between a target and an item in the
          collection
          Class RWSlistCollectables is implemented as a singly-linked
          list, which allows for efficient insertion and removal, but
          efficient movement in only one direction.  This class
          corresponds to the Smalltalk class LinkedList.

Public    RWSlistCollectables();
construct Constructs an empty linked list.
ors

   RWSlistCollectables(const RWCollectable* a);
Constructs an ordered collection with single item a.






Rogue Wave      Tools.h++ Class Library                  331








                      CLASS REFERENCE


Public    RWBoolean           operator==(const RWSlistCollectables& s) const;
member    Returns TRUE if self and s have the same number of members and
operators if for every item in self, the corresponding item at the same
          index in s isEqual to it.


Public    virtual                RWCollectable*      append(RWCollectable*);
member    Redefined from RWSequenceable.  Inserts the item at the end of
functions the collection and returns it.  Returns nil if the insertion was
          unsuccesful.

   virtual void     apply(applyCollectable ap, void*)
Redefined from class RWCollection.    This function has been
redefined to apply the user-defined function pointed to by ap to
each member of the collection, in order, from first to last.

   virtual RWCollectable*&at(int i);
   virtual const RWCollectable*                          at(int i) const;
Redefined from class RWSequenceable.  Note that for a linked-list,
these functions must traverse all the links, making them not
particularly efficient.

   virtual unsigned binaryStoreSize() const;
Inherited from class RWCollection.

   virtual void     clear();
Redefined from class RWCollection.

   virtual void     clearAndDestroy();
Inherited from class RWCollection.

   virtual int      compareTo(const RWCollectable* a) const;
Inherited from class RWCollectable.

   virtual RWBoolean      contains(const RWCollectable* target) const;
Inherited from class RWCollection.

   RWBoolean        containsReference(const RWCollectable* e) const;
Returns true if the list contains an item that is identical to the
item pointed to by e (that is, that has the address e).

   virtual unsigned entries() const;
Redefined from class RWCollection.

Rogue Wave      Tools.h++ Class Library                  332








                      CLASS REFERENCE

   virtual         RWCollectable*   find(const RWCollectable* target) const;
Redefined from class RWCollection.  The first item that matches
target is returned, or nil if no item was found.

   RWCollectable*   findReference(const RWCollectable* e) const;
Returns the first item that is identical to the item pointed to by e
(that is, that has the address e), or nil if none is found.

   virtual         RWCollectable*   first() const;
Redefined from class RWSequenceable.  Returns the item at the
beginning of the list.

   RWCollectable*   get();
Returns and removes the item at the beginning of the list.

   virtual unsigned hash() const;
Inherited from class RWCollectable.

   virtual int      index(const RWCollectable* c) const = 0;
Redefined from class RWSequenceable.  Returns the index of the first
item that isEqual to the item pointed to by c.

   virtual         RWCollectable*   insert(RWCollectable* c);
Redefined from class RWCollection.  Adds the item to the end of the
collection and returns it.  Returns nil if the insertion was
unsuccessful.

   virtual         RWCollectable*   insertAfter(int i, RWCollectable* c);
Redefined from class RWSequenceable.  Inserts and returns the object
pointed to by c after the item at index i.  Returns nil if the
insertion was unsuccessful.

   virtual         ClassID    isA() const;
Redefined from class RWCollectable to return __RWSLISTCOLLECTABLES.

   virtual         RWBoolean  isEmpty() const;
Redefined from class RWCollection.

   virtual         RWCollectable*   last() const;
Redefined from class RWSequenceable.  Returns the value at the end
of the collection.

   virtual        unsigned   occurrencesOf(const RWCollectable* target) const;
Redefined from class RWCollection.  Returns the number of items that

Rogue Wave      Tools.h++ Class Library                  333








                      CLASS REFERENCE

isEqual to the item pointed to by target.

   unsigned    occurrencesOfReference(const RWCollectable* e) const;
Returns the number of items that are identical to the item pointed
to by e (that is, that have the address e).

   virtual         RWCollectable*   prepend(RWCollectable*);
Redefined from class RWSequenceable.  Adds the item to the beginning
of the collection and returns it.  Returns nil if the insertion was
unsuccessful.

   virtual         RWCollectable*   remove(const RWCollectable* target);
Redefined from class RWCollection.  Removes and returns the first
item that isEqual to the item pointed to by target.  Returns nil if
there is no such item.

   virtual void     removeAndDestroy(const RWCollectable* target);
Inherited from class RWCollection.

   RWCollectable*   removeReference(const RWCollectable* e);
Removes and returns the first item that is identical to the item
pointed to by e (that is, that has the address e).  Returns nil if
there is no such item.






















Rogue Wave      Tools.h++ Class Library                  334








                      CLASS REFERENCE

   virtual void     restoreGuts(RWvistream&);
   virtual void     restoreGuts(RWFile&);
   virtual void     saveGuts(RWvostream&) const;
   virtual void     saveGuts(RWFile&) const;
Inherited from class RWCollection.

   static        RWCollectable*    restoreFrom(RWvistream&);
   static        RWCollectable*    restoreFrom(RWFile&);
   void             saveOn(RWvostream&) const;
   void             saveOn(RWFile&) const;
Inherited from class RWCollectable.


































Rogue Wave      Tools.h++ Class Library                  335








                      CLASS REFERENCE



class RWSlistCollectablesIterator     RWSlistCollectablesIterator
                                          |            |
                                       RWIteratorRWSlistIterator



Synopsis  // Smalltalk typedef.
          typedef RWSlistCollectablesIterator     LinkedListIterator;

          #include <slistcol.h>

          RWSlistCollectables sc;
          RWSlistCollectablesIterator sci(sc);



Descripti Iterator for class RWSlistCollectables. Traverses the linked-list
on        from the first to last item.

Public    RWSlistCollectablesIterator (RWSlistCollectables&);
construct Constructs an iterator from a singly-linked list.  Immediately
or        after construction, the iterator is positioned at the last link.


Public    virtual                RWCollectable*      operator()();
member    Redefined from class RWIterator.  Advances the iterator to the
operators next element and returns it. Returns nil when the end of the
          collection is reached.

   void             operator++();
Advances the iterator one item.  This operator wraps around to the
beginning of the list.

   void             operator+=(int n);
Advances the iterator n items.  This operator wraps around to the
beginning of the list.







Rogue Wave      Tools.h++ Class Library                  336








                      CLASS REFERENCE


Public    RWBoolean           atFirst() const;
member    Returns TRUE if the iterator is at the beginning of the list,
functions otherwise FALSE;

          RWBoolean           atLast() const;
          Returns TRUE if the iterator is at the end of the list,
          otherwise FALSE;

   virtual         RWCollectable*   findNext(const RWCollectable* target);
Redefined from class RWIterator.  Moves iterator to the next item
which isEqual to the item pointed to by target and returns it.  If
no item is found, returns nil and the position of the iterator will
be undefined.

   RWCollectable*   findNextReference(const RWCollectable* e);
Moves iterator to the next item which is identical to the item
pointed to by e (that is, that has address e) and returns it.  If no
item is found, returns nil and the position of the iterator will be
undefined.

   RWCollectable*   insertAfterPoint(RWCollectable* a);
Insert item a after the current cursor position and return the item.
The cursor's position will be unchanged.

   virtual         RWCollectable*   key() const;
Redefined from class RWIterator.  Returns the item at the current
iterator position.

   RWCollectable*   remove();
Removes and returns the item at the current cursor position.
Afterwards, the iterator will be positioned at the next item in the
list.

   RWCollectable*   removeNext(const RWCollectable* target);
Moves iterator to the next item in the list which isEqual to the
item pointed to by target, removes it from the list and returns it.
Afterwards, the iterator will be positioned at the next item in the
list.  If no item is found, returns nil and the position of the
iterator will be undefined.

   RWCollectable*   removeNextReference(const RWCollectable* e);
Moves iterator to the next item in the list which is identical to
the item pointed to by e (that is, that has address e), removes it

Rogue Wave      Tools.h++ Class Library                  337








                      CLASS REFERENCE

from the list and returns it.  Afterwards, the iterator will be
positioned at the next item in the list.  If no item is found,
returns nil and the position of the iterator will be undefined.

   virtual void     reset();
Redefined from class RWIterator.  Resets the iterator.  Iterator
will be positioned at the last item in the list.

   void             toFirst();
Moves the iterator to the beginning of the list.

   void             toLast();
Moves the iterator to the end of the list.
































Rogue Wave      Tools.h++ Class Library                  338








                      CLASS REFERENCE



class RWSlistCollectablesQueue        RWSlistCollectablesQueue
                                                 |
                                         RWSlistCollectables
                                           |           |
                                      RWSequenceableRWSlist
                                           |
                                      RWCollection
                                           |
                                      RWCollectable

Synopsis  // Smalltalk typedef:
          typedef RWSlistCollectablesQueue   Queue;

          #include <queuecol.h>
          RWSlistCollectablesQueue a;



Descripti Class RWSlistCollectablesQueue represents a restricted interface
on        to class RWSlistCollectables to implement a first in first out
          (FIFO) queue.  A Queue is a sequential list for which all
          insertions are made at one end (the "tail"), but all removals
          are made at the other end (the "head").  Hence, the ordering is
          determined externally by the ordering of the insertions.
          Duplicates are allowed.
          An object stored by RWSlistCollectablesQueue must inherit
          abstract base class RWCollectable.  The virtual function
          isEqual() (see class RWCollectable) is required to find a
          match between a target and an item in the queue.
          This class corresponds to the Smalltalk class Queue.

Public    RWSlistCollectablesQueue();
construct Construct an empty queue.
ors

   RWSlistCollectablesQueue(RWCollectable* a);
Construct an queue with single item a.

   RWSlistCollectablesQueue(const RWSlistCollectablesQueue & q);
Copy constructor.  A shallow copy of the queue q is made.



Rogue Wave      Tools.h++ Class Library                  339








                      CLASS REFERENCE


Public    void                operator=(const RWSlistCollectablesQueue & q);
member    Assignment operator.  A shallow copy of the queue q is made.
operators


Public    virtual void          apply(applyCollectable ap, void*)
member    Inherited from class RWSlistCollectables.
functions
          virtual                RWCollectable*      append(RWCollectable*);
          Inherited from class RWSlistCollectables.  Adds an element to
          the end of the queue.

   virtual         unsigned   binaryStoreSize() const;
Inherited from class RWCollection.

   virtual void     clear();
Inherited from class RWSlistCollectables.

   virtual void     clearAndDestroy();
   virtual RWBoolean      contains(const RWCollectable* target) const;
Inherited from class RWCollection.

   RWBoolean        containsReference(const RWCollectable* e) const;
   virtual unsigned entries() const;
Inherited from class RWSlistCollectables.

   virtual         RWCollectable*   first() const;
Inherited from class RWSlistCollectables.  Returns the item at the
beginning of the queue (i.e., the least recently inserted item).
Returns nil if the queue is empty.

   RWCollectable*   get();
Inherited from class RWSlistCollectables.  Returns and removes the
item at the beginning of the queue (i.e., the least recently
inserted item).  Returns nil if the queue is empty.

   virtual         RWCollectable*   insert(RWCollectable* c);
Redefined from class RWSlistCollectables to call append().

   virtual ClassID  isA() const;
Redefined from class RWCollectable to return
__RWSLISTCOLLECTABLESQUEUE.


Rogue Wave      Tools.h++ Class Library                  340








                      CLASS REFERENCE

   virtual RWBoolean      isEmpty() const;
Inherited from class RWSlistCollectables.

   virtual         RWCollectable*   last() const;
Inherited from class RWSlistCollectables.  Returns the last item in
the queue (the most recently inserted item).

   virtual unsigned occurrencesOf(const RWCollectable* target) const;
   unsigned   occurrencesOfReference(const RWCollectable* e) const;
Inherited from class RWSlistCollectables.

   virtual         RWCollectable*   remove(const RWCollectable*);
Redefined from class RWSlistCollectables.  Calls get().  The
argument is ignored.































Rogue Wave      Tools.h++ Class Library                  341








                      CLASS REFERENCE



class RWSlistCollectablesStack          RWSlistCollectablesStack
                                                    |
                                         RWSlistCollectables
                                             |          |
                                        RWSequenceable RWSlist
                                             |
                                        RWCollection
                                             |
                                        RWCollectable

Synopsis  // Smalltalk typedef:
          typedef RWSlistCollectablesStack   Stack;

          #include <stackcol.h>
          RWSlistCollectablesStack a;



Descripti Class RWSlistCollectablesStack represents a restricted
on        interface to class RWSlistCollectables to implement a last in
          first out (LIFO) stack.  A Stack is a sequential list for
          which all insertions and deletions are made at one end (the
          beginning of the list).  Hence, the ordering is determined
          externally by the ordering of the insertions.  Duplicates are
          allowed.
          An object stored by RWSlistCollectablesStack must inherit
          abstract base class RWCollectable.  The virtual function
          isEqual() (see class RWCollectable) is required to find a
          match between a target and an item in the stack.
          This class corresponds to the Smalltalk class Stack.

Public    RWSlistCollectablesStack();
construct Construct an empty stack.
ors

   RWSlistCollectablesStack(RWCollectable* a);
Construct a stack with one entry a.

   RWSlistCollectablesStack(const RWSlistCollectablesStack& s);
Copy constructor.  A shallow copy of the stack s is made.



Rogue Wave      Tools.h++ Class Library                  342








                      CLASS REFERENCE


Assignmen void                operator=(const RWSlistCollectablesStack& s);
t         Assignment operator.  A shallow copy of the stack s is made.
operator


Public    virtual void        applyCollectable ap, void*)
member    virtual unsigned    binaryStoreSize() const;
functions virtual void        clear();
          Inherited from class RWSlistCollectables.

   virtual void     clearAndDestroy();
   virtual RWBoolean      contains(const RWCollectable* target) const;
Inherited from class RWCollection.

   RWBoolean        containsReference(const RWCollectable* e) const;
   virtual unsigned entries() const;
Inherited from class RWSlistCollectables.

   virtual         RWCollectable*   first() const;
Inherited from class RWSlistCollectables.  Same as top().

   virtual         RWCollectable*   insert(RWCollectable* c);
Inherited from class RWSlistCollectables.  Same as push().

   virtual ClassID  isA() const;
Redefined from class RWCollectable to return
__RWSLISTCOLLECTABLESSTACK.

   virtual RWBoolean      isEmpty()const;
Inherited from class RWSlistCollectables.

   virtual         RWCollectable*   last() const;
Inherited from class RWSlistCollectables.  Returns the item at the
bottom of the stack.

   virtual unsigned occurrencesOf(const RWCollectable* target) const;
   unsigned   occurrencesOfReference(const RWCollectable* e) const;
Inherited from class RWSlistCollectables.

   virtual RWCollectable* remove(const RWCollectable*);
Redefined from class RWSlistCollectables.  Calls pop().  The
argument is ignored.


Rogue Wave      Tools.h++ Class Library                  343








                      CLASS REFERENCE

   RWCollectable*   pop();
Removes and returns the item at the top of the stack, or returns nil
if the stack is empty.

   void             push(RWCollectable*);
Adds an item to the top of the stack.

   RWCollectable*   top() const;
Returns the item at the top of the stack or nil if the stack is
empty.



































Rogue Wave      Tools.h++ Class Library                  344








                      CLASS REFERENCE



class RWSortedVector                       RWSortedVector
                                                  |
                                              RWOrdered
                                                  |
                                           RWSequenceable
                                                  |
                                            RWCollection
                                                  |
                                            RWCollectable

Synopsis  #include <sortvec.h>

          RWSortedVector a;



Descripti Class RWSortedVector represents a group of ordered items,
on        internally sorted by the compareTo() function and accessible by
          an index number.  Duplicates are allowed.  An object stored by
          RWSortedVector must inherit from the abstract base class
          RWCollectable.  An insertion sort is used to maintain the vector
          in sorted order.
          Because class RWSortedVector is implemented as a vector of
          pointers, traversing the collection is more efficient than
          with class RWBinaryTree.  However, insertions are slower in
          the center of the collection.

















Rogue Wave      Tools.h++ Class Library                  345








                      CLASS REFERENCE

Example   #include <sortvec.h>
          #include <collstr.h>
          #include <rstream.h>

          main()
          {
            RWSortedVector sv;

            sv.insert(new RWCollectableString("dog"));
            sv.insert(new RWCollectableString("cat"));
            sv.insert(new RWCollectableString("fish"));

            RWSortedVectorIterator next(sv);
            RWCollectableString* item;

            while( item = (RWCollectableString*)next() )
              cout << *item << NL;

            sv.clearAndDestroy();

          }
























Rogue Wave      Tools.h++ Class Library                  346








                      CLASS REFERENCE

          Program output:
          cat
          dog
          fish


Public    RWSortedVector(int size = 101);
constructoConstruct an empty RWSortedVector that has an initial capacity
rs        of size items.  The capacity will be increased automatically if
          excess items are inserted into the collection.


Public    RWBoolean           operator==(const RWSortedVector& sv) const;
member    Returns TRUE if for every item in self, the corresponding item
operators in sv at the same index is equal.  The two collections must
          also have the same number of members.

   const RWCollectable*   operator[](int i);
Returns the i'th element in the collection.  If i is out of range,
an exception will occur with error TOOL_INDEX.  This function cannot
be used as an lvalue.

   const RWCollectable*   operator()(int i);
Returns the i'th element in the collection.  Bounds checking is
enabled by defining the preprocessor directive BOUNDS_CHECK before
including the header file sortvec.h.  In this case, if i is out of
range, an exception will occur with error TOOL_INDEX.  This function
cannot be used as an lvalue.


Public    virtual void        apply(applyCollectable ap, void* x);
member    Inherited from class RWOrdered.
functions
          virtual const RWCollectable*    at(int i) const;
          Inherited from class RWOrdered.

   virtual unsigned binaryStoreSize() const;
Inherited from class RWCollection.

   virtual void     clear();
Inherited from class RWOrdered.

   virtual void     clearAndDestroy();
Inherited from class RWCollection.

Rogue Wave      Tools.h++ Class Library                  347








                      CLASS REFERENCE

   virtual int      compareTo(const RWCollectable* a) const;
Inherited from class RWCollectable.

   virtual RWBoolean      contains(const RWCollectable* target) const;
Inherited from class RWCollection.

   virtual unsigned entries() const;
Inherited from class RWOrdered.

   virtual         RWCollectable*   find(const RWCollectable* target) const;
Inherited from class RWOrdered.  Note that RWOrdered::find() uses
the virtual function index() to perform its search.  Hence, a binary
search will be used.

   virtual         RWCollectable*   first() const;
Inherited from class RWOrdered.

   virtual unsigned hash() const;
Inherited from class RWCollectable.

   virtual int      index(const RWCollectable*) const;
Redefined from class RWOrdered.  Performs a binary search to return
the index of the first item that compares equal to the target item,
or _1 if no such item can be found.

   virtual         RWCollectable*   insert(RWCollectable* c);
Redefined from class RWOrdered.  Performs a binary search to insert
the item pointed to by c after all items that compare less than or
equal to it, but before all items that compare greater than it.
Returns nil if the insertion was unsuccessful, c otherwise.

   virtual ClassID  isA() const;
Redefined from class RWCollectable to return __RWSORTEDVECTOR.

   virtual RWBoolean      isEmpty() const;
Inherited from class RWOrdered.

   virtual RWBoolean      isEqual(const RWCollectable* a) const;
Inherited from class RWCollectable.

   virtual         RWCollectable*   last() const;
Inherited from class RWOrdered.



Rogue Wave      Tools.h++ Class Library                  348








                      CLASS REFERENCE

   virtual unsigned occurrencesOf(const RWCollectable* target) const;
Redefined from class RWOrdered.  Returns the number of items that
compare equal to the item pointed to by target.

   virtual         RWCollectable*   remove(const RWCollectable* target);
Inherited from class RWOrdered.  Note that RWOrdered::remove() uses
the virtual function index() to perform its search.  Hence, a binary
search will be used.

   virtual void     removeAndDestroy(const RWCollectable* target);
Inherited from class RWCollection.


































Rogue Wave      Tools.h++ Class Library                  349








                      CLASS REFERENCE



class RWString





Synopsis  #include <rwstring.h>
          RWString a;



Descripti The RWString class is designed to support string manipulations
on        and processing that are more convenient than the standard C
          <string.h> functions.
          A separate RWSubString class supports substring extraction and
          modification operations.
          Note that if compilers implemented type conversion correctly,
          some of the operators below would not be necessary.
          Experience has proven otherwise.

Example   #include <rwstring.h>
          #include <regexp.h>
          #include <rstream.h>

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

            RWRegexp re("[A-Z][a-z]*town");  // Any capitalized "town"

            a(re) = "Redmond";

            cout << a << NL;

          }

          Program output:
                       There is no joy in Redmond.





Rogue Wave      Tools.h++ Class Library                  350








                      CLASS REFERENCE

Public    RWString();
construct Constructs a RWString with zero characters (the null string).
ors

   RWString(const char* c);
Conversion from character string.  The array pointed to by c should
be null terminated.  The created string will copy the data pointed
to by c.

   RWString(const char* c, int N);
Construct a string from the (possibly) null terminated character
string c.  The created string will copy the data pointed to by c.
At most N characters (not including the terminating null) will be
copied.

   RWString(const RWString& s);
Copy constructor.  The created string will reference s's data.  That
is, a shallow copy of s will be made.

   RWString(const RWSubString& ss);
Conversion from sub-string.  The created string will copy the
substring represented by ss.

   RWString(unsigned N, char c = ' ');
Constructs a RWString with N characters (default blanks).


Type      operator            const char*() const;
conversio Returns self as a null-terminated string.
n


Assignmen RWString&           operator=(const RWString& str);
t         Assignment operator.  The string will reference s's data.
operators That is, a shallow copy is made.

   RWString&        operator+=(const RWString& str);
Append the string str to self.

   RWString&        operator+=(const char* s);
Append the character string pointed to by s to self.




Rogue Wave      Tools.h++ Class Library                  351








                      CLASS REFERENCE


Indexing  char&               operator[](int i);
operators Return the i'th character.  The result can be used as an
          lvalue.  The index i must be between 0 and the length of the
          string less one.  Bounds checking is performed -- if the index
          is out of range then an exception with error TOOL_INDEX will
          occur.

   char             operator[](int i) const;
Return the i'th character.  The index i must be between 0 and the
length of the string less one.  Bounds checking is performed -- if
the index is out of range then an exception with error TOOL_INDEX
will occur.

   char&            operator()(int);
Return the i'th character.  The result can be used as an lvalue.
The index i must be between 0 and the length of the string less one.
Bounds checking is performed if the pre-processor macro BOUNDS_CHECK
has been defined before including rwstring.h.  In this case, if the
index is out of range, then an exception with error TOOL_INDEX will
occur.

   char             operator()(int) const;
Return the i'th character.  The index i must be between 0 and the
length of the string less one.  Bounds checking is performed if the
pre-processor macro BOUNDS_CHECK has been defined before including
rwstring.h.  In this case, if the index is out of range, then an
exception with error TOOL_INDEX will occur.

   RWSubString      operator()(int start, unsigned len);
Substring operator.  Returns a RWSubString of self with length len,
starting at index start.  The results can be used as an lvalue.  If
the library was built using the DEBUG flag, and start and len are
out of range, then an exception will occur with error
TOOL_SUBSTRING.

   const RWSubString      operator()(int start, unsigned len) const;
Returns a RWSubString of self with length len, starting at index
start.  The results cannot be used as an lvalue.  If the library was
built using the DEBUG flag, and start and len are out of range, then
an exception will occur with error TOOL_SUBSTRING.

   RWSubString      operator()(const RWRegexp& re, int start=0);
Returns the first substring starting after index start that matches

Rogue Wave      Tools.h++ Class Library                  352








                      CLASS REFERENCE

the regular expression re.  If there is no such substring, then the
null substring is returned.  The results can be used as an lvalue.

   const RWSubString      operator()(const RWRegexp& re, int start=0) const;
Returns the first substring starting after index start that matches
the regular expression re.  If there is no such substring, then the
null substring is returned.  The results cannot be used as an
lvalue.


Logical   RWBoolean           operator==(const char*) const;
operators RWBoolean           operator!=(const char*) const;
          RWBoolean           operator==(const RWString&) const;
          RWBoolean           operator!=(const RWString&) const;
          Logical equality and inequality.  Case sensitivity is set by
          the static member function setCaseSensitive().

   RWBoolean        operator>(const char*) const;
   RWBoolean        operator<(const char*) const;
   RWBoolean        operator>=(const char*) const;
   RWBoolean        operator<=(const char*) const;
   RWBoolean        operator>(const RWString&) const;
   RWBoolean        operator<(const RWString&) const;
   RWBoolean        operator>=(const RWString&) const;
   RWBoolean        operator<=(const RWString&) const;
Other logical operators.  Comparisons are done lexicographically.
Case sensitivity is set by the static member function
setCaseSensitive().


Public    unsigned            binaryStoreSize() const;
member    Returns the number of bytes necessary to store the object using
functions RWString::saveOn(RWFile&).

   int              compareTo(const RWString& str) const;
Returns an int less than, greater than, or equal to zero depending
on whether self is less than, greater than, or equal to the string
str.  The comparisons are done lexicographically.  Case sensitivity
is set by the static member function setCaseSensitive().

   RWBoolean        contains(const char* c) const;
Pattern matching.  Returns TRUE if the string pointed to by c occurs
in self.  Case sensitivity is set by the static member function
setCaseSensitive().

Rogue Wave      Tools.h++ Class Library                  353








                      CLASS REFERENCE

   RWBoolean        contains(const RWString& str) const;
Pattern matching.  Returns TRUE if str occurs in RWString.  Case
sensitivity is set by the static member function setCaseSensitive().

   RWString         copy() const;
Returns a distinct deep copy of self.

   const char*      data() const;
Access to the RWString's data as a null terminated string.  Must be
used with care.

   int              first(char) const;
Returns the index of the first occurence of the character c in self.
Returns _1 if there is no such character.

   unsigned         hash() const;
Returns a suitable hash value.

   int              index(const char* c, int i=0) const;
Pattern matching.  Returns the index greater than or equal to i of
the start of the first occurrence of the string pointed to by c in
self.  Returns -1 if there is no such pattern.  Case sensitivity is
set by the static member function setCaseSensitive().  The pattern
matching is done by computing a hash value for the string pointed to
by c using what is effectively a very large hash table and then
comparing it against hash values computed from self.  The table is
so large that it is very unlikely that two different patterns would
hash to the same value.  Nevertheless, a final string comparison can
be made by calling the static member function setParanoidCheck()
with argument TRUE.

   int              index(const RWString& str, int i=0) const;
Pattern matching.  Returns the index greater than or equal to i of
the start of the first occurrence of str in self.  Returns -1 if
there is no such pattern.  Case sensitivity is set by the static
member function setCaseSensitive().  See additional comments above
on final string comparisons.

   int    index(const RWRegexp& re, int i=0) const;
Regular expression matching.  Returns the index greater than or
equal to i of the start of the first pattern that matches the
regular expression re.  Returns _1 if there is no such pattern.



Rogue Wave      Tools.h++ Class Library                  354








                      CLASS REFERENCE

   int    index(const RWRegexp& re, int* ext, int i=0) const;
Regular expression matching.  Returns the index greater than or
equal to i of the start of the first pattern that matches the
regular expression re.  Returns _1 if there is no such pattern.  The
length of the matching pattern is returned in the integer pointed to
by ext.

   RWBoolean        isNull() const;
Returns TRUE if this is a zero lengthed string (i.e., the null
string).

   int              last(char c) const;
Returns the index of the last occurrence in the string of the
character c.  Returns _1 if there is no such character.

   unsigned         length() const;
Returns the number of characters in self.

   RWString&        prepend(const char*);
Prepends the string pointed to by c to self.

   RWString&        prepend(const RWString& str);
Prepends the string str to self.

   istream&         readFile(istream& s);
Reads an entire file into self from the input stream s, replacing
the previous contents of self.  Reads to EOF.

   istream&         readLine(istream& s);
If skipWhitespace() is TRUE (the default), then whitespace is
skipped before saving characters. Characters are then read from the
input stream s until a newline is encountered. The newline is
removed from the input stream but is not stored.

   istream&         readToken(istream& s);
Whitespace is skipped before saving characters. Characters are then
read from the input stream s until whitespace is encountered. The
whitespace is left on the input stream.

   void             resize(unsigned n);
Changes the length of self, adding blanks or truncating as
necessary.



Rogue Wave      Tools.h++ Class Library                  355








                      CLASS REFERENCE

   void             restoreFrom(RWvistream& s);
Reads an RWString from the input stream s that had been stored using
saveOn(RWvostream&).

   void             restoreFrom(RWFile& f);
Reads an RWString from the RWFile f that had been stored using
storeOn(RWFile&).

   void             saveOn(RWvostream& s) const;
Stores an RWString on the output stream s.

   void             saveOn(RWFile& f) const;
Stores an RWString in binary format on the RWFile f.

   RWSubString      strip(stripType s = trailing, char c = ' ');
Returns a substring of self where the character c has been stripped
off the beginning, end, or both ends of the string.  The enum
stripType can take values:

               stripType      Meaning
               leading        Remove characters at beginning
               trailing       Remove characters at end
               both           Remove characters at both ends

   void             toLower();
Changes all upper-case letters in self to lower-case.

   void             toUpper();
Changes all lower-case letters in self to upper-case.
















Rogue Wave      Tools.h++ Class Library                  356








                      CLASS REFERENCE


Static    static unsigned     initialCapacity(unsigned ic = 63);
public    Sets the minimum initial capacity of an RWString. The initial
member    setting is 63 characters. Larger values will use more memory,
functions but result in fewer resizes when concatenating or reading
          strings. Smaller values will waste less memory, but result in
          more resizes.

   Static unsigned  maxWaste(unsigned mw = 63);
Sets the maximum amount of unused space allowed in a string should
it shrink. If more than this amount of characters is wasted, the
space will be reclaimed.

   Static unsigned  resizeIncrement(unsigned ri = 64);
Sets the resize increment when more memory is needed to grow a
string.

          static RWBoolean    setCaseSensitive(RWBoolean s = TRUE);
          Sets whether pattern matching, hashing, and lexical comparisons
          are case-sensitive.  Returns the old setting.  The initial
          setting is case-sensitive pattern matching.

   static RWBoolean setParanoidCheck(RWBoolean s = TRUE);
Sets whether a pattern match using hash values is followed by a
string comparison.  Returns the old setting.  The initial setting is
FALSE.  See function index() for additional details.

   static RWBoolean skipWhitespace(RWBoolean s = TRUE);
Sets whether white space is skipped before reading a token or a
line.  The initial setting is TRUE.  See function readLine() for
additional details.


Related   RWString            operator+(const RWString&, const RWString&);
global    RWString            operator+(const char*, const RWString&);
operators RWString            operator+(const RWString&, const char*);
          Concatenation operators.

   ostream&         operator<<(ostream& s, const RWString&);
Output a RWString on ostream s.

   istream&         operator>>(istream& s, RWString& str);
Calls str.readToken(s).  That is, a token is read from the input
stream s.

Rogue Wave      Tools.h++ Class Library                  357








                      CLASS REFERENCE

   RWString         toLower(const RWString& str);
Returns a version of str where all upper-case characters have been
replaced with lower-case characters.

   RWString         toUpper(const RWString& str);
Returns a version of str where all lower-case characters have been
replaced with upper-case characters.






































Rogue Wave      Tools.h++ Class Library                  358








                      CLASS REFERENCE



class RWSubString





Synopsis  #include <rwstring.h>
          RWString s("test string");
          s(6,3);             // "tri"



Descripti The class RWSubString allows some subsection of a RWString to
on        be addressed by defining a starting position and an extent.
          For example the 7'th through the 11'th elements, inclusive,
          would have a starting position of 7 and an extent of 5.  The
          specification of a starting position and extent can also be
          done in your behalf by such functions as RWString::strip() or
          the overloaded function call operator taking a regular
          expression as an argument.  There are no public constructors
          -- RWSubStrings are constructed by various functions of the
          RWString class and then destroyed immediately.
          A zero lengthed substring is one with a defined starting
          position and an extent of zero.  It can be thought of as
          starting just before the indicated character, but not
          including it.  It can be used as an lvalue.  A null substring
          is also legal and is frequently used to indicate that a
          requested substring, perhaps through a search, does not exist.
          A null substring can be detected with member function
          isNull().  However, it cannot be used as an lvalue.













Rogue Wave      Tools.h++ Class Library                  359








                      CLASS REFERENCE

Example   #include <rwstring.h>
          #include <rstream.h>

          main() {

            RWString s("What I tell you is true.");

            // Create a substring and use it as an lvalue:
            s(19, 0) = "three times ";
            cout << s << NL;
          }

          Program output:
            What I tell you is three times true.































Rogue Wave      Tools.h++ Class Library                  360








                      CLASS REFERENCE



Assignment void                operator=(const RWString&);
operators  Assignment to a RWString.  The statements:

                    RWString a;
                    RWString b;
                    ...
                    b(2, 3) = a;

will copy a's data into the substring b(2,3).  The number of
elements need not match: if they differ, b will be resized
appropriately.  If the library was compiled with the DEBUG flag and
if self is the null substring then an exception will occur with
error TOOL_NULSS.

   void             operator=(const char*);
Assignment to a character string.  The statements:
                    RWString a("Mary had a lamb");
                    char dat[] = "Perrier";
                    a(11,4) = dat; // "Mary had a Perrier"

Note that the number of characters selected need not match: if they
differ, a will be resized appropriately.  If the library was
compiled with the DEBUG flag and if self is the null substring then
an exception will occur with error TOOL_NULSS.


Logical   RWBoolean           operator==(const char* s) const;
operators RWBoolean           operator==(const RWString& str) const;
          Returns TRUE if this substring is lexicographically equal to
          the character string s or RWString str, respectively.  Case
          sensitivity is set by the static member function
          RWString::setCaseSensitive().  If the library was compiled
          with the DEBUG flag and if self is the null substring then an
          exception will occur with error TOOL_NULSS.

   RWBoolean        operator!=(const char* s) const;
   RWBoolean        operator!=(const RWString& str) const;
Returns the negation of the respective operator==().





Rogue Wave      Tools.h++ Class Library                  361








                      CLASS REFERENCE


Indexing  char&               operator[](int i) const;
operators Access to individual elements with bounds checking.  If the
          index i is out of range then an exception with error TOOL_INDEX
          will occur.

   char&            operator()(int i) const;
Access to individual elements with optional bounds checking.  Bounds
checking is enabled by defining the pre-processor macro BOUNDS_CHECK
before including rwstring.  In this case, if the index i is out of
range, then an exception with error TOOL_INDEX will occur.


Public    RWBoolean           isNull() const;
member    Returns TRUE if this is a null substring.
functions
          unsigned            length() const;
          Returns the extent (i.e., length) of the RWSubString.

   RWBoolean        operator!() const;
Returns TRUE if this is a null substring.

                    operator const char*() const;
Returns zero if this is the null substring, the start of the
substring otherwise.

   int              start() const;
Returns the starting element of the RWSubString.

   void             toLower();
Changes all upper-case letters in self to lower-case.

   void             toUpper();
Changes all lower-case letters in self to upper-case.











Rogue Wave      Tools.h++ Class Library                  362








                      CLASS REFERENCE



class RWTime





Synopsis  typedef unsigned           hourTy;
          typedef unsigned           minuteTy;
          typedef unsigned           secondTy;
          typedef unsigned long      clockTy;

          #include <rwtime.h>
          RWTime a;           // Construct with current time



Descripti Class RWTime represents a time, stored as the number of seconds
on        since 1 January 1901_.  See Section 8 for how to set the time zone
          for your compiler.  Failure to do this may result in GMT times
          being wrong.

Example   #include <time.h>
          #include <rstream.h>

          main()
          {
            RWTime t;  // Current time

            cout << "Current time:         " << t << NL;

            cout << "Start of DST, 1990:   "
                 << RWTime::beginDST(1990) << NL;
          }

          Program output




_ While the ANSI X3J11 committee puts the beginning of all time at 1
  January 1970, we now know through extensive research that time
  actually started much earlier than this.

Rogue Wave      Tools.h++ Class Library                  363








                      CLASS REFERENCE

          Current time:         March 22, 1991 3:01:40 pm
          Start of DST, 1990:   April 1, 1990 2:00:00 am




Public    RWTime();
constructoConstructs a time with the present local time.
rs

   RWTime(clockTy s);
Constructs a time with s seconds since 1 January 1901.

   RWTime(hourTy h, minuteTy m, secondTy s = 0);
Constructs a time with today's date at the specified (local) hour,
minute, and second.

   RWTime(const RWDate&, hourTy h = 0, minuteTy m = 0, secondTy s = 0);
Constructs a time for a given date (defined as a RWDate) at the
specified (local) hour, minute, and second.


Public    RWBoolean           operator<(const RWTime& t) const;
member    Returns TRUE if RWTime is less than t.
operators
          RWBoolean           operator<=(const RWTime& t) const;
          Returns TRUE if RWTime is less than or equal to t.

   RWBoolean        operator>(const RWTime& t) const;
Returns TRUE if RWTime is greater than t.

   RWBoolean        operator>=(const RWTime& t) const;
Returns TRUE if RWTime is greater than or equal to t.

   RWBoolean        operator==(const RWTime& t) const;
Returns TRUE if RWTime is equal to t.

   RWBoolean        operator!=(const RWTime& t) const;
Returns TRUE if RWTime is not equal to t.

   void             operator++();
Add 1 second to RWTime



Rogue Wave      Tools.h++ Class Library                  364








                      CLASS REFERENCE

   void             operator--();
Subtract 1 second from RWTime

   void             operator+=(long s);
Add s seconds to RWTime

   void             operator-=(long s);
Subtract s seconds from RWTime


Public    RWBoolean           between(const RWTime& a, const RWTime& b) const;
member    Returns TRUE if RWTime is between a and b
functions
          unsigned            binaryStoreSize() const;
          Returns the number of bytes necessary to store this object using
          RWTime::saveOn(RWFile&).

   int              compareTo(const RWTime* t) const;
Comparison function, useful for sorting times.  Compares self to the
RWTime pointed to by t and returns:

                0   if self == *t;
                1   if self > *t;
               _1   if self < *t.

   unsigned         hash() const;
Returns a suitable hashing value.

   hourTy           hour() const;
Returns the hour; local time.

   hourTy           hourGMT() const;
Returns the hour; GMT.

   RWTime           max(const RWTime& t) const;
Returns the greater of self or t.  For example, if t1 and t2 are
RWTimes:
                 cout << t1.max(t2);

will print the greater time.

   RWTime           min(const RWTime& t) const;
Returns the lesser of self or t.


Rogue Wave      Tools.h++ Class Library                  365








                      CLASS REFERENCE

   minuteTy         minute() const;
Returns the minute; local time.

   minuteTy         minuteGMT() const;
Returns the minute; GMT.

   void             restoreFrom(RWvistream& s);
Reads a RWTime that was stored with saveOn(RWvostream&) from the
input stream s.

   void             restoreFrom(RWFile& f);
Reads an RWTime that was stored with storeOn(RWFile&) from the
RWFile f.

   secondTy         second() const;
Returns the second; local time or GMT.

   clockTy          seconds() const;
Returns the number of seconds since 00:00:00 January 1, 1901.

   void             saveOn(RWvostream& s) const;
Stores a RWTime on the output stream s.

   void             saveOn(RWFile& f) const;
Stores an RWTime in binary format on the RWFile f.


Static    static RWTime       beginDST(unsigned year);
public    Return the start of Daylight Savings Time for the given year.
member
functions

   static RWTime    endDST(unsigned year);
Return the end of Daylight Savings Time for the given year.


Related   RWTime              operator+(const RWTime& t, long s);
global    RWTime              operator+(long s, const RWTime& t);
operators Returns a RWTime s seconds greater than t.

   RWTime           operator-(const RWTime& t, long s);
Returns a RWTime s seconds less than t.



Rogue Wave      Tools.h++ Class Library                  366








                      CLASS REFERENCE

   ostream&         operator<<(ostream& s, const RWTime& t);
Outputs t on ostream s, in the form: hh:mm:ss am/pm











































Rogue Wave      Tools.h++ Class Library                  367








                      CLASS REFERENCE



class RWTokenizer





Synopsis  #include <token.h>

          RWString str("a string of tokens");
          RWTokenizer(str);   // Lex the above string



Descripti Class RWTokenizer is designed to break a string up into separate
on        tokens, deliminated by an arbitrary "white space".  It can be
          thought of as an iterator for strings and as an alternative to the
          ANSI C function strtok() which has the unfortunate side effect of
          changing the string being tokenized.

Example   #include <token.h>
          #include <rstream.h>

          main()

          {
            RWString a("Something is rotten in the state of Denmark");

            RWTokenizer next(a);     // Tokenize the string "a"

            RWString token;          // Will receive each token

            // Advance until the null string is returned:
            while( !(token=next().isNull() )
              cout << token << "\n";
          }

          Program output:






Rogue Wave      Tools.h++ Class Library                  368








                      CLASS REFERENCE

                       Something
                       is
                       rotten
                       in
                       the
                       state
                       of
                       Denmark


Public    RWTokenizer(const RWString& s);
construct Construct a tokenizer to lex the string s.
or


Public    RWSubString         operator()(const char* s =" \t\n");
member    Advance to the next token and return it as a
function  substring.  The token are considered to be
          deliminated by any of the characters in s.


























Rogue Wave      Tools.h++ Class Library                  369








                      CLASS REFERENCE



class RWvistream                                   RWvistream
                                                        |
                                                       ios

                                          (V2.X style iostreams, only)

Synopsis  #include <vstream.h>



Descripti Class RWvistream is an abstract base class.  The classes derived
on        from it are expected to restore variables stored by their
          RWvostream counterpart.  Storage and retrieval done through the
          abstract classes RWvistream and RWvostream is done in a format-
          independent manner -- the user need not be concerned with how the
          variables will actually be stored or restored.  It might be done
          using an operating-system independent ASCII format (classes
          RWpistream and RWpostream), a binary format (classes RWbistream
          and RWbostream), or the user could define his or her own format
          (e.g., an interface to a network).
          No assumptions should be made about the format of how the
          variables might be stored.  That is up to the derived class to
          decide.  However, the functionality of the derived class is
          expected to follow the descriptions given for the virtual
          member functions below.
          Storage and retrieval is independent of whether the compiler
          is using AT&T V1.2 style "streams", or the newer V2.X style
          "iostreams" -- the user need not be concerned with which style
          is actually being used.  However, the inheritance tree is
          different for the two types of streams.  If the compiler uses
          V1.2 style streams, then RWvostream inherits from class
          istream, otherwise it inherits from virtual base class ios.
          Either way, the class RWvostream can be interrogated as to the
          stream state using member functions good(), bad(), eof(), etc.
          See class RWvostream for additional explanations and examples
          of format-independent stream storage.







Rogue Wave      Tools.h++ Class Library                  370








                      CLASS REFERENCE

Example   #include <vstream.h>

          void restoreStuff( RWvistream& str)

          {

            int i;
            double d;
            char string[80];

            str >> i;  // Restore an int

            str >> d;  // Restore a double

            // Restore a character string, up to 80 characters long:
            str.getString(string, sizeof(string));

            if(str.fail()) cerr << "Oh, oh, bad news.\n";
          }



Public    RWvistream(streambuf* s);
construct Initialize a RWvistream from the streambuf s.  This
or        constructor should be used if you define your own virtual
          stream class to implement your own format.

Public    virtual int         get() = 0;
member    Get and return the next char from the input stream, returning
functions its value.  Returns EOF if end of file is encountered.

   virtual RWvistream&    get(char& c) = 0;
Get the next char from the input stream, returning its value in c.

   virtual RWvistream&    get(unsigned char& c) = 0;
Get the next char from the input stream, returning its value in c.

   virtual RWvistream&    get(char* v, unsigned N) = 0;
Get a vector of char's and store then in the array beginning at v.
If the restore is stopped prematurely, get stores whatever it can in
v, and sets the failbit.  Note that the vector is treated as a
vector of numbers, not characters.  If you wish to restore a
character string, use function getString(char*, int).


Rogue Wave      Tools.h++ Class Library                  371








                      CLASS REFERENCE

   virtual RWvistream&    get(double* v, unsigned N) = 0;
Get a vector of double's and store then in the array beginning at v.
If the restore is stopped prematurely, get stores whatever it can in
v, and sets the failbit.

   virtual RWvistream&    get(float* v, unsigned N) = 0;
Get a vector of float's and store then in the array beginning at v.
If the restore is stopped prematurely, get stores whatever it can in
v, and sets the failbit.

   virtual RWvistream&    get(int* v, unsigned N) = 0;
Get a vector of int's and store then in the array beginning at v.
If the restore is stopped prematurely, get stores whatever it can in
v, and sets the failbit.

   virtual RWvistream&    get(long* v, unsigned N) = 0;
Get a vector of long's and store then in the array beginning at v.
If the restore is stopped prematurely, get stores whatever it can in
v, and sets the failbit.

   virtual RWvistream&    get(short* v, unsigned N) = 0;
Get a vector of short's and store then in the array beginning at v.
If the restore is stopped prematurely, get stores whatever it can in
v, and sets the failbit.

   virtual RWvistream&    get(unsigned char* v, unsigned N) = 0;
Get a vector of unsigned char's and store then in the array
beginning at v.  If the restore is stopped prematurely, get stores
whatever it can in v, and sets the failbit.  Note that the vector is
treated as a vector of numbers, not characters.  If you wish to
restore a character string, use function getString(char*, int).

   virtual RWvistream&    get(unsigned short* v, unsigned N) = 0;
Get a vector of unsigned short's and store then in the array
beginning at v.  If the restore is stopped prematurely, get stores
whatever it can in v, and sets the failbit.

   virtual RWvistream&    get(unsigned int* v, unsigned N) = 0;
Get a vector of unsigned int's and store then in the array beginning
at v.  If the restore is stopped prematurely, get stores whatever it
can in v, and sets the failbit.

   virtual RWvistream&    get(unsigned long* v, unsigned N) = 0;
Get a vector of unsigned long's and store then in the array

Rogue Wave      Tools.h++ Class Library                  372








                      CLASS REFERENCE

beginning at v.  If the restore is stopped prematurely, get stores
whatever it can in v, and sets the failbit.

   virtual RWvistream&    getString(char* s, unsigned N) = 0;
Restores a character string from the input stream and stores it in
the array beginning at s.  The function stops reading at the end of
the string or after N-1 characters, whichever comes first.  If the
latter, then the failbit of the stream will be set.  In either case,
the string will be terminated with a null byte.

   virtual RWvistream&    operator>>(char& c) = 0;
Get the next character from the input stream and store it in c.

   virtual RWvistream&    operator>>(double& d) = 0;
Get the next double from the input stream and store it in d.

   virtual RWvistream&    operator>>(float& f) = 0;
Get the next float from the input stream and store it in f.

   virtual RWvistream&    operator>>(int& i) = 0;
Get the next int from the input stream and store it in i.

   virtual RWvistream&    operator>>(long& l) = 0;
Get the next long from the input stream and store it in l.

   virtual RWvistream&    operator>>(short& s) = 0;
Get the next short from the input stream and store it in s.

   virtual RWvistream&    operator>>(unsigned char& c) = 0;
Get the next unsigned char from the input stream and store it in c.

   virtual RWvistream&    operator>>(unsigned short& s) = 0;
Get the next unsigned short from the input stream and store it in s.

   virtual RWvistream&    operator>>(unsigned int& i) = 0;
Get the next unsigned int from the input stream and store it in i.

   virtual RWvistream&    operator>>(unsigned long& l) = 0;
Get the next unsigned long from the input stream and store it in l.






Rogue Wave      Tools.h++ Class Library                  373








                      CLASS REFERENCE



class RWvostream                                      RWvostream
                                                           |
                                                          ios

                                             (V2.X style iostreams, only)

Synopsis  #include <vstream.h>



Descripti Class RWvostream is an abstract base class.  The classes derived from
on        it are expected to store variables to be restored by their RWvistream
          counterpart.  Storage and retrieval done through the abstract classes
          RWvistream and RWvostream should be done in a format-independent
          manner -- the user need not be concerned with how the variables will
          actually be stored or restored.  It might be done using an operating-
          system independent ASCII format (classes RWpistream and RWpostream),
          a binary format (classes RWbistream and RWbostream), or the user
          could define his or her own format (e.g., an interface to a network).
          Note that because it is an abstract base class, there is no way to
          actually enforce these goals -- the description here is merely the
          model of how a class derived from RWvistream and RWvostream should
          act.
          No assumptions should be made about the format of how the
          variables might be stored.  That is up to the derived class to
          decide.  However, the functionality of the derived class is
          expected to follow the descriptions given for the virtual
          member functions below.  Note that there is no need to
          separate variables with whitespace.  It is the responsibility
          of the derived class to delineate variables with whitespace,
          packet breaks, or whatever might be appropriate for the final
          output sink.  The model is one where variables are inserted
          into the output stream, either individually or as homogeneous
          vectors, to be restored in the same order using RWvistream.
          Storage and retrieval is independent of whether the compiler
          is using AT&T V1.2 style "streams", or the newer V2.X style
          "iostreams" -- the user need not be concerned with which style
          is actually being used.  However, the inheritance tree is
          different for the two types of streams.  If the compiler uses
          V1.2 style streams, then RWvostream inherits from class
          istream, otherwise it inherits from class ios.  Either way,
          the class RWvostream can be interrogated as to the stream

Rogue Wave      Tools.h++ Class Library                  374








                      CLASS REFERENCE

          state using member functions good(), bad(), eof(), etc.
          Storage and retrieval of characters requires some explanation.
          Characters can be thought of as either representing some
          alphanumeric or control character, or as the literal number.
          Generally, the overloaded lshift (<<) and rshift (>>)
          operators seek to store and restore characters preserving
          their symbolic meaning.  I.e., storage of a newline should be
          restored as a newline, irregardless of its representation on
          the target machine.  By contrast, member functions get() and
          put() should treat the character as a literal number, whose
          value is to be preserved.

Example   #include <vstream.h>

          void storeStuff( RWvostream& str)

          {

            int i = 5;
            double d = 22.5;
            char string[] = "A string with \t tabs and a newline\n";

            str << i;  // Store an int

            str << d;  // Store a double

            str << string;           // Store a string

            if(str.fail()) cerr << "Oh, oh, bad news.\n";
          }



Public    RWvostream(streambuf* s);
construct Initialize a RWvostream from the streambuf s.  This constructor
or        should be used if you define your own virtual stream class to
          implement your own format.

   virtual RWvostream&    operator<<(const char* s) = 0;
Store the character string starting at s to the output stream.  The
character string is expected to be null terminated.

   virtual RWvostream&    operator<<(char c) = 0;
Store the char c to the output stream.  Note that c is treated as a

Rogue Wave      Tools.h++ Class Library                  375








                      CLASS REFERENCE

character, not a number.

   virtual RWvostream&    operator<<(unsigned char c) = 0;
Store the unsigned char c to the output stream.  Note that c is
treated as a character, not a number.

   virtual RWvostream&    operator<<(double d) = 0;
Store the double d to the output stream.

   virtual RWvostream&    operator<<(float f) = 0;
Store the float f to the output stream.

   virtual RWvostream&    operator<<(int i) = 0;
Store the int i to the output stream.

   virtual RWvostream&    operator<<(unsigned int i) = 0;
Store the unsigned int i to the output stream.

   virtual RWvostream&    operator<<(long l) = 0;
Store the long l to the output stream.

   virtual RWvostream&    operator<<(unsigned long l) = 0;
Store the unsigned long l to the output stream.

   virtual RWvostream&    operator<<(short s) = 0;
Store the short s to the output stream.

   virtual RWvostream&    operator<<(unsigned short s) = 0;
Store the unsigned short s to the output stream.

   virtual RWvostream&    put(char c) = 0;
Store the char c to the output stream, preserving its value.

   virtual RWvostream&    put(unsigned char c) = 0;
Store the char c to the output stream, preserving its value.

   virtual RWvostream&    put(const char* p, unsigned N) = 0;
Store the vector of chars starting at p to the output stream.  The
chars should be treated as literal numbers (i.e., not as a character
string).

   virtual RWvostream&    put(const unsigned char* p, unsigned N) = 0;
Store the vector of unsigned chars starting at p to the output
stream.  The chars should be treated as literal numbers (i.e., not

Rogue Wave      Tools.h++ Class Library                  376








                      CLASS REFERENCE

as a character string).

   virtual RWvostream&    put(const short* p, unsigned N) = 0;
Store the vector of shorts starting at p to the output stream.

   virtual RWvostream&    put(const unsigned short* p, unsigned N) = 0;
Store the vector of unsigned shorts starting at p to the output
stream.

   virtual RWvostream&    put(const int* p, unsigned N) = 0;
Store the vector of ints starting at p to the output stream.

   virtual RWvostream&    put(const unsigned int* p, unsigned N) = 0;
Store the vector of unsigned ints starting at p to the output
stream.

   virtual RWvostream&    put(const long* p, unsigned N) = 0;
Store the vector of longs starting at p to the output stream.

   virtual RWvostream&    put(const unsigned long* p, unsigned N) = 0;
Store the vector of unsigned longs starting at p to the output
stream.

   virtual RWvostream&    put(const float* p, unsigned N) = 0;
Store the vector of floats starting at p to the output stream.

   virtual RWvostream&    put(const double* p, unsigned N) = 0;
Store the vector of doubles starting at p to the output stream.

















Rogue Wave      Tools.h++ Class Library                  377











                                                            Appendix A:
                                        Summary of typedefs and macros:



Macros:
  #define   FALSE                  0
  #define   KEY_SIZE               16
  #define   nil                    0
  #define   NIL                    _1L
  #define   TRUE                   1

Typedefs:
  typedef   const char*  CharP;
  typedef   unsigned short         ClassID;  // Unique for each class
  typedef   unsigned long          clockTy;  // seconds
  typedef   unsigned     dayTy;    // days
  typedef   int          fileDescTy; // File descriptor
  typedef   unsigned     hourTy;   // hours
  typedef   unsigned long          julTy;    // Julian days
  typedef   unsigned     minuteTy; // minutes
  typedef   unsigned     monthTy;  // months
  typedef   long         nodeOffset; // Used for file offsets
  typedef   int          RWBoolean;  // TRUE or FALSE
  typedef   long         RWoffset; // Used for file offsets
  typedef   void*        RWvoid;   // Useful for arrays of void*
  typedef   unsigned     secondTy; // seconds
  typedef   unsigned     RWspace;  // Used for file records
  typedef   long         storedValue;// Used for file offsets
  typedef   unsigned     yearTy;   // years














Tools.h++ Class Library     379








                          APPENDIX

Pointers to Functions:
  typedef   void         (*RWapplyCollectable)(RWCollectable*, void*);
  typedef   void         (*RWapplyGeneric)(void*, void*);
  typedef   void         (*RWapplyKeyAndValue)(RWCollectable*,
                                         RWCollectable*, void*);
  typedef   RWBoolean    (*RWtestGeneric)(const void*,const void*);
  typedef   RWBoolean    (*RWtestCollectable)(const RWCollectable*,
                                         const void*);
  typedef   RWCollectable*               (*userCreator)();

Enumerations:
  enum      RWSeverity   {RWWARNING, RWDEFAULT, RWFATAL}

          Standard Smalltalk Interface:
  typedef RWBag                    Bag;
  typedef RWBagIterator            BagIterator;
  typedef RWBinaryTree             SortedCollection;
  typedef RWBinaryTreeIterator     SortedCollectionIterator;
  typedef RWBitVec                 BitVec
  typedef RWCollectable            Object; // All-to-common type!
  typedef RWCollectableDate        Date;
  typedef RWCollectableInt         Integer;
  typedef RWCollectableString      String;
  typedef RWCollectableTime        Time;
  typedef RWCollection             Collection;
  typedef RWHashDictionary         Dictionary;
  typedef RWHashDictionaryIterator DictionaryIterator;
  typedef RWIdentityDictionary     IdentityDictionary;
  typedef RWIdentityHash           IdentitySet;
  typedef RWOrdered                OrderedCollection;
  typedef RWOrderedIterator        OrderedCollectionIterator;
  typedef RWSequenceable           SequenceableCollection;
  typedef RWSet                    Set;
  typedef RWSetIterator            SetIterator;
  typedef RWSlistCollectables      LinkedList;
  typedef RWSlistCollectablesIterator   LinkedListIterator;
  typedef RWSlistCollectablesQueue Queue;
  typedef RWSlistCollectablesStack Stack;







Rogue Wave      Tools.h++ Class Library                  380











                                                            Appendix B:
                                                           Bibliography



          Ammeraal, L.  Programs and Data Structures in C, John Wiley
             and Sons, 1989, ISBN 0-471-91751-6.
          Booch, Grady, Object-Oriented Design with Applications, The
             Benjamin Cummings Publishing Company, Inc., 1991, ISBN 0-
             8053-0091-0.
          Eckel, Bruce, Using C++, Osborne McGraw-Hill, 1989, ISBN 0-07-
             881522-3.
          Ellis, Margaret A. and Bjarne Stroustrup, The Annotated C++
             Reference Manual, Addison-Wesley, 1990, ISBN 0-201-51459-
             1.
          Goldberg, Adele and David Robson, Smalltalk-80, The Language,
             Addison-Wesley, 1989, ISBN 0-201-13688-0.
          Gorlen, Keith, The NIH Class Library, Computer Systems
             Laboratory, DCRT, National Institutes of Health, Bethesda,
             MD 20892.
          Gorlen, Keith, Sanford M. Orlow and Perry S. Plexico, Data
             Abstraction and Object-Oriented Programming in C++, John
             Wiley and Sons, 1990, ISBN 0-471-92346 X.
          Khoshafian, Setrag and Razmik Abnous, Object orientation:
             Concepts, Languages, Databases, User Interfaces, John
             Wiley and Sons, 1990, ISBN 0-471-51802-6.
          Lippman, Stanley B. C++ Primer, Addison-Wesley, 1989, ISBN 0-
             201-16487-6.
          Meyer, Bertrand, Object-oriented Software Construction,
             Prentice-Hall, 1988, ISBN 0-13-629049-3.
          Petzold, Charles, Programming Windows, Microsoft Press, 1990,
             ISBN 1-55615-264-7.
          Sedgewick, Robert. Algorithms, Addison-Wesley, 1988, ISBN 0-
             201-06673-4.
          Stroustrup,  Bjarne. The C++ Programming Language, Addison-
             Wesley, 1986, ISBN 0-201-12078-X.








Tools.h++ Class Library     381











                                                                  Index


Apply functions 73, 83
apply() 73, 83
Architectural notes 104
AT&T 13, 20
Bag 157
Bibliography 303
Bit vector 133, 169
Borland 18
Borland C++ 19
Caches
  RWCacheManager 186
ClassID 192, 224, 301
clear() 84
clearAndDestroy() 84
Clipboard 45
clockTy 301
Collection 202
Collection Classes
  abstract base class 202
  Dictionary 87
  generic 16, 67
     declaration 69
     GBitVec(size) 133
     GDlist(type) 136
     GQueue(type) 143
     GSlist(type) 145
     GSortedVector(val) 150
     GStack(type) 153
     user-defined functions 70
  Hash 88
  introduction 61
  RWBag 157
  RWBinaryTree 161
     example 124
  RWBTree 178
  RWBTreeOnDisk 184
     example 126
  RWDlistCollectables 216



Tools.h++ Class Library     383








                           INDEX

  RWHashDictionary
     example 126
  RWIdentitySet 238
  RWOrdered 242, 274
  RWSet 259
  RWSlistCollectables 263
  RWSlistCollectablesQueue 269
  RWSlistCollectablesStack 272
  selection 84
  Smalltalk-like 16, 75
  storing and retrieving 104
  virtual functions 79
Compares equal 62
  definition 132
compareTo() 94, 191
Compilers
  supported 3
Compiling a program 15
  AT&T 20
  Borland 18
  DOS 18
  Glockenspiel 20
  Unix 20
  Zortech 19
contains() 80
Conventions 4
Copies
  shallow vs. deep 63
Copy constructor 30, 64
Create functions 98, 224
Date 194
dayTy 301
DDE 45, 212
  example 45
Debugging 14, 107
Deep copy 64
DEFINE_COLLECTABLE 98
Dictionary 87, 231
  RWBTreeDictionary 181
  RWHashDictionary 231
  RWIdentityDictionary 237
Diskette contents 7
DLL 111
  compiling with 19

Rogue Wave      Tools.h++ Class Library                  384








                           INDEX

  example 111
Dynamic Data Exchange (See DDE)
Dynamic Link Library (See DLL)
Efficiency 30
entries() 80
Equal to
  definition 131
Errors 107
  asynchronous 109
  error handler 110, 223
  invalid input 108
  numbers 110
  violated preconditions 107
Examples 123-127
Exception handling 109
FALSE 301
File suffixes 7
fileDescTy 301
find() 80
GBitVec(size) 133, 169
GDlist(type) 136
  example 124
GDlistIterator(type) 140
Glockenspiel
  Unix 13
GQueue(type) 143
Gregorian calendar 37
GSlist(type) 145
GSlistIterator(type) 148
GSortedVector(val) 150
GStack(type) 153
GVector(val) 155
hash() 88, 97, 192
Hashing collections 88
HCR 13, 20
Header files 15
hourTy 301
Identical to
  definition 131
IdentityDictionary 237
IdentitySet 238
Implementation notes 107
insert() 80
Installation 7

Rogue Wave      Tools.h++ Class Library                  385








                           INDEX

  Glockenspiel 9
  MS-DOS 8
  Zortech 9
Integer 196
Interviews Class Library 226
iostream 41
isA() 94, 192
isEmpty() 80
isEqual 62
isEqual() 96, 192
isSame 62
Iterator 86
  abstract base class 241
  GDlist(type) 140
  GSlist(type) 148
  RWBag 160
  RWBinaryTree 164
  RWDlistCollectables 220
  RWHashDictionary 235
  RWIterator 241
  RWOrdered 245
  RWSet 262
  RWSlistCollectables 267
  vs. function apply() 86
julTy 301
KEY_SIZE 184, 301
Libraries
  naming convention 10
  precompiled 8
  recompiling
     Borland 10
     Glockenspiel 12
     MS-DOS 10
     Unix 12
     Zortech 11
Linked List
  generic
     doubly-linked 136
     singly-linked 145
  of Collectables
     doubly-linked 216
     singly-linked 263
LinkedList 263
LinkedListIterator 267

Rogue Wave      Tools.h++ Class Library                  386








                           INDEX

Makefiles 7
Math.h++ 14
megalomania 4
minuteTy 301
monthTy 301
Multiple inheritance 63
newSpecies() 97
nil 301
NL 23
nodeOffset 301
Oasys 13
Object 191
  identity 62
occurrencesOf() 80
Oregon Software 13
PFile 226
Philosophy 3
Preconditions 107
Queue 269
  generic 143
  of Collectables 269
Recursion (See Recursion)
Reference counting 30
Reference semantics 64
Regular expressions 34, 254, 279
remove() 82
removeAndDestroy() 82
restoreFrom() 90, 101, 192
restoreGuts() 98, 192
rstream.h 23
RWBag 157
RWBagIterator 160
RWBinaryTree 78, 161
RWBinaryTreeIterator 164
RWbistream 165
  example 43
RWBitVec 133, 169
RWBoolean 301
RWbostream 174
  example 43
RWBTree 178
RWBTreeDictionary 181
RWBTreeOnDisk 57, 126, 184
RWCacheManager 186

Rogue Wave      Tools.h++ Class Library                  387








                           INDEX

RWCLIPstreambuf 188
RWCollectable 191
  comparison 94
  designing 92
  storing and retrieving 89, 101
  virtual destructor 94
  virtual functions 92
RWCollectableDate 194
RWCollectableInt 196
RWCollectableString 78, 198
RWCollectableTime 200
RWCollection 202
RWDate 37, 58, 194, 206
  example 123
RWDDEstreambuf 212
  example 45
RWDlistCollectables 216
RWDlistCollectablesIterator 220
RWErrObject 110, 222
RWFactory 98, 224
RWFile 47, 49, 226, 229
RWFileManager 51, 57, 184, 229
RWHashDictionary 231
RWHashDictionaryIterator 235
RWIdentityDictionary 237
RWIdentitySet 238
RWInteger 196, 239
RWIterator 241
RWoffset 51, 229, 301
RWOrdered 242
RWOrderedIterator 245
RWpistream 246
RWpostream 250
RWRegexp 254
RWSequenceable 257
  virtual functions 85
RWSet 259
RWSetIterator 262
RWSlistCollectables 263
RWSlistCollectablesIterator 267
RWSlistCollectablesQueue 269
RWSlistCollectablesStack 272
RWSortedVector 274
RWspace 51, 229, 301

Rogue Wave      Tools.h++ Class Library                  388








                           INDEX

RWString 29, 198, 277
  example 123
  pattern matching 33
  substrings 33, 284
RWSubString 33, 284
RWTime 39, 200, 287
  example 123
RWTokenizer 35, 291
RWvistream 41, 293
RWvostream 41, 297
saveGuts() 97, 192
saveOn() 90, 101, 193
SCO 13
secondTy 301
select() 84
SequenceableCollection 257
Set 259
setw() 59
Shallow copy 64
shallowStoreSize() 193
Smalltalk
  typedefs 302
SortedCollection 78, 161
SortedCollectionIterator 164
Stack 272
  generic 153
  of Collectables 272
storedValue 57, 184, 301
Storing and retrieving
  RWCollectables 101
  to RWFiles 47
  to virtual streams 41
Stream I/O 23
  memory based 45
  RWbistream 165
  RWbostream 174
  RWpistream 246
  RWpostream 250
  RWvistream 293
  RWvostream 297
  virtual streams 41
streambufs
  Windows specializing 45
String 198, 277

Rogue Wave      Tools.h++ Class Library                  389