// -*- C++ -*-


 namespace Hurricane {

 /*! \class        Path
  *  \brief        Path description (\b API)
  *
  *  \section      secPathIntro  Introduction
  *
  *                Pathes are objects representing an ordered sequence of 
  *                instances through the hierarchy. 
  *
  *                They are represented by a head instance which defines the 
  *                path start and tail path which defines the remaining path 
  *                with respect to the cell model referenced by the head 
  *                instance. 
  *
  *                terminology A non void path begins by an instance : this 
  *                instance pertains to the top caller cell, named OwnerCell. On 
  *                the other hand the path ends by an instance (which may be the 
  *                same) : this instance refers to its model which will be named 
  *                the MasterCell. 
  * 
  * 
  *  \section      secPathRemarks  Remarks
  *
  *                The different constructors (appart the one which analyses the 
  *                names of the path) as welle as the destructor and the 
  *                different operators are very efficient because the tail 
  *                pathes being shared, only pointer assignments and pointer 
  *                comparisons are realized. 
  */


 /*! \function     Path::Path(SharedPath* sharedPath=NULL);
  *                Default constructor : the path is then void. 
  *
  *  \remark       This path has no instance and will be the tail terminal path 
  *                of any other path. 
  */

 /*! \function     Path::Path(Instance* instance);
  *                Builds the path made up of this unique instance. 
  *
  *  \caution      If the instance is null an exception is thrown. 
  */

 /*! \function     Path::Path(Instance* headInstance, const Path& tailPath);
  *                Builds the path with head instance \c \<headInstance\> and 
  *                tail path \c \<tailPath\>. 
  *
  *  \caution      If the instance is null, or if the tail path is not 
  *                compatible with this head instance, an exception is thrown. 
  *
  *  \remark       The head instance and the tail path are compatible if the 
  *                tail path is void or if the owner cell of the tail path is 
  *                the model cell referenced by the head instance. 
  */

 /*! \function     Path::Path(const Path& headPath, Instance* tailInstance);
  *                Builds the path with head path \c \<headPath\> and tail 
  *                instance \c \<tailInstance\>. 
  *
  *  \caution      If the tail instance is null, or if the head path is not 
  *                compatible with this tail instance, an exception is thrown. 
  *
  *  \remark       The tail instance and the head path are compatible if the 
  *                owner cell of the tail instance is the master cell of the 
  *                head path (which is recall it, the model cell referenced by 
  *                the last instance of the head path) or if the head path is 
  *                empty (then compatible with any non null instance). 
  */

 /*! \function     Path::Path(Cell* cell, const string& pathName);
  *                Builds the path representing the logic sequence of instance 
  *                names described as a character string. Each instance name is 
  *                separated from the preceeding one by a special delimiter 
  *                (which can be defined with the function 
  *                <b>setPathNameSeparator</b> to be defined later). The cell 
  *                given in argument defines where sarts the search (at each new 
  *                instance identified, we go to its model cell to pursue the 
  *                search within the \c \<pathName\>). 
  *
  *  \caution      If the cell is null or if the name doesn't correspond to an 
  *                existing hierarchical instanciation path an exception is 
  *                thrown. 
  */

 /*! \function     Path::Path(const Path& path);
  *                Copy constructor. 
  */


 /*! \function     Path::~Path();
  *                No description.
  */


 /*! \function     Path& Path::operator=(const Path& path);
  *                Assignment operator. 
  */

 /*! \function     bool Path::operator==(const Path& path) const;
  *                Two pathes are equal if they have the same head instance and 
  *                if their tail pathes are equal. 
  */

 /*! \function     bool Path::operator!=(const Path& path) const;
  *                Two pathes are differents either if they have different head 
  *                instance or if the tail pathes differ. 
  */

 /*! \function     bool Path::operator<(const Path& path) const;
  *                This comparator has no particular signification. It is just 
  *                defined to be abble to use a STL set of pathes which need a 
  *                comparator. 
  */


 /*! \function     Instance* Path::getHeadInstance() const;
  *  \Return       the head instance or NULL if the path is void. 
  */

 /*! \function     Path Path::getTailPath() const;
  *  \Return       the tail path or a void path if the path has 1 or 0 
  *                hierarchical depth. 
  */

 /*! \function     Path Path::getHeadPath() const;
  *  \Return       the head path or a void path if the path has 1 or 0 
  *                hierarchical depth. 
  */

 /*! \function     Instance* Path::getTailInstance() const;
  *  \Return       the tail instance or NULL if the path is void. 
  */

 /*! \function     string Path::getName() const;
  *  \Return       a string defined by the concatenation of instance names 
  *                separated by a special character (which can be set up by the 
  *                function <b>setPathNameSeparator</b>). 
  *
  *  \Return       the string <b>""</b> when the path is void. 
  */

 /*! \function     Cell* Path::getOwnerCell() const;
  *                Retruns the cell owning the head instance or NULL if the path 
  *                is void. 
  */

 /*! \function     Cell* Path::getMasterCell() const;
  *  \Return       the master cell referenced by the last instance of the path 
  *                or NULL if the path is void. 
  */

 /*! \function     Instances Path::getInstances() const;
  *  \Return       the collection of instances defining the path. 
  */

 /*! \function     Transformation Path::getTransformation(const Transformation& transformation = Transformation()) const;
  *  \Return       the transform resulting of the composition of all transforms 
  *                associated with the different instances of the path, applied 
  *                to the given \c \<transformation\>. 
  */


 /*! \function     bool Path::isEmpty() const;
  *  \Return       \true if the path is void and else \false. 
  */


 /*! \function     char Path::getNameSeparator();
  *  \Return       the special character used as a separator between the 
  *                instance names of a path. By default it is the '.' (point). 
  */

 /*! \function     void Path::setNameSeparator(char separator);
  *                This function sets the special character used as a separator 
  *                between the instance names of a path (choose it carrefully, 
  *                it must not appear in any instance name). 
  */


 //! \name         Path Collection
 //  \{

 /*! \typedef      Pathes
  *                Collection representing a set of pathes. 
  */

 /*! \typedef      PathLocator
  *                Locator for traversing a collection of pathes. 
  */

 /*! \typedef      PathFilter
  *                Filter for selecting a subset of pathes matching some 
  *                criteria. 
  */

 /*! \def          for_each_path(path, pathes)
  *                Macro for visiting all pathes of a path collection. 
  */

 //  \}


 }