Add documentation to Array.h

src/Array.c

@@ -12,24 +12,7 @@
 #include <stdio.h>
 #include <stdlib.h>
 
-int lower_bound(IntegerArray *array, uint64_t item) {
-    int low = 0;
-    int high = array->size - 1;
-
-    while (low <= high) {
-        int m = (low + high) / 2;
-
-        if (array->items[m] < item) {
-            low = m + 1;
-        } else if (array->items[m] > item) {
-            high = m - 1;
-        } else {
-            return m;
-        }
-    }
-
-    return low;
-}
+// IntegerArray
 
 IntegerArray *IntegerArray_init(int capacity) {
     IntegerArray *array = (IntegerArray *)malloc(sizeof(IntegerArray));
@@ -44,12 +27,6 @@ void IntegerArray_destroy(IntegerArray **array) {
     *array = NULL;
 }
 
-int IntegerArray_insert_sorted(IntegerArray *array, uint64_t item) {
-    int index = lower_bound(array, item);
-    IntegerArray_insert_at_index(array, index, item);
-    return index;
-}
-
 void IntegerArray_insert_at_index(IntegerArray *array, int index, uint64_t item) {
     for (int i = array->size - 1; i >= index; i--) {
         array->items[i + 1] = array->items[i];
@@ -59,6 +36,31 @@ void IntegerArray_insert_at_index(IntegerArray *array, int index, uint64_t item)
     array->size++;
 }
 
+int IntegerArray_lower_bound(IntegerArray *array, uint64_t item) {
+    int low = 0;
+    int high = array->size - 1;
+
+    while (low <= high) {
+        int m = (low + high) / 2;
+
+        if (array->items[m] < item) {
+            low = m + 1;
+        } else if (array->items[m] > item) {
+            high = m - 1;
+        } else {
+            return m;
+        }
+    }
+
+    return low;
+}
+
+int IntegerArray_insert_sorted(IntegerArray *array, uint64_t item) {
+    int index = IntegerArray_lower_bound(array, item);
+    IntegerArray_insert_at_index(array, index, item);
+    return index;
+}
+
 void IntegerArray_append(IntegerArray *array, uint64_t item) {
     array->items[array->size] = item;
     array->size++;
@@ -122,6 +124,8 @@ void IntegerArray_copy(IntegerArray *src, IntegerArray *dest) {
     dest->size = src->size;
 }
 
+// BPTreeNodeArray
+
 BPTreeNodeArray *BPTreeNodeArray_init(int capacity) {
     BPTreeNodeArray *array = (BPTreeNodeArray *)malloc(sizeof(BPTreeNodeArray));
     array->items = (BPTreeNode **)malloc(sizeof(BPTreeNode *) * capacity);
@@ -167,12 +171,6 @@ void BPTreeNodeArray_delete_at_index(BPTreeNodeArray *array, int index) {
     array->size--;
 }
 
-BPTreeNode *BPTreeNodeArray_pop(BPTreeNodeArray *array) {
-    BPTreeNode *item = array->items[array->size - 1];
-    BPTreeNodeArray_delete_at_index(array, array->size - 1);
-    return item;
-}
-
 void BPTreeNodeArray_clear(BPTreeNodeArray *array) {
     array->size = 0;
 }
@@ -185,6 +183,8 @@ void BPTreeNodeArray_copy(BPTreeNodeArray *src, BPTreeNodeArray *dest) {
     dest->size = src->size;
 }
 
+// ByteArray
+
 ByteArray *ByteArray_init(int capacity) {
     ByteArray *array = (ByteArray *)malloc(sizeof(ByteArray));
     array->items = (uint8_t *)malloc(sizeof(uint8_t) * capacity);

src/Array.h

 /**
  * @file Array.h
  * @author Florian Burgener (florian.burgener@etu.hesge.ch)
- * @brief
+ * @brief Implementation of 3 arrays: IntegerArray, BPTreeNodeArray and ByteArray.
  * @version 1.0
  * @date 2022-06-XX
  */
@@ -13,55 +13,215 @@
 
 // IntegerArray
 
+/**
+ * @brief Data structure that represents an array of integers of type uint64_t.
+ *
+ */
 typedef struct IntegerArray {
     uint64_t *items;
     int size;
 } IntegerArray;
 
-int lower_bound(IntegerArray *array, uint64_t item);
-
+/**
+ * @brief Initializes the "IntegerArray" data structure.
+ *
+ * @param capacity Maximum number of items the array can contain.
+ * @return IntegerArray* An empty "IntegerArray".
+ */
 IntegerArray *IntegerArray_init(int capacity);
+
+/**
+ * @brief Destroy the array and free its memory.
+ *
+ * @param array The array to be destroyed.
+ */
 void IntegerArray_destroy(IntegerArray **array);
 
-int IntegerArray_insert_sorted(IntegerArray *array, uint64_t item);
+/**
+ * @brief Inserts an item in the array at the desired index.
+ *
+ * @param array The array in which the item will be inserted.
+ * @param index The index where the item must be inserted.
+ * @param item The item to be inserted.
+ */
 void IntegerArray_insert_at_index(IntegerArray *array, int index, uint64_t item);
+
+/**
+ * @brief Finds out at which index the item should be inserted in the array.
+ *
+ * @param array The array in which to search, it must be sorted.
+ * @param item The item that should be inserted.
+ * @return int The index where the item would be inserted.
+ */
+int IntegerArray_lower_bound(IntegerArray *array, uint64_t item);
+
+/**
+ * @brief Inserts an item in the sorted array.
+ *
+ * @param array The sorted array in which the item will be inserted.
+ * @param item The item to be inserted.
+ * @return int The index where the item has been inserted.
+ */
+int IntegerArray_insert_sorted(IntegerArray *array, uint64_t item);
+
+/**
+ * @brief Appends an item to the end of the array.
+ *
+ * @param array The array in which the item will be added.
+ * @param item The item to be added.
+ */
 void IntegerArray_append(IntegerArray *array, uint64_t item);
+
+/**
+ * @brief Searches for an item in the sorted array.
+ *
+ * @param array The array in which the item is searched.
+ * @param item The sought-after item.
+ * @param index If the item is found its index will be assigned to this variable.
+ * @return true The item has been found.
+ * @return false The item has not been found.
+ */
 bool IntegerArray_binary_search(IntegerArray *array, uint64_t item, int *index);
+
+/**
+ * @brief Deletes an item from the array at the desired index.
+ *
+ * @param array The array in which the item is deleted.
+ * @param index The index where the item must be deleted.
+ */
 void IntegerArray_delete_at_index(IntegerArray *array, int index);
+
+/**
+ * @brief Displays the array on the console.
+ *
+ * @param array The array to display.
+ */
 void IntegerArray_print(IntegerArray *array);
+
+/**
+ * @brief Deletes all items from the array.
+ *
+ * @param array The array where all the items must be deleted.
+ */
 void IntegerArray_clear(IntegerArray *array);
+
+/**
+ * @brief Copies the source array to the destination array.
+ *
+ * @param src The source array.
+ * @param dest The destination array. The destination array must have at least the capacity of the source array.
+ */
 void IntegerArray_copy(IntegerArray *src, IntegerArray *dest);
 
 // BPTreeNodeArray
 
 typedef struct BPTreeNode BPTreeNode;
 
+/**
+ * @brief Data structure that represents an array of pointers of type BPTreeNode.
+ *
+ */
 typedef struct BPTreeNodeArray {
     BPTreeNode **items;
     int size;
 } BPTreeNodeArray;
 
+/**
+ * @brief Initializes the "BPTreeNodeArray" data structure.
+ *
+ * @param capacity Maximum number of items the array can contain.
+ * @return BPTreeNodeArray* An empty "BPTreeNodeArray".
+ */
 BPTreeNodeArray *BPTreeNodeArray_init(int capacity);
+
+/**
+ * @brief Destroy the array and free its memory.
+ *
+ * @param array The array to be destroyed.
+ */
 void BPTreeNodeArray_destroy(BPTreeNodeArray **array);
 
+/**
+ * @brief Inserts an item in the array at the desired index.
+ *
+ * @param array The array in which the item will be inserted.
+ * @param index The index where the item must be inserted.
+ * @param item The item to be inserted.
+ */
 void BPTreeNodeArray_insert_at_index(BPTreeNodeArray *array, int index, BPTreeNode *item);
+
+/**
+ * @brief Appends an item to the end of the array.
+ *
+ * @param array The array in which the item will be added.
+ * @param item The item to be added.
+ */
 void BPTreeNodeArray_append(BPTreeNodeArray *array, BPTreeNode *item);
+
+/**
+ * @brief Searches for an item in the array.
+ *
+ * @param array The array in which the item is searched.
+ * @param item The sought-after item.
+ * @return int If the item is found returns its index otherwise -1.
+ */
 int BPTreeNodeArray_search(BPTreeNodeArray *array, BPTreeNode *item);
+
+/**
+ * @brief Deletes an item from the array at the desired index.
+ *
+ * @param array The array in which the item is deleted.
+ * @param index The index where the item must be deleted.
+ */
 void BPTreeNodeArray_delete_at_index(BPTreeNodeArray *array, int index);
-BPTreeNode *BPTreeNodeArray_pop(BPTreeNodeArray *array);
+
+/**
+ * @brief Deletes all items from the array.
+ *
+ * @param array The array where all the items must be deleted.
+ */
 void BPTreeNodeArray_clear(BPTreeNodeArray *array);
+
+/**
+ * @brief Copies the source array to the destination array.
+ *
+ * @param src The source array.
+ * @param dest The destination array. The destination array must have at least the capacity of the source array.
+ */
 void BPTreeNodeArray_copy(BPTreeNodeArray *src, BPTreeNodeArray *dest);
 
 // ByteArray
 
+/**
+ * @brief Data structure that represents an array of bytes.
+ *
+ */
 typedef struct ByteArray {
     uint8_t *items;
     int size;
 } ByteArray;
 
+/**
+ * @brief Initializes the "ByteArray" data structure.
+ *
+ * @param capacity Maximum number of items the array can contain.
+ * @return ByteArray* An empty "ByteArray".
+ */
 ByteArray *ByteArray_init(int capacity);
+
+/**
+ * @brief Destroy the array and free its memory.
+ *
+ * @param array The array to be destroyed.
+ */
 void ByteArray_destroy(ByteArray **array);
 
+/**
+ * @brief Appends an item to the end of the array.
+ *
+ * @param array The array in which the item will be added.
+ * @param item The item to be added.
+ */
 void ByteArray_append(ByteArray *array, uint8_t item);
 
 #endif

src/BPTree.c

@@ -78,7 +78,7 @@ bool BPTree_search(BPTreeNode *root, uint64_t key, uint64_t *data) {
         return found;
     }
 
-    int child_index = lower_bound(root->keys, key);
+    int child_index = IntegerArray_lower_bound(root->keys, key);
 
     if (child_index < root->keys->size && root->keys->items[child_index] == key) {
         child_index += 1;
@@ -90,7 +90,7 @@ bool BPTree_search(BPTreeNode *root, uint64_t key, uint64_t *data) {
 // "traverse" function for insertion and deletion.
 
 static BPTreeNode *traverse(BPTreeNode *node, uint64_t key) {
-    int virtual_insertion_index = lower_bound(node->keys, key);
+    int virtual_insertion_index = IntegerArray_lower_bound(node->keys, key);
 
     if (virtual_insertion_index < node->keys->size && node->keys->items[virtual_insertion_index] == key) {
         virtual_insertion_index += 1;
@@ -130,7 +130,7 @@ static void redistribute_keys(BPTreeNode *left_node, BPTreeNode *right_node, int
 }
 
 static uint64_t split_leaf(BPTreeNode *node, uint64_t key, uint64_t data, BPTreeNode **split_right_node) {
-    int virtual_insertion_index = lower_bound(node->keys, key);
+    int virtual_insertion_index = IntegerArray_lower_bound(node->keys, key);
     int median_index = node->keys->size / 2;
     uint64_t median_value;
     *split_right_node = BPTreeNode_init(node->order, true);
@@ -169,7 +169,7 @@ static void redistribute_children(BPTreeNode *left_node, BPTreeNode *right_node,
 }
 
 static uint64_t split_internal(BPTreeNode *node, uint64_t key, BPTreeNode *previous_split_right_node, BPTreeNode **split_right_node) {
-    int virtual_insertion_index = lower_bound(node->keys, key);
+    int virtual_insertion_index = IntegerArray_lower_bound(node->keys, key);
     int median_index = node->keys->size / 2;
     uint64_t median_value;
     *split_right_node = BPTreeNode_init(node->order, false);