lemon/dfs.h
author Peter Kovacs <kpeter@inf.elte.hu>
Tue, 08 Apr 2008 22:51:26 +0200
changeset 123 8899d1891a3c
child 157 2ccc1afc2c52
permissions -rw-r--r--
Small improvements in maps.h
- Add a new version of constMap() function.
- Fix in FunctorToMap class.
     1 /* -*- C++ -*-
     2  *
     3  * This file is a part of LEMON, a generic C++ optimization library
     4  *
     5  * Copyright (C) 2003-2008
     6  * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
     7  * (Egervary Research Group on Combinatorial Optimization, EGRES).
     8  *
     9  * Permission to use, modify and distribute this software is granted
    10  * provided that this copyright notice appears in all copies. For
    11  * precise terms see the accompanying LICENSE file.
    12  *
    13  * This software is provided "AS IS" with no warranty of any kind,
    14  * express or implied, and with no claim as to its suitability for any
    15  * purpose.
    16  *
    17  */
    18 
    19 #ifndef LEMON_DFS_H
    20 #define LEMON_DFS_H
    21 
    22 ///\ingroup search
    23 ///\file
    24 ///\brief Dfs algorithm.
    25 
    26 #include <lemon/list_graph.h>
    27 #include <lemon/graph_utils.h>
    28 #include <lemon/bits/path_dump.h>
    29 #include <lemon/bits/invalid.h>
    30 #include <lemon/error.h>
    31 #include <lemon/maps.h>
    32 
    33 #include <lemon/concept_check.h>
    34 
    35 namespace lemon {
    36 
    37   
    38   ///Default traits class of Dfs class.
    39 
    40   ///Default traits class of Dfs class.
    41   ///\param GR Digraph type.
    42   template<class GR>
    43   struct DfsDefaultTraits
    44   {
    45     ///The digraph type the algorithm runs on. 
    46     typedef GR Digraph;
    47     ///\brief The type of the map that stores the last
    48     ///arcs of the %DFS paths.
    49     /// 
    50     ///The type of the map that stores the last
    51     ///arcs of the %DFS paths.
    52     ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
    53     ///
    54     typedef typename Digraph::template NodeMap<typename GR::Arc> PredMap;
    55     ///Instantiates a PredMap.
    56  
    57     ///This function instantiates a \ref PredMap. 
    58     ///\param G is the digraph, to which we would like to define the PredMap.
    59     ///\todo The digraph alone may be insufficient to initialize
    60     static PredMap *createPredMap(const GR &G) 
    61     {
    62       return new PredMap(G);
    63     }
    64 
    65     ///The type of the map that indicates which nodes are processed.
    66  
    67     ///The type of the map that indicates which nodes are processed.
    68     ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
    69     ///\todo named parameter to set this type, function to read and write.
    70     typedef NullMap<typename Digraph::Node,bool> ProcessedMap;
    71     ///Instantiates a ProcessedMap.
    72  
    73     ///This function instantiates a \ref ProcessedMap. 
    74     ///\param g is the digraph, to which
    75     ///we would like to define the \ref ProcessedMap
    76 #ifdef DOXYGEN
    77     static ProcessedMap *createProcessedMap(const GR &g)
    78 #else
    79     static ProcessedMap *createProcessedMap(const GR &)
    80 #endif
    81     {
    82       return new ProcessedMap();
    83     }
    84     ///The type of the map that indicates which nodes are reached.
    85  
    86     ///The type of the map that indicates which nodes are reached.
    87     ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
    88     ///\todo named parameter to set this type, function to read and write.
    89     typedef typename Digraph::template NodeMap<bool> ReachedMap;
    90     ///Instantiates a ReachedMap.
    91  
    92     ///This function instantiates a \ref ReachedMap. 
    93     ///\param G is the digraph, to which
    94     ///we would like to define the \ref ReachedMap.
    95     static ReachedMap *createReachedMap(const GR &G)
    96     {
    97       return new ReachedMap(G);
    98     }
    99     ///The type of the map that stores the dists of the nodes.
   100  
   101     ///The type of the map that stores the dists of the nodes.
   102     ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
   103     ///
   104     typedef typename Digraph::template NodeMap<int> DistMap;
   105     ///Instantiates a DistMap.
   106  
   107     ///This function instantiates a \ref DistMap. 
   108     ///\param G is the digraph, to which we would like to define the \ref DistMap
   109     static DistMap *createDistMap(const GR &G)
   110     {
   111       return new DistMap(G);
   112     }
   113   };
   114   
   115   ///%DFS algorithm class.
   116   
   117   ///\ingroup search
   118   ///This class provides an efficient implementation of the %DFS algorithm.
   119   ///
   120   ///\param GR The digraph type the algorithm runs on. The default value is
   121   ///\ref ListDigraph. The value of GR is not used directly by Dfs, it
   122   ///is only passed to \ref DfsDefaultTraits.
   123   ///\param TR Traits class to set various data types used by the algorithm.
   124   ///The default traits class is
   125   ///\ref DfsDefaultTraits "DfsDefaultTraits<GR>".
   126   ///See \ref DfsDefaultTraits for the documentation of
   127   ///a Dfs traits class.
   128   ///
   129   ///\author Jacint Szabo and Alpar Juttner
   130 #ifdef DOXYGEN
   131   template <typename GR,
   132 	    typename TR>
   133 #else
   134   template <typename GR=ListDigraph,
   135 	    typename TR=DfsDefaultTraits<GR> >
   136 #endif
   137   class Dfs {
   138   public:
   139     /**
   140      * \brief \ref Exception for uninitialized parameters.
   141      *
   142      * This error represents problems in the initialization
   143      * of the parameters of the algorithms.
   144      */
   145     class UninitializedParameter : public lemon::UninitializedParameter {
   146     public:
   147       virtual const char* what() const throw() {
   148 	return "lemon::Dfs::UninitializedParameter";
   149       }
   150     };
   151 
   152     typedef TR Traits;
   153     ///The type of the underlying digraph.
   154     typedef typename TR::Digraph Digraph;
   155     ///\e
   156     typedef typename Digraph::Node Node;
   157     ///\e
   158     typedef typename Digraph::NodeIt NodeIt;
   159     ///\e
   160     typedef typename Digraph::Arc Arc;
   161     ///\e
   162     typedef typename Digraph::OutArcIt OutArcIt;
   163     
   164     ///\brief The type of the map that stores the last
   165     ///arcs of the %DFS paths.
   166     typedef typename TR::PredMap PredMap;
   167     ///The type of the map indicating which nodes are reached.
   168     typedef typename TR::ReachedMap ReachedMap;
   169     ///The type of the map indicating which nodes are processed.
   170     typedef typename TR::ProcessedMap ProcessedMap;
   171     ///The type of the map that stores the dists of the nodes.
   172     typedef typename TR::DistMap DistMap;
   173   private:
   174     /// Pointer to the underlying digraph.
   175     const Digraph *G;
   176     ///Pointer to the map of predecessors arcs.
   177     PredMap *_pred;
   178     ///Indicates if \ref _pred is locally allocated (\c true) or not.
   179     bool local_pred;
   180     ///Pointer to the map of distances.
   181     DistMap *_dist;
   182     ///Indicates if \ref _dist is locally allocated (\c true) or not.
   183     bool local_dist;
   184     ///Pointer to the map of reached status of the nodes.
   185     ReachedMap *_reached;
   186     ///Indicates if \ref _reached is locally allocated (\c true) or not.
   187     bool local_reached;
   188     ///Pointer to the map of processed status of the nodes.
   189     ProcessedMap *_processed;
   190     ///Indicates if \ref _processed is locally allocated (\c true) or not.
   191     bool local_processed;
   192 
   193     std::vector<typename Digraph::OutArcIt> _stack;
   194     int _stack_head;
   195 
   196     ///Creates the maps if necessary.
   197     
   198     ///\todo Better memory allocation (instead of new).
   199     void create_maps() 
   200     {
   201       if(!_pred) {
   202 	local_pred = true;
   203 	_pred = Traits::createPredMap(*G);
   204       }
   205       if(!_dist) {
   206 	local_dist = true;
   207 	_dist = Traits::createDistMap(*G);
   208       }
   209       if(!_reached) {
   210 	local_reached = true;
   211 	_reached = Traits::createReachedMap(*G);
   212       }
   213       if(!_processed) {
   214 	local_processed = true;
   215 	_processed = Traits::createProcessedMap(*G);
   216       }
   217     }
   218 
   219   protected:
   220 
   221     Dfs() {}
   222     
   223   public:
   224 
   225     typedef Dfs Create;
   226 
   227     ///\name Named template parameters
   228 
   229     ///@{
   230 
   231     template <class T>
   232     struct DefPredMapTraits : public Traits {
   233       typedef T PredMap;
   234       static PredMap *createPredMap(const Digraph &G) 
   235       {
   236 	throw UninitializedParameter();
   237       }
   238     };
   239     ///\brief \ref named-templ-param "Named parameter" for setting
   240     ///PredMap type
   241     ///
   242     ///\ref named-templ-param "Named parameter" for setting PredMap type
   243     ///
   244     template <class T>
   245     struct DefPredMap : public Dfs<Digraph, DefPredMapTraits<T> > {
   246       typedef Dfs<Digraph, DefPredMapTraits<T> > Create;
   247     };
   248     
   249     
   250     template <class T>
   251     struct DefDistMapTraits : public Traits {
   252       typedef T DistMap;
   253       static DistMap *createDistMap(const Digraph &) 
   254       {
   255 	throw UninitializedParameter();
   256       }
   257     };
   258     ///\brief \ref named-templ-param "Named parameter" for setting
   259     ///DistMap type
   260     ///
   261     ///\ref named-templ-param "Named parameter" for setting DistMap
   262     ///type
   263     template <class T>
   264     struct DefDistMap {
   265       typedef Dfs<Digraph, DefDistMapTraits<T> > Create;
   266     };
   267     
   268     template <class T>
   269     struct DefReachedMapTraits : public Traits {
   270       typedef T ReachedMap;
   271       static ReachedMap *createReachedMap(const Digraph &) 
   272       {
   273 	throw UninitializedParameter();
   274       }
   275     };
   276     ///\brief \ref named-templ-param "Named parameter" for setting
   277     ///ReachedMap type
   278     ///
   279     ///\ref named-templ-param "Named parameter" for setting ReachedMap type
   280     ///
   281     template <class T>
   282     struct DefReachedMap : public Dfs< Digraph, DefReachedMapTraits<T> > {
   283       typedef Dfs< Digraph, DefReachedMapTraits<T> > Create;
   284     };
   285 
   286     template <class T>
   287     struct DefProcessedMapTraits : public Traits {
   288       typedef T ProcessedMap;
   289       static ProcessedMap *createProcessedMap(const Digraph &) 
   290       {
   291 	throw UninitializedParameter();
   292       }
   293     };
   294     ///\brief \ref named-templ-param "Named parameter" for setting
   295     ///ProcessedMap type
   296     ///
   297     ///\ref named-templ-param "Named parameter" for setting ProcessedMap type
   298     ///
   299     template <class T>
   300     struct DefProcessedMap : public Dfs< Digraph, DefProcessedMapTraits<T> > { 
   301       typedef Dfs< Digraph, DefProcessedMapTraits<T> > Create;
   302     };
   303     
   304     struct DefDigraphProcessedMapTraits : public Traits {
   305       typedef typename Digraph::template NodeMap<bool> ProcessedMap;
   306       static ProcessedMap *createProcessedMap(const Digraph &G) 
   307       {
   308 	return new ProcessedMap(G);
   309       }
   310     };
   311     ///\brief \ref named-templ-param "Named parameter"
   312     ///for setting the ProcessedMap type to be Digraph::NodeMap<bool>.
   313     ///
   314     ///\ref named-templ-param "Named parameter"
   315     ///for setting the ProcessedMap type to be Digraph::NodeMap<bool>.
   316     ///If you don't set it explicitely, it will be automatically allocated.
   317     template <class T>
   318     class DefProcessedMapToBeDefaultMap :
   319       public Dfs< Digraph, DefDigraphProcessedMapTraits> { 
   320       typedef Dfs< Digraph, DefDigraphProcessedMapTraits> Create;
   321     };
   322     
   323     ///@}
   324 
   325   public:      
   326     
   327     ///Constructor.
   328     
   329     ///\param _G the digraph the algorithm will run on.
   330     ///
   331     Dfs(const Digraph& _G) :
   332       G(&_G),
   333       _pred(NULL), local_pred(false),
   334       _dist(NULL), local_dist(false),
   335       _reached(NULL), local_reached(false),
   336       _processed(NULL), local_processed(false)
   337     { }
   338     
   339     ///Destructor.
   340     ~Dfs() 
   341     {
   342       if(local_pred) delete _pred;
   343       if(local_dist) delete _dist;
   344       if(local_reached) delete _reached;
   345       if(local_processed) delete _processed;
   346     }
   347 
   348     ///Sets the map storing the predecessor arcs.
   349 
   350     ///Sets the map storing the predecessor arcs.
   351     ///If you don't use this function before calling \ref run(),
   352     ///it will allocate one. The destuctor deallocates this
   353     ///automatically allocated map, of course.
   354     ///\return <tt> (*this) </tt>
   355     Dfs &predMap(PredMap &m) 
   356     {
   357       if(local_pred) {
   358 	delete _pred;
   359 	local_pred=false;
   360       }
   361       _pred = &m;
   362       return *this;
   363     }
   364 
   365     ///Sets the map storing the distances calculated by the algorithm.
   366 
   367     ///Sets the map storing the distances calculated by the algorithm.
   368     ///If you don't use this function before calling \ref run(),
   369     ///it will allocate one. The destuctor deallocates this
   370     ///automatically allocated map, of course.
   371     ///\return <tt> (*this) </tt>
   372     Dfs &distMap(DistMap &m) 
   373     {
   374       if(local_dist) {
   375 	delete _dist;
   376 	local_dist=false;
   377       }
   378       _dist = &m;
   379       return *this;
   380     }
   381 
   382     ///Sets the map indicating if a node is reached.
   383 
   384     ///Sets the map indicating if a node is reached.
   385     ///If you don't use this function before calling \ref run(),
   386     ///it will allocate one. The destuctor deallocates this
   387     ///automatically allocated map, of course.
   388     ///\return <tt> (*this) </tt>
   389     Dfs &reachedMap(ReachedMap &m) 
   390     {
   391       if(local_reached) {
   392 	delete _reached;
   393 	local_reached=false;
   394       }
   395       _reached = &m;
   396       return *this;
   397     }
   398 
   399     ///Sets the map indicating if a node is processed.
   400 
   401     ///Sets the map indicating if a node is processed.
   402     ///If you don't use this function before calling \ref run(),
   403     ///it will allocate one. The destuctor deallocates this
   404     ///automatically allocated map, of course.
   405     ///\return <tt> (*this) </tt>
   406     Dfs &processedMap(ProcessedMap &m) 
   407     {
   408       if(local_processed) {
   409 	delete _processed;
   410 	local_processed=false;
   411       }
   412       _processed = &m;
   413       return *this;
   414     }
   415 
   416   public:
   417     ///\name Execution control
   418     ///The simplest way to execute the algorithm is to use
   419     ///one of the member functions called \c run(...).
   420     ///\n
   421     ///If you need more control on the execution,
   422     ///first you must call \ref init(), then you can add a source node
   423     ///with \ref addSource().
   424     ///Finally \ref start() will perform the actual path
   425     ///computation.
   426 
   427     ///@{
   428 
   429     ///Initializes the internal data structures.
   430 
   431     ///Initializes the internal data structures.
   432     ///
   433     void init()
   434     {
   435       create_maps();
   436       _stack.resize(countNodes(*G));
   437       _stack_head=-1;
   438       for ( NodeIt u(*G) ; u!=INVALID ; ++u ) {
   439 	_pred->set(u,INVALID);
   440 	// _predNode->set(u,INVALID);
   441 	_reached->set(u,false);
   442 	_processed->set(u,false);
   443       }
   444     }
   445     
   446     ///Adds a new source node.
   447 
   448     ///Adds a new source node to the set of nodes to be processed.
   449     ///
   450     ///\warning dists are wrong (or at least strange)
   451     ///in case of multiple sources.
   452     void addSource(Node s)
   453     {
   454       if(!(*_reached)[s])
   455 	{
   456 	  _reached->set(s,true);
   457 	  _pred->set(s,INVALID);
   458 	  OutArcIt e(*G,s);
   459 	  if(e!=INVALID) {
   460 	    _stack[++_stack_head]=e;
   461 	    _dist->set(s,_stack_head);
   462 	  }
   463 	  else {
   464 	    _processed->set(s,true);
   465 	    _dist->set(s,0);
   466 	  }
   467 	}
   468     }
   469     
   470     ///Processes the next arc.
   471 
   472     ///Processes the next arc.
   473     ///
   474     ///\return The processed arc.
   475     ///
   476     ///\pre The stack must not be empty!
   477     Arc processNextArc()
   478     { 
   479       Node m;
   480       Arc e=_stack[_stack_head];
   481       if(!(*_reached)[m=G->target(e)]) {
   482 	_pred->set(m,e);
   483 	_reached->set(m,true);
   484 	++_stack_head;
   485 	_stack[_stack_head] = OutArcIt(*G, m);
   486 	_dist->set(m,_stack_head);
   487       }
   488       else {
   489 	m=G->source(e);
   490 	++_stack[_stack_head];
   491       }
   492       while(_stack_head>=0 && _stack[_stack_head]==INVALID) {
   493 	_processed->set(m,true);
   494 	--_stack_head;
   495 	if(_stack_head>=0) {
   496 	  m=G->source(_stack[_stack_head]);
   497 	  ++_stack[_stack_head];
   498 	}
   499       }
   500       return e;
   501     }
   502     ///Next arc to be processed.
   503 
   504     ///Next arc to be processed.
   505     ///
   506     ///\return The next arc to be processed or INVALID if the stack is
   507     /// empty.
   508     OutArcIt nextArc()
   509     { 
   510       return _stack_head>=0?_stack[_stack_head]:INVALID;
   511     }
   512 
   513     ///\brief Returns \c false if there are nodes
   514     ///to be processed in the queue
   515     ///
   516     ///Returns \c false if there are nodes
   517     ///to be processed in the queue
   518     bool emptyQueue() { return _stack_head<0; }
   519     ///Returns the number of the nodes to be processed.
   520     
   521     ///Returns the number of the nodes to be processed in the queue.
   522     int queueSize() { return _stack_head+1; }
   523     
   524     ///Executes the algorithm.
   525 
   526     ///Executes the algorithm.
   527     ///
   528     ///\pre init() must be called and at least one node should be added
   529     ///with addSource() before using this function.
   530     ///
   531     ///This method runs the %DFS algorithm from the root node(s)
   532     ///in order to
   533     ///compute the
   534     ///%DFS path to each node. The algorithm computes
   535     ///- The %DFS tree.
   536     ///- The distance of each node from the root(s) in the %DFS tree.
   537     ///
   538     void start()
   539     {
   540       while ( !emptyQueue() ) processNextArc();
   541     }
   542     
   543     ///Executes the algorithm until \c dest is reached.
   544 
   545     ///Executes the algorithm until \c dest is reached.
   546     ///
   547     ///\pre init() must be called and at least one node should be added
   548     ///with addSource() before using this function.
   549     ///
   550     ///This method runs the %DFS algorithm from the root node(s)
   551     ///in order to
   552     ///compute the
   553     ///%DFS path to \c dest. The algorithm computes
   554     ///- The %DFS path to \c  dest.
   555     ///- The distance of \c dest from the root(s) in the %DFS tree.
   556     ///
   557     void start(Node dest)
   558     {
   559       while ( !emptyQueue() && G->target(_stack[_stack_head])!=dest ) 
   560 	processNextArc();
   561     }
   562     
   563     ///Executes the algorithm until a condition is met.
   564 
   565     ///Executes the algorithm until a condition is met.
   566     ///
   567     ///\pre init() must be called and at least one node should be added
   568     ///with addSource() before using this function.
   569     ///
   570     ///\param em must be a bool (or convertible) arc map. The algorithm
   571     ///will stop when it reaches an arc \c e with <tt>em[e]</tt> true.
   572     ///
   573     ///\return The reached arc \c e with <tt>em[e]</tt> true or
   574     ///\c INVALID if no such arc was found.
   575     ///
   576     ///\warning Contrary to \ref Bfs and \ref Dijkstra, \c em is an arc map,
   577     ///not a node map.
   578     template<class EM>
   579     Arc start(const EM &em)
   580     {
   581       while ( !emptyQueue() && !em[_stack[_stack_head]] )
   582         processNextArc();
   583       return emptyQueue() ? INVALID : _stack[_stack_head];
   584     }
   585 
   586     ///Runs %DFS algorithm to visit all nodes in the digraph.
   587     
   588     ///This method runs the %DFS algorithm in order to
   589     ///compute the
   590     ///%DFS path to each node. The algorithm computes
   591     ///- The %DFS tree.
   592     ///- The distance of each node from the root in the %DFS tree.
   593     ///
   594     ///\note d.run() is just a shortcut of the following code.
   595     ///\code
   596     ///  d.init();
   597     ///  for (NodeIt it(digraph); it != INVALID; ++it) {
   598     ///    if (!d.reached(it)) {
   599     ///      d.addSource(it);
   600     ///      d.start();
   601     ///    }
   602     ///  }
   603     ///\endcode
   604     void run() {
   605       init();
   606       for (NodeIt it(*G); it != INVALID; ++it) {
   607         if (!reached(it)) {
   608           addSource(it);
   609           start();
   610         }
   611       }
   612     }
   613 
   614     ///Runs %DFS algorithm from node \c s.
   615     
   616     ///This method runs the %DFS algorithm from a root node \c s
   617     ///in order to
   618     ///compute the
   619     ///%DFS path to each node. The algorithm computes
   620     ///- The %DFS tree.
   621     ///- The distance of each node from the root in the %DFS tree.
   622     ///
   623     ///\note d.run(s) is just a shortcut of the following code.
   624     ///\code
   625     ///  d.init();
   626     ///  d.addSource(s);
   627     ///  d.start();
   628     ///\endcode
   629     void run(Node s) {
   630       init();
   631       addSource(s);
   632       start();
   633     }
   634     
   635     ///Finds the %DFS path between \c s and \c t.
   636     
   637     ///Finds the %DFS path between \c s and \c t.
   638     ///
   639     ///\return The length of the %DFS s---t path if there exists one,
   640     ///0 otherwise.
   641     ///\note Apart from the return value, d.run(s,t) is
   642     ///just a shortcut of the following code.
   643     ///\code
   644     ///  d.init();
   645     ///  d.addSource(s);
   646     ///  d.start(t);
   647     ///\endcode
   648     int run(Node s,Node t) {
   649       init();
   650       addSource(s);
   651       start(t);
   652       return reached(t)?_stack_head+1:0;
   653     }
   654     
   655     ///@}
   656 
   657     ///\name Query Functions
   658     ///The result of the %DFS algorithm can be obtained using these
   659     ///functions.\n
   660     ///Before the use of these functions,
   661     ///either run() or start() must be called.
   662     
   663     ///@{
   664 
   665     typedef PredMapPath<Digraph, PredMap> Path;
   666 
   667     ///Gives back the shortest path.
   668     
   669     ///Gives back the shortest path.
   670     ///\pre The \c t should be reachable from the source.
   671     Path path(Node t) 
   672     {
   673       return Path(*G, *_pred, t);
   674     }
   675 
   676     ///The distance of a node from the root(s).
   677 
   678     ///Returns the distance of a node from the root(s).
   679     ///\pre \ref run() must be called before using this function.
   680     ///\warning If node \c v is unreachable from the root(s) then the return 
   681     ///value of this funcion is undefined.
   682     int dist(Node v) const { return (*_dist)[v]; }
   683 
   684     ///Returns the 'previous arc' of the %DFS tree.
   685 
   686     ///For a node \c v it returns the 'previous arc'
   687     ///of the %DFS path,
   688     ///i.e. it returns the last arc of a %DFS path from the root(s) to \c
   689     ///v. It is \ref INVALID
   690     ///if \c v is unreachable from the root(s) or \c v is a root. The
   691     ///%DFS tree used here is equal to the %DFS tree used in
   692     ///\ref predNode().
   693     ///\pre Either \ref run() or \ref start() must be called before using
   694     ///this function.
   695     Arc predArc(Node v) const { return (*_pred)[v];}
   696 
   697     ///Returns the 'previous node' of the %DFS tree.
   698 
   699     ///For a node \c v it returns the 'previous node'
   700     ///of the %DFS tree,
   701     ///i.e. it returns the last but one node from a %DFS path from the
   702     ///root(s) to \c v.
   703     ///It is INVALID if \c v is unreachable from the root(s) or
   704     ///if \c v itself a root.
   705     ///The %DFS tree used here is equal to the %DFS
   706     ///tree used in \ref predArc().
   707     ///\pre Either \ref run() or \ref start() must be called before
   708     ///using this function.
   709     Node predNode(Node v) const { return (*_pred)[v]==INVALID ? INVALID:
   710 				  G->source((*_pred)[v]); }
   711     
   712     ///Returns a reference to the NodeMap of distances.
   713 
   714     ///Returns a reference to the NodeMap of distances.
   715     ///\pre Either \ref run() or \ref init() must
   716     ///be called before using this function.
   717     const DistMap &distMap() const { return *_dist;}
   718  
   719     ///Returns a reference to the %DFS arc-tree map.
   720 
   721     ///Returns a reference to the NodeMap of the arcs of the
   722     ///%DFS tree.
   723     ///\pre Either \ref run() or \ref init()
   724     ///must be called before using this function.
   725     const PredMap &predMap() const { return *_pred;}
   726  
   727     ///Checks if a node is reachable from the root.
   728 
   729     ///Returns \c true if \c v is reachable from the root(s).
   730     ///\warning The source nodes are inditated as unreachable.
   731     ///\pre Either \ref run() or \ref start()
   732     ///must be called before using this function.
   733     ///
   734     bool reached(Node v) { return (*_reached)[v]; }
   735     
   736     ///@}
   737   };
   738 
   739   ///Default traits class of Dfs function.
   740 
   741   ///Default traits class of Dfs function.
   742   ///\param GR Digraph type.
   743   template<class GR>
   744   struct DfsWizardDefaultTraits
   745   {
   746     ///The digraph type the algorithm runs on. 
   747     typedef GR Digraph;
   748     ///\brief The type of the map that stores the last
   749     ///arcs of the %DFS paths.
   750     /// 
   751     ///The type of the map that stores the last
   752     ///arcs of the %DFS paths.
   753     ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
   754     ///
   755     typedef NullMap<typename Digraph::Node,typename GR::Arc> PredMap;
   756     ///Instantiates a PredMap.
   757  
   758     ///This function instantiates a \ref PredMap. 
   759     ///\param g is the digraph, to which we would like to define the PredMap.
   760     ///\todo The digraph alone may be insufficient to initialize
   761 #ifdef DOXYGEN
   762     static PredMap *createPredMap(const GR &g) 
   763 #else
   764     static PredMap *createPredMap(const GR &) 
   765 #endif
   766     {
   767       return new PredMap();
   768     }
   769 
   770     ///The type of the map that indicates which nodes are processed.
   771  
   772     ///The type of the map that indicates which nodes are processed.
   773     ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
   774     ///\todo named parameter to set this type, function to read and write.
   775     typedef NullMap<typename Digraph::Node,bool> ProcessedMap;
   776     ///Instantiates a ProcessedMap.
   777  
   778     ///This function instantiates a \ref ProcessedMap. 
   779     ///\param g is the digraph, to which
   780     ///we would like to define the \ref ProcessedMap
   781 #ifdef DOXYGEN
   782     static ProcessedMap *createProcessedMap(const GR &g)
   783 #else
   784     static ProcessedMap *createProcessedMap(const GR &)
   785 #endif
   786     {
   787       return new ProcessedMap();
   788     }
   789     ///The type of the map that indicates which nodes are reached.
   790  
   791     ///The type of the map that indicates which nodes are reached.
   792     ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
   793     ///\todo named parameter to set this type, function to read and write.
   794     typedef typename Digraph::template NodeMap<bool> ReachedMap;
   795     ///Instantiates a ReachedMap.
   796  
   797     ///This function instantiates a \ref ReachedMap. 
   798     ///\param G is the digraph, to which
   799     ///we would like to define the \ref ReachedMap.
   800     static ReachedMap *createReachedMap(const GR &G)
   801     {
   802       return new ReachedMap(G);
   803     }
   804     ///The type of the map that stores the dists of the nodes.
   805  
   806     ///The type of the map that stores the dists of the nodes.
   807     ///It must meet the \ref concepts::WriteMap "WriteMap" concept.
   808     ///
   809     typedef NullMap<typename Digraph::Node,int> DistMap;
   810     ///Instantiates a DistMap.
   811  
   812     ///This function instantiates a \ref DistMap. 
   813     ///\param g is the digraph, to which we would like to define the \ref DistMap
   814 #ifdef DOXYGEN
   815     static DistMap *createDistMap(const GR &g)
   816 #else
   817     static DistMap *createDistMap(const GR &)
   818 #endif
   819     {
   820       return new DistMap();
   821     }
   822   };
   823   
   824   /// Default traits used by \ref DfsWizard
   825 
   826   /// To make it easier to use Dfs algorithm
   827   ///we have created a wizard class.
   828   /// This \ref DfsWizard class needs default traits,
   829   ///as well as the \ref Dfs class.
   830   /// The \ref DfsWizardBase is a class to be the default traits of the
   831   /// \ref DfsWizard class.
   832   template<class GR>
   833   class DfsWizardBase : public DfsWizardDefaultTraits<GR>
   834   {
   835 
   836     typedef DfsWizardDefaultTraits<GR> Base;
   837   protected:
   838     /// Type of the nodes in the digraph.
   839     typedef typename Base::Digraph::Node Node;
   840 
   841     /// Pointer to the underlying digraph.
   842     void *_g;
   843     ///Pointer to the map of reached nodes.
   844     void *_reached;
   845     ///Pointer to the map of processed nodes.
   846     void *_processed;
   847     ///Pointer to the map of predecessors arcs.
   848     void *_pred;
   849     ///Pointer to the map of distances.
   850     void *_dist;
   851     ///Pointer to the source node.
   852     Node _source;
   853     
   854     public:
   855     /// Constructor.
   856     
   857     /// This constructor does not require parameters, therefore it initiates
   858     /// all of the attributes to default values (0, INVALID).
   859     DfsWizardBase() : _g(0), _reached(0), _processed(0), _pred(0),
   860 			   _dist(0), _source(INVALID) {}
   861 
   862     /// Constructor.
   863     
   864     /// This constructor requires some parameters,
   865     /// listed in the parameters list.
   866     /// Others are initiated to 0.
   867     /// \param g is the initial value of  \ref _g
   868     /// \param s is the initial value of  \ref _source
   869     DfsWizardBase(const GR &g, Node s=INVALID) :
   870       _g(reinterpret_cast<void*>(const_cast<GR*>(&g))), 
   871       _reached(0), _processed(0), _pred(0), _dist(0), _source(s) {}
   872 
   873   };
   874   
   875   /// A class to make the usage of the Dfs algorithm easier
   876 
   877   /// This class is created to make it easier to use the Dfs algorithm.
   878   /// It uses the functions and features of the plain \ref Dfs,
   879   /// but it is much simpler to use it.
   880   ///
   881   /// Simplicity means that the way to change the types defined
   882   /// in the traits class is based on functions that returns the new class
   883   /// and not on templatable built-in classes.
   884   /// When using the plain \ref Dfs
   885   /// the new class with the modified type comes from
   886   /// the original class by using the ::
   887   /// operator. In the case of \ref DfsWizard only
   888   /// a function have to be called and it will
   889   /// return the needed class.
   890   ///
   891   /// It does not have own \ref run method. When its \ref run method is called
   892   /// it initiates a plain \ref Dfs object, and calls the \ref Dfs::run
   893   /// method of it.
   894   template<class TR>
   895   class DfsWizard : public TR
   896   {
   897     typedef TR Base;
   898 
   899     ///The type of the underlying digraph.
   900     typedef typename TR::Digraph Digraph;
   901     //\e
   902     typedef typename Digraph::Node Node;
   903     //\e
   904     typedef typename Digraph::NodeIt NodeIt;
   905     //\e
   906     typedef typename Digraph::Arc Arc;
   907     //\e
   908     typedef typename Digraph::OutArcIt OutArcIt;
   909     
   910     ///\brief The type of the map that stores
   911     ///the reached nodes
   912     typedef typename TR::ReachedMap ReachedMap;
   913     ///\brief The type of the map that stores
   914     ///the processed nodes
   915     typedef typename TR::ProcessedMap ProcessedMap;
   916     ///\brief The type of the map that stores the last
   917     ///arcs of the %DFS paths.
   918     typedef typename TR::PredMap PredMap;
   919     ///The type of the map that stores the distances of the nodes.
   920     typedef typename TR::DistMap DistMap;
   921 
   922   public:
   923     /// Constructor.
   924     DfsWizard() : TR() {}
   925 
   926     /// Constructor that requires parameters.
   927 
   928     /// Constructor that requires parameters.
   929     /// These parameters will be the default values for the traits class.
   930     DfsWizard(const Digraph &g, Node s=INVALID) :
   931       TR(g,s) {}
   932 
   933     ///Copy constructor
   934     DfsWizard(const TR &b) : TR(b) {}
   935 
   936     ~DfsWizard() {}
   937 
   938     ///Runs Dfs algorithm from a given node.
   939     
   940     ///Runs Dfs algorithm from a given node.
   941     ///The node can be given by the \ref source function.
   942     void run()
   943     {
   944       if(Base::_source==INVALID) throw UninitializedParameter();
   945       Dfs<Digraph,TR> alg(*reinterpret_cast<const Digraph*>(Base::_g));
   946       if(Base::_reached) 
   947         alg.reachedMap(*reinterpret_cast<ReachedMap*>(Base::_reached));
   948       if(Base::_processed) 
   949         alg.processedMap(*reinterpret_cast<ProcessedMap*>(Base::_processed));
   950       if(Base::_pred) 
   951         alg.predMap(*reinterpret_cast<PredMap*>(Base::_pred));
   952       if(Base::_dist) 
   953         alg.distMap(*reinterpret_cast<DistMap*>(Base::_dist));
   954       alg.run(Base::_source);
   955     }
   956 
   957     ///Runs Dfs algorithm from the given node.
   958 
   959     ///Runs Dfs algorithm from the given node.
   960     ///\param s is the given source.
   961     void run(Node s)
   962     {
   963       Base::_source=s;
   964       run();
   965     }
   966 
   967     template<class T>
   968     struct DefPredMapBase : public Base {
   969       typedef T PredMap;
   970       static PredMap *createPredMap(const Digraph &) { return 0; };
   971       DefPredMapBase(const TR &b) : TR(b) {}
   972     };
   973     
   974     ///\brief \ref named-templ-param "Named parameter"
   975     ///function for setting PredMap type
   976     ///
   977     /// \ref named-templ-param "Named parameter"
   978     ///function for setting PredMap type
   979     ///
   980     template<class T>
   981     DfsWizard<DefPredMapBase<T> > predMap(const T &t) 
   982     {
   983       Base::_pred=reinterpret_cast<void*>(const_cast<T*>(&t));
   984       return DfsWizard<DefPredMapBase<T> >(*this);
   985     }
   986     
   987  
   988     template<class T>
   989     struct DefReachedMapBase : public Base {
   990       typedef T ReachedMap;
   991       static ReachedMap *createReachedMap(const Digraph &) { return 0; };
   992       DefReachedMapBase(const TR &b) : TR(b) {}
   993     };
   994     
   995     ///\brief \ref named-templ-param "Named parameter"
   996     ///function for setting ReachedMap
   997     ///
   998     /// \ref named-templ-param "Named parameter"
   999     ///function for setting ReachedMap
  1000     ///
  1001     template<class T>
  1002     DfsWizard<DefReachedMapBase<T> > reachedMap(const T &t) 
  1003     {
  1004       Base::_pred=reinterpret_cast<void*>(const_cast<T*>(&t));
  1005       return DfsWizard<DefReachedMapBase<T> >(*this);
  1006     }
  1007     
  1008 
  1009     template<class T>
  1010     struct DefProcessedMapBase : public Base {
  1011       typedef T ProcessedMap;
  1012       static ProcessedMap *createProcessedMap(const Digraph &) { return 0; };
  1013       DefProcessedMapBase(const TR &b) : TR(b) {}
  1014     };
  1015     
  1016     ///\brief \ref named-templ-param "Named parameter"
  1017     ///function for setting ProcessedMap
  1018     ///
  1019     /// \ref named-templ-param "Named parameter"
  1020     ///function for setting ProcessedMap
  1021     ///
  1022     template<class T>
  1023     DfsWizard<DefProcessedMapBase<T> > processedMap(const T &t) 
  1024     {
  1025       Base::_pred=reinterpret_cast<void*>(const_cast<T*>(&t));
  1026       return DfsWizard<DefProcessedMapBase<T> >(*this);
  1027     }
  1028     
  1029     template<class T>
  1030     struct DefDistMapBase : public Base {
  1031       typedef T DistMap;
  1032       static DistMap *createDistMap(const Digraph &) { return 0; };
  1033       DefDistMapBase(const TR &b) : TR(b) {}
  1034     };
  1035     
  1036     ///\brief \ref named-templ-param "Named parameter"
  1037     ///function for setting DistMap type
  1038     ///
  1039     /// \ref named-templ-param "Named parameter"
  1040     ///function for setting DistMap type
  1041     ///
  1042     template<class T>
  1043     DfsWizard<DefDistMapBase<T> > distMap(const T &t) 
  1044     {
  1045       Base::_dist=reinterpret_cast<void*>(const_cast<T*>(&t));
  1046       return DfsWizard<DefDistMapBase<T> >(*this);
  1047     }
  1048     
  1049     /// Sets the source node, from which the Dfs algorithm runs.
  1050 
  1051     /// Sets the source node, from which the Dfs algorithm runs.
  1052     /// \param s is the source node.
  1053     DfsWizard<TR> &source(Node s) 
  1054     {
  1055       Base::_source=s;
  1056       return *this;
  1057     }
  1058     
  1059   };
  1060   
  1061   ///Function type interface for Dfs algorithm.
  1062 
  1063   ///\ingroup search
  1064   ///Function type interface for Dfs algorithm.
  1065   ///
  1066   ///This function also has several
  1067   ///\ref named-templ-func-param "named parameters",
  1068   ///they are declared as the members of class \ref DfsWizard.
  1069   ///The following
  1070   ///example shows how to use these parameters.
  1071   ///\code
  1072   ///  dfs(g,source).predMap(preds).run();
  1073   ///\endcode
  1074   ///\warning Don't forget to put the \ref DfsWizard::run() "run()"
  1075   ///to the end of the parameter list.
  1076   ///\sa DfsWizard
  1077   ///\sa Dfs
  1078   template<class GR>
  1079   DfsWizard<DfsWizardBase<GR> >
  1080   dfs(const GR &g,typename GR::Node s=INVALID)
  1081   {
  1082     return DfsWizard<DfsWizardBase<GR> >(g,s);
  1083   }
  1084 
  1085 #ifdef DOXYGEN
  1086   /// \brief Visitor class for dfs.
  1087   ///  
  1088   /// It gives a simple interface for a functional interface for dfs 
  1089   /// traversal. The traversal on a linear data structure. 
  1090   template <typename _Digraph>
  1091   struct DfsVisitor {
  1092     typedef _Digraph Digraph;
  1093     typedef typename Digraph::Arc Arc;
  1094     typedef typename Digraph::Node Node;
  1095     /// \brief Called when the arc reach a node.
  1096     /// 
  1097     /// It is called when the dfs find an arc which target is not
  1098     /// reached yet.
  1099     void discover(const Arc& arc) {}
  1100     /// \brief Called when the node reached first time.
  1101     /// 
  1102     /// It is Called when the node reached first time.
  1103     void reach(const Node& node) {}
  1104     /// \brief Called when we step back on an arc.
  1105     /// 
  1106     /// It is called when the dfs should step back on the arc.
  1107     void backtrack(const Arc& arc) {}
  1108     /// \brief Called when we step back from the node.
  1109     /// 
  1110     /// It is called when we step back from the node.
  1111     void leave(const Node& node) {}
  1112     /// \brief Called when the arc examined but target of the arc 
  1113     /// already discovered.
  1114     /// 
  1115     /// It called when the arc examined but the target of the arc 
  1116     /// already discovered.
  1117     void examine(const Arc& arc) {}
  1118     /// \brief Called for the source node of the dfs.
  1119     /// 
  1120     /// It is called for the source node of the dfs.
  1121     void start(const Node& node) {}
  1122     /// \brief Called when we leave the source node of the dfs.
  1123     /// 
  1124     /// It is called when we leave the source node of the dfs.
  1125     void stop(const Node& node) {}
  1126 
  1127   };
  1128 #else
  1129   template <typename _Digraph>
  1130   struct DfsVisitor {
  1131     typedef _Digraph Digraph;
  1132     typedef typename Digraph::Arc Arc;
  1133     typedef typename Digraph::Node Node;
  1134     void discover(const Arc&) {}
  1135     void reach(const Node&) {}
  1136     void backtrack(const Arc&) {}
  1137     void leave(const Node&) {}
  1138     void examine(const Arc&) {}
  1139     void start(const Node&) {}
  1140     void stop(const Node&) {}
  1141 
  1142     template <typename _Visitor>
  1143     struct Constraints {
  1144       void constraints() {
  1145 	Arc arc;
  1146 	Node node;
  1147 	visitor.discover(arc);
  1148 	visitor.reach(node);
  1149 	visitor.backtrack(arc);
  1150 	visitor.leave(node);
  1151 	visitor.examine(arc);
  1152 	visitor.start(node);
  1153 	visitor.stop(arc);
  1154       }
  1155       _Visitor& visitor;
  1156     };
  1157   };
  1158 #endif
  1159 
  1160   /// \brief Default traits class of DfsVisit class.
  1161   ///
  1162   /// Default traits class of DfsVisit class.
  1163   /// \param _Digraph Digraph type.
  1164   template<class _Digraph>
  1165   struct DfsVisitDefaultTraits {
  1166 
  1167     /// \brief The digraph type the algorithm runs on. 
  1168     typedef _Digraph Digraph;
  1169 
  1170     /// \brief The type of the map that indicates which nodes are reached.
  1171     /// 
  1172     /// The type of the map that indicates which nodes are reached.
  1173     /// It must meet the \ref concepts::WriteMap "WriteMap" concept.
  1174     /// \todo named parameter to set this type, function to read and write.
  1175     typedef typename Digraph::template NodeMap<bool> ReachedMap;
  1176 
  1177     /// \brief Instantiates a ReachedMap.
  1178     ///
  1179     /// This function instantiates a \ref ReachedMap. 
  1180     /// \param digraph is the digraph, to which
  1181     /// we would like to define the \ref ReachedMap.
  1182     static ReachedMap *createReachedMap(const Digraph &digraph) {
  1183       return new ReachedMap(digraph);
  1184     }
  1185 
  1186   };
  1187   
  1188   /// %DFS Visit algorithm class.
  1189   
  1190   /// \ingroup search
  1191   /// This class provides an efficient implementation of the %DFS algorithm
  1192   /// with visitor interface.
  1193   ///
  1194   /// The %DfsVisit class provides an alternative interface to the Dfs
  1195   /// class. It works with callback mechanism, the DfsVisit object calls
  1196   /// on every dfs event the \c Visitor class member functions. 
  1197   ///
  1198   /// \param _Digraph The digraph type the algorithm runs on. The default value is
  1199   /// \ref ListDigraph. The value of _Digraph is not used directly by Dfs, it
  1200   /// is only passed to \ref DfsDefaultTraits.
  1201   /// \param _Visitor The Visitor object for the algorithm. The 
  1202   /// \ref DfsVisitor "DfsVisitor<_Digraph>" is an empty Visitor which
  1203   /// does not observe the Dfs events. If you want to observe the dfs
  1204   /// events you should implement your own Visitor class.
  1205   /// \param _Traits Traits class to set various data types used by the 
  1206   /// algorithm. The default traits class is
  1207   /// \ref DfsVisitDefaultTraits "DfsVisitDefaultTraits<_Digraph>".
  1208   /// See \ref DfsVisitDefaultTraits for the documentation of
  1209   /// a Dfs visit traits class.
  1210   ///
  1211   /// \author Jacint Szabo, Alpar Juttner and Balazs Dezso
  1212 #ifdef DOXYGEN
  1213   template <typename _Digraph, typename _Visitor, typename _Traits>
  1214 #else
  1215   template <typename _Digraph = ListDigraph,
  1216 	    typename _Visitor = DfsVisitor<_Digraph>,
  1217 	    typename _Traits = DfsDefaultTraits<_Digraph> >
  1218 #endif
  1219   class DfsVisit {
  1220   public:
  1221     
  1222     /// \brief \ref Exception for uninitialized parameters.
  1223     ///
  1224     /// This error represents problems in the initialization
  1225     /// of the parameters of the algorithms.
  1226     class UninitializedParameter : public lemon::UninitializedParameter {
  1227     public:
  1228       virtual const char* what() const throw() 
  1229       {
  1230 	return "lemon::DfsVisit::UninitializedParameter";
  1231       }
  1232     };
  1233 
  1234     typedef _Traits Traits;
  1235 
  1236     typedef typename Traits::Digraph Digraph;
  1237 
  1238     typedef _Visitor Visitor;
  1239 
  1240     ///The type of the map indicating which nodes are reached.
  1241     typedef typename Traits::ReachedMap ReachedMap;
  1242 
  1243   private:
  1244 
  1245     typedef typename Digraph::Node Node;
  1246     typedef typename Digraph::NodeIt NodeIt;
  1247     typedef typename Digraph::Arc Arc;
  1248     typedef typename Digraph::OutArcIt OutArcIt;
  1249 
  1250     /// Pointer to the underlying digraph.
  1251     const Digraph *_digraph;
  1252     /// Pointer to the visitor object.
  1253     Visitor *_visitor;
  1254     ///Pointer to the map of reached status of the nodes.
  1255     ReachedMap *_reached;
  1256     ///Indicates if \ref _reached is locally allocated (\c true) or not.
  1257     bool local_reached;
  1258 
  1259     std::vector<typename Digraph::Arc> _stack;
  1260     int _stack_head;
  1261 
  1262     /// \brief Creates the maps if necessary.
  1263     ///
  1264     /// Creates the maps if necessary.
  1265     void create_maps() {
  1266       if(!_reached) {
  1267 	local_reached = true;
  1268 	_reached = Traits::createReachedMap(*_digraph);
  1269       }
  1270     }
  1271 
  1272   protected:
  1273 
  1274     DfsVisit() {}
  1275     
  1276   public:
  1277 
  1278     typedef DfsVisit Create;
  1279 
  1280     /// \name Named template parameters
  1281 
  1282     ///@{
  1283     template <class T>
  1284     struct DefReachedMapTraits : public Traits {
  1285       typedef T ReachedMap;
  1286       static ReachedMap *createReachedMap(const Digraph &digraph) {
  1287 	throw UninitializedParameter();
  1288       }
  1289     };
  1290     /// \brief \ref named-templ-param "Named parameter" for setting 
  1291     /// ReachedMap type
  1292     ///
  1293     /// \ref named-templ-param "Named parameter" for setting ReachedMap type
  1294     template <class T>
  1295     struct DefReachedMap : public DfsVisit< Digraph, Visitor,
  1296 					    DefReachedMapTraits<T> > {
  1297       typedef DfsVisit< Digraph, Visitor, DefReachedMapTraits<T> > Create;
  1298     };
  1299     ///@}
  1300 
  1301   public:      
  1302     
  1303     /// \brief Constructor.
  1304     ///
  1305     /// Constructor.
  1306     ///
  1307     /// \param digraph the digraph the algorithm will run on.
  1308     /// \param visitor The visitor of the algorithm.
  1309     ///
  1310     DfsVisit(const Digraph& digraph, Visitor& visitor) 
  1311       : _digraph(&digraph), _visitor(&visitor),
  1312 	_reached(0), local_reached(false) {}
  1313     
  1314     /// \brief Destructor.
  1315     ///
  1316     /// Destructor.
  1317     ~DfsVisit() {
  1318       if(local_reached) delete _reached;
  1319     }
  1320 
  1321     /// \brief Sets the map indicating if a node is reached.
  1322     ///
  1323     /// Sets the map indicating if a node is reached.
  1324     /// If you don't use this function before calling \ref run(),
  1325     /// it will allocate one. The destuctor deallocates this
  1326     /// automatically allocated map, of course.
  1327     /// \return <tt> (*this) </tt>
  1328     DfsVisit &reachedMap(ReachedMap &m) {
  1329       if(local_reached) {
  1330 	delete _reached;
  1331 	local_reached=false;
  1332       }
  1333       _reached = &m;
  1334       return *this;
  1335     }
  1336 
  1337   public:
  1338     /// \name Execution control
  1339     /// The simplest way to execute the algorithm is to use
  1340     /// one of the member functions called \c run(...).
  1341     /// \n
  1342     /// If you need more control on the execution,
  1343     /// first you must call \ref init(), then you can adda source node
  1344     /// with \ref addSource().
  1345     /// Finally \ref start() will perform the actual path
  1346     /// computation.
  1347 
  1348     /// @{
  1349     /// \brief Initializes the internal data structures.
  1350     ///
  1351     /// Initializes the internal data structures.
  1352     ///
  1353     void init() {
  1354       create_maps();
  1355       _stack.resize(countNodes(*_digraph));
  1356       _stack_head = -1;
  1357       for (NodeIt u(*_digraph) ; u != INVALID ; ++u) {
  1358 	_reached->set(u, false);
  1359       }
  1360     }
  1361     
  1362     /// \brief Adds a new source node.
  1363     ///
  1364     /// Adds a new source node to the set of nodes to be processed.
  1365     void addSource(Node s) {
  1366       if(!(*_reached)[s]) {
  1367 	  _reached->set(s,true);
  1368 	  _visitor->start(s);
  1369 	  _visitor->reach(s);
  1370 	  Arc e; 
  1371 	  _digraph->firstOut(e, s);
  1372 	  if (e != INVALID) {
  1373 	    _stack[++_stack_head] = e;
  1374 	  } else {
  1375 	    _visitor->leave(s);
  1376 	  }
  1377 	}
  1378     }
  1379     
  1380     /// \brief Processes the next arc.
  1381     ///
  1382     /// Processes the next arc.
  1383     ///
  1384     /// \return The processed arc.
  1385     ///
  1386     /// \pre The stack must not be empty!
  1387     Arc processNextArc() { 
  1388       Arc e = _stack[_stack_head];
  1389       Node m = _digraph->target(e);
  1390       if(!(*_reached)[m]) {
  1391 	_visitor->discover(e);
  1392 	_visitor->reach(m);
  1393 	_reached->set(m, true);
  1394 	_digraph->firstOut(_stack[++_stack_head], m);
  1395       } else {
  1396 	_visitor->examine(e);
  1397 	m = _digraph->source(e);
  1398 	_digraph->nextOut(_stack[_stack_head]);
  1399       }
  1400       while (_stack_head>=0 && _stack[_stack_head] == INVALID) {
  1401 	_visitor->leave(m);
  1402 	--_stack_head;
  1403 	if (_stack_head >= 0) {
  1404 	  _visitor->backtrack(_stack[_stack_head]);
  1405 	  m = _digraph->source(_stack[_stack_head]);
  1406 	  _digraph->nextOut(_stack[_stack_head]);
  1407 	} else {
  1408 	  _visitor->stop(m);	  
  1409 	}
  1410       }
  1411       return e;
  1412     }
  1413 
  1414     /// \brief Next arc to be processed.
  1415     ///
  1416     /// Next arc to be processed.
  1417     ///
  1418     /// \return The next arc to be processed or INVALID if the stack is
  1419     /// empty.
  1420     Arc nextArc() { 
  1421       return _stack_head >= 0 ? _stack[_stack_head] : INVALID;
  1422     }
  1423 
  1424     /// \brief Returns \c false if there are nodes
  1425     /// to be processed in the queue
  1426     ///
  1427     /// Returns \c false if there are nodes
  1428     /// to be processed in the queue
  1429     bool emptyQueue() { return _stack_head < 0; }
  1430 
  1431     /// \brief Returns the number of the nodes to be processed.
  1432     ///
  1433     /// Returns the number of the nodes to be processed in the queue.
  1434     int queueSize() { return _stack_head + 1; }
  1435     
  1436     /// \brief Executes the algorithm.
  1437     ///
  1438     /// Executes the algorithm.
  1439     ///
  1440     /// \pre init() must be called and at least one node should be added
  1441     /// with addSource() before using this function.
  1442     void start() {
  1443       while ( !emptyQueue() ) processNextArc();
  1444     }
  1445     
  1446     /// \brief Executes the algorithm until \c dest is reached.
  1447     ///
  1448     /// Executes the algorithm until \c dest is reached.
  1449     ///
  1450     /// \pre init() must be called and at least one node should be added
  1451     /// with addSource() before using this function.
  1452     void start(Node dest) {
  1453       while ( !emptyQueue() && _digraph->target(_stack[_stack_head]) != dest ) 
  1454 	processNextArc();
  1455     }
  1456     
  1457     /// \brief Executes the algorithm until a condition is met.
  1458     ///
  1459     /// Executes the algorithm until a condition is met.
  1460     ///
  1461     /// \pre init() must be called and at least one node should be added
  1462     /// with addSource() before using this function.
  1463     ///
  1464     /// \param em must be a bool (or convertible) arc map. The algorithm
  1465     /// will stop when it reaches an arc \c e with <tt>em[e]</tt> true.
  1466     ///
  1467     ///\return The reached arc \c e with <tt>em[e]</tt> true or
  1468     ///\c INVALID if no such arc was found.
  1469     ///
  1470     /// \warning Contrary to \ref Bfs and \ref Dijkstra, \c em is an arc map,
  1471     /// not a node map.
  1472     template <typename EM>
  1473     Arc start(const EM &em) {
  1474       while ( !emptyQueue() && !em[_stack[_stack_head]] )
  1475         processNextArc();
  1476       return emptyQueue() ? INVALID : _stack[_stack_head];
  1477     }
  1478 
  1479     /// \brief Runs %DFSVisit algorithm from node \c s.
  1480     ///
  1481     /// This method runs the %DFS algorithm from a root node \c s.
  1482     /// \note d.run(s) is just a shortcut of the following code.
  1483     ///\code
  1484     ///   d.init();
  1485     ///   d.addSource(s);
  1486     ///   d.start();
  1487     ///\endcode
  1488     void run(Node s) {
  1489       init();
  1490       addSource(s);
  1491       start();
  1492     }
  1493 
  1494     /// \brief Runs %DFSVisit algorithm to visit all nodes in the digraph.
  1495     
  1496     /// This method runs the %DFS algorithm in order to
  1497     /// compute the %DFS path to each node. The algorithm computes
  1498     /// - The %DFS tree.
  1499     /// - The distance of each node from the root in the %DFS tree.
  1500     ///
  1501     ///\note d.run() is just a shortcut of the following code.
  1502     ///\code
  1503     ///  d.init();
  1504     ///  for (NodeIt it(digraph); it != INVALID; ++it) {
  1505     ///    if (!d.reached(it)) {
  1506     ///      d.addSource(it);
  1507     ///      d.start();
  1508     ///    }
  1509     ///  }
  1510     ///\endcode
  1511     void run() {
  1512       init();
  1513       for (NodeIt it(*_digraph); it != INVALID; ++it) {
  1514         if (!reached(it)) {
  1515           addSource(it);
  1516           start();
  1517         }
  1518       }
  1519     }
  1520     ///@}
  1521 
  1522     /// \name Query Functions
  1523     /// The result of the %DFS algorithm can be obtained using these
  1524     /// functions.\n
  1525     /// Before the use of these functions,
  1526     /// either run() or start() must be called.
  1527     ///@{
  1528     /// \brief Checks if a node is reachable from the root.
  1529     ///
  1530     /// Returns \c true if \c v is reachable from the root(s).
  1531     /// \warning The source nodes are inditated as unreachable.
  1532     /// \pre Either \ref run() or \ref start()
  1533     /// must be called before using this function.
  1534     ///
  1535     bool reached(Node v) { return (*_reached)[v]; }
  1536     ///@}
  1537   };
  1538 
  1539 
  1540 } //END OF NAMESPACE LEMON
  1541 
  1542 #endif
  1543