ferret 0.9.6 → 0.10.0

data/ext/priorityqueue.c

@@ -1,228 +1,151 @@
-#include <priorityqueue.h>
-  
-PriorityQueue *pq_create(int max_size, bool (*less_than)(void *p1, void *p2))
-{
-  PriorityQueue *pq = ALLOC(PriorityQueue);
-  pq->count = 0;
-  pq->size = max_size;
-  pq->heap = ALLOC_N(void *, (max_size + 1));
-  pq->lt = less_than;
-  pq->free_elem = &free;
-  return pq;
-}
-
-void pq_destroy(PriorityQueue *pq)
-{
-  free(pq->heap);
-  free(pq);
-}
+#include <string.h>
+#include "priorityqueue.h"
 
-void pq_up(PriorityQueue *pq)
-{
-	void **heap = pq->heap;
-  void *node;
-	int i = pq->count;
-	int j = i >> 1;
-
-  node = heap[i];
-
-	while ((j > 0) && pq->lt(node, heap[j])) {
-		heap[i] = heap[j];
-		i = j;
-		j = j >> 1;
-	}
-  heap[i] = node;
-}
+#define START_CAPA 127
 
-void pq_down(PriorityQueue *pq)
+PriorityQueue *pq_new(const int capa,
+                      bool (*less_than)(const void *p1, const void *p2),
+                      void (*free_elem)(void *elem))
 {
-  register int i = 1;
-  register int j = 2; //i << 1;
-  register int k = 3; //j + 1;
-  register int count = pq->count;
-  void **heap = pq->heap;
-  void *node = heap[i]; // save top node
-
-  if ((k <= count) && (pq->lt(heap[k], heap[j])))
-    j = k;
-
-  while ((j <= count) && pq->lt(heap[j], node)) {
-    heap[i] = heap[j];      // shift up child
-    i = j;
-    j = i << 1;
-    k = j + 1;
-    if ((k <= count) && pq->lt(heap[k], heap[j]))
-      j = k;
-  }
-  heap[i] = node;
-}
+    PriorityQueue *pq = ALLOC(PriorityQueue);
+    pq->size = 0;
+    pq->capa = capa;
+    pq->mem_capa = (START_CAPA > capa ? capa : START_CAPA) + 1;
+    pq->heap = ALLOC_N(void *, pq->mem_capa);
+    pq->less_than_i = less_than;
 
-void pq_push(PriorityQueue *pq, void *elem) 
-{
-  pq->count++;
-  pq->heap[pq->count] = elem;
-  pq_up(pq);
+    /* need to set this yourself if you want to change it */
+    pq->free_elem_i = free_elem ? free_elem : &dummy_free;
+    return pq;
 }
 
-void *pq_top(PriorityQueue *pq)
+PriorityQueue *pq_clone(PriorityQueue *pq)
 {
-  return pq->heap[1];
-}
+    PriorityQueue *new_pq = ALLOC(PriorityQueue);
+    memcpy(new_pq, pq, sizeof(PriorityQueue));
+    new_pq->heap = ALLOC_N(void *, new_pq->mem_capa);
+    memcpy(new_pq->heap, pq->heap, sizeof(void *) * (new_pq->size + 1));
 
-void *pq_pop(PriorityQueue *pq)
-{
-  if (pq->count > 0) {
-    void *result = pq->heap[1];        // save first value
-    pq->heap[1] = pq->heap[pq->count]; // move last to first
-    pq->heap[pq->count] = NULL;
-    pq->count--;
-    pq_down(pq);                       // adjust heap
-    return result;
-  } else {
-    return NULL;
-  }
+    return new_pq;
 }
 
 void pq_clear(PriorityQueue *pq)
 {
-  int i;
-  for (i = 1; i <= pq->count; i++) {
-    pq->free_elem(pq->heap[i]);
-    pq->heap[i] = NULL;
-  }
-  pq->count = 0;
-}
-
-int pq_insert(PriorityQueue *pq, void *elem) 
-{
-  if (pq->count < pq->size) {
-    pq_push(pq, elem);
-    return true;
-  } else if (pq->count > 0 && pq->lt(pq_top(pq), elem)) {
-    pq->free_elem(pq->heap[1]);
-    pq->heap[1] = elem;
-    pq_down(pq);
-    return true;
-  } else {
-    pq->free_elem(elem);
-    return false;
-  }
+    int i;
+    for (i = 1; i <= pq->size; i++) {
+        pq->free_elem_i(pq->heap[i]);
+        pq->heap[i] = NULL;
+    }
+    pq->size = 0;
 }
 
-/*****************************************************************************
- *
- * PriorityQueue2
- *
- *****************************************************************************/
-
-PriorityQueue2 *pq2_create(int max_size,
-    bool (*less_than)(PriorityQueue2 *pq, void *p1, void *p2),
-    free_ft destroy)
+void pq_free(PriorityQueue *pq)
 {
-  PriorityQueue2 *pq = ALLOC(PriorityQueue2);
-  pq->count = 0;
-  pq->size = max_size;
-  pq->heap = ALLOC_N(void *, (max_size + 1));
-  pq->lt = less_than;
-  pq->free_elem = &free;
-  pq->destroy = destroy;
-  return pq;
+    free(pq->heap);
+    free(pq);
 }
 
-void pq2_destroy(PriorityQueue2 *pq)
+void pq_destroy(PriorityQueue *pq)
 {
-  free(pq->heap);
-  free(pq);
+    pq_clear(pq);
+    pq_free(pq);
 }
 
-void pq2_up(PriorityQueue2 *pq)
+/**
+ * This method is used internally by pq_push. It is similar to pq_down except
+ * that where pq_down reorders the elements from the top, pq_up reorders from
+ * the bottom.
+ *
+ * @param pq the PriorityQueue to reorder
+ */
+static void pq_up(PriorityQueue *pq)
 {
-  void **heap = pq->heap;
-  void *node;
-  int i = pq->count;
-	int j = i >> 1;
-  
-  node = heap[i];
-
-	while ((j > 0) && pq->lt(pq, node, heap[j])) {
-		heap[i] = heap[j];
-		i = j;
-		j = j >> 1;
-	}
-  heap[i] = node;
-}
+    void **heap = pq->heap;
+    void *node;
+    int i = pq->size;
+    int j = i >> 1;
 
-void pq2_down(PriorityQueue2 *pq)
-{
-  register int i = 1;
-  register int j = 2; //i << 1;
-  register int k = 3; //j + 1;
-  register int count = pq->count;
-  void **heap = pq->heap;
-  void *node = heap[i]; // save top node
-
-  if ((k <= count) && (pq->lt(pq, heap[k], heap[j])))
-    j = k;
-
-  while ((j <= count) && pq->lt(pq, heap[j], node)) {
-    heap[i] = heap[j];      // shift up child
-    i = j;
-    j = i << 1;
-    k = j + 1;
-    if ((k <= count) && pq->lt(pq, heap[k], heap[j]))
-      j = k;
-  }
-  heap[i] = node;
-}
+    node = heap[i];
 
-void pq2_push(PriorityQueue2 *pq, void *elem) 
-{
-  pq->count++;
-  pq->heap[pq->count] = elem;
-  pq2_up(pq);
+    while ((j > 0) && pq->less_than_i(node, heap[j])) {
+        heap[i] = heap[j];
+        i = j;
+        j = j >> 1;
+    }
+    heap[i] = node;
 }
 
-void *pq2_top(PriorityQueue2 *pq)
+void pq_down(PriorityQueue *pq)
 {
-  return pq->heap[1];
+    register int i = 1;
+    register int j = 2;         /* i << 1; */
+    register int k = 3;         /* j + 1;  */
+    register int size = pq->size;
+    void **heap = pq->heap;
+    void *node = heap[i];       /* save top node */
+
+    if ((k <= size) && (pq->less_than_i(heap[k], heap[j]))) {
+        j = k;
+    }
+
+    while ((j <= size) && pq->less_than_i(heap[j], node)) {
+        heap[i] = heap[j];      /* shift up child */
+        i = j;
+        j = i << 1;
+        k = j + 1;
+        if ((k <= size) && pq->less_than_i(heap[k], heap[j])) {
+            j = k;
+        }
+    }
+    heap[i] = node;
+}
+
+void pq_push(PriorityQueue *pq, void *elem)
+{
+    pq->size++;
+    if (pq->size >= pq->mem_capa) {
+        pq->mem_capa <<= 1;
+        REALLOC_N(pq->heap, void *, pq->mem_capa);
+    }
+    pq->heap[pq->size] = elem;
+    pq_up(pq);
+}
+
+int pq_insert(PriorityQueue *pq, void *elem)
+{
+    if (pq->size < pq->capa) {
+        pq_push(pq, elem);
+        return PQ_ADDED;
+    }
+    else if (pq->size > 0 && pq->less_than_i(pq->heap[1], elem)) {
+        pq->free_elem_i(pq->heap[1]);
+        pq->heap[1] = elem;
+        pq_down(pq);
+        return PQ_INSERTED;
+    }
+    else {
+        pq->free_elem_i(elem);
+        return PQ_DROPPED;
+    }
 }
 
-void *pq2_pop(PriorityQueue2 *pq)
+void *pq_top(PriorityQueue *pq)
 {
-  if (pq->count > 0) {
-    void *result = pq->heap[1];        // save first value
-    pq->heap[1] = pq->heap[pq->count]; // move last to first
-    pq->heap[pq->count] = NULL;
-    pq->count--;
-    pq2_down(pq);                       // adjust heap
-    return result;
-  } else {
-    return NULL;
-  }
+    return pq->size ? pq->heap[1] : NULL;
 }
 
-void pq2_clear(PriorityQueue2 *pq)
+void *pq_pop(PriorityQueue *pq)
 {
-  int i;
-  for (i = 1; i <= pq->count; i++) {
-    pq->free_elem(pq->heap[i]);
-    pq->heap[i] = NULL;
-  }
-  pq->count = 0;
+    if (pq->size > 0) {
+        void *result = pq->heap[1];       /* save first value */
+        pq->heap[1] = pq->heap[pq->size]; /* move last to first */
+        pq->heap[pq->size] = NULL;
+        pq->size--;
+        pq_down(pq);                      /* adjust heap */
+        return result;
+    }
+    else {
+        return NULL;
+    }
 }
 
-int pq2_insert(PriorityQueue2 *pq, void *elem) 
-{
-  if (pq->count < pq->size) {
-    pq2_push(pq, elem);
-    return true;
-  } else if (pq->count > 0 && pq->lt(pq, pq2_top(pq), elem)) {
-    pq->free_elem(pq->heap[1]);
-    pq->heap[1] = elem;
-    pq2_down(pq);
-    return true;
-  } else {
-    pq->free_elem(elem);
-    return false;
-  }
-}

data/ext/priorityqueue.h

@@ -3,45 +3,141 @@
 
 #include "global.h"
 
-typedef bool (*lt_ft)(void *p1, void *p2);
-
-typedef struct PriorityQueue {
-  int count;
-  int size;
-  void **heap;
-  lt_ft lt;
-  //bool (*lt)(void *p1, void *p2);
-  free_ft free_elem;
+typedef bool(*lt_ft) (const void *p1, const void *p2);
+
+/**
+ * A PriorityQueue has a fixed size and contains a less_than function and a
+ * free_elem function specific to the data type to be stored in the queue.
+ */
+typedef struct PriorityQueue
+{
+    int size;
+    int capa;
+    int mem_capa;
+    void **heap;
+    lt_ft less_than_i;
+    free_ft free_elem_i;
 } PriorityQueue;
 
-PriorityQueue *pq_create(int max_size, bool (*less_than)(void *p1, void *p2));
-void pq_destroy(PriorityQueue *pq);
-void pq_push(PriorityQueue *pq, void *elem);
-void *pq_top(PriorityQueue *pq);
-void *pq_pop(PriorityQueue *pq);
-void pq_down(PriorityQueue *pq);
-void pq_clear(PriorityQueue *pq);
-int pq_insert(PriorityQueue *pq, void *elem);
-#define pq_full(pq) ((pq)->count == (pq)->size)
-
-typedef struct PriorityQueue2 {
-  int count;
-  int size;
-  void **heap;
-  void *data;
-  bool (*lt)(struct PriorityQueue2 *pq, void *p1, void *p2);
-  void (*free_elem)(void *p);
-  free_ft destroy;
-} PriorityQueue2;
-
-PriorityQueue2 *pq2_create(int max_size,
-    bool (*less_than)(PriorityQueue2 *pq, void *p1, void *p2),
-    free_ft destroy);
-void pq2_destroy(PriorityQueue2 *pq);
-void pq2_push(PriorityQueue2 *pq, void *elem);
-void *pq2_top(PriorityQueue2 *pq);
-void *pq2_pop(PriorityQueue2 *pq);
-void pq2_down(PriorityQueue2 *pq);
-void pq2_clear(PriorityQueue2 *pq);
-int pq2_insert(PriorityQueue2 *pq, void *elem);
+/**
+ * Create a new PriorityQueue setting the less_than and free_elem for this
+ * specific PriorityQueue.
+ *
+ * @param capa the capacity of the PriorityQueue. As more than the capacity is
+ *   added to the queue the least valued elements drop off the bottom.
+ * @param less_than the function to determine whether one value is less than
+ *   another for this particular PriorityQueue
+ * @param free_elem the function to free the elements in the PriorityQueue
+ *   when it is destroyed or there is insertion overflow
+ * @return a newly allocated PriorityQueue
+ */
+extern PriorityQueue *pq_new(int capa,
+                             bool (*less_than)(const void *p1, const void *p2),
+                             void (*free_elem)(void *elem));
+
+/**
+ * Allocate a clone of the PriorityQueue. This can be used if you want to scan
+ * through all elements of the PriorityQueue but you don't want to have to
+ * remove the all and add them all again.
+ *
+ * @param pq the priority queue to clone
+ * @return a clone of the original priority queue
+ */
+extern PriorityQueue *pq_clone(PriorityQueue *pq);
+
+/**
+ * Clear all elements from the PriorityQueue and reset the size to 0. When
+ * the elements are removed from the PriorityQueue, free_elem is used to free
+ * them, unless it was set to NULL in which case nothing will happen to them.
+ *
+ * @param self the PriorityQueue to clear
+ */
+extern void pq_clear(PriorityQueue *self);
+
+/**
+ * Free the memory allocated to the PriorityQueue. This function does nothing
+ * to the elements in the PriorityQueue itself. To destroy them also, use
+ * pq_destroy.
+ *
+ * @param self the PriorityQueue to free
+ */
+extern void pq_free(PriorityQueue *self);
+
+/**
+ * Destroy the PriorityQueue, freeing all memory allocated to it and also
+ * destroying all the elements contained by it. This method is equivalent to
+ * calling pq_clear followed by pq_free.
+ *
+ * @param the PriorityQueue to destroy
+ */
+extern void pq_destroy(PriorityQueue *self);
+
+/**
+ * Reorder the PriorityQueue after the top element has been modified. This
+ * method is used especially when the PriorityQueue contains a queue of
+ * iterators. When the top iterator is incremented you should call this
+ * method.
+ *
+ * @param self the PriorityQueue to reorder
+ */
+extern void pq_down(PriorityQueue *self);
+
+/**
+ * Add another element to the PriorityQueue. This method should only be used
+ * when the PriorityQueue has enough space allocated to hold all elements
+ * added. If there is a chance that you will add more than the amount you have
+ * allocated then you should use pq_insert. pq_insert will handle insertion
+ * overflow.
+ *
+ * @param self the PriorityQueue to add the element to
+ * @param elem the element to add to the PriorityQueue
+ */
+extern void pq_push(PriorityQueue *self, void *elem);
+
+#define PQ_DROPPED 0
+#define PQ_ADDED 1
+#define PQ_INSERTED 2
+/**
+ * Add another element to the PriorityQueue. Unlike pq_push, this method
+ * handles insertion overflow. That is, when you insert more elements than the
+ * capacity of the PriorityQueue, the elements are dropped off the bottom and
+ * freed using the free_elem function.
+ *
+ * @param self the PriorityQueue to add the element to
+ * @param elem the element to add to the PriorityQueue
+ * @returns one of three values;
+ *   <pre>
+ *     0 == PQ_DROPPED  the element was too small (according to the less_than
+ *                      function) so it was destroyed
+ *     1 == PQ_ADDED    the element was successfully added
+ *     2 == PQ_INSERTED the element was successfully added after another
+ *                      element was dropped and destroyed
+ *   </pre>
+ */
+extern int pq_insert(PriorityQueue *self, void *elem);
+
+/**
+ * Get the top element in the PriorityQueue.
+ *
+ * @param self the PriorityQueue to get the top from
+ * @return the top element in the PriorityQueue
+ */
+extern void *pq_top(PriorityQueue *self);
+
+/**
+ * Remove and return the top element in the PriorityQueue.
+ *
+ * @param self the PriorityQueue to get the top from
+ * @return the top element in the PriorityQueue
+ */
+extern void *pq_pop(PriorityQueue *self);
+
+/**
+ * Return true if the PriorityQueue is full.
+ *
+ * @param self the PriorityQueue to test
+ * @return true if the PriorityQueue is full.
+ */
+#define pq_full(pq) ((pq)->size == (pq)->capa)
+
 #endif