diff -r e9c203fb003d -r 994c7df296c9 lemon/dfs.h --- a/lemon/dfs.h Fri Nov 13 12:33:33 2009 +0100 +++ b/lemon/dfs.h Thu Dec 10 17:05:35 2009 +0100 @@ -2,7 +2,7 @@ * * This file is a part of LEMON, a generic C++ optimization library. * - * Copyright (C) 2003-2008 + * Copyright (C) 2003-2009 * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport * (Egervary Research Group on Combinatorial Optimization, EGRES). * @@ -49,11 +49,11 @@ ///arcs of the %DFS paths. ///It must meet the \ref concepts::WriteMap "WriteMap" concept. typedef typename Digraph::template NodeMap PredMap; - ///Instantiates a PredMap. + ///Instantiates a \c PredMap. - ///This function instantiates a PredMap. + ///This function instantiates a \ref PredMap. ///\param g is the digraph, to which we would like to define the - ///PredMap. + ///\ref PredMap. static PredMap *createPredMap(const Digraph &g) { return new PredMap(g); @@ -64,11 +64,11 @@ ///The type of the map that indicates which nodes are processed. ///It must meet the \ref concepts::WriteMap "WriteMap" concept. typedef NullMap ProcessedMap; - ///Instantiates a ProcessedMap. + ///Instantiates a \c ProcessedMap. - ///This function instantiates a ProcessedMap. + ///This function instantiates a \ref ProcessedMap. ///\param g is the digraph, to which - ///we would like to define the ProcessedMap + ///we would like to define the \ref ProcessedMap. #ifdef DOXYGEN static ProcessedMap *createProcessedMap(const Digraph &g) #else @@ -83,11 +83,11 @@ ///The type of the map that indicates which nodes are reached. ///It must meet the \ref concepts::ReadWriteMap "ReadWriteMap" concept. typedef typename Digraph::template NodeMap ReachedMap; - ///Instantiates a ReachedMap. + ///Instantiates a \c ReachedMap. - ///This function instantiates a ReachedMap. + ///This function instantiates a \ref ReachedMap. ///\param g is the digraph, to which - ///we would like to define the ReachedMap. + ///we would like to define the \ref ReachedMap. static ReachedMap *createReachedMap(const Digraph &g) { return new ReachedMap(g); @@ -98,11 +98,11 @@ ///The type of the map that stores the distances of the nodes. ///It must meet the \ref concepts::WriteMap "WriteMap" concept. typedef typename Digraph::template NodeMap DistMap; - ///Instantiates a DistMap. + ///Instantiates a \c DistMap. - ///This function instantiates a DistMap. + ///This function instantiates a \ref DistMap. ///\param g is the digraph, to which we would like to define the - ///DistMap. + ///\ref DistMap. static DistMap *createDistMap(const Digraph &g) { return new DistMap(g); @@ -119,13 +119,7 @@ ///used easier. /// ///\tparam GR The type of the digraph the algorithm runs on. - ///The default value is \ref ListDigraph. The value of GR is not used - ///directly by \ref Dfs, it is only passed to \ref DfsDefaultTraits. - ///\tparam TR Traits class to set various data types used by the algorithm. - ///The default traits class is - ///\ref DfsDefaultTraits "DfsDefaultTraits". - ///See \ref DfsDefaultTraits for the documentation of - ///a Dfs traits class. + ///The default type is \ref ListDigraph. #ifdef DOXYGEN template @@ -151,7 +145,7 @@ ///The type of the paths. typedef PredMapPath Path; - ///The traits class. + ///The \ref DfsDefaultTraits "traits class" of the algorithm. typedef TR Traits; private: @@ -212,7 +206,7 @@ typedef Dfs Create; - ///\name Named template parameters + ///\name Named Template Parameters ///@{ @@ -226,10 +220,11 @@ } }; ///\brief \ref named-templ-param "Named parameter" for setting - ///PredMap type. + ///\c PredMap type. /// ///\ref named-templ-param "Named parameter" for setting - ///PredMap type. + ///\c PredMap type. + ///It must meet the \ref concepts::WriteMap "WriteMap" concept. template struct SetPredMap : public Dfs > { typedef Dfs > Create; @@ -245,10 +240,11 @@ } }; ///\brief \ref named-templ-param "Named parameter" for setting - ///DistMap type. + ///\c DistMap type. /// ///\ref named-templ-param "Named parameter" for setting - ///DistMap type. + ///\c DistMap type. + ///It must meet the \ref concepts::WriteMap "WriteMap" concept. template struct SetDistMap : public Dfs< Digraph, SetDistMapTraits > { typedef Dfs > Create; @@ -264,10 +260,11 @@ } }; ///\brief \ref named-templ-param "Named parameter" for setting - ///ReachedMap type. + ///\c ReachedMap type. /// ///\ref named-templ-param "Named parameter" for setting - ///ReachedMap type. + ///\c ReachedMap type. + ///It must meet the \ref concepts::ReadWriteMap "ReadWriteMap" concept. template struct SetReachedMap : public Dfs< Digraph, SetReachedMapTraits > { typedef Dfs< Digraph, SetReachedMapTraits > Create; @@ -283,10 +280,11 @@ } }; ///\brief \ref named-templ-param "Named parameter" for setting - ///ProcessedMap type. + ///\c ProcessedMap type. /// ///\ref named-templ-param "Named parameter" for setting - ///ProcessedMap type. + ///\c ProcessedMap type. + ///It must meet the \ref concepts::WriteMap "WriteMap" concept. template struct SetProcessedMap : public Dfs< Digraph, SetProcessedMapTraits > { typedef Dfs< Digraph, SetProcessedMapTraits > Create; @@ -300,10 +298,10 @@ } }; ///\brief \ref named-templ-param "Named parameter" for setting - ///ProcessedMap type to be Digraph::NodeMap. + ///\c ProcessedMap type to be Digraph::NodeMap. /// ///\ref named-templ-param "Named parameter" for setting - ///ProcessedMap type to be Digraph::NodeMap. + ///\c ProcessedMap type to be Digraph::NodeMap. ///If you don't set it explicitly, it will be automatically allocated. struct SetStandardProcessedMap : public Dfs< Digraph, SetStandardProcessedMapTraits > { @@ -338,9 +336,10 @@ ///Sets the map that stores the predecessor arcs. ///Sets the map that stores the predecessor arcs. - ///If you don't use this function before calling \ref run(), - ///it will allocate one. The destructor deallocates this - ///automatically allocated map, of course. + ///If you don't use this function before calling \ref run(Node) "run()" + ///or \ref init(), an instance will be allocated automatically. + ///The destructor deallocates this automatically allocated map, + ///of course. ///\return (*this) Dfs &predMap(PredMap &m) { @@ -355,9 +354,10 @@ ///Sets the map that indicates which nodes are reached. ///Sets the map that indicates which nodes are reached. - ///If you don't use this function before calling \ref run(), - ///it will allocate one. The destructor deallocates this - ///automatically allocated map, of course. + ///If you don't use this function before calling \ref run(Node) "run()" + ///or \ref init(), an instance will be allocated automatically. + ///The destructor deallocates this automatically allocated map, + ///of course. ///\return (*this) Dfs &reachedMap(ReachedMap &m) { @@ -372,9 +372,10 @@ ///Sets the map that indicates which nodes are processed. ///Sets the map that indicates which nodes are processed. - ///If you don't use this function before calling \ref run(), - ///it will allocate one. The destructor deallocates this - ///automatically allocated map, of course. + ///If you don't use this function before calling \ref run(Node) "run()" + ///or \ref init(), an instance will be allocated automatically. + ///The destructor deallocates this automatically allocated map, + ///of course. ///\return (*this) Dfs &processedMap(ProcessedMap &m) { @@ -390,9 +391,10 @@ ///Sets the map that stores the distances of the nodes calculated by ///the algorithm. - ///If you don't use this function before calling \ref run(), - ///it will allocate one. The destructor deallocates this - ///automatically allocated map, of course. + ///If you don't use this function before calling \ref run(Node) "run()" + ///or \ref init(), an instance will be allocated automatically. + ///The destructor deallocates this automatically allocated map, + ///of course. ///\return (*this) Dfs &distMap(DistMap &m) { @@ -406,22 +408,20 @@ public: - ///\name Execution control - ///The simplest way to execute the algorithm is to use - ///one of the member functions called \ref lemon::Dfs::run() "run()". - ///\n - ///If you need more control on the execution, first you must call - ///\ref lemon::Dfs::init() "init()", then you can add a source node - ///with \ref lemon::Dfs::addSource() "addSource()". - ///Finally \ref lemon::Dfs::start() "start()" will perform the - ///actual path computation. + ///\name Execution Control + ///The simplest way to execute the DFS algorithm is to use one of the + ///member functions called \ref run(Node) "run()".\n + ///If you need more control on the execution, first you have to call + ///\ref init(), then you can add a source node with \ref addSource() + ///and perform the actual computation with \ref start(). + ///This procedure can be repeated if there are nodes that have not + ///been reached. ///@{ + ///\brief Initializes the internal data structures. + /// ///Initializes the internal data structures. - - ///Initializes the internal data structures. - /// void init() { create_maps(); @@ -438,11 +438,10 @@ ///Adds a new source node to the set of nodes to be processed. /// - ///\pre The stack must be empty. (Otherwise the algorithm gives - ///false results.) - /// - ///\warning Distances will be wrong (or at least strange) in case of - ///multiple sources. + ///\pre The stack must be empty. Otherwise the algorithm gives + ///wrong results. (One of the outgoing arcs of all the source nodes + ///except for the last one will not be visited and distances will + ///also be wrong.) void addSource(Node s) { LEMON_DEBUG(emptyQueue(), "The stack is not empty."); @@ -506,16 +505,16 @@ return _stack_head>=0?_stack[_stack_head]:INVALID; } - ///\brief Returns \c false if there are nodes - ///to be processed. - /// - ///Returns \c false if there are nodes - ///to be processed in the queue (stack). + ///Returns \c false if there are nodes to be processed. + + ///Returns \c false if there are nodes to be processed + ///in the queue (stack). bool emptyQueue() const { return _stack_head<0; } ///Returns the number of the nodes to be processed. - ///Returns the number of the nodes to be processed in the queue (stack). + ///Returns the number of the nodes to be processed + ///in the queue (stack). int queueSize() const { return _stack_head+1; } ///Executes the algorithm. @@ -637,8 +636,8 @@ ///%DFS path to each node. /// ///The algorithm computes - ///- the %DFS tree, - ///- the distance of each node from the root in the %DFS tree. + ///- the %DFS tree (forest), + ///- the distance of each node from the root(s) in the %DFS tree. /// ///\note d.run() is just a shortcut of the following code. ///\code @@ -663,10 +662,10 @@ ///@} ///\name Query Functions - ///The result of the %DFS algorithm can be obtained using these + ///The results of the DFS algorithm can be obtained using these ///functions.\n - ///Either \ref lemon::Dfs::run() "run()" or \ref lemon::Dfs::start() - ///"start()" must be called before using them. + ///Either \ref run(Node) "run()" or \ref start() should be called + ///before using them. ///@{ @@ -674,49 +673,49 @@ ///Returns the DFS path to a node. /// - ///\warning \c t should be reachable from the root. + ///\warning \c t should be reached from the root(s). /// - ///\pre Either \ref run() or \ref start() must be called before - ///using this function. + ///\pre Either \ref run(Node) "run()" or \ref init() + ///must be called before using this function. Path path(Node t) const { return Path(*G, *_pred, t); } - ///The distance of a node from the root. + ///The distance of a node from the root(s). - ///Returns the distance of a node from the root. + ///Returns the distance of a node from the root(s). /// - ///\warning If node \c v is not reachable from the root, then + ///\warning If node \c v is not reached from the root(s), then ///the return value of this function is undefined. /// - ///\pre Either \ref run() or \ref start() must be called before - ///using this function. + ///\pre Either \ref run(Node) "run()" or \ref init() + ///must be called before using this function. int dist(Node v) const { return (*_dist)[v]; } ///Returns the 'previous arc' of the %DFS tree for a node. ///This function returns the 'previous arc' of the %DFS tree for the - ///node \c v, i.e. it returns the last arc of a %DFS path from the - ///root to \c v. It is \c INVALID - ///if \c v is not reachable from the root(s) or if \c v is a root. + ///node \c v, i.e. it returns the last arc of a %DFS path from a + ///root to \c v. It is \c INVALID if \c v is not reached from the + ///root(s) or if \c v is a root. /// ///The %DFS tree used here is equal to the %DFS tree used in ///\ref predNode(). /// - ///\pre Either \ref run() or \ref start() must be called before using - ///this function. + ///\pre Either \ref run(Node) "run()" or \ref init() + ///must be called before using this function. Arc predArc(Node v) const { return (*_pred)[v];} ///Returns the 'previous node' of the %DFS tree. ///This function returns the 'previous node' of the %DFS ///tree for the node \c v, i.e. it returns the last but one node - ///from a %DFS path from the root to \c v. It is \c INVALID - ///if \c v is not reachable from the root(s) or if \c v is a root. + ///from a %DFS path from a root to \c v. It is \c INVALID + ///if \c v is not reached from the root(s) or if \c v is a root. /// ///The %DFS tree used here is equal to the %DFS tree used in ///\ref predArc(). /// - ///\pre Either \ref run() or \ref start() must be called before - ///using this function. + ///\pre Either \ref run(Node) "run()" or \ref init() + ///must be called before using this function. Node predNode(Node v) const { return (*_pred)[v]==INVALID ? INVALID: G->source((*_pred)[v]); } @@ -726,7 +725,7 @@ ///Returns a const reference to the node map that stores the ///distances of the nodes calculated by the algorithm. /// - ///\pre Either \ref run() or \ref init() + ///\pre Either \ref run(Node) "run()" or \ref init() ///must be called before using this function. const DistMap &distMap() const { return *_dist;} @@ -736,14 +735,15 @@ ///Returns a const reference to the node map that stores the predecessor ///arcs, which form the DFS tree. /// - ///\pre Either \ref run() or \ref init() + ///\pre Either \ref run(Node) "run()" or \ref init() ///must be called before using this function. const PredMap &predMap() const { return *_pred;} - ///Checks if a node is reachable from the root(s). + ///Checks if a node is reached from the root(s). - ///Returns \c true if \c v is reachable from the root(s). - ///\pre Either \ref run() or \ref start() + ///Returns \c true if \c v is reached from the root(s). + /// + ///\pre Either \ref run(Node) "run()" or \ref init() ///must be called before using this function. bool reached(Node v) const { return (*_reached)[v]; } @@ -889,8 +889,8 @@ /// This auxiliary class is created to implement the /// \ref dfs() "function-type interface" of \ref Dfs algorithm. - /// It does not have own \ref run() method, it uses the functions - /// and features of the plain \ref Dfs. + /// It does not have own \ref run(Node) "run()" method, it uses the + /// functions and features of the plain \ref Dfs. /// /// This class should only be used through the \ref dfs() function, /// which makes it easier to use the algorithm. @@ -1110,8 +1110,7 @@ /// // Compute the DFS path from s to t /// bool reached = dfs(g).path(p).dist(d).run(s,t); ///\endcode - - ///\warning Don't forget to put the \ref DfsWizard::run() "run()" + ///\warning Don't forget to put the \ref DfsWizard::run(Node) "run()" ///to the end of the parameter list. ///\sa DfsWizard ///\sa Dfs @@ -1127,9 +1126,9 @@ /// /// This class defines the interface of the DfsVisit events, and /// it could be the base of a real visitor class. - template + template struct DfsVisitor { - typedef _Digraph Digraph; + typedef GR Digraph; typedef typename Digraph::Arc Arc; typedef typename Digraph::Node Node; /// \brief Called for the source node of the DFS. @@ -1165,9 +1164,9 @@ void backtrack(const Arc& arc) {} }; #else - template + template struct DfsVisitor { - typedef _Digraph Digraph; + typedef GR Digraph; typedef typename Digraph::Arc Arc; typedef typename Digraph::Node Node; void start(const Node&) {} @@ -1200,11 +1199,11 @@ /// /// Default traits class of DfsVisit class. /// \tparam _Digraph The type of the digraph the algorithm runs on. - template + template struct DfsVisitDefaultTraits { /// \brief The type of the digraph the algorithm runs on. - typedef _Digraph Digraph; + typedef GR Digraph; /// \brief The type of the map that indicates which nodes are reached. /// @@ -1225,12 +1224,12 @@ /// \ingroup search /// - /// \brief %DFS algorithm class with visitor interface. + /// \brief DFS algorithm class with visitor interface. /// - /// This class provides an efficient implementation of the %DFS algorithm + /// This class provides an efficient implementation of the DFS algorithm /// with visitor interface. /// - /// The %DfsVisit class provides an alternative interface to the Dfs + /// The DfsVisit class provides an alternative interface to the Dfs /// class. It works with callback mechanism, the DfsVisit object calls /// the member functions of the \c Visitor class on every DFS event. /// @@ -1239,37 +1238,37 @@ /// events of the DFS algorithm. Otherwise consider to use Dfs or dfs() /// instead. /// - /// \tparam _Digraph The type of the digraph the algorithm runs on. - /// The default value is - /// \ref ListDigraph. The value of _Digraph is not used directly by - /// \ref DfsVisit, it is only passed to \ref DfsVisitDefaultTraits. - /// \tparam _Visitor The Visitor type that is used by the algorithm. - /// \ref DfsVisitor "DfsVisitor<_Digraph>" is an empty visitor, which + /// \tparam GR The type of the digraph the algorithm runs on. + /// The default type is \ref ListDigraph. + /// The value of GR is not used directly by \ref DfsVisit, + /// it is only passed to \ref DfsVisitDefaultTraits. + /// \tparam VS The Visitor type that is used by the algorithm. + /// \ref DfsVisitor "DfsVisitor" is an empty visitor, which /// does not observe the DFS events. If you want to observe the DFS /// events, you should implement your own visitor class. - /// \tparam _Traits Traits class to set various data types used by the + /// \tparam TR Traits class to set various data types used by the /// algorithm. The default traits class is - /// \ref DfsVisitDefaultTraits "DfsVisitDefaultTraits<_Digraph>". + /// \ref DfsVisitDefaultTraits "DfsVisitDefaultTraits". /// See \ref DfsVisitDefaultTraits for the documentation of /// a DFS visit traits class. #ifdef DOXYGEN - template + template #else - template , - typename _Traits = DfsVisitDefaultTraits<_Digraph> > + template , + typename TR = DfsVisitDefaultTraits > #endif class DfsVisit { public: ///The traits class. - typedef _Traits Traits; + typedef TR Traits; ///The type of the digraph the algorithm runs on. typedef typename Traits::Digraph Digraph; ///The visitor type used by the algorithm. - typedef _Visitor Visitor; + typedef VS Visitor; ///The type of the map that indicates which nodes are reached. typedef typename Traits::ReachedMap ReachedMap; @@ -1309,7 +1308,7 @@ typedef DfsVisit Create; - /// \name Named template parameters + /// \name Named Template Parameters ///@{ template @@ -1351,9 +1350,10 @@ /// \brief Sets the map that indicates which nodes are reached. /// /// Sets the map that indicates which nodes are reached. - /// If you don't use this function before calling \ref run(), - /// it will allocate one. The destructor deallocates this - /// automatically allocated map, of course. + /// If you don't use this function before calling \ref run(Node) "run()" + /// or \ref init(), an instance will be allocated automatically. + /// The destructor deallocates this automatically allocated map, + /// of course. /// \return (*this) DfsVisit &reachedMap(ReachedMap &m) { if(local_reached) { @@ -1366,16 +1366,14 @@ public: - /// \name Execution control - /// The simplest way to execute the algorithm is to use - /// one of the member functions called \ref lemon::DfsVisit::run() - /// "run()". - /// \n - /// If you need more control on the execution, first you must call - /// \ref lemon::DfsVisit::init() "init()", then you can add several - /// source nodes with \ref lemon::DfsVisit::addSource() "addSource()". - /// Finally \ref lemon::DfsVisit::start() "start()" will perform the - /// actual path computation. + /// \name Execution Control + /// The simplest way to execute the DFS algorithm is to use one of the + /// member functions called \ref run(Node) "run()".\n + /// If you need more control on the execution, first you have to call + /// \ref init(), then you can add a source node with \ref addSource() + /// and perform the actual computation with \ref start(). + /// This procedure can be repeated if there are nodes that have not + /// been reached. /// @{ @@ -1391,15 +1389,14 @@ } } - ///Adds a new source node. - - ///Adds a new source node to the set of nodes to be processed. + /// \brief Adds a new source node. /// - ///\pre The stack must be empty. (Otherwise the algorithm gives - ///false results.) + /// Adds a new source node to the set of nodes to be processed. /// - ///\warning Distances will be wrong (or at least strange) in case of - ///multiple sources. + /// \pre The stack must be empty. Otherwise the algorithm gives + /// wrong results. (One of the outgoing arcs of all the source nodes + /// except for the last one will not be visited and distances will + /// also be wrong.) void addSource(Node s) { LEMON_DEBUG(emptyQueue(), "The stack is not empty."); @@ -1413,6 +1410,7 @@ _stack[++_stack_head] = e; } else { _visitor->leave(s); + _visitor->stop(s); } } } @@ -1589,8 +1587,8 @@ /// compute the %DFS path to each node. /// /// The algorithm computes - /// - the %DFS tree, - /// - the distance of each node from the root in the %DFS tree. + /// - the %DFS tree (forest), + /// - the distance of each node from the root(s) in the %DFS tree. /// /// \note d.run() is just a shortcut of the following code. ///\code @@ -1615,19 +1613,20 @@ ///@} /// \name Query Functions - /// The result of the %DFS algorithm can be obtained using these + /// The results of the DFS algorithm can be obtained using these /// functions.\n - /// Either \ref lemon::DfsVisit::run() "run()" or - /// \ref lemon::DfsVisit::start() "start()" must be called before - /// using them. + /// Either \ref run(Node) "run()" or \ref start() should be called + /// before using them. + ///@{ - /// \brief Checks if a node is reachable from the root(s). + /// \brief Checks if a node is reached from the root(s). /// - /// Returns \c true if \c v is reachable from the root(s). - /// \pre Either \ref run() or \ref start() + /// Returns \c true if \c v is reached from the root(s). + /// + /// \pre Either \ref run(Node) "run()" or \ref init() /// must be called before using this function. - bool reached(Node v) { return (*_reached)[v]; } + bool reached(Node v) const { return (*_reached)[v]; } ///@}