ferret 0.9.6 → 0.10.0

data/ext/hashset.c

@@ -1,139 +1,167 @@
-#include <hashset.h>
+#include "hashset.h"
 #include <string.h>
-#define HS_MIN_SIZE 4
 
-int *imalloc(int i)
+/*
+ * The HashSet contains an array +elems+ of the elements that have been added.
+ * It always has +size+ elements so +size+ ane +elems+ can be used to iterate
+ * over all alements in the HashSet. It also uses a HashTable to keep track of
+ * which elements have been added and their index in the +elems+ array.
+ */
+static HashSet *hs_alloc(void (*free_elem) (void *p))
 {
-  int *ip = ALLOC(int);
-  *ip = i;
-  return ip;
+    HashSet *hs = ALLOC(HashSet);
+    hs->size = 0;
+    hs->capa = HS_MIN_SIZE;
+    hs->elems = ALLOC_N(void *, HS_MIN_SIZE);
+    hs->free_elem_i = free_elem ? free_elem : &dummy_free;
+    return hs;
 }
 
-void hs_dummy_free(void *p){}
-
-HashSet *hs_create(unsigned int (*hash)(const void *p),
-    int (*eq)(const void *p1, const void *p2),
-    void (*free_elem)(void *p))
+HashSet *hs_new(ulong (*hash)(const void *p),
+                int (*eq)(const void *p1, const void *p2),
+                void (*free_elem)(void *p))
 {
-  HashSet *hs = ALLOC(HashSet);
-  hs->ht = h_new(hash, eq, NULL, &free);
-  hs->elems = NULL;
-  hs->capa = hs->size = 0;
-  if (free_elem == NULL)
-    hs->free_elem = &hs_dummy_free;
-  else
-    hs->free_elem = free_elem;
-  return hs;
+    HashSet *hs = hs_alloc(free_elem);
+    hs->ht = h_new(hash, eq, NULL, &free);
+    return hs;
 }
 
-HashSet *hs_str_create(void (*free_elem)(void *p))
+HashSet *hs_new_str(void (*free_elem) (void *p))
 {
-  HashSet *hs = ALLOC(HashSet);
-  hs->ht = h_new_str((free_ft)NULL, &free);
-  hs->elems = NULL;
-  hs->capa = hs->size = 0;
-  if (free_elem == NULL)
-    hs->free_elem = &hs_dummy_free;
-  else
-    hs->free_elem = free_elem;
-  return hs;
+    HashSet *hs = hs_alloc(free_elem);
+    hs->ht = h_new_str((free_ft) NULL, &free);
+    return hs;
 }
 
-void hs_destroy(HashSet *hs)
+void hs_free(HashSet *hs)
 {
-  h_destroy(hs->ht);
-  free(hs->elems);
-  free(hs);
+    h_destroy(hs->ht);
+    free(hs->elems);
+    free(hs);
 }
 
-void hs_clear(HashSet *self)
+void hs_clear(HashSet *hs)
 {
-  int i;
-  for (i = self->size - 1; i >= 0; i--)
-    hs_del(self, self->elems[i]);
+    int i;
+    for (i = hs->size - 1; i >= 0; i--) {
+        hs_del(hs, hs->elems[i]);
+    }
 }
 
-void hs_destroy_all(HashSet *hs)
+void hs_destroy(HashSet *hs)
 {
-  int i;
-  if (hs->free_elem != &dummy_free)
-    for (i = 0; i < hs->size; i++)
-      hs->free_elem(hs->elems[i]);
-  hs_destroy(hs);
+    int i;
+    if (hs->free_elem_i != &dummy_free) {
+        for (i = 0; i < hs->size; i++) {
+            hs->free_elem_i(hs->elems[i]);
+        }
+    }
+    h_destroy(hs->ht);
+    free(hs->elems);
+    free(hs);
 }
 
 int hs_add(HashSet *hs, void *elem)
 {
-  int has_elem = h_has_key(hs->ht, elem);
-  //printf("has_elem = %d %d:%d\n", has_elem, HASH_KEY_EQUAL, HASH_KEY_SAME);
-  if (has_elem == HASH_KEY_EQUAL) {
-    // We don't want to keep two of the same elem so free if necessary
-    hs->free_elem(elem);
-  } else if (has_elem == HASH_KEY_SAME) {
-    // No need to do anything
-  } else {
-    // add the elem to the array, resizing if necessary
-    if (hs->size >= hs->capa) {
-      if (hs->capa == 0)
-        hs->capa = HS_MIN_SIZE;
-      else
-        hs->capa *= 2;
-      REALLOC_N(hs->elems, void *, hs->capa);
+    int has_elem = h_has_key(hs->ht, elem);
+    if (has_elem == HASH_KEY_EQUAL) {
+        /* We don't want to keep two of the same elem so free if necessary */
+        hs->free_elem_i(elem);
+    }
+    else if (has_elem == HASH_KEY_SAME) {
+        /* No need to do anything */
+    }
+    else {
+        /* add the elem to the array, resizing if necessary */
+        if (hs->size >= hs->capa) {
+            hs->capa *= 2;
+            REALLOC_N(hs->elems, void *, hs->capa);
+        }
+        hs->elems[hs->size] = elem;
+        h_set(hs->ht, elem, imalloc(hs->size));
+        hs->size++;
+    }
+    return has_elem;
+}
+
+int hs_add_safe(HashSet *hs, void *elem)
+{
+    int has_elem = h_has_key(hs->ht, elem);
+    if (has_elem == HASH_KEY_EQUAL) {
+        /* element can't be added */
+        return false;
+    }
+    else if (has_elem == HASH_KEY_SAME) {
+        /* the exact same element has already been added */
+        return true;
+    }
+    else {
+        /* add the elem to the array, resizing if necessary */
+        if (hs->size >= hs->capa) {
+            hs->capa *= 2;
+            REALLOC_N(hs->elems, void *, hs->capa);
+        }
+        hs->elems[hs->size] = elem;
+        h_set(hs->ht, elem, imalloc(hs->size));
+        hs->size++;
+        return true;
     }
-    hs->elems[hs->size] = elem;
-    h_set(hs->ht, elem, imalloc(hs->size));
-    hs->size++;
-  }
-  return has_elem;
 }
 
 int hs_del(HashSet *hs, void *elem)
 {
-  void *tmp_elem = hs_rem(hs, elem);
-  if (tmp_elem != NULL) {
-    hs->free_elem(tmp_elem);
-    return 1;
-  } else {
-    return 0;
-  }
+    void *tmp_elem = hs_rem(hs, elem);
+    if (tmp_elem != NULL) {
+        hs->free_elem_i(tmp_elem);
+        return 1;
+    }
+    else {
+        return 0;
+    }
 }
 
 void *hs_rem(HashSet *hs, void *elem)
 {
-  void *ret_elem;
-  int *index = (int *)h_get(hs->ht, elem);
-  if (index == NULL) {
-    return NULL;
-  } else {
-    int i = *index;
-    ret_elem = hs->elems[i];
-    h_del(hs->ht, elem);
-    hs->size--;
-    memmove(&hs->elems[i], &hs->elems[i+1], sizeof(void *) * (hs->size - i));
-    return ret_elem;
-  }
+    void *ret_elem;
+    int *index = (int *)h_get(hs->ht, elem);
+    if (index == NULL) {
+        return NULL;
+    }
+    else {
+        int i = *index;
+        ret_elem = hs->elems[i];
+        h_del(hs->ht, elem);
+        hs->size--;
+        memmove(&hs->elems[i], &hs->elems[i + 1],
+                sizeof(void *) * (hs->size - i));
+        return ret_elem;
+    }
 }
 
 int hs_exists(HashSet *hs, void *elem)
 {
-  return h_has_key(hs->ht, elem);
+    return h_has_key(hs->ht, elem);
 }
 
-HashSet *hs_merge(HashSet *hs, HashSet *other)
+HashSet *hs_merge(HashSet *hs, HashSet * other)
 {
-  int i;
-  for (i = 0; i < other->size; i++) {
-    hs_add(hs, other->elems[i]);
-  }
-  // Now free the other hashset. It is no longer needed. No need, however, to
-  // delete the elements as they are in the new hash set
-  hs_destroy(other);
-  return hs;
+    int i;
+    for (i = 0; i < other->size; i++) {
+        hs_add(hs, other->elems[i]);
+    }
+    /* Now free the other hashset. It is no longer needed. No need, however, to
+     * delete the elements as they're either destroyed or in the new hash set */
+    hs_free(other);
+    return hs;
 }
 
 void *hs_orig(HashSet *hs, void *elem)
 {
-  int *i = h_get(hs->ht, elem);
-  if (i) return hs->elems[*i];
-  else return NULL;
+    int *index = h_get(hs->ht, elem);
+    if (index) {
+        return hs->elems[*index];
+    }
+    else {
+        return NULL;
+    }
 }

data/ext/hashset.h

@@ -2,30 +2,179 @@
 #define FRT_HASHSET_H
 
 #include "hash.h"
-#include "array.h"
 #include "global.h"
 
-typedef struct HashSet {
-  int capa;
-  int size;
-  void **elems;
-  HshTable *ht;
-  void (*free_elem)(void *p);
+#define HS_MIN_SIZE 4
+
+typedef struct HashSet
+{
+    /* used internally to allocate space to elems */
+    int capa;
+
+    /* the number of elements in the HashSet */
+    int size;
+
+    /* the elements in the HashSet. The elements will be found in the order
+     * they were added and can be iterated over from 0 to .size */ 
+    void **elems;
+
+    /* HashTable used internally */
+    HashTable *ht;
+
+    /* Internal: Frees elements added to the HashSet. Should never be NULL */
+    void (*free_elem_i)(void *p);
 } HashSet;
 
-HashSet *hs_create(unsigned int (*hash)(const void *p),
-                   int (*eq)(const void *p1, const void *p2),
-                   void (*free_elem)(void *p));
-HashSet *hs_str_create(void (*free_elem)(void *p));
-void hs_destroy(HashSet *hs);
-void hs_destroy_all(HashSet *hs);
-int hs_add(HashSet *hs, void *elem);
-int hs_del(HashSet *hs, void *elem);
-void *hs_rem(HashSet *hs, void *elem);
-int hs_exists(HashSet *hs, void *elem);
-HashSet *hs_merge(HashSet *hs, HashSet *other);
-void *hs_orig(HashSet *hs, void *elem);
-void hs_clear(HashSet *self);
+/**
+ * Create a new HashSet. The function will allocate a HashSet Struct setting
+ * the functions used to hash the objects it will contain and the eq function.
+ * This should be used for non-string types.
+ *
+ * @param hash function to hash objects added to the HashSet
+ * @param eq function to determine whether two items are equal
+ * @param free_elem function used to free elements as added to the HashSet
+ *   when the HashSet if destroyed or duplicate elements are added to the Set
+ * @return a newly allocated HashSet structure
+ */
+extern HashSet *hs_new(ulong (*hash)(const void *p),
+                       int (*eq)(const void *p1, const void *p2),
+                       void (*free_elem)(void *p));
+
+/**
+ * Create a new HashSet specifically for strings. This will create a HashSet
+ * as if you used hs_new with the standard string hash and eq functions.
+ *
+ * @param free_elem function used to free elements as added to the HashSet
+ *   when the HashSet if destroyed or duplicate elements are added to the Set
+ * @return a newly allocated HashSet structure
+ */
+extern HashSet *hs_new_str(void (*free_elem) (void *p));
+
+/**
+ * Free the memory allocated by the HashSet, but don't free the elements added
+ * to the HashSet. If you'd like to free everything in the HashSet you should
+ * use hs_destroy
+ *
+ * @param hs the HashSet to free
+ */
+extern void hs_free(HashSet *self);
+
+/**
+ * Destroy the HashSet including all elements added to the HashSet. If you'd
+ * like to free the memory allocated to the HashSet without touching the
+ * elements in the HashSet then use hs_free
+ *
+ * @param hs the HashSet to destroy
+ */
+extern void hs_destroy(HashSet *self);
+
+/**
+ * WARNING: this function may destroy some elements if you add them to a
+ * HashSet were equivalent elements already exist, depending on how free_elem
+ * was set.
+ *
+ * Add the element to the HashSet whether or not it was already in the
+ * HashSet.
+ *
+ * When a element is added to the HashTable where it already exists, free_elem
+ * is called on it, ie the element you tried to add might get destroyed.
+ *
+ * @param hs the HashSet to add the element to
+ * @param elem the element to add to the HashSet
+ * @return one of three values;
+ *   <pre>
+ *     HASH_KEY_DOES_NOT_EXIST  the element was not already in the HashSet.
+ *                              This value is equal to 0 or false
+ *     HASH_KEY_SAME            the element was identical (same memory
+ *                              pointer) to an existing element so no freeing
+ *                              was done
+ *     HASH_KEY_EQUAL           the element was equal to an element already in
+ *                              the HashSet so the new_elem was freed if
+ *                              free_elem was set
+ *   </pre>
+ */
+extern int hs_add(HashSet *self, void *elem);
+
+/**
+ * Add element to the HashSet. If the element already existed in the HashSet
+ * and the new element was equal but not the same (same pointer/memory) then
+ * don't add the element and return false, otherwise return true.
+ *
+ * @param hs the HashSet to add the element to
+ * @param elem the element to add to the HashSet
+ * @return true if the element was successfully added or false otherwise
+ */
+extern int hs_add_safe(HashSet *self, void *elem);
+
+/**
+ * Delete the element from the HashSet. Returns true if the item was
+ * successfully deleted or false if the element never existed.
+ *
+ * @param hs the HashSet to delete from
+ * @param elem the element to delete
+ * @return true if the element was deleted or false if the element never
+ *   existed
+ */
+extern int hs_del(HashSet *self, void *elem);
+
+/**
+ * Remove an item from the HashSet without actually freeing the item. This
+ * function should return the item itself so that it can be freed later if
+ * necessary.
+ *
+ * @param hs the HashSet to remove the element from.
+ * @param elem the element to remove
+ * @param the element that was removed or NULL otherwise
+ */
+extern void *hs_rem(HashSet *self, void *elem);
+
+/**
+ * Check if the element exists and return the appropriate value described
+ * bellow.
+ *
+ * @param hs the HashSet to check in
+ * @param elem the element to check for
+ * @return one of the following values
+ * <pre>
+ *     HASH_KEY_DOES_NOT_EXIST  the element was not already in the HashSet.
+ *                              This value is equal to 0 or false
+ *     HASH_KEY_SAME            the element was identical (same memory
+ *                              pointer) to an existing element so no freeing
+ *                              was done
+ *     HASH_KEY_EQUAL           the element was equal to an element already in
+ *                              the HashSet so the new_elem was freed if
+ *                              free_elem was set
+ *   </pre>
+ */
+extern int hs_exists(HashSet *self, void *elem);
+
+/**
+ * Merge two HashSets. When a merge is done the merger (self) HashTable is
+ * returned and the mergee is destroyed. All elements from mergee that were
+ * not found in merger (self) will be added to self, otherwise they will be
+ * destroyed.
+ * 
+ * @param self the HashSet to merge into
+ * @param other HastSet to be merged into self
+ * @return the merged HashSet
+ */
+extern HashSet *hs_merge(HashSet *self, HashSet *other);
+
+/** 
+ * Return the original version of +elem+. So if you allocate two elements
+ * which are equal and add the first to the HashSet, calling this function
+ * with the second element will return the first element from the HashSet.
+ */
+extern void *hs_orig(HashSet *self, void *elem);
+
+/**
+ * Clear all elements from the HashSet. If free_elem was set then use it to
+ * free all elements as they are cleared. After the method is called, the
+ * HashSets size will be 0.
+ *
+ * @param self the HashSet to clear
+ */
+extern void hs_clear(HashSet *self);
 
 /* TODO: finish these functions.
 int hs_osf(HashSet *hs, void *elem);