find() and Friends

SourcePro Core : Essential Tools Module User's Guide : Collection Classes : Smalltalk‑like Collection Classes : Virtual Functions Inherited From RWCollection : find() and Friends

find() and Friends

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

virtual bool contains(const RWCollectable*) const;

virtual unsigned entries() const;

virtual RWCollectable* find(const RWCollectable*) const;

virtual bool isEmpty() const;

virtual unsigned occurrencesOf(const RWCollectable*) const;

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:

#define RW_STD_TYPEDEFS 1

#include <rw/bintree.h> //1

#include <rw/collstr.h>

#include <rw/rstream.h>

using std::cout;

using std::endl;

int main(){

// Construct an empty SortedCollection

SortedCollection sc;

// Insert some RWCollectableStrings:

sc.insert(new RWCollectableString("George"));

sc.insert(new RWCollectableString("Mary"));

sc.insert(new RWCollectableString("Bill"));

sc.insert(new RWCollectableString("Throkmorton"));

sc.insert(new RWCollectableString("Mary")); //2

cout << sc.entries() << endl; //3

RWCollectableString dummy("Mary"); //4

RWCollectable* t = sc.find( &dummy ); //5

if(t){ //6

if(t->isA() == dummy.isA()) //7

cout << *(RWCollectableString*)t << endl; //8

}

else

cout << "Object not found.\n"; //9

cout << sc.occurrencesOf(&dummy) << endl; //10

sc.clearAndDestroy();

return 0;

}

Program Output:

Mary

//1 This initial code block is duplicated from Smalltalk-like Classes Example.

//2 Insert another instance with the value Mary.

//3 Prints out 5, the total number of entries in the sorted collection.

//4 Constructs a throwaway variable dummy to be used to test for the occurrences of strings containing Mary.

//5 The collection is asked to return a pointer to the first object encountered that compares equal to the argument. A nil pointer (zero) is returned if there is no such object.

//6 The pointer is tested to make sure it is not nil.

//7 Paranoid check. In this example, it is obvious that the items in the collection must be of type RWCollectableString. In general, it may not be obvious.

//8 Because of the results of Step 7, the cast to an RWCollectableString pointer is safe. The pointer is then dereferenced and printed.

//9 If the pointer t was nil, then an error message would have been printed here.

//10 The call to occurrencesOf() returns the number of items that compare equal to its argument. In this case, two items are found, the two occurrences of Mary.