Reformatting: too long code lines.
2 * lemon/dfs.h - Part of LEMON, a generic C++ optimization library
4 * Copyright (C) 2006 Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
5 * (Egervary Research Group on Combinatorial Optimization, EGRES).
7 * Permission to use, modify and distribute this software is granted
8 * provided that this copyright notice appears in all copies. For
9 * precise terms see the accompanying LICENSE file.
11 * This software is provided "AS IS" with no warranty of any kind,
12 * express or implied, and with no claim as to its suitability for any
22 ///\brief Dfs algorithm.
24 #include <lemon/list_graph.h>
25 #include <lemon/graph_utils.h>
26 #include <lemon/invalid.h>
27 #include <lemon/error.h>
28 #include <lemon/maps.h>
30 #include <lemon/concept_check.h>
35 ///Default traits class of Dfs class.
37 ///Default traits class of Dfs class.
38 ///\param GR Graph type.
40 struct DfsDefaultTraits
42 ///The graph type the algorithm runs on.
44 ///\brief The type of the map that stores the last
45 ///edges of the %DFS paths.
47 ///The type of the map that stores the last
48 ///edges of the %DFS paths.
49 ///It must meet the \ref concept::WriteMap "WriteMap" concept.
51 typedef typename Graph::template NodeMap<typename GR::Edge> PredMap;
52 ///Instantiates a PredMap.
54 ///This function instantiates a \ref PredMap.
55 ///\param G is the graph, to which we would like to define the PredMap.
56 ///\todo The graph alone may be insufficient to initialize
57 static PredMap *createPredMap(const GR &G)
59 return new PredMap(G);
62 ///The type of the map that indicates which nodes are processed.
64 ///The type of the map that indicates which nodes are processed.
65 ///It must meet the \ref concept::WriteMap "WriteMap" concept.
66 ///\todo named parameter to set this type, function to read and write.
67 typedef NullMap<typename Graph::Node,bool> ProcessedMap;
68 ///Instantiates a ProcessedMap.
70 ///This function instantiates a \ref ProcessedMap.
71 ///\param g is the graph, to which
72 ///we would like to define the \ref ProcessedMap
74 static ProcessedMap *createProcessedMap(const GR &g)
76 static ProcessedMap *createProcessedMap(const GR &)
79 return new ProcessedMap();
81 ///The type of the map that indicates which nodes are reached.
83 ///The type of the map that indicates which nodes are reached.
84 ///It must meet the \ref concept::WriteMap "WriteMap" concept.
85 ///\todo named parameter to set this type, function to read and write.
86 typedef typename Graph::template NodeMap<bool> ReachedMap;
87 ///Instantiates a ReachedMap.
89 ///This function instantiates a \ref ReachedMap.
90 ///\param G is the graph, to which
91 ///we would like to define the \ref ReachedMap.
92 static ReachedMap *createReachedMap(const GR &G)
94 return new ReachedMap(G);
96 ///The type of the map that stores the dists of the nodes.
98 ///The type of the map that stores the dists of the nodes.
99 ///It must meet the \ref concept::WriteMap "WriteMap" concept.
101 typedef typename Graph::template NodeMap<int> DistMap;
102 ///Instantiates a DistMap.
104 ///This function instantiates a \ref DistMap.
105 ///\param G is the graph, to which we would like to define the \ref DistMap
106 static DistMap *createDistMap(const GR &G)
108 return new DistMap(G);
112 ///%DFS algorithm class.
115 ///This class provides an efficient implementation of the %DFS algorithm.
117 ///\param GR The graph type the algorithm runs on. The default value is
118 ///\ref ListGraph. The value of GR is not used directly by Dfs, it
119 ///is only passed to \ref DfsDefaultTraits.
120 ///\param TR Traits class to set various data types used by the algorithm.
121 ///The default traits class is
122 ///\ref DfsDefaultTraits "DfsDefaultTraits<GR>".
123 ///See \ref DfsDefaultTraits for the documentation of
124 ///a Dfs traits class.
126 ///\author Jacint Szabo and Alpar Juttner
128 template <typename GR,
131 template <typename GR=ListGraph,
132 typename TR=DfsDefaultTraits<GR> >
137 * \brief \ref Exception for uninitialized parameters.
139 * This error represents problems in the initialization
140 * of the parameters of the algorithms.
142 class UninitializedParameter : public lemon::UninitializedParameter {
144 virtual const char* exceptionName() const {
145 return "lemon::Dfs::UninitializedParameter";
150 ///The type of the underlying graph.
151 typedef typename TR::Graph Graph;
153 typedef typename Graph::Node Node;
155 typedef typename Graph::NodeIt NodeIt;
157 typedef typename Graph::Edge Edge;
159 typedef typename Graph::OutEdgeIt OutEdgeIt;
161 ///\brief The type of the map that stores the last
162 ///edges of the %DFS paths.
163 typedef typename TR::PredMap PredMap;
164 ///The type of the map indicating which nodes are reached.
165 typedef typename TR::ReachedMap ReachedMap;
166 ///The type of the map indicating which nodes are processed.
167 typedef typename TR::ProcessedMap ProcessedMap;
168 ///The type of the map that stores the dists of the nodes.
169 typedef typename TR::DistMap DistMap;
171 /// Pointer to the underlying graph.
173 ///Pointer to the map of predecessors edges.
175 ///Indicates if \ref _pred is locally allocated (\c true) or not.
177 ///Pointer to the map of distances.
179 ///Indicates if \ref _dist is locally allocated (\c true) or not.
181 ///Pointer to the map of reached status of the nodes.
182 ReachedMap *_reached;
183 ///Indicates if \ref _reached is locally allocated (\c true) or not.
185 ///Pointer to the map of processed status of the nodes.
186 ProcessedMap *_processed;
187 ///Indicates if \ref _processed is locally allocated (\c true) or not.
188 bool local_processed;
190 std::vector<typename Graph::OutEdgeIt> _stack;
193 ///Creates the maps if necessary.
195 ///\todo Better memory allocation (instead of new).
200 _pred = Traits::createPredMap(*G);
204 _dist = Traits::createDistMap(*G);
207 local_reached = true;
208 _reached = Traits::createReachedMap(*G);
211 local_processed = true;
212 _processed = Traits::createProcessedMap(*G);
224 ///\name Named template parameters
229 struct DefPredMapTraits : public Traits {
231 static PredMap *createPredMap(const Graph &G)
233 throw UninitializedParameter();
236 ///\ref named-templ-param "Named parameter" for setting PredMap type
238 ///\ref named-templ-param "Named parameter" for setting PredMap type
241 struct DefPredMap : public Dfs<Graph, DefPredMapTraits<T> > {
242 typedef Dfs<Graph, DefPredMapTraits<T> > Create;
247 struct DefDistMapTraits : public Traits {
249 static DistMap *createDistMap(const Graph &G)
251 throw UninitializedParameter();
254 ///\ref named-templ-param "Named parameter" for setting DistMap type
256 ///\ref named-templ-param "Named parameter" for setting DistMap type
260 typedef Dfs<Graph, DefDistMapTraits<T> > Create;
264 struct DefReachedMapTraits : public Traits {
265 typedef T ReachedMap;
266 static ReachedMap *createReachedMap(const Graph &G)
268 throw UninitializedParameter();
271 ///\ref named-templ-param "Named parameter" for setting ReachedMap type
273 ///\ref named-templ-param "Named parameter" for setting ReachedMap type
276 struct DefReachedMap : public Dfs< Graph, DefReachedMapTraits<T> > {
277 typedef Dfs< Graph, DefReachedMapTraits<T> > Create;
281 struct DefProcessedMapTraits : public Traits {
282 typedef T ProcessedMap;
283 static ProcessedMap *createProcessedMap(const Graph &G)
285 throw UninitializedParameter();
288 ///\ref named-templ-param "Named parameter" for setting ProcessedMap type
290 ///\ref named-templ-param "Named parameter" for setting ProcessedMap type
293 struct DefProcessedMap : public Dfs< Graph, DefProcessedMapTraits<T> > {
294 typedef Dfs< Graph, DefProcessedMapTraits<T> > Create;
297 struct DefGraphProcessedMapTraits : public Traits {
298 typedef typename Graph::template NodeMap<bool> ProcessedMap;
299 static ProcessedMap *createProcessedMap(const Graph &G)
301 return new ProcessedMap(G);
304 ///\brief \ref named-templ-param "Named parameter"
305 ///for setting the ProcessedMap type to be Graph::NodeMap<bool>.
307 ///\ref named-templ-param "Named parameter"
308 ///for setting the ProcessedMap type to be Graph::NodeMap<bool>.
309 ///If you don't set it explicitely, it will be automatically allocated.
311 class DefProcessedMapToBeDefaultMap :
312 public Dfs< Graph, DefGraphProcessedMapTraits> {
313 typedef Dfs< Graph, DefGraphProcessedMapTraits> Create;
322 ///\param _G the graph the algorithm will run on.
324 Dfs(const Graph& _G) :
326 _pred(NULL), local_pred(false),
327 _dist(NULL), local_dist(false),
328 _reached(NULL), local_reached(false),
329 _processed(NULL), local_processed(false)
335 if(local_pred) delete _pred;
336 if(local_dist) delete _dist;
337 if(local_reached) delete _reached;
338 if(local_processed) delete _processed;
341 ///Sets the map storing the predecessor edges.
343 ///Sets the map storing the predecessor edges.
344 ///If you don't use this function before calling \ref run(),
345 ///it will allocate one. The destuctor deallocates this
346 ///automatically allocated map, of course.
347 ///\return <tt> (*this) </tt>
348 Dfs &predMap(PredMap &m)
358 ///Sets the map storing the distances calculated by the algorithm.
360 ///Sets the map storing the distances calculated by the algorithm.
361 ///If you don't use this function before calling \ref run(),
362 ///it will allocate one. The destuctor deallocates this
363 ///automatically allocated map, of course.
364 ///\return <tt> (*this) </tt>
365 Dfs &distMap(DistMap &m)
375 ///Sets the map indicating if a node is reached.
377 ///Sets the map indicating if a node is reached.
378 ///If you don't use this function before calling \ref run(),
379 ///it will allocate one. The destuctor deallocates this
380 ///automatically allocated map, of course.
381 ///\return <tt> (*this) </tt>
382 Dfs &reachedMap(ReachedMap &m)
392 ///Sets the map indicating if a node is processed.
394 ///Sets the map indicating if a node is processed.
395 ///If you don't use this function before calling \ref run(),
396 ///it will allocate one. The destuctor deallocates this
397 ///automatically allocated map, of course.
398 ///\return <tt> (*this) </tt>
399 Dfs &processedMap(ProcessedMap &m)
401 if(local_processed) {
403 local_processed=false;
410 ///\name Execution control
411 ///The simplest way to execute the algorithm is to use
412 ///one of the member functions called \c run(...).
414 ///If you need more control on the execution,
415 ///first you must call \ref init(), then you can add a source node
416 ///with \ref addSource().
417 ///Finally \ref start() will perform the actual path
422 ///Initializes the internal data structures.
424 ///Initializes the internal data structures.
429 _stack.resize(countNodes(*G));
431 for ( NodeIt u(*G) ; u!=INVALID ; ++u ) {
432 _pred->set(u,INVALID);
433 // _predNode->set(u,INVALID);
434 _reached->set(u,false);
435 _processed->set(u,false);
439 ///Adds a new source node.
441 ///Adds a new source node to the set of nodes to be processed.
443 ///\warning dists are wrong (or at least strange)
444 ///in case of multiple sources.
445 void addSource(Node s)
449 _reached->set(s,true);
450 _pred->set(s,INVALID);
453 _stack[++_stack_head]=e;
454 _dist->set(s,_stack_head);
457 _processed->set(s,true);
463 ///Processes the next edge.
465 ///Processes the next edge.
467 ///\return The processed edge.
469 ///\pre The stack must not be empty!
470 Edge processNextEdge()
473 Edge e=_stack[_stack_head];
474 if(!(*_reached)[m=G->target(e)]) {
476 _reached->set(m,true);
478 _stack[_stack_head] = OutEdgeIt(*G, m);
479 _dist->set(m,_stack_head);
483 ++_stack[_stack_head];
485 while(_stack_head>=0 && _stack[_stack_head]==INVALID) {
486 _processed->set(m,true);
489 m=G->source(_stack[_stack_head]);
490 ++_stack[_stack_head];
495 ///Next edge to be processed.
497 ///Next edge to be processed.
499 ///\return The next edge to be processed or INVALID if the stack is
503 return _stack_head>=0?_stack[_stack_head]:INVALID;
506 ///\brief Returns \c false if there are nodes
507 ///to be processed in the queue
509 ///Returns \c false if there are nodes
510 ///to be processed in the queue
511 bool emptyQueue() { return _stack_head<0; }
512 ///Returns the number of the nodes to be processed.
514 ///Returns the number of the nodes to be processed in the queue.
515 int queueSize() { return _stack_head+1; }
517 ///Executes the algorithm.
519 ///Executes the algorithm.
521 ///\pre init() must be called and at least one node should be added
522 ///with addSource() before using this function.
524 ///This method runs the %DFS algorithm from the root node(s)
527 ///%DFS path to each node. The algorithm computes
529 ///- The distance of each node from the root(s) in the %DFS tree.
533 while ( !emptyQueue() ) processNextEdge();
536 ///Executes the algorithm until \c dest is reached.
538 ///Executes the algorithm until \c dest is reached.
540 ///\pre init() must be called and at least one node should be added
541 ///with addSource() before using this function.
543 ///This method runs the %DFS algorithm from the root node(s)
546 ///%DFS path to \c dest. The algorithm computes
547 ///- The %DFS path to \c dest.
548 ///- The distance of \c dest from the root(s) in the %DFS tree.
550 void start(Node dest)
552 while ( !emptyQueue() && G->target(_stack[_stack_head])!=dest )
556 ///Executes the algorithm until a condition is met.
558 ///Executes the algorithm until a condition is met.
560 ///\pre init() must be called and at least one node should be added
561 ///with addSource() before using this function.
563 ///\param em must be a bool (or convertible) edge map. The algorithm
564 ///will stop when it reaches an edge \c e with \code em[e]==true \endcode.
566 ///\warning Contrary to \ref Dfs and \ref Dijkstra, \c em is an edge map,
569 void start(const EM &em)
571 while ( !emptyQueue() && !em[_stack[_stack_head]] ) processNextEdge();
574 ///Runs %DFS algorithm from node \c s.
576 ///This method runs the %DFS algorithm from a root node \c s
579 ///%DFS path to each node. The algorithm computes
581 ///- The distance of each node from the root in the %DFS tree.
583 ///\note d.run(s) is just a shortcut of the following code.
595 ///Finds the %DFS path between \c s and \c t.
597 ///Finds the %DFS path between \c s and \c t.
599 ///\return The length of the %DFS s---t path if there exists one,
601 ///\note Apart from the return value, d.run(s,t) is
602 ///just a shortcut of the following code.
608 int run(Node s,Node t) {
612 return reached(t)?_stack_head+1:0;
617 ///\name Query Functions
618 ///The result of the %DFS algorithm can be obtained using these
620 ///Before the use of these functions,
621 ///either run() or start() must be called.
625 ///Copies the path to \c t on the DFS tree into \c p
627 ///This function copies the path to \c t on the DFS tree into \c p.
628 ///If \c t is a source itself or unreachable, then it does not
631 ///\return Returns \c true if a path to \c t was actually copied to \c p,
632 ///\c false otherwise.
635 bool getPath(P &p,Node t)
639 typename P::Builder b(p);
640 for(b.setStartNode(t);predEdge(t)!=INVALID;t=predNode(t))
641 b.pushFront(predEdge(t));
648 ///The distance of a node from the root(s).
650 ///Returns the distance of a node from the root(s).
651 ///\pre \ref run() must be called before using this function.
652 ///\warning If node \c v is unreachable from the root(s) then the return value
653 ///of this funcion is undefined.
654 int dist(Node v) const { return (*_dist)[v]; }
656 ///Returns the 'previous edge' of the %DFS tree.
658 ///For a node \c v it returns the 'previous edge'
660 ///i.e. it returns the last edge of a %DFS path from the root(s) to \c
661 ///v. It is \ref INVALID
662 ///if \c v is unreachable from the root(s) or \c v is a root. The
663 ///%DFS tree used here is equal to the %DFS tree used in
665 ///\pre Either \ref run() or \ref start() must be called before using
667 Edge predEdge(Node v) const { return (*_pred)[v];}
669 ///Returns the 'previous node' of the %DFS tree.
671 ///For a node \c v it returns the 'previous node'
673 ///i.e. it returns the last but one node from a %DFS path from the
675 ///It is INVALID if \c v is unreachable from the root(s) or
676 ///if \c v itself a root.
677 ///The %DFS tree used here is equal to the %DFS
678 ///tree used in \ref predEdge().
679 ///\pre Either \ref run() or \ref start() must be called before
680 ///using this function.
681 Node predNode(Node v) const { return (*_pred)[v]==INVALID ? INVALID:
682 G->source((*_pred)[v]); }
684 ///Returns a reference to the NodeMap of distances.
686 ///Returns a reference to the NodeMap of distances.
687 ///\pre Either \ref run() or \ref init() must
688 ///be called before using this function.
689 const DistMap &distMap() const { return *_dist;}
691 ///Returns a reference to the %DFS edge-tree map.
693 ///Returns a reference to the NodeMap of the edges of the
695 ///\pre Either \ref run() or \ref init()
696 ///must be called before using this function.
697 const PredMap &predMap() const { return *_pred;}
699 ///Checks if a node is reachable from the root.
701 ///Returns \c true if \c v is reachable from the root(s).
702 ///\warning The source nodes are inditated as unreachable.
703 ///\pre Either \ref run() or \ref start()
704 ///must be called before using this function.
706 bool reached(Node v) { return (*_reached)[v]; }
711 ///Default traits class of Dfs function.
713 ///Default traits class of Dfs function.
714 ///\param GR Graph type.
716 struct DfsWizardDefaultTraits
718 ///The graph type the algorithm runs on.
720 ///\brief The type of the map that stores the last
721 ///edges of the %DFS paths.
723 ///The type of the map that stores the last
724 ///edges of the %DFS paths.
725 ///It must meet the \ref concept::WriteMap "WriteMap" concept.
727 typedef NullMap<typename Graph::Node,typename GR::Edge> PredMap;
728 ///Instantiates a PredMap.
730 ///This function instantiates a \ref PredMap.
731 ///\param g is the graph, to which we would like to define the PredMap.
732 ///\todo The graph alone may be insufficient to initialize
734 static PredMap *createPredMap(const GR &g)
736 static PredMap *createPredMap(const GR &)
739 return new PredMap();
742 ///The type of the map that indicates which nodes are processed.
744 ///The type of the map that indicates which nodes are processed.
745 ///It must meet the \ref concept::WriteMap "WriteMap" concept.
746 ///\todo named parameter to set this type, function to read and write.
747 typedef NullMap<typename Graph::Node,bool> ProcessedMap;
748 ///Instantiates a ProcessedMap.
750 ///This function instantiates a \ref ProcessedMap.
751 ///\param g is the graph, to which
752 ///we would like to define the \ref ProcessedMap
754 static ProcessedMap *createProcessedMap(const GR &g)
756 static ProcessedMap *createProcessedMap(const GR &)
759 return new ProcessedMap();
761 ///The type of the map that indicates which nodes are reached.
763 ///The type of the map that indicates which nodes are reached.
764 ///It must meet the \ref concept::WriteMap "WriteMap" concept.
765 ///\todo named parameter to set this type, function to read and write.
766 typedef typename Graph::template NodeMap<bool> ReachedMap;
767 ///Instantiates a ReachedMap.
769 ///This function instantiates a \ref ReachedMap.
770 ///\param G is the graph, to which
771 ///we would like to define the \ref ReachedMap.
772 static ReachedMap *createReachedMap(const GR &G)
774 return new ReachedMap(G);
776 ///The type of the map that stores the dists of the nodes.
778 ///The type of the map that stores the dists of the nodes.
779 ///It must meet the \ref concept::WriteMap "WriteMap" concept.
781 typedef NullMap<typename Graph::Node,int> DistMap;
782 ///Instantiates a DistMap.
784 ///This function instantiates a \ref DistMap.
785 ///\param g is the graph, to which we would like to define the \ref DistMap
787 static DistMap *createDistMap(const GR &g)
789 static DistMap *createDistMap(const GR &)
792 return new DistMap();
796 /// Default traits used by \ref DfsWizard
798 /// To make it easier to use Dfs algorithm
799 ///we have created a wizard class.
800 /// This \ref DfsWizard class needs default traits,
801 ///as well as the \ref Dfs class.
802 /// The \ref DfsWizardBase is a class to be the default traits of the
803 /// \ref DfsWizard class.
805 class DfsWizardBase : public DfsWizardDefaultTraits<GR>
808 typedef DfsWizardDefaultTraits<GR> Base;
810 /// Type of the nodes in the graph.
811 typedef typename Base::Graph::Node Node;
813 /// Pointer to the underlying graph.
815 ///Pointer to the map of reached nodes.
817 ///Pointer to the map of processed nodes.
819 ///Pointer to the map of predecessors edges.
821 ///Pointer to the map of distances.
823 ///Pointer to the source node.
829 /// This constructor does not require parameters, therefore it initiates
830 /// all of the attributes to default values (0, INVALID).
831 DfsWizardBase() : _g(0), _reached(0), _processed(0), _pred(0),
832 _dist(0), _source(INVALID) {}
836 /// This constructor requires some parameters,
837 /// listed in the parameters list.
838 /// Others are initiated to 0.
839 /// \param g is the initial value of \ref _g
840 /// \param s is the initial value of \ref _source
841 DfsWizardBase(const GR &g, Node s=INVALID) :
842 _g((void *)&g), _reached(0), _processed(0), _pred(0),
843 _dist(0), _source(s) {}
847 /// A class to make the usage of the Dfs algorithm easier
849 /// This class is created to make it easier to use the Dfs algorithm.
850 /// It uses the functions and features of the plain \ref Dfs,
851 /// but it is much simpler to use it.
853 /// Simplicity means that the way to change the types defined
854 /// in the traits class is based on functions that returns the new class
855 /// and not on templatable built-in classes.
856 /// When using the plain \ref Dfs
857 /// the new class with the modified type comes from
858 /// the original class by using the ::
859 /// operator. In the case of \ref DfsWizard only
860 /// a function have to be called and it will
861 /// return the needed class.
863 /// It does not have own \ref run method. When its \ref run method is called
864 /// it initiates a plain \ref Dfs object, and calls the \ref Dfs::run
867 class DfsWizard : public TR
871 ///The type of the underlying graph.
872 typedef typename TR::Graph Graph;
874 typedef typename Graph::Node Node;
876 typedef typename Graph::NodeIt NodeIt;
878 typedef typename Graph::Edge Edge;
880 typedef typename Graph::OutEdgeIt OutEdgeIt;
882 ///\brief The type of the map that stores
884 typedef typename TR::ReachedMap ReachedMap;
885 ///\brief The type of the map that stores
886 ///the processed nodes
887 typedef typename TR::ProcessedMap ProcessedMap;
888 ///\brief The type of the map that stores the last
889 ///edges of the %DFS paths.
890 typedef typename TR::PredMap PredMap;
891 ///The type of the map that stores the distances of the nodes.
892 typedef typename TR::DistMap DistMap;
896 DfsWizard() : TR() {}
898 /// Constructor that requires parameters.
900 /// Constructor that requires parameters.
901 /// These parameters will be the default values for the traits class.
902 DfsWizard(const Graph &g, Node s=INVALID) :
906 DfsWizard(const TR &b) : TR(b) {}
910 ///Runs Dfs algorithm from a given node.
912 ///Runs Dfs algorithm from a given node.
913 ///The node can be given by the \ref source function.
916 if(Base::_source==INVALID) throw UninitializedParameter();
917 Dfs<Graph,TR> alg(*(Graph*)Base::_g);
918 if(Base::_reached) alg.reachedMap(*(ReachedMap*)Base::_reached);
919 if(Base::_processed) alg.processedMap(*(ProcessedMap*)Base::_processed);
920 if(Base::_pred) alg.predMap(*(PredMap*)Base::_pred);
921 if(Base::_dist) alg.distMap(*(DistMap*)Base::_dist);
922 alg.run(Base::_source);
925 ///Runs Dfs algorithm from the given node.
927 ///Runs Dfs algorithm from the given node.
928 ///\param s is the given source.
936 struct DefPredMapBase : public Base {
938 static PredMap *createPredMap(const Graph &) { return 0; };
939 DefPredMapBase(const TR &b) : TR(b) {}
942 ///\brief \ref named-templ-param "Named parameter"
943 ///function for setting PredMap type
945 /// \ref named-templ-param "Named parameter"
946 ///function for setting PredMap type
949 DfsWizard<DefPredMapBase<T> > predMap(const T &t)
951 Base::_pred=(void *)&t;
952 return DfsWizard<DefPredMapBase<T> >(*this);
957 struct DefReachedMapBase : public Base {
958 typedef T ReachedMap;
959 static ReachedMap *createReachedMap(const Graph &) { return 0; };
960 DefReachedMapBase(const TR &b) : TR(b) {}
963 ///\brief \ref named-templ-param "Named parameter"
964 ///function for setting ReachedMap
966 /// \ref named-templ-param "Named parameter"
967 ///function for setting ReachedMap
970 DfsWizard<DefReachedMapBase<T> > reachedMap(const T &t)
972 Base::_pred=(void *)&t;
973 return DfsWizard<DefReachedMapBase<T> >(*this);
978 struct DefProcessedMapBase : public Base {
979 typedef T ProcessedMap;
980 static ProcessedMap *createProcessedMap(const Graph &) { return 0; };
981 DefProcessedMapBase(const TR &b) : TR(b) {}
984 ///\brief \ref named-templ-param "Named parameter"
985 ///function for setting ProcessedMap
987 /// \ref named-templ-param "Named parameter"
988 ///function for setting ProcessedMap
991 DfsWizard<DefProcessedMapBase<T> > processedMap(const T &t)
993 Base::_pred=(void *)&t;
994 return DfsWizard<DefProcessedMapBase<T> >(*this);
998 struct DefDistMapBase : public Base {
1000 static DistMap *createDistMap(const Graph &) { return 0; };
1001 DefDistMapBase(const TR &b) : TR(b) {}
1004 ///\brief \ref named-templ-param "Named parameter"
1005 ///function for setting DistMap type
1007 /// \ref named-templ-param "Named parameter"
1008 ///function for setting DistMap type
1011 DfsWizard<DefDistMapBase<T> > distMap(const T &t)
1013 Base::_dist=(void *)&t;
1014 return DfsWizard<DefDistMapBase<T> >(*this);
1017 /// Sets the source node, from which the Dfs algorithm runs.
1019 /// Sets the source node, from which the Dfs algorithm runs.
1020 /// \param s is the source node.
1021 DfsWizard<TR> &source(Node s)
1029 ///Function type interface for Dfs algorithm.
1031 /// \ingroup flowalgs
1032 ///Function type interface for Dfs algorithm.
1034 ///This function also has several
1035 ///\ref named-templ-func-param "named parameters",
1036 ///they are declared as the members of class \ref DfsWizard.
1038 ///example shows how to use these parameters.
1040 /// dfs(g,source).predMap(preds).run();
1042 ///\warning Don't forget to put the \ref DfsWizard::run() "run()"
1043 ///to the end of the parameter list.
1047 DfsWizard<DfsWizardBase<GR> >
1048 dfs(const GR &g,typename GR::Node s=INVALID)
1050 return DfsWizard<DfsWizardBase<GR> >(g,s);
1054 /// \brief Visitor class for dfs.
1056 /// It gives a simple interface for a functional interface for dfs
1057 /// traversal. The traversal on a linear data structure.
1058 template <typename _Graph>
1060 typedef _Graph Graph;
1061 typedef typename Graph::Edge Edge;
1062 typedef typename Graph::Node Node;
1063 /// \brief Called when the edge reach a node.
1065 /// It is called when the dfs find an edge which target is not
1067 void discover(const Edge& edge) {}
1068 /// \brief Called when the node reached first time.
1070 /// It is Called when the node reached first time.
1071 void reach(const Node& node) {}
1072 /// \brief Called when we step back on an edge.
1074 /// It is called when the dfs should step back on the edge.
1075 void backtrack(const Edge& edge) {}
1076 /// \brief Called when we step back from the node.
1078 /// It is called when we step back from the node.
1079 void leave(const Node& node) {}
1080 /// \brief Called when the edge examined but target of the edge
1081 /// already discovered.
1083 /// It called when the edge examined but the target of the edge
1084 /// already discovered.
1085 void examine(const Edge& edge) {}
1086 /// \brief Called for the source node of the dfs.
1088 /// It is called for the source node of the dfs.
1089 void start(const Node& node) {}
1090 /// \brief Called when we leave the source node of the dfs.
1092 /// It is called when we leave the source node of the dfs.
1093 void stop(const Node& node) {}
1097 template <typename _Graph>
1099 typedef _Graph Graph;
1100 typedef typename Graph::Edge Edge;
1101 typedef typename Graph::Node Node;
1102 void discover(const Edge&) {}
1103 void reach(const Node&) {}
1104 void backtrack(const Edge&) {}
1105 void leave(const Node&) {}
1106 void examine(const Edge&) {}
1107 void start(const Node&) {}
1108 void stop(const Node&) {}
1110 template <typename _Visitor>
1111 struct Constraints {
1112 void constraints() {
1115 visitor.discover(edge);
1116 visitor.reach(node);
1117 visitor.backtrack(edge);
1118 visitor.leave(node);
1119 visitor.examine(edge);
1120 visitor.start(node);
1128 /// \brief Default traits class of DfsVisit class.
1130 /// Default traits class of DfsVisit class.
1131 /// \param _Graph Graph type.
1132 template<class _Graph>
1133 struct DfsVisitDefaultTraits {
1135 /// \brief The graph type the algorithm runs on.
1136 typedef _Graph Graph;
1138 /// \brief The type of the map that indicates which nodes are reached.
1140 /// The type of the map that indicates which nodes are reached.
1141 /// It must meet the \ref concept::WriteMap "WriteMap" concept.
1142 /// \todo named parameter to set this type, function to read and write.
1143 typedef typename Graph::template NodeMap<bool> ReachedMap;
1145 /// \brief Instantiates a ReachedMap.
1147 /// This function instantiates a \ref ReachedMap.
1148 /// \param graph is the graph, to which
1149 /// we would like to define the \ref ReachedMap.
1150 static ReachedMap *createReachedMap(const Graph &graph) {
1151 return new ReachedMap(graph);
1156 /// %DFS Visit algorithm class.
1158 /// \ingroup flowalgs
1159 /// This class provides an efficient implementation of the %DFS algorithm
1160 /// with visitor interface.
1162 /// The %DfsVisit class provides an alternative interface to the Dfs
1163 /// class. It works with callback mechanism, the DfsVisit object calls
1164 /// on every dfs event the \c Visitor class member functions.
1166 /// \param _Graph The graph type the algorithm runs on. The default value is
1167 /// \ref ListGraph. The value of _Graph is not used directly by Dfs, it
1168 /// is only passed to \ref DfsDefaultTraits.
1169 /// \param _Visitor The Visitor object for the algorithm. The
1170 /// \ref DfsVisitor "DfsVisitor<_Graph>" is an empty Visitor which
1171 /// does not observe the Dfs events. If you want to observe the dfs
1172 /// events you should implement your own Visitor class.
1173 /// \param _Traits Traits class to set various data types used by the
1174 /// algorithm. The default traits class is
1175 /// \ref DfsVisitDefaultTraits "DfsVisitDefaultTraits<_Graph>".
1176 /// See \ref DfsVisitDefaultTraits for the documentation of
1177 /// a Dfs visit traits class.
1179 /// \author Jacint Szabo, Alpar Juttner and Balazs Dezso
1181 template <typename _Graph, typename _Visitor, typename _Traits>
1183 template <typename _Graph = ListGraph,
1184 typename _Visitor = DfsVisitor<_Graph>,
1185 typename _Traits = DfsDefaultTraits<_Graph> >
1190 /// \brief \ref Exception for uninitialized parameters.
1192 /// This error represents problems in the initialization
1193 /// of the parameters of the algorithms.
1194 class UninitializedParameter : public lemon::UninitializedParameter {
1196 virtual const char* exceptionName() const {
1197 return "lemon::DfsVisit::UninitializedParameter";
1201 typedef _Traits Traits;
1203 typedef typename Traits::Graph Graph;
1205 typedef _Visitor Visitor;
1207 ///The type of the map indicating which nodes are reached.
1208 typedef typename Traits::ReachedMap ReachedMap;
1212 typedef typename Graph::Node Node;
1213 typedef typename Graph::NodeIt NodeIt;
1214 typedef typename Graph::Edge Edge;
1215 typedef typename Graph::OutEdgeIt OutEdgeIt;
1217 /// Pointer to the underlying graph.
1218 const Graph *_graph;
1219 /// Pointer to the visitor object.
1221 ///Pointer to the map of reached status of the nodes.
1222 ReachedMap *_reached;
1223 ///Indicates if \ref _reached is locally allocated (\c true) or not.
1226 std::vector<typename Graph::Edge> _stack;
1229 /// \brief Creates the maps if necessary.
1231 /// Creates the maps if necessary.
1232 void create_maps() {
1234 local_reached = true;
1235 _reached = Traits::createReachedMap(*_graph);
1245 typedef DfsVisit Create;
1247 /// \name Named template parameters
1251 struct DefReachedMapTraits : public Traits {
1252 typedef T ReachedMap;
1253 static ReachedMap *createReachedMap(const Graph &graph) {
1254 throw UninitializedParameter();
1257 /// \brief \ref named-templ-param "Named parameter" for setting
1260 /// \ref named-templ-param "Named parameter" for setting ReachedMap type
1262 struct DefReachedMap : public DfsVisit< Graph, Visitor,
1263 DefReachedMapTraits<T> > {
1264 typedef DfsVisit< Graph, Visitor, DefReachedMapTraits<T> > Create;
1270 /// \brief Constructor.
1274 /// \param graph the graph the algorithm will run on.
1275 /// \param visitor The visitor of the algorithm.
1277 DfsVisit(const Graph& graph, Visitor& visitor)
1278 : _graph(&graph), _visitor(&visitor),
1279 _reached(0), local_reached(false) {}
1281 /// \brief Destructor.
1285 if(local_reached) delete _reached;
1288 /// \brief Sets the map indicating if a node is reached.
1290 /// Sets the map indicating if a node is reached.
1291 /// If you don't use this function before calling \ref run(),
1292 /// it will allocate one. The destuctor deallocates this
1293 /// automatically allocated map, of course.
1294 /// \return <tt> (*this) </tt>
1295 DfsVisit &reachedMap(ReachedMap &m) {
1298 local_reached=false;
1305 /// \name Execution control
1306 /// The simplest way to execute the algorithm is to use
1307 /// one of the member functions called \c run(...).
1309 /// If you need more control on the execution,
1310 /// first you must call \ref init(), then you can adda source node
1311 /// with \ref addSource().
1312 /// Finally \ref start() will perform the actual path
1316 /// \brief Initializes the internal data structures.
1318 /// Initializes the internal data structures.
1322 _stack.resize(countNodes(*_graph));
1324 for (NodeIt u(*_graph) ; u != INVALID ; ++u) {
1325 _reached->set(u, false);
1329 /// \brief Adds a new source node.
1331 /// Adds a new source node to the set of nodes to be processed.
1332 void addSource(Node s) {
1333 if(!(*_reached)[s]) {
1334 _reached->set(s,true);
1338 _graph->firstOut(e, s);
1340 _stack[++_stack_head] = e;
1347 /// \brief Processes the next edge.
1349 /// Processes the next edge.
1351 /// \return The processed edge.
1353 /// \pre The stack must not be empty!
1354 Edge processNextEdge() {
1355 Edge e = _stack[_stack_head];
1356 Node m = _graph->target(e);
1357 if(!(*_reached)[m]) {
1358 _visitor->discover(e);
1360 _reached->set(m, true);
1361 _graph->firstOut(_stack[++_stack_head], m);
1363 _visitor->examine(e);
1364 m = _graph->source(e);
1365 _graph->nextOut(_stack[_stack_head]);
1367 while (_stack_head>=0 && _stack[_stack_head] == INVALID) {
1370 if (_stack_head >= 0) {
1371 _visitor->backtrack(_stack[_stack_head]);
1372 m = _graph->source(_stack[_stack_head]);
1373 _graph->nextOut(_stack[_stack_head]);
1381 /// \brief Next edge to be processed.
1383 /// Next edge to be processed.
1385 /// \return The next edge to be processed or INVALID if the stack is
1388 return _stack_head >= 0 ? _stack[_stack_head] : INVALID;
1391 /// \brief Returns \c false if there are nodes
1392 /// to be processed in the queue
1394 /// Returns \c false if there are nodes
1395 /// to be processed in the queue
1396 bool emptyQueue() { return _stack_head < 0; }
1398 /// \brief Returns the number of the nodes to be processed.
1400 /// Returns the number of the nodes to be processed in the queue.
1401 int queueSize() { return _stack_head + 1; }
1403 /// \brief Executes the algorithm.
1405 /// Executes the algorithm.
1407 /// \pre init() must be called and at least one node should be added
1408 /// with addSource() before using this function.
1410 while ( !emptyQueue() ) processNextEdge();
1413 /// \brief Executes the algorithm until \c dest is reached.
1415 /// Executes the algorithm until \c dest is reached.
1417 /// \pre init() must be called and at least one node should be added
1418 /// with addSource() before using this function.
1419 void start(Node dest) {
1420 while ( !emptyQueue() && _graph->target(_stack[_stack_head]) != dest)
1424 /// \brief Executes the algorithm until a condition is met.
1426 /// Executes the algorithm until a condition is met.
1428 /// \pre init() must be called and at least one node should be added
1429 /// with addSource() before using this function.
1431 /// \param em must be a bool (or convertible) edge map. The algorithm
1432 /// will stop when it reaches an edge \c e with \code nm[e]==true \endcode.
1434 /// \warning Contrary to \ref Dfs and \ref Dijkstra, \c em is an edge map,
1436 template <typename EM>
1437 void start(const EM &em) {
1438 while (!emptyQueue() && !em[_stack[_stack_head]]) processNextEdge();
1441 /// \brief Runs %DFS algorithm from node \c s.
1443 /// This method runs the %DFS algorithm from a root node \c s.
1444 /// \note d.run(s) is just a shortcut of the following code.
1457 /// \name Query Functions
1458 /// The result of the %DFS algorithm can be obtained using these
1460 /// Before the use of these functions,
1461 /// either run() or start() must be called.
1463 /// \brief Checks if a node is reachable from the root.
1465 /// Returns \c true if \c v is reachable from the root(s).
1466 /// \warning The source nodes are inditated as unreachable.
1467 /// \pre Either \ref run() or \ref start()
1468 /// must be called before using this function.
1470 bool reached(Node v) { return (*_reached)[v]; }
1475 } //END OF NAMESPACE LEMON