COIN-OR::LEMON - Graph Library

Changeset 398:a8a22a96d495 in lemon for lemon/elevator.h


Ignore:
Timestamp:
11/21/08 11:10:25 (11 years ago)
Author:
Peter Kovacs <kpeter@…>
Branch:
default
Phase:
public
Message:

Doc improvements for elevator classes (#174)

File:
1 edited

Legend:

Unmodified
Added
Removed
  • lemon/elevator.h

    r397 r398  
    2828///
    2929
    30 #include <test/test_tools.h>
     30#include <lemon/bits/traits.h>
     31
    3132namespace lemon {
    3233
     
    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
     
    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),
     
    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),
     
    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    {
     
    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    {
     
    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
     
    211210    }
    212211
    213     ///Return a highest active level.
    214 
    215     ///Return a highest active level.
    216     ///
    217     ///\return the level of the highest active item or -1 if there is no active
     212    ///Return the highest active level.
     213
     214    ///Return the level of the highest active item or -1 if there is no active
    218215    ///item.
    219216    int highestActiveLevel() const
     
    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.
     
    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    {
     
    290283    ///@{
    291284
    292     ///Returns an active item on level \c l.
    293 
    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
     285    ///Return an active item on level \c l.
     286
     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
     
    301292    }
    302293
    303     ///Lifts the active item returned by \c activeOn() member function.
    304 
    305     ///Lifts the active item returned by \c activeOn() member function
     294    ///Lift the active item returned by \c activeOn(level) by one.
     295
     296    ///Lift the active item returned by \ref activeOn() "activeOn(level)"
    306297    ///by one.
    307298    Item liftActiveOn(int level)
     
    313304    }
    314305
    315     ///Lifts the active item returned by \c activeOn() member function.
    316 
    317     ///Lifts the active item returned by \c activeOn() member function
     306    ///Lift the active item returned by \c activeOn(level) to the given level.
     307
     308    ///Lift the active item returned by \ref activeOn() "activeOn(level)"
    318309    ///to the given level.
    319310    void liftActiveOn(int level, int new_level)
     
    332323    }
    333324
    334     ///Lifts the active item returned by \c activeOn() member function.
    335 
    336     ///Lifts the active item returned by \c activeOn() member function
    337     ///to the top level.
     325    ///Lift the active item returned by \c activeOn(level) to the top level.
     326
     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    {
     
    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) {
     
    393385    }
    394386
    395     ///Lift all items on and above a level to the top (and deactivate them).
    396 
    397     ///This function lifts all items on and above level \c l to \c
    398     ///maxLevel(), and also deactivates them.
     387    ///Lift all items on and above the given level to the top level.
     388
     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    {
     
    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    {
     
    450440
    451441    ///Add an item to the current level.
    452 
    453442    void initAddItem(Item i)
    454443    {
     
    470459
    471460    ///Finalize the initialization process.
    472 
    473461    void initFinish()
    474462    {
     
    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 {
     
    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),
     
    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)
     
    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]];
     
    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.
    687 
    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.
     672    ///Return the highest active level.
     673
     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;
     
    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.
     
    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];
     
    774757    ///@{
    775758
    776     ///Returns an active item on level \c l.
    777 
    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
     759    ///Return an active item on level \c l.
     760
     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
     
    785766    }
    786767
    787     ///Lifts the active item returned by \c activeOn() member function.
    788 
    789     ///Lifts the active item returned by \c activeOn() member function
     768    ///Lift the active item returned by \c activeOn(l) by one.
     769
     770    ///Lift the active item returned by \ref activeOn() "activeOn(l)"
    790771    ///by one.
    791772    Item liftActiveOn(int l)
     
    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    {
     
    843824    }
    844825
    845     ///Lifts the active item returned by \c activeOn() member function.
    846 
    847     ///Lifts the active item returned by \c activeOn() member function
    848     ///to the top level.
     826    ///Lift the active item returned by \c activeOn(l) to the top level.
     827
     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    {
     
    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) {
     
    909891    }
    910892
    911     ///Lift all items on and above a level to the top (and deactivate them).
    912 
    913     ///This function lifts all items on and above level \c l to \c
    914     ///maxLevel(), and also deactivates them.
     893    ///Lift all items on and above the given level to the top level.
     894
     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) {
     
    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
     
    963943
    964944    ///Add an item to the current level.
    965 
    966945    void initAddItem(Item i) {
    967946      _level.set(i, _init_level);
     
    988967
    989968    ///Finalize the initialization process.
    990 
    991969    void initFinish() {
    992970      _highest_active = -1;
Note: See TracChangeset for help on using the changeset viewer.