oaIter Class Template Reference

Inheritance diagram for oaIter:

oaBaseIter


Public Methods

 oaIter (const oaBaseCollection &coll)
 oaIter (const oaIter< obj > &iterIn)
obj * getNext ()

Detailed Description

template<class obj>
class oaIter< obj >

The oaIter class is used to iterate over the objects in an oaCollection. oaCollections are used wherever the database needs to return multiple objects in some relationship to a single starting object. The oaIter class allows the caller to return one object in the collection at a time and to test when all the objects are returned.

The intended usage of the oaIter class is shown in the following example: 

        oaIter<oaShape>  sIter(view->getShapes());
        oaShape          *myshape;
        while (myshape = sIter.getNext()) { ... }

Note that some collections use special case iterators that do not belong to the oaIter class. This happens where the getNext() function has a different signature.

Constructor & Destructor Documentation

template<class obj>
oaIter< obj >::oaIter (  const oaBaseCollection &    coll )  [inline]
 

This function constructs an oaIter object that is associated with the specified oaBaseCollection coll.

template<class obj>
oaIter< obj >::oaIter (  const oaIter< obj > &    iterIn )  [inline]
 

This function constructs an oaIter object that iterates over the same set of objects as the specified iterator iterIn.

Note: When an iterator is copied, the new copy retains the state of the original. For example, if the original iterator is in the middle of a collection at the time of the copy, the new copy of the iterator will be at middle of the collection. In other words, this copy constructor function does not reset the iterator to point to the beginning of the collection.

Member Function Documentation

template<class obj>
obj * oaIter< obj >::getNext (    )  [inline]
 

This function returns the next object in the collection that is being iterated. NULL is returned when there are no more objects to return.

The order in which objects are returned by oaIter::getNext() is not guaranteed to be the same:

  • between two separate instantiations of an oaIter class over the same set of objects
  • after calling oaIter::reset()

When an iterator is active it is safe to delete objects that have already been returned by that iterator, including the most recent getNext() call. Such deletion will not cause the iterator to return invalid objects or to skip other objects in the collection that is being iterated over.

It is not safe to delete an object in the collection that has not yet been returned by the iterator. Such deletion will invalidate the iterator and can cause problem results, including returning invalid objects, throwing exceptions, and skipping members of the collection.

Further, adding objects to a collection while iterating over the collection is not recommended since subsequent getNext() return results on a collection after the addition of objects to the collection are undefined.

Reimplemented from oaBaseIter.

The documentation for this class was generated from the following files:

Return to top of page




Copyright © 2002 - 2010 Cadence Design Systems, Inc.
All Rights Reserved.