COIN-OR::LEMON - Graph Library

Ticket #174: doc_d21271cbdc09.patch

File doc_d21271cbdc09.patch, 15.7 KB (added by Peter Kovacs, 11 years ago)
  • lemon/elevator.h

    # HG changeset patch
    # User Peter Kovacs <kpeter@inf.elte.hu>
    # Date 1227262225 -3600
    # Node ID d21271cbdc09705c48e22240837a37bae2054636
    # Parent  09acd23a35bdd78e83868cc10d819d96081bf5d7
    Doc improvements for elevator classes (#174)
    
    diff --git a/lemon/elevator.h b/lemon/elevator.h
    a b  
    2727///for labeling items in push-relabel type algorithms.
    2828///
    2929
    30 #include <test/test_tools.h>
     30#include <lemon/bits/traits.h>
     31
    3132namespace lemon {
    3233
    3334  ///Class for handling "labels" in push-relabel type algorithms.
     
    4445  ///
    4546  ///\sa LinkedElevator
    4647  ///
    47   ///\param Graph the underlying graph type
     48  ///\param Graph Type of the underlying graph.
    4849  ///\param Item Type of the items the data is assigned to (Graph::Node,
    49   ///Graph::Edge, Graph::UEdge)
     50  ///Graph::Arc, Graph::Edge).
    5051  template<class Graph, class Item>
    5152  class Elevator
    5253  {
     
    100101
    101102    ///Constructor with given maximum level.
    102103    ///
    103     ///\param g The underlying graph
    104     ///\param max_level Set the range of the possible labels to
    105     ///[0...\c max_level]
    106     Elevator(const Graph &g,int max_level) :
    107       _g(g),
     104    ///\param graph The underlying graph.
     105    ///\param max_level The maximum allowed level.
     106    ///Set the range of the possible labels to <tt>[0..max_level]</tt>.
     107    Elevator(const Graph &graph,int max_level) :
     108      _g(graph),
    108109      _max_level(max_level),
    109110      _item_num(_max_level),
    110       _where(g),
    111       _level(g,0),
     111      _where(graph),
     112      _level(graph,0),
    112113      _items(_max_level),
    113114      _first(_max_level+2),
    114115      _last_active(_max_level+2),
     
    117118
    118119    ///Constructor.
    119120    ///
    120     ///\param g The underlying graph
    121     ///The range of the possible labels is [0...\c max_level],
     121    ///\param graph The underlying graph.
     122    ///Set the range of the possible labels to <tt>[0..max_level]</tt>,
    122123    ///where \c max_level is equal to the number of labeled items in the graph.
    123     Elevator(const Graph &g) :
    124       _g(g),
    125       _max_level(countItems<Graph, Item>(g)),
     124    Elevator(const Graph &graph) :
     125      _g(graph),
     126      _max_level(countItems<Graph, Item>(graph)),
    126127      _item_num(_max_level),
    127       _where(g),
    128       _level(g,0),
     128      _where(graph),
     129      _level(graph,0),
    129130      _items(_max_level),
    130131      _first(_max_level+2),
    131132      _last_active(_max_level+2),
     
    167168    {
    168169      return _first[l+1]-_first[l];
    169170    }
    170     ///Return true if the level is empty.
     171    ///Return true if level \c l is empty.
    171172    bool emptyLevel(int l) const
    172173    {
    173174      return _first[l+1]-_first[l]==0;
     
    182183    {
    183184      return _last_active[l]-_first[l]+1;
    184185    }
    185     ///Return true if there is not active item on level \c l.
     186    ///Return true if there is no active item on level \c l.
    186187    bool activeFree(int l) const
    187188    {
    188189      return _last_active[l]<_first[l];
     
    201202
    202203    ///Return a highest level active item.
    203204
    204     ///Return a highest level active item.
    205     ///
    206     ///\return the highest level active item or INVALID if there is no active
     205    ///Return a highest level active item or INVALID if there is no active
    207206    ///item.
    208207    Item highestActive() const
    209208    {
    210209      return _highest_active>=0?*_last_active[_highest_active]:INVALID;
    211210    }
    212211
    213     ///Return a highest active level.
     212    ///Return the highest active level.
    214213
    215     ///Return a highest active level.
    216     ///
    217     ///\return the level of the highest active item or -1 if there is no active
     214    ///Return the level of the highest active item or -1 if there is no active
    218215    ///item.
    219216    int highestActiveLevel() const
    220217    {
     
    233230      --_first[++_highest_active];
    234231    }
    235232
    236     ///Lift the highest active item.
     233    ///Lift the highest active item to the given level.
    237234
    238235    ///Lift the item returned by highestActive() to level \c new_level.
    239236    ///
     
    255252      _highest_active=new_level;
    256253    }
    257254
    258     ///Lift the highest active item.
     255    ///Lift the highest active item to the top level.
    259256
    260257    ///Lift the item returned by highestActive() to the top level and
    261     ///deactivates it.
    262     ///
    263     ///\warning \c new_level must be strictly higher
    264     ///than the current level.
    265     ///
     258    ///deactivate it.
    266259    void liftHighestActiveToTop()
    267260    {
    268261      const Item li = *_last_active[_highest_active];
     
    289282
    290283    ///@{
    291284
    292     ///Returns an active item on level \c l.
     285    ///Return an active item on level \c l.
    293286
    294     ///Returns an active item on level \c l.
    295     ///
    296     ///Returns an active item on level \c l or \ref INVALID if there is no such
     287    ///Return an active item on level \c l or \ref INVALID if there is no such
    297288    ///an item. (\c l must be from the range [0...\c max_level].
    298289    Item activeOn(int l) const
    299290    {
    300291      return _last_active[l]>=_first[l]?*_last_active[l]:INVALID;
    301292    }
    302293
    303     ///Lifts the active item returned by \c activeOn() member function.
     294    ///Lift the active item returned by \c activeOn(level) by one.
    304295
    305     ///Lifts the active item returned by \c activeOn() member function
     296    ///Lift the active item returned by \ref activeOn() "activeOn(level)"
    306297    ///by one.
    307298    Item liftActiveOn(int level)
    308299    {
     
    312303      if (level+1>_highest_active) ++_highest_active;
    313304    }
    314305
    315     ///Lifts the active item returned by \c activeOn() member function.
     306    ///Lift the active item returned by \c activeOn(level) to the given level.
    316307
    317     ///Lifts the active item returned by \c activeOn() member function
     308    ///Lift the active item returned by \ref activeOn() "activeOn(level)"
    318309    ///to the given level.
    319310    void liftActiveOn(int level, int new_level)
    320311    {
     
    331322      if (new_level>_highest_active) _highest_active=new_level;
    332323    }
    333324
    334     ///Lifts the active item returned by \c activeOn() member function.
     325    ///Lift the active item returned by \c activeOn(level) to the top level.
    335326
    336     ///Lifts the active item returned by \c activeOn() member function
    337     ///to the top level.
     327    ///Lift the active item returned by \ref activeOn() "activeOn(level)"
     328    ///to the top level and deactivate it.
    338329    void liftActiveToTop(int level)
    339330    {
    340331      const Item ai = *_last_active[level];
     
    384375
    385376    ///Move an inactive item to the top but one level (in a dirty way).
    386377
    387     ///This function moves an inactive item to the top but one level.
    388     ///It makes the underlying datastructure corrupt, so use is only if
    389     ///you really know what it is for.
     378    ///This function moves an inactive item from the top level to the top
     379    ///but one level (in a dirty way).
     380    ///\warning It makes the underlying datastructure corrupt, so use it
     381    ///only if you really know what it is for.
    390382    ///\pre The item is on the top level.
    391383    void dirtyTopButOne(Item i) {
    392384      _level.set(i,_max_level - 1);
    393385    }
    394386
    395     ///Lift all items on and above a level to the top (and deactivate them).
     387    ///Lift all items on and above the given level to the top level.
    396388
    397     ///This function lifts all items on and above level \c l to \c
    398     ///maxLevel(), and also deactivates them.
     389    ///This function lifts all items on and above level \c l to the top
     390    ///level and deactivates them.
    399391    void liftToTop(int l)
    400392    {
    401393      const Vit f=_first[l];
     
    420412  public:
    421413
    422414    ///\name Initialization
    423     ///Using this function you can initialize the levels of the item.
     415    ///Using these functions you can initialize the levels of the items.
    424416    ///\n
    425     ///This initializatios is started with calling \c initStart().
    426     ///Then the
    427     ///items should be listed levels by levels statring with the lowest one
    428     ///(with level 0). This is done by using \c initAddItem()
    429     ///and \c initNewLevel(). Finally \c initFinish() must be called.
    430     ///The items not listed will be put on the highest level.
     417    ///The initialization must be started with calling \c initStart().
     418    ///Then the items should be listed level by level starting with the
     419    ///lowest one (level 0) using \c initAddItem() and \c initNewLevel().
     420    ///Finally \c initFinish() must be called.
     421    ///The items not listed are put on the highest level.
    431422    ///@{
    432423
    433424    ///Start the initialization process.
    434 
    435425    void initStart()
    436426    {
    437427      _init_lev=0;
     
    449439    }
    450440
    451441    ///Add an item to the current level.
    452 
    453442    void initAddItem(Item i)
    454443    {
    455444      swap(_where[i],_init_num);
     
    469458    }
    470459
    471460    ///Finalize the initialization process.
    472 
    473461    void initFinish()
    474462    {
    475463      for(_init_lev++;_init_lev<=_max_level;_init_lev++)
     
    500488  ///
    501489  ///\sa Elevator
    502490  ///
    503   ///\param Graph the underlying graph type
     491  ///\param Graph Type of the underlying graph.
    504492  ///\param Item Type of the items the data is assigned to (Graph::Node,
    505   ///Graph::Edge, Graph::UEdge)
     493  ///Graph::Arc, Graph::Edge).
    506494  template <class Graph, class Item>
    507495  class LinkedElevator {
    508496  public:
     
    533521
    534522    ///Constructor with given maximum level.
    535523    ///
    536     ///\param g The underlying graph
    537     ///\param max_level Set the range of the possible labels to
    538     ///[0...\c max_level]
     524    ///\param graph The underlying graph.
     525    ///\param max_level The maximum allowed level.
     526    ///Set the range of the possible labels to <tt>[0..max_level]</tt>.
    539527    LinkedElevator(const Graph& graph, int max_level)
    540528      : _graph(graph), _max_level(max_level), _item_num(_max_level),
    541529        _first(_max_level + 1), _last(_max_level + 1),
     
    546534
    547535    ///Constructor.
    548536    ///
    549     ///\param g The underlying graph
    550     ///The range of the possible labels is [0...\c max_level],
     537    ///\param graph The underlying graph.
     538    ///Set the range of the possible labels to <tt>[0..max_level]</tt>,
    551539    ///where \c max_level is equal to the number of labeled items in the graph.
    552540    LinkedElevator(const Graph& graph)
    553541      : _graph(graph), _max_level(countItems<Graph, Item>(graph)),
     
    657645      return num;
    658646    }
    659647
    660     ///Return true if there is not active item on level \c l.
     648    ///Return true if there is no active item on level \c l.
    661649    bool activeFree(int l) const {
    662650      return _first[l] == INVALID || !_active[_first[l]];
    663651    }
     
    675663
    676664    ///Return a highest level active item.
    677665
    678     ///Return a highest level active item.
    679     ///
    680     ///\return the highest level active item or INVALID if there is no
    681     ///active item.
     666    ///Return a highest level active item or INVALID if there is no active
     667    ///item.
    682668    Item highestActive() const {
    683669      return _highest_active >= 0 ? _first[_highest_active] : INVALID;
    684670    }
    685671
    686     ///Return a highest active level.
     672    ///Return the highest active level.
    687673
    688     ///Return a highest active level.
    689     ///
    690     ///\return the level of the highest active item or -1 if there is
    691     ///no active item.
     674    ///Return the level of the highest active item or -1 if there is no active
     675    ///item.
    692676    int highestActiveLevel() const {
    693677      return _highest_active;
    694678    }
     
    719703      }
    720704    }
    721705
    722     ///Lift the highest active item.
     706    ///Lift the highest active item to the given level.
    723707
    724708    ///Lift the item returned by highestActive() to level \c new_level.
    725709    ///
     
    747731      }
    748732    }
    749733
    750     ///Lift the highest active to top.
     734    ///Lift the highest active item to the top level.
    751735
    752736    ///Lift the item returned by highestActive() to the top level and
    753     ///deactivates the item.
    754     ///
     737    ///deactivate it.
    755738    void liftHighestActiveToTop() {
    756739      Item i = _first[_highest_active];
    757740      _level.set(i, _max_level);
     
    773756
    774757    ///@{
    775758
    776     ///Returns an active item on level \c l.
     759    ///Return an active item on level \c l.
    777760
    778     ///Returns an active item on level \c l.
    779     ///
    780     ///Returns an active item on level \c l or \ref INVALID if there is no such
     761    ///Return an active item on level \c l or \ref INVALID if there is no such
    781762    ///an item. (\c l must be from the range [0...\c max_level].
    782763    Item activeOn(int l) const
    783764    {
    784765      return _active[_first[l]] ? _first[l] : INVALID;
    785766    }
    786767
    787     ///Lifts the active item returned by \c activeOn() member function.
     768    ///Lift the active item returned by \c activeOn(l) by one.
    788769
    789     ///Lifts the active item returned by \c activeOn() member function
     770    ///Lift the active item returned by \ref activeOn() "activeOn(l)"
    790771    ///by one.
    791772    Item liftActiveOn(int l)
    792773    {
     
    813794      }
    814795    }
    815796
    816     /// \brief Lifts the active item returned by \c activeOn() member function.
    817     ///
    818     /// Lifts the active item returned by \c activeOn() member function
    819     /// to the given level.
     797    ///Lift the active item returned by \c activeOn(l) to the given level.
     798
     799    ///Lift the active item returned by \ref activeOn() "activeOn(l)"
     800    ///to the given level.
    820801    void liftActiveOn(int l, int new_level)
    821802    {
    822803      Item i = _first[l];
     
    842823      }
    843824    }
    844825
    845     ///Lifts the active item returned by \c activeOn() member function.
     826    ///Lift the active item returned by \c activeOn(l) to the top level.
    846827
    847     ///Lifts the active item returned by \c activeOn() member function
    848     ///to the top level.
     828    ///Lift the active item returned by \ref activeOn() "activeOn(l)"
     829    ///to the top level and deactivate it.
    849830    void liftActiveToTop(int l)
    850831    {
    851832      Item i = _first[l];
     
    900881
    901882    ///Move an inactive item to the top but one level (in a dirty way).
    902883
    903     ///This function moves an inactive item to the top but one level.
    904     ///It makes the underlying datastructure corrupt, so use is only if
    905     ///you really know what it is for.
     884    ///This function moves an inactive item from the top level to the top
     885    ///but one level (in a dirty way).
     886    ///\warning It makes the underlying datastructure corrupt, so use it
     887    ///only if you really know what it is for.
    906888    ///\pre The item is on the top level.
    907889    void dirtyTopButOne(Item i) {
    908890      _level.set(i, _max_level - 1);
    909891    }
    910892
    911     ///Lift all items on and above a level to the top (and deactivate them).
     893    ///Lift all items on and above the given level to the top level.
    912894
    913     ///This function lifts all items on and above level \c l to \c
    914     ///maxLevel(), and also deactivates them.
     895    ///This function lifts all items on and above level \c l to the top
     896    ///level and deactivates them.
    915897    void liftToTop(int l)  {
    916898      for (int i = l + 1; _first[i] != INVALID; ++i) {
    917899        Item n = _first[i];
     
    936918  public:
    937919
    938920    ///\name Initialization
    939     ///Using this function you can initialize the levels of the item.
     921    ///Using these functions you can initialize the levels of the items.
    940922    ///\n
    941     ///This initializatios is started with calling \c initStart().
    942     ///Then the
    943     ///items should be listed levels by levels statring with the lowest one
    944     ///(with level 0). This is done by using \c initAddItem()
    945     ///and \c initNewLevel(). Finally \c initFinish() must be called.
    946     ///The items not listed will be put on the highest level.
     923    ///The initialization must be started with calling \c initStart().
     924    ///Then the items should be listed level by level starting with the
     925    ///lowest one (level 0) using \c initAddItem() and \c initNewLevel().
     926    ///Finally \c initFinish() must be called.
     927    ///The items not listed are put on the highest level.
    947928    ///@{
    948929
    949930    ///Start the initialization process.
    950 
    951931    void initStart() {
    952932
    953933      for (int i = 0; i <= _max_level; ++i) {
     
    962942    }
    963943
    964944    ///Add an item to the current level.
    965 
    966945    void initAddItem(Item i) {
    967946      _level.set(i, _init_level);
    968947      if (_last[_init_level] == INVALID) {
     
    987966    }
    988967
    989968    ///Finalize the initialization process.
    990 
    991969    void initFinish() {
    992970      _highest_active = -1;
    993971    }