COIN-OR::LEMON - Graph Library

source: lemon-0.x/lemon/concept/graph.h @ 2117:96efb4fa0736

Last change on this file since 2117:96efb4fa0736 was 2117:96efb4fa0736, checked in by Alpar Juttner, 18 years ago
  • Revised "Concepts" group documentation
  • Other minor doc improvements
File size: 14.3 KB
RevLine 
[959]1/* -*- C++ -*-
2 *
[1956]3 * This file is a part of LEMON, a generic C++ optimization library
4 *
5 * Copyright (C) 2003-2006
6 * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
[1359]7 * (Egervary Research Group on Combinatorial Optimization, EGRES).
[959]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
19#ifndef LEMON_CONCEPT_GRAPH_H
20#define LEMON_CONCEPT_GRAPH_H
21
[1030]22///\ingroup graph_concepts
[959]23///\file
24///\brief Declaration of Graph.
25
[1993]26#include <lemon/bits/invalid.h>
27#include <lemon/bits/utility.h>
[959]28#include <lemon/concept/maps.h>
29#include <lemon/concept_check.h>
30#include <lemon/concept/graph_component.h>
31
32namespace lemon {
33  namespace concept {
[1136]34
[959]35   
[961]36    /**************** The full-featured graph concepts ****************/
[959]37
[1136]38
[1760]39    // \brief Modular static graph class.
40    //     
[2111]41    // It should be the same as the \c Graph class.
42    class _Graph
[961]43      :  virtual public BaseGraphComponent,
[1426]44         public IterableGraphComponent, public MappableGraphComponent {
[959]45    public:
[1448]46
[959]47      typedef BaseGraphComponent::Node Node;
48      typedef BaseGraphComponent::Edge Edge;
49
[989]50      template <typename _Graph>
51      struct Constraints {
[1426]52        void constraints() {
53          checkConcept<IterableGraphComponent, _Graph>();
54          checkConcept<MappableGraphComponent, _Graph>();
55        }
[989]56      };
[959]57    };
58
[1620]59    /// \addtogroup graph_concepts
60    /// @{
61
[2117]62    /// The directed graph concept
63
64    /// This class describes the \ref concept "concept" of the
65    /// immutable directed graphs.
[1136]66    ///
[2117]67    /// Note that actual graph implementation like @ref ListGraph or
68    /// @ref SmartGraph may have several additional functionality.
[1136]69    ///
[2117]70    /// \sa concept
[2111]71    class Graph {
[1136]72    public:
[1448]73      ///\e
74
[1136]75      /// Defalult constructor.
76
77      /// Defalult constructor.
78      ///
[2111]79      Graph() { }
[1136]80
81      /// The base type of node iterators,
82      /// or in other words, the trivial node iterator.
83
84      /// This is the base type of each node iterator,
85      /// thus each kind of node iterator converts to this.
86      /// More precisely each kind of node iterator should be inherited
87      /// from the trivial node iterator.
88      class Node {
89      public:
[1426]90        /// Default constructor
[1136]91
[1426]92        /// @warning The default constructor sets the iterator
93        /// to an undefined value.
94        Node() { }
95        /// Copy constructor.
[1136]96
[1426]97        /// Copy constructor.
98        ///
99        Node(const Node&) { }
[1136]100
[1426]101        /// Invalid constructor \& conversion.
[1136]102
[1426]103        /// This constructor initializes the iterator to be invalid.
104        /// \sa Invalid for more details.
105        Node(Invalid) { }
106        /// Equality operator
[1136]107
[1426]108        /// Two iterators are equal if and only if they point to the
109        /// same object or both are invalid.
110        bool operator==(Node) const { return true; }
[1136]111
[1426]112        /// Inequality operator
113       
114        /// \sa operator==(Node n)
115        ///
116        bool operator!=(Node) const { return true; }
[1136]117
[1622]118        /// Artificial ordering operator.
119       
120        /// To allow the use of graph descriptors as key type in std::map or
121        /// similar associative container we require this.
122        ///
123        /// \note This operator only have to define some strict ordering of
124        /// the items; this order has nothing to do with the iteration
125        /// ordering of the items.
126        ///
127        /// \bug This is a technical requirement. Do we really need this?
128        bool operator<(Node) const { return false; }
129
[1136]130      };
131   
132      /// This iterator goes through each node.
133
134      /// This iterator goes through each node.
135      /// Its usage is quite simple, for example you can count the number
136      /// of nodes in graph \c g of type \c Graph like this:
[1946]137      ///\code
[1136]138      /// int count=0;
[1426]139      /// for (Graph::NodeIt n(g); n!=INVALID; ++n) ++count;
[1946]140      ///\endcode
[1136]141      class NodeIt : public Node {
142      public:
[1426]143        /// Default constructor
[1136]144
[1426]145        /// @warning The default constructor sets the iterator
146        /// to an undefined value.
147        NodeIt() { }
148        /// Copy constructor.
149       
150        /// Copy constructor.
151        ///
152        NodeIt(const NodeIt& n) : Node(n) { }
153        /// Invalid constructor \& conversion.
[1136]154
[1426]155        /// Initialize the iterator to be invalid.
156        /// \sa Invalid for more details.
157        NodeIt(Invalid) { }
158        /// Sets the iterator to the first node.
[1136]159
[1426]160        /// Sets the iterator to the first node of \c g.
161        ///
[2111]162        NodeIt(const Graph&) { }
[1426]163        /// Node -> NodeIt conversion.
[1136]164
[1470]165        /// Sets the iterator to the node of \c the graph pointed by
166        /// the trivial iterator.
[1426]167        /// This feature necessitates that each time we
168        /// iterate the edge-set, the iteration order is the same.
[2111]169        NodeIt(const Graph&, const Node&) { }
[1426]170        /// Next node.
[1136]171
[1426]172        /// Assign the iterator to the next node.
173        ///
174        NodeIt& operator++() { return *this; }
[1136]175      };
176   
177   
178      /// The base type of the edge iterators.
179
180      /// The base type of the edge iterators.
181      ///
182      class Edge {
183      public:
[1426]184        /// Default constructor
[1136]185
[1426]186        /// @warning The default constructor sets the iterator
187        /// to an undefined value.
188        Edge() { }
189        /// Copy constructor.
[1136]190
[1426]191        /// Copy constructor.
192        ///
193        Edge(const Edge&) { }
194        /// Initialize the iterator to be invalid.
[1136]195
[1426]196        /// Initialize the iterator to be invalid.
197        ///
198        Edge(Invalid) { }
199        /// Equality operator
[1136]200
[1426]201        /// Two iterators are equal if and only if they point to the
202        /// same object or both are invalid.
203        bool operator==(Edge) const { return true; }
204        /// Inequality operator
[1136]205
[1620]206        /// \sa operator==(Edge n)
[1426]207        ///
208        bool operator!=(Edge) const { return true; }
[1622]209
210        /// Artificial ordering operator.
211       
212        /// To allow the use of graph descriptors as key type in std::map or
213        /// similar associative container we require this.
214        ///
215        /// \note This operator only have to define some strict ordering of
216        /// the items; this order has nothing to do with the iteration
217        /// ordering of the items.
218        ///
219        /// \bug This is a technical requirement. Do we really need this?
220        bool operator<(Edge) const { return false; }
[1136]221      };
222   
223      /// This iterator goes trough the outgoing edges of a node.
224
225      /// This iterator goes trough the \e outgoing edges of a certain node
226      /// of a graph.
227      /// Its usage is quite simple, for example you can count the number
228      /// of outgoing edges of a node \c n
229      /// in graph \c g of type \c Graph as follows.
[1946]230      ///\code
[1136]231      /// int count=0;
232      /// for (Graph::OutEdgeIt e(g, n); e!=INVALID; ++e) ++count;
[1946]233      ///\endcode
[1136]234   
235      class OutEdgeIt : public Edge {
236      public:
[1426]237        /// Default constructor
[1136]238
[1426]239        /// @warning The default constructor sets the iterator
240        /// to an undefined value.
241        OutEdgeIt() { }
242        /// Copy constructor.
[1136]243
[1426]244        /// Copy constructor.
245        ///
246        OutEdgeIt(const OutEdgeIt& e) : Edge(e) { }
247        /// Initialize the iterator to be invalid.
[1136]248
[1426]249        /// Initialize the iterator to be invalid.
250        ///
251        OutEdgeIt(Invalid) { }
252        /// This constructor sets the iterator to the first outgoing edge.
[1136]253   
[1426]254        /// This constructor sets the iterator to the first outgoing edge of
255        /// the node.
[2111]256        OutEdgeIt(const Graph&, const Node&) { }
[1426]257        /// Edge -> OutEdgeIt conversion
[1136]258
[1470]259        /// Sets the iterator to the value of the trivial iterator.
260        /// This feature necessitates that each time we
[1426]261        /// iterate the edge-set, the iteration order is the same.
[2111]262        OutEdgeIt(const Graph&, const Edge&) { }
[1426]263        ///Next outgoing edge
264       
265        /// Assign the iterator to the next
266        /// outgoing edge of the corresponding node.
267        OutEdgeIt& operator++() { return *this; }
[1136]268      };
269
270      /// This iterator goes trough the incoming edges of a node.
271
272      /// This iterator goes trough the \e incoming edges of a certain node
273      /// of a graph.
274      /// Its usage is quite simple, for example you can count the number
275      /// of outgoing edges of a node \c n
276      /// in graph \c g of type \c Graph as follows.
[1946]277      ///\code
[1136]278      /// int count=0;
279      /// for(Graph::InEdgeIt e(g, n); e!=INVALID; ++e) ++count;
[1946]280      ///\endcode
[1136]281
282      class InEdgeIt : public Edge {
283      public:
[1426]284        /// Default constructor
[1136]285
[1426]286        /// @warning The default constructor sets the iterator
287        /// to an undefined value.
288        InEdgeIt() { }
289        /// Copy constructor.
[1136]290
[1426]291        /// Copy constructor.
292        ///
293        InEdgeIt(const InEdgeIt& e) : Edge(e) { }
294        /// Initialize the iterator to be invalid.
[1136]295
[1426]296        /// Initialize the iterator to be invalid.
297        ///
298        InEdgeIt(Invalid) { }
299        /// This constructor sets the iterator to first incoming edge.
[1136]300   
[1426]301        /// This constructor set the iterator to the first incoming edge of
302        /// the node.
[2111]303        InEdgeIt(const Graph&, const Node&) { }
[1426]304        /// Edge -> InEdgeIt conversion
[1136]305
[1426]306        /// Sets the iterator to the value of the trivial iterator \c e.
307        /// This feature necessitates that each time we
308        /// iterate the edge-set, the iteration order is the same.
[2111]309        InEdgeIt(const Graph&, const Edge&) { }
[1426]310        /// Next incoming edge
[1136]311
[1426]312        /// Assign the iterator to the next inedge of the corresponding node.
313        ///
314        InEdgeIt& operator++() { return *this; }
[1136]315      };
316      /// This iterator goes through each edge.
317
318      /// This iterator goes through each edge of a graph.
319      /// Its usage is quite simple, for example you can count the number
320      /// of edges in a graph \c g of type \c Graph as follows:
[1946]321      ///\code
[1136]322      /// int count=0;
323      /// for(Graph::EdgeIt e(g); e!=INVALID; ++e) ++count;
[1946]324      ///\endcode
[1136]325      class EdgeIt : public Edge {
326      public:
[1426]327        /// Default constructor
[1136]328
[1426]329        /// @warning The default constructor sets the iterator
330        /// to an undefined value.
331        EdgeIt() { }
332        /// Copy constructor.
[1136]333
[1426]334        /// Copy constructor.
335        ///
336        EdgeIt(const EdgeIt& e) : Edge(e) { }
337        /// Initialize the iterator to be invalid.
[1136]338
[1426]339        /// Initialize the iterator to be invalid.
340        ///
341        EdgeIt(Invalid) { }
342        /// This constructor sets the iterator to the first edge.
[1136]343   
[1426]344        /// This constructor sets the iterator to the first edge of \c g.
345        ///@param g the graph
[2111]346        EdgeIt(const Graph& g) { ignore_unused_variable_warning(g); }
[1426]347        /// Edge -> EdgeIt conversion
[1136]348
[1426]349        /// Sets the iterator to the value of the trivial iterator \c e.
350        /// This feature necessitates that each time we
351        /// iterate the edge-set, the iteration order is the same.
[2111]352        EdgeIt(const Graph&, const Edge&) { }
[1426]353        ///Next edge
354       
355        /// Assign the iterator to the next edge.
356        EdgeIt& operator++() { return *this; }
[1136]357      };
358      ///Gives back the target node of an edge.
359
360      ///Gives back the target node of an edge.
361      ///
362      Node target(Edge) const { return INVALID; }
363      ///Gives back the source node of an edge.
364
365      ///Gives back the source node of an edge.
366      ///
367      Node source(Edge) const { return INVALID; }
[1563]368
369      void first(Node&) const {}
370      void next(Node&) const {}
371
372      void first(Edge&) const {}
373      void next(Edge&) const {}
374
375
376      void firstIn(Edge&, const Node&) const {}
377      void nextIn(Edge&) const {}
378
379      void firstOut(Edge&, const Node&) const {}
380      void nextOut(Edge&) const {}
381
382      /// \brief The base node of the iterator.
383      ///
384      /// Gives back the base node of the iterator.
[1627]385      /// It is always the target of the pointed edge.
[1563]386      Node baseNode(const InEdgeIt&) const { return INVALID; }
387
388      /// \brief The running node of the iterator.
389      ///
390      /// Gives back the running node of the iterator.
[1627]391      /// It is always the source of the pointed edge.
[1563]392      Node runningNode(const InEdgeIt&) const { return INVALID; }
393
394      /// \brief The base node of the iterator.
395      ///
396      /// Gives back the base node of the iterator.
[1627]397      /// It is always the source of the pointed edge.
[1563]398      Node baseNode(const OutEdgeIt&) const { return INVALID; }
399
400      /// \brief The running node of the iterator.
401      ///
402      /// Gives back the running node of the iterator.
[1627]403      /// It is always the target of the pointed edge.
[1563]404      Node runningNode(const OutEdgeIt&) const { return INVALID; }
[1136]405
[1627]406      /// \brief The opposite node on the given edge.
407      ///
408      /// Gives back the opposite node on the given edge.
409      Node oppositeNode(const Node&, const Edge&) const { return INVALID; }
410
411      /// \brief Read write map of the nodes to type \c T.
412      ///
[1136]413      /// ReadWrite map of the nodes to type \c T.
414      /// \sa Reference
415      /// \warning Making maps that can handle bool type (NodeMap<bool>)
416      /// needs some extra attention!
[1630]417      /// \todo Wrong documentation
[1136]418      template<class T>
419      class NodeMap : public ReadWriteMap< Node, T >
420      {
421      public:
422
[1426]423        ///\e
[2111]424        NodeMap(const Graph&) { }
[1426]425        ///\e
[2111]426        NodeMap(const Graph&, T) { }
[1136]427
[1426]428        ///Copy constructor
429        NodeMap(const NodeMap& nm) : ReadWriteMap< Node, T >(nm) { }
430        ///Assignment operator
431        NodeMap& operator=(const NodeMap&) { return *this; }
432        // \todo fix this concept
[1136]433      };
434
[1627]435      /// \brief Read write map of the edges to type \c T.
436      ///
437      /// Reference map of the edges to type \c T.
[1136]438      /// \sa Reference
439      /// \warning Making maps that can handle bool type (EdgeMap<bool>)
440      /// needs some extra attention!
[1630]441      /// \todo Wrong documentation
[1136]442      template<class T>
443      class EdgeMap : public ReadWriteMap<Edge,T>
444      {
445      public:
446
[1426]447        ///\e
[2111]448        EdgeMap(const Graph&) { }
[1426]449        ///\e
[2111]450        EdgeMap(const Graph&, T) { }
[1426]451        ///Copy constructor
452        EdgeMap(const EdgeMap& em) : ReadWriteMap<Edge,T>(em) { }
453        ///Assignment operator
454        EdgeMap& operator=(const EdgeMap&) { return *this; }
455        // \todo fix this concept   
[1136]456      };
457
[2111]458      template <typename RGraph>
459      struct Constraints : public _Graph::Constraints<RGraph> {};
[1136]460
461    };
462   
[959]463    // @}
464  } //namespace concept 
465} //namespace lemon
466
467
468
469#endif // LEMON_CONCEPT_GRAPH_H
Note: See TracBrowser for help on using the repository browser.