| 1 | /* |
| 2 | * Header file for bheap.c. |
| 3 | * |
| 4 | * This file is copyright 2005 Simon Tatham. |
| 5 | * |
| 6 | * Permission is hereby granted, free of charge, to any person |
| 7 | * obtaining a copy of this software and associated documentation |
| 8 | * files (the "Software"), to deal in the Software without |
| 9 | * restriction, including without limitation the rights to use, |
| 10 | * copy, modify, merge, publish, distribute, sublicense, and/or |
| 11 | * sell copies of the Software, and to permit persons to whom the |
| 12 | * Software is furnished to do so, subject to the following |
| 13 | * conditions: |
| 14 | * |
| 15 | * The above copyright notice and this permission notice shall be |
| 16 | * included in all copies or substantial portions of the Software. |
| 17 | * |
| 18 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, |
| 19 | * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES |
| 20 | * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND |
| 21 | * NONINFRINGEMENT. IN NO EVENT SHALL SIMON TATHAM BE LIABLE FOR |
| 22 | * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF |
| 23 | * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN |
| 24 | * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE |
| 25 | * SOFTWARE. |
| 26 | */ |
| 27 | |
| 28 | #ifndef BHEAP_H |
| 29 | #define BHEAP_H |
| 30 | |
| 31 | typedef struct bheap bheap; |
| 32 | |
| 33 | typedef int (*bheap_cmpfn_t)(void *ctx, const void *x, const void *y); |
| 34 | |
| 35 | /* |
| 36 | * Create a new binary heap, of maximum size `maxelts'. `eltsize' |
| 37 | * is the size of each element (use `sizeof'). `compare' is the |
| 38 | * function that determines the ordering between elements; |
| 39 | * `compare_ctx' is passed as its first argument. |
| 40 | * |
| 41 | * If `direction' is +1, the heap sorts the largest things to the |
| 42 | * top, so it can return the largest element easily. If it's -1, |
| 43 | * the heap sorts the smallest things to the top. |
| 44 | */ |
| 45 | bheap *bheap_new(int maxelts, int eltsize, int direction, |
| 46 | bheap_cmpfn_t compare, void *compare_ctx); |
| 47 | |
| 48 | /* |
| 49 | * Add an element to the heap. Returns `elt', or NULL if the heap |
| 50 | * is full. |
| 51 | */ |
| 52 | void *bheap_add(bheap *bh, void *elt); |
| 53 | |
| 54 | /* |
| 55 | * Non-destructively read the topmost element in the heap and store |
| 56 | * it at `elt'. Returns `elt', or NULL if the heap is empty. |
| 57 | */ |
| 58 | void *bheap_topmost(bheap *bh, void *elt); |
| 59 | |
| 60 | /* |
| 61 | * Remove, and optionally also read, the topmost element in the |
| 62 | * heap. Stores it at `elt' if `elt' is not itself NULL. |
| 63 | * |
| 64 | * Returns `elt', or NULL if the heap is empty. Note that if you |
| 65 | * pass elt==NULL the two cases can therefore not be distinguished! |
| 66 | */ |
| 67 | void *bheap_remove(bheap *bh, void *elt); |
| 68 | |
| 69 | /* |
| 70 | * Count the number of elements currently in the heap. |
| 71 | */ |
| 72 | int bheap_count(bheap *bh); |
| 73 | |
| 74 | /* |
| 75 | * Destroy a heap. If the elements in the heap need freeing, you'd |
| 76 | * better make sure there aren't any left before calling this |
| 77 | * function, because the heap code won't know about it and won't do |
| 78 | * anything. |
| 79 | */ |
| 80 | void bheap_free(bheap *bh); |
| 81 | |
| 82 | #endif /* BHEAP_H */ |