diff --git a/lemon/concepts/graph.h b/lemon/concepts/graph.h --- a/lemon/concepts/graph.h +++ b/lemon/concepts/graph.h @@ -18,12 +18,14 @@ ///\ingroup graph_concepts ///\file -///\brief The concept of Undirected Graphs. +///\brief The concept of undirected graphs. #ifndef LEMON_CONCEPTS_GRAPH_H #define LEMON_CONCEPTS_GRAPH_H #include +#include +#include #include namespace lemon { @@ -31,63 +33,74 @@ /// \ingroup graph_concepts /// - /// \brief Class describing the concept of Undirected Graphs. + /// \brief Class describing the concept of undirected graphs. /// - /// This class describes the common interface of all Undirected - /// Graphs. + /// This class describes the common interface of all undirected + /// graphs. /// - /// As all concept describing classes it provides only interface - /// without any sensible implementation. So any algorithm for - /// undirected graph should compile with this class, but it will not + /// Like all concept classes, it only provides an interface + /// without any sensible implementation. So any general algorithm for + /// undirected graphs should compile with this class, but it will not /// run properly, of course. + /// An actual graph implementation like \ref ListGraph or + /// \ref SmartGraph may have additional functionality. /// - /// The LEMON undirected graphs also fulfill the concept of - /// directed graphs (\ref lemon::concepts::Digraph "Digraph - /// Concept"). Each edges can be seen as two opposite - /// directed arc and consequently the undirected graph can be - /// seen as the direceted graph of these directed arcs. The - /// Graph has the Edge inner class for the edges and - /// the Arc type for the directed arcs. The Arc type is - /// convertible to Edge or inherited from it so from a directed - /// arc we can get the represented edge. + /// The undirected graphs also fulfill the concept of \ref Digraph + /// "directed graphs", since each edge can also be regarded as two + /// oppositely directed arcs. + /// Undirected graphs provide an Edge type for the undirected edges and + /// an Arc type for the directed arcs. The Arc type is convertible to + /// Edge or inherited from it, i.e. the corresponding edge can be + /// obtained from an arc. + /// EdgeIt and EdgeMap classes can be used for the edges, while ArcIt + /// and ArcMap classes can be used for the arcs (just like in digraphs). + /// Both InArcIt and OutArcIt iterates on the same edges but with + /// opposite direction. IncEdgeIt also iterates on the same edges + /// as OutArcIt and InArcIt, but it is not convertible to Arc, + /// only to Edge. /// - /// In the sense of the LEMON each edge has a default - /// direction (it should be in every computer implementation, - /// because the order of edge's nodes defines an - /// orientation). With the default orientation we can define that - /// the directed arc is forward or backward directed. With the \c - /// direction() and \c direct() function we can get the direction - /// of the directed arc and we can direct an edge. + /// In LEMON, each undirected edge has an inherent orientation. + /// Thus it can defined if an arc is forward or backward oriented in + /// an undirected graph with respect to this default oriantation of + /// the represented edge. + /// With the direction() and direct() functions the direction + /// of an arc can be obtained and set, respectively. /// - /// The EdgeIt is an iterator for the edges. We can use - /// the EdgeMap to map values for the edges. The InArcIt and - /// OutArcIt iterates on the same edges but with opposite - /// direction. The IncEdgeIt iterates also on the same edges - /// as the OutArcIt and InArcIt but it is not convertible to Arc just - /// to Edge. + /// Only nodes and edges can be added to or removed from an undirected + /// graph and the corresponding arcs are added or removed automatically. + /// + /// \sa Digraph class Graph { + private: + /// Graphs are \e not copy constructible. Use DigraphCopy instead. + Graph(const Graph&) {} + /// \brief Assignment of a graph to another one is \e not allowed. + /// Use DigraphCopy instead. + void operator=(const Graph&) {} + public: - /// \brief The undirected graph should be tagged by the - /// UndirectedTag. + /// Default constructor. + Graph() {} + + /// \brief Undirected graphs should be tagged with \c UndirectedTag. /// - /// The undirected graph should be tagged by the UndirectedTag. This - /// tag helps the enable_if technics to make compile time + /// Undirected graphs should be tagged with \c UndirectedTag. + /// + /// This tag helps the \c enable_if technics to make compile time /// specializations for undirected graphs. typedef True UndirectedTag; - /// \brief The base type of node iterators, - /// or in other words, the trivial node iterator. - /// - /// This is the base type of each node iterator, - /// thus each kind of node iterator converts to this. - /// More precisely each kind of node iterator should be inherited - /// from the trivial node iterator. + /// The node type of the graph + + /// This class identifies a node of the graph. It also serves + /// as a base class of the node iterators, + /// thus they convert to this type. class Node { public: /// Default constructor - /// @warning The default constructor sets the iterator - /// to an undefined value. + /// Default constructor. + /// \warning It sets the object to an undefined value. Node() { } /// Copy constructor. @@ -95,40 +108,40 @@ /// Node(const Node&) { } - /// Invalid constructor \& conversion. + /// %Invalid constructor \& conversion. - /// This constructor initializes the iterator to be invalid. + /// Initializes the object to be invalid. /// \sa Invalid for more details. Node(Invalid) { } /// Equality operator + /// Equality operator. + /// /// Two iterators are equal if and only if they point to the - /// same object or both are invalid. + /// same object or both are \c INVALID. bool operator==(Node) const { return true; } /// Inequality operator - /// \sa operator==(Node n) - /// + /// Inequality operator. bool operator!=(Node) const { return true; } /// Artificial ordering operator. - /// To allow the use of graph descriptors as key type in std::map or - /// similar associative container we require this. + /// Artificial ordering operator. /// - /// \note This operator only have to define some strict ordering of + /// \note This operator only has to define some strict ordering of /// the items; this order has nothing to do with the iteration /// ordering of the items. bool operator<(Node) const { return false; } }; - /// This iterator goes through each node. + /// Iterator class for the nodes. - /// This iterator goes through each node. - /// Its usage is quite simple, for example you can count the number - /// of nodes in graph \c g of type \c Graph like this: + /// This iterator goes through each node of the graph. + /// Its usage is quite simple, for example, you can count the number + /// of nodes in a graph \c g of type \c %Graph like this: ///\code /// int count=0; /// for (Graph::NodeIt n(g); n!=INVALID; ++n) ++count; @@ -137,30 +150,28 @@ public: /// Default constructor - /// @warning The default constructor sets the iterator - /// to an undefined value. + /// Default constructor. + /// \warning It sets the iterator to an undefined value. NodeIt() { } /// Copy constructor. /// Copy constructor. /// NodeIt(const NodeIt& n) : Node(n) { } - /// Invalid constructor \& conversion. + /// %Invalid constructor \& conversion. - /// Initialize the iterator to be invalid. + /// Initializes the iterator to be invalid. /// \sa Invalid for more details. NodeIt(Invalid) { } /// Sets the iterator to the first node. - /// Sets the iterator to the first node of \c g. + /// Sets the iterator to the first node of the given digraph. /// - NodeIt(const Graph&) { } - /// Node -> NodeIt conversion. + explicit NodeIt(const Graph&) { } + /// Sets the iterator to the given node. - /// Sets the iterator to the node of \c the graph pointed by - /// the trivial iterator. - /// This feature necessitates that each time we - /// iterate the arc-set, the iteration order is the same. + /// Sets the iterator to the given node of the given digraph. + /// NodeIt(const Graph&, const Node&) { } /// Next node. @@ -170,54 +181,55 @@ }; - /// The base type of the edge iterators. + /// The edge type of the graph - /// The base type of the edge iterators. - /// + /// This class identifies an edge of the graph. It also serves + /// as a base class of the edge iterators, + /// thus they will convert to this type. class Edge { public: /// Default constructor - /// @warning The default constructor sets the iterator - /// to an undefined value. + /// Default constructor. + /// \warning It sets the object to an undefined value. Edge() { } /// Copy constructor. /// Copy constructor. /// Edge(const Edge&) { } - /// Initialize the iterator to be invalid. + /// %Invalid constructor \& conversion. - /// Initialize the iterator to be invalid. - /// + /// Initializes the object to be invalid. + /// \sa Invalid for more details. Edge(Invalid) { } /// Equality operator + /// Equality operator. + /// /// Two iterators are equal if and only if they point to the - /// same object or both are invalid. + /// same object or both are \c INVALID. bool operator==(Edge) const { return true; } /// Inequality operator - /// \sa operator==(Edge n) - /// + /// Inequality operator. bool operator!=(Edge) const { return true; } /// Artificial ordering operator. - /// To allow the use of graph descriptors as key type in std::map or - /// similar associative container we require this. + /// Artificial ordering operator. /// - /// \note This operator only have to define some strict ordering of - /// the items; this order has nothing to do with the iteration - /// ordering of the items. + /// \note This operator only has to define some strict ordering of + /// the edges; this order has nothing to do with the iteration + /// ordering of the edges. bool operator<(Edge) const { return false; } }; - /// This iterator goes through each edge. + /// Iterator class for the edges. - /// This iterator goes through each edge of a graph. - /// Its usage is quite simple, for example you can count the number - /// of edges in a graph \c g of type \c Graph as follows: + /// This iterator goes through each edge of the graph. + /// Its usage is quite simple, for example, you can count the number + /// of edges in a graph \c g of type \c %Graph as follows: ///\code /// int count=0; /// for(Graph::EdgeIt e(g); e!=INVALID; ++e) ++count; @@ -226,290 +238,285 @@ public: /// Default constructor - /// @warning The default constructor sets the iterator - /// to an undefined value. + /// Default constructor. + /// \warning It sets the iterator to an undefined value. EdgeIt() { } /// Copy constructor. /// Copy constructor. /// EdgeIt(const EdgeIt& e) : Edge(e) { } - /// Initialize the iterator to be invalid. + /// %Invalid constructor \& conversion. - /// Initialize the iterator to be invalid. + /// Initializes the iterator to be invalid. + /// \sa Invalid for more details. + EdgeIt(Invalid) { } + /// Sets the iterator to the first edge. + + /// Sets the iterator to the first edge of the given graph. /// - EdgeIt(Invalid) { } - /// This constructor sets the iterator to the first edge. + explicit EdgeIt(const Graph&) { } + /// Sets the iterator to the given edge. - /// This constructor sets the iterator to the first edge. - EdgeIt(const Graph&) { } - /// Edge -> EdgeIt conversion - - /// Sets the iterator to the value of the trivial iterator. - /// This feature necessitates that each time we - /// iterate the edge-set, the iteration order is the - /// same. + /// Sets the iterator to the given edge of the given graph. + /// EdgeIt(const Graph&, const Edge&) { } /// Next edge /// Assign the iterator to the next edge. + /// EdgeIt& operator++() { return *this; } }; - /// \brief This iterator goes trough the incident undirected - /// arcs of a node. - /// - /// This iterator goes trough the incident edges - /// of a certain node of a graph. You should assume that the - /// loop arcs will be iterated twice. - /// - /// Its usage is quite simple, for example you can compute the - /// degree (i.e. count the number of incident arcs of a node \c n - /// in graph \c g of type \c Graph as follows. + /// Iterator class for the incident edges of a node. + + /// This iterator goes trough the incident undirected edges + /// of a certain node of a graph. + /// Its usage is quite simple, for example, you can compute the + /// degree (i.e. the number of incident edges) of a node \c n + /// in a graph \c g of type \c %Graph as follows. /// ///\code /// int count=0; /// for(Graph::IncEdgeIt e(g, n); e!=INVALID; ++e) ++count; ///\endcode + /// + /// \warning Loop edges will be iterated twice. class IncEdgeIt : public Edge { public: /// Default constructor - /// @warning The default constructor sets the iterator - /// to an undefined value. + /// Default constructor. + /// \warning It sets the iterator to an undefined value. IncEdgeIt() { } /// Copy constructor. /// Copy constructor. /// IncEdgeIt(const IncEdgeIt& e) : Edge(e) { } - /// Initialize the iterator to be invalid. + /// %Invalid constructor \& conversion. - /// Initialize the iterator to be invalid. + /// Initializes the iterator to be invalid. + /// \sa Invalid for more details. + IncEdgeIt(Invalid) { } + /// Sets the iterator to the first incident edge. + + /// Sets the iterator to the first incident edge of the given node. /// - IncEdgeIt(Invalid) { } - /// This constructor sets the iterator to first incident arc. + IncEdgeIt(const Graph&, const Node&) { } + /// Sets the iterator to the given edge. - /// This constructor set the iterator to the first incident arc of - /// the node. - IncEdgeIt(const Graph&, const Node&) { } - /// Edge -> IncEdgeIt conversion + /// Sets the iterator to the given edge of the given graph. + /// + IncEdgeIt(const Graph&, const Edge&) { } + /// Next incident edge - /// Sets the iterator to the value of the trivial iterator \c e. - /// This feature necessitates that each time we - /// iterate the arc-set, the iteration order is the same. - IncEdgeIt(const Graph&, const Edge&) { } - /// Next incident arc - - /// Assign the iterator to the next incident arc + /// Assign the iterator to the next incident edge /// of the corresponding node. IncEdgeIt& operator++() { return *this; } }; - /// The directed arc type. + /// The arc type of the graph - /// The directed arc type. It can be converted to the - /// edge or it should be inherited from the undirected - /// edge. + /// This class identifies a directed arc of the graph. It also serves + /// as a base class of the arc iterators, + /// thus they will convert to this type. class Arc { public: /// Default constructor - /// @warning The default constructor sets the iterator - /// to an undefined value. + /// Default constructor. + /// \warning It sets the object to an undefined value. Arc() { } /// Copy constructor. /// Copy constructor. /// Arc(const Arc&) { } - /// Initialize the iterator to be invalid. + /// %Invalid constructor \& conversion. - /// Initialize the iterator to be invalid. - /// + /// Initializes the object to be invalid. + /// \sa Invalid for more details. Arc(Invalid) { } /// Equality operator + /// Equality operator. + /// /// Two iterators are equal if and only if they point to the - /// same object or both are invalid. + /// same object or both are \c INVALID. bool operator==(Arc) const { return true; } /// Inequality operator - /// \sa operator==(Arc n) - /// + /// Inequality operator. bool operator!=(Arc) const { return true; } /// Artificial ordering operator. - /// To allow the use of graph descriptors as key type in std::map or - /// similar associative container we require this. + /// Artificial ordering operator. /// - /// \note This operator only have to define some strict ordering of - /// the items; this order has nothing to do with the iteration - /// ordering of the items. + /// \note This operator only has to define some strict ordering of + /// the arcs; this order has nothing to do with the iteration + /// ordering of the arcs. bool operator<(Arc) const { return false; } - /// Converison to Edge + /// Converison to \c Edge + + /// Converison to \c Edge. + /// operator Edge() const { return Edge(); } }; - /// This iterator goes through each directed arc. - /// This iterator goes through each arc of a graph. - /// Its usage is quite simple, for example you can count the number - /// of arcs in a graph \c g of type \c Graph as follows: + /// Iterator class for the arcs. + + /// This iterator goes through each directed arc of the graph. + /// Its usage is quite simple, for example, you can count the number + /// of arcs in a graph \c g of type \c %Graph as follows: ///\code /// int count=0; - /// for(Graph::ArcIt e(g); e!=INVALID; ++e) ++count; + /// for(Graph::ArcIt a(g); a!=INVALID; ++a) ++count; ///\endcode class ArcIt : public Arc { public: /// Default constructor - /// @warning The default constructor sets the iterator - /// to an undefined value. + /// Default constructor. + /// \warning It sets the iterator to an undefined value. ArcIt() { } /// Copy constructor. /// Copy constructor. /// ArcIt(const ArcIt& e) : Arc(e) { } - /// Initialize the iterator to be invalid. + /// %Invalid constructor \& conversion. - /// Initialize the iterator to be invalid. + /// Initializes the iterator to be invalid. + /// \sa Invalid for more details. + ArcIt(Invalid) { } + /// Sets the iterator to the first arc. + + /// Sets the iterator to the first arc of the given graph. /// - ArcIt(Invalid) { } - /// This constructor sets the iterator to the first arc. + explicit ArcIt(const Graph &g) { ignore_unused_variable_warning(g); } + /// Sets the iterator to the given arc. - /// This constructor sets the iterator to the first arc of \c g. - ///@param g the graph - ArcIt(const Graph &g) { ignore_unused_variable_warning(g); } - /// Arc -> ArcIt conversion - - /// Sets the iterator to the value of the trivial iterator \c e. - /// This feature necessitates that each time we - /// iterate the arc-set, the iteration order is the same. + /// Sets the iterator to the given arc of the given graph. + /// ArcIt(const Graph&, const Arc&) { } - ///Next arc + /// Next arc /// Assign the iterator to the next arc. + /// ArcIt& operator++() { return *this; } }; - /// This iterator goes trough the outgoing directed arcs of a node. + /// Iterator class for the outgoing arcs of a node. - /// This iterator goes trough the \e outgoing arcs of a certain node - /// of a graph. - /// Its usage is quite simple, for example you can count the number + /// This iterator goes trough the \e outgoing directed arcs of a + /// certain node of a graph. + /// Its usage is quite simple, for example, you can count the number /// of outgoing arcs of a node \c n - /// in graph \c g of type \c Graph as follows. + /// in a graph \c g of type \c %Graph as follows. ///\code /// int count=0; - /// for (Graph::OutArcIt e(g, n); e!=INVALID; ++e) ++count; + /// for (Digraph::OutArcIt a(g, n); a!=INVALID; ++a) ++count; ///\endcode - class OutArcIt : public Arc { public: /// Default constructor - /// @warning The default constructor sets the iterator - /// to an undefined value. + /// Default constructor. + /// \warning It sets the iterator to an undefined value. OutArcIt() { } /// Copy constructor. /// Copy constructor. /// OutArcIt(const OutArcIt& e) : Arc(e) { } - /// Initialize the iterator to be invalid. + /// %Invalid constructor \& conversion. - /// Initialize the iterator to be invalid. + /// Initializes the iterator to be invalid. + /// \sa Invalid for more details. + OutArcIt(Invalid) { } + /// Sets the iterator to the first outgoing arc. + + /// Sets the iterator to the first outgoing arc of the given node. /// - OutArcIt(Invalid) { } - /// This constructor sets the iterator to the first outgoing arc. - - /// This constructor sets the iterator to the first outgoing arc of - /// the node. - ///@param n the node - ///@param g the graph OutArcIt(const Graph& n, const Node& g) { ignore_unused_variable_warning(n); ignore_unused_variable_warning(g); } - /// Arc -> OutArcIt conversion + /// Sets the iterator to the given arc. - /// Sets the iterator to the value of the trivial iterator. - /// This feature necessitates that each time we - /// iterate the arc-set, the iteration order is the same. + /// Sets the iterator to the given arc of the given graph. + /// OutArcIt(const Graph&, const Arc&) { } - ///Next outgoing arc + /// Next outgoing arc /// Assign the iterator to the next /// outgoing arc of the corresponding node. OutArcIt& operator++() { return *this; } }; - /// This iterator goes trough the incoming directed arcs of a node. + /// Iterator class for the incoming arcs of a node. - /// This iterator goes trough the \e incoming arcs of a certain node - /// of a graph. - /// Its usage is quite simple, for example you can count the number - /// of outgoing arcs of a node \c n - /// in graph \c g of type \c Graph as follows. + /// This iterator goes trough the \e incoming directed arcs of a + /// certain node of a graph. + /// Its usage is quite simple, for example, you can count the number + /// of incoming arcs of a node \c n + /// in a graph \c g of type \c %Graph as follows. ///\code /// int count=0; - /// for(Graph::InArcIt e(g, n); e!=INVALID; ++e) ++count; + /// for (Digraph::InArcIt a(g, n); a!=INVALID; ++a) ++count; ///\endcode - class InArcIt : public Arc { public: /// Default constructor - /// @warning The default constructor sets the iterator - /// to an undefined value. + /// Default constructor. + /// \warning It sets the iterator to an undefined value. InArcIt() { } /// Copy constructor. /// Copy constructor. /// InArcIt(const InArcIt& e) : Arc(e) { } - /// Initialize the iterator to be invalid. + /// %Invalid constructor \& conversion. - /// Initialize the iterator to be invalid. + /// Initializes the iterator to be invalid. + /// \sa Invalid for more details. + InArcIt(Invalid) { } + /// Sets the iterator to the first incoming arc. + + /// Sets the iterator to the first incoming arc of the given node. /// - InArcIt(Invalid) { } - /// This constructor sets the iterator to first incoming arc. - - /// This constructor set the iterator to the first incoming arc of - /// the node. - ///@param n the node - ///@param g the graph InArcIt(const Graph& g, const Node& n) { ignore_unused_variable_warning(n); ignore_unused_variable_warning(g); } - /// Arc -> InArcIt conversion + /// Sets the iterator to the given arc. - /// Sets the iterator to the value of the trivial iterator \c e. - /// This feature necessitates that each time we - /// iterate the arc-set, the iteration order is the same. + /// Sets the iterator to the given arc of the given graph. + /// InArcIt(const Graph&, const Arc&) { } /// Next incoming arc - /// Assign the iterator to the next inarc of the corresponding node. - /// + /// Assign the iterator to the next + /// incoming arc of the corresponding node. InArcIt& operator++() { return *this; } }; - /// \brief Reference map of the nodes to type \c T. + /// \brief Standard graph map type for the nodes. /// - /// Reference map of the nodes to type \c T. + /// Standard graph map type for the nodes. + /// It conforms to the ReferenceMap concept. template class NodeMap : public ReferenceMap { public: - ///\e - NodeMap(const Graph&) { } - ///\e + /// Constructor + explicit NodeMap(const Graph&) { } + /// Constructor with given initial value NodeMap(const Graph&, T) { } private: @@ -524,18 +531,20 @@ } }; - /// \brief Reference map of the arcs to type \c T. + /// \brief Standard graph map type for the arcs. /// - /// Reference map of the arcs to type \c T. + /// Standard graph map type for the arcs. + /// It conforms to the ReferenceMap concept. template class ArcMap : public ReferenceMap { public: - ///\e - ArcMap(const Graph&) { } - ///\e + /// Constructor + explicit ArcMap(const Graph&) { } + /// Constructor with given initial value ArcMap(const Graph&, T) { } + private: ///Copy constructor ArcMap(const ArcMap& em) : @@ -548,18 +557,20 @@ } }; - /// Reference map of the edges to type \c T. - - /// Reference map of the edges to type \c T. + /// \brief Standard graph map type for the edges. + /// + /// Standard graph map type for the edges. + /// It conforms to the ReferenceMap concept. template class EdgeMap : public ReferenceMap { public: - ///\e - EdgeMap(const Graph&) { } - ///\e + /// Constructor + explicit EdgeMap(const Graph&) { } + /// Constructor with given initial value EdgeMap(const Graph&, T) { } + private: ///Copy constructor EdgeMap(const EdgeMap& em) : @@ -572,107 +583,124 @@ } }; - /// \brief Direct the given edge. + /// \brief The first node of the edge. /// - /// Direct the given edge. The returned arc source - /// will be the given node. - Arc direct(const Edge&, const Node&) const { - return INVALID; - } - - /// \brief Direct the given edge. + /// Returns the first node of the given edge. /// - /// Direct the given edge. The returned arc - /// represents the given edge and the direction comes - /// from the bool parameter. The source of the edge and - /// the directed arc is the same when the given bool is true. - Arc direct(const Edge&, bool) const { - return INVALID; - } - - /// \brief Returns true if the arc has default orientation. - /// - /// Returns whether the given directed arc is same orientation as - /// the corresponding edge's default orientation. - bool direction(Arc) const { return true; } - - /// \brief Returns the opposite directed arc. - /// - /// Returns the opposite directed arc. - Arc oppositeArc(Arc) const { return INVALID; } - - /// \brief Opposite node on an arc - /// - /// \return The opposite of the given node on the given edge. - Node oppositeNode(Node, Edge) const { return INVALID; } - - /// \brief First node of the edge. - /// - /// \return The first node of the given edge. - /// - /// Naturally edges don't have direction and thus - /// don't have source and target node. However we use \c u() and \c v() - /// methods to query the two nodes of the arc. The direction of the - /// arc which arises this way is called the inherent direction of the - /// edge, and is used to define the "default" direction - /// of the directed versions of the arcs. + /// Edges don't have source and target nodes, however, methods + /// u() and v() are used to query the two end-nodes of an edge. + /// The orientation of an edge that arises this way is called + /// the inherent direction, it is used to define the default + /// direction for the corresponding arcs. /// \sa v() /// \sa direction() Node u(Edge) const { return INVALID; } - /// \brief Second node of the edge. + /// \brief The second node of the edge. /// - /// \return The second node of the given edge. + /// Returns the second node of the given edge. /// - /// Naturally edges don't have direction and thus - /// don't have source and target node. However we use \c u() and \c v() - /// methods to query the two nodes of the arc. The direction of the - /// arc which arises this way is called the inherent direction of the - /// edge, and is used to define the "default" direction - /// of the directed versions of the arcs. + /// Edges don't have source and target nodes, however, methods + /// u() and v() are used to query the two end-nodes of an edge. + /// The orientation of an edge that arises this way is called + /// the inherent direction, it is used to define the default + /// direction for the corresponding arcs. /// \sa u() /// \sa direction() Node v(Edge) const { return INVALID; } - /// \brief Source node of the directed arc. + /// \brief The source node of the arc. + /// + /// Returns the source node of the given arc. Node source(Arc) const { return INVALID; } - /// \brief Target node of the directed arc. + /// \brief The target node of the arc. + /// + /// Returns the target node of the given arc. Node target(Arc) const { return INVALID; } - /// \brief Returns the id of the node. + /// \brief The ID of the node. + /// + /// Returns the ID of the given node. int id(Node) const { return -1; } - /// \brief Returns the id of the edge. + /// \brief The ID of the edge. + /// + /// Returns the ID of the given edge. int id(Edge) const { return -1; } - /// \brief Returns the id of the arc. + /// \brief The ID of the arc. + /// + /// Returns the ID of the given arc. int id(Arc) const { return -1; } - /// \brief Returns the node with the given id. + /// \brief The node with the given ID. /// - /// \pre The argument should be a valid node id in the graph. + /// Returns the node with the given ID. + /// \pre The argument should be a valid node ID in the graph. Node nodeFromId(int) const { return INVALID; } - /// \brief Returns the edge with the given id. + /// \brief The edge with the given ID. /// - /// \pre The argument should be a valid edge id in the graph. + /// Returns the edge with the given ID. + /// \pre The argument should be a valid edge ID in the graph. Edge edgeFromId(int) const { return INVALID; } - /// \brief Returns the arc with the given id. + /// \brief The arc with the given ID. /// - /// \pre The argument should be a valid arc id in the graph. + /// Returns the arc with the given ID. + /// \pre The argument should be a valid arc ID in the graph. Arc arcFromId(int) const { return INVALID; } - /// \brief Returns an upper bound on the node IDs. + /// \brief An upper bound on the node IDs. + /// + /// Returns an upper bound on the node IDs. int maxNodeId() const { return -1; } - /// \brief Returns an upper bound on the edge IDs. + /// \brief An upper bound on the edge IDs. + /// + /// Returns an upper bound on the edge IDs. int maxEdgeId() const { return -1; } - /// \brief Returns an upper bound on the arc IDs. + /// \brief An upper bound on the arc IDs. + /// + /// Returns an upper bound on the arc IDs. int maxArcId() const { return -1; } + /// \brief The direction of the arc. + /// + /// Returns \c true if the direction of the given arc is the same as + /// the inherent orientation of the represented edge. + bool direction(Arc) const { return true; } + + /// \brief Direct the edge. + /// + /// Direct the given edge. The returned arc + /// represents the given edge and its direction comes + /// from the bool parameter. If it is \c true, then the direction + /// of the arc is the same as the inherent orientation of the edge. + Arc direct(Edge, bool) const { + return INVALID; + } + + /// \brief Direct the edge. + /// + /// Direct the given edge. The returned arc represents the given + /// edge and its source node is the given node. + Arc direct(Edge, Node) const { + return INVALID; + } + + /// \brief The oppositely directed arc. + /// + /// Returns the oppositely directed arc representing the same edge. + Arc oppositeArc(Arc) const { return INVALID; } + + /// \brief The opposite node on the edge. + /// + /// Returns the opposite node on the given edge. + Node oppositeNode(Node, Edge) const { return INVALID; } + void first(Node&) const {} void next(Node&) const {} @@ -705,47 +733,39 @@ // Dummy parameter. int maxId(Arc) const { return -1; } - /// \brief Base node of the iterator + /// \brief The base node of the iterator. /// - /// Returns the base node (the source in this case) of the iterator - Node baseNode(OutArcIt e) const { - return source(e); - } - /// \brief Running node of the iterator + /// Returns the base node of the given incident edge iterator. + Node baseNode(IncEdgeIt) const { return INVALID; } + + /// \brief The running node of the iterator. /// - /// Returns the running node (the target in this case) of the - /// iterator - Node runningNode(OutArcIt e) const { - return target(e); - } + /// Returns the running node of the given incident edge iterator. + Node runningNode(IncEdgeIt) const { return INVALID; } - /// \brief Base node of the iterator + /// \brief The base node of the iterator. /// - /// Returns the base node (the target in this case) of the iterator - Node baseNode(InArcIt e) const { - return target(e); - } - /// \brief Running node of the iterator + /// Returns the base node of the given outgoing arc iterator + /// (i.e. the source node of the corresponding arc). + Node baseNode(OutArcIt) const { return INVALID; } + + /// \brief The running node of the iterator. /// - /// Returns the running node (the source in this case) of the - /// iterator - Node runningNode(InArcIt e) const { - return source(e); - } + /// Returns the running node of the given outgoing arc iterator + /// (i.e. the target node of the corresponding arc). + Node runningNode(OutArcIt) const { return INVALID; } - /// \brief Base node of the iterator + /// \brief The base node of the iterator. /// - /// Returns the base node of the iterator - Node baseNode(IncEdgeIt) const { - return INVALID; - } + /// Returns the base node of the given incomming arc iterator + /// (i.e. the target node of the corresponding arc). + Node baseNode(InArcIt) const { return INVALID; } - /// \brief Running node of the iterator + /// \brief The running node of the iterator. /// - /// Returns the running node of the iterator - Node runningNode(IncEdgeIt) const { - return INVALID; - } + /// Returns the running node of the given incomming arc iterator + /// (i.e. the source node of the corresponding arc). + Node runningNode(InArcIt) const { return INVALID; } template struct Constraints {