Example

Click on the banner to return to the user guide home page.

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 Chapter 15: Add Definitions for Virtual Functions). 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 RWCollectableStrings. 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 Chapter 10 (Iterators in Collection Classes) 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.