COIN-OR::LEMON - Graph Library

Ticket #169: impr_f58410582b9b.patch

File impr_f58410582b9b.patch, 14.5 KB (added by Peter Kovacs, 16 years ago)
  • lemon/bits/alteration_notifier.h

    # HG changeset patch
    # User Peter Kovacs <kpeter@inf.elte.hu>
    # Date 1225831079 -3600
    # Node ID f58410582b9bac22c553618b60d5fce2ad4e89ab
    # Parent  75cf49ce539059c67130b03592325fcbd5e4f96c
    Doc improvements for the graph related tools in lemon/bits
    
    diff --git a/lemon/bits/alteration_notifier.h b/lemon/bits/alteration_notifier.h
    a b  
    3535  // \brief Notifier class to notify observes about alterations in
    3636  // a container.
    3737  //
    38   // The simple graph's can be refered as two containers, one node container
    39   // and one edge container. But they are not standard containers they
    40   // does not store values directly they are just key continars for more
    41   // value containers which are the node and edge maps.
     38  // The simple graphs can be refered as two containers: a node container
     39  // and an edge container. But they do not store values directly, they
     40  // are just key continars for more value containers, which are the
     41  // node and edge maps.
    4242  //
    43   // The graph's node and edge sets can be changed as we add or erase
     43  // The node and edge sets of the graphs can be changed as we add or erase
    4444  // nodes and edges in the graph. LEMON would like to handle easily
    4545  // that the node and edge maps should contain values for all nodes or
    4646  // edges. If we want to check on every indicing if the map contains
    4747  // the current indicing key that cause a drawback in the performance
    48   // in the library. We use another solution we notify all maps about
     48  // in the library. We use another solution: we notify all maps about
    4949  // an alteration in the graph, which cause only drawback on the
    5050  // alteration of the graph.
    5151  //
    52   // This class provides an interface to the container. The \e first() and \e
    53   // next() member functions make possible to iterate on the keys of the
    54   // container. The \e id() function returns an integer id for each key.
    55   // The \e maxId() function gives back an upper bound of the ids.
     52  // This class provides an interface to a node or edge container.
     53  // The first() and next() member functions make possible
     54  // to iterate on the keys of the container.
     55  // The id() function returns an integer id for each key.
     56  // The maxId() function gives back an upper bound of the ids.
    5657  //
    5758  // For the proper functonality of this class, we should notify it
    58   // about each alteration in the container. The alterations have four type
    59   // as \e add(), \e erase(), \e build() and \e clear(). The \e add() and
    60   // \e erase() signals that only one or few items added or erased to or
    61   // from the graph. If all items are erased from the graph or from an empty
    62   // graph a new graph is builded then it can be signaled with the
     59  // about each alteration in the container. The alterations have four type:
     60  // add(), erase(), build() and clear(). The add() and
     61  // erase() signal that only one or few items added or erased to or
     62  // from the graph. If all items are erased from the graph or if a new graph
     63  // is built from an empty graph, then it can be signaled with the
    6364  // clear() and build() members. Important rule that if we erase items
    64   // from graph we should first signal the alteration and after that erase
     65  // from graphs we should first signal the alteration and after that erase
    6566  // them from the container, on the other way on item addition we should
    6667  // first extend the container and just after that signal the alteration.
    6768  //
    6869  // The alteration can be observed with a class inherited from the
    69   // \e ObserverBase nested class. The signals can be handled with
     70  // ObserverBase nested class. The signals can be handled with
    7071  // overriding the virtual functions defined in the base class.  The
    7172  // observer base can be attached to the notifier with the
    72   // \e attach() member and can be detached with detach() function. The
     73  // attach() member and can be detached with detach() function. The
    7374  // alteration handlers should not call any function which signals
    7475  // an other alteration in the same notifier and should not
    7576  // detach any observer from the notifier.
    7677  //
    77   // Alteration observers try to be exception safe. If an \e add() or
    78   // a \e clear() function throws an exception then the remaining
     78  // Alteration observers try to be exception safe. If an add() or
     79  // a clear() function throws an exception then the remaining
    7980  // observeres will not be notified and the fulfilled additions will
    80   // be rolled back by calling the \e erase() or \e clear()
    81   // functions. Thence the \e erase() and \e clear() should not throw
    82   // exception. Actullay, it can be throw only \ref ImmediateDetach
    83   // exception which detach the observer from the notifier.
     81  // be rolled back by calling the erase() or clear() functions.
     82  // Hence erase() and clear() should not throw exception.
     83  // Actullay, they can throw only \ref ImmediateDetach exception,
     84  // which detach the observer from the notifier.
    8485  //
    85   // There are some place when the alteration observing is not completly
     86  // There are some cases, when the alteration observing is not completly
    8687  // reliable. If we want to carry out the node degree in the graph
    87   // as in the \ref InDegMap and we use the reverseEdge that cause
     88  // as in the \ref InDegMap and we use the reverseArc(), then it cause
    8889  // unreliable functionality. Because the alteration observing signals
    89   // only erasing and adding but not the reversing it will stores bad
    90   // degrees. The sub graph adaptors cannot signal the alterations because
    91   // just a setting in the filter map can modify the graph and this cannot
    92   // be watched in any way.
     90  // only erasing and adding but not the reversing, it will stores bad
     91  // degrees. Apart form that the subgraph adaptors cannot even signal
     92  // the alterations because just a setting in the filter map can modify
     93  // the graph and this cannot be watched in any way.
    9394  //
    9495  // \param _Container The container which is observed.
    9596  // \param _Item The item type which is obserbved.
     
    103104    typedef _Container Container;
    104105    typedef _Item Item;
    105106
    106     // \brief Exception which can be called from \e clear() and
    107     // \e erase().
     107    // \brief Exception which can be called from clear() and
     108    // erase().
    108109    //
    109     // From the \e clear() and \e erase() function only this
     110    // From the clear() and erase() function only this
    110111    // exception is allowed to throw. The exception immediatly
    111112    // detaches the current observer from the notifier. Because the
    112     // \e clear() and \e erase() should not throw other exceptions
     113    // clear() and erase() should not throw other exceptions
    113114    // it can be used to invalidate the observer.
    114115    struct ImmediateDetach {};
    115116
     
    121122    //
    122123    // The observer interface contains some pure virtual functions
    123124    // to override. The add() and erase() functions are
    124     // to notify the oberver when one item is added or
    125     // erased.
     125    // to notify the oberver when one item is added or erased.
    126126    //
    127127    // The build() and clear() members are to notify the observer
    128128    // about the container is built from an empty container or
  • lemon/bits/array_map.h

    diff --git a/lemon/bits/array_map.h b/lemon/bits/array_map.h
    a b  
    3636  //
    3737  // \brief Graph map based on the array storage.
    3838  //
    39   // The ArrayMap template class is graph map structure what
    40   // automatically updates the map when a key is added to or erased from
    41   // the map. This map uses the allocators to implement
    42   // the container functionality.
     39  // The ArrayMap template class is graph map structure that automatically
     40  // updates the map when a key is added to or erased from the graph.
     41  // This map uses the allocators to implement the container functionality.
    4342  //
    44   // The template parameters are the Graph the current Item type and
     43  // The template parameters are the Graph, the current Item type and
    4544  // the Value type of the map.
    4645  template <typename _Graph, typename _Item, typename _Value>
    4746  class ArrayMap
    4847    : public ItemSetTraits<_Graph, _Item>::ItemNotifier::ObserverBase {
    4948  public:
    50     // The graph type of the maps.
     49    // The graph type.
    5150    typedef _Graph Graph;
    52     // The item type of the map.
     51    // The item type.
    5352    typedef _Item Item;
    5453    // The reference map tag.
    5554    typedef True ReferenceMapTag;
    5655
    57     // The key type of the maps.
     56    // The key type of the map.
    5857    typedef _Item Key;
    5958    // The value type of the map.
    6059    typedef _Value Value;
     
    200199
    201200    // \brief Adds a new key to the map.
    202201    //
    203     // It adds a new key to the map. It called by the observer notifier
     202    // It adds a new key to the map. It is called by the observer notifier
    204203    // and it overrides the add() member function of the observer base.
    205204    virtual void add(const Key& key) {
    206205      Notifier* nf = Parent::notifier();
     
    228227
    229228    // \brief Adds more new keys to the map.
    230229    //
    231     // It adds more new keys to the map. It called by the observer notifier
     230    // It adds more new keys to the map. It is called by the observer notifier
    232231    // and it overrides the add() member function of the observer base.
    233232    virtual void add(const std::vector<Key>& keys) {
    234233      Notifier* nf = Parent::notifier();
     
    272271
    273272    // \brief Erase a key from the map.
    274273    //
    275     // Erase a key from the map. It called by the observer notifier
     274    // Erase a key from the map. It is called by the observer notifier
    276275    // and it overrides the erase() member function of the observer base.
    277276    virtual void erase(const Key& key) {
    278277      int id = Parent::notifier()->id(key);
     
    281280
    282281    // \brief Erase more keys from the map.
    283282    //
    284     // Erase more keys from the map. It called by the observer notifier
     283    // Erase more keys from the map. It is called by the observer notifier
    285284    // and it overrides the erase() member function of the observer base.
    286285    virtual void erase(const std::vector<Key>& keys) {
    287286      for (int i = 0; i < int(keys.size()); ++i) {
     
    290289      }
    291290    }
    292291
    293     // \brief Buildes the map.
     292    // \brief Builds the map.
    294293    //
    295     // It buildes the map. It called by the observer notifier
     294    // It builds the map. It is called by the observer notifier
    296295    // and it overrides the build() member function of the observer base.
    297296    virtual void build() {
    298297      Notifier* nf = Parent::notifier();
     
    306305
    307306    // \brief Clear the map.
    308307    //
    309     // It erase all items from the map. It called by the observer notifier
     308    // It erase all items from the map. It is called by the observer notifier
    310309    // and it overrides the clear() member function of the observer base.
    311310    virtual void clear() {
    312311      Notifier* nf = Parent::notifier();
  • lemon/bits/base_extender.h

    diff --git a/lemon/bits/base_extender.h b/lemon/bits/base_extender.h
    a b  
    3030
    3131//\ingroup digraphbits
    3232//\file
    33 //\brief Extenders for the digraph types
     33//\brief Extenders for the graph types
    3434namespace lemon {
    3535
    3636  // \ingroup digraphbits
  • lemon/bits/graph_extender.h

    diff --git a/lemon/bits/graph_extender.h b/lemon/bits/graph_extender.h
    a b  
    2929
    3030//\ingroup graphbits
    3131//\file
    32 //\brief Extenders for the digraph types
     32//\brief Extenders for the graph types
    3333namespace lemon {
    3434
    3535  // \ingroup graphbits
    3636  //
    37   // \brief Extender for the Digraphs
     37  // \brief Extender for the digraph implementations
    3838  template <typename Base>
    3939  class DigraphExtender : public Base {
    4040  public:
  • lemon/bits/vector_map.h

    diff --git a/lemon/bits/vector_map.h b/lemon/bits/vector_map.h
    a b  
    3838  //
    3939  // \brief Graph map based on the std::vector storage.
    4040  //
    41   // The VectorMap template class is graph map structure what
    42   // automatically updates the map when a key is added to or erased from
    43   // the map. This map type uses the std::vector to store the values.
     41  // The VectorMap template class is graph map structure that automatically
     42  // updates the map when a key is added to or erased from the graph.
     43  // This map type uses std::vector to store the values.
    4444  //
    4545  // \tparam _Graph The graph this map is attached to.
    4646  // \tparam _Item The item type of the graph items.
     
    169169
    170170    // \brief Adds a new key to the map.
    171171    //
    172     // It adds a new key to the map. It called by the observer notifier
     172    // It adds a new key to the map. It is called by the observer notifier
    173173    // and it overrides the add() member function of the observer base.
    174174    virtual void add(const Key& key) {
    175175      int id = Parent::notifier()->id(key);
     
    180180
    181181    // \brief Adds more new keys to the map.
    182182    //
    183     // It adds more new keys to the map. It called by the observer notifier
     183    // It adds more new keys to the map. It is called by the observer notifier
    184184    // and it overrides the add() member function of the observer base.
    185185    virtual void add(const std::vector<Key>& keys) {
    186186      int max = container.size() - 1;
     
    195195
    196196    // \brief Erase a key from the map.
    197197    //
    198     // Erase a key from the map. It called by the observer notifier
     198    // Erase a key from the map. It is called by the observer notifier
    199199    // and it overrides the erase() member function of the observer base.
    200200    virtual void erase(const Key& key) {
    201201      container[Parent::notifier()->id(key)] = Value();
     
    203203
    204204    // \brief Erase more keys from the map.
    205205    //
    206     // Erase more keys from the map. It called by the observer notifier
     206    // It erases more keys from the map. It is called by the observer notifier
    207207    // and it overrides the erase() member function of the observer base.
    208208    virtual void erase(const std::vector<Key>& keys) {
    209209      for (int i = 0; i < int(keys.size()); ++i) {
     
    211211      }
    212212    }
    213213
    214     // \brief Buildes the map.
     214    // \brief Build the map.
    215215    //
    216     // It buildes the map. It called by the observer notifier
     216    // It builds the map. It is called by the observer notifier
    217217    // and it overrides the build() member function of the observer base.
    218218    virtual void build() {
    219219      int size = Parent::notifier()->maxId() + 1;
     
    223223
    224224    // \brief Clear the map.
    225225    //
    226     // It erase all items from the map. It called by the observer notifier
     226    // It erases all items from the map. It is called by the observer notifier
    227227    // and it overrides the clear() member function of the observer base.
    228228    virtual void clear() {
    229229      container.clear();