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

Text File | 1992-04-01 | 174.9 KB | 5,400 lines

                                  Tools.h++
                                     V5.0
                                  Supplement







                              License Agreement

          c Copyright Rogue Wave Associates, 1989, 1990, 1991, 1992.

This software  package and  its documentation  are subject  to  the following
license agreement.  By opening the diskette package  seal, you are implicitly
accepting these terms and conditions.

Permission is given to the buyer of this package to use  this software on one
computer at a time,  make one backup copy,  and make one printed  copy of the
source code.   You may  utilize and/or modify  this program  for use  in your
projects.   You may  distribute and  sell any  executable which  results from
using this code  in your  applications, except a  utility program  of similar
nature to  this  product.   You  may  NOT  redistribute  the source  code  or
resultant object modules or libraries of  object modules in any  form, put it
on a bulletin  board system,  or sell  it.   You may  not use,  copy, modify,
merge, or transfer the  program, or manual or  any portion of the  program or
manual, except as expressly provided above in this agreement.

A multi-user license  may be purchased  to allow the  software to be  used on
more than one  computer at  the same  time; including  a shared  disk system.
Contact Rogue Wave for information on site licenses.

This material  is  sold  "as is".  Rogue  Wave  makes no  warranties,  either
expressed or implied, regarding  the enclosed computer software  package, its
merchantability, or its  fitness for any  particular purpose.  Information in
this document is subject  to change without notice  and does not  represent a
commitment on the part of Rogue Wave.   While every effort  is made to insure
that the above mentioned product  and its documentation are  free of defects,
Rogue Wave shall not be held responsible for any loss of  profit or any other
commercial  damage,  including  but  not  limited   to  special,  incidental,
consequential or other damages occasioned by the use of this product.

It is  assumed  that  purchasers of  this  product  are familiar  with  basic
programming skills (e.g., setting  up a path with  MS-DOS). This is  a highly
technical product,  offered in  a rapidly  evolving  programming environment.
Rogue Wave  recognizes  this  fact,  and  will  provide  limited  support  to
purchasers of this  product for 60  days after its  purchase (of  course, bug
reports and  comments are  always welcome).   Questions  and comments  may be
submitted either by  mail or  telephone.   Rogue Wave  reserves the  right to
respond to questions or comments in writing or by telephone.

Rogue Wave acknowledges all trademarks found in this manual and in the source
code documentation.  This acknowledgement includes, but is not limited to:
AT&T/UNIX, Microsoft, MS-DOS, Zortech, Borland, Oregon Software, HCR,
ParcPlace, Smalltalk-80, SCO, Free Software Foundation, Glockenspiel,
Windows.





                              Table of Contents

     Templates.....................................................3
     1.1 Introduction .............................................3
          1.1.1 Enter templates ...................................3
          1.1.2 What's the catch? .................................4
          1.1.3 Factoring out commonality .........................4
     1.2 Naming scheme ............................................5
     1.3 Header files .............................................5
     1.4 Types of templates .......................................6
          1.4.1 Intrusive lists ...................................6
          1.4.2 Value-based collections ...........................6
          1.4.3 Pointer-based collections .........................7
     1.5 An example ...............................................7
     1.6 A more complicated example ...............................9

     Class Reference Guide........................................13
     GOrderedVector(val)..........................................14
     RWBench......................................................17
     RWBufferedPageHeap...........................................22
     RWCString....................................................24
     RWDiskPageHeap...............................................32
     RWModel......................................................36
     RWTBitVec<size>..............................................37
     RWTimer......................................................40
     RWTIsvDlist<T>...............................................42
     RWTIsvSlist<T>...............................................46
     RWTQueue<T, C>...............................................50
     RWTStack<T, C>...............................................52
     RWTValDlist<T>...............................................54
     RWTValHashDictionary<K,V>....................................60
     RWTValHashSet<T>.............................................65
     RWTValHashTable<T>...........................................66
     RWTValOrderedVector<T>.......................................69
     RWTValSlist<T>...............................................73
     RWTValSortedVector<T>........................................79
     RWTValVector<T>..............................................83
     RWTValVirtualArray<T>........................................87
     RWVirtualPageHeap............................................91

     Appendix A:      Upgrading from V4.0 ........................95
     A.1 Include path has changed ................................95
     A.2 Dropped compilers .......................................95
     A.3 Borland library names changed ...........................95
     A.4 Windows streambuf constructors have changed .............96
     A.5 RWCString replaces RWString .............................96
     A.6 GSortedVector(val) ......................................96













                                  Tools.h++
                                     V5.0

                                  Supplement
                                    to the
                                  User Guide













                                                           S e c t i o n   1


                                                                     Templates
                                                    (Source code version only)



1.1  Introduction


Ever since Version 2.0, Tools.h++ has traditionally offered two types of
collection classes: the so-called "generic" collection classes and the
Smalltalk-like collection classes.  Each had its advantages and
disadvantages.  The Smalltalk-like classes offer a pleasant programming
interface, code reuse, and a consistent interface.  However, they actually
collect pointers to a common base class (RWCollectable), requiring that all
collected objects inherit from this class -- the actual type of the class is
unknown at runtime.  This requires the programmer to rely on some other kind
of information, either the isA() function or some logical inference, to
decide whether it is safe to "downcast" the pointer to an RWCollectable to a
pointer to the derived class.  Future language extensions1 hold the promise
that such downcasting can at least be standardized by the language.  However,
the programmer will always have to remember to perform the check.  The check
may also fail: an object's inheritance hierarchy may make the type cast
impossible and the prudent programmer must be prepared for this.

1.1.1 Enter templates
Templates, or parameterized types, offer an elegant solution.  Over the next
few years they promise to revolutionize the way we approach C++ programming.
Indeed, 5 years from now the polymorphic collection approach may be just a
footnote in the history of C++ design.
Templates are extremely similar to the existing "generic.h" approach, used by
Rogue Wave's present generic collection classes, which relies on preprocessor
macros to define a family of classes parameterized on a type.  However, a
macro does a lexical substitution in situ, that is at the site of invocation,
making them extremely hard to debug (a single line may be expanded into



1 See, for example, Bjarne Stroustrup's article ``Runtime type
  identification'' in the March 1992 issue of The C++ Report.








                                                               Templates

thousands of tokens!).  They are also nasty to write, requiring as they do
that all newlines be escaped with a backslash.
Templates are logically a class declaration parameterized on a type.  They
are a prescription for how a particular type of collection should behave.
For example, a Vector template would describe such things as how to index an
element, how long it is, how to resize, etc.  The actual type of the elements
is independent of these larger, more general issues.
Now if you procede to request a vector of a particular type, say a
Vector<double>, that is, a vector of doubles, then the compiler goes back to
the template declaration and fills it in for the type double.  The effect is
as if you had hand written a class "VectorOfDoubles".  But, of course, you
didn't.  Instead, the compiler automatically generated the logical equivalent
of such a class.  The result is extreme source code reuse.

1.1.2 What's the catch?
Which brings us to the one disadvantage of templates.  It is the source code
that is being reused, not the object code.  A declaration for Vector<double>
gets compiled separately from Vector<int>.  Unless some provisions have been
made by the class designer, the two declarations will generate totally
independent object code, with the potential for bloat of the executable.
Indeed, to some extent, this is unavoidable.  Still, the careful class
designer will recognize points of commonality that do not depend on the
actual type and factor them out.  These are put in a separate "type-
independent" class which can be compiled once, resulting in more
compact code.  A trivial example, one that builds on our discussion of
vectors, might be the vector length.  We might want to declare a
BaseVector class that holds the length of any vector.  We would then
derive the template-based vectors Vector<T> from this.  Of course, the
code required to return the length of a vector is trivial, and so it
turns out that in practice it isn't worth doing this.

1.1.3 Factoring out commonality
For a more substantial example, take a look at the intrusive linked-list
class RWTIsvSlist<T>.  This is a linked list of types T which are required to
inherit from class RWIsvSlink.  This class contains a "next" field,
consisting of a pointer to the next link.  A few moments reflection will
convince you that we don't really need to know the derived type of the link
to actually walk the list.  We need only know that it inherits from
RWIsvSlink.  Furthermore, given an existing link, we don't even need to know
its type to add or remove it from the list!
Hence, all this code can be factored out, compiled once, and forgotten.




Rogue Wave              Tools.h++   V 5.0   Supplement  4








                                                               Templates


1.2  Naming scheme


All of the template class names start with "RWT", followed by a three letter
code:
               Isv             Intrusive lists
               Val             Value-based
               Ptr             Pointer-based

Hence, RWTValOrderedVector<T> is a value-based template for an ordered vector
of type T.

1.3  Header files





 Template class          Description                           Header file

 RWTBitVec<size>         Bit vector of length size            <rw/tbitvec.h>
 RWTIsvDlist<T>          Intrusive doubly-linked list of      <rw/tidlist.h>
                         types T
 RWTIsvDlistIterator<T   Iterator for RWTIsvDlist<T>          <rw/tidlist.h>
 >
 RWTIsvSlist<T>          Intrusive singly-linked list of      <rw/tislist.h>
                         types T
 RWTIsvSlistIterator<T   Iterator for RWTIsvSlist<T>          <rw/tislist.h>
 >
 RWTPtrVector<T>         Vector of pointers to T.              <rw/tpvector.h>
 RWTQueue<T,C>           Queue of types T, implemented by     <rw/tqueue.h>
                         class C
 RWTStack<T,C>           Stack of types T, implemented by     <rw/tstack.h>
                         class C
 RWTValDlist<T>          Value-based doubly linked list of    <rw/tvdlist.h>
                         types T.
 RWTValDlistIterator<T   Iterator for RWTValDlist<T>          <rw/tvdlist.h>
 >
 RWTValHashDictionary<   Value-based hash dictionary of keys  <rw/tvhdict.h>
 K,V>                    of type K and values of type V.
 RWTValHashDictionaryI   Iterator for                         <rw/tvhdict.h>
 terator<K,V>            RWTValHashDictionary<K,V>


Rogue Wave              Tools.h++   V 5.0   Supplement  5








                                                               Templates

 RWTValHashSet<T>        Value-based Set, implemented using   <rw/tvhset.h>
                         a hashed table
 RWTValHashTable<T>      Value-based Bag, implemented using   <rw/tvhasht.h>
                         a hashed table
 RWTValHashTableIterat   Iterator for RWTValHashTable<T>      <rw/tvhasht.h>
 or<T>
 RWTValOrderedVector<T   Ordered collection of types T,       <rw/tvordvec.h>
 >                       implemented as a vector
 RWTValSlist<T>          Value-based singly linked list of    <rw/tvslist.h>
                         types T.
 RWTValSlistIterator<T   Iterator for RWTValSlist<T>          <rw/tvslist.h>
 >
 RWTValSortedVector<T>   Sorted vector of types T,             <rw/tvsrtvec.h>
                         implemented as a vector
 RWTValVector<T>         Vector of types T.                    <rw/tvvector.h>
 RWTValVirtualArray<T>   Virtual array of types T.             <rw/tvrtarry.h>




1.4  Types of templates



1.4.1 Intrusive lists
For a collection of type T, intrusive lists are lists where type T inherits
directly from the link type itself2.  The results are optimal in space and
time, but require you to honor the inheritance hierarchy.

1.4.2 Value-based collections
Value-based collections copy the object in and out of the collection.  A very
familiar example of a value-based "collection" is the C array:
            int v[100];  /* A 100 element array of ints */
            int i = 7;
            v[2] = i;

The statement "v[2] = i" copies the value of i into the array at index 2.
What resides within the array is a distinct copy, separate from the original
object i.



2 See Stroustrup, The C++ Programming Language, Second Edition,
  Addison-Wesley, 1991, for a description of intrusive lists.

Rogue Wave              Tools.h++   V 5.0   Supplement  6








                                                               Templates

Value-based collections can contain more complicated objects too.  Here's an
example of a vector of RWCStrings:
            /* A 100 element array of RWCStrings: */
            RWTValVector<RWCString> v(100);
            RWCString s("A string");
            v[2] = s;

Just as with the array of ints, the statement "v[2] = s" copies the value of
s into the vector at index 2.  The object that lies within the vector is
distinct and separate from the original object s.

1.4.3 Pointer-based collections
The final type of collection, pointer-based, is similar to the Smalltalk-like
collection classes.  The data that gets inserted into the collection is not
the object itself, but rather its address.  That is, a pointer to the data is
inserted.  Now the collection class refers to the original object:
            /* A 100 element array of pointers to RWCStrings: */
            RWTPtrVector<RWCString> v(100);
            RWCString s("A string");
            v[2] = &s;

Both the object s and the array element v[2] refer to the same object.
Naturally, this approach requires some care: should the string be deleted the
array element will be left pointing into nonsense.  You must take care that
you are aware of who is responsible for the allocation and deallocation of
objects collected this way.
Neverthless, this type of collection can be appropriate for many situations.
You may need to have the same group of objects referred to in many ways,
requiring that each collection point to the target objects, rather than wholy
contain them.  For example, a collection may refer to a set of "picked"
objects that your graphical program has obtained from a user.  You need to
know which ones must be highlighted.  You can probably think of many other
such examples.

1.5  An example


It's time to look at an example.  Let's start with a simple one: a vector of
doubles.
            BEGIN FILE: exam1.cpp
          #include <rw/tvvector.h>    // 1

          main() {


Rogue Wave              Tools.h++   V 5.0   Supplement  7








                                                               Templates

            RWTValVector<double> vec(20, 0.0);          // 2

            int i;
            for (i=0; i<10; i++) vec[i] = 1.0;          // 3
            for (i=11; i<20; i++) vec(i) = 2.0;         // 4

            vec.reshape(30);          // 5
            for (i=21; i<30; i++) vec[i] = 3.0;         // 6
            return 0;
          }
            END FILE

Each program line is detailed below.
          1  This is where the template for RWTValVector<T> is defined.
          2  A vector of doubles, 20 elements long and initialized to 0.0 is
             defined.
          3  The first 10 elements of the vector are set to 1.0.  Here,
             RWValVector<double>::operator[](int) has been used.  This
             operator always performs a bounds check on its argument.
          4  The next 10 elements of the vector are set to 2.0.  In this case
             RWValVector<double>::operator()(int) has been used.  This
             operator generally does not perform a bounds check.


For all Rogue Wave classes, operator[](int) always performs a bounds check on
its argument.


Some classes also support operator()(int).  Bounds checking is generally not
performed for this operator unless you define RWBOUNDS_CHECK before including
the header file.


          5  Member function reshape(int) changes the length of the vector.











Rogue Wave              Tools.h++   V 5.0   Supplement  8








                                                               Templates



If a vector is lengthened using reshape(int), then the values of the new
elements are undefined.


If a vector is lengthened using resize(int), then the new values are
initialized to something sensible, generally zero or blanks.


All Rogue Wave vectors work this way.


6    Finally, the last 10 elements are initialized to 3.0.

1.6  A more complicated example


Here's another example, this one involving a hashing dictionary.
          BEGIN FILE: exam2.cpp
          #include <rw/tvhdict.h>
          #include <rw/cstring.h>
          #include <iostream.h>
          #include <iomanip.h>

          class Count {               // 1
            int           N;
          public:
            Count() : N(0){ }         // 2
            int           operator++()  { return ++N; } // 3
            operator      int() { return N; }           // 4
          };

          unsigned hashString ( const RWCString& str )  // 5
            { return str.hash(); }

          main() {

            RWTValHashDictionary<RWCString,Count> map(hashString);    // 6

            RWCString token;
            while ( cin >> token )    // 7
              ++map[token];                             // 8


Rogue Wave              Tools.h++   V 5.0   Supplement  9








                                                               Templates

            RWTValHashDictionaryIterator<RWCString,Count> next(map);  // 9

            cout.setf(ios::left, ios::adjustfield);    // 10
            while ( ++next )          // 11
              cout << setw(20) << next.key()
                << " " << setw(10) << next.value() << endl;// 12

            return 0;
          }
          END FILE

Program input:
          How much wood could a woodchuck chuck if a woodchuck could chuck
          wood ?

Program output:
          much                 1
          wood                 2
          a                    2
          if                   1
          woodchuck            2
          could                2
          chuck                2
          How                  1
          ?                    1

The problem is to read an input file, break it up into tokens separated
by whitespace, count the number of occurences of each token and print
the results.  The general approach is to use a dictionary to map each
token to its respective count.  Here's a line-by-line description:
          1  This is a class used as the value part of the dictionary.
          2  A default constructor is supplied that zeroes out the count.
          3  We supply a prefix increment operator.  This will be used to
             increment the count in a convenient and pleasant way.
          4  A conversion operator is supplied that allows Count to be
             converted to an int.  This will be used to print the results.
             Alternatively, we could have supplied an overloaded operator<<()
             to teach a Count how to print itself, but this is easier.
          5  This is a function that must be supplied to the dictionary
             constructor.  Its job is to return a hash value given an
             argument of the type of the key.
          6  Here the dictionary is constructed.  Given a key, the dictionary
             will be used to look up a value.  In this case, the key will be
             of type RWCString, the value of type Count.  The constructor

Rogue Wave              Tools.h++   V 5.0   Supplement  10








                                                               Templates

             requires a single argument: a pointer to a function that will
             return a hash value, given a key.  This function was defined on
             line 5 above.
          7  Tokens are read from the input stream into a RWCString.  This
             will continue until an EOF is encountered.  How does this work?
             The expression "cin >> token" reads a single token and returns
             an ostream&.  Class ostream has a type conversion operator to
             void* which is what the while loop will actually be testing.
             Operator void* returns "this" if the stream state is "good",
             otherwise zero.  Because an EOF causes the stream state to turn
             to "not good", the while loop will be broken when an EOF is
             encountered.  See the RWCString entry in the class reference
             guide and the ios entry in the class reference guide that comes
             with your compiler for more details.
          8  Here's where all the magic occurs.  Object map is the
             dictionary.  It has an overloaded operator[] that takes an
             argument of the type of the key and returns a reference to its
             associated value.  Recall that the type of the value is a Count.
             Hence, map[token] will be of type Count.  As we saw on line 3,
             Count has an overloaded prefix increment operator.  This is
             invoked on the Count, thereby increasing its value.
             What if the key isn't in the dictionary?  Then the overloaded
             operator[] will insert it, along with a brand new value built
             using the default constructor of the value's class.  This was
             defined on line 2 to initialize the count to zero.
          9  Now it comes time to print the results.  We start by defining an
             iterator that will sweep over the dictionary, returning each key
             and value.
          10 The "field width" of the output stream is adjusted to make
             things pretty.
          11 The iterator is advanced until it reaches the end of the
             collection.  For all template iterators, the prefix increment
             operator advances the iterator then tests whether it has gone
             past the end of the collection.
          12 The key and value at the position of the iterator are printed.










Rogue Wave              Tools.h++   V 5.0   Supplement  11

















                                  Tools.h++
                                     V5.0

                                  Supplement
                                    to the
                            Class Reference Guide










GOrderedVector(val)GOrderedVector(val)





Synopsis     #include <rw/gordvec.h>
             declare(GVector,val)
             declare(GOrderedVector,val)
             implement(GVector,val)
             implement(GOrderedVector,val)

             GOrderedVector(val) v; // Ordered vector of objects of type val.


DescriptionClass GOrderedVector(val) represents an ordered collection of
           objects of type val.  Objects are ordered by the order of
           insertion and are accessible by index.  Duplicates are allowed.
           GorderedVector(val) is implemented as a vector, using macros
           defined in the standard C++ header file <generic.h>.
           To use this class you must declare and implement its base class as
           well as the class itself.  For example, here is how you declare and
           implement an ordered collection of doubles:
          declare(GVector,double)     // Declare base class
          declare(GOrderedVector,double)// Declare ordered vector

          // In one and only one .cpp file you must put the following:
          implement(GVector,double)   // Implement base class
          implement(GOrderedVector,double)// Implement ordered vector

          For each type of GOrderedVector you must include one (and only
          one) call to the macro implement somewhere in your code for
          both the GOrderedVector itself and for its base class GVector.
Example

Here's an example that uses an ordered vector of RWCStrings.
          BEGIN FILE: gordvec.cpp
          #include <rw/gordvec.h>
          #include <rw/cstring.h>
          #include <rw/rstream.h>

          declare(GVector,RWCString)
          declare(GOrderedVector,RWCString)
          implement(GVector,RWCString)
          implement(GOrderedVector,RWCString)








                                                     GOrderedVector(val)



          main()
          {
            GOrderedVector(RWCString) vec;

            RWCString one("First");
            vec.insert(one);

            vec.insert("Second");// Automatic type conversion occurs
            vec.insert("Last");// Automatic type conversion occurs

            for(int i=0; i<vec.length(); i++)  cout << vec[i] << NL;

            return 0;
          }
          END FILE

Program output:

          First
          Second
          Last

Public      GOrderedVector(val)(unsigned capac=RWDEFAULT_CAPACITY);
constructors


        Construct an ordered vector of elements of type val.  The initial
        capacity of the vector will be capac whose default value is
        RWDEFAULT_CAPACITY.  The capacity will be automatically increased as
        necessary should too many items be inserted, a relatively expensive
        process because each item must be copied into the new storage.

Public member  val               operator()(int i) const;
functions      val&              operator()(int i);


        Return the i'th value in the vector.  The index i must be between 0
        and the length of the vector less one.  No bounds checking is
        performed.




Rogue Wave              Tools.h++   V 5.0   Supplement  15








                                                     GOrderedVector(val)


          val     operator[](int i) const;
          val&    operator[](int i);
       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 will be
       performed.
          void    clear();
       Remove all items from the collection.
          unsignedentries() const;
       Return the number of items currently in the collection.
          int     index(val item) const;
       Performs a linear search of the collection returning the index of the
       first item that isEqual to the argument item.  If no item is found,
       then it returns -1.
          void    insert(val item);
       Add the new value item to the end of the collection.
          void    insertAt(int indx, val item);
       Add the new value item to the collection at position indx.  The value
       of indx must be between zero and length of the collection.  Old items
       from index indx upwards will be shifted to higher indices.  E.g., the
       old item at position indx will be moved to position indx+1, etc.
          RWBoolean      isEmpty() const;
       Return TRUE if the collection has no entries.  FALSE otherwise.
          unsignedlength() const;
       Return the number of items in the collection.
          void    removeAt(int indx);
       Remove the item at position indx from the collection.  The value of
       indx must be between zero and the length of the collection less one.
       Old items from index indx+1 will be shifted to lower indices.  E.g.,
       the item at index indx+1 will be moved to position indx, etc.
          void    resize(unsigned newCapacity);
       Change the capacity of the collection to newCapacity, which must be at
       least as large as the present number of items in the collection.  Note
       that the actual number of items in the collection does not change,
       just the capacity.










Rogue Wave              Tools.h++   V 5.0   Supplement  16











RWBenchRWBench


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


Descrip-  This is an abstract class that can automate the process of
          benchmarking a piece of code.  To use it, derive a class from RWBench
tion      including a definition for the virtual function doLoop(unsigned long
          N).  This function should perform N operations of the type that you
          are trying to benchmark.  RWBench will call doLoop() over and over
          again until a preset amount of time has elapsed.  It will then sum
          the total number of operations performed.
         To run, construct an instance of your derived class and then call
         go().  Then call report() to get a standard summary.  For many
         compilers, this summary will automatically include the compiler type
         and memory model.  You can call ops(), outerLoops(), etc. for more
         detail.
         If you wish to correct for overhead, then provide an idleLoop()
         function which should do non-benchmark related calculations.
Example   This example benchmarks the time required to return a hash
          value for a Rogue Wave string versus a Borland string.

          BEGIN FILE: bench.cpp

          #define RWNO_STD_TYPEDEFS 1
          #include <rw/bench.h>                                  /* Benchmark
          software */
          #include <rw/cstring.h>/* Rogue Wave string class */
          #include <strng.h>      /* Borland string class */
          #include <stdlib.h>

          // The string to be hashed:
          const char* cs = "A 22 character string.";

          class TestBCCString : public RWBench {
          public:
            TestBCCString() { }
            virtual void   doLoop(unsigned long n);
            virtual void   idleLoop(unsigned long n);
            virtual void   what(ostream& s) const
              { s << "Borland hashing string \"" << cs << "\"\n"; }
          };









                                                                 RWBench


          class TestRWCString : public RWBench {
          public:
            TestRWCString() { }
            virtual void   doLoop(unsigned long n);
            virtual void   idleLoop(unsigned long n);
            virtual void   what(ostream& s) const
              { s << "Rogue Wave hashing string \"" << cs << "\"\n"; }
          };

          main(int argc, char* argv[])
          {
            cout << "Testing string \"" << cs << "\"\n\n";

            // Test Borland strings:
            TestBCCString bccstring;
            bccstring.parse(argc, argv);
            bccstring.go();
            bccstring.report(cout);

            // Test RW Strings:
            TestRWCString rwstring;
            rwstring.parse(argc, argv);
            rwstring.go();
            rwstring.report(cout);

            return 0;
          }

          void TestBCCString::doLoop(unsigned long n){
            String string(cs);
            hashValueType h;
            while(n--){
              h = string.hashValue();
            }
          }

          void TestRWCString::doLoop(unsigned long n){
            RWCString string(cs);
            unsigned h;
            while(n--){
              h = string.hash();
            }
          }


Rogue Wave              Tools.h++   V 5.0   Supplement  18









                                                                 RWBench


          void TestBCCString::idleLoop(unsigned long n){
            String string(cs); // Subtract out constructor time
            hashValueType h;
            while(n--){ /* No-op */ }
          }

          void TestRWCString::idleLoop(unsigned long n){
            RWCString string(cs);// Subtract out constructor time
            unsigned h;
            while(n--){ /* No-op */ }
          }
          END FILE

Program output:

          Testing string "A 22 character string."

          Borland C++ V3.0 Large memory model.

          Borland hashing string "A 22 character string."

          Iterations:                 163
          Inner loop operations:      1000
          Total operations:           163000
          Elapsed (user) time:        4.945055
          Kilo-operations per second: 32.962222

          Borland C++ V3.0 Large memory model.

          Rogue Wave hashing string "A 22 character string."

          Iterations:                 417
          Inner loop operations:      1000
          Total operations:           417000
          Elapsed (user) time:        4.835165
          Kilo-operations per second: 86.243182

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






Rogue Wave              Tools.h++   V 5.0   Supplement  19









                                                                 RWBench


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

Public     virtual void      doLoop(unsigned long N)=0;
member
functions


       A pure virtual function whose actual definition should be supplied by
       the specializing class. This function will be repeatedly called until
       a time duration has elapsed.  It should perform the operation to be
       benchmarked N times.  See the example.
          double  duration() const;
       Return the current current setting for the benchmark test duration.
       This should not be confused with function time() which returns the
       actual test time.
          virtual void   go();
       Call this function to actually run the benchmark.
          virtual void   idleLoop(unsigned long N);
       This function can help to correct the benchmark for overhead.  The
       default definition merely executes a "for()" loop N times.  See the
       example.
          virtual void   parse(int argc, char* argv[]);
       This function allows an easy way to change the test duration, number
       of inner loops and machine description from the command line:
               Argument   Type              Description

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

          virtual void   report(ostream&) const;
       Calling this function provides an easy and convenient way of getting
       an overall summary of the results of a benchmark.
          double  setDuration(double t);
       Change the test duration to time t.


Rogue Wave              Tools.h++   V 5.0   Supplement  20









                                                                 RWBench


          unsigned long  setInnerLoops(unsigned long N);
       Change the number of "inner loop operations" to N.
          virtual void   what(ostream&) const;
       You can supply a specializing version of this virtual function that
       provides some detail of what is being benchmarked.  It is called by
       report() when generating a standard report.
          void    where(ostream&) const;
       This function will print information to the stream about the compiler
       and memory model that the code was compiled under.
          unsigned long  innerLoops() const;
       Returns the current setting for the number of inner loop operations
       that will be passed into function doLoop(unsigned long N) as parameter
       N.
          double  time() const;
       Returns the amount of time the benchmark took, corrected for overhead.
          unsigned long  outerLoops() const;
       Returns the number of times the function doLoop() was called.
          double  ops() const;
       Returns the total number of inner loop operations that were performed
       (the product of the number of times outerLoop() was called times the
       number of inner loop operations performed per call).
          double  opsRate() const;
       Returns the number of inner loop operations per second.






















Rogue Wave              Tools.h++   V 5.0   Supplement  21










RWBufferedPageHeapRWBufferedPageHeap                       RWBufferedPageHeap
                                                                   |
                                                           RWVirtualPageHeap



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


Descripti This is an abstract base class that represents an abstract
on        page heap buffered through a set of memory buffers.  It
          inherits from the abstract base class RWVirtualPageHeap which
          represents an abstract page heap.
          RWBufferedPageHeap will supply and maintain a set of memory
          buffers.  Specializing classes should supply the actual
          physical mechanism to swap pages in and out of these buffers
          by supplying definitions for the pure virtual functions
          swapIn(RWHandle, void*) and swapOut(RWHandle, void*).
          The specializing class should also supply appropriate definitions
          for the public functions allocate() and deallocate(RWHandle).
         For a sample implementation of a specializing class, see class
         RWDiskPageHeap.
Public    RWBufferedPageHeap(unsigned pgsize, unsigned nbufs=10);
constructo
r


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

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


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








                                                      RWBufferedPageHeap


Public    virtual RWHandle  allocate() = 0;
member
functions


          It is the responsibility of the specializing class to supply a
          definition for this pure virtual function.  The specializing class
          should allocate a page and return a unique handle for it.  It should
          return zero if it cannot satisfy the request.  The size of the page
          is set by the constructor.
          virtual ~RWBufferedPageHeap();
       Deallocates all internal buffers.

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

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











Rogue Wave              Tools.h++   V 5.0   Supplement  23










RWCStringRWCString





Synopsis  #include <cstring.h>
          RWCString a;


Description  Class RWCString replaces class RWString, used in previous
          versions of Tools.h++.  It is very similar, the only difference
          being that its copy constructor and assignment operator use copy
          semantics, rather than reference semantics.
          The class is implemented using a technique called copy on write.
          With this technique, the copy constructor and assignment operators
          still reference the old object and hence are very fast.  An actual
          copy is made only when a "write" is performed, that is if the object
          is about to be changed.  The net result is excellent performance,
          but with easy to understand copy semantics.
         A separate RWCSubString 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 <rw/cstring.h>
          #include <rw/regexp.h>
          #include <rw/rstream.h>

          main()
          {
            RWCString 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.








                                                               RWCString


Public    RWCString();
construct
ors


          Constructs a RWCString with zero characters (the null string).
          RWCString(const char* cs);
       Conversion from  a null-terminated character string.  The created
       string will copy the data pointed to by cs.
          RWCString(const char* cs, int N);
       Constructs a string from the (possibly) null terminated character
       string cs.  The created string will copy the data pointed to by cs.
       At most N characters (not including the terminating null) will be
       copied.
          RWCString(const RWCString& str);
       Copy constructor.  The created string will copy str's data.
          RWCString(const RWCSubString& ss);
       Conversion from sub-string.  The created string will copy the
       substring represented by ss.
          RWCString(unsigned N, char c = ' ');
       Constructs a RWCString with N characters, all initialized to the
       character c (default blank).

Type      operator          const char*() const;
conversion


          Returns self as a null-terminated string.

AssignmentRWCString&        operator=(const RWCString& str);
operators


          Assignment operator.  The string will copy str's data.
          RWCString&     operator+=(const RWCString& str);
       Append the string str to self.
          RWCString&     operator+=(const char* cs);
       Append the character string pointed to by cs to self.

Indexing  char&             operator[](int i);
operators



Rogue Wave              Tools.h++   V 5.0   Supplement  25








                                                               RWCString


       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.
          RWCSubString   operator()(int start, unsigned len);
       Substring operator.  Returns a RWCSubString 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 RWCSubString  operator()(int start, unsigned len) const;
       Returns a RWCSubString 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.
          RWCSubString   operator()(const RWRegexp& re, int start=0);
       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 can be used as an lvalue.
          const RWCSubString  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.



Rogue Wave              Tools.h++   V 5.0   Supplement  26








                                                               RWCString



Logical   RWBoolean         operator==(const char*) const;
operators RWBoolean         operator!=(const char*) const;
          RWBoolean         operator==(const RWCString&) const;
          RWBoolean         operator!=(const RWCString&) 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 RWCString&) const;
          RWBoolean      operator<(const RWCString&) const;
          RWBoolean      operator>=(const RWCString&) const;
          RWBoolean      operator<=(const RWCString&) const;
       Other logical operators.  Comparisons are done lexicographically.
       Case sensitivity is set by the static member function
       setCaseSensitive().

Public   RWCString&         append(const char* cs, unsigned N);
member
functions


       Append the (possibly) null terminated character string cs to self.  At
       most, the first N characters of the string (not including the
       terminating null) will be used.  A copy of cs will be made.
          unsignedbinaryStoreSize() const;
       Returns the number of bytes necessary to store the object using the
       function RWCString::saveOn(RWFile&).
          int     compareTo(const RWCString& 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* cs) const;
       Pattern matching.  Returns TRUE if the string pointed to by cs occurs
       in self.  Case sensitivity is set by the static member function
       setCaseSensitive().
          RWBoolean      contains(const RWCString& str) const;
       Pattern matching.  Returns TRUE if str occurs in RWCString.  Case
       sensitivity is set by the static member function setCaseSensitive().

Rogue Wave              Tools.h++   V 5.0   Supplement  27








                                                               RWCString


          const char*    data() const;
       Access to the RWCString's data as a null terminated string.  Must be
       used with care.
          int     first(char c) const;
       Returns the index of the first occurence of the character c in self.
       Returns -1 if there is no such character.
          unsignedhash() const;
       Returns a suitable hash value.
          int     index(const char* cs, 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 cs 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 RWCString& 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.
          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.
          unsignedlength() const;
       Return the number of characters in self.


Rogue Wave              Tools.h++   V 5.0   Supplement  28








                                                               RWCString


          RWCString&     prepend(const char* cs);
       Prepend the string pointed to by cs to self.  A copy of cs will be
       made.
          RWCString&     prepend(const char* cs, unsigned N);
       Prepend the (possibly) null terminated character string cs to self.
       At most, the first N characters of the string (not including the
       terminating null) will be used.  A copy of cs will be made.
          RWCString&     prepend(const RWCString& str);
       Prepends the string str to self.
          istream&readFile(istream& s);
       Read an entire file into self from the input stream s, replacing the
       previous contents of self.  Read to an EOF or null terminator,
       whichever comes first.
          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 (or an EOF) is encountered. The newline is
       removed from the input stream but is not stored.
          istream&readToDelim(istream&, char delim='\n');
       Reads up to an EOF or the delimiting character delim, whichever comes
       first.  The delimiter is not stored in the string, but is removed from
       the input stream.

          istream&readToken(istream& s);
       Whitespace is skipped before saving characters. Characters are then
       read from the input stream s until whitespace or an EOF 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.
          void    restoreFrom(RWvistream& s);
       Reads an RWCString from the input stream s that had been stored using
       saveOn(RWvostream&).
          void    restoreFrom(RWFile& f);
       Reads an RWCString from the RWFile f that had been stored using
       storeOn(RWFile&).
          void    saveOn(RWvostream& s) const;
       Stores an RWCString on the output stream s.
          void    saveOn(RWFile& f) const;
       Stores an RWCString in binary format on the RWFile f.
          RWCSubString   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:

Rogue Wave              Tools.h++   V 5.0   Supplement  29








                                                               RWCString


               stripType      Meaning
               leading        Remove characters at beginning
               trailing       Remove characters at end
               both           Remove characters at both ends
          RWCSubString   subString(const char* cs, int start=0);
          const RWCSubString  subString(const char* cs, int start=0) const;
       Returns a substring representing the first occurence of the string
       pointed to by "cs".  Case sensitivity is set by the static member
       function setCaseSensitive().  See member function index() for
       additional information on how the match is performed.
          void    toLower();
       Changes all upper-case letters in self to lower-case.
          void    toUpper();
       Changes all lower-case letters in self to upper-case.

Static    static unsigned   initialCapacity(unsigned ic = 63);
public
member
functions


       Sets the minimum initial capacity of an RWCString. The initial setting
       is 63 characters. Larger values will use more memory, but result in
       fewer resizes when concatenating or reading strings. Smaller values
       will waste less memory, but result in more resizes.
          Static 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.




Rogue Wave              Tools.h++   V 5.0   Supplement  30








                                                               RWCString


          static RWBoolean    skipWhitespace(RWBoolean s = TRUE);
       Sets whether white space is skipped before reading a line.  The
       initial setting is TRUE.  See function readLine() for additional
       details.

Related   RWCString         operator+(const RWCString&, const RWCString&);
global    RWCString         operator+(const char*, const RWCString&);
operators RWCString         operator+(const RWCString&, const char*);


          Concatenation operators.
          ostream&operator<<(ostream& s, const RWCString&);
       Output a RWCString on ostream s.
          istream&operator>>(istream& s, RWCString& str);
       Calls str.readToken(s).  That is, a token is read from the input
       stream s.
          RWCString      toLower(const RWCString& str);
       Returns a version of str where all upper-case characters have been
       replaced with lower-case characters.
          RWCString      toUpper(const RWCString& str);
       Returns a version of str where all lower-case characters have been
       replaced with upper-case characters.






















Rogue Wave              Tools.h++   V 5.0   Supplement  31










RWDiskPageHeapRWDiskPageHeap                        RWDiskPageHeap
                                                           |
                                                  RWBufferedPageHeap
                                                           |
                                                   RWVirtualPageHeap

Synopsis   #include <rw/diskpage.h>
           unsigned nbufs;
           unsigned pagesize;
           RWDiskPageHeap heap("filename", nbufs, pagesize);


Description  Class RWDiskPageHeap is a specializing type of buffered page heap.
          It swaps its pages to disk as necessary.


Example   In this example, 100 nodes of a linked list are created and strung
          together.  The list is then walked, confirming that it contains 100
          nodes.  Each node is a single page.  The "pointer" to the next node
          is actually the handle for the next page.
          BEGIN FILE: diskpage.cpp
          #include <rw/diskpage.h>
          #include <rw/rstream.h>

          struct Node {
            int     key;
            RWHandle                                   next;
          };

          RWHandle head = 0;

          const int N = 100;           // Exercise 100 Nodes

          main() {

            // Construct a disk-based page heap with page size equal
            // to the size of Node and with 10 buffers:
            RWDiskPageHeap heap(0, 10, sizeof(Node));

            // Build the linked list:
            for (int i=0; i<N; i++){
              RWHandle h = heap.allocate();
              Node* newNode = (Node*)heap.lock(h);
              newNode->key  = i;
              newNode->next = head;








                                                          RWDiskPageHeap


              head = h;
              heap.dirty(h);
              heap.unlock(h);
            }

            // Now walk the list:
            unsigned count = 0;
            RWHandle nodeHandle = head;
            while(nodeHandle){
              Node* node = (Node*)heap.lock(nodeHandle);
              RWHandle nextHandle = node->next;
              heap.unlock(nodeHandle);
              heap.deallocate(nodeHandle);
              nodeHandle = nextHandle;
              count++;
            }

            cout << "List with " << count << " nodes walked.\n";
            return 0;
          }
          END FILE

Program output:
          List with 100 nodes walked.

Public    RWDiskPageHeap(const char* filename=0,
constructor          unsigned nbufs=10,
          unsigned pgsize=512);
       Constructs a new disk-based page heap.  The heap will use a file with
       filename filename, otherwise it will negotiate with the operating
       system for a temporary filename.  The number of buffers, each the size
       of the page size, will be nbufs.  No more than this many pages can be
       locked at any one time.  The size of each page is given by pgsize.  To
       see whether a valid RWDiskPageHeap has been constructed, call member
       function isValid().
          virtual ~RWDiskPageHeap();
       Returns any resources used by the disk page heap back to the operating
       system.  All pages should have been deallocated before the destructor
       is called.
          RWBoolean      isValid() const;
       Returns TRUE if this is a valid RWDiskPageHeap.



Rogue Wave              Tools.h++   V 5.0   Supplement  33








                                                          RWDiskPageHeap


Public    virtual RWHandle  allocate();
member
functions


       Redefined from class RWVirtualPageHeap.  Allocates a page off the disk
       page heap and returns a handle for it.  If there is no more space (for
       example, the disk is full) then returns zero.
          virtual void   deallocate(RWHandle h);
       Redefined from class RWBufferedPageHeap.  Deallocate the page
       associated with handle h.  It is not an error to deallocate a zero
       handle.
          virtual void   dirty(RWHandle h);
       Inherited from RWBufferedPageHeap.
          virtual void*  lock(RWHandle h);
       Inherited from RWBufferedPageHeap.
          virtual void   unlock(RWHandle h) = 0;
       Inherited from RWBufferedPageHeap.


























Rogue Wave              Tools.h++   V 5.0   Supplement  34










RWModelRWModel


Synopsis   #include <rw/model.h>
           (abstract base class)


Description          This abstract base class has been designed to implement a
          dependency hierarchy.  It maintains a list of dependents and,
          in turn, it can be a dependent of another instance of
          RWModel.  You should subclass off of it to supply the actual
          functionality.  It is intended to be a base class for both
          the "Model" and "View" legs of a Model-View-Controller
          architecture.
          When member function changed() is called, the list of dependents
          will be traversed, calling updateFrom(RWModel*) for each one, with
          itself as the argument.  Classes subclassing off RWModel should be
          prepared to accept such a call

Example   This is an incomplete and somewhat contrived example in that it does
          not completely define the classes involved.  "Dial" is assumed to be
          a graphical representation of the internal settings of "Thermostat".
          The essential point is that there is a dependency relationship
          between the "Thermostat" and the "Dial": when the setting of the
          thermostat is changed, the dial must be notified so that it can
          update itself from the new setting of the thermostat.

          BEGIN FILE: model.cpp
          #include <rw/model.h>

          class Dial : public RWModel {
          public:
            virtual void   updateFrom(RWModel* m);
          };


          class Thermostat : public RWModel {
            double         setting;
          public:
            Thermostat( Dial* d )
              { addDependent(d); }
            double         temperature() const
              { return setting; }
            void           setTemperature(double t)
              { setting = t; changed(); }








                                                                 RWModel


            virtual void   updateFrom(RWModel*)
              { /* No-op: not dependent on anything */ }
          };

          void Dial::updateFrom(RWModel* m){
            Thermostat* t = (Thermostat*)m;
            double temp = t->temperature();
            // Redraw graphic.
          }
          END FILE

Public constructor    RWModel();


       When called by the specializing class, sets up the internal ordered
       list of dependents.
          void    addDependent(RWModel* m);
       Adds the object pointed to by m to the list of dependents of self.
          void    removeDependent(RWModel* m);
       Removes the object pointed to by m from the list of dependents of
       self.
          virtual void   changed();
       Traverse the internal list of dependents, calling member function
       updateFrom(RWModel*) for each one, with self as the argument.
          virtual void   updateFrom(RWModel* p) = 0;
       Deriving classes should supply an appropriate definition for this pure
       virtual function.  The overall semantics of the definition should be
       to update self from the data presented by the object pointed to by p.
       That is, self is considered a dependent of the object pointed to by p.















Rogue Wave              Tools.h++   V 5.0   Supplement  36










RWTBitVec<size>RWTBitVec<size>


Synopsis  #include <rw/tbitvec.h>
          RWTBitVec<22>      // A 22 bit long vector


          RWTBitVec<size> is a parameterized bit vector of fixed length
          size.  Unlike class RWBitVec, its length cannot be changed at
          run time.  Its advantage of RWBitVec is its smaller size, and
          one less level of indirection, resulting in a slight speed
          advantage.
          Bits are numbered from 0 through size-1, inclusive.
         The copy constructor and assignment operator use copy semantics.

Example   In this example, a bit vector 24 bits long is exercised:

          #include <rw/tbitvec.h>

          main()
          {
            RWTBitVec<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.
            RWTBitVec<24> c = a ^ b;// Set c to the XOR of a and b.
          }

Public    RWTBitVec<size>();
constructo
r


          Constructs an instance with all bits set to FALSE.
          RWTBitVec<size>(RWBoolean val);
       Constructs an instance with all bits set to val.
Assignment         RWTBitVec<size>&   operator=(const RWTBitVec<size>& v);
operators


          Sets self to a copy of v.
          RWTBitVec&     operator=(RWBoolean val);
       Sets all bits in self to the value val.








                                                         RWTBitVec<size>


          RWTBitVec&     operator&=(const RWTBitVec& v);
          RWTBitVec&     operator^=(const RWTBitVec& v)
          RWTBitVec&     operator|=(const RWTBitVec& v)
       Logical assignments.  Sets each bit of self to the logical AND, XOR,
       or OR, respectively, of self and the corresponding bit in v.
          RWBitRefoperator[](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 size-1,
       inclusive.  Bounds checking will occur.
          RWBitRefoperator()(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 size-1,
       inclusive.  No bounds checking is done.

Logical   RWBoolean         operator==(RWBoolean b) const;
operators


       Returns TRUE if every bit of self is set to the value b.  Otherwise,
       returns FALSE.
          RWBoolean      operator!=(RWBoolean b) const;
       Returns TRUE if any bit of self is not set to the value b.  Otherwise,
       returns FALSE.
          RWBoolean      operator==(const RWTBitVec& v) const;
      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 RWTBitVec& v) const;
       Returns TRUE if any bit of self is not set to the same value as the
       corresponding bit in v.  Otherwise, returns FALSE.
          void    clearBit(int i);
       Clears (i.e., sets to FALSE) the bit with index i.  The index i must
       be between 0 and size-1.  No bounds checking is performed.  The
       following two lines 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

Rogue Wave              Tools.h++   V 5.0   Supplement  38








                                                         RWTBitVec<size>


       two lines 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( a.testBit(i) ) doSomething();

Related  RWTBitVec operator&(const RWTBitVec& v1, const RWTBitVec& v2);
global   RWTBitVec operator^(const RWTBitVec& v1, const RWTBitVec& v2);
functionsRWTBitVec operator|(const RWTBitVec& v1, const RWTBitVec& v2);


      Return the logical AND, XOR, and OR, respectively, of vectors v1 and v2.

























Rogue Wave              Tools.h++   V 5.0   Supplement  39










RWTimerRWTimer


Synopsis   #include <rw/timer.h>
           RWTimer timer;

Description

This class can measure elapsed real (wall clock) time.  The timer has
two states: running and stopped.  The timer measures the total amount
of time spent in the "running" state since it was either constructed or
reset.
The timer is put into the "running" state by calling member function
start().  It is put into the "stopped" state by calling stop().
Example

This example times the amount of time that elapsed during a 5 second sleep
and a 2 second sleep.  Note that Microsoft C/C++ does not implement sleep().
          BEGIN FILE: timer.cpp
          #include <rw/timer.h>
          #include <rw/rstream.h>
          #ifdef __MSDOS__
          #  include <dos.h>       /* Looking for sleep() */
          #else
          #  include <unistd.h>
          #endif

          main()
          {
            RWTimer t;

            t.start();
            sleep(5);      // Sleep 5 seconds while in running state
            t.stop();
            sleep(8);      // Sleep 8 seconds while in stopped state
            t.start();
            sleep(2);      // Sleep 2 seconds while in running state
            t.stop();
            cout << t.elapsedTime() << NL;
            return 0;
          }
          END FILE
Program output:
          7.02936








                                                                 RWTimer


Public
constructor

          RWTimer();
       Constructs a new timer.  The timer will not start running until
       start() is called.
          double  elapsedTime() const;
       Returns the amount of (wall clock) time that has accumulated while the
       timer was in the running state.
          void    reset();
       Resets (and stops) the timer.
          void    start();
       Puts the timer in the "running" state.  Time accumulates while in this
       state.
          void    stop();
       Puts the timer in the "stopped" state.  Time will not accumulate while
       in this state.



























Rogue Wave              Tools.h++   V 5.0   Supplement  41










RWTIsvDlist<T>RWTIsvDlist<T>


Synopsis   #include <rw/tidlist.h>
           RWTIsvDlist<T> list;

Description
       Class RWTIsvDlist<T> is a class that implements intrusive singly-
       linked lists.
       An intrusive list is one where the member of the list must
       inherit from a common base class, in this case RWIsvDlink.  The
       advantage of such a list is that memory and space requirements
       are kept to a minimum.  The disadvantage is that the inheritance
       hierarchy is inflexible, making it slightly more difficult to use
       with an existing class.  Class RWTValDlist<T> is offered as an
       alternative, non-intrusive, linked list.
See Stroustrup (1991; Section 8.3.1) for more information about intrusive
lists.


Note that when you insert an item into an intrusive list, the actual item
(not a copy) is inserted.  Because each item carries only one link field, the
same item cannot be inserted into more than one list, nor can it be inserted
into the same list more than once.



Example   BEGIN FILE: tidlist.cpp
          #include <rw/tidlist.h>
          #include <rw/rstream.h>
          #include <string.h>

          struct Symbol : public RWIsvSlink {
            char name[10];
            Symbol( const char* cs)
              { strncpy(name, cs, sizeof(name)); name[9] = '\0'; }
          };

          void printem(Symbol* s, void*) { cout << s->name << NL; }

          main(){
            RWTIsvDlist<Symbol> list;
            list.insert( new Symbol("one") );
            list.insert( new Symbol("two") );
            list.prepend( new Symbol("zero") );








                                                          RWTIsvDlist<T>


            list.apply(printem, 0);
            list.clearAndDestroy();// Deletes the items inserted into the list
            return 0;
          }
          END FILE

Program Output:
          zero
          one
          two

Public    RWTIsvDlist();
constructors


       Constructs an empty list.
          RWTIsvDlist(T* a);
       Constructs a list with the single item pointed to by a in it.
          void    append(T* a);
       Appends the item pointed to by a to the end of the list.
          void    apply(void (*applyFun)(T*, void*), void* d);
       Calls the function pointed to by applyFun to every item in the
       collection.  This must have the prototype:
            void  yourFun(T* item, void* d);
       The item will be passed in as argument item.  Client data may be
       passed through as parameter d.
          T*      at(int i) const;
       Returns the item at index i, or nil if the index is an invalid index.
       Valid indices are between zero and the number of items in the list,
       less one.
          void    clear();
       Removes all items from the list.
          void    clearAndDestroy();
       Removes and calls delete for each item in the list.  Note that this
       assumes that each item was allocated off the heap.
          RWBoolean      contains(RWBoolean (*testFun)(const T*, void*), void*
          d) const;
       Returns TRUE if the list contains an item for which the user-defined
       "tester" function pointed to by testFun returns TRUE .  The tester
       function must have the prototype:
            RWBoolean  yourTester(const T* item, void* d);



Rogue Wave              Tools.h++   V 5.0   Supplement  43








                                                          RWTIsvDlist<T>


       For each item in the list this function will be called with the item
       as the first argument.  Client data may be passed through as parameter
       d.
          RWBoolean      containsReference(const T* a) const;
       Returns TRUE if the list contains an item with the address a.
          unsignedentries() const;
       Returns the number of items currently in the list.
          T*      find(RWBoolean (*testFun)(const T*, void*), void* d) const;
       Returns the first item in the list for which the user-defined "tester"
       function pointed to by testFun returns TRUE.  If there is no such
       item, then returns nil.  The tester function must have the prototype:
            RWBoolean  yourTester(const T* item, void* d);
       For each item in the list this function will be called with the item
       as the first argument.  Client data may be passed through as parameter
       d.
          T*      first() const;
       Returns (but does not remove) the first item in the list, or nil if
       the list is empty.
          T*      get();
       Returns and removes the first item in the list, or nil if the list is
       empty.
          int     index(RWBoolean (*testFun)(const T*, void*), void* d) const;
       Returns the index of the first item in the list for which the user-
       defined "tester" function pointed to by testFun returns TRUE.  If
       there is no such item, then returns -1.  The tester function must have
       the prototype:
            RWBoolean  yourTester(const T* item, void* d);
       For each item in the list this function will be called with the item
       as the first argument.  Client data may be passed through as parameter
       d.
          void    insert(T* a);
       Appends the item pointed to by a to the end of the list.  This item
       cannot be inserted into more than one list, nor can it be inserted
       into the same list more than once.
          void    insertAt(int i, T* a);
       Insert the item pointed to by a at the index position i.  This
       position must be between zero and the number of items in the list.
       The item cannot be inserted into more than one list, nor can it be
       inserted into the same list more than once.
          RWBoolean      isEmpty() const;
       Returns TRUE if there are no items in the list, FALSE otherwise.



Rogue Wave              Tools.h++   V 5.0   Supplement  44








                                                          RWTIsvDlist<T>


          T*      last() const;
       Returns (but does not remove) the last item in the list, or nil if the
       list is empty.
          unsignedoccurrencesOf(RWBoolean (*testFun)(const T*, void*), void*
          d) const;
       Traverses the list and returns the number of times for which the user-
       defined "tester" function pointed to by testFun returned TRUE .  The
       tester function must have the prototype:
            RWBoolean  yourTester(const T* item, void* d);
       For each item in the list this function will be called with the item
       as the first argument.  Client data may be passed through as parameter
       d.
          unsignedoccurrencesOfReference(const T* a) const;
       Returns the number of times which the item pointed to by a occurs in
       the list.  Because items cannot be inserted into a list more than
       once, this function can only return zero or one.
          void    prepend(T* a);
       Prepends the item pointed to by a to the beginning of the list.
          T*      remove(RWBoolean (*testFun)(const T*, void*), void* d);
       Removes and returns the first item for which the user-defined tester
       function pointed to by testFun returns TRUE, or nil if there is no
       such item.  The tester function must have the prototype:
            RWBoolean  yourTester(const T* item, void* d);
       For each item in the list this function will be called with the item
       as the first argument.  Client data may be passed through as parameter
       d.
          T*      removeAt(int i);
       Removes and returns the item at index i, or nil if the index is an
       invalid index.  Valid indices are between zero and the number of items
       in the list, less one.
          T*      removeFirst();
       Removes and returns the first item in the list, or nil if there are no
       items in the list.
          T*      removeLast();
       Removes and returns the last item in the list, or nil if there are no
       items in the list.
          T*      removeReference(const T* a);
       Removes and returns the item with address a, or nil if there is no
       such item.





Rogue Wave              Tools.h++   V 5.0   Supplement  45










RWTIsvSlist<T>RWTIsvSlist<T>


Synopsis  #include <rw/tislist.h>
          RWTIsvSlist<T> list;

Description
    Class RWTIsvSlist<T> is a class that implements intrusive singly-
    linked lists.
        An intrusive list is one where the member of the list must inherit
        from a common base class, in this case RWIsvSlink.  The advantage of
        such a list is that memory and space requirements are kept to a
        minimum.  The disadvantage is that the inheritance hierarchy is
        inflexible, making it slightly more difficult to use with an
        existing class.  Class RWTValSlist<T> is offered as an alternative,
        non-intrusive, linked list.
See Stroustrup (1991; Section 8.3.1) for more information about intrusive
lists.


Note that when you insert an item into an intrusive list, the actual item
(not a copy) is inserted.  Because each item carries only one link field, the
same item cannot be inserted into more than one list, nor can it be inserted
into the same list more than once.



Example   BEGIN FILE: tislist.cpp
          #include <rw/tislist.h>
          #include <rw/rstream.h>
          #include <string.h>

          struct Symbol : public RWIsvSlink {
            char name[10];
            Symbol( const char* cs)
              { strncpy(name, cs, sizeof(name)); name[9] = '\0'; }
          };

          void printem(Symbol* s, void*) { cout << s->name << NL; }

          main(){
            RWTIsvSlist<Symbol> list;
            list.insert( new Symbol("one") );
            list.insert( new Symbol("two") );
            list.prepend( new Symbol("zero") );








                                                          RWTIsvSlist<T>


            list.apply(printem, 0);
            list.clearAndDestroy();// Deletes the items inserted into the list
            return 0;
          }
          END FILE

Program Output:
          zero
          one
          two

Public    RWTIsvSlist();
constructors


          Constructs an empty list.
          RWTIsvSlist(T* a);
       Constructs a list with the single item pointed to by a in it.
          void    append(T* a);
       Appends the item pointed to by a to the end of the list.
          void    apply(void (*applyFun)(T*, void*), void* d);
       Calls the function pointed to by applyFun to every item in the
       collection.  This must have the prototype:
            void  yourFun(T* item, void* d);
       The item will be passed in as argument item.  Client data may be
       passed through as parameter d.
          T*      at(int i) const;
       Returns the item at index i, or nil if the index is an invalid index.
       Valid indices are between zero and the number of items in the list,
       less one.
          void    clear();
       Removes all items from the list.
          void    clearAndDestroy();
       Removes and calls delete for each item in the list.  Note that this
       assumes that each item was allocated off the heap.
          RWBoolean      contains(RWBoolean (*testFun)(const T*, void*), void*
          d) const;
       Returns TRUE if the list contains an item for which the user-defined
       "tester" function pointed to by testFun returns TRUE .  The tester
       function must have the prototype:
            RWBoolean  yourTester(const T* item, void* d);



Rogue Wave              Tools.h++   V 5.0   Supplement  47








                                                          RWTIsvSlist<T>


       For each item in the list this function will be called with the item
       as the first argument.  Client data may be passed through as parameter
       d.
          RWBoolean      containsReference(const T* a) const;
       Returns TRUE if the list contains an item with the address a.
          unsignedentries() const;
       Returns the number of items currently in the list.
          T*      find(RWBoolean (*testFun)(const T*, void*), void* d) const;
       Returns the first item in the list for which the user-defined "tester"
       function pointed to by testFun returns TRUE.  If there is no such
       item, then returns nil.  The tester function must have the prototype:
            RWBoolean  yourTester(const T* item, void* d);
       For each item in the list this function will be called with the item
       as the first argument.  Client data may be passed through as parameter
       d.
          T*      first() const;
       Returns (but does not remove) the first item in the list, or nil if
       the list is empty.
          T*      get();
       Returns and removes the first item in the list, or nil if the list is
       empty.
          int     index(RWBoolean (*testFun)(const T*, void*), void* d) const;
       Returns the index of the first item in the list for which the user-
       defined "tester" function pointed to by testFun returns TRUE.  If
       there is no such item, then returns -1.  The tester function must have
       the prototype:
            RWBoolean  yourTester(const T* item, void* d);
       For each item in the list this function will be called with the item
       as the first argument.  Client data may be passed through as parameter
       d.
          void    insert(T* a);
       Appends the item pointed to by a to the end of the list.  This item
       cannot be inserted into more than one list, nor can it be inserted
       into the same list more than once.
          void    insertAt(int i, T* a);
       Insert the item pointed to by a at the index position i.  This
       position must be between zero and the number of items in the list.
       The item cannot be inserted into more than one list, nor can it be
       inserted into the same list more than once.
          RWBoolean      isEmpty() const;
       Returns TRUE if there are no items in the list, FALSE otherwise.



Rogue Wave              Tools.h++   V 5.0   Supplement  48








                                                          RWTIsvSlist<T>


          T*      last() const;
       Returns (but does not remove) the last item in the list, or nil if the
       list is empty.
          unsignedoccurrencesOf(RWBoolean (*testFun)(const T*, void*), void*
          d) const;
       Traverses the list and returns the number of times for which the user-
       defined "tester" function pointed to by testFun returned TRUE .  The
       tester function must have the prototype:
            RWBoolean  yourTester(const T* item, void* d);
       For each item in the list this function will be called with the item
       as the first argument.  Client data may be passed through as parameter
       d.
          unsignedoccurrencesOfReference(const T* a) const;
       Returns the number of times which the item pointed to by a occurs in
       the list.  Because items cannot be inserted into a list more than
       once, this function can only return zero or one.
          void    prepend(T* a);
       Prepends the item pointed to by a to the beginning of the list.
          T*      remove(RWBoolean (*testFun)(const T*, void*), void* d);
       Removes and returns the first item for which the user-defined tester
       function pointed to by testFun returns TRUE, or nil if there is no
       such item.  The tester function must have the prototype:
            RWBoolean  yourTester(const T* item, void* d);
       For each item in the list this function will be called with the item
       as the first argument.  Client data may be passed through as parameter
       d.
          T*      removeAt(int i);
       Removes and returns the item at index i, or nil if the index is an
       invalid index.  Valid indices are between zero and the number of items
       in the list, less one.
          T*      removeFirst();
       Removes and returns the first item in the list, or nil if there are no
       items in the list.
          T*      removeLast();
       Removes and returns the last item in the list, or nil if there are no
       items in the list.  This function is relatively slow because removing
       the last link in a singly-linked list necessitates access to the next-
       to-the-last link, requiring the whole list to be searched.
          T*      removeReference(const T* a);
       Removes and returns the item with address a, or nil if there is no
       such item.



Rogue Wave              Tools.h++   V 5.0   Supplement  49










RWTQueue<T, C>RWTQueue<T, C>


Synopsis  #include <rw/tqueue.h>
          RWTQueue<T, C> queue;

Description          This class represents a parameterized queue.  Not only can
          the type of object inserted into the queue be parameterized,
          but also the implementation.
         Parameter T represents the type of object in the queue, either a
         class or built in type.  The class T must have:
          o  well-defined copy semantics (T::T(const T&) or equiv.);
          o  well-defined assignment semantics (T::operator=(const T&) or
             equiv.).
        Parameter C represents the class used for implementation.  Useful
        choices are RWTValSlist<T> or RWTValDlist<T>.  Vectors, such as
        RWTValOrderedVector<T>, can also be used, but tend to be less
        efficient at removing an object off the front of the list.

Example   In this example a queue of RWCStrings, implemented as a singly-
          linked list, is exercised.
          BEGIN FILE: tqueue.cpp
          #include <rw/tqueue.h>
          #include <rw/cstring.h>
          #include <rw/tvslist.h>
          #include <rw/rstream.h>

          main() {
            RWTQueue<RWCString, RWTValSlist<RWCString> > queue;

            queue.insert("one");   // Type conversion occurs
            queue.insert("two");
            queue.insert("three");

            while (!queue.isEmpty())
              cout << queue.get() << NL;

            return 0;
          }
          END FILE

Program output
          one
          two
          three








                                                          RWTQueue<T, C>



Public    RWTQueue<T,C>();
constructor


          Construct an empty queue of objects of type T, implemented using
          class C.

Public   void              clear();
member
functions


          Removes all items from the queue.

          void                             entries() const;
          Returns the number of items in the queue.
          T       first() const;
       Returns, but does not remove, the first item in the queue (the item
       least recently inserted into the queue).
          T       get();
       Returns and removes the first item in the queue (the item least
       recently inserted into the queue).
          RWBoolean      isEmpty() const;
       Returns TRUE if there are no items in the queue, otherwise FALSE.
          void    insert(T a);
       Inserts the item a at the end of the queue.
          T       last() const;
       Returns, but does not remove, the last item in the queue (the item
       most recently inserted into the queue).














Rogue Wave              Tools.h++   V 5.0   Supplement  51










RWTStack<T, C>RWTStack<T, C>


Synopsis  #include <rw/tstack.h>
          RWTStack<T, C> stack;

Description          This class maintains a stack of values.  Not only can the
          type of object inserted onto the stack be parameterized, but
          also the implementation of the stack.
         Parameter T represents the type of object in the stack, either a
         class or built in type.  The class T must have:
          o  well-defined copy semantics (T::T(const T&) or equiv.);
          o  well-defined assignment semantics (T::operator=(const T&) or
             equiv.).
        Parameter C represents the class used for implementation.
        Useful choices are RWTValOrderedVector<T> or RWTValDlist<T>.
        Class RWTValSlist<T> can also be used, but note that singly-
        linked lists are less efficient at removing the last item of a
        list (function pop()), because of the necessity of searching
        the list for the next-to-the-last item.

Example   In this example a stack of ints, implemented as an ordered
          vector, is exercised.
          BEGIN FILE: tstack.cpp
          #include <rw/tstack.h>
          #include <rw/tvordvec.h>
          #include <rw/rstream.h>

          main() {

            RWTStack<int, RWTValOrderedVector<int> > stack;

            stack.push(1);
            stack.push(5);
            stack.push(6);

            while (!stack.isEmpty())
              cout << stack.pop() << NL;
            return 0;
          }
          END FILE

Program output:
          6
          5








                                                          RWTStack<T, C>


          1

Public    RWTStack<T,C>();
constructor


          Constructs an empty stack of objects of type T,
          implemented using class C.

Public    void              clear();
member
functions

          Removes all items from the stack.

          unsigned            entries() const;
       Returns the number of items currently on the stack.
          RWBoolean      isEmpty() const;
       Returns TRUE if there are currently no items on the stack, FALSE
       otherwise.
          void    push(T a);
       Push the item a onto the top of the stack.
          T       pop();
       Pop (remove and return) the item at the top of the stack.  If there
       are no items on the stack then an exception of type TOOL_INDEX will
       occur.
          T       top() const;
       Returns (but does not remove) the item at the top of the stack.
















Rogue Wave              Tools.h++   V 5.0   Supplement  53










RWTValDlist<T>RWTValDlist<T>


Synopsis   #include <rw/tvdlist.h>
           RWTValDlist<T> list;


Descripti This class maintains a collection of values, implemented as a
on        doubly linked list.  This is a value based list: objects are
          copied in and out of the links that make up the list.  Unlike
          intrusive lists (see class RWTIsvDlist<T>), the objects need
          not inherit from a link class.  However, this makes the class
          slightly less efficient than the intrusive lists because of
          the need to allocate a new link off the heap with every
          insertion and to make a copy of the object in the newly
          allocated link.
          Parameter T represents the type of object to be inserted into
          the list, either a class or built in type.  The class T must
          have:
          o  well-defined copy semantics (T::T(const T&) or equiv.);
          o  well-defined assignment semantics (T::operator=(const T&) or
             equiv.);
          o  well-defined equality semantics (T::operator==(const T&));

Example   In this example, a doubly-linked list of user type Dog is
          exercised.

          BEGIN FILE: tvdlist.cpp
          #include <rw/tvdlist.h>
          #include <rw/rstream.h>
          #include <string.h>

          class Dog {
            char* name;
          public:
            Dog( const char* c) {
             name = new char[strlen(c)+1];
             strcpy(name, c); }

            ~Dog() { delete name; }

            // Define a copy constructor:
            Dog(const Dog& dog) {
             name = new char[strlen(dog.name)+1];
             strcpy(name, dog.name); }








                                                          RWTValDlist<T>



            // Define an assignment operator:
            void operator=(const Dog& dog) {
             if (this!=&dog) {
               delete name;
               name = new char[strlen(dog.name)+1];
               strcpy(name, dog.name);
             }
            }

            // Define an equality test operator:
            int operator==(const Dog& dog) const {
             return strcmp(name, dog.name)==0; }

            friend ostream& operator<<(ostream& str, Dog& dog){
              str << dog.name;
              return str;}
          };

          main()
          {
            RWTValDlist<Dog> terriers;
            terriers.insert("Cairn Terrier");// NB: type conversion occurs
            terriers.insert("Irish Terrier");
            terriers.insert("Schnauzer");

            cout << "The list " <<
              (terriers.contains("Schnauzer") ? "does " : "does not ") <<
              "contain a Schnauzer\n";

            terriers.insertAt(
                terriers.index("Irish Terrier"),
                "Fox Terrier"
              );

            while (!terriers.isEmpty())
              cout << terriers.get() << NL;

            return 0;
          }
          END FILE

Program output:

Rogue Wave              Tools.h++   V 5.0   Supplement  55








                                                          RWTValDlist<T>


          The list does contain a Schnauzer
          Cairn Terrier
          Fox Terrier
          Irish Terrier
          Schnauzer

Public    RWTValDlist<T>();
construct
ors


          Construct an empty list.
          RWTValDlist<T>(const RWTValDlist<T>& list);
       Construct a copy of the list list.  Depending on the nature of the
       copy constructor of T, this could be relatively expensive because
       every item in the list must be copied.
Public    RWTValDlist&      operator=(const RWTValDlist<T>& list);
operators


       Sets self to a copy of the list list.  Depending on the nature of the
       copy constructor of T, this could be relatively expensive because
       every item in the list must be copied.
          T&      operator[](int i);
       Returns a reference to the item at index i.  The results can be used
       as an lvalue.  An exception of type TOOL_INDEX will be thrown if i is
       not a valid index.  Valid indices are from zero to the number of items
       in the list less one.
          T       operator[](int i) const;
       Returns a copy of the item at index i.  The results cannot be used as
       an lvalue.  An exception of type TOOL_INDEX will be thrown if i is not
       a valid index.  Valid indices are from zero to the number of items in
       the list less one.
Public member functions   void               append(T a);


          Adds the item a to the end of the list.

          void                apply(void (*applyFun)(T, void*), void* d);
       Applies the user-defined function pointed to by applyFun to every item
       in the list.  This function must have prototype:

            void yourFun(T a, void* d);

Rogue Wave              Tools.h++   V 5.0   Supplement  56








                                                          RWTValDlist<T>


       Client data may be passed through as parameter d.
          T&      at(int i);
       Returns a reference to the item at index i.  The results can be used
       as an lvalue.  An exception of type TOOL_INDEX will be thrown if i is
       not a valid index.  Valid indices are from zero to the number of items
       in the list less one.
          T       at(int i) const;
       Returns a copy of the item at index i.  The results cannot be used as
       an lvalue.  An exception of type TOOL_INDEX will be thrown if i is not
       a valid index.  Valid indices are from zero to the number of items in
       the list less one.
          void    clear();
       Removes all items from the list.  Their destructors (if any) will be
       called.
          RWBoolean      contains(T a) const;
       Returns TRUE if the list contains an object that is equal to the
       object a.  Returns FALSE otherwise.  Equality is measured by the
       class-defined equality operator.
          RWBoolean      contains(RWBoolean (*testFun)(T, void*), void* d)
          const;
       Returns TRUE if the list contains an item for which the user-defined
       "tester" function pointed to by testFun returns TRUE .  Returns FALSE
       otherwise.  The tester function must have the prototype:
            RWBoolean  yourTester(T, void* d);
       For each item in the list this function will be called with the item
       as the first argument.  Client data may be passed through as parameter
       d.
          unsignedentries() const;
       Returns the number of items that are currently in the collection.
          RWBoolean      find(T a, T& k) const;
       Returns TRUE if the list contains an object that is equal to the
       object a and puts a copy of the matching object into k.  Returns FALSE
       otherwise and does not touch k.  Equality is measured by the class-
       defined equality operator.
          RWBoolean      find(RWBoolean (*testFun)(T, void*), void* d, T& k)
          const;
       Returns TRUE if the list contains an object for which the user-defined
       tester function pointed to by testFun returns TRUE and puts a copy of
       the matching object into k.  Returns FALSE otherwise and does not
       touch k.  The tester function must have the prototype:
            RWBoolean  yourTester(T, void* d);



Rogue Wave              Tools.h++   V 5.0   Supplement  57








                                                          RWTValDlist<T>


       For each item in the list this function will be called with the item
       as the first argument.  Client data may be passed through as parameter
       d.
          T       first() const;
       Returns (but does not remove) the first item in the list.  The
       behavior is undefined if the list is empty.
          T       get();
       Returns and removes the first item in the list.  The behavior is
       undefined if the list is empty.
          int     index(T a);
       Returns the index of the first object that is equal to the object a,
       or -1 if there is no such object.  Equality is measured by the class-
       defined equality operator.
          int     index(RWBoolean (*testFun)(T, void*),
          void* d) const;
       Returns the index of the first object for which the user-defined
       tester function pointed to by testFun returns TRUE, or -1 if there is
       no such object.  The tester function must have the prototype:
            RWBoolean  yourTester(T, void* d);
       For each item in the list this function will be called with the item
       as the first argument.  Client data may be passed through as parameter
       d.
          void    insert(T a);
       Adds the item a to the end of the list.
          void    insertAt(int i, T a);
       Insert the item a at the index position i.  This position must be
       between zero and the number of items in the list.
          RWBoolean      isEmpty() const;
       Returns TRUE if there are no items in the list, FALSE otherwise.
          T       last() const;
       Returns (but does not remove) the last item in the list.  The behavior
       is undefined if the list is empty.
          unsignedoccurrencesOf(T a) const;
       Returns the number of objects in the list that are equal to the object
       a.  Equality is measured by the class-defined equality operator.
          unsignedoccurrencesOf(RWBoolean (*testFun)(T, void*), void* d)
          const;
       Returns the number of objects in the list for which the user-defined
       "tester" function pointed to by testFun returns TRUE .  The tester
       function must have the prototype:
            RWBoolean  yourTester(T, void* d);



Rogue Wave              Tools.h++   V 5.0   Supplement  58








                                                          RWTValDlist<T>


       For each item in the list this function will be called with the item
       as the first argument.  Client data may be passed through as parameter
       d.
          void    prepend(T a);
       Adds the item a to the beginning of the list.
          RWBoolean      remove(T a);
       Removes the first object which is equal to the object a and returns
       TRUE.  Returns FALSE if there is no such object.  Equality is measured
       by the class-defined equality operator.
          RWBoolean      remove(RWBoolean (*testFun)(T, void*),
          void* d);
       Removes the first object for which the user-defined tester function
       pointed to by testFun returns TRUE, and returns TRUE.  Returns FALSE
       if there is no such object.  The tester function must have the
       prototype:
            RWBoolean  yourTester(T, void* d);
       For each item in the list this function will be called with the item
       as the first argument.  Client data may be passed through as parameter
       d.
          unsignedremoveAll(T a);
       Removes all objects which are equal to the object a.  Returns the
       number of objects removed.  Equality is measured by the class-defined
       equality operator.
          unsignedremoveAll(RWBoolean (*testFun)(T, void*), void* d);
       Removes all objects for which the user-defined tester function pointed
       to by testFun returns TRUE.  Returns the number of objects removed.
       The tester function must have the prototype:
            RWBoolean  yourTester(T, void* d);
       For each item in the list this function will be called with the item
       as the first argument.  Client data may be passed through as parameter
       d.
          T       removeAt(int i);
       Removes and returns the object at index i.  An exception of type
       TOOL_INDEX will be thrown if i is not a valid index.  Valid indices
       are from zero to the number of items in the list less one.
          T       removeFirst();
       Removes and returns the first item in the list.  The behavior is
       undefined if the list is empty.
          T       removeLast()
       Removes and returns the last item in the list.  The behavior is
       undefined if the list is empty.



Rogue Wave              Tools.h++   V 5.0   Supplement  59










RWTValHashDictionary<K,V>RWTValHashDictionary<K,V>


Synopsis  #include <rw/tvhdict.h>
          unsigned hashFun(const K&);
          RWTValHashDictionary<K,V> dictionary(hashFun);

Descripti RWTValHashDictionary<K,V> is a dictionary of keys of type K
on        and values of type V, implemented using a hash table.  While
          duplicates of values are allowed, duplicates of keys are not.
        It is a value based collection: keys and values are copied in and out
        of the hash buckets.
        Parameters K and V represent the type of the key and the type of the
        value, respectively, to be inserted into the table.  These can be
        either classes or built in types.  Classes K and V must have:
          o  well-defined copy semantics (T::T(const T&) or equiv.);
          o  well-defined assignment semantics (T::operator=(const T&) or
             equiv.).
          In addition, class K must have
          o  well-defined equality semantics (K::operator==(const K&)).

A user-supplied hashing function for type K must be supplied to the
constructor when creating a new table.  If K is a Rogue Wave class, then this
requirement is usually trivial because all Rogue Wave objects know how to
return a hashing value.  This function has prototype:
            unsigned hFun(const K& a);

and should return a suitable hash value for the object a.
To find a value, the key is first hashed to determine in which bucket
the key and value can be found.  The bucket is then searched for an
object that is equal (as determined by the equality operator) to the
key.
The initial number of buckets in the table is set by the constructor.  There
is a default value.  If the number of (key/value) pairs in the collection
greatly exceeds the number of buckets then efficiency will sag because each
bucket must be searched linearly.  The number of buckets can be changed by
calling member function resize().  This is an expensive proposition because
not only must all the items be copied into the new buckets, but all of the
keys must be rehashed.
If you wish this to be done automatically, then you can subclass from this
class and implement your own special insert() and remove() functions which
perform a resize() as necessary.








                                               RWTValHashDictionary<K,V>


Example   BEGIN FILE: tvhdict.cpp
          #include <rw/tvhdict.h>
          #include <rw/cstring.h>
          #include <rw/rwdate.h>
          #include <rw/rstream.h>

          unsigned hashString(const RWCString& str){return str.hash();}

          main()
          {
            RWTValHashDictionary<RWCString, RWDate> birthdays(hashString);

            birthdays.insertKeyAndValue("John", RWDate(12, "April", 1975));
            birthdays.insertKeyAndValue("Ivan", RWDate(2, "Nov", 1980));

            // Alternative syntax:
            birthdays["Susan"] = RWDate(30, "June", 1955);
            birthdays["Gene"] = RWDate(5, "Jan", 1981);

            // Print a birthday:
            cout << birthdays["John"] << NL;
            return 0;
          }
          END FILE

Program output:
          April 12, 1975

Public    RWTValHashDictionary<K,V>(unsigned (*hashKey)(const K&),
constructors          unsigned buckets = RWDEFAULT_CAPACITY);


       Constructs a new hash dictionary.  The first argument is a pointer to
       a user-defined hashing function for items of type K (the key).  The
       table will initally have buckets buckets although this can be changed
       with member function resize().
          RWTValHashDictionary<K,V>(const RWTValHashDictionary<K,V>& dict);
       Copy constructor.  Constructs a new hash dictionary as a copy of dict.
       The new dictionary will have the same number of buckets as the old
       table.  Hence, although the keys and values must be copied into the
       new table, the keys will not be rehashed.



Rogue Wave              Tools.h++   V 5.0   Supplement  61








                                               RWTValHashDictionary<K,V>


Public    RWTValHashDictionary<K,V>&
operators operator=(const RWTValHashDictionary<K,V>& dict);


         Sets self to a copy of dict.  Afterwards, the new table will have
         the same number of buckets as the old table.  Hence, although the
         keys and values must be copied into the new table, the keys will not
         be rehashed.
          V&      operator[](K key);
       Look up the key key and return its associated value as an lvalue
       reference.  If the key is not in the dictionary, then it is added to
       the dictionary.  In this case, the value associated with the key will
       be provided by the default constructor for objects of type V.
Public    void              applyToKeyAndValue(
member    void (*applyFun)(K,V&,void*), void* d);
functions


       Applies the user-defined function pointed to by applyFun to every key-
       value pair in the dictionary.  This function must have prototype:
            void yourFun(K key, V& value, void* d);
       The key will be passed by value and hence cannot be changed.  The
       value will be passed by reference and can be modified.  Client data
       may be passed through as parameter d.
          void    clear();
       Removes all items from the collection.
          RWBoolean      contains(K key) const;
       Returns TRUE if the dictionary contains a key which is equal to key.
       Returns FALSE otherwise.  Equality is measured by the class-defined
       equality operator for class K.
          unsignedentries() const;
       Returns the number of key-value pairs currently in the dictionary.
          RWBoolean      find(K key, K& retKey) const;
       Returns TRUE if the dictionary contains a key which is equal to key
       and puts the matching key into retKey.  Returns FALSE otherwise and
       leaves retKey untouched.  Equality is measured by the class-defined
       equality operator for class K.
          RWBoolean      findValue(K key, V& retVal) const;
       Returns TRUE if the dictionary contains a key which is equal to key
       and puts the associated value into retVal.  Returns FALSE otherwise
       and leaves retVal untouched.  Equality is measured by the class-
       defined equality operator for class K.


Rogue Wave              Tools.h++   V 5.0   Supplement  62








                                               RWTValHashDictionary<K,V>


          RWBoolean      findKeyAndValue(K key, K& retKey, V& retVal) const;
       Returns TRUE if the dictionary contains a key which is equal to key
       and puts the matching key into retKey and the associated value into
       retVal.  Returns FALSE otherwise and leaves retKey and retVal
       untouched.  Equality is measured by the class-defined equality
       operator for class K.
          void    insertKeyAndValue(K key, V value);
       Inserts the key key and value value into the dictionary.
          RWBoolean      isEmpty() const;
       Returns TRUE if the dictionary has no items in it, FALSE otherwise.
          RWBoolean      remove(K key);
       Returns TRUE and removes the (key/value) pair where the key is equal
       to the key.  Returns FALSE if there is no such key.  Equality is
       measured by the class-defined equality operator for class K.
          void    resize(unsigned N);
       Changes the number of buckets to N, a relatively expensive operation
       if there are many items in the collection.



























Rogue Wave              Tools.h++   V 5.0   Supplement  63










RWTValHashSet<T>RWTValHashSet<T>                   RWTValHashSet<T>
                                                           |
                                                  RWTValHashTable<T>



Synopsis  #include <rw/tvhset.h>
          unsigned hashFun(const T&);
          RWTValHashSet(hashFun) set;

Descripti RWTValHashSet<T> is a derived class of RWTValHashTable<T> where
on        the insert() function has been overridden to accept only one
          item of a given value.  Hence, each item in the collection will
          be unique.
        As with class RWTValHashTable<T>, you must supply a hashing function
        to the constructor.
        The class T must have:
          o  well-defined copy semantics (T::T(const T&) or equiv.);
          o  well-defined assignment semantics (T::operator=(const T&) or
             equiv.);
          o  well-defined equality semantics (T::operator==(const T&)).

Example   This examples exercises a set of RWCStrings.

          BEGIN FILE: tvhset.cpp
          #include <rw/tvhset.h>
          #include <rw/cstring.h>
          #include <rw/rstream.h>

          unsigned hashIt(const RWCString& str){ return str.hash(); }

          main()
          {
            RWTValHashSet<RWCString> set(hashIt);

            set.insert("one");
            set.insert("two");
            set.insert("three");
            set.insert("one");// Rejected: already in collection

            cout << set.entries() << NL;       // Prints "3"
            return 0;
          }
          END FILE








                                                        RWTValHashSet<T>


Program output:
          3

       Inherited from class RWTValHashTable<T>.
          void    clear();
       Inherited from class RWTValHashTable<T>.
          RWBoolean      contains(T val) const;
       Inherited from class RWTValHashTable<T>.
          unsignedentries() const;
       Inherited from class RWTValHashTable<T>.
          RWBoolean      find(T a, T& k) const;
       Inherited from class RWTValHashTable<T>.
          void    insert(T val);
       Redefined from class RWTValHashTable<T> to allow an object of a given
       value to be inserted only once.
          RWBoolean      isEmpty() const;
       Inherited from class RWTValHashTable<T>.
          unsignedoccurrencesOf(T val) const;
       Inherited from class RWTValHashTable<T>.
          RWBoolean      remove(T val);
       Inherited from class RWTValHashTable<T>.
          unsignedremoveAll(T val);
       Inherited from class RWTValHashTable<T>.
          void    resize(unsigned N);
       Inherited from class RWTValHashTable<T>.



















Rogue Wave              Tools.h++   V 5.0   Supplement  65










RWTValHashTable<T>RWTValHashTable<T>


Synopsis  #include <rw/tvhasht.h>
          unsigned hashFun(const T&);
          RWTValHashTable<T> table(hashFun);

Description This class implements a parameterized hash table of types T.  It uses
          chaining to resolve hash collisions.  Duplicates are allowed.
          It is a value based collection: objects are copied in and out of the
          hash buckets.
Parameter T represents the type of object to be inserted into the table,
either a class or built in type.  The class T must have:
          o  well-defined copy semantics (T::T(const T&) or equiv.);
          o  well-defined assignment semantics (T::operator=(const T&) or
             equiv.);
          o  well-defined equality semantics (T::operator==(const T&)).

A user-supplied hashing function for type T must be supplied to the
constructor when creating a new table.  If T is a Rogue Wave class, then this
requirement is usually trivial because all Rogue Wave objects know how to
return a hashing value.  This function has prototype:
            unsigned hFun(const T& a);

and should return a suitable hash value for the object a.
To find an object, it is first hashed to determine in which bucket it occurs.
The bucket is then searched for an object that is equal (as determined by the
equality operator) to the candidate.
The initial number of buckets in the table is set by the constructor.  There
is a default value.  If the number of items in the collection greatly exceeds
the number of buckets then efficiency will sag because each bucket must be
searched linearly.  The number of buckets can be changed by calling member
function resize().  This is an expensive proposition because not only must
all items be copied into the new buckets, but they must also be rehashed.
If you wish this to be automatically done, then you can subclass from this
class and implement your own special insert() and remove() functions which
perform a resize() as necessary.

Example   BEGIN FILE: hasht.cpp
          #include <rw/tvhasht.h>
          #include <rw/cstring.h>
          #include <rw/rstream.h>

          unsigned hashIt(const RWCString& str) {return str.hash();}








                                                      RWTValHashTable<T>


          main()
          {
            RWTValHashTable<RWCString> table(hashIt);

            table.insert("Alabama");// NB: Type conversion occurs
            table.insert("Pennsylvania");
            table.insert("Oregon");
            table.insert("Montana");

            cout << "The table " <<
              (table.contains("Oregon") ? "does " : "does not ") <<
              "contain Oregon\n";

            table.removeAll("Oregon");

            cout << "The table " <<
              (table.contains("Oregon") ? "does " : "does not ") <<
              "contain Oregon";
            return 0;
          }
          END FILE

Program output
          The table does contain Oregon
          The table does not contain Oregon

Public    RWTValHashTable<T>(unsigned (*hashFun)(const T&),
constructors          unsigned buckets = RWDEFAULT_CAPACITY);


          Constructs a new hash table.  The first argument is a pointer to a
          user-defined hashing function for items of type T.  The table will
          initally have buckets buckets although this can be changed with member
          function resize().
          RWTValHashTable<T>(const RWTValHashTable<T>& table);
       Constructs a new hash table as a copy of table.  The new table will
       have the same number of buckets as the old table.  Hence, although
       objects must be copied into the new table, they will not be hashed.
Public operators   RWTValHashTable&   operator=(const RWTValHashTable<T>&);





Rogue Wave              Tools.h++   V 5.0   Supplement  67








                                                      RWTValHashTable<T>


          Sets self to a copy of table.  Afterwards, the new table will have
          the same number of buckets as the old table.  Hence, although objects
          must be copied into the new table, they will not be hashed.

Public    void              apply(void (*applyFun)(T, void*), void* d);
member
functions


          Applies the user-defined function pointed to by applyFun to every
          item in the table.  This function must have prototype:
               void yourFun(T a, void* d);
          Client data may be passed through as parameter d.
          void    clear();
       Removes all items from the collection.
          RWBoolean      contains(T val) const;
       Returns TRUE if the collection contains an item which is equal to val.
       Returns FALSE otherwise.  Equality is measured by the class-defined
       equality operator.
          unsignedentries() const;
       Returns the number of items currently in the collection.
          RWBoolean      find(T a, T& k) const;
       Returns TRUE if the collection contains an item which is equal to val
       and puts the matching object into k.  Returns FALSE otherwise and
       leaves k untouched.  Equality is measured by the class-defined
       equality operator.
          void    insert(T val);
       Inserts the value val into the collection.
          RWBoolean      isEmpty() const;
       Returns TRUE if the collection has no items in it, FALSE otherwise.
          unsignedoccurrencesOf(T val) const;
       Returns the number of items in the collection which are equal to val.
       Equality is measured by the class-defined equality operator.
          RWBoolean      remove(T val);
       Removes the first object which is equal to the object a and returns
       TRUE.  Returns FALSE if there is no such object.  Equality is measured
       by the class-defined equality operator.
          unsignedremoveAll(T val);
       Removes all objects which are equal to the object a.  Returns the
       number of objects removed.  Equality is measured by the class-defined
       equality operator.



Rogue Wave              Tools.h++   V 5.0   Supplement  68








                                                      RWTValHashTable<T>


          void    resize(unsigned N);
Changes the number of buckets to N, a relatively expensive operation if there
are many items in the collection.









































Rogue Wave              Tools.h++   V 5.0   Supplement  69










RWTValOrderedVector<T>RWTValOrderedVector<T>


Synopsis   #include <rw/tvordvec.h>
           RWTValOrderedVector<T> ordvec;

Description          RWTValOrderedVector<T> is an ordered collection.  That is, the
          items in the collection have a meaningful ordered relationship with
          respect to one another and can be accessed by an index number.  The
          order is set by the order of insertion.  Duplicates are allowed.
          The class is implemented as a vector, allowing efficient insertion
          and retrieval from the end of the collection, but somewhat slower
          from the beginning of the collection.
The class T must have:
          o  well-defined copy semantics (T::T(const T&) or equiv.);
          o  well-defined assignment semantics (T::operator=(const T&) or
             equiv.);
          o  well-defined equality semantics (T::operator==(const T&));
          o  a default constructor.

Example   BEGIN FILE: tvordvec.cpp
          #include <rw/tvordvec.h>
          #include <rw/rstream.h>

          main() {

            RWTValOrderedVector<double> vec;

            vec.insert(22.0);
            vec.insert(5.3);
            vec.insert(-102.5);
            vec.insert(15.0);
            vec.insert(5.3);

            cout << vec.entries() << " entries\n" << NL;// Prints "5"
            for (int i=0; i<vec.length(); i++)
              cout << vec[i] << NL;

            return 0;
          }
          END FILE

Program output:
          5 entries
          22








                                                  RWTValOrderedVector<T>


          5.3
          -102.5
          15
          5.3

Public   RWTValOrderedVector<T>(unsigned capac=RWDEFAULT_CAPACITY);
constructor


          Create an empty ordered vector with capacity capac.  Should the
          number of items exceed this value, the vector will be resized
          automatically.

Public operators      T                 operator()(int i) const;
                      T&                operator()(int i);

          Return the i'th value in the vector.  The index i must be between 0 and
          the length of the vector less one.  No bounds checking is performed.
          T       operator[](int i) const;
          T&      operator[](int i);
       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 will be
       performed.
Public    void              append(T a);
member
functions


          Appends the value a to the end of the vector.  The collection will
          automatically be resized if this causes the number of items in the
          collection to exceed the capacity.
          T&      at(int i);
          T       at(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 will be
       performed.
          void    clear();
       Removes all items from the collection.
          RWBoolean      contains(T a) const;
       Returns TRUE if the collection contains an item that is equal to a.  A
       linear search is done.  Equality is measured by the class-defined
       equality operator.


Rogue Wave              Tools.h++   V 5.0   Supplement  71








                                                  RWTValOrderedVector<T>


          const T*data() const;
       Returns a pointer to the raw data of the vector.  The contents should
       not be changed.  Should be used with care.
          unsignedentries() const;
       Returns the number of items currently in the collection.
          RWBoolean      find(T a,T& ret) const;
       Performs a linear search and returns TRUE if the vector contains an
       object that is equal to the object a and puts a copy of the matching
       object into ret.  Returns FALSE otherwise and does not touch ret.
       Equality is measured by the class-defined equality operator.
          T       first() const;
       Returns the first item in the collection.  An exception of type
       TOOL_INDEX will occur if the vector is empty.
          int     index(T a) const;
       Performs a linear search, returning the index of the first item that
       is equal to a.  Returns -1 if there is no such item.  Equality is
       measured by the class-defined equality operator.
          void    insert(T a);
       Appends the value a to the end of the vector.  The collection will
       automatically be resized if this causes the number of items in the
       collection to exceed the capacity.
          void    insertAt(int i, T a);
       Inserts the value a into the vector at index i.  The item previously
       at position i is moved to i+1, etc.  The collection will automatically
       be resized if this causes the number of items in the collection to
       exceed the capacity.  The index i must be between 0 and the number of
       items in the vector or an exception of type TOOL_INDEX will occur.
          RWBoolean      isEmpty() const;
       Returns TRUE if there are no items in the collection, FALSE otherwise.
          T       last() const;
       Returns the last item in the collection.  If there are no items in the
       collection then an exception of type TOOL_INDEX will occur.
          unsignedlength() const;
       Returns the number of items currently in the collection.
          unsignedoccurrencesOf(T a) const;
       Performs a linear search, returning the number of items that are equal
       to a.  Equality is measured by the class-defined equality operator.
          void    prepend(T a);
       Prepends the value a to the beginning of the vector.  The collection
       will automatically be resized if this causes the number of items in
       the collection to exceed the capacity.



Rogue Wave              Tools.h++   V 5.0   Supplement  72








                                                  RWTValOrderedVector<T>


          RWBoolean      remove(T a);
       Performs a linear search, removing the first object which is equal to
       the object a and returns TRUE.  Returns FALSE if there is no such
       object.  Equality is measured by the class-defined equality operator.
          unsignedremoveAll(T a);
       Removes all items which are equal to a, returning the number removed.
       Equality is measured by the class-defined equality operator.
          T       removeAt(int i);
       Removes and returns the object at index i.  An exception of type
       TOOL_INDEX will be thrown if i is not a valid index.  Valid indices
       are from zero to the number of items in the list less one.
          T       removeFirst();
       Removes and returns the first object in the collection.  An exception
       of type TOOL_INDEX will be thrown if the list is empty.
          T       removeLast();
       Removes and returns the last object in the collection.  An exception
       of type TOOL_INDEX will be thrown if the list is empty.
          void    resize(unsigned N);
       Changes the capacity of the collection to N.  Note that the number of
       objects in the collection does not change, just the capacity.
























Rogue Wave              Tools.h++   V 5.0   Supplement  73










RWTValSlist<T>RWTValSlist<T>


Synopsis   #include <rw/tvslist.h>
           RWTValSlist<T> list;

Description          This class maintains a collection of values, implemented as a
          singly linked list.  This is a value based list: objects are copied
          in and out of the links that make up the list.  Unlike intrusive
          lists (see class RWTIsvSlist<T>) the objects need not inherit from
          a link class.  However, this makes the class slightly less
          efficient than the intrusive lists because of the need to allocate
          a new link off the heap with every insertion and to make a copy of
          the object in the newly allocated link.
Parameter T represents the type of object to be inserted into the list,
either a class or built in type.  The class T must have:
          o  well-defined copy semantics (T::T(const T&) or equiv.);
          o  well-defined assignment semantics (T::operator=(const T&) or
             equiv.);
          o  well-defined equality semantics (T::operator==(const T&)).

Example   In this example, a singly-linked list of RWDates is exercised.

          BEGIN FILE: tvslist.cpp
          #include <rw/tvslist.h>
          #include <rw/rwdate.h>
          #include <rw/rstream.h>


          main()
          {
            RWTValSlist<RWDate> dates;
            dates.insert(RWDate(2, "June", 52));   // 6/2/52
            dates.insert(RWDate(30, "March", 46));// 3/30/46
            dates.insert(RWDate(1, "April", 90));  // 4/1/90

            // Now look for one of the dates:
            RWDate ret;
            if (dates.find(RWDate(2, "June", 52), ret)){
              cout << "Found date " << ret << NL;
            }

            // Remove in reverse order:
            while (!dates.isEmpty())
              cout << dates.removeLast() << NL;








                                                          RWTValSlist<T>



            return 0;
          }
          END FILE

Program output:
          Found date June 2, 1952
          April 1, 1990
          March 30, 1946
          June 2, 1952

Public   RWTValSlist<T>();
constructors


          Construct an empty list.
          RWTValSlist<T>(const RWTValSlist<T>& list);
       Construct a copy of the list list.  Depending on the nature of the
       copy constructor of T, this could be relatively expensive because
       every item in the list must be copied.
Public   RWTValSlist&      operator=(const RWTValSlist<T>& list);
operators


          Sets self to a copy of the list list.  Depending on the nature of the
          copy constructor of T, this could be relatively expensive because every
          item in the list must be copied.
          T&      operator[](int i);
       Returns a reference to the item at index i.  The results can be used
       as an lvalue.  An exception of type TOOL_INDEX will be thrown if i is
       not a valid index.  Valid indices are from zero to the number of items
       in the list less one.
          T       operator[](int i) const;
       Returns a copy of the item at index i.  The results cannot be used as
       an lvalue.  An exception of type TOOL_INDEX will be thrown if i is not
       a valid index.  Valid indices are from zero to the number of items in
       the list less one.
Public member          void              append(T a);
functions


          Adds the item a to the end of the list.


Rogue Wave              Tools.h++   V 5.0   Supplement  75








                                                          RWTValSlist<T>


          void    apply(void (*applyFun)(T, void*), void* d);
       Applies the user-defined function pointed to by applyFun to every item
       in the list.  This function must have prototype:
            void yourFun(T a, void* d);
       Client data may be passed through as parameter d.
          T&      at(int i);
       Returns a reference to the item at index i.  The results can be used
       as an lvalue.  An exception of type TOOL_INDEX will be thrown if i is
       not a valid index.  Valid indices are from zero to the number of items
       in the list less one.
          T       at(int i) const;
       Returns a copy of the item at index i.  The results cannot be used as
       an lvalue.  An exception of type TOOL_INDEX will be thrown if i is not
       a valid index.  Valid indices are from zero to the number of items in
       the list less one.
          void    clear();
       Removes all items from the list.  Their destructors (if any) will be
       called.
          RWBoolean      contains(T a) const;
       Returns TRUE if the list contains an object that is equal to the
       object a.  Returns FALSE otherwise.  Equality is measured by the
       class-defined equality operator.
          RWBoolean      contains(RWBoolean (*testFun)(T, void*), void* d)
          const;
       Returns TRUE if the list contains an item for which the user-defined
       "tester" function pointed to by testFun returns TRUE .  Returns FALSE
       otherwise.  The tester function must have the prototype:
            RWBoolean  yourTester(T, void* d);
       For each item in the list this function will be called with the item
       as the first argument.  Client data may be passed through as parameter
       d.
          unsignedentries() const;
       Returns the number of items that are currently in the collection.
          RWBoolean      find(T a, T& k) const;
       Returns TRUE if the list contains an object that is equal to the
       object a and puts a copy of the matching object into k.  Returns FALSE
       otherwise and does not touch k.  Equality is measured by the class-
       defined equality operator.
          RWBoolean      find(RWBoolean (*testFun)(T, void*), void* d, T& k)
          const;
       Returns TRUE if the list contains an object for which the user-defined
       tester function pointed to by testFun returns TRUE and puts a copy of


Rogue Wave              Tools.h++   V 5.0   Supplement  76








                                                          RWTValSlist<T>


       the matching object into k.  Returns FALSE otherwise and does not
       touch k.  The tester function must have the prototype:
            RWBoolean  yourTester(T, void* d);
       For each item in the list this function will be called with the item
       as the first argument.  Client data may be passed through as parameter
       d.
          T       first() const;
       Returns (but does not remove) the first item in the list.  The
       behavior is undefined if the list is empty.
          T       get();
       Returns and removes the first item in the list.  The behavior is
       undefined if the list is empty.
          int     index(T a);
       Returns the index of the first object that is equal to the object a,
       or -1 if there is no such object.  Equality is measured by the class-
       defined equality operator.
          int     index(RWBoolean (*testFun)(T, void*),
          void* d) const;
       Returns the index of the first object for which the user-defined
       tester function pointed to by testFun returns TRUE, or -1 if there is
       no such object.  The tester function must have the prototype:
            RWBoolean  yourTester(T, void* d);
       For each item in the list this function will be called with the item
       as the first argument.  Client data may be passed through as parameter
       d.
          void    insert(T a);
       Adds the item a to the end of the list.
          void    insertAt(int i, T a);
       Insert the item a at the index position i.  This position must be
       between zero and the number of items in the list.
          RWBoolean      isEmpty() const;
       Returns TRUE if there are no items in the list, FALSE otherwise.
          T       last() const;
       Returns (but does not remove) the last item in the list.  The behavior
       is undefined if the list is empty.
          unsignedoccurrencesOf(T a) const;
       Returns the number of objects in the list that are equal to the object
       a.  Equality is measured by the class-defined equality operator.
          unsignedoccurrencesOf(RWBoolean (*testFun)(T, void*), void* d)
          const;
       Returns the number of objects in the list for which the user-defined
       "tester" function pointed to by testFun returns TRUE .  The tester
       function must have the prototype:

Rogue Wave              Tools.h++   V 5.0   Supplement  77








                                                          RWTValSlist<T>


            RWBoolean  yourTester(T, void* d);
       For each item in the list this function will be called with the item
       as the first argument.  Client data may be passed through as parameter
       d.
          void    prepend(T a);
       Adds the item a to the beginning of the list.
          RWBoolean      remove(T a);
       Removes the first object which is equal to the object a and returns
       TRUE.  Returns FALSE if there is no such object.  Equality is measured
       by the class-defined equality operator.
          RWBoolean      remove(RWBoolean (*testFun)(T, void*),
          void* d);
       Removes the first object for which the user-defined tester function
       pointed to by testFun returns TRUE, and returns TRUE.  Returns FALSE
       if there is no such object.  The tester function must have the
       prototype:
            RWBoolean  yourTester(T, void* d);
       For each item in the list this function will be called with the item
       as the first argument.  Client data may be passed through as parameter
       d.
          unsignedremoveAll(T a);
       Removes all objects which are equal to the object a.  Returns the
       number of objects removed.  Equality is measured by the class-defined
       equality operator.
          unsignedremoveAll(RWBoolean (*testFun)(T, void*), void* d);
       Removes all objects for which the user-defined tester function pointed
       to by testFun returns TRUE.  Returns the number of objects removed.
       The tester function must have the prototype:
            RWBoolean  yourTester(T, void* d);
       For each item in the list this function will be called with the item
       as the first argument.  Client data may be passed through as parameter
       d.
          T       removeAt(int i);
       Removes and returns the object at index i.  An exception of type
       TOOL_INDEX will be thrown if i is not a valid index.  Valid indices
       are from zero to the number of items in the list less one.
          T       removeFirst();
       Removes and returns the first item in the list.  The behavior is
       undefined if the list is empty.
          T       removeLast()
       Removes and returns the last item in the list.  The behavior is
       undefined if the list is empty.  This function is relatively slow
       because removing the last link in a singly-linked list necessitates

Rogue Wave              Tools.h++   V 5.0   Supplement  78








                                                          RWTValSlist<T>


       access to the next-to-the-last link, requiring the whole list to be
       searched.










































Rogue Wave              Tools.h++   V 5.0   Supplement  79










RWTValSortedVector<T>RWTValSortedVector<T>


Synopsis   #include <rw/tvsrtvec.h>
           RWTValSortedVector<T> sortvec;

Description RWTValSortedVector<T> is an ordered collection.  That is, the items
          in the collection have a meaningful ordered relationship with
          respect to each other and can be accessed by an index number.  In
          the case of RWTValSortedVector<T>, objects are inserted such that
          objects "less than" themselves are before the object, objects
          "greater than" themselves after the object.  An insertion sort is
          used.  Duplicates are allowed.
Stores a copy of the inserted item into the collection according to an
ordering determined by the less-than (<) operator.
The class T must have:
          o  well-defined copy semantics (T::T(const T&) or equiv.);
          o  well-defined assignment semantics (T::operator=(const T&) or
             equiv.);
          o  well-defined equality semantics (T::operator==(const T&));
          o  well-defined less-than semantics (T::operator<(const T&));
          o  a default constructor.

Example   This example inserts a set of dates into a sorted vector in no
          particular order, then prints them out in order.

          BEGIN FILE: tvsrtvec.cpp
          #include <rw/tvsrtvec.h>
          #include <rw/rwdate.h>
          #include <rw/rstream.h>

          main()
          {
            RWTValSortedVector<RWDate> vec;

            vec.insert(RWDate(10, "Aug", 1991));
            vec.insert(RWDate(9, "Aug", 1991));
            vec.insert(RWDate(1, "Sept", 1991));
            vec.insert(RWDate(14, "May", 1990));
            vec.insert(RWDate(1, "Sept", 1991));// Add a duplicate
            vec.insert(RWDate(2, "June", 1991));

            for (int i=0; i<vec.length(); i++)
              cout << vec[i] << NL;
            return 0;








                                                                   Index


          }
          END FILE

Program output
          May 14, 1990
          June 2, 1991
          August 9, 1991
          August 10, 1001
          September 1, 1991
          September 1, 1991

Public    RWTValSortedVector(unsigned capac = RWDEFAULT_CAPACITY);
constructor


          Create an empty sorted vector with an initial capacity equal to
          capac.  The vector will be automatically resized should the number of
          items exceed this amount.

Public    T                 operator()(int i) const;
operators T&                operator()(int i);


          Return the i'th value in the vector.  The index i must be between 0
          and the length of the vector less one.  No bounds checking is
          performed.
          T       operator[](int i) const;
          T&      operator[](int i);
       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 will be
       performed.
          T&      at(int i);
          T       at(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 will be
       performed.
          void    clear();
       Removes all items from the collection.
          RWBoolean      contains(T a) const;
       Returns TRUE if the collection contains an item that is equal to a.  A
       binary search is done.  Equality is measured by the class-defined
       equality operator.


Rogue Wave              Tools.h++   V 5.0   Supplement  82








                                                                   Index


          const T*data() const;
       Returns a pointer to the raw data of the vector.  The contents should
       not be changed.  Should be used with care.
          unsignedentries() const;
       Returns the number of items currently in the collection.
          RWBoolean      find(T a,T& ret) const;
       Performs a binary search and returns TRUE if the vector contains an
       object that is equal to the object a and puts a copy of the matching
       object into ret.  Returns FALSE otherwise and does not touch ret.
       Equality is measured by the class-defined equality operator.
          T       first() const;
       Returns the first item in the collection.  An exception of type
       TOOL_INDEX will occur if the vector is empty.
          int     index(T a) const;
       Performs a binary search, returning the index of the first item that
       is equal to a.  Returns -1 if there is no such item.  Equality is
       measured by the class-defined equality operator.
          void    insert(T a);
       Performs a binary search to insert the item a into the collection
       after all items that compare less than or equal to it, but before all
       items that compare greater than it.
          RWBoolean      isEmpty() const;
       Returns TRUE if there are no items in the collection, FALSE otherwise.
          T       last() const;
       Returns the last item in the collection.  If there are no items in the
       collection then an exception of type TOOL_INDEX will occur.
          unsignedlength() const;
       Returns the number of items currently in the collection.
          unsignedoccurrencesOf(T a) const;
       Performs a binary search, returning the number of items that are equal
       to a.  Equality is measured by the class-defined equality operator.
          RWBoolean      remove(T a);
       Performs a binary search, removing the first object which is equal to
       the object a and returns TRUE.  Returns FALSE if there is no such
       object.  Equality is measured by the class-defined equality operator.
          unsignedremoveAll(T a);
       Removes all items which are equal to a, returning the number removed.
       Equality is measured by the class-defined equality operator.
          T       removeAt(int i);
       Removes and returns the object at index i.  An exception of type
       TOOL_INDEX will be thrown if i is not a valid index.  Valid indices
       are from zero to the number of items in the list less one.


Rogue Wave              Tools.h++   V 5.0   Supplement  83








                                                                   Index


          T       removeFirst();
       Removes and returns the first object in the collection.  An exception
       of type TOOL_INDEX will be thrown if the list is empty.
          T       removeLast();
       Removes and returns the last object in the collection.  An exception
       of type TOOL_INDEX will be thrown if the list is empty.
          void    resize(unsigned N);
       Changes the capacity of the collection to N.  Note that the number of
       objects in the collection does not change, just the capacity.



































Rogue Wave              Tools.h++   V 5.0   Supplement  84










RWTValVector<T>RWTValVector<T>


Synopsis   #include <rw/tvvector.h>
           RWTValVector<T> vec;

DescriptonClass RWTValVector<T> is a simple parameterized vector of objects of
          type T.  It is most useful when you know precisely how many objects
          have to be held in the collection.  If the intention is to "insert" an
          unknown number of objects into a collection, then class
          RWTValOrderedVector<T> may be a better choice.
The class T must have:
          o  well-defined copy semantics (T::T(const T&) or equiv.);
          o  well-defined assignment semantics (T::operator=(const T&) or
             equiv.);
          o  a default constructor.

Example   BEGIN FILE: tvvector.cpp
          #include <rw/tvvector.h>
          #include <rw/rwdate.h>
          #include <rw/rstream.h>

          main() {

            RWTValVector<RWDate> week(7);

            RWDate begin;  // Today's date

            for (int i=0; i<7; i++)
              week[i] = begin++;

            for (i=0; i<7; i++)
              cout << week[i] << NL;

            return 0;
          }
          END FILE

Program output:
          March 16, 1992
          March 17, 1992
          March 18, 1992
          March 19, 1992
          March 20, 1992
          March 21, 1992








                                                         RWTValVector<T>


          March 22, 1992

Public    RWTValVector<T>();
constructors


          Constructs an empty vector of length zero.
          RWTValVector<T>(unsigned n);
       Constructs a vector of length n.  The values of the elements will be
       set by the default constructor of class T.  For a built in type this
       can (and probably will) be garbage.
          RWTValVector<T>(unsigned n, T ival);
       Constructs a vector of length n, with each element initialized to the
       value ival.
          RWTValVector<T>(const RWTValVector& v);
       Constructs self as a copy of v.  Each element in v will be copied into
       self.
          ~RWTValVector<T>();
       Calls the destructor for every element in self.
Public    RWTValVector<T>&  operator=(const RWTValVector<T>& v);
operators


          Sets self to the same length as v and then copies all elements of v
          into self.
          RWTValVector<T>&    operator=(T ival);
       Sets all elements in self to the value ival.
          T       operator()(int i) const;
          T&      operator()(int i);
       Return the i'th value in the vector.  The index i must be between 0
       and the length of the vector less one.  No bounds checking is
       performed.
          T       operator[](int i) const;
          T&      operator[](int i);
       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 will be
       performed.
          const T*data() const;
       Returns a pointer to the raw data of self.  Should be used with care.
          unsignedlength() const;
       Returns the length of the vector.



Rogue Wave              Tools.h++   V 5.0   Supplement  86








                                                         RWTValVector<T>


          void    reshape(unsigned N);
       Changes the length of the vector to N.  If this results in the vector
       being lengthened, then the initial value of the additional elements is
       set by the default constructor of T.








































Rogue Wave              Tools.h++   V 5.0   Supplement  87










RWTValVirtualArray<T>RWTValVirtualArray<T>


Synopsis  #include <rw/tvrtarry.h>
          RWVirtualPageHeap* heap;
          RWTValVirtualArray<T> array(1000L, heap);

Description          This class represents a virtual array of elements of type T of
          almost any length.  Individual elements are brought into physical
          memory on an "as needed" basis.  If an element is used as an lvalue
          it is automatically marked as "dirty" and will be rewritten to the
          swapping medium.
The swap space is provided by an abstract page heap which is specified by the
constructor.  Any number of virtual arrays can use the same abstract page
heap.  You must take care that the destructor of the abstract page heap is
not called before all virtual arrays built from it have been destroyed.
The class supports reference counting using a copy-on-write technique, so
(for example) returning a virtual array by value from a function is as
efficient as it can be.  Be aware, however, that if the copy-on-write
machinery finds that a copy must ultimately be made, then for large arrays
this could take quite a bit of time.
For efficiency, more than one element can (and should) be put on a page.  The
actual number of elements is equal to the page size divided by the element
size, rounded downwards.  Example: for a page size of 512 bytes, and an
element size of 8, then 64 elements would be put on a page.
The indexing operator (operator[](long)) actually returns an object of type
RWTVirtualElement<T>.  Consider this example:
            double d = vec[j];
            vec[i] = 22.0;
Assume that vec is of type RWTValVirtualArray<double>.  The expression vec[j]
will return an object of type RWTVirtualElement<double>, which will contain a
reference to the element being addressed.  In the first line, this expression
is being used to initialize a double.  The class RWTVirtualElement<T>
contains a type conversion operator to convert itself to a T, in this case a
double.  The compiler uses this to initialize d.  In the second line, the
expression vec[i] is being used as an lvalue.  In this case, the compiler
uses the assignment operator for RWTVirtualElement<T>.  This assignment
operator recognizes that the expression is being used as an lvalue and
automatically marks the appropriate page as "dirty", thus guaranteeing that
it will be written back out to the swapping medium.
Slices, as well as individual elements, can also be addressed.  These should
be used wherever possible as they are much more efficient because they allow
a page to be locked and used multiple times before unlocking.
The class T must have:
          o  well-defined copy semantics (T::T(const T&) or equiv.);








                                                      RWTVirtualArray<T>


          o  well-defined assignment semantics (T::operator=(const T&) or
             equiv.).
In addition, you must never take the address of an element.

Example   In this example, a virtual vector of objects of type ErsatzInt is
          exercised.  A disk-based page heap is used for swapping space.

          BEGIN FILE: tvrtarry.cpp
          #include <rw/tvrtarry.h>
          #include <rw/rstream.h>
          #include <rw/diskpage.h>
          #include <stdlib.h>
          #include <stdio.h>

          struct ErsatzInt {
            char  buf[8];
            ErsatzInt(int i) { sprintf(buf, "%d", i); }
            friend ostream& operator<<(ostream& str, ErsatzInt& i)
              { str << atoi(i.buf); return str; }
          };

          main() {

            RWDiskPageHeap heap;
            RWTValVirtualArray<ErsatzInt> vec1(10000L, &heap);

            for (long i=0; i<10000L; i++)
              vec1[i] = i; // Some compilers may need a cast here

            cout << vec1[100] << NL;         // Prints "100"
            cout << vec1[300] << NL;         // Prints "300"

            RWTValVirtualArray<ErsatzInt> vec2 = vec.slice(5000L, 500L);
            cout << vec2.length() << NL;     // Prints "500"
            cout << vec2[0] << NL; // Prints "5000";

            return 0;
          }
          END FILE

Program output:
          100
          300

Rogue Wave              Tools.h++   V 5.0   Supplement  90








                                                      RWTVirtualArray<T>


          500
          5000

Public   RWTValVirtualArray<T>(long size, RWVirtualPageHeap* heap);
constructors


          Construct a vector of length size.  The pages for the vector will be
          allocated from the page heap given by heap which can be of any type.
          RWTValVirtualArray<T>(const RWTValVirtualArray<T>& v);
       Constructs a vector as a copy of v.  The resultant vector will use the
       same heap and have the same length as v.  The actual copy will not be
       made until a write, minimizing the amount of heap allocations and
       copying that must be done.
          RWTValVirtualArray<T>(const RWTVirtualSlice<T>& sl);
       Constructs a vector from a slice of another vector.  The resultant
       vector will use the same heap as the vector whose slice is being
       taken.  Its length will be given by the length of the slice.  The copy
       will be made immediately.
Public    ~RWTValVirtualArray<T>();
destructor


          Releases all pages allocated by the vector.

Public    RWTValVirtualArray&
operators operator=(const RWTValVirtualArray<T>& v);


       Sets self to a copy of v.  The resultant vector will use the same
       heap and have the same length as v.  The actual copy will not be
       made until a write, minimizing the amount of heap allocations
       and copying that must be done.
          void    operator=(const RWTVirtualSlice<T>& sl);
       Sets self equal to a slice of another vector.  The resultant vector
       will use the same heap as the vector whose slice is being taken.  Its
       length will be given by the length of the slice.  The copy will be
       made immediately.
          T       operator=(T val);
       Sets all elements in self equal to val.  This operator is actually
       quite efficient because it can work with many elements on a single
       page at once.


Rogue Wave              Tools.h++   V 5.0   Supplement  91








                                                      RWTVirtualArray<T>


Public    long              length() const;
member
functions


          Returns the length of the vector.

          T                   val(long i) const;
          Returns a copy of the value at index i.  The index i
          must be between zero and the length of the vector less
          one or an exception of type TOOL_LONGINDEX will occur.
          void    set(long i, T v);
       Sets the value at the index i to v.  The index i must be between zero
       and the length of the vector less one or an exception of type
       TOOL_LONGINDEX will occur.
          T       operator[](long i) const;
       Returns a copy of the value at index i.  The index i must be between
       zero and the length of the vector less one or an exception of type
       TOOL_LONGINDEX will occur.
          RWTVirtualElement<T>     operator[](long);;
       Returns a reference to the value at index i.  The results can be used
       as an lvalue.  The index i must be between zero and the length of the
       vector less one or an exception of type TOOL_LONGINDEX will occur.
          RWTVirtualSlice<T>  slice(long start, long length);
       Returns a reference to a slice of self.  The value start is the
       starting index of the slice, the value length its extent.  The results
       can be used as an lvalue.
          void    reshape(long newLength);
       Change the length of the vector to newLength.  If this results in the
       vector being lengthened then the value of the new elements is
       undefined.
          RWVirtualPageHeap*  heap() const;
       Returns a pointer to the heap from which the vector is getting its
       pages.










Rogue Wave              Tools.h++   V 5.0   Supplement  92










RWVirtualPageHeapRWVirtualPageHeap


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


Description  This is an abstract base class representing an abstract page
          heap of fixed sized pages.  The following describes the
          model by which specializing classes of this class are
          expected to work.
          You allocate a page off the abstract heap by calling member
          function allocate() which will return a memory "handle", an
          object of type RWHandle.  This handle logically represents the
          page.
          In order to use the page it must first be "locked" by calling
          member function lock() with the handle as an argument.  It is
          the job of the specializing class of RWVirtualPageHeap to make
          whatever arrangements are necessary to swap in the page
          associated with the handle and bring it into physical memory.
          The actual swapping medium could be disk, expanded or extended
          memory, or a machine someplace on a network.  Upon return,
          lock() returns a pointer to the page, now residing in memory.
          Once a page is in memory, you are free to do anything you want
          with it although if you change the contents, you must call
          member function dirty() before unlocking the page.
          Locked pages use up memory.  In fact, some specializing
          classes may have only a fixed number of buffers in which to do
          their swapping.  If you are not using the page, you should
          call unlock().  After calling unlock() the original address
          returned by lock() is no longer valid -- to use the page
          again, it must be locked again with lock().
          When you are completely done with the page then call
          deallocate() to return it to the abstract heap.
          In practice, managing this locking and unlocking and the
          inevitable type casts can be difficult.  It is usually easier
          to design a class than can work with an abstract heap to bring
          things in and out of memory automatically.  Indeed, this is
          what has been done with class RWTValVirtualArray<T>, which
          represents a virtual array of elements of type T.  Elements
          are automatically swapped in as necessary as they are
          addressed.
Example   This example illustrates adding N nodes to a linked list.  In this
          linked list, a "pointer" to the next node is actually a handle.








                                                       RWVirtualPageHeap


          BEGIN FILE: vpage.cpp
          #include <rw/vpage.h>

          struct Node {
            int     key;
            RWHandle                                   next;
          };

          RWHandle head = 0;

          void addNodes(RWVirtualPageHeap& heap, unsigned N) {
            for (int i=0; i<N; i++){
              RWHandle h = heap.allocate();
              Node* newNode = (Node*)heap.lock(h);
              newNode->key  = i;
              newNode->next = head;
              head = h;
              heap.dirty(h);
              heap.unlock(h);
            }
          }
          END FILE

Public    RWVirtualPageHeap(unsigned pgsize);
constructor


          Sets the size of a page.

Public    virtual           ~RWVirtualPageHeap();
destructor


       The destructor has been made virtual to give specializing classes a
       chance to deallocate any resources that they may have allocated.

Public   unsigned           pageSize() const;
member
functions


          Returns the page size for this abstract page heap.


Rogue Wave              Tools.h++   V 5.0   Supplement  94








                                                       RWVirtualPageHeap


Public    virtual RWHandle  allocate() = 0;;
pure
virtual
functions


       Allocates a page off the abstract heap and returns a handle for it.
       If the specializing class is unable to honor the request, then it
       should return a zero handle.
          virtual void   deallocate(RWHandle h) = 0;
       Deallocate the page associated with handle h.  It is not an error to
       deallocate a zero handle.
          virtual void   dirty(RWHandle h) = 0;
       Declare the page associated with handle h to be "dirty".  That is, it
       has changed since it was last locked.  The page must be locked before
       calling this function.
          virtual void*  lock(RWHandle h) = 0;
       Lock the page, swapping it into physical memory, and return an address
       for it.  A nil pointer will be returned if the specializing class is
       unable to honor the lock.  The returned pointer should be regarded as
       pointing to a buffer of the page size.
          virtual void   unlock(RWHandle h) = 0;
       Unlock a page.  A page must be locked before calling this function.
       After calling this function the address returned by lock() is no
       longer valid.



















Rogue Wave              Tools.h++   V 5.0   Supplement  95










                                                                    Appendix A
                                                           Upgrading from V4.0



The Rogue Wave Tools.h++ V5.0  library is extremely upwards compatible from
V4.0.  Incompatibilities are listed below.

A.1  Include path has changed


The include file paths must now be given as (for example)
            #include <rw/rwdate.h>      /* Use this */

rather than the old
            #include <rwdate.h>         /* Obsolete */

Along the same line, the compiler include path should not be given as (using
Borland C++ V3.0 as an example):
            bcc -I\rogue myfile.cpp     # Use this

rather than the old
            bcc -I\rogue\rw myfile.cpp  # Obsolete

This was done to improve the separation of file name space should you combine
Tools.h++ with another library that uses the same header file names.

A.2  Dropped compilers


We are no longer supporting the Glockenspiel C++ compiler under MS-DOS.
Users who require Microsoft compatibility are encouraged to switch to the new
Microsoft C/C++ V7.0 compiler.
Of course, other Glockenspiel compilers on other platforms are still
enthusiastically supported.

A.3  Borland library names changed


Borland C++ V3.0 is not upwardly compatible with Borland C++ V2.0.  You may
not mix and match code between them.  Hence, there are now two separate
precompiled libraries:
     Borland C++ V2.0 large memory model:    b2tll.lib
     Borland C++ V3.0 large memory model:    b3tll.lib
Similarly, there are two separate makefiles:








                                                            V5.0 Changes


     Borland C++ V2.0 makefile:              makefile.bc2
     Borland C++ V3.0 makefile:              makefile.bc3

A.4  Windows streambuf constructors have changed


Some constructors for the two Windows classes "RWCLIPstreambuf" and
"RWDDEstreambuf" have changed slightly from what was given in the V4.0
documentation.  This was done to avoid invoking the wrong one accidentally in
a series of constructors that differed only in whether an argument was signed
or unsigned.  The two constructors listed in the documentation as:
            RWCLIPstreambuf(int N);
            RWDDEstreambuf(         WORD format   = CF_TEXT),
                         BOOL response  = TRUE,
                         BOOL ackReq= TRUE,
                         BOOL release   = TRUE);

are now given by:
            RWCLIPstreambuf(int N, int dummy);    // Second arg ignored
            RWDDEstreambuf(         WORD format   = CF_TEXT),
                         BOOL response  = TRUE,
                         BOOL ackReq= TRUE,
                         BOOL release   = TRUE);

Note that the particular constructor for a RWCLIPstreambuf shown here now
takes a dummy second argument which is ignored.  This is to distinguish it
from the extremely similar constructor which takes a windows handle as a
single argument.
Note that the particulare constructor for a RWDDEstreambuf shown here no
longer has any default arguments.  You must explicitly specify all arguments.

A.5  RWCString replaces RWString


Class RWString has been replaced with a new class RWCString.  The two classes
are identical with two exceptions: the copy constructor and assignment
operators
            RWCString::RWCString(const RWCString&);
            RWCString::operator=(const RWCString&);

now use "copy semantics" rather than "reference semantics".  Here are two
example programs that illustrate the difference:


Rogue Wave              Tools.h++   V 5.0   Supplement  98








                                                            V5.0 Changes


            RWCString a("AIX");              RWString a("AIX");
            RWCString b(a);                  RWString b(a);
            a[1] = 'U';                      a[1] = 'U';

            cout << a << " " << b;           cout << a << " " << b;


OUTPUT:

            AIX AUX               AUX AUX


(with apologies to Apple and IBM).  Note that with copy semantics (as
illustrated on the left), the copy constructor makes a distinct, independent
copy of the data of its argument.  With reference semantics, the new string
merely references the old string's data.  To make a distinct copy, you must
call copy().
We used reference semantics with the old RWString class because of its speed
advantage.  However, we have found it confusing to many of our users and so
we have changed Tools.h++ to consistently use copy semantics everywhere.
See RWCString in the reference guide for more information.

A.6  GSortedVector(val)


The generic sorted vector GSortedVector(val) now requires you to declare and
implement its base class, GVector(val), as well as the sorted vector itself.
This used to be done automatically.  Because the new generic class
GOrderedVector(val) uses the same base class, this can no longer be done
without causing a compile error (multiple class declaration) should you use
both classes in the same program.
Example:
            declare(GVector,double)          // Declare the base class
            declare(GSortedVector,double)    // Now the derived class
            implement(GVector,double)        // Implement base class
            implement(GSortedVector,double)  // Implement derived class


Index

Benchmarking 17
Bit vector 35
Copy on write 23, 83

Rogue Wave              Tools.h++   V 5.0   Supplement  99









COW (See Copy on write)
Dictionary
  RWTValHashDictionary<K,V> 58
  template
     example 9
GOrderedVector(val) 14
Hashing collections
  RWTValHashTable<T> 64
Model-View-Controller 33
Ordered collection
  generic 14
Page heaps
  abstract 87
  buffered 21
  disk based 31
Regular expressions 25
Reshape vs. resize 9
RWBench 17
RWBitVec 35
RWBOUNDS_CHECK 8
RWBufferedPageHeap 21, 31
RWCString 23
RWDiskPageHeap 31
RWModel 33
RWTBitVec<size> 35
RWTimer 38
RWTIsvDlist<T> 40
RWTIsvSlist<T> 44
RWTQueue<T, C> 48
RWTStack<T, C> 50
RWTValDlist<T> 52
RWTValHashDictionary<K,V> 58
RWTValHashSet<T> 62
RWTValHashTable<T> 64
RWTValOrderedVector<T> 67
RWTValSlist<T> 71
RWTValSortedVector<T> 77
RWTValVector<T> 81
RWTValVirtualArray<T> 83
RWVirtualPageHeap 21, 31, 87
String 23
  searches 25, 26
Templates 3-11
time
  measuring elapsed 38

Rogue Wave              Tools.h++   V 5.0   Supplement  100









Vector
  bit 35
  bounds checking 8
  generic
     ordered 14
reshape vs. resize 9








































Rogue Wave              Tools.h++   V 5.0   Supplement  101