1 /* -*- mode: C++; indent-tabs-mode: nil; -*-
3 * This file is a part of LEMON, a generic C++ optimization library.
5 * Copyright (C) 2003-2008
6 * Egervary Jeno Kombinatorikus Optimalizalasi Kutatocsoport
7 * (Egervary Research Group on Combinatorial Optimization, EGRES).
9 * Permission to use, modify and distribute this software is granted
10 * provided that this copyright notice appears in all copies. For
11 * precise terms see the accompanying LICENSE file.
13 * This software is provided "AS IS" with no warranty of any kind,
14 * express or implied, and with no claim as to its suitability for any
21 ///\brief The concept of heaps.
23 #ifndef LEMON_CONCEPT_HEAP_H
24 #define LEMON_CONCEPT_HEAP_H
26 #include <lemon/core.h>
32 /// \addtogroup concept
35 /// \brief The heap concept.
37 /// Concept class describing the main interface of heaps.
38 template <typename Priority, typename ItemIntMap>
42 /// Type of the items stored in the heap.
43 typedef typename ItemIntMap::Key Item;
45 /// Type of the priorities.
46 typedef Priority Prio;
48 /// \brief Type to represent the states of the items.
50 /// Each item has a state associated to it. It can be "in heap",
51 /// "pre heap" or "post heap". The later two are indifferent
52 /// from the point of view of the heap, but may be useful for
55 /// The \c ItemIntMap must be initialized in such a way, that it
56 /// assigns \c PRE_HEAP (<tt>-1</tt>) to every item.
63 /// \brief The constructor.
66 /// \param map A map that assigns \c int values to keys of type
67 /// \c Item. It is used internally by the heap implementations to
68 /// handle the cross references. The assigned value must be
69 /// \c PRE_HEAP (<tt>-1</tt>) for every item.
70 explicit Heap(ItemIntMap &map) {}
72 /// \brief The number of items stored in the heap.
74 /// Returns the number of items stored in the heap.
75 int size() const { return 0; }
77 /// \brief Checks if the heap is empty.
79 /// Returns \c true if the heap is empty.
80 bool empty() const { return false; }
82 /// \brief Makes the heap empty.
84 /// Makes the heap empty.
87 /// \brief Inserts an item into the heap with the given priority.
89 /// Inserts the given item into the heap with the given priority.
90 /// \param i The item to insert.
91 /// \param p The priority of the item.
92 void push(const Item &i, const Prio &p) {}
94 /// \brief Returns the item having minimum priority.
96 /// Returns the item having minimum priority.
97 /// \pre The heap must be non-empty.
100 /// \brief The minimum priority.
102 /// Returns the minimum priority.
103 /// \pre The heap must be non-empty.
106 /// \brief Removes the item having minimum priority.
108 /// Removes the item having minimum priority.
109 /// \pre The heap must be non-empty.
112 /// \brief Removes an item from the heap.
114 /// Removes the given item from the heap if it is already stored.
115 /// \param i The item to delete.
116 void erase(const Item &i) {}
118 /// \brief The priority of an item.
120 /// Returns the priority of the given item.
121 /// \pre \c i must be in the heap.
122 /// \param i The item.
123 Prio operator[](const Item &i) const {}
125 /// \brief Sets the priority of an item or inserts it, if it is
126 /// not stored in the heap.
128 /// This method sets the priority of the given item if it is
129 /// already stored in the heap.
130 /// Otherwise it inserts the given item with the given priority.
132 /// It may throw an \ref UnderflowPriorityException.
133 /// \param i The item.
134 /// \param p The priority.
135 void set(const Item &i, const Prio &p) {}
137 /// \brief Decreases the priority of an item to the given value.
139 /// Decreases the priority of an item to the given value.
140 /// \pre \c i must be stored in the heap with priority at least \c p.
141 /// \param i The item.
142 /// \param p The priority.
143 void decrease(const Item &i, const Prio &p) {}
145 /// \brief Increases the priority of an item to the given value.
147 /// Increases the priority of an item to the given value.
148 /// \pre \c i must be stored in the heap with priority at most \c p.
149 /// \param i The item.
150 /// \param p The priority.
151 void increase(const Item &i, const Prio &p) {}
153 /// \brief Returns if an item is in, has already been in, or has
154 /// never been in the heap.
156 /// This method returns \c PRE_HEAP if the given item has never
157 /// been in the heap, \c IN_HEAP if it is in the heap at the moment,
158 /// and \c POST_HEAP otherwise.
159 /// In the latter case it is possible that the item will get back
160 /// to the heap again.
161 /// \param i The item.
162 State state(const Item &i) const {}
164 /// \brief Sets the state of an item in the heap.
166 /// Sets the state of the given item in the heap. It can be used
167 /// to manually clear the heap when it is important to achive the
168 /// better time complexity.
169 /// \param i The item.
170 /// \param st The state. It should not be \c IN_HEAP.
171 void state(const Item& i, State st) {}
174 template <typename _Heap>
178 typedef typename _Heap::Item OwnItem;
179 typedef typename _Heap::Prio OwnPrio;
180 typedef typename _Heap::State OwnState;
186 ignore_unused_variable_warning(item);
187 ignore_unused_variable_warning(prio);
194 ignore_unused_variable_warning(own_item);
195 ignore_unused_variable_warning(own_prio);
196 ignore_unused_variable_warning(own_state);
200 ignore_unused_variable_warning(heap1);
201 ignore_unused_variable_warning(heap2);
204 ignore_unused_variable_warning(s);
205 bool e = heap.empty();
206 ignore_unused_variable_warning(e);
211 own_prio = heap.prio();
212 own_item = heap.top();
213 own_prio = heap[own_item];
215 heap.push(item, prio);
216 heap.push(own_item, own_prio);
219 heap.set(item, prio);
220 heap.decrease(item, prio);
221 heap.increase(item, prio);
222 heap.set(own_item, own_prio);
223 heap.decrease(own_item, own_prio);
224 heap.increase(own_item, own_prio);
227 heap.erase(own_item);
230 own_state = heap.state(own_item);
231 heap.state(own_item, own_state);
233 own_state = _Heap::PRE_HEAP;
234 own_state = _Heap::IN_HEAP;
235 own_state = _Heap::POST_HEAP;
246 #endif // LEMON_CONCEPT_PATH_H