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