mdw@git.distorted.org.uk Git - sgt/library/blob - bheap.h

   1 /*
   2  * Header file for bheap.c.
   3  */
   4
   5 #ifndef BHEAP_H
   6 #define BHEAP_H
   7
   8 typedef struct bheap bheap;
   9
  10 typedef int (*bheap_cmpfn_t)(void *ctx, const void *x, const void *y);
  11
  12 /*
  13  * Create a new binary heap, of maximum size `maxelts'. `eltsize'
  14  * is the size of each element (use `sizeof'). `compare' is the
  15  * function that determines the ordering between elements;
  16  * `compare_ctx' is passed as its first argument.
  17  *
  18  * If `direction' is +1, the heap sorts the largest things to the
  19  * top, so it can return the largest element easily. If it's -1,
  20  * the heap sorts the smallest things to the top.
  21  */
  22 bheap *bheap_new(int maxelts, int eltsize, int direction,
  23                  bheap_cmpfn_t compare, void *compare_ctx);
  24
  25 /*
  26  * Add an element to the heap. Returns `elt', or NULL if the heap
  27  * is full.
  28  */
  29 void *bheap_add(bheap *bh, void *elt);
  30
  31 /*
  32  * Non-destructively read the topmost element in the heap and store
  33  * it at `elt'. Returns `elt', or NULL if the heap is empty.
  34  */
  35 void *bheap_topmost(bheap *bh, void *elt);
  36
  37 /*
  38  * Remove, and optionally also read, the topmost element in the
  39  * heap. Stores it at `elt' if `elt' is not itself NULL.
  40  *
  41  * Returns `elt', or NULL if the heap is empty. Note that if you
  42  * pass elt==NULL the two cases can therefore not be distinguished!
  43  */
  44 void *bheap_remove(bheap *bh, void *elt);
  45
  46 /*
  47  * Count the number of elements currently in the heap.
  48  */
  49 int bheap_count(bheap *bh);
  50
  51 /*
  52  * Destroy a heap. If the elements in the heap need freeing, you'd
  53  * better make sure there aren't any left before calling this
  54  * function, because the heap code won't know about it and won't do
  55  * anything.
  56  */
  57 void bheap_free(bheap *bh);
  58
  59 #endif /* BHEAP_H */