Chores: add improved function-comments at 'dynamic_array' and additional dynamic-array length-checks to 'test_insert_element_at_index'-unittest function

Author: Pulsar7

docs/README.md

@@ -95,7 +95,7 @@ for (int value = 0; value < 50; value++) {
 //
 // Get amount of elments in dynamic-array
 size_t array_len;
-if (get_len(&dynamic_array, &array_len) == true) {
+if (get_len(&dynamic_array, &array_len) == NO_ERROR) {
     printf("length of dynamic-array=%d\n", array_len);
 } else {
     printf("Couldn't get length of dynamic-array\n");
@@ -188,7 +188,7 @@ size_t static_char_array_len = strlen(static_char_array);
 if (append_element_to_dyn_array(&dynamic_array_b, (void*)static_char_array, sizeof(char)*((size_t)static_char_array_len)) == NO_ERROR) {
     //
     // Append string-element from dynamic-array-B to dynamic-array-A
-    if (append_dyn_arrays_inplace(&dynamic_array_a, &dynamic_array_b)) {
+    if (append_dyn_arrays_inplace(&dynamic_array_a, &dynamic_array_b) == NO_ERROR) {
         printf("%s\n", (char*)get_element_by_index(&dynamic_array_a, 0));
     }
 }

includes/dynamic_array.h

@@ -2,7 +2,6 @@
 #define DYNAMIC_ARRAY_LIB_DYNAMIC_ARRAY_H
 
 #include <stddef.h>
-#include <stdbool.h>
 
 /*
 Define enums, structs
@@ -37,11 +36,11 @@ Error_Code init_dyn_array(DynArray* dynamic_array);
 Error_Code append_element_to_dyn_array(DynArray* dynamic_array, const void* data, const size_t data_size);
 void* get_last(const DynArray* dynamic_array);
 void* get_first(const DynArray* dynamic_array);
-bool get_len(const DynArray* dynamic_array, size_t* len);
+Error_Code get_len(const DynArray* dynamic_array, size_t* len);
 Error_Code append_static_array_elements_to_dyn_array(DynArray* dynamic_array, const void* static_array, const size_t static_array_elem_size, const size_t static_array_len);
 DynArrayNode* get_element_ptr_by_index(const DynArray* dynamic_array, const size_t index);
 void* get_element_by_index(const DynArray* dynamic_array, const size_t index);
-bool append_dyn_arrays_inplace(DynArray* a, const DynArray* b);
+Error_Code append_dyn_arrays_inplace(DynArray* a, const DynArray* b);
 Error_Code swap_elements_by_indices(DynArray* dynamic_array, const size_t index_a, const size_t index_b);
 Error_Code replace_element_by_index(DynArray* dynamic_array, const size_t index, const void* data, const size_t data_size);
 Error_Code insert_element_at_index(DynArray* dynamic_array, const size_t index, const void* data, const size_t data_size);

src/dynamic_array.c

@@ -4,10 +4,14 @@
 #include <stddef.h>
 #include <stdbool.h>
 
-/*
-Helper function
-Check whether provided DynArray-Pointer is pointing to a valid Dynamic-Array.
-*/
+/**
+ * Helper function -
+ * Check whether provided DynArray-Pointer is pointing to a valid Dynamic-Array.
+ * 
+ * @param dynamic_array `DynArray`-Pointer to the given dynamic-array.
+ * 
+ * @return `Error_Code` - `NO_ERROR` on success; otherwise another `Error_Code`.
+ */
 Error_Code check_dyn_array(const DynArray* dynamic_array) {
     if (dynamic_array == NULL || (dynamic_array->head_ptr == NULL && dynamic_array->tail_ptr != NULL)
         || (dynamic_array->head_ptr != NULL && dynamic_array->tail_ptr == NULL)) {
@@ -27,11 +31,19 @@ Error_Code check_dyn_array(const DynArray* dynamic_array) {
     return NO_ERROR;
 }
 
-/*
-Initialize a new dynamic-array.
-
-Set `dynamic_array->length` to 0.
-*/
+/**
+ * Initialize a new dynamic-array.
+ * 
+ * @param dynamic_array `DynArray`-Pointer to the new dynamic-array.
+ * 
+ * @return `Error_Code` - `NO_ERROR` on success; otherwise another `Error_Code`.
+ * @note 
+ *  - Sets the `dynamic_array->length` to 1
+ * 
+ *  - Sets the `dynamic_array->head_ptr` to `NULL`
+ * 
+ *  - Sets the `dynamic_array->tail_ptr` to `NULL`
+ */
 Error_Code init_dyn_array(DynArray* dynamic_array) {
     if (dynamic_array == NULL) {
         //
@@ -91,14 +103,18 @@ DynArrayNode* create_new_dyn_array_node(const void* data, const size_t data_size
     return new_node;
 }
 
-/*
-Helper function
-Add first element to dynamic-array.
-This function assumes, that the given dynamic-array has already been checked with `check_dyn_array` and that the given
-`data-ptr` and `data_size` are also valid.
-
-Set `dynamic_array->length` to 1.
-*/
+/**
+ * Helper function -
+ * Add first element to dynamic-array.
+ * 
+ * @param dynamic_array `DynArray`-Pointer to a given dynamic-array.
+ * @param data The `void`-Pointer to the data that should be stored at the new element.
+ * @param data_size Size in Bytes of the given data.
+ * 
+ * @return `Error_Code` - `NO_ERROR` on success; otherwise another `Error_Code`.
+ * @note This function assumes, that the given dynamic-array has already been checked with `check_dyn_array` and that the given
+`data-ptr` and `data_size` are also valid. This function sets the `dynamic_array->length` to 1.
+ */
 Error_Code add_first_element_to_dyn_array(DynArray* dynamic_array, const void* data, const size_t data_size) {
     DynArrayNode* first_node = create_new_dyn_array_node(data, data_size);
     if (first_node == NULL) {
@@ -117,11 +133,16 @@ Error_Code add_first_element_to_dyn_array(DynArray* dynamic_array, const void* d
     return NO_ERROR;
 }
 
-/*
-Append element to dynamic-array.
-
-Increases `dynamic_array->length` by 1.
-*/
+/**
+ * Append element to dynamic-array.
+ * 
+ * @param dynamic_array `DynArray`-Pointer to a given dynamic-array.
+ * @param data The `void`-Pointer to the data that should be stored at the new element.
+ * @param data_size Size in Bytes of the given data.
+ * 
+ * @return `Error_Code` - `NO_ERROR` on success; otherwise another `Error_Code`.
+ * @note Increases `dynamic_array->length` by 1.
+ */
 Error_Code append_element_to_dyn_array(DynArray* dynamic_array, const void* data, const size_t data_size) {
     if (check_dyn_array(dynamic_array) != NO_ERROR) {
         //
@@ -179,10 +200,13 @@ Error_Code append_element_to_dyn_array(DynArray* dynamic_array, const void* data
     return NO_ERROR;
 }
 
-/*
-Get and Return last element of dynamic-array.
-Returns 'NULL`-ptr if empty or an error occured.
-*/
+/**
+ * Get last element of dynamic-array.
+ * 
+ * @param dynamic_array `DynArray`-Pointer to a given dynamic-array.
+ * 
+ * @return `void*` - `void`-Pointer to the data on success; otherwise `NULL`.
+ */
 void* get_last(const DynArray* dynamic_array) {
     if (check_dyn_array(dynamic_array) != NO_ERROR) {
         //
@@ -199,10 +223,13 @@ void* get_last(const DynArray* dynamic_array) {
     return dynamic_array->tail_ptr->data;
 }
 
-/*
-Get and Return first element of dynamic-array.
-Returns 'NULL`-ptr if empty or an error occured.
-*/
+/**
+ * Get first element of dynamic-array.
+ * 
+ * @param dynamic_array `DynArray`-Pointer to a given dynamic-array.
+ * 
+ * @return `void*` - `void`-Pointer to the data on success; otherwise `NULL`.
+ */
 void* get_first(const DynArray* dynamic_array) {
     if (check_dyn_array(dynamic_array) != NO_ERROR) {
         //
@@ -219,35 +246,47 @@ void* get_first(const DynArray* dynamic_array) {
     return dynamic_array->head_ptr->data;
 }
 
-/*
-Get amount of elements in dynamic-array by iterating through whole dynamic-array.
-Boolean indicates whether an error occured or the given dynamic-array is invalid.
-*/
-bool get_len(const DynArray* dynamic_array, size_t* len) {
+/**
+ * Get amount of elements in dynamic-array by iterating through whole dynamic-array.
+ * 
+ * @param dynamic_array `DynArray`-Pointer to a given dynamic-array.
+ * @param len `size_t`-Pointer to the value - where to store the counted value.
+ * 
+ * @return `Error_Code` - `NO_ERROR` on success; otherwise another `Error_Code`.
+ * @note May become deprecated in the near future. Please use `dynamic_array->length` instead.
+ */
+Error_Code get_len(const DynArray* dynamic_array, size_t* len) {
     if (check_dyn_array(dynamic_array) != NO_ERROR) {
         //
         // Given dynamic-array is invalid
-        return false;
+        return INVALID_ARRAY_ERROR;
     }
     //
     if (len == NULL) {
         //
         // Given len-ptr is the NULL-ptr
-        return false;
+        return NULL_PTR_ERROR;
     }
     DynArrayNode* current_ptr = dynamic_array->head_ptr;
     *len = 0;
     while (current_ptr != NULL) {
         (*len)++;
         current_ptr = current_ptr->next_ptr;
     }
-    return true;
+    return NO_ERROR;
 }
 
-/*
-Copy the array’s elements individually into the dynamic-array.
-Uses `append_element_to_dyn_array` under the hood.
-*/
+/**
+ * Copy the elements of a static-array individually to the dynamic-array.
+ * 
+ * @param dynamic_array `DynArray`-Pointer to a given dynamic-array.
+ * @param static_array `void`-Pointer to the given static-array.
+ * @param static_array_elem_size Size of each individual element of the static-array.
+ * @param static_array_len Length of the static-array.
+ * 
+ * @return `DynArrayNode*` - `DynArrayNode`-Pointer to the element on success; otherwise `NULL`.
+ * @note Uses `append_element_to_dyn_array` under the hood.
+ */
 Error_Code append_static_array_elements_to_dyn_array(DynArray* dynamic_array, const void* static_array, const size_t static_array_elem_size, const size_t static_array_len) {
     if (check_dyn_array(dynamic_array) != NO_ERROR) {
         //
@@ -280,11 +319,14 @@ Error_Code append_static_array_elements_to_dyn_array(DynArray* dynamic_array, co
     return append_elem_error_code;
 }
 
-/*
-Get element-ptr of dynamic-array-Node by index.
-
-Return `NULL` if an error occurs.
-*/
+/**
+ * Get element-Pointer of dynamic-array-Node by index.
+ * 
+ * @param dynamic_array `DynArray`-Pointer to a given dynamic-array.
+ * @param index Index of the element at the dynamic-array.
+ * 
+ * @return `DynArrayNode*` - `DynArrayNode`-Pointer to the element on success; otherwise `NULL`.
+ */
 DynArrayNode* get_element_ptr_by_index(const DynArray* dynamic_array, const size_t index) {
     if (check_dyn_array(dynamic_array) != NO_ERROR) {
         //
@@ -341,11 +383,14 @@ DynArrayNode* get_element_ptr_by_index(const DynArray* dynamic_array, const size
     return current_ptr;
 }
 
-/*
-Get element of dynamic-array by index.
-
-Return `NULL`-ptr if an error occurs.
-*/
+/**
+ * Get element of dynamic-array by index.
+ * 
+ * @param dynamic_array `DynArray`-Pointer to a given dynamic-array.
+ * @param index Index of the element at the dynamic-array.
+ * 
+ * @return `void*` - `void`-Pointer to the data on success; otherwise `NULL`.
+ */
 void* get_element_by_index(const DynArray* dynamic_array, const size_t index) {
     DynArrayNode* current_ptr = get_element_ptr_by_index(dynamic_array, index);
     if (current_ptr == NULL) {
@@ -354,26 +399,29 @@ void* get_element_by_index(const DynArray* dynamic_array, const size_t index) {
     return current_ptr->data;
 }
 
-/*
-Append elements of dynamic-array `b` to dynamic-array `a`.
-Uses `append_element_to_dyn_array` under the hood.
-*/
-bool append_dyn_arrays_inplace(DynArray* a, const DynArray* b) {
+/**
+ * Append elements of dynamic-array `b` to dynamic-array `a`.
+ * 
+ * @param a `DynArray`-Pointer to the given DESTINATION dynamic-array `A`.
+ * @param b `DynArray`-Pointer to the given SOURCE dynamic-array `B`.
+ * 
+ * @return `Error_Code` - `NO_ERROR` on success; otherwise another `Error_Code`.
+ * @note Uses `append_element_to_dyn_array` under the hood.
+ */
+Error_Code append_dyn_arrays_inplace(DynArray* a, const DynArray* b) {
     DynArray* dyn_array_a = a;
     const DynArray* dyn_array_b = b;
     //
     // Check both dynamic-arrays
     if (check_dyn_array(dyn_array_a) != NO_ERROR || check_dyn_array(dyn_array_b) != NO_ERROR) {
         //
         // One or both of the given dynamic-arrays are invalid
-        // INVALID_ARRAY_ERROR
-        return false;
+        return INVALID_ARRAY_ERROR;
     }
     if (dyn_array_b->length == 0) {
         //
         // Dynamic-array `b` is empty, nothing to append
-        // NO_ERROR
-        return true;
+        return NO_ERROR;
     }
     //
     // Iterate through dynamic-array `b`
@@ -384,18 +432,23 @@ bool append_dyn_arrays_inplace(DynArray* a, const DynArray* b) {
         if (append_elem_error_code != NO_ERROR) {
             //
             // Appending element went wrong
-            return false;
+            return append_elem_error_code;
         }
         current_b_ptr = current_b_ptr->next_ptr;
     }
     //
-    // NO_ERROR
-    return true;
+    return NO_ERROR;
 }
 
-/*
-Swap position of elements by its indices.
-*/
+/**
+ * Swap position of elements by its indices.
+ * 
+ * @param dynamic_array `DynArray`-Pointer to the given existing dynamic-array.
+ * @param index_a The index of element-A
+ * @param index_b The index of element-B
+ * 
+ * @return `Error_Code` - `NO_ERROR` on success; otherwise another `Error_Code`.
+ */
 Error_Code swap_elements_by_indices(DynArray* dynamic_array, const size_t index_a, const size_t index_b) {
     if (check_dyn_array(dynamic_array) != NO_ERROR) {
         //
@@ -529,10 +582,17 @@ Error_Code swap_elements_by_indices(DynArray* dynamic_array, const size_t index_
     return NO_ERROR;
 }
 
-/*
-Replace an element-data by its index inplace.
-Stored element-data gets deleted and new element-data gets stored at the given index.
-*/
+/**
+ * Replace an element-data by its index inplace.
+ * 
+ * @param dynamic_array `DynArray`-Pointer to the given existing dynamic-array.
+ * @param index The index where the element should be replaced at.
+ * @param data The `void`-Pointer to the new data that should be stored at the element.
+ * @param data_size Size in Bytes of the new given data.
+ * 
+ * @return `Error_Code` - `NO_ERROR` on success; otherwise another `Error_Code`.
+ * @note Stored element-data gets deleted and new element-data gets stored at the given index.
+ */
 Error_Code replace_element_by_index(DynArray* dynamic_array, const size_t index, const void* data, const size_t data_size) {
     if (check_dyn_array(dynamic_array) != NO_ERROR) {
         //
@@ -588,12 +648,13 @@ Error_Code replace_element_by_index(DynArray* dynamic_array, const size_t index,
 /**
  * Insert an element at the given index.
  * 
- * @param dynamic_array `DynArray`-Pointer to the given exsiting dynamic-array.
- * @param index The given where the new element should be inserted at.
+ * @param dynamic_array `DynArray`-Pointer to the given existing dynamic-array.
+ * @param index The element-index where the new element should be inserted at.
  * @param data The `void`-Pointer to the data that should be stored at the new element.
  * @param data_size Size in Bytes of the given data.
  * 
  * @return `Error_Code` - `NO_ERROR` on success; otherwise another `Error_Code`.
+ * @note Increases `dynamic_array->length` by 1.
  */
 Error_Code insert_element_at_index(DynArray* dynamic_array, const size_t index, const void* data, const size_t data_size) {
     if (check_dyn_array(dynamic_array) != NO_ERROR) {
@@ -667,9 +728,13 @@ Error_Code insert_element_at_index(DynArray* dynamic_array, const size_t index,
     return NO_ERROR;
 }
 
-/*
-Deallocate space of all elments in a dynamic-array.
-*/
+/**
+ * Deallocate space of all elments in a dynamic-array.
+ * 
+ * @param dynamic_array `DynArray`-Pointer to the given existing dynamic-array.
+ * 
+ * @return `Error_Code` - `NO_ERROR` on success; otherwise another `Error_Code`.
+ */
 Error_Code clear_dyn_array(DynArray* dynamic_array) {
     if (check_dyn_array(dynamic_array) != NO_ERROR) {
         //