source: lemon-0.x/src/hugo/skeletons/path.h @ 808:9cabbdd73375

// -*- c++ -*- //

///\ingroup skeletons
///\file
///\brief Classes for representing paths in graphs.

#ifndef HUGO_PATH_H
#define HUGO_PATH_H

#include <hugo/invalid.h>

namespace hugo {
  namespace skeleton {
    /// \addtogroup skeletons
    /// @{
    
    
    //! \brief A skeletom structure for representing directed paths in a graph.
    //!
    //! A skeleton structure for representing directed paths in a graph.
    //! \param GR The graph type in which the path is.
    //! 
    //! In a sense, the path can be treated as a graph, for is has \c NodeIt
    //! and \c EdgeIt with the same usage. These types converts to the \c Node
    //! and \c Edge of the original graph.
    template<typename GR>
    class Path {
    public:
      
      /// Type of the underlying graph.
      typedef typename GR Graph;
      /// Edge type of the underlying graph.
      typedef typename Graph::Edge GraphEdge; 
      /// Node type of the underlying graph.
      typedef typename Graph::Node GraphNode;
      class NodeIt;
      class EdgeIt;
      
      /// \param _G The graph in which the path is.
      ///
      Path(const Graph &_G) {}
      
      /// Length of the path.
      size_t length() const {}
      /// Returns whether the path is empty.
      bool empty() const {}
      
      /// Resets the path to an empty path.
      void clear() {}

      /// \brief Starting point of the path.
      ///
      /// Starting point of the path.
      /// Returns INVALID if the path is empty.
      NodeIt head() const {}
      /// \brief End point of the path.
      ///
      /// End point of the path.
      /// Returns INVALID if the path is empty.
      NodeIt tail() const {}

      /// \brief First NodeIt/EdgeIt.
      ///
      /// Initializes node or edge iterator to point to the first
      /// node or edge.
      template<typename It>
      It& first(It &i) const { return i=It(*this); }

      /// \brief The head of an edge.
      ///
      /// Returns node iterator pointing to the head node of the
      /// given edge iterator.
      NodeIt head(const EdgeIt& e) const {}

      /// \brief The tail of an edge.
      ///
      /// Returns node iterator pointing to the tail node of the
      /// given edge iterator.
      NodeIt tail(const EdgeIt& e) const {}


      /* Iterator classes */

      /**
       * \brief Iterator class to iterate on the edges of the paths
       * 
       * \ingroup skeletons
       * This class is used to iterate on the edges of the paths
       *
       * Of course it converts to Graph::Edge
       * 
       */
      class EdgeIt {
      public:
        /// Default constructor
        EdgeIt() {}
        /// Invalid constructor
        EdgeIt(Invalid) {}
        /// Constructor with starting point
        EdgeIt(const Path &_p) {}

        operator GraphEdge () const {}

        /// Next edge
        EdgeIt& operator++() {}

        /// Comparison operator
        bool operator==(const EdgeIt& e) const {}
        /// Comparison operator
        bool operator!=(const EdgeIt& e) const {}
//      /// Comparison operator
//      /// \todo It is not clear what is the "natural" ordering.
//      bool operator<(const EdgeIt& e) const {}

      };

      /**
       * \brief Iterator class to iterate on the nodes of the paths
       * 
       * \ingroup skeletons
       * This class is used to iterate on the nodes of the paths
       *
       * Of course it converts to Graph::Node.
       * 
       */
      class NodeIt {
      public:
        /// Default constructor
        NodeIt() {}
        /// Invalid constructor
        NodeIt(Invalid) {}
        /// Constructor with starting point
        NodeIt(const Path &_p) {}

        ///Conversion to Graph::Node
        operator const GraphNode& () const {}
        /// Next node
        NodeIt& operator++() {}

        /// Comparison operator
        bool operator==(const NodeIt& e) const {}
        /// Comparison operator
        bool operator!=(const NodeIt& e) const {}
//      /// Comparison operator
//      /// \todo It is not clear what is the "natural" ordering.
//      bool operator<(const NodeIt& e) const {}

      };

      friend class Builder;    

      /**
       * \brief Class to build paths
       * 
       * \ingroup skeletons
       * This class is used to fill a path with edges.
       *
       * You can push new edges to the front and to the back of the path in
       * arbitrary order then you should commit these changes to the graph.
       *
       * While the builder is active (after the first modifying
       * operation and until the call of \ref commit())
       * the underlining Path is in a
       * "transitional" state (operations on it have undefined result).
       */
      class Builder {
      public:
        ///\param _P the path you want to fill in.
        ///
        Builder(Path &_P) : P(_P) {}

        /// Sets the starting node of the path.
      
        /// Sets the starting node of the path. Edge added to the path
        /// afterwards have to be incident to this node.
        /// You \em must start building an empry path with this functions.
        /// (And you \em must \em not use it later).
        /// \sa pushFront()
        /// \sa pushBack()
        void setStartNode(const GraphNode &) {}

        ///Push a new edge to the front of the path

        ///Push a new edge to the front of the path.
        ///If the path is empty, you \em must call \ref setStartNode() before
        ///the first use of \ref pushFront().
        void pushFront(const GraphEdge& e) {}

        ///Push a new edge to the back of the path

        ///Push a new edge to the back of the path.
        ///If the path is empty, you \em must call \ref setStartNode() before
        ///the first use of \ref pushBack().
        void pushBack(const GraphEdge& e) {}

        ///Commit the changes to the path.
        void commit() {}

        ///Reserve (front) storage for the builder in advance.

        ///If you know an reasonable upper bound of the number of the edges
        ///to add to the front of the path,
        ///using this function you may speed up the building.
        void reserveFront(size_t r) {}
        ///Reserve (back) storage for the builder in advance.

        ///If you know an reasonable upper bound of the number of the edges
        ///to add to the back of the path,
        ///using this function you may speed up the building.
        void reserveBack(size_t r) {}
      };
    };

  ///@}
  }
  
} // namespace hugo

#endif // HUGO_PATH_H