
 // -*- 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. 
  */

 //  \}


 }
