Branch from path.h to extend its documentation.
4 @defgroup paths Path Structures
6 \brief Path structures implemented in Hugo.
8 Hugolib provides flexible data structures
11 All of them have the same interface, especially they can be built or extended
12 using a standard Builder subclass. This make is easy to have e.g. the Dijkstra
13 algorithm to store its result in any kind of path structure.
19 ///\brief Classes for representing paths in graphs.
28 #include <hugo/invalid.h>
29 #include <hugo/error.h>
38 //! \brief A structure for representing directed path in a graph.
40 //! A structure for representing directed path in a graph.
41 //! \param Graph The graph type in which the path is.
42 //! \param DM DebugMode, defaults to DefaultDebugMode.
44 //! In a sense, the path can be treated as a graph, for is has \c NodeIt
45 //! and \c EdgeIt with the same usage. These types converts to the \c Node
46 //! and \c Edge of the original graph.
48 //! \todo Thoroughfully check all the range and consistency tests.
49 template<typename Graph, typename DM = DefaultDebugMode>
52 /// Edge type of the underlying graph.
53 typedef typename Graph::Edge GraphEdge;
54 /// Node type of the underlying graph.
55 typedef typename Graph::Node GraphNode;
61 typedef std::vector<GraphEdge> Container;
66 /// \param _G The graph in which the path is.
68 DirPath(const Graph &_G) : gr(&_G) {}
70 /// \brief Subpath constructor.
72 /// Subpath defined by two nodes.
73 /// \warning It is an error if the two edges are not in order!
74 DirPath(const DirPath &P, const NodeIt &a, const NodeIt &b) {
75 if( DM::range_check && (!a.valid() || !b.valid) ) {
76 // FIXME: this check should be more elaborate...
77 fault("DirPath, subpath ctor: invalid bounding nodes");
80 edges.insert(edges.end(), P.edges.begin()+a.idx, P.edges.begin()+b.idx);
83 /// \brief Subpath constructor.
85 /// Subpath defined by two edges. Contains edges in [a,b)
86 /// \warning It is an error if the two edges are not in order!
87 DirPath(const DirPath &P, const EdgeIt &a, const EdgeIt &b) {
88 if( DM::range_check && (!a.valid() || !b.valid) ) {
89 // FIXME: this check should be more elaborate...
90 fault("DirPath, subpath ctor: invalid bounding nodes");
93 edges.insert(edges.end(), P.edges.begin()+a.idx, P.edges.begin()+b.idx);
96 /// Length of the path.
97 size_t length() const { return edges.size(); }
98 /// Returns whether the path is empty.
99 bool empty() const { return edges.empty(); }
101 /// Resets the path to an empty path.
102 void clear() { edges.clear(); }
104 /// \brief Starting point of the path.
106 /// Starting point of the path.
107 /// Returns INVALID if the path is empty.
108 GraphNode from() const {
109 return empty() ? INVALID : gr->tail(edges[0]);
111 /// \brief End point of the path.
113 /// End point of the path.
114 /// Returns INVALID if the path is empty.
115 GraphNode to() const {
116 return empty() ? INVALID : gr->head(edges[length()-1]);
119 /// \brief Initializes node or edge iterator to point to the first
123 template<typename It>
124 It& first(It &i) const { return i=It(*this); }
126 /// \brief Initializes node iterator to point to the node of a given index.
127 NodeIt& nth(NodeIt &i, int n) const {
128 if( DM::range_check && (n<0 || n>int(length())) )
129 fault("DirPath::nth: index out of range");
130 return i=NodeIt(*this, n);
133 /// \brief Initializes edge iterator to point to the edge of a given index.
134 EdgeIt& nth(EdgeIt &i, int n) const {
135 if( DM::range_check && (n<0 || n>=int(length())) )
136 fault("DirPath::nth: index out of range");
137 return i=EdgeIt(*this, n);
140 /// Checks validity of a node or edge iterator.
141 template<typename It>
143 bool valid(const It &i) { return i.valid(); }
145 /// Steps the given node or edge iterator.
146 template<typename It>
149 if( DM::range_check && !e.valid() )
150 fault("DirPath::next() on invalid iterator");
154 /// \brief Returns node iterator pointing to the head node of the
155 /// given edge iterator.
156 NodeIt head(const EdgeIt& e) const {
157 if( DM::range_check && !e.valid() )
158 fault("DirPath::head() on invalid iterator");
159 return NodeIt(*this, e.idx+1);
162 /// \brief Returns node iterator pointing to the tail node of the
163 /// given edge iterator.
164 NodeIt tail(const EdgeIt& e) const {
165 if( DM::range_check && !e.valid() )
166 fault("DirPath::tail() on invalid iterator");
167 return NodeIt(*this, e.idx);
171 /* Iterator classes */
174 * \brief Iterator class to iterate on the edges of the paths
177 * This class is used to iterate on the edges of the paths
179 * Of course it converts to Graph::Edge
181 * \todo Its interface differs from the standard edge iterator.
185 friend class DirPath;
190 /// Default constructor
192 /// Invalid constructor
193 EdgeIt(Invalid) : idx(-1), p(0) {}
194 /// Constructor with starting point
195 EdgeIt(const DirPath &_p, int _idx = 0) :
196 idx(_idx), p(&_p) { validate(); }
199 bool valid() const { return idx!=-1; }
201 ///Conversion to Graph::Edge
202 operator GraphEdge () const {
203 return valid() ? p->edges[idx] : INVALID;
207 EdgeIt& operator++() { ++idx; validate(); return *this; }
209 /// Comparison operator
210 bool operator==(const EdgeIt& e) const { return idx==e.idx; }
211 /// Comparison operator
212 bool operator!=(const EdgeIt& e) const { return idx!=e.idx; }
213 /// Comparison operator
214 bool operator<(const EdgeIt& e) const { return idx<e.idx; }
217 // FIXME: comparison between signed and unsigned...
218 // Jo ez igy? Vagy esetleg legyen a length() int?
219 void validate() { if( size_t(idx) >= p->length() ) idx=-1; }
223 * \brief Iterator class to iterate on the nodes of the paths
226 * This class is used to iterate on the nodes of the paths
228 * Of course it converts to Graph::Node
230 * \todo Its interface differs from the standard node iterator.
234 friend class DirPath;
239 /// Default constructor
241 /// Invalid constructor
242 NodeIt(Invalid) : idx(-1), p(0) {}
243 /// Constructor with starting point
244 NodeIt(const DirPath &_p, int _idx = 0) :
245 idx(_idx), p(&_p) { validate(); }
248 bool valid() const { return idx!=-1; }
250 ///Conversion to Graph::Node
251 operator const GraphNode& () const {
252 if(idx >= p->length())
255 return p->gr->tail(p->edges[idx]);
260 NodeIt& operator++() { ++idx; validate(); return *this; }
262 /// Comparison operator
263 bool operator==(const NodeIt& e) const { return idx==e.idx; }
264 /// Comparison operator
265 bool operator!=(const NodeIt& e) const { return idx!=e.idx; }
266 /// Comparison operator
267 bool operator<(const NodeIt& e) const { return idx<e.idx; }
270 void validate() { if( size_t(idx) > p->length() ) idx=-1; }
273 friend class Builder;
276 * \brief Class to build paths
279 * This class is used to fill a path with edges.
281 * You can push new edges to the front and to the back of the path in
282 * arbitrary order then you should commit these changes to the graph.
284 * Fundamentally, for most "Paths" (classes fulfilling the
285 * PathConcept) while the builder is active (after the first modifying
286 * operation and until the commit()) the original Path is in a
287 * "transitional" state (operations on it have undefined result). But
288 * in the case of DirPath the original path remains unchanged until the
289 * commit. However we don't recomend that you use this feature.
293 Container front, back;
296 ///\param _P the path you want to fill in.
298 Builder(DirPath &_P) : P(_P) {}
300 /// Sets the starting node of the path.
302 /// Sets the starting node of the path. Edge added to the path
303 /// afterwards have to be incident to this node.
304 /// It should be called iff the path is empty and before any call to
305 /// \ref pushFront() or \ref pushBack()
306 void setStart(const GraphNode &) {}
308 ///Push a new edge to the front of the path
310 ///Push a new edge to the front of the path.
312 void pushFront(const GraphEdge& e) {
313 if( DM::consistensy_check && !empty() && P.gr->head(e)!=from() ) {
314 fault("DirPath::Builder::pushFront: nonincident edge");
319 ///Push a new edge to the back of the path
321 ///Push a new edge to the back of the path.
323 void pushBack(const GraphEdge& e) {
324 if( DM::consistensy_check && !empty() && P.gr->tail(e)!=to() ) {
325 fault("DirPath::Builder::pushBack: nonincident edge");
330 ///Commit the changes to the path.
332 if( !(front.empty() && back.empty()) ) {
334 tmp.reserve(front.size()+back.size()+P.length());
335 tmp.insert(tmp.end(), front.rbegin(), front.rend());
336 tmp.insert(tmp.end(), P.edges.begin(), P.edges.end());
337 tmp.insert(tmp.end(), back.begin(), back.end());
344 // FIXME: Hmm, pontosan hogy is kene ezt csinalni?
345 // Hogy kenyelmes egy ilyet hasznalni?
347 ///Reserve storage in advance for the builder
349 ///If you know an reasonable upper bound of the number of the edges
350 ///to add, using this function you can speed up the building.
351 void reserve(size_t r) {
358 return front.empty() && back.empty() && P.empty();
361 GraphNode from() const {
362 if( ! front.empty() )
363 return P.gr->tail(front[front.size()-1]);
364 else if( ! P.empty() )
365 return P.gr->tail(P.edges[0]);
366 else if( ! back.empty() )
367 return P.gr->tail(back[0]);
371 GraphNode to() const {
373 return P.gr->head(back[back.size()-1]);
374 else if( ! P.empty() )
375 return P.gr->head(P.edges[P.length()-1]);
376 else if( ! front.empty() )
377 return P.gr->head(front[0]);
391 /**********************************************************************/
394 //! \brief A structure for representing undirected path in a graph.
396 //! A structure for representing undirected path in a graph. Ie. this is
397 //! a path in a \e directed graph but the edges should not be directed
400 //! \param Graph The graph type in which the path is.
401 //! \param DM DebugMode, defaults to DefaultDebugMode.
403 //! In a sense, the path can be treated as a graph, for is has \c NodeIt
404 //! and \c EdgeIt with the same usage. These types converts to the \c Node
405 //! and \c Edge of the original graph.
407 //! \todo Thoroughfully check all the range and consistency tests.
408 template<typename Graph, typename DM = DefaultDebugMode>
411 /// Edge type of the underlying graph.
412 typedef typename Graph::Edge GraphEdge;
413 /// Node type of the underlying graph.
414 typedef typename Graph::Node GraphNode;
420 typedef std::vector<GraphEdge> Container;
425 /// \param _G The graph in which the path is.
427 UndirPath(const Graph &_G) : gr(&_G) {}
429 /// \brief Subpath constructor.
431 /// Subpath defined by two nodes.
432 /// \warning It is an error if the two edges are not in order!
433 UndirPath(const UndirPath &P, const NodeIt &a, const NodeIt &b) {
434 if( DM::range_check && (!a.valid() || !b.valid) ) {
435 // FIXME: this check should be more elaborate...
436 fault("UndirPath, subpath ctor: invalid bounding nodes");
439 edges.insert(edges.end(), P.edges.begin()+a.idx, P.edges.begin()+b.idx);
442 /// \brief Subpath constructor.
444 /// Subpath defined by two edges. Contains edges in [a,b)
445 /// \warning It is an error if the two edges are not in order!
446 UndirPath(const UndirPath &P, const EdgeIt &a, const EdgeIt &b) {
447 if( DM::range_check && (!a.valid() || !b.valid) ) {
448 // FIXME: this check should be more elaborate...
449 fault("UndirPath, subpath ctor: invalid bounding nodes");
452 edges.insert(edges.end(), P.edges.begin()+a.idx, P.edges.begin()+b.idx);
455 /// Length of the path.
456 size_t length() const { return edges.size(); }
457 /// Returns whether the path is empty.
458 bool empty() const { return edges.empty(); }
460 /// Resets the path to an empty path.
461 void clear() { edges.clear(); }
463 /// \brief Starting point of the path.
465 /// Starting point of the path.
466 /// Returns INVALID if the path is empty.
467 GraphNode from() const {
468 return empty() ? INVALID : gr->tail(edges[0]);
470 /// \brief End point of the path.
472 /// End point of the path.
473 /// Returns INVALID if the path is empty.
474 GraphNode to() const {
475 return empty() ? INVALID : gr->head(edges[length()-1]);
478 /// \brief Initializes node or edge iterator to point to the first
482 template<typename It>
483 It& first(It &i) const { return i=It(*this); }
485 /// \brief Initializes node iterator to point to the node of a given index.
486 NodeIt& nth(NodeIt &i, int n) const {
487 if( DM::range_check && (n<0 || n>int(length())) )
488 fault("UndirPath::nth: index out of range");
489 return i=NodeIt(*this, n);
492 /// \brief Initializes edge iterator to point to the edge of a given index.
493 EdgeIt& nth(EdgeIt &i, int n) const {
494 if( DM::range_check && (n<0 || n>=int(length())) )
495 fault("UndirPath::nth: index out of range");
496 return i=EdgeIt(*this, n);
499 /// Checks validity of a node or edge iterator.
500 template<typename It>
502 bool valid(const It &i) { return i.valid(); }
504 /// Steps the given node or edge iterator.
505 template<typename It>
508 if( DM::range_check && !e.valid() )
509 fault("UndirPath::next() on invalid iterator");
513 /// \brief Returns node iterator pointing to the head node of the
514 /// given edge iterator.
515 NodeIt head(const EdgeIt& e) const {
516 if( DM::range_check && !e.valid() )
517 fault("UndirPath::head() on invalid iterator");
518 return NodeIt(*this, e.idx+1);
521 /// \brief Returns node iterator pointing to the tail node of the
522 /// given edge iterator.
523 NodeIt tail(const EdgeIt& e) const {
524 if( DM::range_check && !e.valid() )
525 fault("UndirPath::tail() on invalid iterator");
526 return NodeIt(*this, e.idx);
532 * \brief Iterator class to iterate on the edges of the paths
535 * This class is used to iterate on the edges of the paths
537 * Of course it converts to Graph::Edge
539 * \todo Its interface differs from the standard edge iterator.
543 friend class UndirPath;
548 /// Default constructor
550 /// Invalid constructor
551 EdgeIt(Invalid) : idx(-1), p(0) {}
552 /// Constructor with starting point
553 EdgeIt(const UndirPath &_p, int _idx = 0) :
554 idx(_idx), p(&_p) { validate(); }
557 bool valid() const { return idx!=-1; }
559 ///Conversion to Graph::Edge
560 operator GraphEdge () const {
561 return valid() ? p->edges[idx] : INVALID;
564 EdgeIt& operator++() { ++idx; validate(); return *this; }
566 /// Comparison operator
567 bool operator==(const EdgeIt& e) const { return idx==e.idx; }
568 /// Comparison operator
569 bool operator!=(const EdgeIt& e) const { return idx!=e.idx; }
570 /// Comparison operator
571 bool operator<(const EdgeIt& e) const { return idx<e.idx; }
574 // FIXME: comparison between signed and unsigned...
575 // Jo ez igy? Vagy esetleg legyen a length() int?
576 void validate() { if( size_t(idx) >= p->length() ) idx=-1; }
580 * \brief Iterator class to iterate on the nodes of the paths
583 * This class is used to iterate on the nodes of the paths
585 * Of course it converts to Graph::Node
587 * \todo Its interface differs from the standard node iterator.
591 friend class UndirPath;
596 /// Default constructor
598 /// Invalid constructor
599 NodeIt(Invalid) : idx(-1), p(0) {}
600 /// Constructor with starting point
601 NodeIt(const UndirPath &_p, int _idx = 0) :
602 idx(_idx), p(&_p) { validate(); }
605 bool valid() const { return idx!=-1; }
607 ///Conversion to Graph::Node
608 operator const GraphNode& () const {
609 if(idx >= p->length())
612 return p->gr->tail(p->edges[idx]);
617 NodeIt& operator++() { ++idx; validate(); return *this; }
619 /// Comparison operator
620 bool operator==(const NodeIt& e) const { return idx==e.idx; }
621 /// Comparison operator
622 bool operator!=(const NodeIt& e) const { return idx!=e.idx; }
623 /// Comparison operator
624 bool operator<(const NodeIt& e) const { return idx<e.idx; }
627 void validate() { if( size_t(idx) > p->length() ) idx=-1; }
630 friend class Builder;
633 * \brief Class to build paths
636 * This class is used to fill a path with edges.
638 * You can push new edges to the front and to the back of the path in
639 * arbitrary order then you should commit these changes to the graph.
641 * Fundamentally, for most "Paths" (classes fulfilling the
642 * PathConcept) while the builder is active (after the first modifying
643 * operation and until the commit()) the original Path is in a
644 * "transitional" state (operations ot it have undefined result). But
645 * in the case of UndirPath the original path is unchanged until the
646 * commit. However we don't recomend that you use this feature.
650 Container front, back;
653 ///\param _P the path you want to fill in.
655 Builder(UndirPath &_P) : P(_P) {}
657 /// Sets the starting node of the path.
659 /// Sets the starting node of the path. Edge added to the path
660 /// afterwards have to be incident to this node.
661 /// It should be called iff the path is empty and before any call to
662 /// \ref pushFront() or \ref pushBack()
663 void setStart(const GraphNode &) {}
665 ///Push a new edge to the front of the path
667 ///Push a new edge to the front of the path.
669 void pushFront(const GraphEdge& e) {
670 if( DM::consistensy_check && !empty() && P.gr->head(e)!=from() ) {
671 fault("UndirPath::Builder::pushFront: nonincident edge");
676 ///Push a new edge to the back of the path
678 ///Push a new edge to the back of the path.
680 void pushBack(const GraphEdge& e) {
681 if( DM::consistensy_check && !empty() && P.gr->tail(e)!=to() ) {
682 fault("UndirPath::Builder::pushBack: nonincident edge");
687 ///Commit the changes to the path.
689 if( !(front.empty() && back.empty()) ) {
691 tmp.reserve(front.size()+back.size()+P.length());
692 tmp.insert(tmp.end(), front.rbegin(), front.rend());
693 tmp.insert(tmp.end(), P.edges.begin(), P.edges.end());
694 tmp.insert(tmp.end(), back.begin(), back.end());
701 // FIXME: Hmm, pontosan hogy is kene ezt csinalni?
702 // Hogy kenyelmes egy ilyet hasznalni?
704 ///Reserve storage in advance for the builder
706 ///If you know an reasonable upper bound of the number of the edges
707 ///to add, using this function you can speed up the building.
708 void reserve(size_t r) {
715 return front.empty() && back.empty() && P.empty();
718 GraphNode from() const {
719 if( ! front.empty() )
720 return P.gr->tail(front[front.size()-1]);
721 else if( ! P.empty() )
722 return P.gr->tail(P.edges[0]);
723 else if( ! back.empty() )
724 return P.gr->tail(back[0]);
728 GraphNode to() const {
730 return P.gr->head(back[back.size()-1]);
731 else if( ! P.empty() )
732 return P.gr->head(P.edges[P.length()-1]);
733 else if( ! front.empty() )
734 return P.gr->head(front[0]);
748 #endif // HUGO_PATH_H