COIN-OR::LEMON - Graph Library

source: lemon/lemon/concepts/digraph.h @ 781:bd72f8d20f33

Last change on this file since 781:bd72f8d20f33 was 781:bd72f8d20f33, checked in by Peter Kovacs <kpeter@…>, 10 years ago

Doc improvements and unification for graph concepts (#311)

File size: 15.1 KB
RevLine 
[209]1/* -*- mode: C++; indent-tabs-mode: nil; -*-
[57]2 *
[209]3 * This file is a part of LEMON, a generic C++ optimization library.
[57]4 *
[463]5 * Copyright (C) 2003-2009
[57]6 * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
7 * (Egervary Research Group on Combinatorial Optimization, EGRES).
8 *
9 * Permission to use, modify and distribute this software is granted
10 * provided that this copyright notice appears in all copies. For
11 * precise terms see the accompanying LICENSE file.
12 *
13 * This software is provided "AS IS" with no warranty of any kind,
14 * express or implied, and with no claim as to its suitability for any
15 * purpose.
16 *
17 */
18
[576]19#ifndef LEMON_CONCEPTS_DIGRAPH_H
20#define LEMON_CONCEPTS_DIGRAPH_H
[57]21
22///\ingroup graph_concepts
23///\file
24///\brief The concept of directed graphs.
25
[220]26#include <lemon/core.h>
[57]27#include <lemon/concepts/maps.h>
28#include <lemon/concept_check.h>
29#include <lemon/concepts/graph_components.h>
30
31namespace lemon {
32  namespace concepts {
33
34    /// \ingroup graph_concepts
35    ///
36    /// \brief Class describing the concept of directed graphs.
37    ///
[781]38    /// This class describes the common interface of all directed
39    /// graphs (digraphs).
[57]40    ///
[781]41    /// Like all concept classes, it only provides an interface
42    /// without any sensible implementation. So any general algorithm for
43    /// directed graphs should compile with this class, but it will not
44    /// run properly, of course.
45    /// An actual digraph implementation like \ref ListDigraph or
46    /// \ref SmartDigraph may have additional functionality.
[57]47    ///
[781]48    /// \sa Graph
[57]49    class Digraph {
50    private:
[781]51      /// Diraphs are \e not copy constructible. Use DigraphCopy instead.
52      Digraph(const Digraph &) {}
53      /// \brief Assignment of a digraph to another one is \e not allowed.
54      /// Use DigraphCopy instead.
55      void operator=(const Digraph &) {}
[209]56
[781]57    public:
58      /// Default constructor.
59      Digraph() { }
[209]60
[781]61      /// The node type of the digraph
[57]62
63      /// This class identifies a node of the digraph. It also serves
64      /// as a base class of the node iterators,
[781]65      /// thus they convert to this type.
[57]66      class Node {
67      public:
68        /// Default constructor
69
[781]70        /// Default constructor.
71        /// \warning It sets the object to an undefined value.
[57]72        Node() { }
73        /// Copy constructor.
74
75        /// Copy constructor.
76        ///
77        Node(const Node&) { }
78
[781]79        /// %Invalid constructor \& conversion.
[57]80
[781]81        /// Initializes the object to be invalid.
[57]82        /// \sa Invalid for more details.
83        Node(Invalid) { }
84        /// Equality operator
85
[781]86        /// Equality operator.
87        ///
[57]88        /// Two iterators are equal if and only if they point to the
[781]89        /// same object or both are \c INVALID.
[57]90        bool operator==(Node) const { return true; }
91
92        /// Inequality operator
[209]93
[781]94        /// Inequality operator.
[57]95        bool operator!=(Node) const { return true; }
96
[209]97        /// Artificial ordering operator.
98
[781]99        /// Artificial ordering operator.
[209]100        ///
[781]101        /// \note This operator only has to define some strict ordering of
102        /// the nodes; this order has nothing to do with the iteration
103        /// ordering of the nodes.
[209]104        bool operator<(Node) const { return false; }
[57]105      };
[209]106
[781]107      /// Iterator class for the nodes.
[57]108
[781]109      /// This iterator goes through each node of the digraph.
[57]110      /// Its usage is quite simple, for example you can count the number
[781]111      /// of nodes in a digraph \c g of type \c %Digraph like this:
[57]112      ///\code
113      /// int count=0;
114      /// for (Digraph::NodeIt n(g); n!=INVALID; ++n) ++count;
115      ///\endcode
116      class NodeIt : public Node {
117      public:
118        /// Default constructor
119
[781]120        /// Default constructor.
121        /// \warning It sets the iterator to an undefined value.
[57]122        NodeIt() { }
123        /// Copy constructor.
[209]124
[57]125        /// Copy constructor.
126        ///
127        NodeIt(const NodeIt& n) : Node(n) { }
[781]128        /// %Invalid constructor \& conversion.
[57]129
[781]130        /// Initializes the iterator to be invalid.
[57]131        /// \sa Invalid for more details.
132        NodeIt(Invalid) { }
133        /// Sets the iterator to the first node.
134
[781]135        /// Sets the iterator to the first node of the given digraph.
[57]136        ///
[781]137        explicit NodeIt(const Digraph&) { }
138        /// Sets the iterator to the given node.
[57]139
[781]140        /// Sets the iterator to the given node of the given digraph.
141        ///
[57]142        NodeIt(const Digraph&, const Node&) { }
143        /// Next node.
144
145        /// Assign the iterator to the next node.
146        ///
147        NodeIt& operator++() { return *this; }
148      };
[209]149
150
[781]151      /// The arc type of the digraph
[57]152
153      /// This class identifies an arc of the digraph. It also serves
154      /// as a base class of the arc iterators,
155      /// thus they will convert to this type.
156      class Arc {
157      public:
158        /// Default constructor
159
[781]160        /// Default constructor.
161        /// \warning It sets the object to an undefined value.
[57]162        Arc() { }
163        /// Copy constructor.
164
165        /// Copy constructor.
166        ///
167        Arc(const Arc&) { }
[781]168        /// %Invalid constructor \& conversion.
[57]169
[781]170        /// Initializes the object to be invalid.
171        /// \sa Invalid for more details.
[57]172        Arc(Invalid) { }
173        /// Equality operator
174
[781]175        /// Equality operator.
176        ///
[57]177        /// Two iterators are equal if and only if they point to the
[781]178        /// same object or both are \c INVALID.
[57]179        bool operator==(Arc) const { return true; }
180        /// Inequality operator
181
[781]182        /// Inequality operator.
[57]183        bool operator!=(Arc) const { return true; }
184
[209]185        /// Artificial ordering operator.
186
[781]187        /// Artificial ordering operator.
[209]188        ///
[781]189        /// \note This operator only has to define some strict ordering of
190        /// the arcs; this order has nothing to do with the iteration
191        /// ordering of the arcs.
[209]192        bool operator<(Arc) const { return false; }
[57]193      };
[209]194
[781]195      /// Iterator class for the outgoing arcs of a node.
[57]196
197      /// This iterator goes trough the \e outgoing arcs of a certain node
198      /// of a digraph.
199      /// Its usage is quite simple, for example you can count the number
200      /// of outgoing arcs of a node \c n
[781]201      /// in a digraph \c g of type \c %Digraph as follows.
[57]202      ///\code
203      /// int count=0;
[781]204      /// for (Digraph::OutArcIt a(g, n); a!=INVALID; ++a) ++count;
[57]205      ///\endcode
206      class OutArcIt : public Arc {
207      public:
208        /// Default constructor
209
[781]210        /// Default constructor.
211        /// \warning It sets the iterator to an undefined value.
[57]212        OutArcIt() { }
213        /// Copy constructor.
214
215        /// Copy constructor.
216        ///
217        OutArcIt(const OutArcIt& e) : Arc(e) { }
[781]218        /// %Invalid constructor \& conversion.
[57]219
[781]220        /// Initializes the iterator to be invalid.
221        /// \sa Invalid for more details.
222        OutArcIt(Invalid) { }
223        /// Sets the iterator to the first outgoing arc.
224
225        /// Sets the iterator to the first outgoing arc of the given node.
[57]226        ///
[781]227        OutArcIt(const Digraph&, const Node&) { }
228        /// Sets the iterator to the given arc.
[209]229
[781]230        /// Sets the iterator to the given arc of the given digraph.
231        ///
[57]232        OutArcIt(const Digraph&, const Arc&) { }
[781]233        /// Next outgoing arc
[209]234
235        /// Assign the iterator to the next
[57]236        /// outgoing arc of the corresponding node.
237        OutArcIt& operator++() { return *this; }
238      };
239
[781]240      /// Iterator class for the incoming arcs of a node.
[57]241
242      /// This iterator goes trough the \e incoming arcs of a certain node
243      /// of a digraph.
244      /// Its usage is quite simple, for example you can count the number
[781]245      /// of incoming arcs of a node \c n
246      /// in a digraph \c g of type \c %Digraph as follows.
[57]247      ///\code
248      /// int count=0;
[781]249      /// for(Digraph::InArcIt a(g, n); a!=INVALID; ++a) ++count;
[57]250      ///\endcode
251      class InArcIt : public Arc {
252      public:
253        /// Default constructor
254
[781]255        /// Default constructor.
256        /// \warning It sets the iterator to an undefined value.
[57]257        InArcIt() { }
258        /// Copy constructor.
259
260        /// Copy constructor.
261        ///
262        InArcIt(const InArcIt& e) : Arc(e) { }
[781]263        /// %Invalid constructor \& conversion.
[57]264
[781]265        /// Initializes the iterator to be invalid.
266        /// \sa Invalid for more details.
267        InArcIt(Invalid) { }
268        /// Sets the iterator to the first incoming arc.
269
270        /// Sets the iterator to the first incoming arc of the given node.
[57]271        ///
[781]272        InArcIt(const Digraph&, const Node&) { }
273        /// Sets the iterator to the given arc.
[209]274
[781]275        /// Sets the iterator to the given arc of the given digraph.
276        ///
[57]277        InArcIt(const Digraph&, const Arc&) { }
278        /// Next incoming arc
279
[781]280        /// Assign the iterator to the next
281        /// incoming arc of the corresponding node.
[57]282        InArcIt& operator++() { return *this; }
283      };
284
[781]285      /// Iterator class for the arcs.
286
287      /// This iterator goes through each arc of the digraph.
[57]288      /// Its usage is quite simple, for example you can count the number
[781]289      /// of arcs in a digraph \c g of type \c %Digraph as follows:
[57]290      ///\code
291      /// int count=0;
[781]292      /// for(Digraph::ArcIt a(g); a!=INVALID; ++a) ++count;
[57]293      ///\endcode
294      class ArcIt : public Arc {
295      public:
296        /// Default constructor
297
[781]298        /// Default constructor.
299        /// \warning It sets the iterator to an undefined value.
[57]300        ArcIt() { }
301        /// Copy constructor.
302
303        /// Copy constructor.
304        ///
305        ArcIt(const ArcIt& e) : Arc(e) { }
[781]306        /// %Invalid constructor \& conversion.
[57]307
[781]308        /// Initializes the iterator to be invalid.
309        /// \sa Invalid for more details.
310        ArcIt(Invalid) { }
311        /// Sets the iterator to the first arc.
312
313        /// Sets the iterator to the first arc of the given digraph.
[57]314        ///
[781]315        explicit ArcIt(const Digraph& g) { ignore_unused_variable_warning(g); }
316        /// Sets the iterator to the given arc.
[209]317
[781]318        /// Sets the iterator to the given arc of the given digraph.
319        ///
[209]320        ArcIt(const Digraph&, const Arc&) { }
[781]321        /// Next arc
[209]322
[57]323        /// Assign the iterator to the next arc.
[781]324        ///
[57]325        ArcIt& operator++() { return *this; }
326      };
327
[781]328      /// \brief The source node of the arc.
[57]329      ///
[781]330      /// Returns the source node of the given arc.
[57]331      Node source(Arc) const { return INVALID; }
332
[781]333      /// \brief The target node of the arc.
334      ///
335      /// Returns the target node of the given arc.
336      Node target(Arc) const { return INVALID; }
337
338      /// \brief The ID of the node.
339      ///
340      /// Returns the ID of the given node.
[209]341      int id(Node) const { return -1; }
[61]342
[781]343      /// \brief The ID of the arc.
344      ///
345      /// Returns the ID of the given arc.
[209]346      int id(Arc) const { return -1; }
[61]347
[781]348      /// \brief The node with the given ID.
[61]349      ///
[781]350      /// Returns the node with the given ID.
351      /// \pre The argument should be a valid node ID in the digraph.
[209]352      Node nodeFromId(int) const { return INVALID; }
[61]353
[781]354      /// \brief The arc with the given ID.
[61]355      ///
[781]356      /// Returns the arc with the given ID.
357      /// \pre The argument should be a valid arc ID in the digraph.
[209]358      Arc arcFromId(int) const { return INVALID; }
[61]359
[781]360      /// \brief An upper bound on the node IDs.
361      ///
362      /// Returns an upper bound on the node IDs.
[209]363      int maxNodeId() const { return -1; }
[61]364
[781]365      /// \brief An upper bound on the arc IDs.
366      ///
367      /// Returns an upper bound on the arc IDs.
[209]368      int maxArcId() const { return -1; }
[61]369
[57]370      void first(Node&) const {}
371      void next(Node&) const {}
372
373      void first(Arc&) const {}
374      void next(Arc&) const {}
375
376
377      void firstIn(Arc&, const Node&) const {}
378      void nextIn(Arc&) const {}
379
380      void firstOut(Arc&, const Node&) const {}
381      void nextOut(Arc&) const {}
382
[61]383      // The second parameter is dummy.
384      Node fromId(int, Node) const { return INVALID; }
385      // The second parameter is dummy.
386      Arc fromId(int, Arc) const { return INVALID; }
387
388      // Dummy parameter.
[209]389      int maxId(Node) const { return -1; }
[61]390      // Dummy parameter.
[209]391      int maxId(Arc) const { return -1; }
[61]392
[781]393      /// \brief The opposite node on the arc.
394      ///
395      /// Returns the opposite node on the given arc.
396      Node oppositeNode(Node, Arc) const { return INVALID; }
397
[57]398      /// \brief The base node of the iterator.
399      ///
[781]400      /// Returns the base node of the given outgoing arc iterator
401      /// (i.e. the source node of the corresponding arc).
402      Node baseNode(OutArcIt) const { return INVALID; }
[57]403
404      /// \brief The running node of the iterator.
405      ///
[781]406      /// Returns the running node of the given outgoing arc iterator
407      /// (i.e. the target node of the corresponding arc).
408      Node runningNode(OutArcIt) const { return INVALID; }
[57]409
410      /// \brief The base node of the iterator.
411      ///
[781]412      /// Returns the base node of the given incomming arc iterator
413      /// (i.e. the target node of the corresponding arc).
414      Node baseNode(InArcIt) const { return INVALID; }
[57]415
416      /// \brief The running node of the iterator.
417      ///
[781]418      /// Returns the running node of the given incomming arc iterator
419      /// (i.e. the source node of the corresponding arc).
420      Node runningNode(InArcIt) const { return INVALID; }
[57]421
[781]422      /// \brief Standard graph map type for the nodes.
[57]423      ///
[781]424      /// Standard graph map type for the nodes.
425      /// It conforms to the ReferenceMap concept.
[209]426      template<class T>
[627]427      class NodeMap : public ReferenceMap<Node, T, T&, const T&> {
[57]428      public:
429
[781]430        /// Constructor
431        explicit NodeMap(const Digraph&) { }
432        /// Constructor with given initial value
[57]433        NodeMap(const Digraph&, T) { }
434
[263]435      private:
[57]436        ///Copy constructor
[627]437        NodeMap(const NodeMap& nm) :
438          ReferenceMap<Node, T, T&, const T&>(nm) { }
[57]439        ///Assignment operator
440        template <typename CMap>
[209]441        NodeMap& operator=(const CMap&) {
[57]442          checkConcept<ReadMap<Node, T>, CMap>();
[209]443          return *this;
[57]444        }
445      };
446
[781]447      /// \brief Standard graph map type for the arcs.
[57]448      ///
[781]449      /// Standard graph map type for the arcs.
450      /// It conforms to the ReferenceMap concept.
[209]451      template<class T>
[627]452      class ArcMap : public ReferenceMap<Arc, T, T&, const T&> {
[57]453      public:
454
[781]455        /// Constructor
456        explicit ArcMap(const Digraph&) { }
457        /// Constructor with given initial value
[57]458        ArcMap(const Digraph&, T) { }
[781]459
[263]460      private:
[57]461        ///Copy constructor
[627]462        ArcMap(const ArcMap& em) :
463          ReferenceMap<Arc, T, T&, const T&>(em) { }
[57]464        ///Assignment operator
465        template <typename CMap>
[209]466        ArcMap& operator=(const CMap&) {
[57]467          checkConcept<ReadMap<Arc, T>, CMap>();
[209]468          return *this;
[57]469        }
470      };
471
[125]472      template <typename _Digraph>
[57]473      struct Constraints {
474        void constraints() {
[627]475          checkConcept<BaseDigraphComponent, _Digraph>();
[125]476          checkConcept<IterableDigraphComponent<>, _Digraph>();
[209]477          checkConcept<IDableDigraphComponent<>, _Digraph>();
[125]478          checkConcept<MappableDigraphComponent<>, _Digraph>();
[57]479        }
480      };
481
482    };
[209]483
484  } //namespace concepts
[57]485} //namespace lemon
486
487
488
[576]489#endif
Note: See TracBrowser for help on using the repository browser.