13.6 Virtual Functions Inherited from RWSequenceable

Collections that inherit from the abstract base class RWSequenceable, which inherits from RWCollectable, have an innate, meaningful ordering. This section describes the virtual functions inherited from RWSequenceable which make use of that ordering. For example, the following virtual functions allow access to the ith item in the collection:

virtual RWCollectable*&       at(size_t i);
virtual const RWCollectable*  at(size_t i) const;

Remember that the first item in any collection is at position i=0. The compiler chooses which function to use on the basis of whether or not your collection has been declared const: the second variant of the function is for const collections, the first for all others. The first variant can also be used as an lvalue, as in the following example:

RWOrdered od;
od.insert(new RWCollectableInt(0));                          // 0
od.insert(new RWCollectableInt(1));                        // 0 1
od.insert(new RWCollectableInt(2));                      // 0 1 2

delete od(1);              // Use variant available for RWOrdered
od.at(1) = new RWCollectableInt(3);                      // 0 3 2

As you might expect, the operations above are efficient for the class RWOrdered, which is implemented as a vector, but relatively inefficient for a class implemented as a linked-list, because the entire list must be traversed to find a particular index.

The following virtual functions return the first or last item in the collection, respectively, or nil if the collection is empty:

virtual RWCollectable*  first() const;
virtual RWCollectable*  last() const;

The next virtual function returns the index of the first object that is equal to the argument, or the special value RW_NPOS if there is no such object:

virtual size_t  index(const RWCollectable*) const;

Here's an example of the index function in use. The output shows that the index of the variable we were searching for was found at position 1.

RWOrdered od;
od.insert(new RWCollectableInt(6));                          // 6
od.insert(new RWCollectableInt(2));                        // 6 2
od.insert(new RWCollectableInt(4));                      // 6 2 4

RWCollectableInt dummy(2);
size_t inx = od.index(&dummy);
if (inx == RW_NPOS)
  cout << "Not found.\n";
else
  cout << "Found at index " << inx << endl;

Program Output:

Found at index 1

Finally, you can use the following function to insert an item at a particular index:

virtual RWCollectable* insertAt(size_t i, RWCollectable* c);

In the example below, the code uses the function insertAt to insert 4 at position 1.

RWOrdered od;
od.insert(new RWCollectableInt(6));                          // 6
od.insert(new RWCollectableInt(2));                        // 6 2
od.insertAt(1, new RWCollectableInt(4));                 // 6 4 2