The Smalltalk-like collection classes inherit from the abstract base class RWCollection, which in turn inherits from the abstract base class RWCollectable, described in “Designing an RWCollectable Class”, “Creating an RWCollectable Object”, “Complete Listing for Class Bus”, and “Tables of the Smalltalk-like Classes”. (Thus do we produce collections of collections, but that is another story.)

An abstract base class is a class intended to be inherited by some other class, not used as itself per se. If you think of it as a kind of virtual class, you can easily project the meaning of virtual functions. These virtual functions provide a blueprint of functionality for the derived class. As an abstract base class, RWCollection provides a blueprint for collection classes by declaring various virtual functions, such as insert(), remove(), entries(), and so on.

This section describes the virtual functions inherited by the Smalltalk-like collections. Any of these collections can be expected to understand them.

You can put a pointer to an object into a collection by using the virtual function insert():

This function inserts in the way most natural for the collection. Faced with a stack, it pushes an item onto the stack. Faced with a queue, it appends the item to the queue. In a sorted collection, it inserts the new item so that items before it compare less than itself, items after it compare greater than itself, and items equal compare equal, if duplicates are allowed. See the example in “Smalltalk-like Classes Example” for an example using insert().

You must always insert pointers to real objects. Since all RWCollection classes need to dereference their contents for some methods such as find(), inserting a zero will cause such methods to crash. If you must store an empty object, we suggest you create and insert a default constructed object of the appropriate type, such as RWCollectable*.

You can use the following virtual functions to test how many objects a collection contains, and whether it contains a particular object:

The function isEmpty() returns true if the collection contains no objects. The function entries() returns the total number of objects that the collection contains.

The function contains() returns true if the argument is equal to an item within the collection. The meaning of is equal to depends on the collection and the type of object being tested. Hashing collections use the virtual function isEqual() to test for equality, after first hashing the argument to reduce the number of possible candidates to those in one hash bucket. (Here it is important that all items which are isEqual with each other hash to the same value!). Sorted collections search for an item that compares equal to the argument; in other words, an item for which compareTo() returns zero.

The virtual function occurrencesOf() is similar to contains(), but returns the number of items that are equal to the argument.

The virtual function find() returns a pointer to an item that is equal to its argument.

The following example, which builds on the example in “Smalltalk-like Classes Example”, uses find() to find occurrences of Mary in the collection, and occurrencesOf() to find the number of times Mary occurs:

To search for and remove particular items, you can use the functions remove() and removeAndDestroy():

The function remove() looks for an item that is equal to its argument and removes it from the collection, returning a pointer to it. It returns nil if no item is found.

The function removeAndDestroy() is similar except it deletes the item instead of returning it, using the virtual destructor inherited by all RWCollectable items. You must be careful when using this function that the item was actually allocated off the heap, not the stack, and that it is not shared with another collection.

The following example, which expands on the previous one, demonstrates the use of the virtual function removeAndDestroy():

To efficiently examine the members of a Smalltalk-like collection, use the member function apply():

The first argument, RWapplyCollectable, is a typedef:

In other words, RWapplyCollectable is a pointer to a function with prototype:

where yourApplyFunction is the name of the function. You must supply this function. It will be called for each item in the collection, in whatever order is appropriate for the collection, and passed as a pointer to the item as its first argument. You must be careful that you cast the pointer item to the proper derived class. The second argument x is passed through from the call to apply(), and is available for your use. For example, you could use it to hold a handle to a window on which the object is to be drawn.

The apply-functions generally employ the most efficient method for examining all members of the collection. This is their great advantage. Their disadvantage is that they are slightly clumsy to use, requiring you to supply a separate function. The functional equivalent to apply() in the Smalltalk world is do. It takes just one argument: a piece of code to be evaluated for each item in the collection.

To remove all items from the collection, you can use the functions clear() and clearAndDestroy():

The function clearAndDestroy() not only removes the items, but also calls the virtual destructor for each item. You must use this function with care. The function does check to see if the same item occurs more than once in a collection (by building an RWIdentitySet internally), and thereby deletes each item only once. However, it cannot check whether an item is shared between two different collections. You must also be certain that every member of the collection was allocated off the heap.