Using Cursors to Locate and Access Elements

Cursors provide a basic mechanism for accessing elements of collection classes. For each collection, you can define one or more cursors, and you can use these cursors to access elements. Collection Class functions such as elementAt, locate and removeAt use cursors.

The elementAt function lets you access an element using a cursor. The elementAt function returns a reference to an element, thereby avoiding copying the elements. Suppose that an element had a size of 20KB and you want to access a 2-byte data member of that element. If you use elementAt to return a reference to this element, you avoid having to copy the entire element to a local variable.

Several other functions, such as firstElement or elementWithKey, return a reference to an element. They can be thought of as first executing a corresponding cursor function, such as setToFirst or locateElementWithKey, and then accessing the element using the cursor.

You must determine if the element exists before trying to access it. If its existence is not known from the context, it must first be checked.

To save the extra effort of locating the desired element twice (once for checking whether it exists and then for actually retrieving its reference), use the cursor that is returned by the locate function for fast element access:

//main.cpp - main file
#include <iset.h>
#include <iostream.h>
#include "person.h" //person.h from the previous examples

typedef ISet <Person> AddressList;

void main()
{
    AddressList business;
    AddressList::Cursor myCursor(Business); //Cursor definition

    Person A("Peter Black","714-50706");
    Person B("Carl Render","714-540321");
    Person C("Sandra Summers","x");
    Person D("Mike Summers","x");
    Person E;

    business.add(A);
    business.add(B);
    business.add(C);
    business.add(D);
    if (business.locate(B, myCursor)){
        E=business.elementAt(myCursor) ;
    }
    else {
        cout << "\nElement not in set !";
    }

    business.remove(B); //myCursor is no longer valid
    if (business.locate(B, myCursor)) {
        E=business.elementAt(myCursor);
    }
    else {
        cout << "\nElement not in set !";
    }
}

The elementAt function can also be used to replace the value of the referenced element. You must ensure that the positioning property of the element is not changed with respect to the given collection.

There are two versions of elementAt:

Element const& elementAt (ICursor const&) const;
Element&       elementAt (ICursor const&);

Use the first version of elementAt if you want to ensure that the located element cannot be changed by any subsequent function.

Introduction to the Collection Classes
Collection Characteristics
Overview of Iteration
Iteration with Cursors

Adding an Element to a Collection
Removing an Element from a Collection
Using Cursors to Iterate Over a Collection
Using allElementsDo and Applicators to Iterate Over a Collection
Cursors vs. Exception Handling
Instantiating the Collection Classes
Troubleshooting Problems while Using the Collection Class Library