Merge pull request #99 from saxbophone/develop

version 0.18.0

Author: saxbophone

CMakeLists.txt

@@ -1,7 +1,7 @@
 # begin basic metadata
 cmake_minimum_required(VERSION 3.0)
 
-project(libsaxbospiral VERSION 0.17.1 LANGUAGES C)
+project(libsaxbospiral VERSION 0.18.0 LANGUAGES C)
 set(CMAKE_C_STANDARD 99)
 set(CMAKE_C_STANDARD_REQUIRED ON)
 set(

saxbospiral/solve.c

@@ -240,23 +240,28 @@ sxbp_status_t sxbp_resize_spiral(
  * given a pointer to a spiral spiral for which the length of all its lines are
  * not yet known, a perfection threshold (-1 for no perfection, or otherwise
  * the maximmum line length at which to allow aggressive optimisation), the
- * index of the highest line to plot to and a pointer to a callback function,
+ * index of the highest line to plot to, a pointer to a callback function and
+ * a void pointer to a user-defined data struct for use with the callback,
  * calculate the length needed for each line in the spiral up to this index
  * (to avoid line overlap) and store these in a the spiral struct that is
  * pointed to by the pointer. If the spiral has some lines already solved, the
  * algorithm will start at the next unsolved line.
- * the function pointer can be NULL, if it is not then it will be called every
- * time a new line of the spiral is solved. The function should be of return
- * type void and take three arguments: a pointer to a spiral_t struct, an
- * integer specifying the index of the latest solved line and an integer
- * specifying the index of the highest line that will be solved.
+ * the function pointer and the user data pointer can be NULL.
+ * If the function pointer is not NULL, then it will be called every time a new
+ * line of the spiral is solved. The function should be of return type void and
+ * take four arguments: a pointer to a spiral_t struct, an integer specifying
+ * the index of the latest solved line, an integer specifying the index of the
+ * highest line that will be solved and a void pointer used for accessing the
+ * user data.
  * returns a status struct (used for error information)
  */
 sxbp_status_t sxbp_plot_spiral(
     sxbp_spiral_t* spiral, int perfection_threshold, uint64_t max_line,
     void(* progress_callback)(
-        sxbp_spiral_t* spiral, uint64_t latest_line, uint64_t target_line
-    )
+        sxbp_spiral_t* spiral, uint64_t latest_line, uint64_t target_line,
+        void* progress_callback_user_data
+    ),
+    void* progress_callback_user_data
 ) {
     // set up result status
     sxbp_status_t result = {{0, 0, 0}, 0};
@@ -271,7 +276,7 @@ sxbp_status_t sxbp_plot_spiral(
         }
         // call callback if given
         if(progress_callback != NULL) {
-            progress_callback(spiral, i, max_index);
+            progress_callback(spiral, i, max_index, progress_callback_user_data);
         }
     }
     // all ok

saxbospiral/solve.h

@@ -27,23 +27,28 @@ sxbp_status_t sxbp_resize_spiral(
  * given a pointer to a spiral spiral for which the length of all its lines are
  * not yet known, a perfection threshold (-1 for no perfection, or otherwise
  * the maximmum line length at which to allow aggressive optimisation), the
- * index of the highest line to plot to and a pointer to a callback function,
+ * index of the highest line to plot to, a pointer to a callback function and
+ * a void pointer to a user-defined data struct for use with the callback,
  * calculate the length needed for each line in the spiral up to this index
  * (to avoid line overlap) and store these in a the spiral struct that is
  * pointed to by the pointer. If the spiral has some lines already solved, the
  * algorithm will start at the next unsolved line.
- * the function pointer can be NULL, if it is not then it will be called every
- * time a new line of the spiral is solved. The function should be of return
- * type void and take three arguments: a pointer to a spiral_t struct, an
- * integer specifying the index of the latest solved line and an integer
- * specifying the index of the highest line that will be solved.
+ * the function pointer and the user data pointer can be NULL.
+ * If the function pointer is not NULL, then it will be called every time a new
+ * line of the spiral is solved. The function should be of return type void and
+ * take four arguments: a pointer to a spiral_t struct, an integer specifying
+ * the index of the latest solved line, an integer specifying the index of the
+ * highest line that will be solved and a void pointer used for accessing the
+ * user data.
  * returns a status struct (used for error information)
  */
 sxbp_status_t sxbp_plot_spiral(
     sxbp_spiral_t* spiral, int perfection_threshold, uint64_t max_line,
     void(* progress_callback)(
-        sxbp_spiral_t* spiral, uint64_t latest_line, uint64_t target_line
-    )
+        sxbp_spiral_t* spiral, uint64_t latest_line, uint64_t target_line,
+        void* progress_callback_user_data
+    ),
+    void* progress_callback_user_data
 );
 
 #ifdef __cplusplus

tests.c

@@ -205,7 +205,7 @@ bool test_sxbp_plot_spiral() {
     }
 
     // call plot_spiral on spiral
-    sxbp_plot_spiral(&spiral, 1, 16, NULL);
+    sxbp_plot_spiral(&spiral, 1, 16, NULL, NULL);
 
     // check solved count
     if(spiral.solved_count != expected.solved_count) {
@@ -249,7 +249,7 @@ bool test_sxbp_plot_spiral_partial() {
     }
 
     // call plot_spiral on spiral, with instruction to only plot up to line 9
-    sxbp_plot_spiral(&spiral, 1, 9, NULL);
+    sxbp_plot_spiral(&spiral, 1, 9, NULL, NULL);
 
     // check solved count
     if(spiral.solved_count != expected.solved_count) {
@@ -270,6 +270,58 @@ bool test_sxbp_plot_spiral_partial() {
     return result;
 }
 
+/*
+ * disable GCC warning about the unused parameters as this function by necessity
+ * requires these arguments in its signature, but it needn't use all of them.
+ */
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wunused-parameter"
+// test callback for next test case
+static void test_progress_callback(
+    sxbp_spiral_t* spiral, uint64_t latest_line, uint64_t target_line,
+    void* progress_callback_user_data
+) {
+    // cast user data from void pointer to uint16_t pointer, deref and multiply
+    *(uint16_t*)progress_callback_user_data *= 13;
+}
+// re-enable all warnings
+#pragma GCC diagnostic pop
+
+bool test_sxbp_plot_spiral_progress_callback() {
+    // success / failure variable
+    bool result = true;
+    // build input structs
+    sxbp_spiral_t spiral = { .size = 16, };
+    spiral.lines = calloc(sizeof(sxbp_line_t), 16);
+    sxbp_direction_t directions[16] = {
+        SXBP_UP, SXBP_LEFT, SXBP_DOWN, SXBP_LEFT, SXBP_DOWN, SXBP_RIGHT,
+        SXBP_DOWN, SXBP_RIGHT, SXBP_UP, SXBP_LEFT, SXBP_UP, SXBP_RIGHT,
+        SXBP_DOWN, SXBP_RIGHT, SXBP_UP, SXBP_LEFT,
+    };
+    for(uint8_t i = 0; i < 16; i++) {
+        spiral.lines[i].direction = directions[i];
+        spiral.lines[i].length = 0;
+    }
+    // create user data variable
+    uint16_t user_data = 17;
+
+    /*
+     * call plot_spiral on spiral, with instruction to only plot up to line 1
+     * supply our progress_callback function and a user data variable
+     */
+    sxbp_plot_spiral(&spiral, 1, 1, test_progress_callback, (void*)&user_data);
+
+    // user data variable should have been set to 221 (17 * 13) by callback
+    if(user_data != 221) {
+        result = false;
+    }
+
+    // free memory
+    free(spiral.lines);
+
+    return result;
+}
+
 bool test_sxbp_load_spiral() {
     // success / failure variable
     bool result = true;
@@ -599,6 +651,10 @@ int main() {
     result = run_test_case(
         result, test_sxbp_plot_spiral_partial, "test_sxbp_plot_spiral_partial"
     );
+    result = run_test_case(
+        result, test_sxbp_plot_spiral_progress_callback,
+        "test_sxbp_plot_spiral_progress_callback"
+    );
     result = run_test_case(
         result, test_sxbp_load_spiral, "test_sxbp_load_spiral"
     );