[Lemon-commits] Peter Kovacs: Improve and unify the doc + names ...
Lemon HG
hg at lemon.cs.elte.hu
Mon Aug 31 12:21:04 CEST 2009
details: http://lemon.cs.elte.hu/hg/lemon/rev/bb3392fe91f2
changeset: 756:bb3392fe91f2
user: Peter Kovacs <kpeter [at] inf.elte.hu>
date: Thu Jul 09 04:07:08 2009 +0200
description:
Improve and unify the doc + names in the new heaps (#301)
diffstat:
lemon/binom_heap.h | 462 ++++++++++++++++++++++++++-------------------------
lemon/fourary_heap.h | 349 +++++++++++++++++++-------------------
lemon/kary_heap.h | 369 ++++++++++++++++++++--------------------
lemon/pairing_heap.h | 479 +++++++++++++++++++++++++++--------------------------
4 files changed, 839 insertions(+), 820 deletions(-)
diffs (truncated from 2430 to 300 lines):
diff --git a/lemon/binom_heap.h b/lemon/binom_heap.h
--- a/lemon/binom_heap.h
+++ b/lemon/binom_heap.h
@@ -1,8 +1,8 @@
-/* -*- C++ -*-
+/* -*- mode: C++; indent-tabs-mode: nil; -*-
*
- * This file is a part of LEMON, a generic C++ optimization library
+ * This file is a part of LEMON, a generic C++ optimization library.
*
- * Copyright (C) 2003-2008
+ * Copyright (C) 2003-2009
* Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
* (Egervary Research Group on Combinatorial Optimization, EGRES).
*
@@ -20,193 +20,199 @@
#define LEMON_BINOM_HEAP_H
///\file
-///\ingroup auxdat
+///\ingroup heaps
///\brief Binomial Heap implementation.
#include <vector>
+#include <utility>
#include <functional>
#include <lemon/math.h>
#include <lemon/counter.h>
namespace lemon {
- /// \ingroup auxdat
+ /// \ingroup heaps
///
- ///\brief Binomial Heap.
+ ///\brief Binomial heap data structure.
///
- ///This class implements the \e Binomial \e heap data structure. A \e heap
- ///is a data structure for storing items with specified values called \e
- ///priorities in such a way that finding the item with minimum priority is
- ///efficient. \c Compare specifies the ordering of the priorities. In a heap
- ///one can change the priority of an item, add or erase an item, etc.
+ /// This class implements the \e binomial \e heap data structure.
+ /// It fully conforms to the \ref concepts::Heap "heap concept".
///
- ///The methods \ref increase and \ref erase are not efficient in a Binomial
- ///heap. In case of many calls to these operations, it is better to use a
- ///\ref BinHeap "binary heap".
+ /// The methods \ref increase() and \ref erase() are not efficient
+ /// in a binomial heap. In case of many calls of these operations,
+ /// it is better to use other heap structure, e.g. \ref BinHeap
+ /// "binary heap".
///
- ///\param _Prio Type of the priority of the items.
- ///\param _ItemIntMap A read and writable Item int map, used internally
- ///to handle the cross references.
- ///\param _Compare A class for the ordering of the priorities. The
- ///default is \c std::less<_Prio>.
- ///
- ///\sa BinHeap
- ///\sa Dijkstra
- ///\author Dorian Batha
-
+ /// \tparam PR Type of the priorities of the items.
+ /// \tparam IM A read-writable item map with \c int values, used
+ /// internally to handle the cross references.
+ /// \tparam CMP A functor class for comparing the priorities.
+ /// The default is \c std::less<PR>.
#ifdef DOXYGEN
- template <typename _Prio,
- typename _ItemIntMap,
- typename _Compare>
+ template <typename PR, typename IM, typename CMP>
#else
- template <typename _Prio,
- typename _ItemIntMap,
- typename _Compare = std::less<_Prio> >
+ template <typename PR, typename IM, typename CMP = std::less<PR> >
#endif
class BinomHeap {
public:
- typedef _ItemIntMap ItemIntMap;
- typedef _Prio Prio;
+ /// Type of the item-int map.
+ typedef IM ItemIntMap;
+ /// Type of the priorities.
+ typedef PR Prio;
+ /// Type of the items stored in the heap.
typedef typename ItemIntMap::Key Item;
- typedef std::pair<Item,Prio> Pair;
- typedef _Compare Compare;
+ /// Functor type for comparing the priorities.
+ typedef CMP Compare;
+
+ /// \brief Type to represent the states of the items.
+ ///
+ /// Each item has a state associated to it. It can be "in heap",
+ /// "pre-heap" or "post-heap". The latter two are indifferent from the
+ /// heap's point of view, but may be useful to the user.
+ ///
+ /// The item-int map must be initialized in such way that it assigns
+ /// \c PRE_HEAP (<tt>-1</tt>) to any element to be put in the heap.
+ enum State {
+ IN_HEAP = 0, ///< = 0.
+ PRE_HEAP = -1, ///< = -1.
+ POST_HEAP = -2 ///< = -2.
+ };
private:
class store;
- std::vector<store> container;
- int minimum, head;
- ItemIntMap &iimap;
- Compare comp;
- int num_items;
+ std::vector<store> _data;
+ int _min, _head;
+ ItemIntMap &_iim;
+ Compare _comp;
+ int _num_items;
public:
- ///Status of the nodes
- enum State {
- ///The node is in the heap
- IN_HEAP = 0,
- ///The node has never been in the heap
- PRE_HEAP = -1,
- ///The node was in the heap but it got out of it
- POST_HEAP = -2
- };
+ /// \brief Constructor.
+ ///
+ /// Constructor.
+ /// \param map A map that assigns \c int values to the items.
+ /// It is used internally to handle the cross references.
+ /// The assigned value must be \c PRE_HEAP (<tt>-1</tt>) for each item.
+ explicit BinomHeap(ItemIntMap &map)
+ : _min(0), _head(-1), _iim(map), _num_items(0) {}
- /// \brief The constructor
+ /// \brief Constructor.
///
- /// \c _iimap should be given to the constructor, since it is
- /// used internally to handle the cross references.
- explicit BinomHeap(ItemIntMap &_iimap)
- : minimum(0), head(-1), iimap(_iimap), num_items() {}
-
- /// \brief The constructor
- ///
- /// \c _iimap should be given to the constructor, since it is used
- /// internally to handle the cross references. \c _comp is an
- /// object for ordering of the priorities.
- BinomHeap(ItemIntMap &_iimap, const Compare &_comp)
- : minimum(0), head(-1), iimap(_iimap), comp(_comp), num_items() {}
+ /// Constructor.
+ /// \param map A map that assigns \c int values to the items.
+ /// It is used internally to handle the cross references.
+ /// The assigned value must be \c PRE_HEAP (<tt>-1</tt>) for each item.
+ /// \param comp The function object used for comparing the priorities.
+ BinomHeap(ItemIntMap &map, const Compare &comp)
+ : _min(0), _head(-1), _iim(map), _comp(comp), _num_items(0) {}
/// \brief The number of items stored in the heap.
///
- /// Returns the number of items stored in the heap.
- int size() const { return num_items; }
+ /// This function returns the number of items stored in the heap.
+ int size() const { return _num_items; }
- /// \brief Checks if the heap stores no items.
+ /// \brief Check if the heap is empty.
///
- /// Returns \c true if and only if the heap stores no items.
- bool empty() const { return num_items==0; }
+ /// This function returns \c true if the heap is empty.
+ bool empty() const { return _num_items==0; }
- /// \brief Make empty this heap.
+ /// \brief Make the heap empty.
///
- /// Make empty this heap. It does not change the cross reference
- /// map. If you want to reuse a heap what is not surely empty you
- /// should first clear the heap and after that you should set the
- /// cross reference map for each item to \c PRE_HEAP.
+ /// This functon makes the heap empty.
+ /// It does not change the cross reference map. If you want to reuse
+ /// a heap that is not surely empty, you should first clear it and
+ /// then you should set the cross reference map to \c PRE_HEAP
+ /// for each item.
void clear() {
- container.clear(); minimum=0; num_items=0; head=-1;
+ _data.clear(); _min=0; _num_items=0; _head=-1;
}
- /// \brief \c item gets to the heap with priority \c value independently
- /// if \c item was already there.
+ /// \brief Set the priority of an item or insert it, if it is
+ /// not stored in the heap.
///
- /// This method calls \ref push(\c item, \c value) if \c item is not
- /// stored in the heap and it calls \ref decrease(\c item, \c value) or
- /// \ref increase(\c item, \c value) otherwise.
+ /// This method sets the priority of the given item if it is
+ /// already stored in the heap. Otherwise it inserts the given
+ /// item into the heap with the given priority.
+ /// \param item The item.
+ /// \param value The priority.
void set (const Item& item, const Prio& value) {
- int i=iimap[item];
- if ( i >= 0 && container[i].in ) {
- if ( comp(value, container[i].prio) ) decrease(item, value);
- if ( comp(container[i].prio, value) ) increase(item, value);
+ int i=_iim[item];
+ if ( i >= 0 && _data[i].in ) {
+ if ( _comp(value, _data[i].prio) ) decrease(item, value);
+ if ( _comp(_data[i].prio, value) ) increase(item, value);
} else push(item, value);
}
- /// \brief Adds \c item to the heap with priority \c value.
+ /// \brief Insert an item into the heap with the given priority.
///
- /// Adds \c item to the heap with priority \c value.
- /// \pre \c item must not be stored in the heap.
+ /// This function inserts the given item into the heap with the
+ /// given priority.
+ /// \param item The item to insert.
+ /// \param value The priority of the item.
+ /// \pre \e item must not be stored in the heap.
void push (const Item& item, const Prio& value) {
- int i=iimap[item];
+ int i=_iim[item];
if ( i<0 ) {
- int s=container.size();
- iimap.set( item,s );
+ int s=_data.size();
+ _iim.set( item,s );
store st;
st.name=item;
- container.push_back(st);
+ _data.push_back(st);
i=s;
}
else {
- container[i].parent=container[i].right_neighbor=container[i].child=-1;
- container[i].degree=0;
- container[i].in=true;
+ _data[i].parent=_data[i].right_neighbor=_data[i].child=-1;
+ _data[i].degree=0;
+ _data[i].in=true;
}
- container[i].prio=value;
+ _data[i].prio=value;
- if( 0==num_items ) { head=i; minimum=i; }
+ if( 0==_num_items ) { _head=i; _min=i; }
else { merge(i); }
- minimum = find_min();
+ _min = findMin();
- ++num_items;
+ ++_num_items;
}
- /// \brief Returns the item with minimum priority relative to \c Compare.
+ /// \brief Return the item having minimum priority.
///
- /// This method returns the item with minimum priority relative to \c
- /// Compare.
- /// \pre The heap must be nonempty.
- Item top() const { return container[minimum].name; }
+ /// This function returns the item having minimum priority.
+ /// \pre The heap must be non-empty.
+ Item top() const { return _data[_min].name; }
- /// \brief Returns the minimum priority relative to \c Compare.
+ /// \brief The minimum priority.
///
- /// It returns the minimum priority relative to \c Compare.
- /// \pre The heap must be nonempty.
- const Prio& prio() const { return container[minimum].prio; }
+ /// This function returns the minimum priority.
+ /// \pre The heap must be non-empty.
+ Prio prio() const { return _data[_min].prio; }
- /// \brief Returns the priority of \c item.
+ /// \brief The priority of the given item.
///
- /// It returns the priority of \c item.
- /// \pre \c item must be in the heap.
+ /// This function returns the priority of the given item.
+ /// \param item The item.
+ /// \pre \e item must be in the heap.
const Prio& operator[](const Item& item) const {
- return container[iimap[item]].prio;
+ return _data[_iim[item]].prio;
}
More information about the Lemon-commits
mailing list