// -*- 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.
  *
  *                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.
  *
  *
  *  \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) {
 
   // 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;
}
\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 = 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;
}
\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 
  *                forEach macros. 
  */


 /*! \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). 
  */


 /*! \function     bool Locator::isValid() const;
  *  \Return       \true while the walk has not exhausted the set of elements, 
  *                else \false. 
  */


 /*! \function     void Locator::progress();
  *                Moves forward the locator to the following element. 
  */


 /*! \class        GenericLocator
  *  \brief        Generic Locator auto-pointer.
  *
  *                This class is an auto-pointer like wrapped around the raw locator.
  *
  *  \remark       The destruction of a GenericLocator triggers the destruction of
  *                the raw locator.
  */

 /*! \function     GenericLocator::GenericLocator(Locator<Type>* locator);
  *                Constructor from a raw Locator.
  *
  *  \remark       This constructor do not build a copy of the raw locator. So the original
  *                raw locator must not be deleted. It's deletion will occurs with the one
  *                of the GenericLocator.
  */

 /*! \function     GenericLocator::GenericLocator(const Locator<Type>& locator);
  *                Constructor from a primary Locator.
  *
  *  \remark       This constructor build a \e copy of the raw locator. So the originating
  *                locator can be safely deleted.
  */

 /*! \function     GenericLocator::GenericLocator(const GenericLocator<Type>& locator);
  *                Constructor from a primary Locator and a Filter.
  *
  *  \remark       This constructor build a \e copy of the raw locator. So the originating
  *                locator can be safely deleted.
  */

 }