145 lines
4.2 KiB
C++
145 lines
4.2 KiB
C++
|
|
// -*- C++ -*-
|
|
|
|
|
|
namespace Hurricane {
|
|
|
|
/*! \class Locator
|
|
* \brief Locator description (\b API)
|
|
*
|
|
* \section secLocatorIntro Introduction
|
|
*
|
|
* Locators are objects which allow to walk efficiently through
|
|
* the data structure.
|
|
*/
|
|
|
|
|
|
|
|
/*! \section secLocatorGeneralConcepts General concepts
|
|
*
|
|
* <b>Initialization</b> 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.
|
|
*
|
|
* <b>End of walk indicator</b> The predicate <b>IsValid()</b>
|
|
* returns \true if the locator refers an element of the set,
|
|
* \false when all the elements have been visited.
|
|
*
|
|
* <b>Getting the current element</b> The current element is
|
|
* obtained by the accessor <b>GetElement()</b>. There is no
|
|
* risk to call this function when the visit is finished or the
|
|
* locator is non initialized (the returned value is
|
|
* meaningless).
|
|
*
|
|
* <b>Walk progression</b> The function <b>Progress()</b> moves
|
|
* forward the locator on the next element of the set (does
|
|
* nothing if called after the last element).
|
|
*/
|
|
|
|
|
|
|
|
/*! \section secLocatorUsageExamples Usage examples
|
|
*
|
|
* The following sample code shows how to trace the nets of a
|
|
* given cell
|
|
\code
|
|
Cell* cell = ...; // we get the cell
|
|
|
|
if (cell) {
|
|
|
|
// CellGetNets()
|
|
// returns the nets collection of the cell
|
|
// and GetLocator()
|
|
// allocates and returns a locator for traversing those nets
|
|
Locator<Net*>* locator = CellGetNets().GetLocator();
|
|
|
|
while (locatorIsValid()) {
|
|
Net* net = locatorGetElement();
|
|
assert(netGetCell() == cell);
|
|
locatorProgress();
|
|
}
|
|
|
|
// don't forget to release the allocated locator
|
|
delete locator;
|
|
}
|
|
\endcode
|
|
* And this one how to print all pairs of nets of a given cell
|
|
\code
|
|
Cell* cell = ...; // we get a cell
|
|
|
|
if (cell) {
|
|
Locator<Net*>* locator1 = CellGetNets().GetLocator();
|
|
while (locator1IsValid()) {
|
|
Net* net1 = locator1GetElement();
|
|
|
|
Locator<Net*>* locator2 = locator1GetClone();
|
|
while (locator2IsValid()) {
|
|
Net* net2 = locator2GetElement();
|
|
cerr << net1 << " " << net2 << endl;
|
|
locator2Progress();
|
|
}
|
|
delete locator2;
|
|
|
|
locator1Progress();
|
|
}
|
|
delete locator1;
|
|
}
|
|
\endcode
|
|
* \remark 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
|
|
* for_each macros.
|
|
*/
|
|
|
|
|
|
|
|
/*! \name Accessors
|
|
*/
|
|
// \{
|
|
|
|
/*! \function Type Locator::GetElement() const;
|
|
* \Return the current element (or the value <b>Type()</b> when the
|
|
* locator is not or no longer valid).
|
|
*/
|
|
|
|
/*! \function Locator<Type>* Locator::GetClone() const;
|
|
* This function allocates and returns a new locator that will
|
|
* have the same visiting course than the remaining one of the
|
|
* locator being cloned.
|
|
*
|
|
* \remark 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).
|
|
*/
|
|
|
|
// \}
|
|
|
|
|
|
/*! \name Predicates
|
|
*/
|
|
// \{
|
|
|
|
/*! \function bool Locator::IsValid() const;
|
|
* \Return \true while the walk has not exhausted the set of elements,
|
|
* else \false.
|
|
*/
|
|
|
|
// \}
|
|
|
|
|
|
/*! \name Modifiers
|
|
*/
|
|
// \{
|
|
|
|
/*! \function void Locator::Progress();
|
|
* Moves forward the locator to the following element.
|
|
*/
|
|
|
|
// \}
|
|
|
|
|
|
}
|