Hurricane::Locator< Type > Class Template Reference

Locator description (API) More...

Inheritance diagram for Hurricane::Locator< Type >:

Public Member Functions
virtual Type	getElement () const =0
virtual Locator< Type > *	getClone () const =0
virtual bool	isValid () const =0
virtual void	progress ()=0

Detailed Description

template<class Type>
class Hurricane::Locator< Type >

Locator description (API)

Introduction

Locators are objects which allow to walk efficiently through the data structure.

Locators are indeed algorithms. They do not hold a list of elements but the way to go from one element to the next. As such, they are very light in memory, contrary to containers. Locators are the workhorse of Collection, and while they can be used directly, this is not the recommended way.

General concepts

Initialization In order to get a locator, you must : either ask the collection to provide a locator for visiting the elements of its described set, or build a clone of an existing locator allowing to visit the remaining elements starting from the current position of that locator.

End of walk indicator The predicate isValid() returns true if the locator refers an element of the set, false when all the elements have been visited.

getting the current element The current element is obtained by the accessor getElement(). There is no risk to call this function when the visit is finished or the locator is non initialized (the returned value is meaningless).

Walk progression The function progress() moves forward the locator on the next element of the set (does nothing if called after the last element).

Usage examples

The following sample code shows how to trace the nets of a given cell

Cell* cell = ...; // we get the cell
 
if (cell) {
 
   // cell->getNets()
   //    returns the nets collection of the cell
   // and getLocator()
   //    allocates and returns a locator for traversing those nets
   Locator<Net*>* locator = cell->getNets().getLocator();
 
   while (locator->isValid()) {
      Net* net = locator->getElement();
      assert(net->getCell() == cell);
      locator->progress();
   }
 
   // don't forget to release the allocated locator
   delete locator;
}

And this one how to print all pairs of nets of a given cell

Cell* cell = ...; // we get a cell
 
if (cell) {
   Locator<Net*>* locator1 = cell->GetNets().getLocator();
   while (locator1->isValid()) {
      Net* net1 = locator1->getElement();
 
      Locator<Net*>* locator2 = locator1->getClone();
      while (locator2->isValid()) {
         Net* net2 = locator2->getElement();
         cerr << net1 << " " << net2 << endl;
         locator2->progress();
      }
      delete locator2;
 
      locator1->progress();
   }
   delete locator1;
}

Remarks

Those examples are given in order to explain how locators work. We will see in the following how to do that more simply by using generic locators, or even simpler by using the forEach macros.

Member Function Documentation

getElement()

template<class Type >

Type Hurricane::Locator< Type >::getElement ( ) const

pure virtual

Returns: the current element (or the value Type() when the locator is not or no longer valid).

getClone()

template<class Type >

Locator< Type > * Hurricane::Locator< Type >::getClone ( ) const

pure virtual

This function allocates and returns a new locator that will have the same visiting course than the remaining one of the locator being cloned.

Remarks

In principle there is no need to call this function, but if you do so you must not forget to release the clone after its use or, from it, build a generic locator which will do that for you (to be explained later).

isValid()

template<class Type >

bool Hurricane::Locator< Type >::isValid ( ) const

pure virtual

Returns: true while the walk has not exhausted the set of elements, else false.

progress()

template<class Type >

void Hurricane::Locator< Type >::progress ( )

pure virtual

Moves forward the locator to the following element.

---

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

• Locator.h
• Locator.dox