Merge
authorAlpar Juttner <alpar@cs.elte.hu>
Mon, 31 Aug 2009 20:27:38 +0200
changeset 7126d5f547e5bfb
parent 708 5d313b76f323
parent 711 28cfac049a6a
child 715 ece80147fb08
child 729 be48a648d28f
child 797 30cb42e3e43a
child 868 0513ccfea967
Merge
     1.1 --- a/doc/groups.dox	Mon Aug 31 10:03:23 2009 +0200
     1.2 +++ b/doc/groups.dox	Mon Aug 31 20:27:38 2009 +0200
     1.3 @@ -226,14 +226,6 @@
     1.4  */
     1.5  
     1.6  /**
     1.7 -@defgroup matrices Matrices
     1.8 -@ingroup datas
     1.9 -\brief Two dimensional data storages implemented in LEMON.
    1.10 -
    1.11 -This group contains two dimensional data storages implemented in LEMON.
    1.12 -*/
    1.13 -
    1.14 -/**
    1.15  @defgroup paths Path Structures
    1.16  @ingroup datas
    1.17  \brief %Path structures implemented in LEMON.
    1.18 @@ -246,7 +238,36 @@
    1.19  efficient to have e.g. the Dijkstra algorithm to store its result in
    1.20  any kind of path structure.
    1.21  
    1.22 -\sa lemon::concepts::Path
    1.23 +\sa \ref concepts::Path "Path concept"
    1.24 +*/
    1.25 +
    1.26 +/**
    1.27 +@defgroup heaps Heap Structures
    1.28 +@ingroup datas
    1.29 +\brief %Heap structures implemented in LEMON.
    1.30 +
    1.31 +This group contains the heap structures implemented in LEMON.
    1.32 +
    1.33 +LEMON provides several heap classes. They are efficient implementations
    1.34 +of the abstract data type \e priority \e queue. They store items with
    1.35 +specified values called \e priorities in such a way that finding and
    1.36 +removing the item with minimum priority are efficient.
    1.37 +The basic operations are adding and erasing items, changing the priority
    1.38 +of an item, etc.
    1.39 +
    1.40 +Heaps are crucial in several algorithms, such as Dijkstra and Prim.
    1.41 +The heap implementations have the same interface, thus any of them can be
    1.42 +used easily in such algorithms.
    1.43 +
    1.44 +\sa \ref concepts::Heap "Heap concept"
    1.45 +*/
    1.46 +
    1.47 +/**
    1.48 +@defgroup matrices Matrices
    1.49 +@ingroup datas
    1.50 +\brief Two dimensional data storages implemented in LEMON.
    1.51 +
    1.52 +This group contains two dimensional data storages implemented in LEMON.
    1.53  */
    1.54  
    1.55  /**
     2.1 --- a/lemon/bin_heap.h	Mon Aug 31 10:03:23 2009 +0200
     2.2 +++ b/lemon/bin_heap.h	Mon Aug 31 20:27:38 2009 +0200
     2.3 @@ -19,9 +19,9 @@
     2.4  #ifndef LEMON_BIN_HEAP_H
     2.5  #define LEMON_BIN_HEAP_H
     2.6  
     2.7 -///\ingroup auxdat
     2.8 +///\ingroup heaps
     2.9  ///\file
    2.10 -///\brief Binary Heap implementation.
    2.11 +///\brief Binary heap implementation.
    2.12  
    2.13  #include <vector>
    2.14  #include <utility>
    2.15 @@ -29,45 +29,41 @@
    2.16  
    2.17  namespace lemon {
    2.18  
    2.19 -  ///\ingroup auxdat
    2.20 +  /// \ingroup heaps
    2.21    ///
    2.22 -  ///\brief A Binary Heap implementation.
    2.23 +  /// \brief Binary heap data structure.
    2.24    ///
    2.25 -  ///This class implements the \e binary \e heap data structure.
    2.26 +  /// This class implements the \e binary \e heap data structure.
    2.27 +  /// It fully conforms to the \ref concepts::Heap "heap concept".
    2.28    ///
    2.29 -  ///A \e heap is a data structure for storing items with specified values
    2.30 -  ///called \e priorities in such a way that finding the item with minimum
    2.31 -  ///priority is efficient. \c CMP specifies the ordering of the priorities.
    2.32 -  ///In a heap one can change the priority of an item, add or erase an
    2.33 -  ///item, etc.
    2.34 -  ///
    2.35 -  ///\tparam PR Type of the priority of the items.
    2.36 -  ///\tparam IM A read and writable item map with int values, used internally
    2.37 -  ///to handle the cross references.
    2.38 -  ///\tparam CMP A functor class for the ordering of the priorities.
    2.39 -  ///The default is \c std::less<PR>.
    2.40 -  ///
    2.41 -  ///\sa FibHeap
    2.42 -  ///\sa Dijkstra
    2.43 +  /// \tparam PR Type of the priorities of the items.
    2.44 +  /// \tparam IM A read-writable item map with \c int values, used
    2.45 +  /// internally to handle the cross references.
    2.46 +  /// \tparam CMP A functor class for comparing the priorities.
    2.47 +  /// The default is \c std::less<PR>.
    2.48 +#ifdef DOXYGEN
    2.49 +  template <typename PR, typename IM, typename CMP>
    2.50 +#else
    2.51    template <typename PR, typename IM, typename CMP = std::less<PR> >
    2.52 +#endif
    2.53    class BinHeap {
    2.54 +  public:
    2.55  
    2.56 -  public:
    2.57 -    ///\e
    2.58 +    /// Type of the item-int map.
    2.59      typedef IM ItemIntMap;
    2.60 -    ///\e
    2.61 +    /// Type of the priorities.
    2.62      typedef PR Prio;
    2.63 -    ///\e
    2.64 +    /// Type of the items stored in the heap.
    2.65      typedef typename ItemIntMap::Key Item;
    2.66 -    ///\e
    2.67 +    /// Type of the item-priority pairs.
    2.68      typedef std::pair<Item,Prio> Pair;
    2.69 -    ///\e
    2.70 +    /// Functor type for comparing the priorities.
    2.71      typedef CMP Compare;
    2.72  
    2.73 -    /// \brief Type to represent the items states.
    2.74 +    /// \brief Type to represent the states of the items.
    2.75      ///
    2.76 -    /// Each Item element have a state associated to it. It may be "in heap",
    2.77 -    /// "pre heap" or "post heap". The latter two are indifferent from the
    2.78 +    /// Each item has a state associated to it. It can be "in heap",
    2.79 +    /// "pre-heap" or "post-heap". The latter two are indifferent from the
    2.80      /// heap's point of view, but may be useful to the user.
    2.81      ///
    2.82      /// The item-int map must be initialized in such way that it assigns
    2.83 @@ -84,42 +80,43 @@
    2.84      ItemIntMap &_iim;
    2.85  
    2.86    public:
    2.87 -    /// \brief The constructor.
    2.88 +
    2.89 +    /// \brief Constructor.
    2.90      ///
    2.91 -    /// The constructor.
    2.92 -    /// \param map should be given to the constructor, since it is used
    2.93 -    /// internally to handle the cross references. The value of the map
    2.94 -    /// must be \c PRE_HEAP (<tt>-1</tt>) for every item.
    2.95 +    /// Constructor.
    2.96 +    /// \param map A map that assigns \c int values to the items.
    2.97 +    /// It is used internally to handle the cross references.
    2.98 +    /// The assigned value must be \c PRE_HEAP (<tt>-1</tt>) for each item.
    2.99      explicit BinHeap(ItemIntMap &map) : _iim(map) {}
   2.100  
   2.101 -    /// \brief The constructor.
   2.102 +    /// \brief Constructor.
   2.103      ///
   2.104 -    /// The constructor.
   2.105 -    /// \param map should be given to the constructor, since it is used
   2.106 -    /// internally to handle the cross references. The value of the map
   2.107 -    /// should be PRE_HEAP (-1) for each element.
   2.108 -    ///
   2.109 -    /// \param comp The comparator function object.
   2.110 +    /// Constructor.
   2.111 +    /// \param map A map that assigns \c int values to the items.
   2.112 +    /// It is used internally to handle the cross references.
   2.113 +    /// The assigned value must be \c PRE_HEAP (<tt>-1</tt>) for each item.
   2.114 +    /// \param comp The function object used for comparing the priorities.
   2.115      BinHeap(ItemIntMap &map, const Compare &comp)
   2.116        : _iim(map), _comp(comp) {}
   2.117  
   2.118  
   2.119 -    /// The number of items stored in the heap.
   2.120 +    /// \brief The number of items stored in the heap.
   2.121      ///
   2.122 -    /// \brief Returns the number of items stored in the heap.
   2.123 +    /// This function returns the number of items stored in the heap.
   2.124      int size() const { return _data.size(); }
   2.125  
   2.126 -    /// \brief Checks if the heap stores no items.
   2.127 +    /// \brief Check if the heap is empty.
   2.128      ///
   2.129 -    /// Returns \c true if and only if the heap stores no items.
   2.130 +    /// This function returns \c true if the heap is empty.
   2.131      bool empty() const { return _data.empty(); }
   2.132  
   2.133 -    /// \brief Make empty this heap.
   2.134 +    /// \brief Make the heap empty.
   2.135      ///
   2.136 -    /// Make empty this heap. It does not change the cross reference map.
   2.137 -    /// If you want to reuse what is not surely empty you should first clear
   2.138 -    /// the heap and after that you should set the cross reference map for
   2.139 -    /// each item to \c PRE_HEAP.
   2.140 +    /// This functon makes the heap empty.
   2.141 +    /// It does not change the cross reference map. If you want to reuse
   2.142 +    /// a heap that is not surely empty, you should first clear it and
   2.143 +    /// then you should set the cross reference map to \c PRE_HEAP
   2.144 +    /// for each item.
   2.145      void clear() {
   2.146        _data.clear();
   2.147      }
   2.148 @@ -127,12 +124,12 @@
   2.149    private:
   2.150      static int parent(int i) { return (i-1)/2; }
   2.151  
   2.152 -    static int second_child(int i) { return 2*i+2; }
   2.153 +    static int secondChild(int i) { return 2*i+2; }
   2.154      bool less(const Pair &p1, const Pair &p2) const {
   2.155        return _comp(p1.second, p2.second);
   2.156      }
   2.157  
   2.158 -    int bubble_up(int hole, Pair p) {
   2.159 +    int bubbleUp(int hole, Pair p) {
   2.160        int par = parent(hole);
   2.161        while( hole>0 && less(p,_data[par]) ) {
   2.162          move(_data[par],hole);
   2.163 @@ -143,8 +140,8 @@
   2.164        return hole;
   2.165      }
   2.166  
   2.167 -    int bubble_down(int hole, Pair p, int length) {
   2.168 -      int child = second_child(hole);
   2.169 +    int bubbleDown(int hole, Pair p, int length) {
   2.170 +      int child = secondChild(hole);
   2.171        while(child < length) {
   2.172          if( less(_data[child-1], _data[child]) ) {
   2.173            --child;
   2.174 @@ -153,7 +150,7 @@
   2.175            goto ok;
   2.176          move(_data[child], hole);
   2.177          hole = child;
   2.178 -        child = second_child(hole);
   2.179 +        child = secondChild(hole);
   2.180        }
   2.181        child--;
   2.182        if( child<length && less(_data[child], p) ) {
   2.183 @@ -171,87 +168,91 @@
   2.184      }
   2.185  
   2.186    public:
   2.187 +
   2.188      /// \brief Insert a pair of item and priority into the heap.
   2.189      ///
   2.190 -    /// Adds \c p.first to the heap with priority \c p.second.
   2.191 +    /// This function inserts \c p.first to the heap with priority
   2.192 +    /// \c p.second.
   2.193      /// \param p The pair to insert.
   2.194 +    /// \pre \c p.first must not be stored in the heap.
   2.195      void push(const Pair &p) {
   2.196        int n = _data.size();
   2.197        _data.resize(n+1);
   2.198 -      bubble_up(n, p);
   2.199 +      bubbleUp(n, p);
   2.200      }
   2.201  
   2.202 -    /// \brief Insert an item into the heap with the given heap.
   2.203 +    /// \brief Insert an item into the heap with the given priority.
   2.204      ///
   2.205 -    /// Adds \c i to the heap with priority \c p.
   2.206 +    /// This function inserts the given item into the heap with the
   2.207 +    /// given priority.
   2.208      /// \param i The item to insert.
   2.209      /// \param p The priority of the item.
   2.210 +    /// \pre \e i must not be stored in the heap.
   2.211      void push(const Item &i, const Prio &p) { push(Pair(i,p)); }
   2.212  
   2.213 -    /// \brief Returns the item with minimum priority relative to \c Compare.
   2.214 +    /// \brief Return the item having minimum priority.
   2.215      ///
   2.216 -    /// This method returns the item with minimum priority relative to \c
   2.217 -    /// Compare.
   2.218 -    /// \pre The heap must be nonempty.
   2.219 +    /// This function returns the item having minimum priority.
   2.220 +    /// \pre The heap must be non-empty.
   2.221      Item top() const {
   2.222        return _data[0].first;
   2.223      }
   2.224  
   2.225 -    /// \brief Returns the minimum priority relative to \c Compare.
   2.226 +    /// \brief The minimum priority.
   2.227      ///
   2.228 -    /// It returns the minimum priority relative to \c Compare.
   2.229 -    /// \pre The heap must be nonempty.
   2.230 +    /// This function returns the minimum priority.
   2.231 +    /// \pre The heap must be non-empty.
   2.232      Prio prio() const {
   2.233        return _data[0].second;
   2.234      }
   2.235  
   2.236 -    /// \brief Deletes the item with minimum priority relative to \c Compare.
   2.237 +    /// \brief Remove the item having minimum priority.
   2.238      ///
   2.239 -    /// This method deletes the item with minimum priority relative to \c
   2.240 -    /// Compare from the heap.
   2.241 +    /// This function removes the item having minimum priority.
   2.242      /// \pre The heap must be non-empty.
   2.243      void pop() {
   2.244        int n = _data.size()-1;
   2.245        _iim.set(_data[0].first, POST_HEAP);
   2.246        if (n > 0) {
   2.247 -        bubble_down(0, _data[n], n);
   2.248 +        bubbleDown(0, _data[n], n);
   2.249        }
   2.250        _data.pop_back();
   2.251      }
   2.252  
   2.253 -    /// \brief Deletes \c i from the heap.
   2.254 +    /// \brief Remove the given item from the heap.
   2.255      ///
   2.256 -    /// This method deletes item \c i from the heap.
   2.257 -    /// \param i The item to erase.
   2.258 -    /// \pre The item should be in the heap.
   2.259 +    /// This function removes the given item from the heap if it is
   2.260 +    /// already stored.
   2.261 +    /// \param i The item to delete.
   2.262 +    /// \pre \e i must be in the heap.
   2.263      void erase(const Item &i) {
   2.264        int h = _iim[i];
   2.265        int n = _data.size()-1;
   2.266        _iim.set(_data[h].first, POST_HEAP);
   2.267        if( h < n ) {
   2.268 -        if ( bubble_up(h, _data[n]) == h) {
   2.269 -          bubble_down(h, _data[n], n);
   2.270 +        if ( bubbleUp(h, _data[n]) == h) {
   2.271 +          bubbleDown(h, _data[n], n);
   2.272          }
   2.273        }
   2.274        _data.pop_back();
   2.275      }
   2.276  
   2.277 -
   2.278 -    /// \brief Returns the priority of \c i.
   2.279 +    /// \brief The priority of the given item.
   2.280      ///
   2.281 -    /// This function returns the priority of item \c i.
   2.282 +    /// This function returns the priority of the given item.
   2.283      /// \param i The item.
   2.284 -    /// \pre \c i must be in the heap.
   2.285 +    /// \pre \e i must be in the heap.
   2.286      Prio operator[](const Item &i) const {
   2.287        int idx = _iim[i];
   2.288        return _data[idx].second;
   2.289      }
   2.290  
   2.291 -    /// \brief \c i gets to the heap with priority \c p independently
   2.292 -    /// if \c i was already there.
   2.293 +    /// \brief Set the priority of an item or insert it, if it is
   2.294 +    /// not stored in the heap.
   2.295      ///
   2.296 -    /// This method calls \ref push(\c i, \c p) if \c i is not stored
   2.297 -    /// in the heap and sets the priority of \c i to \c p otherwise.
   2.298 +    /// This method sets the priority of the given item if it is
   2.299 +    /// already stored in the heap. Otherwise it inserts the given
   2.300 +    /// item into the heap with the given priority.
   2.301      /// \param i The item.
   2.302      /// \param p The priority.
   2.303      void set(const Item &i, const Prio &p) {
   2.304 @@ -260,44 +261,42 @@
   2.305          push(i,p);
   2.306        }
   2.307        else if( _comp(p, _data[idx].second) ) {
   2.308 -        bubble_up(idx, Pair(i,p));
   2.309 +        bubbleUp(idx, Pair(i,p));
   2.310        }
   2.311        else {
   2.312 -        bubble_down(idx, Pair(i,p), _data.size());
   2.313 +        bubbleDown(idx, Pair(i,p), _data.size());
   2.314        }
   2.315      }
   2.316  
   2.317 -    /// \brief Decreases the priority of \c i to \c p.
   2.318 +    /// \brief Decrease the priority of an item to the given value.
   2.319      ///
   2.320 -    /// This method decreases the priority of item \c i to \c p.
   2.321 +    /// This function decreases the priority of an item to the given value.
   2.322      /// \param i The item.
   2.323      /// \param p The priority.
   2.324 -    /// \pre \c i must be stored in the heap with priority at least \c
   2.325 -    /// p relative to \c Compare.
   2.326 +    /// \pre \e i must be stored in the heap with priority at least \e p.
   2.327      void decrease(const Item &i, const Prio &p) {
   2.328        int idx = _iim[i];
   2.329 -      bubble_up(idx, Pair(i,p));
   2.330 +      bubbleUp(idx, Pair(i,p));
   2.331      }
   2.332  
   2.333 -    /// \brief Increases the priority of \c i to \c p.
   2.334 +    /// \brief Increase the priority of an item to the given value.
   2.335      ///
   2.336 -    /// This method sets the priority of item \c i to \c p.
   2.337 +    /// This function increases the priority of an item to the given value.
   2.338      /// \param i The item.
   2.339      /// \param p The priority.
   2.340 -    /// \pre \c i must be stored in the heap with priority at most \c
   2.341 -    /// p relative to \c Compare.
   2.342 +    /// \pre \e i must be stored in the heap with priority at most \e p.
   2.343      void increase(const Item &i, const Prio &p) {
   2.344        int idx = _iim[i];
   2.345 -      bubble_down(idx, Pair(i,p), _data.size());
   2.346 +      bubbleDown(idx, Pair(i,p), _data.size());
   2.347      }
   2.348  
   2.349 -    /// \brief Returns if \c item is in, has already been in, or has
   2.350 -    /// never been in the heap.
   2.351 +    /// \brief Return the state of an item.
   2.352      ///
   2.353 -    /// This method returns PRE_HEAP if \c item has never been in the
   2.354 -    /// heap, IN_HEAP if it is in the heap at the moment, and POST_HEAP
   2.355 -    /// otherwise. In the latter case it is possible that \c item will
   2.356 -    /// get back to the heap again.
   2.357 +    /// This method returns \c PRE_HEAP if the given item has never
   2.358 +    /// been in the heap, \c IN_HEAP if it is in the heap at the moment,
   2.359 +    /// and \c POST_HEAP otherwise.
   2.360 +    /// In the latter case it is possible that the item will get back
   2.361 +    /// to the heap again.
   2.362      /// \param i The item.
   2.363      State state(const Item &i) const {
   2.364        int s = _iim[i];
   2.365 @@ -306,11 +305,11 @@
   2.366        return State(s);
   2.367      }
   2.368  
   2.369 -    /// \brief Sets the state of the \c item in the heap.
   2.370 +    /// \brief Set the state of an item in the heap.
   2.371      ///
   2.372 -    /// Sets the state of the \c item in the heap. It can be used to
   2.373 -    /// manually clear the heap when it is important to achive the
   2.374 -    /// better time complexity.
   2.375 +    /// This function sets the state of the given item in the heap.
   2.376 +    /// It can be used to manually clear the heap when it is important
   2.377 +    /// to achive better time complexity.
   2.378      /// \param i The item.
   2.379      /// \param st The state. It should not be \c IN_HEAP.
   2.380      void state(const Item& i, State st) {
   2.381 @@ -327,12 +326,13 @@
   2.382        }
   2.383      }
   2.384  
   2.385 -    /// \brief Replaces an item in the heap.
   2.386 +    /// \brief Replace an item in the heap.
   2.387      ///
   2.388 -    /// The \c i item is replaced with \c j item. The \c i item should
   2.389 -    /// be in the heap, while the \c j should be out of the heap. The
   2.390 -    /// \c i item will out of the heap and \c j will be in the heap
   2.391 -    /// with the same prioriority as prevoiusly the \c i item.
   2.392 +    /// This function replaces item \c i with item \c j.
   2.393 +    /// Item \c i must be in the heap, while \c j must be out of the heap.
   2.394 +    /// After calling this method, item \c i will be out of the
   2.395 +    /// heap and \c j will be in the heap with the same prioriority
   2.396 +    /// as item \c i had before.
   2.397      void replace(const Item& i, const Item& j) {
   2.398        int idx = _iim[i];
   2.399        _iim.set(i, _iim[j]);
     3.1 --- a/lemon/bucket_heap.h	Mon Aug 31 10:03:23 2009 +0200
     3.2 +++ b/lemon/bucket_heap.h	Mon Aug 31 20:27:38 2009 +0200
     3.3 @@ -19,9 +19,9 @@
     3.4  #ifndef LEMON_BUCKET_HEAP_H
     3.5  #define LEMON_BUCKET_HEAP_H
     3.6  
     3.7 -///\ingroup auxdat
     3.8 +///\ingroup heaps
     3.9  ///\file
    3.10 -///\brief Bucket Heap implementation.
    3.11 +///\brief Bucket heap implementation.
    3.12  
    3.13  #include <vector>
    3.14  #include <utility>
    3.15 @@ -53,35 +53,41 @@
    3.16  
    3.17    }
    3.18  
    3.19 -  /// \ingroup auxdat
    3.20 +  /// \ingroup heaps
    3.21    ///
    3.22 -  /// \brief A Bucket Heap implementation.
    3.23 +  /// \brief Bucket heap data structure.
    3.24    ///
    3.25 -  /// This class implements the \e bucket \e heap data structure. A \e heap
    3.26 -  /// is a data structure for storing items with specified values called \e
    3.27 -  /// priorities in such a way that finding the item with minimum priority is
    3.28 -  /// efficient. The bucket heap is very simple implementation, it can store
    3.29 -  /// only integer priorities and it stores for each priority in the
    3.30 -  /// \f$ [0..C) \f$ range a list of items. So it should be used only when
    3.31 -  /// the priorities are small. It is not intended to use as dijkstra heap.
    3.32 +  /// This class implements the \e bucket \e heap data structure.
    3.33 +  /// It practically conforms to the \ref concepts::Heap "heap concept",
    3.34 +  /// but it has some limitations.
    3.35    ///
    3.36 -  /// \param IM A read and write Item int map, used internally
    3.37 -  /// to handle the cross references.
    3.38 -  /// \param MIN If the given parameter is false then instead of the
    3.39 -  /// minimum value the maximum can be retrivied with the top() and
    3.40 -  /// prio() member functions.
    3.41 +  /// The bucket heap is a very simple structure. It can store only
    3.42 +  /// \c int priorities and it maintains a list of items for each priority
    3.43 +  /// in the range <tt>[0..C)</tt>. So it should only be used when the
    3.44 +  /// priorities are small. It is not intended to use as a Dijkstra heap.
    3.45 +  ///
    3.46 +  /// \tparam IM A read-writable item map with \c int values, used
    3.47 +  /// internally to handle the cross references.
    3.48 +  /// \tparam MIN Indicate if the heap is a \e min-heap or a \e max-heap.
    3.49 +  /// The default is \e min-heap. If this parameter is set to \c false,
    3.50 +  /// then the comparison is reversed, so the top(), prio() and pop()
    3.51 +  /// functions deal with the item having maximum priority instead of the
    3.52 +  /// minimum.
    3.53 +  ///
    3.54 +  /// \sa SimpleBucketHeap
    3.55    template <typename IM, bool MIN = true>
    3.56    class BucketHeap {
    3.57  
    3.58    public:
    3.59 -    /// \e
    3.60 -    typedef typename IM::Key Item;
    3.61 -    /// \e
    3.62 +
    3.63 +    /// Type of the item-int map.
    3.64 +    typedef IM ItemIntMap;
    3.65 +    /// Type of the priorities.
    3.66      typedef int Prio;
    3.67 -    /// \e
    3.68 -    typedef std::pair<Item, Prio> Pair;
    3.69 -    /// \e
    3.70 -    typedef IM ItemIntMap;
    3.71 +    /// Type of the items stored in the heap.
    3.72 +    typedef typename ItemIntMap::Key Item;
    3.73 +    /// Type of the item-priority pairs.
    3.74 +    typedef std::pair<Item,Prio> Pair;
    3.75  
    3.76    private:
    3.77  
    3.78 @@ -89,10 +95,10 @@
    3.79  
    3.80    public:
    3.81  
    3.82 -    /// \brief Type to represent the items states.
    3.83 +    /// \brief Type to represent the states of the items.
    3.84      ///
    3.85 -    /// Each Item element have a state associated to it. It may be "in heap",
    3.86 -    /// "pre heap" or "post heap". The latter two are indifferent from the
    3.87 +    /// Each item has a state associated to it. It can be "in heap",
    3.88 +    /// "pre-heap" or "post-heap". The latter two are indifferent from the
    3.89      /// heap's point of view, but may be useful to the user.
    3.90      ///
    3.91      /// The item-int map must be initialized in such way that it assigns
    3.92 @@ -104,37 +110,39 @@
    3.93      };
    3.94  
    3.95    public:
    3.96 -    /// \brief The constructor.
    3.97 +
    3.98 +    /// \brief Constructor.
    3.99      ///
   3.100 -    /// The constructor.
   3.101 -    /// \param map should be given to the constructor, since it is used
   3.102 -    /// internally to handle the cross references. The value of the map
   3.103 -    /// should be PRE_HEAP (-1) for each element.
   3.104 +    /// Constructor.
   3.105 +    /// \param map A map that assigns \c int values to the items.
   3.106 +    /// It is used internally to handle the cross references.
   3.107 +    /// The assigned value must be \c PRE_HEAP (<tt>-1</tt>) for each item.
   3.108      explicit BucketHeap(ItemIntMap &map) : _iim(map), _minimum(0) {}
   3.109  
   3.110 -    /// The number of items stored in the heap.
   3.111 +    /// \brief The number of items stored in the heap.
   3.112      ///
   3.113 -    /// \brief Returns the number of items stored in the heap.
   3.114 +    /// This function returns the number of items stored in the heap.
   3.115      int size() const { return _data.size(); }
   3.116  
   3.117 -    /// \brief Checks if the heap stores no items.
   3.118 +    /// \brief Check if the heap is empty.
   3.119      ///
   3.120 -    /// Returns \c true if and only if the heap stores no items.
   3.121 +    /// This function returns \c true if the heap is empty.
   3.122      bool empty() const { return _data.empty(); }
   3.123  
   3.124 -    /// \brief Make empty this heap.
   3.125 +    /// \brief Make the heap empty.
   3.126      ///
   3.127 -    /// Make empty this heap. It does not change the cross reference
   3.128 -    /// map.  If you want to reuse a heap what is not surely empty you
   3.129 -    /// should first clear the heap and after that you should set the
   3.130 -    /// cross reference map for each item to \c PRE_HEAP.
   3.131 +    /// This functon makes the heap empty.
   3.132 +    /// It does not change the cross reference map. If you want to reuse
   3.133 +    /// a heap that is not surely empty, you should first clear it and
   3.134 +    /// then you should set the cross reference map to \c PRE_HEAP
   3.135 +    /// for each item.
   3.136      void clear() {
   3.137        _data.clear(); _first.clear(); _minimum = 0;
   3.138      }
   3.139  
   3.140    private:
   3.141  
   3.142 -    void relocate_last(int idx) {
   3.143 +    void relocateLast(int idx) {
   3.144        if (idx + 1 < int(_data.size())) {
   3.145          _data[idx] = _data.back();
   3.146          if (_data[idx].prev != -1) {
   3.147 @@ -174,19 +182,24 @@
   3.148      }
   3.149  
   3.150    public:
   3.151 +
   3.152      /// \brief Insert a pair of item and priority into the heap.
   3.153      ///
   3.154 -    /// Adds \c p.first to the heap with priority \c p.second.
   3.155 +    /// This function inserts \c p.first to the heap with priority
   3.156 +    /// \c p.second.
   3.157      /// \param p The pair to insert.
   3.158 +    /// \pre \c p.first must not be stored in the heap.
   3.159      void push(const Pair& p) {
   3.160        push(p.first, p.second);
   3.161      }
   3.162  
   3.163      /// \brief Insert an item into the heap with the given priority.
   3.164      ///
   3.165 -    /// Adds \c i to the heap with priority \c p.
   3.166 +    /// This function inserts the given item into the heap with the
   3.167 +    /// given priority.
   3.168      /// \param i The item to insert.
   3.169      /// \param p The priority of the item.
   3.170 +    /// \pre \e i must not be stored in the heap.
   3.171      void push(const Item &i, const Prio &p) {
   3.172        int idx = _data.size();
   3.173        _iim[i] = idx;
   3.174 @@ -197,10 +210,10 @@
   3.175        }
   3.176      }
   3.177  
   3.178 -    /// \brief Returns the item with minimum priority.
   3.179 +    /// \brief Return the item having minimum priority.
   3.180      ///
   3.181 -    /// This method returns the item with minimum priority.
   3.182 -    /// \pre The heap must be nonempty.
   3.183 +    /// This function returns the item having minimum priority.
   3.184 +    /// \pre The heap must be non-empty.
   3.185      Item top() const {
   3.186        while (_first[_minimum] == -1) {
   3.187          Direction::increase(_minimum);
   3.188 @@ -208,10 +221,10 @@
   3.189        return _data[_first[_minimum]].item;
   3.190      }
   3.191  
   3.192 -    /// \brief Returns the minimum priority.
   3.193 +    /// \brief The minimum priority.
   3.194      ///
   3.195 -    /// It returns the minimum priority.
   3.196 -    /// \pre The heap must be nonempty.
   3.197 +    /// This function returns the minimum priority.
   3.198 +    /// \pre The heap must be non-empty.
   3.199      Prio prio() const {
   3.200        while (_first[_minimum] == -1) {
   3.201          Direction::increase(_minimum);
   3.202 @@ -219,9 +232,9 @@
   3.203        return _minimum;
   3.204      }
   3.205  
   3.206 -    /// \brief Deletes the item with minimum priority.
   3.207 +    /// \brief Remove the item having minimum priority.
   3.208      ///
   3.209 -    /// This method deletes the item with minimum priority from the heap.
   3.210 +    /// This function removes the item having minimum priority.
   3.211      /// \pre The heap must be non-empty.
   3.212      void pop() {
   3.213        while (_first[_minimum] == -1) {
   3.214 @@ -230,37 +243,38 @@
   3.215        int idx = _first[_minimum];
   3.216        _iim[_data[idx].item] = -2;
   3.217        unlace(idx);
   3.218 -      relocate_last(idx);
   3.219 +      relocateLast(idx);
   3.220      }
   3.221  
   3.222 -    /// \brief Deletes \c i from the heap.
   3.223 +    /// \brief Remove the given item from the heap.
   3.224      ///
   3.225 -    /// This method deletes item \c i from the heap, if \c i was
   3.226 -    /// already stored in the heap.
   3.227 -    /// \param i The item to erase.
   3.228 +    /// This function removes the given item from the heap if it is
   3.229 +    /// already stored.
   3.230 +    /// \param i The item to delete.
   3.231 +    /// \pre \e i must be in the heap.
   3.232      void erase(const Item &i) {
   3.233        int idx = _iim[i];
   3.234        _iim[_data[idx].item] = -2;
   3.235        unlace(idx);
   3.236 -      relocate_last(idx);
   3.237 +      relocateLast(idx);
   3.238      }
   3.239  
   3.240 -
   3.241 -    /// \brief Returns the priority of \c i.
   3.242 +    /// \brief The priority of the given item.
   3.243      ///
   3.244 -    /// This function returns the priority of item \c i.
   3.245 -    /// \pre \c i must be in the heap.
   3.246 +    /// This function returns the priority of the given item.
   3.247      /// \param i The item.
   3.248 +    /// \pre \e i must be in the heap.
   3.249      Prio operator[](const Item &i) const {
   3.250        int idx = _iim[i];
   3.251        return _data[idx].value;
   3.252      }
   3.253  
   3.254 -    /// \brief \c i gets to the heap with priority \c p independently
   3.255 -    /// if \c i was already there.
   3.256 +    /// \brief Set the priority of an item or insert it, if it is
   3.257 +    /// not stored in the heap.
   3.258      ///
   3.259 -    /// This method calls \ref push(\c i, \c p) if \c i is not stored
   3.260 -    /// in the heap and sets the priority of \c i to \c p otherwise.
   3.261 +    /// This method sets the priority of the given item if it is
   3.262 +    /// already stored in the heap. Otherwise it inserts the given
   3.263 +    /// item into the heap with the given priority.
   3.264      /// \param i The item.
   3.265      /// \param p The priority.
   3.266      void set(const Item &i, const Prio &p) {
   3.267 @@ -274,13 +288,12 @@
   3.268        }
   3.269      }
   3.270  
   3.271 -    /// \brief Decreases the priority of \c i to \c p.
   3.272 +    /// \brief Decrease the priority of an item to the given value.
   3.273      ///
   3.274 -    /// This method decreases the priority of item \c i to \c p.
   3.275 -    /// \pre \c i must be stored in the heap with priority at least \c
   3.276 -    /// p relative to \c Compare.
   3.277 +    /// This function decreases the priority of an item to the given value.
   3.278      /// \param i The item.
   3.279      /// \param p The priority.
   3.280 +    /// \pre \e i must be stored in the heap with priority at least \e p.
   3.281      void decrease(const Item &i, const Prio &p) {
   3.282        int idx = _iim[i];
   3.283        unlace(idx);
   3.284 @@ -291,13 +304,12 @@
   3.285        lace(idx);
   3.286      }
   3.287  
   3.288 -    /// \brief Increases the priority of \c i to \c p.
   3.289 +    /// \brief Increase the priority of an item to the given value.
   3.290      ///
   3.291 -    /// This method sets the priority of item \c i to \c p.
   3.292 -    /// \pre \c i must be stored in the heap with priority at most \c
   3.293 -    /// p relative to \c Compare.
   3.294 +    /// This function increases the priority of an item to the given value.
   3.295      /// \param i The item.
   3.296      /// \param p The priority.
   3.297 +    /// \pre \e i must be stored in the heap with priority at most \e p.
   3.298      void increase(const Item &i, const Prio &p) {
   3.299        int idx = _iim[i];
   3.300        unlace(idx);
   3.301 @@ -305,13 +317,13 @@
   3.302        lace(idx);
   3.303      }
   3.304  
   3.305 -    /// \brief Returns if \c item is in, has already been in, or has
   3.306 -    /// never been in the heap.
   3.307 +    /// \brief Return the state of an item.
   3.308      ///
   3.309 -    /// This method returns PRE_HEAP if \c item has never been in the
   3.310 -    /// heap, IN_HEAP if it is in the heap at the moment, and POST_HEAP
   3.311 -    /// otherwise. In the latter case it is possible that \c item will
   3.312 -    /// get back to the heap again.
   3.313 +    /// This method returns \c PRE_HEAP if the given item has never
   3.314 +    /// been in the heap, \c IN_HEAP if it is in the heap at the moment,
   3.315 +    /// and \c POST_HEAP otherwise.
   3.316 +    /// In the latter case it is possible that the item will get back
   3.317 +    /// to the heap again.
   3.318      /// \param i The item.
   3.319      State state(const Item &i) const {
   3.320        int idx = _iim[i];
   3.321 @@ -319,11 +331,11 @@
   3.322        return State(idx);
   3.323      }
   3.324  
   3.325 -    /// \brief Sets the state of the \c item in the heap.
   3.326 +    /// \brief Set the state of an item in the heap.
   3.327      ///
   3.328 -    /// Sets the state of the \c item in the heap. It can be used to
   3.329 -    /// manually clear the heap when it is important to achive the
   3.330 -    /// better time complexity.
   3.331 +    /// This function sets the state of the given item in the heap.
   3.332 +    /// It can be used to manually clear the heap when it is important
   3.333 +    /// to achive better time complexity.
   3.334      /// \param i The item.
   3.335      /// \param st The state. It should not be \c IN_HEAP.
   3.336      void state(const Item& i, State st) {
   3.337 @@ -359,33 +371,44 @@
   3.338  
   3.339    }; // class BucketHeap
   3.340  
   3.341 -  /// \ingroup auxdat
   3.342 +  /// \ingroup heaps
   3.343    ///
   3.344 -  /// \brief A Simplified Bucket Heap implementation.
   3.345 +  /// \brief Simplified bucket heap data structure.
   3.346    ///
   3.347    /// This class implements a simplified \e bucket \e heap data
   3.348 -  /// structure.  It does not provide some functionality but it faster
   3.349 -  /// and simplier data structure than the BucketHeap. The main
   3.350 -  /// difference is that the BucketHeap stores for every key a double
   3.351 -  /// linked list while this class stores just simple lists. In the
   3.352 -  /// other way it does not support erasing each elements just the
   3.353 -  /// minimal and it does not supports key increasing, decreasing.
   3.354 +  /// structure. It does not provide some functionality, but it is
   3.355 +  /// faster and simpler than BucketHeap. The main difference is
   3.356 +  /// that BucketHeap stores a doubly-linked list for each key while
   3.357 +  /// this class stores only simply-linked lists. It supports erasing
   3.358 +  /// only for the item having minimum priority and it does not support
   3.359 +  /// key increasing and decreasing.
   3.360    ///
   3.361 -  /// \param IM A read and write Item int map, used internally
   3.362 -  /// to handle the cross references.
   3.363 -  /// \param MIN If the given parameter is false then instead of the
   3.364 -  /// minimum value the maximum can be retrivied with the top() and
   3.365 -  /// prio() member functions.
   3.366 +  /// Note that this implementation does not conform to the
   3.367 +  /// \ref concepts::Heap "heap concept" due to the lack of some 
   3.368 +  /// functionality.
   3.369 +  ///
   3.370 +  /// \tparam IM A read-writable item map with \c int values, used
   3.371 +  /// internally to handle the cross references.
   3.372 +  /// \tparam MIN Indicate if the heap is a \e min-heap or a \e max-heap.
   3.373 +  /// The default is \e min-heap. If this parameter is set to \c false,
   3.374 +  /// then the comparison is reversed, so the top(), prio() and pop()
   3.375 +  /// functions deal with the item having maximum priority instead of the
   3.376 +  /// minimum.
   3.377    ///
   3.378    /// \sa BucketHeap
   3.379    template <typename IM, bool MIN = true >
   3.380    class SimpleBucketHeap {
   3.381  
   3.382    public:
   3.383 -    typedef typename IM::Key Item;
   3.384 +
   3.385 +    /// Type of the item-int map.
   3.386 +    typedef IM ItemIntMap;
   3.387 +    /// Type of the priorities.
   3.388      typedef int Prio;
   3.389 -    typedef std::pair<Item, Prio> Pair;
   3.390 -    typedef IM ItemIntMap;
   3.391 +    /// Type of the items stored in the heap.
   3.392 +    typedef typename ItemIntMap::Key Item;
   3.393 +    /// Type of the item-priority pairs.
   3.394 +    typedef std::pair<Item,Prio> Pair;
   3.395  
   3.396    private:
   3.397  
   3.398 @@ -393,10 +416,10 @@
   3.399  
   3.400    public:
   3.401  
   3.402 -    /// \brief Type to represent the items states.
   3.403 +    /// \brief Type to represent the states of the items.
   3.404      ///
   3.405 -    /// Each Item element have a state associated to it. It may be "in heap",
   3.406 -    /// "pre heap" or "post heap". The latter two are indifferent from the
   3.407 +    /// Each item has a state associated to it. It can be "in heap",
   3.408 +    /// "pre-heap" or "post-heap". The latter two are indifferent from the
   3.409      /// heap's point of view, but may be useful to the user.
   3.410      ///
   3.411      /// The item-int map must be initialized in such way that it assigns
   3.412 @@ -409,48 +432,53 @@
   3.413  
   3.414    public:
   3.415  
   3.416 -    /// \brief The constructor.
   3.417 +    /// \brief Constructor.
   3.418      ///
   3.419 -    /// The constructor.
   3.420 -    /// \param map should be given to the constructor, since it is used
   3.421 -    /// internally to handle the cross references. The value of the map
   3.422 -    /// should be PRE_HEAP (-1) for each element.
   3.423 +    /// Constructor.
   3.424 +    /// \param map A map that assigns \c int values to the items.
   3.425 +    /// It is used internally to handle the cross references.
   3.426 +    /// The assigned value must be \c PRE_HEAP (<tt>-1</tt>) for each item.
   3.427      explicit SimpleBucketHeap(ItemIntMap &map)
   3.428        : _iim(map), _free(-1), _num(0), _minimum(0) {}
   3.429  
   3.430 -    /// \brief Returns the number of items stored in the heap.
   3.431 +    /// \brief The number of items stored in the heap.
   3.432      ///
   3.433 -    /// The number of items stored in the heap.
   3.434 +    /// This function returns the number of items stored in the heap.
   3.435      int size() const { return _num; }
   3.436  
   3.437 -    /// \brief Checks if the heap stores no items.
   3.438 +    /// \brief Check if the heap is empty.
   3.439      ///
   3.440 -    /// Returns \c true if and only if the heap stores no items.
   3.441 +    /// This function returns \c true if the heap is empty.
   3.442      bool empty() const { return _num == 0; }
   3.443  
   3.444 -    /// \brief Make empty this heap.
   3.445 +    /// \brief Make the heap empty.
   3.446      ///
   3.447 -    /// Make empty this heap. It does not change the cross reference
   3.448 -    /// map.  If you want to reuse a heap what is not surely empty you
   3.449 -    /// should first clear the heap and after that you should set the
   3.450 -    /// cross reference map for each item to \c PRE_HEAP.
   3.451 +    /// This functon makes the heap empty.
   3.452 +    /// It does not change the cross reference map. If you want to reuse
   3.453 +    /// a heap that is not surely empty, you should first clear it and
   3.454 +    /// then you should set the cross reference map to \c PRE_HEAP
   3.455 +    /// for each item.
   3.456      void clear() {
   3.457        _data.clear(); _first.clear(); _free = -1; _num = 0; _minimum = 0;
   3.458      }
   3.459  
   3.460      /// \brief Insert a pair of item and priority into the heap.
   3.461      ///
   3.462 -    /// Adds \c p.first to the heap with priority \c p.second.
   3.463 +    /// This function inserts \c p.first to the heap with priority
   3.464 +    /// \c p.second.
   3.465      /// \param p The pair to insert.
   3.466 +    /// \pre \c p.first must not be stored in the heap.
   3.467      void push(const Pair& p) {
   3.468        push(p.first, p.second);
   3.469      }
   3.470  
   3.471      /// \brief Insert an item into the heap with the given priority.
   3.472      ///
   3.473 -    /// Adds \c i to the heap with priority \c p.
   3.474 +    /// This function inserts the given item into the heap with the
   3.475 +    /// given priority.
   3.476      /// \param i The item to insert.
   3.477      /// \param p The priority of the item.
   3.478 +    /// \pre \e i must not be stored in the heap.
   3.479      void push(const Item &i, const Prio &p) {
   3.480        int idx;
   3.481        if (_free == -1) {
   3.482 @@ -471,10 +499,10 @@
   3.483        ++_num;
   3.484      }
   3.485  
   3.486 -    /// \brief Returns the item with minimum priority.
   3.487 +    /// \brief Return the item having minimum priority.
   3.488      ///
   3.489 -    /// This method returns the item with minimum priority.
   3.490 -    /// \pre The heap must be nonempty.
   3.491 +    /// This function returns the item having minimum priority.
   3.492 +    /// \pre The heap must be non-empty.
   3.493      Item top() const {
   3.494        while (_first[_minimum] == -1) {
   3.495          Direction::increase(_minimum);
   3.496 @@ -482,10 +510,10 @@
   3.497        return _data[_first[_minimum]].item;
   3.498      }
   3.499  
   3.500 -    /// \brief Returns the minimum priority.
   3.501 +    /// \brief The minimum priority.
   3.502      ///
   3.503 -    /// It returns the minimum priority.
   3.504 -    /// \pre The heap must be nonempty.
   3.505 +    /// This function returns the minimum priority.
   3.506 +    /// \pre The heap must be non-empty.
   3.507      Prio prio() const {
   3.508        while (_first[_minimum] == -1) {
   3.509          Direction::increase(_minimum);
   3.510 @@ -493,9 +521,9 @@
   3.511        return _minimum;
   3.512      }
   3.513  
   3.514 -    /// \brief Deletes the item with minimum priority.
   3.515 +    /// \brief Remove the item having minimum priority.
   3.516      ///
   3.517 -    /// This method deletes the item with minimum priority from the heap.
   3.518 +    /// This function removes the item having minimum priority.
   3.519      /// \pre The heap must be non-empty.
   3.520      void pop() {
   3.521        while (_first[_minimum] == -1) {
   3.522 @@ -509,16 +537,15 @@
   3.523        --_num;
   3.524      }
   3.525  
   3.526 -    /// \brief Returns the priority of \c i.
   3.527 +    /// \brief The priority of the given item.
   3.528      ///
   3.529 -    /// This function returns the priority of item \c i.
   3.530 -    /// \warning This operator is not a constant time function
   3.531 -    /// because it scans the whole data structure to find the proper
   3.532 -    /// value.
   3.533 -    /// \pre \c i must be in the heap.
   3.534 +    /// This function returns the priority of the given item.
   3.535      /// \param i The item.
   3.536 +    /// \pre \e i must be in the heap.
   3.537 +    /// \warning This operator is not a constant time function because
   3.538 +    /// it scans the whole data structure to find the proper value.
   3.539      Prio operator[](const Item &i) const {
   3.540 -      for (int k = 0; k < _first.size(); ++k) {
   3.541 +      for (int k = 0; k < int(_first.size()); ++k) {
   3.542          int idx = _first[k];
   3.543          while (idx != -1) {
   3.544            if (_data[idx].item == i) {
   3.545 @@ -530,13 +557,13 @@
   3.546        return -1;
   3.547      }
   3.548  
   3.549 -    /// \brief Returns if \c item is in, has already been in, or has
   3.550 -    /// never been in the heap.
   3.551 +    /// \brief Return the state of an item.
   3.552      ///
   3.553 -    /// This method returns PRE_HEAP if \c item has never been in the
   3.554 -    /// heap, IN_HEAP if it is in the heap at the moment, and POST_HEAP
   3.555 -    /// otherwise. In the latter case it is possible that \c item will
   3.556 -    /// get back to the heap again.
   3.557 +    /// This method returns \c PRE_HEAP if the given item has never
   3.558 +    /// been in the heap, \c IN_HEAP if it is in the heap at the moment,
   3.559 +    /// and \c POST_HEAP otherwise.
   3.560 +    /// In the latter case it is possible that the item will get back
   3.561 +    /// to the heap again.
   3.562      /// \param i The item.
   3.563      State state(const Item &i) const {
   3.564        int idx = _iim[i];
     4.1 --- a/lemon/concepts/heap.h	Mon Aug 31 10:03:23 2009 +0200
     4.2 +++ b/lemon/concepts/heap.h	Mon Aug 31 20:27:38 2009 +0200
     4.3 @@ -16,13 +16,13 @@
     4.4   *
     4.5   */
     4.6  
     4.7 +#ifndef LEMON_CONCEPTS_HEAP_H
     4.8 +#define LEMON_CONCEPTS_HEAP_H
     4.9 +
    4.10  ///\ingroup concept
    4.11  ///\file
    4.12  ///\brief The concept of heaps.
    4.13  
    4.14 -#ifndef LEMON_CONCEPTS_HEAP_H
    4.15 -#define LEMON_CONCEPTS_HEAP_H
    4.16 -
    4.17  #include <lemon/core.h>
    4.18  #include <lemon/concept_check.h>
    4.19  
    4.20 @@ -35,21 +35,27 @@
    4.21  
    4.22      /// \brief The heap concept.
    4.23      ///
    4.24 -    /// Concept class describing the main interface of heaps. A \e heap
    4.25 -    /// is a data structure for storing items with specified values called
    4.26 -    /// \e priorities in such a way that finding the item with minimum
    4.27 -    /// priority is efficient. In a heap one can change the priority of an
    4.28 -    /// item, add or erase an item, etc.
    4.29 +    /// This concept class describes the main interface of heaps.
    4.30 +    /// The various \ref heaps "heap structures" are efficient
    4.31 +    /// implementations of the abstract data type \e priority \e queue.
    4.32 +    /// They store items with specified values called \e priorities
    4.33 +    /// in such a way that finding and removing the item with minimum
    4.34 +    /// priority are efficient. The basic operations are adding and
    4.35 +    /// erasing items, changing the priority of an item, etc.
    4.36      ///
    4.37 -    /// \tparam PR Type of the priority of the items.
    4.38 -    /// \tparam IM A read and writable item map with int values, used
    4.39 +    /// Heaps are crucial in several algorithms, such as Dijkstra and Prim.
    4.40 +    /// Any class that conforms to this concept can be used easily in such
    4.41 +    /// algorithms.
    4.42 +    ///
    4.43 +    /// \tparam PR Type of the priorities of the items.
    4.44 +    /// \tparam IM A read-writable item map with \c int values, used
    4.45      /// internally to handle the cross references.
    4.46 -    /// \tparam Comp A functor class for the ordering of the priorities.
    4.47 +    /// \tparam CMP A functor class for comparing the priorities.
    4.48      /// The default is \c std::less<PR>.
    4.49  #ifdef DOXYGEN
    4.50 -    template <typename PR, typename IM, typename Comp = std::less<PR> >
    4.51 +    template <typename PR, typename IM, typename CMP>
    4.52  #else
    4.53 -    template <typename PR, typename IM>
    4.54 +    template <typename PR, typename IM, typename CMP = std::less<PR> >
    4.55  #endif
    4.56      class Heap {
    4.57      public:
    4.58 @@ -64,109 +70,125 @@
    4.59        /// \brief Type to represent the states of the items.
    4.60        ///
    4.61        /// Each item has a state associated to it. It can be "in heap",
    4.62 -      /// "pre heap" or "post heap". The later two are indifferent
    4.63 -      /// from the point of view of the heap, but may be useful for
    4.64 -      /// the user.
    4.65 +      /// "pre-heap" or "post-heap". The latter two are indifferent from the
    4.66 +      /// heap's point of view, but may be useful to the user.
    4.67        ///
    4.68        /// The item-int map must be initialized in such way that it assigns
    4.69        /// \c PRE_HEAP (<tt>-1</tt>) to any element to be put in the heap.
    4.70        enum State {
    4.71          IN_HEAP = 0,    ///< = 0. The "in heap" state constant.
    4.72 -        PRE_HEAP = -1,  ///< = -1. The "pre heap" state constant.
    4.73 -        POST_HEAP = -2  ///< = -2. The "post heap" state constant.
    4.74 +        PRE_HEAP = -1,  ///< = -1. The "pre-heap" state constant.
    4.75 +        POST_HEAP = -2  ///< = -2. The "post-heap" state constant.
    4.76        };
    4.77  
    4.78 -      /// \brief The constructor.
    4.79 +      /// \brief Constructor.
    4.80        ///
    4.81 -      /// The constructor.
    4.82 +      /// Constructor.
    4.83        /// \param map A map that assigns \c int values to keys of type
    4.84        /// \c Item. It is used internally by the heap implementations to
    4.85        /// handle the cross references. The assigned value must be
    4.86 -      /// \c PRE_HEAP (<tt>-1</tt>) for every item.
    4.87 +      /// \c PRE_HEAP (<tt>-1</tt>) for each item.
    4.88        explicit Heap(ItemIntMap &map) {}
    4.89  
    4.90 +      /// \brief Constructor.
    4.91 +      ///
    4.92 +      /// Constructor.
    4.93 +      /// \param map A map that assigns \c int values to keys of type
    4.94 +      /// \c Item. It is used internally by the heap implementations to
    4.95 +      /// handle the cross references. The assigned value must be
    4.96 +      /// \c PRE_HEAP (<tt>-1</tt>) for each item.
    4.97 +      /// \param comp The function object used for comparing the priorities.
    4.98 +      explicit Heap(ItemIntMap &map, const CMP &comp) {}
    4.99 +
   4.100        /// \brief The number of items stored in the heap.
   4.101        ///
   4.102 -      /// Returns the number of items stored in the heap.
   4.103 +      /// This function returns the number of items stored in the heap.
   4.104        int size() const { return 0; }
   4.105  
   4.106 -      /// \brief Checks if the heap is empty.
   4.107 +      /// \brief Check if the heap is empty.
   4.108        ///
   4.109 -      /// Returns \c true if the heap is empty.
   4.110 +      /// This function returns \c true if the heap is empty.
   4.111        bool empty() const { return false; }
   4.112  
   4.113 -      /// \brief Makes the heap empty.
   4.114 +      /// \brief Make the heap empty.
   4.115        ///
   4.116 -      /// Makes the heap empty.
   4.117 -      void clear();
   4.118 +      /// This functon makes the heap empty.
   4.119 +      /// It does not change the cross reference map. If you want to reuse
   4.120 +      /// a heap that is not surely empty, you should first clear it and
   4.121 +      /// then you should set the cross reference map to \c PRE_HEAP
   4.122 +      /// for each item.
   4.123 +      void clear() {}
   4.124  
   4.125 -      /// \brief Inserts an item into the heap with the given priority.
   4.126 +      /// \brief Insert an item into the heap with the given priority.
   4.127        ///
   4.128 -      /// Inserts the given item into the heap with the given priority.
   4.129 +      /// This function inserts the given item into the heap with the
   4.130 +      /// given priority.
   4.131        /// \param i The item to insert.
   4.132        /// \param p The priority of the item.
   4.133 +      /// \pre \e i must not be stored in the heap.
   4.134        void push(const Item &i, const Prio &p) {}
   4.135  
   4.136 -      /// \brief Returns the item having minimum priority.
   4.137 +      /// \brief Return the item having minimum priority.
   4.138        ///
   4.139 -      /// Returns the item having minimum priority.
   4.140 +      /// This function returns the item having minimum priority.
   4.141        /// \pre The heap must be non-empty.
   4.142        Item top() const {}
   4.143  
   4.144        /// \brief The minimum priority.
   4.145        ///
   4.146 -      /// Returns the minimum priority.
   4.147 +      /// This function returns the minimum priority.
   4.148        /// \pre The heap must be non-empty.
   4.149        Prio prio() const {}
   4.150  
   4.151 -      /// \brief Removes the item having minimum priority.
   4.152 +      /// \brief Remove the item having minimum priority.
   4.153        ///
   4.154 -      /// Removes the item having minimum priority.
   4.155 +      /// This function removes the item having minimum priority.
   4.156        /// \pre The heap must be non-empty.
   4.157        void pop() {}
   4.158  
   4.159 -      /// \brief Removes an item from the heap.
   4.160 +      /// \brief Remove the given item from the heap.
   4.161        ///
   4.162 -      /// Removes the given item from the heap if it is already stored.
   4.163 +      /// This function removes the given item from the heap if it is
   4.164 +      /// already stored.
   4.165        /// \param i The item to delete.
   4.166 +      /// \pre \e i must be in the heap.
   4.167        void erase(const Item &i) {}
   4.168  
   4.169 -      /// \brief The priority of an item.
   4.170 +      /// \brief The priority of the given item.
   4.171        ///
   4.172 -      /// Returns the priority of the given item.
   4.173 +      /// This function returns the priority of the given item.
   4.174        /// \param i The item.
   4.175 -      /// \pre \c i must be in the heap.
   4.176 +      /// \pre \e i must be in the heap.
   4.177        Prio operator[](const Item &i) const {}
   4.178  
   4.179 -      /// \brief Sets the priority of an item or inserts it, if it is
   4.180 +      /// \brief Set the priority of an item or insert it, if it is
   4.181        /// not stored in the heap.
   4.182        ///
   4.183        /// This method sets the priority of the given item if it is
   4.184 -      /// already stored in the heap.
   4.185 -      /// Otherwise it inserts the given item with the given priority.
   4.186 +      /// already stored in the heap. Otherwise it inserts the given
   4.187 +      /// item into the heap with the given priority.
   4.188        ///
   4.189        /// \param i The item.
   4.190        /// \param p The priority.
   4.191        void set(const Item &i, const Prio &p) {}
   4.192  
   4.193 -      /// \brief Decreases the priority of an item to the given value.
   4.194 +      /// \brief Decrease the priority of an item to the given value.
   4.195        ///
   4.196 -      /// Decreases the priority of an item to the given value.
   4.197 +      /// This function decreases the priority of an item to the given value.
   4.198        /// \param i The item.
   4.199        /// \param p The priority.
   4.200 -      /// \pre \c i must be stored in the heap with priority at least \c p.
   4.201 +      /// \pre \e i must be stored in the heap with priority at least \e p.
   4.202        void decrease(const Item &i, const Prio &p) {}
   4.203  
   4.204 -      /// \brief Increases the priority of an item to the given value.
   4.205 +      /// \brief Increase the priority of an item to the given value.
   4.206        ///
   4.207 -      /// Increases the priority of an item to the given value.
   4.208 +      /// This function increases the priority of an item to the given value.
   4.209        /// \param i The item.
   4.210        /// \param p The priority.
   4.211 -      /// \pre \c i must be stored in the heap with priority at most \c p.
   4.212 +      /// \pre \e i must be stored in the heap with priority at most \e p.
   4.213        void increase(const Item &i, const Prio &p) {}
   4.214  
   4.215 -      /// \brief Returns if an item is in, has already been in, or has
   4.216 -      /// never been in the heap.
   4.217 +      /// \brief Return the state of an item.
   4.218        ///
   4.219        /// This method returns \c PRE_HEAP if the given item has never
   4.220        /// been in the heap, \c IN_HEAP if it is in the heap at the moment,
   4.221 @@ -176,11 +198,11 @@
   4.222        /// \param i The item.
   4.223        State state(const Item &i) const {}
   4.224  
   4.225 -      /// \brief Sets the state of an item in the heap.
   4.226 +      /// \brief Set the state of an item in the heap.
   4.227        ///
   4.228 -      /// Sets the state of the given item in the heap. It can be used
   4.229 -      /// to manually clear the heap when it is important to achive the
   4.230 -      /// better time complexity.
   4.231 +      /// This function sets the state of the given item in the heap.
   4.232 +      /// It can be used to manually clear the heap when it is important
   4.233 +      /// to achive better time complexity.
   4.234        /// \param i The item.
   4.235        /// \param st The state. It should not be \c IN_HEAP.
   4.236        void state(const Item& i, State st) {}
     5.1 --- a/lemon/fib_heap.h	Mon Aug 31 10:03:23 2009 +0200
     5.2 +++ b/lemon/fib_heap.h	Mon Aug 31 20:27:38 2009 +0200
     5.3 @@ -20,53 +20,49 @@
     5.4  #define LEMON_FIB_HEAP_H
     5.5  
     5.6  ///\file
     5.7 -///\ingroup auxdat
     5.8 -///\brief Fibonacci Heap implementation.
     5.9 +///\ingroup heaps
    5.10 +///\brief Fibonacci heap implementation.
    5.11  
    5.12  #include <vector>
    5.13 +#include <utility>
    5.14  #include <functional>
    5.15  #include <lemon/math.h>
    5.16  
    5.17  namespace lemon {
    5.18  
    5.19 -  /// \ingroup auxdat
    5.20 +  /// \ingroup heaps
    5.21    ///
    5.22 -  ///\brief Fibonacci Heap.
    5.23 +  /// \brief Fibonacci heap data structure.
    5.24    ///
    5.25 -  ///This class implements the \e Fibonacci \e heap data structure. A \e heap
    5.26 -  ///is a data structure for storing items with specified values called \e
    5.27 -  ///priorities in such a way that finding the item with minimum priority is
    5.28 -  ///efficient. \c CMP specifies the ordering of the priorities. In a heap
    5.29 -  ///one can change the priority of an item, add or erase an item, etc.
    5.30 +  /// This class implements the \e Fibonacci \e heap data structure.
    5.31 +  /// It fully conforms to the \ref concepts::Heap "heap concept".
    5.32    ///
    5.33 -  ///The methods \ref increase and \ref erase are not efficient in a Fibonacci
    5.34 -  ///heap. In case of many calls to these operations, it is better to use a
    5.35 -  ///\ref BinHeap "binary heap".
    5.36 +  /// The methods \ref increase() and \ref erase() are not efficient in a
    5.37 +  /// Fibonacci heap. In case of many calls of these operations, it is
    5.38 +  /// better to use other heap structure, e.g. \ref BinHeap "binary heap".
    5.39    ///
    5.40 -  ///\param PRIO Type of the priority of the items.
    5.41 -  ///\param IM A read and writable Item int map, used internally
    5.42 -  ///to handle the cross references.
    5.43 -  ///\param CMP A class for the ordering of the priorities. The
    5.44 -  ///default is \c std::less<PRIO>.
    5.45 -  ///
    5.46 -  ///\sa BinHeap
    5.47 -  ///\sa Dijkstra
    5.48 +  /// \tparam PR Type of the priorities of the items.
    5.49 +  /// \tparam IM A read-writable item map with \c int values, used
    5.50 +  /// internally to handle the cross references.
    5.51 +  /// \tparam CMP A functor class for comparing the priorities.
    5.52 +  /// The default is \c std::less<PR>.
    5.53  #ifdef DOXYGEN
    5.54 -  template <typename PRIO, typename IM, typename CMP>
    5.55 +  template <typename PR, typename IM, typename CMP>
    5.56  #else
    5.57 -  template <typename PRIO, typename IM, typename CMP = std::less<PRIO> >
    5.58 +  template <typename PR, typename IM, typename CMP = std::less<PR> >
    5.59  #endif
    5.60    class FibHeap {
    5.61    public:
    5.62 -    ///\e
    5.63 +
    5.64 +    /// Type of the item-int map.
    5.65      typedef IM ItemIntMap;
    5.66 -    ///\e
    5.67 -    typedef PRIO Prio;
    5.68 -    ///\e
    5.69 +    /// Type of the priorities.
    5.70 +    typedef PR Prio;
    5.71 +    /// Type of the items stored in the heap.
    5.72      typedef typename ItemIntMap::Key Item;
    5.73 -    ///\e
    5.74 +    /// Type of the item-priority pairs.
    5.75      typedef std::pair<Item,Prio> Pair;
    5.76 -    ///\e
    5.77 +    /// Functor type for comparing the priorities.
    5.78      typedef CMP Compare;
    5.79  
    5.80    private:
    5.81 @@ -80,10 +76,10 @@
    5.82  
    5.83    public:
    5.84  
    5.85 -    /// \brief Type to represent the items states.
    5.86 +    /// \brief Type to represent the states of the items.
    5.87      ///
    5.88 -    /// Each Item element have a state associated to it. It may be "in heap",
    5.89 -    /// "pre heap" or "post heap". The latter two are indifferent from the
    5.90 +    /// Each item has a state associated to it. It can be "in heap",
    5.91 +    /// "pre-heap" or "post-heap". The latter two are indifferent from the
    5.92      /// heap's point of view, but may be useful to the user.
    5.93      ///
    5.94      /// The item-int map must be initialized in such way that it assigns
    5.95 @@ -94,60 +90,54 @@
    5.96        POST_HEAP = -2  ///< = -2.
    5.97      };
    5.98  
    5.99 -    /// \brief The constructor
   5.100 +    /// \brief Constructor.
   5.101      ///
   5.102 -    /// \c map should be given to the constructor, since it is
   5.103 -    ///   used internally to handle the cross references.
   5.104 +    /// Constructor.
   5.105 +    /// \param map A map that assigns \c int values to the items.
   5.106 +    /// It is used internally to handle the cross references.
   5.107 +    /// The assigned value must be \c PRE_HEAP (<tt>-1</tt>) for each item.
   5.108      explicit FibHeap(ItemIntMap &map)
   5.109        : _minimum(0), _iim(map), _num() {}
   5.110  
   5.111 -    /// \brief The constructor
   5.112 +    /// \brief Constructor.
   5.113      ///
   5.114 -    /// \c map should be given to the constructor, since it is used
   5.115 -    /// internally to handle the cross references. \c comp is an
   5.116 -    /// object for ordering of the priorities.
   5.117 +    /// Constructor.
   5.118 +    /// \param map A map that assigns \c int values to the items.
   5.119 +    /// It is used internally to handle the cross references.
   5.120 +    /// The assigned value must be \c PRE_HEAP (<tt>-1</tt>) for each item.
   5.121 +    /// \param comp The function object used for comparing the priorities.
   5.122      FibHeap(ItemIntMap &map, const Compare &comp)
   5.123        : _minimum(0), _iim(map), _comp(comp), _num() {}
   5.124  
   5.125      /// \brief The number of items stored in the heap.
   5.126      ///
   5.127 -    /// Returns the number of items stored in the heap.
   5.128 +    /// This function returns the number of items stored in the heap.
   5.129      int size() const { return _num; }
   5.130  
   5.131 -    /// \brief Checks if the heap stores no items.
   5.132 +    /// \brief Check if the heap is empty.
   5.133      ///
   5.134 -    ///   Returns \c true if and only if the heap stores no items.
   5.135 +    /// This function returns \c true if the heap is empty.
   5.136      bool empty() const { return _num==0; }
   5.137  
   5.138 -    /// \brief Make empty this heap.
   5.139 +    /// \brief Make the heap empty.
   5.140      ///
   5.141 -    /// Make empty this heap. It does not change the cross reference
   5.142 -    /// map.  If you want to reuse a heap what is not surely empty you
   5.143 -    /// should first clear the heap and after that you should set the
   5.144 -    /// cross reference map for each item to \c PRE_HEAP.
   5.145 +    /// This functon makes the heap empty.
   5.146 +    /// It does not change the cross reference map. If you want to reuse
   5.147 +    /// a heap that is not surely empty, you should first clear it and
   5.148 +    /// then you should set the cross reference map to \c PRE_HEAP
   5.149 +    /// for each item.
   5.150      void clear() {
   5.151        _data.clear(); _minimum = 0; _num = 0;
   5.152      }
   5.153  
   5.154 -    /// \brief \c item gets to the heap with priority \c value independently
   5.155 -    /// if \c item was already there.
   5.156 +    /// \brief Insert an item into the heap with the given priority.
   5.157      ///
   5.158 -    /// This method calls \ref push(\c item, \c value) if \c item is not
   5.159 -    /// stored in the heap and it calls \ref decrease(\c item, \c value) or
   5.160 -    /// \ref increase(\c item, \c value) otherwise.
   5.161 -    void set (const Item& item, const Prio& value) {
   5.162 -      int i=_iim[item];
   5.163 -      if ( i >= 0 && _data[i].in ) {
   5.164 -        if ( _comp(value, _data[i].prio) ) decrease(item, value);
   5.165 -        if ( _comp(_data[i].prio, value) ) increase(item, value);
   5.166 -      } else push(item, value);
   5.167 -    }
   5.168 -
   5.169 -    /// \brief Adds \c item to the heap with priority \c value.
   5.170 -    ///
   5.171 -    /// Adds \c item to the heap with priority \c value.
   5.172 -    /// \pre \c item must not be stored in the heap.
   5.173 -    void push (const Item& item, const Prio& value) {
   5.174 +    /// This function inserts the given item into the heap with the
   5.175 +    /// given priority.
   5.176 +    /// \param item The item to insert.
   5.177 +    /// \param prio The priority of the item.
   5.178 +    /// \pre \e item must not be stored in the heap.
   5.179 +    void push (const Item& item, const Prio& prio) {
   5.180        int i=_iim[item];
   5.181        if ( i < 0 ) {
   5.182          int s=_data.size();
   5.183 @@ -168,47 +158,37 @@
   5.184          _data[i].right_neighbor=_data[_minimum].right_neighbor;
   5.185          _data[_minimum].right_neighbor=i;
   5.186          _data[i].left_neighbor=_minimum;
   5.187 -        if ( _comp( value, _data[_minimum].prio) ) _minimum=i;
   5.188 +        if ( _comp( prio, _data[_minimum].prio) ) _minimum=i;
   5.189        } else {
   5.190          _data[i].right_neighbor=_data[i].left_neighbor=i;
   5.191          _minimum=i;
   5.192        }
   5.193 -      _data[i].prio=value;
   5.194 +      _data[i].prio=prio;
   5.195        ++_num;
   5.196      }
   5.197  
   5.198 -    /// \brief Returns the item with minimum priority relative to \c Compare.
   5.199 +    /// \brief Return the item having minimum priority.
   5.200      ///
   5.201 -    /// This method returns the item with minimum priority relative to \c
   5.202 -    /// Compare.
   5.203 -    /// \pre The heap must be nonempty.
   5.204 +    /// This function returns the item having minimum priority.
   5.205 +    /// \pre The heap must be non-empty.
   5.206      Item top() const { return _data[_minimum].name; }
   5.207  
   5.208 -    /// \brief Returns the minimum priority relative to \c Compare.
   5.209 +    /// \brief The minimum priority.
   5.210      ///
   5.211 -    /// It returns the minimum priority relative to \c Compare.
   5.212 -    /// \pre The heap must be nonempty.
   5.213 -    const Prio& prio() const { return _data[_minimum].prio; }
   5.214 +    /// This function returns the minimum priority.
   5.215 +    /// \pre The heap must be non-empty.
   5.216 +    Prio prio() const { return _data[_minimum].prio; }
   5.217  
   5.218 -    /// \brief Returns the priority of \c item.
   5.219 +    /// \brief Remove the item having minimum priority.
   5.220      ///
   5.221 -    /// It returns the priority of \c item.
   5.222 -    /// \pre \c item must be in the heap.
   5.223 -    const Prio& operator[](const Item& item) const {
   5.224 -      return _data[_iim[item]].prio;
   5.225 -    }
   5.226 -
   5.227 -    /// \brief Deletes the item with minimum priority relative to \c Compare.
   5.228 -    ///
   5.229 -    /// This method deletes the item with minimum priority relative to \c
   5.230 -    /// Compare from the heap.
   5.231 +    /// This function removes the item having minimum priority.
   5.232      /// \pre The heap must be non-empty.
   5.233      void pop() {
   5.234        /*The first case is that there are only one root.*/
   5.235        if ( _data[_minimum].left_neighbor==_minimum ) {
   5.236          _data[_minimum].in=false;
   5.237          if ( _data[_minimum].degree!=0 ) {
   5.238 -          makeroot(_data[_minimum].child);
   5.239 +          makeRoot(_data[_minimum].child);
   5.240            _minimum=_data[_minimum].child;
   5.241            balance();
   5.242          }
   5.243 @@ -221,7 +201,7 @@
   5.244            int child=_data[_minimum].child;
   5.245            int last_child=_data[child].left_neighbor;
   5.246  
   5.247 -          makeroot(child);
   5.248 +          makeRoot(child);
   5.249  
   5.250            _data[left].right_neighbor=child;
   5.251            _data[child].left_neighbor=left;
   5.252 @@ -234,10 +214,12 @@
   5.253        --_num;
   5.254      }
   5.255  
   5.256 -    /// \brief Deletes \c item from the heap.
   5.257 +    /// \brief Remove the given item from the heap.
   5.258      ///
   5.259 -    /// This method deletes \c item from the heap, if \c item was already
   5.260 -    /// stored in the heap. It is quite inefficient in Fibonacci heaps.
   5.261 +    /// This function removes the given item from the heap if it is
   5.262 +    /// already stored.
   5.263 +    /// \param item The item to delete.
   5.264 +    /// \pre \e item must be in the heap.
   5.265      void erase (const Item& item) {
   5.266        int i=_iim[item];
   5.267  
   5.268 @@ -252,43 +234,68 @@
   5.269        }
   5.270      }
   5.271  
   5.272 -    /// \brief Decreases the priority of \c item to \c value.
   5.273 +    /// \brief The priority of the given item.
   5.274      ///
   5.275 -    /// This method decreases the priority of \c item to \c value.
   5.276 -    /// \pre \c item must be stored in the heap with priority at least \c
   5.277 -    ///   value relative to \c Compare.
   5.278 -    void decrease (Item item, const Prio& value) {
   5.279 +    /// This function returns the priority of the given item.
   5.280 +    /// \param item The item.
   5.281 +    /// \pre \e item must be in the heap.
   5.282 +    Prio operator[](const Item& item) const {
   5.283 +      return _data[_iim[item]].prio;
   5.284 +    }
   5.285 +
   5.286 +    /// \brief Set the priority of an item or insert it, if it is
   5.287 +    /// not stored in the heap.
   5.288 +    ///
   5.289 +    /// This method sets the priority of the given item if it is
   5.290 +    /// already stored in the heap. Otherwise it inserts the given
   5.291 +    /// item into the heap with the given priority.
   5.292 +    /// \param item The item.
   5.293 +    /// \param prio The priority.
   5.294 +    void set (const Item& item, const Prio& prio) {
   5.295        int i=_iim[item];
   5.296 -      _data[i].prio=value;
   5.297 +      if ( i >= 0 && _data[i].in ) {
   5.298 +        if ( _comp(prio, _data[i].prio) ) decrease(item, prio);
   5.299 +        if ( _comp(_data[i].prio, prio) ) increase(item, prio);
   5.300 +      } else push(item, prio);
   5.301 +    }
   5.302 +
   5.303 +    /// \brief Decrease the priority of an item to the given value.
   5.304 +    ///
   5.305 +    /// This function decreases the priority of an item to the given value.
   5.306 +    /// \param item The item.
   5.307 +    /// \param prio The priority.
   5.308 +    /// \pre \e item must be stored in the heap with priority at least \e prio.
   5.309 +    void decrease (const Item& item, const Prio& prio) {
   5.310 +      int i=_iim[item];
   5.311 +      _data[i].prio=prio;
   5.312        int p=_data[i].parent;
   5.313  
   5.314 -      if ( p!=-1 && _comp(value, _data[p].prio) ) {
   5.315 +      if ( p!=-1 && _comp(prio, _data[p].prio) ) {
   5.316          cut(i,p);
   5.317          cascade(p);
   5.318        }
   5.319 -      if ( _comp(value, _data[_minimum].prio) ) _minimum=i;
   5.320 +      if ( _comp(prio, _data[_minimum].prio) ) _minimum=i;
   5.321      }
   5.322  
   5.323 -    /// \brief Increases the priority of \c item to \c value.
   5.324 +    /// \brief Increase the priority of an item to the given value.
   5.325      ///
   5.326 -    /// This method sets the priority of \c item to \c value. Though
   5.327 -    /// there is no precondition on the priority of \c item, this
   5.328 -    /// method should be used only if it is indeed necessary to increase
   5.329 -    /// (relative to \c Compare) the priority of \c item, because this
   5.330 -    /// method is inefficient.
   5.331 -    void increase (Item item, const Prio& value) {
   5.332 +    /// This function increases the priority of an item to the given value.
   5.333 +    /// \param item The item.
   5.334 +    /// \param prio The priority.
   5.335 +    /// \pre \e item must be stored in the heap with priority at most \e prio.
   5.336 +    void increase (const Item& item, const Prio& prio) {
   5.337        erase(item);
   5.338 -      push(item, value);
   5.339 +      push(item, prio);
   5.340      }
   5.341  
   5.342 -
   5.343 -    /// \brief Returns if \c item is in, has already been in, or has never
   5.344 -    /// been in the heap.
   5.345 +    /// \brief Return the state of an item.
   5.346      ///
   5.347 -    /// This method returns PRE_HEAP if \c item has never been in the
   5.348 -    /// heap, IN_HEAP if it is in the heap at the moment, and POST_HEAP
   5.349 -    /// otherwise. In the latter case it is possible that \c item will
   5.350 -    /// get back to the heap again.
   5.351 +    /// This method returns \c PRE_HEAP if the given item has never
   5.352 +    /// been in the heap, \c IN_HEAP if it is in the heap at the moment,
   5.353 +    /// and \c POST_HEAP otherwise.
   5.354 +    /// In the latter case it is possible that the item will get back
   5.355 +    /// to the heap again.
   5.356 +    /// \param item The item.
   5.357      State state(const Item &item) const {
   5.358        int i=_iim[item];
   5.359        if( i>=0 ) {
   5.360 @@ -298,11 +305,11 @@
   5.361        return State(i);
   5.362      }
   5.363  
   5.364 -    /// \brief Sets the state of the \c item in the heap.
   5.365 +    /// \brief Set the state of an item in the heap.
   5.366      ///
   5.367 -    /// Sets the state of the \c item in the heap. It can be used to
   5.368 -    /// manually clear the heap when it is important to achive the
   5.369 -    /// better time _complexity.
   5.370 +    /// This function sets the state of the given item in the heap.
   5.371 +    /// It can be used to manually clear the heap when it is important
   5.372 +    /// to achive better time complexity.
   5.373      /// \param i The item.
   5.374      /// \param st The state. It should not be \c IN_HEAP.
   5.375      void state(const Item& i, State st) {
   5.376 @@ -365,7 +372,7 @@
   5.377        } while ( s != m );
   5.378      }
   5.379  
   5.380 -    void makeroot(int c) {
   5.381 +    void makeRoot(int c) {
   5.382        int s=c;
   5.383        do {
   5.384          _data[s].parent=-1;
     6.1 --- a/lemon/radix_heap.h	Mon Aug 31 10:03:23 2009 +0200
     6.2 +++ b/lemon/radix_heap.h	Mon Aug 31 20:27:38 2009 +0200
     6.3 @@ -19,9 +19,9 @@
     6.4  #ifndef LEMON_RADIX_HEAP_H
     6.5  #define LEMON_RADIX_HEAP_H
     6.6  
     6.7 -///\ingroup auxdat
     6.8 +///\ingroup heaps
     6.9  ///\file
    6.10 -///\brief Radix Heap implementation.
    6.11 +///\brief Radix heap implementation.
    6.12  
    6.13  #include <vector>
    6.14  #include <lemon/error.h>
    6.15 @@ -29,56 +29,54 @@
    6.16  namespace lemon {
    6.17  
    6.18  
    6.19 -  /// \ingroup auxdata
    6.20 +  /// \ingroup heaps
    6.21    ///
    6.22 -  /// \brief A Radix Heap implementation.
    6.23 +  /// \brief Radix heap data structure.
    6.24    ///
    6.25 -  /// This class implements the \e radix \e heap data structure. A \e heap
    6.26 -  /// is a data structure for storing items with specified values called \e
    6.27 -  /// priorities in such a way that finding the item with minimum priority is
    6.28 -  /// efficient. This heap type can store only items with \e int priority.
    6.29 -  /// In a heap one can change the priority of an item, add or erase an
    6.30 -  /// item, but the priority cannot be decreased under the last removed
    6.31 -  /// item's priority.
    6.32 +  /// This class implements the \e radix \e heap data structure.
    6.33 +  /// It practically conforms to the \ref concepts::Heap "heap concept",
    6.34 +  /// but it has some limitations due its special implementation.
    6.35 +  /// The type of the priorities must be \c int and the priority of an
    6.36 +  /// item cannot be decreased under the priority of the last removed item.
    6.37    ///
    6.38 -  /// \param IM A read and writable Item int map, used internally
    6.39 -  /// to handle the cross references.
    6.40 -  ///
    6.41 -  /// \see BinHeap
    6.42 -  /// \see Dijkstra
    6.43 +  /// \tparam IM A read-writable item map with \c int values, used
    6.44 +  /// internally to handle the cross references.
    6.45    template <typename IM>
    6.46    class RadixHeap {
    6.47  
    6.48    public:
    6.49 -    typedef typename IM::Key Item;
    6.50 +
    6.51 +    /// Type of the item-int map.
    6.52 +    typedef IM ItemIntMap;
    6.53 +    /// Type of the priorities.
    6.54      typedef int Prio;
    6.55 -    typedef IM ItemIntMap;
    6.56 +    /// Type of the items stored in the heap.
    6.57 +    typedef typename ItemIntMap::Key Item;
    6.58  
    6.59      /// \brief Exception thrown by RadixHeap.
    6.60      ///
    6.61 -    /// This Exception is thrown when a smaller priority
    6.62 -    /// is inserted into the \e RadixHeap then the last time erased.
    6.63 +    /// This exception is thrown when an item is inserted into a
    6.64 +    /// RadixHeap with a priority smaller than the last erased one.
    6.65      /// \see RadixHeap
    6.66 -
    6.67 -    class UnderFlowPriorityError : public Exception {
    6.68 +    class PriorityUnderflowError : public Exception {
    6.69      public:
    6.70        virtual const char* what() const throw() {
    6.71 -        return "lemon::RadixHeap::UnderFlowPriorityError";
    6.72 +        return "lemon::RadixHeap::PriorityUnderflowError";
    6.73        }
    6.74      };
    6.75  
    6.76 -    /// \brief Type to represent the items states.
    6.77 +    /// \brief Type to represent the states of the items.
    6.78      ///
    6.79 -    /// Each Item element have a state associated to it. It may be "in heap",
    6.80 -    /// "pre heap" or "post heap". The latter two are indifferent from the
    6.81 +    /// Each item has a state associated to it. It can be "in heap",
    6.82 +    /// "pre-heap" or "post-heap". The latter two are indifferent from the
    6.83      /// heap's point of view, but may be useful to the user.
    6.84      ///
    6.85 -    /// The ItemIntMap \e should be initialized in such way that it maps
    6.86 -    /// PRE_HEAP (-1) to any element to be put in the heap...
    6.87 +    /// The item-int map must be initialized in such way that it assigns
    6.88 +    /// \c PRE_HEAP (<tt>-1</tt>) to any element to be put in the heap.
    6.89      enum State {
    6.90 -      IN_HEAP = 0,
    6.91 -      PRE_HEAP = -1,
    6.92 -      POST_HEAP = -2
    6.93 +      IN_HEAP = 0,    ///< = 0.
    6.94 +      PRE_HEAP = -1,  ///< = -1.
    6.95 +      POST_HEAP = -2  ///< = -2.
    6.96      };
    6.97  
    6.98    private:
    6.99 @@ -96,52 +94,55 @@
   6.100        RadixBox(int _min, int _size) : first(-1), min(_min), size(_size) {}
   6.101      };
   6.102  
   6.103 -    std::vector<RadixItem> data;
   6.104 -    std::vector<RadixBox> boxes;
   6.105 +    std::vector<RadixItem> _data;
   6.106 +    std::vector<RadixBox> _boxes;
   6.107  
   6.108      ItemIntMap &_iim;
   6.109  
   6.110 +  public:
   6.111  
   6.112 -  public:
   6.113 -    /// \brief The constructor.
   6.114 +    /// \brief Constructor.
   6.115      ///
   6.116 -    /// The constructor.
   6.117 -    ///
   6.118 -    /// \param map It should be given to the constructor, since it is used
   6.119 -    /// internally to handle the cross references. The value of the map
   6.120 -    /// should be PRE_HEAP (-1) for each element.
   6.121 -    ///
   6.122 -    /// \param minimal The initial minimal value of the heap.
   6.123 -    /// \param capacity It determines the initial capacity of the heap.
   6.124 -    RadixHeap(ItemIntMap &map, int minimal = 0, int capacity = 0)
   6.125 -      : _iim(map) {
   6.126 -      boxes.push_back(RadixBox(minimal, 1));
   6.127 -      boxes.push_back(RadixBox(minimal + 1, 1));
   6.128 -      while (lower(boxes.size() - 1, capacity + minimal - 1)) {
   6.129 +    /// Constructor.
   6.130 +    /// \param map A map that assigns \c int values to the items.
   6.131 +    /// It is used internally to handle the cross references.
   6.132 +    /// The assigned value must be \c PRE_HEAP (<tt>-1</tt>) for each item.
   6.133 +    /// \param minimum The initial minimum value of the heap.
   6.134 +    /// \param capacity The initial capacity of the heap.
   6.135 +    RadixHeap(ItemIntMap &map, int minimum = 0, int capacity = 0)
   6.136 +      : _iim(map)
   6.137 +    {
   6.138 +      _boxes.push_back(RadixBox(minimum, 1));
   6.139 +      _boxes.push_back(RadixBox(minimum + 1, 1));
   6.140 +      while (lower(_boxes.size() - 1, capacity + minimum - 1)) {
   6.141          extend();
   6.142        }
   6.143      }
   6.144  
   6.145 -    /// The number of items stored in the heap.
   6.146 +    /// \brief The number of items stored in the heap.
   6.147      ///
   6.148 -    /// \brief Returns the number of items stored in the heap.
   6.149 -    int size() const { return data.size(); }
   6.150 -    /// \brief Checks if the heap stores no items.
   6.151 +    /// This function returns the number of items stored in the heap.
   6.152 +    int size() const { return _data.size(); }
   6.153 +
   6.154 +    /// \brief Check if the heap is empty.
   6.155      ///
   6.156 -    /// Returns \c true if and only if the heap stores no items.
   6.157 -    bool empty() const { return data.empty(); }
   6.158 +    /// This function returns \c true if the heap is empty.
   6.159 +    bool empty() const { return _data.empty(); }
   6.160  
   6.161 -    /// \brief Make empty this heap.
   6.162 +    /// \brief Make the heap empty.
   6.163      ///
   6.164 -    /// Make empty this heap. It does not change the cross reference
   6.165 -    /// map.  If you want to reuse a heap what is not surely empty you
   6.166 -    /// should first clear the heap and after that you should set the
   6.167 -    /// cross reference map for each item to \c PRE_HEAP.
   6.168 -    void clear(int minimal = 0, int capacity = 0) {
   6.169 -      data.clear(); boxes.clear();
   6.170 -      boxes.push_back(RadixBox(minimal, 1));
   6.171 -      boxes.push_back(RadixBox(minimal + 1, 1));
   6.172 -      while (lower(boxes.size() - 1, capacity + minimal - 1)) {
   6.173 +    /// This functon makes the heap empty.
   6.174 +    /// It does not change the cross reference map. If you want to reuse
   6.175 +    /// a heap that is not surely empty, you should first clear it and
   6.176 +    /// then you should set the cross reference map to \c PRE_HEAP
   6.177 +    /// for each item.
   6.178 +    /// \param minimum The minimum value of the heap.
   6.179 +    /// \param capacity The capacity of the heap.
   6.180 +    void clear(int minimum = 0, int capacity = 0) {
   6.181 +      _data.clear(); _boxes.clear();
   6.182 +      _boxes.push_back(RadixBox(minimum, 1));
   6.183 +      _boxes.push_back(RadixBox(minimum + 1, 1));
   6.184 +      while (lower(_boxes.size() - 1, capacity + minimum - 1)) {
   6.185          extend();
   6.186        }
   6.187      }
   6.188 @@ -149,255 +150,259 @@
   6.189    private:
   6.190  
   6.191      bool upper(int box, Prio pr) {
   6.192 -      return pr < boxes[box].min;
   6.193 +      return pr < _boxes[box].min;
   6.194      }
   6.195  
   6.196      bool lower(int box, Prio pr) {
   6.197 -      return pr >= boxes[box].min + boxes[box].size;
   6.198 +      return pr >= _boxes[box].min + _boxes[box].size;
   6.199      }
   6.200  
   6.201 -    /// \brief Remove item from the box list.
   6.202 +    // Remove item from the box list
   6.203      void remove(int index) {
   6.204 -      if (data[index].prev >= 0) {
   6.205 -        data[data[index].prev].next = data[index].next;
   6.206 +      if (_data[index].prev >= 0) {
   6.207 +        _data[_data[index].prev].next = _data[index].next;
   6.208        } else {
   6.209 -        boxes[data[index].box].first = data[index].next;
   6.210 +        _boxes[_data[index].box].first = _data[index].next;
   6.211        }
   6.212 -      if (data[index].next >= 0) {
   6.213 -        data[data[index].next].prev = data[index].prev;
   6.214 +      if (_data[index].next >= 0) {
   6.215 +        _data[_data[index].next].prev = _data[index].prev;
   6.216        }
   6.217      }
   6.218  
   6.219 -    /// \brief Insert item into the box list.
   6.220 +    // Insert item into the box list
   6.221      void insert(int box, int index) {
   6.222 -      if (boxes[box].first == -1) {
   6.223 -        boxes[box].first = index;
   6.224 -        data[index].next = data[index].prev = -1;
   6.225 +      if (_boxes[box].first == -1) {
   6.226 +        _boxes[box].first = index;
   6.227 +        _data[index].next = _data[index].prev = -1;
   6.228        } else {
   6.229 -        data[index].next = boxes[box].first;
   6.230 -        data[boxes[box].first].prev = index;
   6.231 -        data[index].prev = -1;
   6.232 -        boxes[box].first = index;
   6.233 +        _data[index].next = _boxes[box].first;
   6.234 +        _data[_boxes[box].first].prev = index;
   6.235 +        _data[index].prev = -1;
   6.236 +        _boxes[box].first = index;
   6.237        }
   6.238 -      data[index].box = box;
   6.239 +      _data[index].box = box;
   6.240      }
   6.241  
   6.242 -    /// \brief Add a new box to the box list.
   6.243 +    // Add a new box to the box list
   6.244      void extend() {
   6.245 -      int min = boxes.back().min + boxes.back().size;
   6.246 -      int bs = 2 * boxes.back().size;
   6.247 -      boxes.push_back(RadixBox(min, bs));
   6.248 +      int min = _boxes.back().min + _boxes.back().size;
   6.249 +      int bs = 2 * _boxes.back().size;
   6.250 +      _boxes.push_back(RadixBox(min, bs));
   6.251      }
   6.252  
   6.253 -    /// \brief Move an item up into the proper box.
   6.254 -    void bubble_up(int index) {
   6.255 -      if (!lower(data[index].box, data[index].prio)) return;
   6.256 +    // Move an item up into the proper box.
   6.257 +    void bubbleUp(int index) {
   6.258 +      if (!lower(_data[index].box, _data[index].prio)) return;
   6.259        remove(index);
   6.260 -      int box = findUp(data[index].box, data[index].prio);
   6.261 +      int box = findUp(_data[index].box, _data[index].prio);
   6.262        insert(box, index);
   6.263      }
   6.264  
   6.265 -    /// \brief Find up the proper box for the item with the given prio.
   6.266 +    // Find up the proper box for the item with the given priority
   6.267      int findUp(int start, int pr) {
   6.268        while (lower(start, pr)) {
   6.269 -        if (++start == int(boxes.size())) {
   6.270 +        if (++start == int(_boxes.size())) {
   6.271            extend();
   6.272          }
   6.273        }
   6.274        return start;
   6.275      }
   6.276  
   6.277 -    /// \brief Move an item down into the proper box.
   6.278 -    void bubble_down(int index) {
   6.279 -      if (!upper(data[index].box, data[index].prio)) return;
   6.280 +    // Move an item down into the proper box
   6.281 +    void bubbleDown(int index) {
   6.282 +      if (!upper(_data[index].box, _data[index].prio)) return;
   6.283        remove(index);
   6.284 -      int box = findDown(data[index].box, data[index].prio);
   6.285 +      int box = findDown(_data[index].box, _data[index].prio);
   6.286        insert(box, index);
   6.287      }
   6.288  
   6.289 -    /// \brief Find up the proper box for the item with the given prio.
   6.290 +    // Find down the proper box for the item with the given priority
   6.291      int findDown(int start, int pr) {
   6.292        while (upper(start, pr)) {
   6.293 -        if (--start < 0) throw UnderFlowPriorityError();
   6.294 +        if (--start < 0) throw PriorityUnderflowError();
   6.295        }
   6.296        return start;
   6.297      }
   6.298  
   6.299 -    /// \brief Find the first not empty box.
   6.300 +    // Find the first non-empty box
   6.301      int findFirst() {
   6.302        int first = 0;
   6.303 -      while (boxes[first].first == -1) ++first;
   6.304 +      while (_boxes[first].first == -1) ++first;
   6.305        return first;
   6.306      }
   6.307  
   6.308 -    /// \brief Gives back the minimal prio of the box.
   6.309 +    // Gives back the minimum priority of the given box
   6.310      int minValue(int box) {
   6.311 -      int min = data[boxes[box].first].prio;
   6.312 -      for (int k = boxes[box].first; k != -1; k = data[k].next) {
   6.313 -        if (data[k].prio < min) min = data[k].prio;
   6.314 +      int min = _data[_boxes[box].first].prio;
   6.315 +      for (int k = _boxes[box].first; k != -1; k = _data[k].next) {
   6.316 +        if (_data[k].prio < min) min = _data[k].prio;
   6.317        }
   6.318        return min;
   6.319      }
   6.320  
   6.321 -    /// \brief Rearrange the items of the heap and makes the
   6.322 -    /// first box not empty.
   6.323 +    // Rearrange the items of the heap and make the first box non-empty
   6.324      void moveDown() {
   6.325        int box = findFirst();
   6.326        if (box == 0) return;
   6.327        int min = minValue(box);
   6.328        for (int i = 0; i <= box; ++i) {
   6.329 -        boxes[i].min = min;
   6.330 -        min += boxes[i].size;
   6.331 +        _boxes[i].min = min;
   6.332 +        min += _boxes[i].size;
   6.333        }
   6.334 -      int curr = boxes[box].first, next;
   6.335 +      int curr = _boxes[box].first, next;
   6.336        while (curr != -1) {
   6.337 -        next = data[curr].next;
   6.338 -        bubble_down(curr);
   6.339 +        next = _data[curr].next;
   6.340 +        bubbleDown(curr);
   6.341          curr = next;
   6.342        }
   6.343      }
   6.344  
   6.345 -    void relocate_last(int index) {
   6.346 -      if (index != int(data.size()) - 1) {
   6.347 -        data[index] = data.back();
   6.348 -        if (data[index].prev != -1) {
   6.349 -          data[data[index].prev].next = index;
   6.350 +    void relocateLast(int index) {
   6.351 +      if (index != int(_data.size()) - 1) {
   6.352 +        _data[index] = _data.back();
   6.353 +        if (_data[index].prev != -1) {
   6.354 +          _data[_data[index].prev].next = index;
   6.355          } else {
   6.356 -          boxes[data[index].box].first = index;
   6.357 +          _boxes[_data[index].box].first = index;
   6.358          }
   6.359 -        if (data[index].next != -1) {
   6.360 -          data[data[index].next].prev = index;
   6.361 +        if (_data[index].next != -1) {
   6.362 +          _data[_data[index].next].prev = index;
   6.363          }
   6.364 -        _iim[data[index].item] = index;
   6.365 +        _iim[_data[index].item] = index;
   6.366        }
   6.367 -      data.pop_back();
   6.368 +      _data.pop_back();
   6.369      }
   6.370  
   6.371    public:
   6.372  
   6.373      /// \brief Insert an item into the heap with the given priority.
   6.374      ///
   6.375 -    /// Adds \c i to the heap with priority \c p.
   6.376 +    /// This function inserts the given item into the heap with the
   6.377 +    /// given priority.
   6.378      /// \param i The item to insert.
   6.379      /// \param p The priority of the item.
   6.380 +    /// \pre \e i must not be stored in the heap.
   6.381 +    /// \warning This method may throw an \c UnderFlowPriorityException.
   6.382      void push(const Item &i, const Prio &p) {
   6.383 -      int n = data.size();
   6.384 +      int n = _data.size();
   6.385        _iim.set(i, n);
   6.386 -      data.push_back(RadixItem(i, p));
   6.387 -      while (lower(boxes.size() - 1, p)) {
   6.388 +      _data.push_back(RadixItem(i, p));
   6.389 +      while (lower(_boxes.size() - 1, p)) {
   6.390          extend();
   6.391        }
   6.392 -      int box = findDown(boxes.size() - 1, p);
   6.393 +      int box = findDown(_boxes.size() - 1, p);
   6.394        insert(box, n);
   6.395      }
   6.396  
   6.397 -    /// \brief Returns the item with minimum priority.
   6.398 +    /// \brief Return the item having minimum priority.
   6.399      ///
   6.400 -    /// This method returns the item with minimum priority.
   6.401 -    /// \pre The heap must be nonempty.
   6.402 +    /// This function returns the item having minimum priority.
   6.403 +    /// \pre The heap must be non-empty.
   6.404      Item top() const {
   6.405        const_cast<RadixHeap<ItemIntMap>&>(*this).moveDown();
   6.406 -      return data[boxes[0].first].item;
   6.407 +      return _data[_boxes[0].first].item;
   6.408      }
   6.409  
   6.410 -    /// \brief Returns the minimum priority.
   6.411 +    /// \brief The minimum priority.
   6.412      ///
   6.413 -    /// It returns the minimum priority.
   6.414 -    /// \pre The heap must be nonempty.
   6.415 +    /// This function returns the minimum priority.
   6.416 +    /// \pre The heap must be non-empty.
   6.417      Prio prio() const {
   6.418        const_cast<RadixHeap<ItemIntMap>&>(*this).moveDown();
   6.419 -      return data[boxes[0].first].prio;
   6.420 +      return _data[_boxes[0].first].prio;
   6.421       }
   6.422  
   6.423 -    /// \brief Deletes the item with minimum priority.
   6.424 +    /// \brief Remove the item having minimum priority.
   6.425      ///
   6.426 -    /// This method deletes the item with minimum priority.
   6.427 +    /// This function removes the item having minimum priority.
   6.428      /// \pre The heap must be non-empty.
   6.429      void pop() {
   6.430        moveDown();
   6.431 -      int index = boxes[0].first;
   6.432 -      _iim[data[index].item] = POST_HEAP;
   6.433 +      int index = _boxes[0].first;
   6.434 +      _iim[_data[index].item] = POST_HEAP;
   6.435        remove(index);
   6.436 -      relocate_last(index);
   6.437 +      relocateLast(index);
   6.438      }
   6.439  
   6.440 -    /// \brief Deletes \c i from the heap.
   6.441 +    /// \brief Remove the given item from the heap.
   6.442      ///
   6.443 -    /// This method deletes item \c i from the heap, if \c i was
   6.444 -    /// already stored in the heap.
   6.445 -    /// \param i The item to erase.
   6.446 +    /// This function removes the given item from the heap if it is
   6.447 +    /// already stored.
   6.448 +    /// \param i The item to delete.
   6.449 +    /// \pre \e i must be in the heap.
   6.450      void erase(const Item &i) {
   6.451        int index = _iim[i];
   6.452        _iim[i] = POST_HEAP;
   6.453        remove(index);
   6.454 -      relocate_last(index);
   6.455 +      relocateLast(index);
   6.456     }
   6.457  
   6.458 -    /// \brief Returns the priority of \c i.
   6.459 +    /// \brief The priority of the given item.
   6.460      ///
   6.461 -    /// This function returns the priority of item \c i.
   6.462 -    /// \pre \c i must be in the heap.
   6.463 +    /// This function returns the priority of the given item.
   6.464      /// \param i The item.
   6.465 +    /// \pre \e i must be in the heap.
   6.466      Prio operator[](const Item &i) const {
   6.467        int idx = _iim[i];
   6.468 -      return data[idx].prio;
   6.469 +      return _data[idx].prio;
   6.470      }
   6.471  
   6.472 -    /// \brief \c i gets to the heap with priority \c p independently
   6.473 -    /// if \c i was already there.
   6.474 +    /// \brief Set the priority of an item or insert it, if it is
   6.475 +    /// not stored in the heap.
   6.476      ///
   6.477 -    /// This method calls \ref push(\c i, \c p) if \c i is not stored
   6.478 -    /// in the heap and sets the priority of \c i to \c p otherwise.
   6.479 -    /// It may throw an \e UnderFlowPriorityException.
   6.480 +    /// This method sets the priority of the given item if it is
   6.481 +    /// already stored in the heap. Otherwise it inserts the given
   6.482 +    /// item into the heap with the given priority.
   6.483      /// \param i The item.
   6.484      /// \param p The priority.
   6.485 +    /// \pre \e i must be in the heap.
   6.486 +    /// \warning This method may throw an \c UnderFlowPriorityException.
   6.487      void set(const Item &i, const Prio &p) {
   6.488        int idx = _iim[i];
   6.489        if( idx < 0 ) {
   6.490          push(i, p);
   6.491        }
   6.492 -      else if( p >= data[idx].prio ) {
   6.493 -        data[idx].prio = p;
   6.494 -        bubble_up(idx);
   6.495 +      else if( p >= _data[idx].prio ) {
   6.496 +        _data[idx].prio = p;
   6.497 +        bubbleUp(idx);
   6.498        } else {
   6.499 -        data[idx].prio = p;
   6.500 -        bubble_down(idx);
   6.501 +        _data[idx].prio = p;
   6.502 +        bubbleDown(idx);
   6.503        }
   6.504      }
   6.505  
   6.506 -
   6.507 -    /// \brief Decreases the priority of \c i to \c p.
   6.508 +    /// \brief Decrease the priority of an item to the given value.
   6.509      ///
   6.510 -    /// This method decreases the priority of item \c i to \c p.
   6.511 -    /// \pre \c i must be stored in the heap with priority at least \c p, and
   6.512 -    /// \c should be greater or equal to the last removed item's priority.
   6.513 +    /// This function decreases the priority of an item to the given value.
   6.514      /// \param i The item.
   6.515      /// \param p The priority.
   6.516 +    /// \pre \e i must be stored in the heap with priority at least \e p.
   6.517 +    /// \warning This method may throw an \c UnderFlowPriorityException.
   6.518      void decrease(const Item &i, const Prio &p) {
   6.519        int idx = _iim[i];
   6.520 -      data[idx].prio = p;
   6.521 -      bubble_down(idx);
   6.522 +      _data[idx].prio = p;
   6.523 +      bubbleDown(idx);
   6.524      }
   6.525  
   6.526 -    /// \brief Increases the priority of \c i to \c p.
   6.527 +    /// \brief Increase the priority of an item to the given value.
   6.528      ///
   6.529 -    /// This method sets the priority of item \c i to \c p.
   6.530 -    /// \pre \c i must be stored in the heap with priority at most \c p
   6.531 +    /// This function increases the priority of an item to the given value.
   6.532      /// \param i The item.
   6.533      /// \param p The priority.
   6.534 +    /// \pre \e i must be stored in the heap with priority at most \e p.
   6.535      void increase(const Item &i, const Prio &p) {
   6.536        int idx = _iim[i];
   6.537 -      data[idx].prio = p;
   6.538 -      bubble_up(idx);
   6.539 +      _data[idx].prio = p;
   6.540 +      bubbleUp(idx);
   6.541      }
   6.542  
   6.543 -    /// \brief Returns if \c item is in, has already been in, or has
   6.544 -    /// never been in the heap.
   6.545 +    /// \brief Return the state of an item.
   6.546      ///
   6.547 -    /// This method returns PRE_HEAP if \c item has never been in the
   6.548 -    /// heap, IN_HEAP if it is in the heap at the moment, and POST_HEAP
   6.549 -    /// otherwise. In the latter case it is possible that \c item will
   6.550 -    /// get back to the heap again.
   6.551 +    /// This method returns \c PRE_HEAP if the given item has never
   6.552 +    /// been in the heap, \c IN_HEAP if it is in the heap at the moment,
   6.553 +    /// and \c POST_HEAP otherwise.
   6.554 +    /// In the latter case it is possible that the item will get back
   6.555 +    /// to the heap again.
   6.556      /// \param i The item.
   6.557      State state(const Item &i) const {
   6.558        int s = _iim[i];
   6.559 @@ -405,11 +410,11 @@
   6.560        return State(s);
   6.561      }
   6.562  
   6.563 -    /// \brief Sets the state of the \c item in the heap.
   6.564 +    /// \brief Set the state of an item in the heap.
   6.565      ///
   6.566 -    /// Sets the state of the \c item in the heap. It can be used to
   6.567 -    /// manually clear the heap when it is important to achive the
   6.568 -    /// better time complexity.
   6.569 +    /// This function sets the state of the given item in the heap.
   6.570 +    /// It can be used to manually clear the heap when it is important
   6.571 +    /// to achive better time complexity.
   6.572      /// \param i The item.
   6.573      /// \param st The state. It should not be \c IN_HEAP.
   6.574      void state(const Item& i, State st) {