COIN-OR::LEMON - Graph Library

About

Downloads

Documentation

Development

Issue Tracker

Browse Tickets

Custom Query

Roadmap

Browse Source

Local Info

Mailing Lists

Search


Ignore:
File:
1 edited

Legend:

Unmodified
Added
Removed

  • lemon/concepts/digraph.h

    r877 r580  
    33 * This file is a part of LEMON, a generic C++ optimization library.
    44 *
    5  * Copyright (C) 2003-2010
     5 * Copyright (C) 2003-2009
    66 * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
    77 * (Egervary Research Group on Combinatorial Optimization, EGRES).
    … …  
    3636    /// \brief Class describing the concept of directed graphs.
    3737    ///
    38     /// This class describes the common interface of all directed
    39     /// graphs (digraphs).
     38    /// This class describes the \ref concept "concept" of the
     39    /// immutable directed digraphs.
    4040    ///
    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.
     41    /// Note that actual digraph implementation like @ref ListDigraph or
     42    /// @ref SmartDigraph may have several additional functionality.
    4743    ///
    48     /// \sa Graph
     44    /// \sa concept
    4945    class Digraph {
    5046    private:
    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.
     47      ///Digraphs are \e not copy constructible. Use DigraphCopy() instead.
     48
     49      ///Digraphs are \e not copy constructible. Use DigraphCopy() instead.
     50      ///
     51      Digraph(const Digraph &) {};
     52      ///\brief Assignment of \ref Digraph "Digraph"s to another ones are
     53      ///\e not allowed. Use DigraphCopy() instead.
     54
     55      ///Assignment of \ref Digraph "Digraph"s to another ones are
     56      ///\e not allowed.  Use DigraphCopy() instead.
     57
    5558      void operator=(const Digraph &) {}
    56 
    5759    public:
    58       /// Default constructor.
     60      ///\e
     61
     62      /// Defalult constructor.
     63
     64      /// Defalult constructor.
     65      ///
    5966      Digraph() { }
    60 
    61       /// The node type of the digraph
     67      /// Class for identifying a node of the digraph
    6268
    6369      /// This class identifies a node of the digraph. It also serves
    6470      /// as a base class of the node iterators,
    65       /// thus they convert to this type.
     71      /// thus they will convert to this type.
    6672      class Node {
    6773      public:
    6874        /// Default constructor
    6975
    70         /// Default constructor.
    71         /// \warning It sets the object to an undefined value.
     76        /// @warning The default constructor sets the iterator
     77        /// to an undefined value.
    7278        Node() { }
    7379        /// Copy constructor.
    … …  
    7783        Node(const Node&) { }
    7884
    79         /// %Invalid constructor \& conversion.
    80 
    81         /// Initializes the object to be invalid.
     85        /// Invalid constructor \& conversion.
     86
     87        /// This constructor initializes the iterator to be invalid.
    8288        /// \sa Invalid for more details.
    8389        Node(Invalid) { }
    8490        /// Equality operator
    8591
    86         /// Equality operator.
    87         ///
    8892        /// Two iterators are equal if and only if they point to the
    89         /// same object or both are \c INVALID.
     93        /// same object or both are invalid.
    9094        bool operator==(Node) const { return true; }
    9195
    9296        /// Inequality operator
    9397
    94         /// Inequality operator.
     98        /// \sa operator==(Node n)
     99        ///
    95100        bool operator!=(Node) const { return true; }
    96101
    97102        /// Artificial ordering operator.
    98103
    99         /// Artificial ordering operator.
    100         ///
    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.
     104        /// To allow the use of digraph descriptors as key type in std::map or
     105        /// similar associative container we require this.
     106        ///
     107        /// \note This operator only have to define some strict ordering of
     108        /// the items; this order has nothing to do with the iteration
     109        /// ordering of the items.
    104110        bool operator<(Node) const { return false; }
    105       };
    106 
    107       /// Iterator class for the nodes.
    108 
    109       /// This iterator goes through each node of the digraph.
    110       /// Its usage is quite simple, for example, you can count the number
    111       /// of nodes in a digraph \c g of type \c %Digraph like this:
     111
     112      };
     113
     114      /// This iterator goes through each node.
     115
     116      /// This iterator goes through each node.
     117      /// Its usage is quite simple, for example you can count the number
     118      /// of nodes in digraph \c g of type \c Digraph like this:
    112119      ///\code
    113120      /// int count=0;
    … …  
    118125        /// Default constructor
    119126
    120         /// Default constructor.
    121         /// \warning It sets the iterator to an undefined value.
     127        /// @warning The default constructor sets the iterator
     128        /// to an undefined value.
    122129        NodeIt() { }
    123130        /// Copy constructor.
    … …  
    126133        ///
    127134        NodeIt(const NodeIt& n) : Node(n) { }
    128         /// %Invalid constructor \& conversion.
    129 
    130         /// Initializes the iterator to be invalid.
     135        /// Invalid constructor \& conversion.
     136
     137        /// Initialize the iterator to be invalid.
    131138        /// \sa Invalid for more details.
    132139        NodeIt(Invalid) { }
    133140        /// Sets the iterator to the first node.
    134141
    135         /// Sets the iterator to the first node of the given digraph.
    136         ///
    137         explicit NodeIt(const Digraph&) { }
    138         /// Sets the iterator to the given node.
    139 
    140         /// Sets the iterator to the given node of the given digraph.
    141         ///
     142        /// Sets the iterator to the first node of \c g.
     143        ///
     144        NodeIt(const Digraph&) { }
     145        /// Node -> NodeIt conversion.
     146
     147        /// Sets the iterator to the node of \c the digraph pointed by
     148        /// the trivial iterator.
     149        /// This feature necessitates that each time we
     150        /// iterate the arc-set, the iteration order is the same.
    142151        NodeIt(const Digraph&, const Node&) { }
    143152        /// Next node.
    … …  
    149158
    150159
    151       /// The arc type of the digraph
     160      /// Class for identifying an arc of the digraph
    152161
    153162      /// This class identifies an arc of the digraph. It also serves
    … …  
    158167        /// Default constructor
    159168
    160         /// Default constructor.
    161         /// \warning It sets the object to an undefined value.
     169        /// @warning The default constructor sets the iterator
     170        /// to an undefined value.
    162171        Arc() { }
    163172        /// Copy constructor.
    … …  
    166175        ///
    167176        Arc(const Arc&) { }
    168         /// %Invalid constructor \& conversion.
    169 
    170         /// Initializes the object to be invalid.
    171         /// \sa Invalid for more details.
     177        /// Initialize the iterator to be invalid.
     178
     179        /// Initialize the iterator to be invalid.
     180        ///
    172181        Arc(Invalid) { }
    173182        /// Equality operator
    174183
    175         /// Equality operator.
    176         ///
    177184        /// Two iterators are equal if and only if they point to the
    178         /// same object or both are \c INVALID.
     185        /// same object or both are invalid.
    179186        bool operator==(Arc) const { return true; }
    180187        /// Inequality operator
    181188
    182         /// Inequality operator.
     189        /// \sa operator==(Arc n)
     190        ///
    183191        bool operator!=(Arc) const { return true; }
    184192
    185193        /// Artificial ordering operator.
    186194
    187         /// Artificial ordering operator.
    188         ///
    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.
     195        /// To allow the use of digraph descriptors as key type in std::map or
     196        /// similar associative container we require this.
     197        ///
     198        /// \note This operator only have to define some strict ordering of
     199        /// the items; this order has nothing to do with the iteration
     200        /// ordering of the items.
    192201        bool operator<(Arc) const { return false; }
    193202      };
    194203
    195       /// Iterator class for the outgoing arcs of a node.
     204      /// This iterator goes trough the outgoing arcs of a node.
    196205
    197206      /// This iterator goes trough the \e outgoing arcs of a certain node
    198207      /// of a digraph.
    199       /// Its usage is quite simple, for example, you can count the number
     208      /// Its usage is quite simple, for example you can count the number
    200209      /// of outgoing arcs of a node \c n
    201       /// in a digraph \c g of type \c %Digraph as follows.
     210      /// in digraph \c g of type \c Digraph as follows.
    202211      ///\code
    203212      /// int count=0;
    204       /// for (Digraph::OutArcIt a(g, n); a!=INVALID; ++a) ++count;
     213      /// for (Digraph::OutArcIt e(g, n); e!=INVALID; ++e) ++count;
    205214      ///\endcode
     215
    206216      class OutArcIt : public Arc {
    207217      public:
    208218        /// Default constructor
    209219
    210         /// Default constructor.
    211         /// \warning It sets the iterator to an undefined value.
     220        /// @warning The default constructor sets the iterator
     221        /// to an undefined value.
    212222        OutArcIt() { }
    213223        /// Copy constructor.
    … …  
    216226        ///
    217227        OutArcIt(const OutArcIt& e) : Arc(e) { }
    218         /// %Invalid constructor \& conversion.
    219 
    220         /// Initializes the iterator to be invalid.
    221         /// \sa Invalid for more details.
     228        /// Initialize the iterator to be invalid.
     229
     230        /// Initialize the iterator to be invalid.
     231        ///
    222232        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.
    226         ///
     233        /// This constructor sets the iterator to the first outgoing arc.
     234
     235        /// This constructor sets the iterator to the first outgoing arc of
     236        /// the node.
    227237        OutArcIt(const Digraph&, const Node&) { }
    228         /// Sets the iterator to the given arc.
    229 
    230         /// Sets the iterator to the given arc of the given digraph.
    231         ///
     238        /// Arc -> OutArcIt conversion
     239
     240        /// Sets the iterator to the value of the trivial iterator.
     241        /// This feature necessitates that each time we
     242        /// iterate the arc-set, the iteration order is the same.
    232243        OutArcIt(const Digraph&, const Arc&) { }
    233         /// Next outgoing arc
     244        ///Next outgoing arc
    234245
    235246        /// Assign the iterator to the next
    … …  
    238249      };
    239250
    240       /// Iterator class for the incoming arcs of a node.
     251      /// This iterator goes trough the incoming arcs of a node.
    241252
    242253      /// This iterator goes trough the \e incoming arcs of a certain node
    243254      /// of a digraph.
    244       /// Its usage is quite simple, for example, you can count the number
    245       /// of incoming arcs of a node \c n
    246       /// in a digraph \c g of type \c %Digraph as follows.
     255      /// Its usage is quite simple, for example you can count the number
     256      /// of outgoing arcs of a node \c n
     257      /// in digraph \c g of type \c Digraph as follows.
    247258      ///\code
    248259      /// int count=0;
    249       /// for(Digraph::InArcIt a(g, n); a!=INVALID; ++a) ++count;
     260      /// for(Digraph::InArcIt e(g, n); e!=INVALID; ++e) ++count;
    250261      ///\endcode
     262
    251263      class InArcIt : public Arc {
    252264      public:
    253265        /// Default constructor
    254266
    255         /// Default constructor.
    256         /// \warning It sets the iterator to an undefined value.
     267        /// @warning The default constructor sets the iterator
     268        /// to an undefined value.
    257269        InArcIt() { }
    258270        /// Copy constructor.
    … …  
    261273        ///
    262274        InArcIt(const InArcIt& e) : Arc(e) { }
    263         /// %Invalid constructor \& conversion.
    264 
    265         /// Initializes the iterator to be invalid.
    266         /// \sa Invalid for more details.
     275        /// Initialize the iterator to be invalid.
     276
     277        /// Initialize the iterator to be invalid.
     278        ///
    267279        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.
    271         ///
     280        /// This constructor sets the iterator to first incoming arc.
     281
     282        /// This constructor set the iterator to the first incoming arc of
     283        /// the node.
    272284        InArcIt(const Digraph&, const Node&) { }
    273         /// Sets the iterator to the given arc.
    274 
    275         /// Sets the iterator to the given arc of the given digraph.
    276         ///
     285        /// Arc -> InArcIt conversion
     286
     287        /// Sets the iterator to the value of the trivial iterator \c e.
     288        /// This feature necessitates that each time we
     289        /// iterate the arc-set, the iteration order is the same.
    277290        InArcIt(const Digraph&, const Arc&) { }
    278291        /// Next incoming arc
    279292
    280         /// Assign the iterator to the next
    281         /// incoming arc of the corresponding node.
     293        /// Assign the iterator to the next inarc of the corresponding node.
     294        ///
    282295        InArcIt& operator++() { return *this; }
    283296      };
    284 
    285       /// Iterator class for the arcs.
    286 
    287       /// This iterator goes through each arc of the digraph.
    288       /// Its usage is quite simple, for example, you can count the number
    289       /// of arcs in a digraph \c g of type \c %Digraph as follows:
     297      /// This iterator goes through each arc.
     298
     299      /// This iterator goes through each arc of a digraph.
     300      /// Its usage is quite simple, for example you can count the number
     301      /// of arcs in a digraph \c g of type \c Digraph as follows:
    290302      ///\code
    291303      /// int count=0;
    292       /// for(Digraph::ArcIt a(g); a!=INVALID; ++a) ++count;
     304      /// for(Digraph::ArcIt e(g); e!=INVALID; ++e) ++count;
    293305      ///\endcode
    294306      class ArcIt : public Arc {
    … …  
    296308        /// Default constructor
    297309
    298         /// Default constructor.
    299         /// \warning It sets the iterator to an undefined value.
     310        /// @warning The default constructor sets the iterator
     311        /// to an undefined value.
    300312        ArcIt() { }
    301313        /// Copy constructor.
    … …  
    304316        ///
    305317        ArcIt(const ArcIt& e) : Arc(e) { }
    306         /// %Invalid constructor \& conversion.
    307 
    308         /// Initializes the iterator to be invalid.
    309         /// \sa Invalid for more details.
     318        /// Initialize the iterator to be invalid.
     319
     320        /// Initialize the iterator to be invalid.
     321        ///
    310322        ArcIt(Invalid) { }
    311         /// Sets the iterator to the first arc.
    312 
    313         /// Sets the iterator to the first arc of the given digraph.
    314         ///
    315         explicit ArcIt(const Digraph& g) { ignore_unused_variable_warning(g); }
    316         /// Sets the iterator to the given arc.
    317 
    318         /// Sets the iterator to the given arc of the given digraph.
    319         ///
     323        /// This constructor sets the iterator to the first arc.
     324
     325        /// This constructor sets the iterator to the first arc of \c g.
     326        ///@param g the digraph
     327        ArcIt(const Digraph& g) { ignore_unused_variable_warning(g); }
     328        /// Arc -> ArcIt conversion
     329
     330        /// Sets the iterator to the value of the trivial iterator \c e.
     331        /// This feature necessitates that each time we
     332        /// iterate the arc-set, the iteration order is the same.
    320333        ArcIt(const Digraph&, const Arc&) { }
    321         /// Next arc
     334        ///Next arc
    322335
    323336        /// Assign the iterator to the next arc.
    324         ///
    325337        ArcIt& operator++() { return *this; }
    326338      };
    327 
    328       /// \brief The source node of the arc.
    329       ///
    330       /// Returns the source node of the given arc.
     339      ///Gives back the target node of an arc.
     340
     341      ///Gives back the target node of an arc.
     342      ///
     343      Node target(Arc) const { return INVALID; }
     344      ///Gives back the source node of an arc.
     345
     346      ///Gives back the source node of an arc.
     347      ///
    331348      Node source(Arc) const { return INVALID; }
    332349
    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.
     350      /// \brief Returns the ID of the node.
    341351      int id(Node) const { return -1; }
    342352
    343       /// \brief The ID of the arc.
    344       ///
    345       /// Returns the ID of the given arc.
     353      /// \brief Returns the ID of the arc.
    346354      int id(Arc) const { return -1; }
    347355
    348       /// \brief The node with the given ID.
    349       ///
    350       /// Returns the node with the given ID.
    351       /// \pre The argument should be a valid node ID in the digraph.
     356      /// \brief Returns the node with the given ID.
     357      ///
     358      /// \pre The argument should be a valid node ID in the graph.
    352359      Node nodeFromId(int) const { return INVALID; }
    353360
    354       /// \brief The arc with the given ID.
    355       ///
    356       /// Returns the arc with the given ID.
    357       /// \pre The argument should be a valid arc ID in the digraph.
     361      /// \brief Returns the arc with the given ID.
     362      ///
     363      /// \pre The argument should be a valid arc ID in the graph.
    358364      Arc arcFromId(int) const { return INVALID; }
    359365
    360       /// \brief An upper bound on the node IDs.
    361       ///
    362       /// Returns an upper bound on the node IDs.
     366      /// \brief Returns an upper bound on the node IDs.
    363367      int maxNodeId() const { return -1; }
    364368
    365       /// \brief An upper bound on the arc IDs.
    366       ///
    367       /// Returns an upper bound on the arc IDs.
     369      /// \brief Returns an upper bound on the arc IDs.
    368370      int maxArcId() const { return -1; }
    369371
    … …  
    391393      int maxId(Arc) const { return -1; }
    392394
    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 
    398395      /// \brief The base node of the iterator.
    399396      ///
    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; }
     397      /// Gives back the base node of the iterator.
     398      /// It is always the target of the pointed arc.
     399      Node baseNode(const InArcIt&) const { return INVALID; }
    403400
    404401      /// \brief The running node of the iterator.
    405402      ///
    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; }
     403      /// Gives back the running node of the iterator.
     404      /// It is always the source of the pointed arc.
     405      Node runningNode(const InArcIt&) const { return INVALID; }
    409406
    410407      /// \brief The base node of the iterator.
    411408      ///
    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; }
     409      /// Gives back the base node of the iterator.
     410      /// It is always the source of the pointed arc.
     411      Node baseNode(const OutArcIt&) const { return INVALID; }
    415412
    416413      /// \brief The running node of the iterator.
    417414      ///
    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; }
    421 
    422       /// \brief Standard graph map type for the nodes.
    423       ///
    424       /// Standard graph map type for the nodes.
    425       /// It conforms to the ReferenceMap concept.
     415      /// Gives back the running node of the iterator.
     416      /// It is always the target of the pointed arc.
     417      Node runningNode(const OutArcIt&) const { return INVALID; }
     418
     419      /// \brief The opposite node on the given arc.
     420      ///
     421      /// Gives back the opposite node on the given arc.
     422      Node oppositeNode(const Node&, const Arc&) const { return INVALID; }
     423
     424      /// \brief Reference map of the nodes to type \c T.
     425      ///
     426      /// Reference map of the nodes to type \c T.
    426427      template<class T>
    427428      class NodeMap : public ReferenceMap<Node, T, T&, const T&> {
    428429      public:
    429430
    430         /// Constructor
    431         explicit NodeMap(const Digraph&) { }
    432         /// Constructor with given initial value
     431        ///\e
     432        NodeMap(const Digraph&) { }
     433        ///\e
    433434        NodeMap(const Digraph&, T) { }
    434435
    435436      private:
    436437        ///Copy constructor
    437         NodeMap(const NodeMap& nm) :
     438        NodeMap(const NodeMap& nm) : 
    438439          ReferenceMap<Node, T, T&, const T&>(nm) { }
    439440        ///Assignment operator
    … …  
    445446      };
    446447
    447       /// \brief Standard graph map type for the arcs.
    448       ///
    449       /// Standard graph map type for the arcs.
    450       /// It conforms to the ReferenceMap concept.
     448      /// \brief Reference map of the arcs to type \c T.
     449      ///
     450      /// Reference map of the arcs to type \c T.
    451451      template<class T>
    452452      class ArcMap : public ReferenceMap<Arc, T, T&, const T&> {
    453453      public:
    454454
    455         /// Constructor
    456         explicit ArcMap(const Digraph&) { }
    457         /// Constructor with given initial value
     455        ///\e
     456        ArcMap(const Digraph&) { }
     457        ///\e
    458458        ArcMap(const Digraph&, T) { }
    459 
    460459      private:
    461460        ///Copy constructor
Note: See TracChangeset for help on using the changeset viewer.