13.2 Example

To orient ourselves, we always like to start with an example. The following example uses a SortedCollection to store and order a set of RWCollectableStrings. SortedCollection is actually a typedef for the Smalltalk-like collection class RWBinaryTree. Objects inserted into it are stored in order according to their relative values as returned by the virtual function compareTo(). (See Section 15.2.4). Here is the code:

#define RW_STD_TYPEDEFS 1                                    //1
#include <rw/bintree.h>
#include <rw/collstr.h>                                      //2
#include <rw/rstream.h>

main(){
// Construct an empty SortedCollection
SortedCollection sc;                                         //3

// Insert some RWCollectableStrings:
sc.insert(new RWCollectableString("George"));                // 4
sc.insert(new RWCollectableString("Mary"));                  // 5
sc.insert(new RWCollectableString("Bill"));                  // 6
sc.insert(new RWCollectableString("Throkmorton"));           // 7

// Now iterate through the collection printing all members:
RWCollectableString* str;                                    // 8
SortedCollectionIterator sci(sc);                            // 9
  while( str = (RWCollectableString*)sci() )                // 10
    cout << *str << endl;                                   // 11

sc.clearAndDestroy();
return 0;
}

Program Output:

Bill
George
Mary
Throkmorton

Let's go through the code line-by-line and explain what is happening:

//1	By defining the preprocessor macro `RW_STD_TYPEDEFS`, we enable the set of Smalltalk-like typedefs. We can then use the typedef *SortedCollection* instead of *RWBinaryTree*, its true identity.
//2	The second `#include` declares class *RWCollectableString, a derived class that multiply inherits from its base classes RWCString* and *RWCollectable. RWCollectableString* inherits functionality from *RWCString, and "ability to be collected" from class RWCollectable*.
//3	An empty *SortedCollection* was created at this line.
//4-//7	Four *RWCollectableStrings were created off the heap and inserted into the collection, in no particular order. See the Class Reference for details on constructors for RWCollectableString*s. The objects allocated here normally should be deleted before the end of the program, but we omitted this step to make the example more concise.
//8	A pointer to an *RWCollectableString* was declared and defined here.
//9	An iterator was constructed from the *SortedCollection* `sc`.
//10	The iterator is then used to step through the entire collection, retrieving each value in order. The function call operator `operator()`has been overloaded so that the iterator means "step to the next item and return a pointer to it." All Tools.h++ iterators work this way. See Stroustrup (1986, Section 7.3.2) for an example and discussion of iterators, as well as Section 10.4 of this manual. The typecast: `str = (RWCollectableString)sci()` is necessary because the iterator returns an `RWCollectable`; that is, a pointer to an *RWCollectable* which must then be cast into its actual identity.
//11	Finally, the pointer `str` is dereferenced and printed. The ability of an *RWCollectableString* to be printed is inherited from its base class *RWCString*.

When run, the program prints out the four collected strings in order; for class RWCollectableString, this means lexicographical order.