lemon-0.x: comparison src/work/klao/path.h

equal deleted inserted replaced

-:56cb8321e311
+:4f5027e89a22
 // -*- c++ -*- //
-///\ingroup datas
+/**
+@defgroup paths Path Structures
+@ingroup datas
+\brief Path structures implemented in Hugo.
+Hugolib provides flexible data structures
+to work with paths.
+All of them have the same interface, especially they can be built or extended
+using a standard Builder subclass. This make is easy to have e.g. the Dijkstra
+algorithm to store its result in any kind of path structure.
+*/
+///\ingroup paths
 ///\file
 ///\brief Classes for representing paths in graphs.
 #ifndef HUGO_PATH_H
 #define HUGO_PATH_H
 #include <hugo/error.h>
 #include <debug.h>
 namespace hugo {
-/// \addtogroup datas
+/// \addtogroup paths
 /// @{
 //! \brief A structure for representing directed path in a graph.
 //!
 //!
 //! \todo Thoroughfully check all the range and consistency tests.
 template<typename Graph, typename DM = DefaultDebugMode>
 class DirPath {
 public:
-typedef typename Graph::Edge GraphEdge;
+/// Edge type of the underlying graph.
+typedef typename Graph::Edge GraphEdge;
+/// Node type of the underlying graph.
 typedef typename Graph::Node GraphNode;
 class NodeIt;
 class EdgeIt;
 protected:
 	fault("DirPath::tail() on invalid iterator");
 return NodeIt(*this, e.idx);
 }
-/*** Iterator classes ***/
+/* Iterator classes */
+/**
+* \brief Iterator class to iterate on the edges of the paths
+*
+* \ingroup paths
+* This class is used to iterate on the edges of the paths
+*
+* Of course it converts to Graph::Edge
+*
+* \todo Its interface differs from the standard edge iterator.
+* Yes, it shouldn't.
+*/
 class EdgeIt {
 friend class DirPath;
 int idx;
 const DirPath *p;
 public:
+/// Default constructor
 EdgeIt() {}
+/// Invalid constructor
 EdgeIt(Invalid) : idx(-1), p(0) {}
+/// Constructor with starting point
 EdgeIt(const DirPath &_p, int _idx = 0) :
 	idx(_idx), p(&_p) { validate(); }
+///Validity check
 bool valid() const { return idx!=-1; }
+///Conversion to Graph::Edge
 operator GraphEdge () const {
 	return valid() ? p->edges[idx] : INVALID;
 }
+/// Next edge
 EdgeIt& operator++() { ++idx; validate(); return *this; }
+/// Comparison operator
 bool operator==(const EdgeIt& e) const { return idx==e.idx; }
+/// Comparison operator
 bool operator!=(const EdgeIt& e) const { return idx!=e.idx; }
+/// Comparison operator
 bool operator<(const EdgeIt& e) const { return idx<e.idx; }
 private:
 // FIXME: comparison between signed and unsigned...
 // Jo ez igy? Vagy esetleg legyen a length() int?
 void validate() { if( size_t(idx) >= p->length() ) idx=-1; }
 };
+/**
+* \brief Iterator class to iterate on the nodes of the paths
+*
+* \ingroup paths
+* This class is used to iterate on the nodes of the paths
+*
+* Of course it converts to Graph::Node
+*
+* \todo Its interface differs from the standard node iterator.
+* Yes, it shouldn't.
+*/
 class NodeIt {
 friend class DirPath;
 int idx;
 const DirPath *p;
 public:
+/// Default constructor
 NodeIt() {}
+/// Invalid constructor
 NodeIt(Invalid) : idx(-1), p(0) {}
+/// Constructor with starting point
 NodeIt(const DirPath &_p, int _idx = 0) :
 	idx(_idx), p(&_p) { validate(); }
+///Validity check
 bool valid() const { return idx!=-1; }
+///Conversion to Graph::Node
 operator const GraphNode& () const {
 	if(idx >= p->length())
 	  return p->to();
 	else if(idx >= 0)
 	  return p->gr->tail(p->edges[idx]);
 	else
 	  return INVALID;
 }
+/// Next node
 NodeIt& operator++() { ++idx; validate(); return *this; }
+/// Comparison operator
 bool operator==(const NodeIt& e) const { return idx==e.idx; }
+/// Comparison operator
 bool operator!=(const NodeIt& e) const { return idx!=e.idx; }
+/// Comparison operator
 bool operator<(const NodeIt& e) const { return idx<e.idx; }
 private:
 void validate() { if( size_t(idx) > p->length() ) idx=-1; }
 };
 friend class Builder;
 /**
 * \brief Class to build paths
 *
-* \ingroup datas
+* \ingroup paths
 * This class is used to fill a path with edges.
 *
 * You can push new edges to the front and to the back of the path in
 * arbitrary order then you should commit these changes to the graph.
 *
 	}
 }
 // FIXME: Hmm, pontosan hogy is kene ezt csinalni?
 // Hogy kenyelmes egy ilyet hasznalni?
+///Reserve storage in advance for the builder
+///If you know an reasonable upper bound of the number of the edges
+///to add, using this function you can speed up the building.
 void reserve(size_t r) {
 	front.reserve(r);
 	back.reserve(r);
 }
 //!
 //! \todo Thoroughfully check all the range and consistency tests.
 template<typename Graph, typename DM = DefaultDebugMode>
 class UndirPath {
 public:
+/// Edge type of the underlying graph.
 typedef typename Graph::Edge GraphEdge;
-typedef typename Graph::Node GraphNode;
+/// Node type of the underlying graph.
+typedef typename Graph::Node GraphNode;
 class NodeIt;
 class EdgeIt;
 protected:
 const Graph *gr;
 	fault("UndirPath::tail() on invalid iterator");
 return NodeIt(*this, e.idx);
 }
-/*** Iterator classes ***/
+/**
+* \brief Iterator class to iterate on the edges of the paths
+*
+* \ingroup paths
+* This class is used to iterate on the edges of the paths
+*
+* Of course it converts to Graph::Edge
+*
+* \todo Its interface differs from the standard edge iterator.
+* Yes, it shouldn't.
+*/
 class EdgeIt {
 friend class UndirPath;
 int idx;
 const UndirPath *p;
 public:
+/// Default constructor
 EdgeIt() {}
+/// Invalid constructor
 EdgeIt(Invalid) : idx(-1), p(0) {}
+/// Constructor with starting point
 EdgeIt(const UndirPath &_p, int _idx = 0) :
 	idx(_idx), p(&_p) { validate(); }
+///Validity check
 bool valid() const { return idx!=-1; }
+///Conversion to Graph::Edge
 operator GraphEdge () const {
 	return valid() ? p->edges[idx] : INVALID;
 }
-EdgeIt& operator++() { ++idx; validate(); return *this; }
+/// Next edge
+EdgeIt& operator++() { ++idx; validate(); return *this; }
+/// Comparison operator
 bool operator==(const EdgeIt& e) const { return idx==e.idx; }
+/// Comparison operator
 bool operator!=(const EdgeIt& e) const { return idx!=e.idx; }
+/// Comparison operator
 bool operator<(const EdgeIt& e) const { return idx<e.idx; }
 private:
 // FIXME: comparison between signed and unsigned...
 // Jo ez igy? Vagy esetleg legyen a length() int?
 void validate() { if( size_t(idx) >= p->length() ) idx=-1; }
 };
+/**
+* \brief Iterator class to iterate on the nodes of the paths
+*
+* \ingroup paths
+* This class is used to iterate on the nodes of the paths
+*
+* Of course it converts to Graph::Node
+*
+* \todo Its interface differs from the standard node iterator.
+* Yes, it shouldn't.
+*/
 class NodeIt {
 friend class UndirPath;
 int idx;
 const UndirPath *p;
 public:
+/// Default constructor
 NodeIt() {}
+/// Invalid constructor
 NodeIt(Invalid) : idx(-1), p(0) {}
+/// Constructor with starting point
 NodeIt(const UndirPath &_p, int _idx = 0) :
 	idx(_idx), p(&_p) { validate(); }
+///Validity check
 bool valid() const { return idx!=-1; }
+///Conversion to Graph::Node
 operator const GraphNode& () const {
 	if(idx >= p->length())
 	  return p->to();
 	else if(idx >= 0)
 	  return p->gr->tail(p->edges[idx]);
 	else
 	  return INVALID;
 }
+/// Next node
 NodeIt& operator++() { ++idx; validate(); return *this; }
+/// Comparison operator
 bool operator==(const NodeIt& e) const { return idx==e.idx; }
+/// Comparison operator
 bool operator!=(const NodeIt& e) const { return idx!=e.idx; }
-bool operator<(const NodeIt& e) const { return idx<e.idx; }
+/// Comparison operator
+bool operator<(const NodeIt& e) const { return idx<e.idx; }
 private:
 void validate() { if( size_t(idx) > p->length() ) idx=-1; }
 };
 friend class Builder;
 /**
 * \brief Class to build paths
 *
-* \ingroup datas
+* \ingroup paths
 * This class is used to fill a path with edges.
 *
 * You can push new edges to the front and to the back of the path in
 * arbitrary order then you should commit these changes to the graph.
 *
 	}
 }
 // FIXME: Hmm, pontosan hogy is kene ezt csinalni?
 // Hogy kenyelmes egy ilyet hasznalni?
-void reserve(size_t r) {
+///Reserve storage in advance for the builder
+///If you know an reasonable upper bound of the number of the edges
+///to add, using this function you can speed up the building.
+void reserve(size_t r) {
 	front.reserve(r);
 	back.reserve(r);
 }
 private:

changeset 739	3bb5553ec41b
parent 683	3cbf51510180
child 803	c3d832275e69