249 lines
8.0 KiB
C++
249 lines
8.0 KiB
C++
|
|
// -*- 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.
|
|
*/
|
|
|
|
|
|
|
|
/*! \name Constructors
|
|
*/
|
|
// \{
|
|
|
|
/*! \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.
|
|
*/
|
|
|
|
// \}
|
|
|
|
|
|
/*! \name Destructors
|
|
*/
|
|
// \{
|
|
|
|
/*! \function Path::~Path();
|
|
* No description.
|
|
*/
|
|
|
|
// \}
|
|
|
|
|
|
/*! \name Operators
|
|
*/
|
|
// \{
|
|
|
|
/*! \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.
|
|
*/
|
|
|
|
// \}
|
|
|
|
|
|
|
|
/*! \name Accessors
|
|
*/
|
|
// \{
|
|
|
|
/*! \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\>.
|
|
*/
|
|
|
|
// \}
|
|
|
|
|
|
/*! \name Predicates
|
|
*/
|
|
// \{
|
|
|
|
/*! \function bool Path::isEmpty() const;
|
|
* \Return \true if the path is void and else \false.
|
|
*/
|
|
|
|
// \}
|
|
|
|
|
|
/*! \name Path Functions
|
|
*/
|
|
// \{
|
|
|
|
/*! \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.
|
|
*/
|
|
|
|
// \}
|
|
|
|
|
|
}
|