RhodeCode

 *

 * Copyright (C) 2003-2008

 * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport

 * (Egervary Research Group on Combinatorial Optimization, EGRES).

 *

 * Permission to use, modify and distribute this software is granted

 * provided that this copyright notice appears in all copies. For

 * precise terms see the accompanying LICENSE file.

 *

 * This software is provided "AS IS" with no warranty of any kind,

 * express or implied, and with no claim as to its suitability for any

 * purpose.

 *

 */

///\ingroup demos

///\file

///\brief Demonstrating graph input and output

///

/// This program gives an example of how to read and write a digraph

/// and additional maps from/to a stream or a file using the

/// \ref lgf-format "LGF" format.

///

/// The \c "digraph.lgf" file:

/// \include digraph.lgf

///

/// And the program which reads it and prints the digraph to the

/// standard output:

/// \include lgf_demo.cc

#include <iostream>

#include <lemon/smart_graph.h>

#include <lemon/lgf_reader.h>

#include <lemon/lgf_writer.h>

using namespace lemon;

int main() {

  SmartDigraph g;

  SmartDigraph::ArcMap<int> cap(g);

  SmartDigraph::Node s, t;

  try {

    digraphReader("digraph.lgf", g). // read the directed graph into g

      arcMap("capacity", cap).       // read the 'capacity' arc map into cap

      node("source", s).             // read 'source' node to s

      node("target", t).             // read 'target' node to t

      run();

    std::cerr << "Error: " << error.what() << std::endl;

    return -1;

  }

  std::cout << "A digraph is read from 'digraph.lgf'." << std::endl;

  std::cout << "Number of nodes: " << countNodes(g) << std::endl;

  std::cout << "Number of arcs: " << countArcs(g) << std::endl;

  std::cout << "We can write it to the standard output:" << std::endl;

  digraphWriter(std::cout, g).     // write g to the standard output

    arcMap("capacity", cap).       // write cap into 'capacity'

    node("source", s).             // write s to 'source'

    node("target", t).             // write t to 'target'

    run();

  return 0;

}

    ///Create synonym to an option

    ///With this function you can create a synonym \c syn of the

    ///option \c opt.

    ArgParser &synonym(const std::string &syn,

                           const std::string &opt);

    ///@}

  private:

    void show(std::ostream &os,Opts::const_iterator i) const;

    void show(std::ostream &os,Groups::const_iterator i) const;

    void showHelp(Opts::const_iterator i) const;

    void showHelp(std::vector<OtherArg>::const_iterator i) const;

    void unknownOpt(std::string arg) const;

    void requiresValue(std::string arg, OptType t) const;

    void checkMandatories() const;

    void shortHelp() const;

    void showHelp() const;

  public:

    ///Start the parsing process

    ArgParser &parse();

    /// Synonym for parse()

    ArgParser &run()

    {

      return parse();

    }

    ///Give back the command name (the 0th argument)

    const std::string &commandName() const { return _command_name; }

    ///Check if an opion has been given to the command.

    bool given(std::string op) const

    {

      Opts::const_iterator i = _opts.find(op);

      return i!=_opts.end()?i->second.set:false;

    }

    ///Magic type for operator[]

    ///This is the type of the return value of ArgParser::operator[]().

    ///It automatically converts to \c int, \c double, \c bool or

    class RefType

    {

      const ArgParser &_parser;

      std::string _name;

    public:

      ///\e

      RefType(const ArgParser &p,const std::string &n) :_parser(p),_name(n) {}

      ///\e

      operator bool()

      {

        Opts::const_iterator i = _parser._opts.find(_name);

        LEMON_ASSERT(i!=_parser._opts.end(),

                     std::string()+"Unkown option: '"+_name+"'");

        LEMON_ASSERT(i->second.type==ArgParser::BOOL,

                     std::string()+"'"+_name+"' is a bool option");

        return *(i->second.bool_p);

      }

      ///\e

      operator std::string()

      {

        Opts::const_iterator i = _parser._opts.find(_name);

        LEMON_ASSERT(i!=_parser._opts.end(),

                     std::string()+"Unkown option: '"+_name+"'");

        LEMON_ASSERT(i->second.type==ArgParser::STRING,

                     std::string()+"'"+_name+"' is a string option");

        return *(i->second.string_p);

      }

      ///\e

      operator double()

      {

        Opts::const_iterator i = _parser._opts.find(_name);

        LEMON_ASSERT(i!=_parser._opts.end(),

                     std::string()+"Unkown option: '"+_name+"'");

        LEMON_ASSERT(i->second.type==ArgParser::DOUBLE ||

                     i->second.type==ArgParser::INTEGER,

                     std::string()+"'"+_name+"' is a floating point option");

        return i->second.type==ArgParser::DOUBLE ?

          *(i->second.double_p) : *(i->second.int_p);

      }

      ///\e

      operator int()

      {

        Opts::const_iterator i = _parser._opts.find(_name);

        LEMON_ASSERT(i!=_parser._opts.end(),

                     std::string()+"Unkown option: '"+_name+"'");

        LEMON_ASSERT(i->second.type==ArgParser::INTEGER,

                     std::string()+"'"+_name+"' is an integer option");

        return *(i->second.int_p);

  (defined(LEMON_ASSERT_CUSTOM) ? 1 : 0) > 1

#error "LEMON assertion system is not set properly"

#endif

#if ((defined(LEMON_ASSERT_ABORT) ? 1 : 0) +            \

     (defined(LEMON_ASSERT_CUSTOM) ? 1 : 0) == 1 ||     \

     defined(LEMON_ENABLE_ASSERTS)) &&                  \

  (defined(LEMON_DISABLE_ASSERTS) ||                    \

   defined(NDEBUG))

#error "LEMON assertion system is not set properly"

#endif

#if defined LEMON_ASSERT_ABORT

#  undef LEMON_ASSERT_HANDLER

#  define LEMON_ASSERT_HANDLER ::lemon::assert_fail_abort

#elif defined LEMON_ASSERT_CUSTOM

#  undef LEMON_ASSERT_HANDLER

#  ifndef LEMON_CUSTOM_ASSERT_HANDLER

#    error "LEMON_CUSTOM_ASSERT_HANDLER is not set"

#  endif

#  define LEMON_ASSERT_HANDLER LEMON_CUSTOM_ASSERT_HANDLER

#elif defined LEMON_DISABLE_ASSERTS

#  undef LEMON_ASSERT_HANDLER

#elif defined NDEBUG

#  undef LEMON_ASSERT_HANDLER

#else

#  define LEMON_ASSERT_HANDLER ::lemon::assert_fail_abort

#endif

#ifndef LEMON_FUNCTION_NAME

#  if defined __GNUC__

#    define LEMON_FUNCTION_NAME (__PRETTY_FUNCTION__)

#  elif defined _MSC_VER

#    define LEMON_FUNCTION_NAME (__FUNCSIG__)

#  elif __STDC_VERSION__ >= 199901L

#    define LEMON_FUNCTION_NAME (__func__)

#  else

#    define LEMON_FUNCTION_NAME ("<unknown>")

#  endif

#endif

#ifdef DOXYGEN

/// \ingroup exceptions

///

/// \brief Macro for assertion with customizable message

///

/// \param exp An expression that must be convertible to \c bool.  If it is \c

/// false, then an assertion is raised. The concrete behaviour depends on the

/// settings of the assertion system.

/// \param msg A <tt>const char*</tt> parameter, which can be used to provide

/// information about the circumstances of the failed assertion.

///

/// The assertions are enabled in the default behaviour.

/// You can disable them with the following code:

/// \code

/// #define LEMON_DISABLE_ASSERTS

/// \endcode

/// or with compilation parameters:

/// \code

/// g++ -DLEMON_DISABLE_ASSERTS

/// make CXXFLAGS='-DLEMON_DISABLE_ASSERTS'

/// \endcode

/// The checking is also disabled when the standard macro \c NDEBUG is defined.

///

/// As a default behaviour the failed assertion prints a short log message to

/// the standard error and aborts the execution.

///

/// However, the following modes can be used in the assertion system:

/// - \c LEMON_ASSERT_ABORT The failed assertion prints a short log message to

///   the standard error and aborts the program. It is the default behaviour.

/// - \c LEMON_ASSERT_CUSTOM The user can define own assertion handler

///   function.

///   \code

///     void custom_assert_handler(const char* file, int line,

///                                const char* function, const char* message,

///                                const char* assertion);

///   \endcode

///   The name of the function should be defined as the \c

///   LEMON_CUSTOM_ASSERT_HANDLER macro name.

///   \code

///     #define LEMON_CUSTOM_ASSERT_HANDLER custom_assert_handler

///   \endcode

///   Whenever an assertion is occured, the custom assertion

///   handler is called with appropiate parameters.

///

/// The assertion mode can also be changed within one compilation unit.

/// If the macros are redefined with other settings and the

/// \ref lemon/assert.h "assert.h" file is reincluded, then the

/// behaviour is changed appropiately to the new settings.

#  define LEMON_ASSERT(exp, msg)                                        \

  (static_cast<void> (!!(exp) ? 0 : (                                   \

    LEMON_ASSERT_HANDLER(__FILE__, __LINE__,                            \

                         LEMON_FUNCTION_NAME,                           \

                         ::lemon::_assert_bits::cstringify(msg), #exp), 0)))

    ///we would like to define the \ref ReachedMap.

    static ReachedMap *createReachedMap(const Digraph &g)

    {

      return new ReachedMap(g);

    }

    ///The type of the map that stores the distances of the nodes.

    ///The type of the map that stores the distances of the nodes.

    ///It must meet the \ref concepts::WriteMap "WriteMap" concept.

    typedef typename Digraph::template NodeMap<int> DistMap;

    ///Instantiates a \ref DistMap.

    ///This function instantiates a \ref DistMap.

    ///\param g is the digraph, to which we would like to define the

    ///\ref DistMap.

    static DistMap *createDistMap(const Digraph &g)

    {

      return new DistMap(g);

    }

  };

  ///%BFS algorithm class.

  ///\ingroup search

  ///This class provides an efficient implementation of the %BFS algorithm.

  ///

  ///There is also a \ref bfs() "function-type interface" for the BFS

  ///algorithm, which is convenient in the simplier cases and it can be

  ///used easier.

  ///

  ///\tparam GR The type of the digraph the algorithm runs on.

  ///The default value is \ref ListDigraph. The value of GR is not used

  ///directly by \ref Bfs, it is only passed to \ref BfsDefaultTraits.

  ///\tparam TR Traits class to set various data types used by the algorithm.

  ///The default traits class is

  ///\ref BfsDefaultTraits "BfsDefaultTraits<GR>".

  ///See \ref BfsDefaultTraits for the documentation of

  ///a Bfs traits class.

#ifdef DOXYGEN

  template <typename GR,

            typename TR>

#else

  template <typename GR=ListDigraph,

            typename TR=BfsDefaultTraits<GR> >

#endif

  class Bfs {

  public:

    ///The type of the digraph the algorithm runs on.

    typedef typename TR::Digraph Digraph;

    ///\brief The type of the map that stores the predecessor arcs of the

    ///shortest paths.

    typedef typename TR::PredMap PredMap;

    ///The type of the map that stores the distances of the nodes.

    typedef typename TR::DistMap DistMap;

    ///The type of the map that indicates which nodes are reached.

    typedef typename TR::ReachedMap ReachedMap;

    ///The type of the map that indicates which nodes are processed.

    typedef typename TR::ProcessedMap ProcessedMap;

    ///The type of the paths.

    typedef PredMapPath<Digraph, PredMap> Path;

    ///The traits class.

    typedef TR Traits;

  private:

    typedef typename Digraph::Node Node;

    typedef typename Digraph::NodeIt NodeIt;

    typedef typename Digraph::Arc Arc;

    typedef typename Digraph::OutArcIt OutArcIt;

    //Pointer to the underlying digraph.

    const Digraph *G;

    //Pointer to the map of predecessor arcs.

    PredMap *_pred;

    //Indicates if _pred is locally allocated (true) or not.

    bool local_pred;

    //Pointer to the map of distances.

    DistMap *_dist;

    //Indicates if _dist is locally allocated (true) or not.

    bool local_dist;

    //Pointer to the map of reached status of the nodes.

    ReachedMap *_reached;

    //Indicates if _reached is locally allocated (true) or not.

    bool local_reached;

    //Pointer to the map of processed status of the nodes.

    ProcessedMap *_processed;

    //Indicates if _processed is locally allocated (true) or not.

    bool local_processed;

    std::vector<typename Digraph::Node> _queue;

    int _queue_head,_queue_tail,_queue_next_dist;

    int _curr_dist;

    //Creates the maps if necessary.

    void create_maps()

    {

      if(!_pred) {

        local_pred = true;

        _pred = Traits::createPredMap(*G);

      }

      if(!_dist) {

        local_dist = true;

        _dist = Traits::createDistMap(*G);

      }

      if(!_reached) {

        local_reached = true;

        _reached = Traits::createReachedMap(*G);

      }

      if(!_processed) {

        local_processed = true;

        _processed = Traits::createProcessedMap(*G);

      }

    }

  protected:

    Bfs() {}

  public:

    typedef Bfs Create;

    ///\name Named template parameters

    ///@{

    template <class T>

    struct SetPredMapTraits : public Traits {

      typedef T PredMap;

      static PredMap *createPredMap(const Digraph &)

      {

      }

    };

    ///\brief \ref named-templ-param "Named parameter" for setting

    ///\ref PredMap type.

    ///

    ///\ref named-templ-param "Named parameter" for setting

    ///\ref PredMap type.

    template <class T>

    struct SetPredMap : public Bfs< Digraph, SetPredMapTraits<T> > {

      typedef Bfs< Digraph, SetPredMapTraits<T> > Create;

    };

    template <class T>

    struct SetDistMapTraits : public Traits {

      typedef T DistMap;

      static DistMap *createDistMap(const Digraph &)

      {

      }

    };

    ///\brief \ref named-templ-param "Named parameter" for setting

    ///\ref DistMap type.

    ///

    ///\ref named-templ-param "Named parameter" for setting

    ///\ref DistMap type.

    template <class T>

    struct SetDistMap : public Bfs< Digraph, SetDistMapTraits<T> > {

      typedef Bfs< Digraph, SetDistMapTraits<T> > Create;

    };

    template <class T>

    struct SetReachedMapTraits : public Traits {

      typedef T ReachedMap;

      static ReachedMap *createReachedMap(const Digraph &)

      {

      }

    };

    ///\brief \ref named-templ-param "Named parameter" for setting

    ///\ref ReachedMap type.

    ///

    ///\ref named-templ-param "Named parameter" for setting

    ///\ref ReachedMap type.

    template <class T>

    struct SetReachedMap : public Bfs< Digraph, SetReachedMapTraits<T> > {

      typedef Bfs< Digraph, SetReachedMapTraits<T> > Create;

    };

    template <class T>

    struct SetProcessedMapTraits : public Traits {

      typedef T ProcessedMap;

      static ProcessedMap *createProcessedMap(const Digraph &)

      {

      }

    };

    ///\brief \ref named-templ-param "Named parameter" for setting

    ///\ref ProcessedMap type.

    ///

    ///\ref named-templ-param "Named parameter" for setting

    ///\ref ProcessedMap type.

    template <class T>

    struct SetProcessedMap : public Bfs< Digraph, SetProcessedMapTraits<T> > {

      typedef Bfs< Digraph, SetProcessedMapTraits<T> > Create;

    };

    struct SetStandardProcessedMapTraits : public Traits {

      typedef typename Digraph::template NodeMap<bool> ProcessedMap;

      static ProcessedMap *createProcessedMap(const Digraph &g)

      {

        return new ProcessedMap(g);

      }

    };

    ///\brief \ref named-templ-param "Named parameter" for setting

    ///\ref ProcessedMap type to be <tt>Digraph::NodeMap<bool></tt>.

    ///

    ///\ref named-templ-param "Named parameter" for setting

    ///\ref ProcessedMap type to be <tt>Digraph::NodeMap<bool></tt>.

    ///If you don't set it explicitly, it will be automatically allocated.

    struct SetStandardProcessedMap :

      public Bfs< Digraph, SetStandardProcessedMapTraits > {

      typedef Bfs< Digraph, SetStandardProcessedMapTraits > Create;

    };

    ///@}

  public:

    ///Constructor.

    ///Constructor.

    ///\param g The digraph the algorithm runs on.

    Bfs(const Digraph &g) :

      G(&g),

      _pred(NULL), local_pred(false),

      _dist(NULL), local_dist(false),

      _reached(NULL), local_reached(false),

      _processed(NULL), local_processed(false)

    { }

    ///Destructor.

    ~Bfs()

    {

      if(local_pred) delete _pred;

      if(local_dist) delete _dist;

      if(local_reached) delete _reached;

      if(local_processed) delete _processed;

    }

    ///Sets the map that stores the predecessor arcs.

    ///Sets the map that stores the predecessor arcs.

    ///If you don't use this function before calling \ref run(),

    ///it will allocate one. The destructor deallocates this

    ///automatically allocated map, of course.

    ///\return <tt> (*this) </tt>

    Bfs &predMap(PredMap &m)

    {

      if(local_pred) {

  public:

    /// Constructor.

    BfsWizard() : TR() {}

    /// Constructor that requires parameters.

    /// Constructor that requires parameters.

    /// These parameters will be the default values for the traits class.

    /// \param g The digraph the algorithm runs on.

    BfsWizard(const Digraph &g) :

      TR(g) {}

    ///Copy constructor

    BfsWizard(const TR &b) : TR(b) {}

    ~BfsWizard() {}

    ///Runs BFS algorithm from the given source node.

    ///This method runs BFS algorithm from node \c s

    ///in order to compute the shortest path to each node.

    void run(Node s)

    {

      Bfs<Digraph,TR> alg(*reinterpret_cast<const Digraph*>(Base::_g));

      if (Base::_pred)

        alg.predMap(*reinterpret_cast<PredMap*>(Base::_pred));

      if (Base::_dist)

        alg.distMap(*reinterpret_cast<DistMap*>(Base::_dist));

      if (Base::_reached)

        alg.reachedMap(*reinterpret_cast<ReachedMap*>(Base::_reached));

      if (Base::_processed)

        alg.processedMap(*reinterpret_cast<ProcessedMap*>(Base::_processed));

      if (s!=INVALID)

        alg.run(s);

      else

        alg.run();

    }

    ///Finds the shortest path between \c s and \c t.

    ///This method runs BFS algorithm from node \c s

    ///in order to compute the shortest path to node \c t

    ///(it stops searching when \c t is processed).

    ///

    ///\return \c true if \c t is reachable form \c s.

    bool run(Node s, Node t)

    {

      Bfs<Digraph,TR> alg(*reinterpret_cast<const Digraph*>(Base::_g));

      if (Base::_pred)

        alg.predMap(*reinterpret_cast<PredMap*>(Base::_pred));

      if (Base::_dist)

        alg.distMap(*reinterpret_cast<DistMap*>(Base::_dist));

      if (Base::_reached)

        alg.reachedMap(*reinterpret_cast<ReachedMap*>(Base::_reached));

      if (Base::_processed)

        alg.processedMap(*reinterpret_cast<ProcessedMap*>(Base::_processed));

      alg.run(s,t);

      if (Base::_path)

        *reinterpret_cast<Path*>(Base::_path) = alg.path(t);

      if (Base::_di)

        *Base::_di = alg.dist(t);

      return alg.reached(t);

    }

    ///Runs BFS algorithm to visit all nodes in the digraph.

    ///This method runs BFS algorithm in order to compute

    ///the shortest path to each node.

    void run()

    {

      run(INVALID);

    }

    template<class T>

    struct SetPredMapBase : public Base {

      typedef T PredMap;

      static PredMap *createPredMap(const Digraph &) { return 0; };

      SetPredMapBase(const TR &b) : TR(b) {}

    };

    ///\brief \ref named-func-param "Named parameter"

    ///for setting \ref PredMap object.

    ///

    ///\ref named-func-param "Named parameter"

    ///for setting \ref PredMap object.

    template<class T>

    BfsWizard<SetPredMapBase<T> > predMap(const T &t)

    {

      Base::_pred=reinterpret_cast<void*>(const_cast<T*>(&t));

      return BfsWizard<SetPredMapBase<T> >(*this);

    }

    template<class T>

    struct SetReachedMapBase : public Base {

      typedef T ReachedMap;

      static ReachedMap *createReachedMap(const Digraph &) { return 0; };

    /// This function instantiates a \ref ReachedMap.

    /// \param digraph is the digraph, to which

    /// we would like to define the \ref ReachedMap.

    static ReachedMap *createReachedMap(const Digraph &digraph) {

      return new ReachedMap(digraph);

    }

  };

  /// \ingroup search

  ///

  /// \brief %BFS algorithm class with visitor interface.

  ///

  /// This class provides an efficient implementation of the %BFS algorithm

  /// with visitor interface.

  ///

  /// The %BfsVisit class provides an alternative interface to the Bfs

  /// class. It works with callback mechanism, the BfsVisit object calls

  /// the member functions of the \c Visitor class on every BFS event.

  ///

  /// This interface of the BFS algorithm should be used in special cases

  /// when extra actions have to be performed in connection with certain

  /// events of the BFS algorithm. Otherwise consider to use Bfs or bfs()

  /// instead.

  ///

  /// \tparam _Digraph The type of the digraph the algorithm runs on.

  /// The default value is

  /// \ref ListDigraph. The value of _Digraph is not used directly by

  /// \ref BfsVisit, it is only passed to \ref BfsVisitDefaultTraits.

  /// \tparam _Visitor The Visitor type that is used by the algorithm.

  /// \ref BfsVisitor "BfsVisitor<_Digraph>" is an empty visitor, which

  /// does not observe the BFS events. If you want to observe the BFS

  /// events, you should implement your own visitor class.

  /// \tparam _Traits Traits class to set various data types used by the

  /// algorithm. The default traits class is

  /// \ref BfsVisitDefaultTraits "BfsVisitDefaultTraits<_Digraph>".

  /// See \ref BfsVisitDefaultTraits for the documentation of

  /// a BFS visit traits class.

#ifdef DOXYGEN

  template <typename _Digraph, typename _Visitor, typename _Traits>

#else

  template <typename _Digraph = ListDigraph,

            typename _Visitor = BfsVisitor<_Digraph>,

            typename _Traits = BfsDefaultTraits<_Digraph> >

#endif

  class BfsVisit {

  public:

    ///The traits class.

    typedef _Traits Traits;

    ///The type of the digraph the algorithm runs on.

    typedef typename Traits::Digraph Digraph;

    ///The visitor type used by the algorithm.

    typedef _Visitor Visitor;

    ///The type of the map that indicates which nodes are reached.

    typedef typename Traits::ReachedMap ReachedMap;

  private:

    typedef typename Digraph::Node Node;

    typedef typename Digraph::NodeIt NodeIt;

    typedef typename Digraph::Arc Arc;

    typedef typename Digraph::OutArcIt OutArcIt;

    //Pointer to the underlying digraph.

    const Digraph *_digraph;

    //Pointer to the visitor object.

    Visitor *_visitor;

    //Pointer to the map of reached status of the nodes.

    ReachedMap *_reached;

    //Indicates if _reached is locally allocated (true) or not.

    bool local_reached;

    std::vector<typename Digraph::Node> _list;

    int _list_front, _list_back;

    //Creates the maps if necessary.

    void create_maps() {

      if(!_reached) {

        local_reached = true;

        _reached = Traits::createReachedMap(*_digraph);

      }

    }

  protected:

    BfsVisit() {}

  public:

    typedef BfsVisit Create;

    /// \name Named template parameters

    ///@{

    template <class T>

    struct SetReachedMapTraits : public Traits {

      typedef T ReachedMap;

      static ReachedMap *createReachedMap(const Digraph &digraph) {

      }

    };

    /// \brief \ref named-templ-param "Named parameter" for setting

    /// ReachedMap type.

    ///

    /// \ref named-templ-param "Named parameter" for setting ReachedMap type.

    template <class T>

    struct SetReachedMap : public BfsVisit< Digraph, Visitor,

                                            SetReachedMapTraits<T> > {

      typedef BfsVisit< Digraph, Visitor, SetReachedMapTraits<T> > Create;

    };

    ///@}

  public:

    /// \brief Constructor.

    ///

    /// Constructor.

    ///

    /// \param digraph The digraph the algorithm runs on.

    /// \param visitor The visitor object of the algorithm.

    BfsVisit(const Digraph& digraph, Visitor& visitor)

      : _digraph(&digraph), _visitor(&visitor),

        _reached(0), local_reached(false) {}

    /// \brief Destructor.

    ~BfsVisit() {

      if(local_reached) delete _reached;

    }

    /// \brief Sets the map that indicates which nodes are reached.

    ///

    /// Sets the map that indicates which nodes are reached.

    /// If you don't use this function before calling \ref run(),

    /// it will allocate one. The destructor deallocates this

    /// automatically allocated map, of course.

    /// \return <tt> (*this) </tt>

    BfsVisit &reachedMap(ReachedMap &m) {

      if(local_reached) {

        delete _reached;

        local_reached = false;

      }

      _reached = &m;

      return *this;

    }

  public:

      /// Makes the heap empty.

      void clear();

      /// \brief Inserts an item into the heap with the given priority.

      ///

      /// Inserts the given item into the heap with the given priority.

      /// \param i The item to insert.

      /// \param p The priority of the item.

      void push(const Item &i, const Prio &p) {}

      /// \brief Returns the item having minimum priority.

      ///

      /// Returns the item having minimum priority.

      /// \pre The heap must be non-empty.

      Item top() const {}

      /// \brief The minimum priority.

      ///

      /// Returns the minimum priority.

      /// \pre The heap must be non-empty.

      Prio prio() const {}

      /// \brief Removes the item having minimum priority.

      ///

      /// Removes the item having minimum priority.

      /// \pre The heap must be non-empty.

      void pop() {}

      /// \brief Removes an item from the heap.

      ///

      /// Removes the given item from the heap if it is already stored.

      /// \param i The item to delete.

      void erase(const Item &i) {}

      /// \brief The priority of an item.

      ///

      /// Returns the priority of the given item.

      /// \pre \c i must be in the heap.

      /// \param i The item.

      Prio operator[](const Item &i) const {}

      /// \brief Sets the priority of an item or inserts it, if it is

      /// not stored in the heap.

      ///

      /// This method sets the priority of the given item if it is

      /// already stored in the heap.

      /// Otherwise it inserts the given item with the given priority.

      ///

      /// \param i The item.

      /// \param p The priority.

      void set(const Item &i, const Prio &p) {}

      /// \brief Decreases the priority of an item to the given value.

      ///

      /// Decreases the priority of an item to the given value.

      /// \pre \c i must be stored in the heap with priority at least \c p.

      /// \param i The item.

      /// \param p The priority.

      void decrease(const Item &i, const Prio &p) {}

      /// \brief Increases the priority of an item to the given value.

      ///

      /// Increases the priority of an item to the given value.

      /// \pre \c i must be stored in the heap with priority at most \c p.

      /// \param i The item.

      /// \param p The priority.

      void increase(const Item &i, const Prio &p) {}

      /// \brief Returns if an item is in, has already been in, or has

      /// never been in the heap.

      ///

      /// This method returns \c PRE_HEAP if the given item has never

      /// been in the heap, \c IN_HEAP if it is in the heap at the moment,

      /// and \c POST_HEAP otherwise.

      /// In the latter case it is possible that the item will get back

      /// to the heap again.

      /// \param i The item.

      State state(const Item &i) const {}

      /// \brief Sets the state of an item in the heap.

      ///

      /// Sets the state of the given item in the heap. It can be used

      /// to manually clear the heap when it is important to achive the

      /// better time complexity.

      /// \param i The item.

      /// \param st The state. It should not be \c IN_HEAP.

      void state(const Item& i, State st) {}

      template <typename _Heap>

      struct Constraints {

      public:

        void constraints() {

          typedef typename _Heap::Item OwnItem;

          typedef typename _Heap::Prio OwnPrio;

          typedef typename _Heap::State OwnState;

    ///we would like to define the \ref ReachedMap.

    static ReachedMap *createReachedMap(const Digraph &g)

    {

      return new ReachedMap(g);

    }

    ///The type of the map that stores the distances of the nodes.

    ///The type of the map that stores the distances of the nodes.

    ///It must meet the \ref concepts::WriteMap "WriteMap" concept.

    typedef typename Digraph::template NodeMap<int> DistMap;

    ///Instantiates a \ref DistMap.

    ///This function instantiates a \ref DistMap.

    ///\param g is the digraph, to which we would like to define the

    ///\ref DistMap.

    static DistMap *createDistMap(const Digraph &g)

    {

      return new DistMap(g);

    }

  };

  ///%DFS algorithm class.

  ///\ingroup search

  ///This class provides an efficient implementation of the %DFS algorithm.

  ///

  ///There is also a \ref dfs() "function-type interface" for the DFS

  ///algorithm, which is convenient in the simplier cases and it can be

  ///used easier.

  ///

  ///\tparam GR The type of the digraph the algorithm runs on.

  ///The default value is \ref ListDigraph. The value of GR is not used

  ///directly by \ref Dfs, it is only passed to \ref DfsDefaultTraits.

  ///\tparam TR Traits class to set various data types used by the algorithm.

  ///The default traits class is

  ///\ref DfsDefaultTraits "DfsDefaultTraits<GR>".

  ///See \ref DfsDefaultTraits for the documentation of

  ///a Dfs traits class.

#ifdef DOXYGEN

  template <typename GR,

            typename TR>

#else

  template <typename GR=ListDigraph,

            typename TR=DfsDefaultTraits<GR> >

#endif

  class Dfs {

  public:

    ///The type of the digraph the algorithm runs on.

    typedef typename TR::Digraph Digraph;

    ///\brief The type of the map that stores the predecessor arcs of the

    ///DFS paths.

    typedef typename TR::PredMap PredMap;

    ///The type of the map that stores the distances of the nodes.

    typedef typename TR::DistMap DistMap;

    ///The type of the map that indicates which nodes are reached.

    typedef typename TR::ReachedMap ReachedMap;

    ///The type of the map that indicates which nodes are processed.

    typedef typename TR::ProcessedMap ProcessedMap;

    ///The type of the paths.

    typedef PredMapPath<Digraph, PredMap> Path;

    ///The traits class.

    typedef TR Traits;

  private:

    typedef typename Digraph::Node Node;

    typedef typename Digraph::NodeIt NodeIt;

    typedef typename Digraph::Arc Arc;

    typedef typename Digraph::OutArcIt OutArcIt;

    //Pointer to the underlying digraph.

    const Digraph *G;

    //Pointer to the map of predecessor arcs.

    PredMap *_pred;

    //Indicates if _pred is locally allocated (true) or not.

    bool local_pred;

    //Pointer to the map of distances.

    DistMap *_dist;

    //Indicates if _dist is locally allocated (true) or not.

    bool local_dist;

    //Pointer to the map of reached status of the nodes.

    ReachedMap *_reached;

    //Indicates if _reached is locally allocated (true) or not.

    bool local_reached;

    //Pointer to the map of processed status of the nodes.

    ProcessedMap *_processed;

    //Indicates if _processed is locally allocated (true) or not.

    bool local_processed;

    std::vector<typename Digraph::OutArcIt> _stack;

    int _stack_head;

    //Creates the maps if necessary.

    void create_maps()

    {

      if(!_pred) {

        local_pred = true;

        _pred = Traits::createPredMap(*G);

      }

      if(!_dist) {

        local_dist = true;

        _dist = Traits::createDistMap(*G);

      }

      if(!_reached) {

        local_reached = true;

        _reached = Traits::createReachedMap(*G);

      }

      if(!_processed) {

        local_processed = true;

        _processed = Traits::createProcessedMap(*G);

      }

    }

  protected:

    Dfs() {}

  public:

    typedef Dfs Create;

    ///\name Named template parameters

    ///@{

    template <class T>

    struct SetPredMapTraits : public Traits {

      typedef T PredMap;

      static PredMap *createPredMap(const Digraph &)

      {

      }

    };

    ///\brief \ref named-templ-param "Named parameter" for setting

    ///\ref PredMap type.

    ///

    ///\ref named-templ-param "Named parameter" for setting

    ///\ref PredMap type.

    template <class T>

    struct SetPredMap : public Dfs<Digraph, SetPredMapTraits<T> > {

      typedef Dfs<Digraph, SetPredMapTraits<T> > Create;

    };

    template <class T>

    struct SetDistMapTraits : public Traits {

      typedef T DistMap;

      static DistMap *createDistMap(const Digraph &)

      {

      }

    };

    ///\brief \ref named-templ-param "Named parameter" for setting

    ///\ref DistMap type.

    ///

    ///\ref named-templ-param "Named parameter" for setting

    ///\ref DistMap type.

    template <class T>

    struct SetDistMap : public Dfs< Digraph, SetDistMapTraits<T> > {

      typedef Dfs<Digraph, SetDistMapTraits<T> > Create;

    };