Add another option for c heapsort, minor refactors, update docs

c/algorithms/sort_heap.c

@@ -1,8 +1,18 @@
 #include "../data_structures/heap.h"
 #include "sort_heap.h"
 
-void dlos_sort_heap(dlos_Heap *h) {
-    int original_size = h->size;
+void dlos_heapsort_array(dlos_ComparableNode *arr, int size, int (*compare)()) {
+    dlos_Heap heap = { .size = size, .arr = arr, .arr_size = size, .compare = compare };
+    dlos_max_heap(&heap);
+    for (int i = heap.size - 1; i > 0; i--) {
+        dlos_node_swap(heap.arr, 0, i);
+        heap.size -= 1;
+        dlos_sift_down(0, &heap);
+    }
+}
+
+// already have the heap, want to sort its array
+void dlos_heapsort_heap(dlos_Heap *h) {
     for (int i = h->size - 1; i > 0; i--) {
         dlos_node_swap(h->arr, 0, i);
         h->size -= 1;

c/algorithms/sort_heap.h

@@ -2,4 +2,37 @@
 
 #include "../data_structures/heap.h"
 
-void dlos_sort_heap(dlos_Heap *h);
+// // example use of dlos_heapsort_array
+// // define a comparison function for the nodes
+// int compare_nodes(dlos_ComparableNode *a, dlos_ComparableNode *b) {
+//     int left = *((int*) a->value);
+//     int right = *((int*) b->value);
+//     if (left > right) {
+//         return -1;
+//     } else if (left == right) {
+//         return 0;
+//     } else {
+//         return 1;
+//     }
+// }
+//
+// int main(int argc, char *argv[]) {
+//     // have an array (could be malloc'd/heap memory or something in the stack)
+//     int test_size = 10;
+//     int data_storage[] = {73, 6, 57, 88, 60, 42, 83, 72, 48, 85};
+//     dlos_ComparableNode a[test_size];
+//     for (int i = 0; i < test_size; i++) {
+//         a[i].value = &data_storage[i];
+//     }
+//     // call sort with pointer to array, size, and pointer to the compare func
+//     dlos_heapsort_array(a, test_size, compare_nodes);
+//     for (int i = 0; i < test_size; i++) {
+//         if (i == 0) printf("sorted: ");
+//         printf("%d, ", *((int*) a[i].value));
+//         if (i == test_size - 1) printf("\n");
+//     }
+//     return 0;
+// }
+
+void dlos_heapsort_array(dlos_ComparableNode *arr, int size, int (*compare)());
+void dlos_heapsort_heap(dlos_Heap *h);

c/data_structures/heap.c

@@ -1,6 +1,5 @@
 #include "heap.h"
 
-// TODO: remove the extra checks for heap_size if i don't need them based on calling
 static int parent(int i) {
     return (i > 0) ? (i - 1) / 2 : -1;
 }

c/data_structures/heap.h

@@ -1,23 +1,9 @@
 #pragma once
 
-typedef struct dlos_ComparableNode {
-    void *value;
-} dlos_ComparableNode;
-
-typedef struct dlos_Heap {
-    int size;
-    dlos_ComparableNode *arr;
-    int arr_size;
-    int (*compare)(dlos_ComparableNode *a, dlos_ComparableNode *b);
-} dlos_Heap;
-
-void dlos_node_swap(dlos_ComparableNode *arr, int a, int b);
-void dlos_sift_down(int i, dlos_Heap *h);
-void dlos_max_heap(dlos_Heap *h);
-
 // example of how the heap can be used
 // here, each node value points to a plain int, but can substitute with other types
 //
+// // define a comparison function, a > b returns -1, a == b returns 0, a < b returns 1
 // int compare_nodes(dlos_ComparableNode *a, dlos_ComparableNode *b) {
 //     int left = *((int*) a->value);
 //     int right = *((int*) b->value);
@@ -33,16 +19,22 @@ void dlos_max_heap(dlos_Heap *h);
 // int main(int argc, char *argv[]) {
 //     int test_size = 10;
 //     int data_storage[] = {73, 6, 57, 88, 60, 42, 83, 72, 48, 85};
+//
+//     // define an array of dlos_ComparableNode and fill it with the desired data
+//     // note: if using heap memory, just use for array, keep dlos_Heap in stack memory
 //     dlos_ComparableNode a[test_size];
 //     for (int i = 0; i < test_size; i++) {
 //         a[i].value = &data_storage[i];
 //     }
+//     // then define the dlos_Heap with the above array, compare function, and sizes
 //     dlos_Heap heap = {
 //         .size = test_size,
 //         .arr = a,
 //         .arr_size = test_size,
 //         .compare = compare_nodes
 //     };
+//
+//     // then can use the heap; for example: order data into a max heap and sort it
 //     dlos_max_heap(&heap);
 //     dlos_sort_heap(&heap);
 //     for (int i = 0; i < test_size; i++) {
@@ -52,3 +44,18 @@ void dlos_max_heap(dlos_Heap *h);
 //     }
 //     return 0;
 // }
+
+typedef struct dlos_ComparableNode {
+    void *value;
+} dlos_ComparableNode;
+
+typedef struct dlos_Heap {
+    int size;
+    dlos_ComparableNode *arr;
+    int arr_size;
+    int (*compare)(dlos_ComparableNode *a, dlos_ComparableNode *b);
+} dlos_Heap;
+
+void dlos_node_swap(dlos_ComparableNode *arr, int a, int b);
+void dlos_sift_down(int i, dlos_Heap *h);
+void dlos_max_heap(dlos_Heap *h);

c/test.c

@@ -22,17 +22,10 @@ int main(int argc, char *argv[]) {
     for (int i = 0; i < test_size; i++) {
         a[i].value = &data_storage[i];
     }
-    dlos_Heap heap = {
-        .size = test_size,
-        .arr = a,
-        .arr_size = test_size,
-        .compare = compare_nodes
-    };
-    dlos_max_heap(&heap);
-    dlos_sort_heap(&heap);
+    dlos_heapsort_array(a, test_size, compare_nodes);
     for (int i = 0; i < test_size; i++) {
         if (i == 0) printf("sorted: ");
-        printf("%d, ", *((int*) heap.arr[i].value));
+        printf("%d, ", *((int*) a[i].value));
         if (i == test_size - 1) printf("\n");
     }
     return 0;