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, 13 years ago
  • Revised "Concepts" group documentation
  • Other minor doc improvements
File size: 14.3 KB
Line 
1/* -*- C++ -*-
2 *
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
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
19#ifndef LEMON_CONCEPT_GRAPH_H
20#define LEMON_CONCEPT_GRAPH_H
21
22///\ingroup graph_concepts
23///\file
24///\brief Declaration of Graph.
25
26#include <lemon/bits/invalid.h>
27#include <lemon/bits/utility.h>
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 {
34
35   
36    /**************** The full-featured graph concepts ****************/
37
38
39    // \brief Modular static graph class.
40    //     
41    // It should be the same as the \c Graph class.
42    class _Graph
43      :  virtual public BaseGraphComponent,
44         public IterableGraphComponent, public MappableGraphComponent {
45    public:
46
47      typedef BaseGraphComponent::Node Node;
48      typedef BaseGraphComponent::Edge Edge;
49
50      template <typename _Graph>
51      struct Constraints {
52        void constraints() {
53          checkConcept<IterableGraphComponent, _Graph>();
54          checkConcept<MappableGraphComponent, _Graph>();
55        }
56      };
57    };
58
59    /// \addtogroup graph_concepts
60    /// @{
61
62    /// The directed graph concept
63
64    /// This class describes the \ref concept "concept" of the
65    /// immutable directed graphs.
66    ///
67    /// Note that actual graph implementation like @ref ListGraph or
68    /// @ref SmartGraph may have several additional functionality.
69    ///
70    /// \sa concept
71    class Graph {
72    public:
73      ///\e
74
75      /// Defalult constructor.
76
77      /// Defalult constructor.
78      ///
79      Graph() { }
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:
90        /// Default constructor
91
92        /// @warning The default constructor sets the iterator
93        /// to an undefined value.
94        Node() { }
95        /// Copy constructor.
96
97        /// Copy constructor.
98        ///
99        Node(const Node&) { }
100
101        /// Invalid constructor \& conversion.
102
103        /// This constructor initializes the iterator to be invalid.
104        /// \sa Invalid for more details.
105        Node(Invalid) { }
106        /// Equality operator
107
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; }
111
112        /// Inequality operator
113       
114        /// \sa operator==(Node n)
115        ///
116        bool operator!=(Node) const { return true; }
117
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
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:
137      ///\code
138      /// int count=0;
139      /// for (Graph::NodeIt n(g); n!=INVALID; ++n) ++count;
140      ///\endcode
141      class NodeIt : public Node {
142      public:
143        /// Default constructor
144
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.
154
155        /// Initialize the iterator to be invalid.
156        /// \sa Invalid for more details.
157        NodeIt(Invalid) { }
158        /// Sets the iterator to the first node.
159
160        /// Sets the iterator to the first node of \c g.
161        ///
162        NodeIt(const Graph&) { }
163        /// Node -> NodeIt conversion.
164
165        /// Sets the iterator to the node of \c the graph pointed by
166        /// the trivial iterator.
167        /// This feature necessitates that each time we
168        /// iterate the edge-set, the iteration order is the same.
169        NodeIt(const Graph&, const Node&) { }
170        /// Next node.
171
172        /// Assign the iterator to the next node.
173        ///
174        NodeIt& operator++() { return *this; }
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:
184        /// Default constructor
185
186        /// @warning The default constructor sets the iterator
187        /// to an undefined value.
188        Edge() { }
189        /// Copy constructor.
190
191        /// Copy constructor.
192        ///
193        Edge(const Edge&) { }
194        /// Initialize the iterator to be invalid.
195
196        /// Initialize the iterator to be invalid.
197        ///
198        Edge(Invalid) { }
199        /// Equality operator
200
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
205
206        /// \sa operator==(Edge n)
207        ///
208        bool operator!=(Edge) const { return true; }
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; }
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.
230      ///\code
231      /// int count=0;
232      /// for (Graph::OutEdgeIt e(g, n); e!=INVALID; ++e) ++count;
233      ///\endcode
234   
235      class OutEdgeIt : public Edge {
236      public:
237        /// Default constructor
238
239        /// @warning The default constructor sets the iterator
240        /// to an undefined value.
241        OutEdgeIt() { }
242        /// Copy constructor.
243
244        /// Copy constructor.
245        ///
246        OutEdgeIt(const OutEdgeIt& e) : Edge(e) { }
247        /// Initialize the iterator to be invalid.
248
249        /// Initialize the iterator to be invalid.
250        ///
251        OutEdgeIt(Invalid) { }
252        /// This constructor sets the iterator to the first outgoing edge.
253   
254        /// This constructor sets the iterator to the first outgoing edge of
255        /// the node.
256        OutEdgeIt(const Graph&, const Node&) { }
257        /// Edge -> OutEdgeIt conversion
258
259        /// Sets the iterator to the value of the trivial iterator.
260        /// This feature necessitates that each time we
261        /// iterate the edge-set, the iteration order is the same.
262        OutEdgeIt(const Graph&, const Edge&) { }
263        ///Next outgoing edge
264       
265        /// Assign the iterator to the next
266        /// outgoing edge of the corresponding node.
267        OutEdgeIt& operator++() { return *this; }
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.
277      ///\code
278      /// int count=0;
279      /// for(Graph::InEdgeIt e(g, n); e!=INVALID; ++e) ++count;
280      ///\endcode
281
282      class InEdgeIt : public Edge {
283      public:
284        /// Default constructor
285
286        /// @warning The default constructor sets the iterator
287        /// to an undefined value.
288        InEdgeIt() { }
289        /// Copy constructor.
290
291        /// Copy constructor.
292        ///
293        InEdgeIt(const InEdgeIt& e) : Edge(e) { }
294        /// Initialize the iterator to be invalid.
295
296        /// Initialize the iterator to be invalid.
297        ///
298        InEdgeIt(Invalid) { }
299        /// This constructor sets the iterator to first incoming edge.
300   
301        /// This constructor set the iterator to the first incoming edge of
302        /// the node.
303        InEdgeIt(const Graph&, const Node&) { }
304        /// Edge -> InEdgeIt conversion
305
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.
309        InEdgeIt(const Graph&, const Edge&) { }
310        /// Next incoming edge
311
312        /// Assign the iterator to the next inedge of the corresponding node.
313        ///
314        InEdgeIt& operator++() { return *this; }
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:
321      ///\code
322      /// int count=0;
323      /// for(Graph::EdgeIt e(g); e!=INVALID; ++e) ++count;
324      ///\endcode
325      class EdgeIt : public Edge {
326      public:
327        /// Default constructor
328
329        /// @warning The default constructor sets the iterator
330        /// to an undefined value.
331        EdgeIt() { }
332        /// Copy constructor.
333
334        /// Copy constructor.
335        ///
336        EdgeIt(const EdgeIt& e) : Edge(e) { }
337        /// Initialize the iterator to be invalid.
338
339        /// Initialize the iterator to be invalid.
340        ///
341        EdgeIt(Invalid) { }
342        /// This constructor sets the iterator to the first edge.
343   
344        /// This constructor sets the iterator to the first edge of \c g.
345        ///@param g the graph
346        EdgeIt(const Graph& g) { ignore_unused_variable_warning(g); }
347        /// Edge -> EdgeIt conversion
348
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.
352        EdgeIt(const Graph&, const Edge&) { }
353        ///Next edge
354       
355        /// Assign the iterator to the next edge.
356        EdgeIt& operator++() { return *this; }
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; }
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.
385      /// It is always the target of the pointed edge.
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.
391      /// It is always the source of the pointed edge.
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.
397      /// It is always the source of the pointed edge.
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.
403      /// It is always the target of the pointed edge.
404      Node runningNode(const OutEdgeIt&) const { return INVALID; }
405
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      ///
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!
417      /// \todo Wrong documentation
418      template<class T>
419      class NodeMap : public ReadWriteMap< Node, T >
420      {
421      public:
422
423        ///\e
424        NodeMap(const Graph&) { }
425        ///\e
426        NodeMap(const Graph&, T) { }
427
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
433      };
434
435      /// \brief Read write map of the edges to type \c T.
436      ///
437      /// Reference map of the edges to type \c T.
438      /// \sa Reference
439      /// \warning Making maps that can handle bool type (EdgeMap<bool>)
440      /// needs some extra attention!
441      /// \todo Wrong documentation
442      template<class T>
443      class EdgeMap : public ReadWriteMap<Edge,T>
444      {
445      public:
446
447        ///\e
448        EdgeMap(const Graph&) { }
449        ///\e
450        EdgeMap(const Graph&, T) { }
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   
456      };
457
458      template <typename RGraph>
459      struct Constraints : public _Graph::Constraints<RGraph> {};
460
461    };
462   
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.