chiark / gitweb /
DisOrder 3.0
[disorder] / lib / heap.h
CommitLineData
033fd4e3
RK
1/*
2 * This file is part of DisOrder.
5aff007d 3 * Copyright (C) 2007, 2008 Richard Kettlewell
033fd4e3
RK
4 *
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
9 *
10 * This program is distributed in the hope that it will be useful, but
11 * WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * General Public License for more details.
14 *
15 * You should have received a copy of the GNU General Public License
16 * along with this program; if not, write to the Free Software
17 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
18 * USA
19 */
20/** @file lib/heap.h @brief Binary heap template */
21
22#ifndef HEAP_H
23#define HEAP_H
24
25/** @brief Binary heap template.
26 * @param NAME name of type to define
27 * @param ETYPE element type
28 * @param LT comparison function
29 *
30 * Defines a heap type called @c struct @p NAME and a number of functions to
31 * operate on it.
32 *
33 * The element type of the heap will be @p ETYPE.
34 *
35 * @p LT will be called with two arguments of type @p ETYPE, and
36 * implements a less-than comparison.
37 *
38 * The functions defined are:
39 * - NAME_init(h) which initializes an empty heap at @p h
40 * - NAME_count(h) which returns the number of elements in the heap
41 * - NAME_insert(h, e) which inserts @p e into @p h
42 * - NAME_first(g) which returns the least element of @p h
43 * - NAME_remove(g) which removes and returns the least element of @p h
44 *
45 * The heap is implemented as a vector. Element 0 is the root. For any
46 * element \f$i\f$, its children are elements \f$2i+1\f$ and \f$2i+2\f$ and
47 * consequently its parent (if it is not the root) is
48 * \f$\lfloor(i-1)/2\rfloor\f$.
49 *
50 * The insert and remove operations maintain two invariants: the @b
51 * shape property (all levels of the tree are fully filled except the
52 * deepest, and that is filled from the left), and the @b heap
53 * property, that every element compares less than or equal to its
54 * children.
55 *
56 * The shape property implies that the array representation has no gaps, which
57 * is convenient. It is preserved by only adding or removing the final element
58 * of the array and otherwise only modifying the array by swapping pairs of
59 * elements.
60 *
61 * @b Insertion works by inserting the new element \f$N\f$ at the end and
62 * bubbling it up the tree until it is in the right order for its branch.
63 * - If, for its parent \f$P\f$, \f$P \le N\f$ then it is already in the right
64 * place and the insertion is complete.
65 * - Otherwise \f$P > N\f$ and so \f$P\f$ and \f$N\f$ are exchanged. If
66 * \f$P\f$ has a second child, \f$C\f$, then \f$N < P < C\f$ so the heap
67 * property is now satisfied from \f$P\f$ down.
68 *
69 * @b Removal works by first swapping the root with the final element (and then
70 * removing it) and then bubbling the new root \f$N\f$ down the tree until it
71 * finds its proper place. At each stage it is compared with its children
72 * \f$A\f$ and \f$B\f$.
73 * - If \f$N \le A\f$ and \f$N \le B\f$ then it is in the
74 * right place already.
75 * - Otherwise \f$N > A\f$ or \f$N > B\f$ (or both). WLOG \f$A \le B\f$.
76 * \f$N\f$ and \f$A\f$ are exchanged, so now \f$A\f$ has children \f$N\f$ and
77 * \f$B\f$. \f$A < N\f$ and \f$A \le B\f$.
78 */
b8956e9e
RK
79#define HEAP_TYPE(NAME, ETYPE, LT) \
80 typedef ETYPE NAME##_element; \
81 VECTOR_TYPE(NAME, NAME##_element, xrealloc); \
82 \
83 static inline int NAME##_count(struct NAME *heap) { \
84 return heap->nvec; \
85 } \
86 \
87 static inline NAME##_element NAME##_first(struct NAME *heap) { \
4c672170 88 assert(heap->nvec > 0 && "_first"); \
b8956e9e
RK
89 return heap->vec[0]; \
90 } \
91 \
8e3fe3d8 92 void NAME##_insert(struct NAME *heap, NAME##_element elt); \
93 NAME##_element NAME##_remove(struct NAME *heap); \
b8956e9e 94 \
033fd4e3 95 struct heap_swallow_semicolon
8e3fe3d8 96
97/** @brief External-linkage definitions for @ref HEAP_TYPE */
98#define HEAP_DEFINE(NAME, ETYPE, LT) \
99 void NAME##_insert(struct NAME *heap, NAME##_element elt) { \
100 int n = heap->nvec; \
101 NAME##_append(heap, elt); \
102 while(n > 0) { \
103 const int p = (n-1)/2; \
104 if(!LT(heap->vec[n],heap->vec[p])) \
105 break; \
106 else { \
107 const NAME##_element t = heap->vec[n]; \
108 heap->vec[n] = heap->vec[p]; \
109 heap->vec[p] = t; \
110 n = p; \
111 } \
112 } \
113 } \
114 \
115 NAME##_element NAME##_remove(struct NAME *heap) { \
116 int n = 0; \
117 NAME##_element r; \
118 \
4c672170 119 assert(heap->nvec > 0 && "_remove"); \
8e3fe3d8 120 r = heap->vec[0]; \
121 heap->vec[0] = heap->vec[--heap->nvec]; \
122 while(2 * n + 1 < heap->nvec) { \
123 int a = 2 * n + 1; \
124 int b = 2 * n + 2; \
125 \
126 if(b < heap->nvec && LT(heap->vec[b],heap->vec[a])) { \
127 ++a; \
128 --b; \
129 } \
130 if(LT(heap->vec[a], heap->vec[n])) { \
131 const NAME##_element t = heap->vec[n]; \
132 heap->vec[n] = heap->vec[a]; \
133 heap->vec[a] = t; \
134 n = a; \
135 } else \
136 break; \
137 } \
138 return r; \
139 } \
140 \
141 struct heap_swallow_semicolon \
033fd4e3
RK
142
143
144#endif /* PQUEUE_H */
145
146/*
147Local Variables:
148c-basic-offset:2
149comment-column:40
150fill-column:79
151indent-tabs-mode:nil
152End:
153*/