Iterating through Objects of a Dictionary

The OdDbDictionaryIterator class is a ready-to-use class that provides the base interface for unidirectional iterators that are hard-associated with dictionary objects of the database. The iterator traverses through objects of the dictionary except for inaccessible and erased objects. The iterator refers to the current object of the dictionary for which it returns required information. Working with iterators includes the following operations: setting an iterator to a position, moving an iterator to the next object, checking whether traversing is complete, and getting an object from the dictionary.

The OdDbDictionaryIteratorPtr class is the typified smart pointer to the iterator of any dictionary. This class is used as a pointer for storing and passing references to the iterators. The OdDbDictionaryIterator class is derived from the OdRxIterator class and inherits its interface. The OdDbDictionaryIterator class has standard iterator behavior and can traverse through database objects of any dictionary. In the following examples, the pDict variable stores a pointer to the dictionary object.

Creating an iterator

The iterator must be created before traversing. To create an iterator, declare a variable of the OdDbDictionaryIteratorPtr type and use the NewIterator() method of the dictionary object. The NewIterator() method creates the instance of the iterator, sets the new iterator to the first object in the dictionary, and returns the typified smart pointer to it. For example:


OdDbDictionaryIteratorPtr itDict = pDict->newIterator();

The NewIterator() method has an optional argument which defines the traversing order type of the DictIterType type. The traversing order type defines how to offer the objects of the dictionary during traversing — the kDictCollated value performs the traversing in the order objects were added in the dictionary, and the kDictSorted value performs the traversing in alphabetical order of names. The argument is kDictCollated by default. For example:


// Create a new iterator for traversing in the order of adding
OdDbDictionaryIteratorPtr itDict = pDict->newIterator(OdRx::kDictCollated);

// Create a new iterator traversing in the alphabetical order
OdDbDictionaryIteratorPtr itDict = pDict->newIterator(OdRx::kDictSorted);

To change the traverse order, the program must delete the existing iterator and create a new iterator with other order type. The created iterator does not move backward to the beginning of the dictionary. When the iterator reaches the end of the dictionary, the program must delete it and create a new iterator. To delete the iterator, set a NULL value for the smart pointer to it.

Moving an iterator

To move the iterator through objects, use the next() method which traverses to the next object towards the end of the dictionary. The next() method does not have arguments and returns True if the iterator has not reached the end of the dictionary or False if it is at the end. For example:


itDict->next();

Checking an iterator

To check whether the traversing is complete, use the done() method that returns True if the iterator is out of the traverse scope or False if the iterator is within the traverse scope. For example:


while(!itDict->done()) itDict->next();

Getting an object using the iterator

The iterator has three methods for getting an object from the dictionary: getObject(), object(), and objectId(), which differ by the returned value.

The getObject() method returns a smart pointer to the database object of which the iterator refers and requires the mode for opening the object as an argument of the OdDb::OpenMode enumerator (kForRead, kForWrite, or kForNotify). The returned value has the OdDbObjectPtr type, but it can be cast to the specific type of the obtained object. The argument is OdDb::kForRead by default. For example:


// Open the object in the read mode
OdDbObjectPtr pObject = itDict->getObject(OdDb::kForRead);    // or  itDict->getObject();

// Open the object in the write mode
OdDbObjectPtr pObject = itDict->getObject(OdDb::kForWrite);

// Open the object in the notify mode and cast to the OdDbColor type
OdDbColorPtr pColor = (OdDbColorPtr) itDict->getObject(OdDb::kForNotify);

The object() method returns a non-typified smart pointer to the object of which the iterator refers and does not have arguments. The method opens the object in read mode (kForRead). The returned value has the OdRxObjectPtr type. For example:


OdRxObjectPtr pSmart = itDict->object();

The objectId() method returns the ID of the object to which the iterator refers and does not have arguments. The returned value is the OdDbObjectId instance associated with the object in the database. For example:


OdDbObjectId idObject = itDict->objectId();

The objectId() method does not open the object. To open the object, use the safeOpenObject() method of the Object ID; it requires the open mode as an argument of the OdDb::OpenMode enumerator (kForRead, kForWrite, or kForNotify) and returns a smart pointer to the opened object. For example:


// Open the object in the read mode
OdDbObjectPtr pObject = idObject.safeOpenObject(OdDb::kForRead)

// Open the object in the write mode
OdDbObjectPtr pObject = idObject.safeOpenObject(OdDb::kForWrite);

// Get the ID, open the object in the notify mode, and cast to the specific type in a one line
OdDbColorPtr pColor = (OdDbColorPtr) itDict->objectId().safeOpenObject(OdDb::kForNotify);

Getting a name using the iterator

The iterator can obtain a unique keyword (name) associated with an object in the dictionary. To get the name of an object, use the name() method; it does not have arguments and returns the name of the object to which the iterator refers in the dictionary as a value of the OdString type. For example:


OdString sName = itDict->name();
odPrintConsoleString(L"\n\"%s\"", sName.c_str());

For example, get the handle, name, and type of the object to which the iterator refers:


odPrintConsoleString(L"\nH=%s, Name=\"%s\", Type=%s", itDict->objectId().getHandle().ascii(), 
                     itDict->name().c_str(), itDict->getObject()->isA()->name().c_str());

Positioning an iterator

An iterator can be set to the specified position in the dictionary using the ID of an object. To set the position, use the setPosition() method which requires one argument — the OdDbObjectId instance associated with the object of the dictionary to which the iterator must be set — and returns True if the iterator is successfully set to the position of the object specified by the passed ID, or it returns False if the object with the specified ID is not found in the dictionary. For example:


itDict->setPosition(idObject);

Example of iterating

The following example demonstrates iterating through objects from beginning to end of the dictionary in order to list them:


odPrintConsoleString(L"\nThe list of objects:");

for(itDict = pDict->newIterator() ; !itDict->done() ; itDict->next())
{
  odPrintConsoleString(L"\n%s-\"%s\"-%s", itDict->objectId().getHandle().ascii(), itDict->name().c_str(),
                       itDict->getObject()->isA()->name().c_str());
}
itDict = NULL;