Merge pull request #122 from saxbophone/develop

v0.20.0 - Cleanup and Improvements

CMakeLists.txt

@@ -23,7 +23,7 @@
 # begin basic metadata
 cmake_minimum_required(VERSION 3.0)
 
-project(libsaxbospiral VERSION 0.19.3 LANGUAGES C)
+project(libsaxbospiral VERSION 0.20.0 LANGUAGES C)
 
 # set default C standard to use (C99)
 set(SAXBOSPIRAL_C_STANDARD "99")
@@ -50,7 +50,9 @@ if(CMAKE_SIZEOF_VOID_P LESS 8)
     message(
         WARNING
         "It looks like this system's architecture is not at least 64-bit.\n"
-        "libsaxbospiral requires a system with an architecture of at least 64 bits!")
+        "libsaxbospiral requires a system with an architecture of at least 64 bits!\n"
+        "We'll continue trying to compile anyway, be sure to run the unit tests after."
+    )
 endif()
 
 # pass in version of library as preprocessor definitions
@@ -123,15 +125,37 @@ install(
     LIBRARY DESTINATION lib
     RUNTIME DESTINATION bin
 )
-# Install main library header files
+
+# Generate rough (nearest major) version-dependent header installation folder
+set(
+    LIBSAXBOSPIRAL_ROUGH_HEADER_DESTINATION
+    "saxbospiral-${PROJECT_VERSION_MAJOR}"
+)
+# Generate precise (major and minor) version-dependent header installation folder
+set(
+    LIBSAXBOSPIRAL_PRECISE_HEADER_DESTINATION
+    "saxbospiral-${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR}"
+)
+
+# Install main library header files, both to rough and precise install locations
+install(
+    FILES ${LIB_SAXBOSPIRAL_HEADERS}
+    DESTINATION "include/${LIBSAXBOSPIRAL_ROUGH_HEADER_DESTINATION}"
+)
+# Install render_backends header files
+install(
+    FILES ${LIB_SAXBOSPIRAL_RENDER_BACKENDS_HEADERS}
+    DESTINATION "include/${LIBSAXBOSPIRAL_ROUGH_HEADER_DESTINATION}/render_backends"
+)
+
 install(
     FILES ${LIB_SAXBOSPIRAL_HEADERS}
-    DESTINATION include/saxbospiral
+    DESTINATION "include/${LIBSAXBOSPIRAL_PRECISE_HEADER_DESTINATION}"
 )
 # Install render_backends header files
 install(
     FILES ${LIB_SAXBOSPIRAL_RENDER_BACKENDS_HEADERS}
-    DESTINATION include/saxbospiral/render_backends
+    DESTINATION "include/${LIBSAXBOSPIRAL_PRECISE_HEADER_DESTINATION}/render_backends"
 )
 
 enable_testing()

saxbospiral/initialise.c

@@ -20,6 +20,7 @@
  * You should have received a copy of the GNU Affero General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+#include <assert.h>
 #include <stdint.h>
 #include <stdlib.h>
 
@@ -54,8 +55,14 @@ sxbp_spiral_t sxbp_blank_spiral() {
  * this converts the 0s and 1s in the data into UP, LEFT, DOWN, RIGHT
  * instructions which are then used to build the pattern.
  * returns a status_t struct with error information (if needed)
+ *
+ * Asserts:
+ * - That the spiral struct pointed to has its pointer attributes set to NULL
  */
 sxbp_status_t sxbp_init_spiral(sxbp_buffer_t buffer, sxbp_spiral_t* spiral) {
+    // preconditional assertions
+    assert(spiral->lines == NULL);
+    assert(spiral->co_ord_cache.co_ords.items == NULL);
     // result status object
     sxbp_status_t result;
     // number of lines is number of bits of the data, + 1 for the first UP line
@@ -67,8 +74,7 @@ sxbp_status_t sxbp_init_spiral(sxbp_buffer_t buffer, sxbp_spiral_t* spiral) {
     spiral->lines = calloc(sizeof(sxbp_line_t), line_count);
     // check for memory allocation failure
     if(spiral->lines == NULL) {
-        result.location = SXBP_DEBUG;
-        result.diagnostic = SXBP_MALLOC_REFUSED;
+        result = SXBP_MALLOC_REFUSED;
         return result;
     }
     // First line is always an UP line - this is for orientation purposes
@@ -98,7 +104,7 @@ sxbp_status_t sxbp_init_spiral(sxbp_buffer_t buffer, sxbp_spiral_t* spiral) {
         }
     }
     // all ok
-    result.diagnostic = SXBP_OPERATION_OK;
+    result = SXBP_OPERATION_OK;
     return result;
 }
 

saxbospiral/initialise.h

@@ -49,6 +49,9 @@ sxbp_spiral_t sxbp_blank_spiral();
  * this converts the 0s and 1s in the data into UP, LEFT, DOWN, RIGHT
  * instructions which are then used to build the pattern.
  * returns a status_t struct with error information (if needed)
+ *
+ * Asserts:
+ * - That the spiral struct pointed to has its pointer attributes set to NULL
  */
 sxbp_status_t sxbp_init_spiral(sxbp_buffer_t buffer, sxbp_spiral_t* spiral);
 

saxbospiral/plot.c

@@ -21,6 +21,7 @@
  * You should have received a copy of the GNU Affero General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+#include <assert.h>
 #include <stdlib.h>
 
 #include "saxbospiral.h"
@@ -31,8 +32,18 @@
 extern "C"{
 #endif
 
-// returns the sum of all line lengths within the given indexes
+/*
+ * returns the sum of all line lengths within the given indexes
+ *
+ * Asserts:
+ * - That start and end indexes are less than or equal to the spiral size
+ * - That spiral.lines is not NULL
+ */
 size_t sxbp_sum_lines(sxbp_spiral_t spiral, size_t start, size_t end) {
+    // preconditional assertions
+    assert(start <= spiral.size);
+    assert(end <= spiral.size);
+    assert(spiral.lines != NULL);
     size_t size = 0;
     for(size_t i = start; i < end; i++) {
         size += spiral.lines[i].length;
@@ -49,22 +60,31 @@ size_t sxbp_sum_lines(sxbp_spiral_t spiral, size_t start, size_t end) {
  * each line segment is only one unit long, meaning multiple ones are needed for
  * lines longer than one unit.
  * returns a status struct with error information (if any)
+ *
+ * Asserts:
+ * - That the output struct's items pointer is NULL
+ * - That start and end indexes are less than or equal to the spiral size
+ * - That spiral.lines is not NULL
  */
 sxbp_status_t sxbp_spiral_points(
     sxbp_spiral_t spiral, sxbp_co_ord_array_t* output,
     sxbp_co_ord_t start_point, size_t start, size_t end
 ) {
+    // preconditional assertions
+    assert(output->items == NULL);
+    assert(start <= spiral.size);
+    assert(end <= spiral.size);
+    assert(spiral.lines != NULL);
     // prepare result status
-    sxbp_status_t result = {{0, 0, 0}, 0};
+    sxbp_status_t result;
     // the amount of space needed is the sum of all line lengths + 1 for end
     size_t size = sxbp_sum_lines(spiral, start, end) + 1;
     // allocate memory
     output->items = calloc(sizeof(sxbp_co_ord_t), size);
     // catch malloc error
     if(output->items == NULL) {
         // set error information then early return
-        result.location = SXBP_DEBUG;
-        result.diagnostic = SXBP_MALLOC_REFUSED;
+        result = SXBP_MALLOC_REFUSED;
         return result;
     }
     output->size = size;
@@ -86,22 +106,29 @@ sxbp_status_t sxbp_spiral_points(
         }
     }
     // all good
-    result.diagnostic = SXBP_OPERATION_OK;
+    result = SXBP_OPERATION_OK;
     return result;
 }
 
 /*
- * given a pointer to a spiral struct an limit, which is the index of the last
+ * given a pointer to a spiral struct and limit, which is the index of the last
  * line to use, calculate and store the co-ordinates of all line segments that
  * would make up the spiral if the current lengths and directions were used.
  * each line segment is only one unit long, meaning multiple ones are needed for
  * lines longer than one unit. The co-ords are stored in the spiral's
  * co_ord_cache member and are re-used if they are still valid
  * returns a status struct with error information (if any)
+ *
+ * Asserts:
+ * - That spiral->lines is not NULL
+ * - That limit is less than or equal to spiral->size
  */
 sxbp_status_t sxbp_cache_spiral_points(sxbp_spiral_t* spiral, size_t limit) {
+    // preconditional assertions
+    assert(spiral->lines != NULL);
+    assert(limit <= spiral->size);
     // prepare result status
-    sxbp_status_t result = {{0, 0, 0}, 0};
+    sxbp_status_t result;
     // the amount of space needed is the sum of all line lengths + 1 for end
     size_t size = sxbp_sum_lines(*spiral, 0, limit) + 1;
     // allocate / reallocate memory
@@ -122,8 +149,7 @@ sxbp_status_t sxbp_cache_spiral_points(sxbp_spiral_t* spiral, size_t limit) {
     // catch malloc failure
     if(spiral->co_ord_cache.co_ords.items == NULL) {
         // set error information then early return
-        result.location = SXBP_DEBUG;
-        result.diagnostic = SXBP_MALLOC_REFUSED;
+        result = SXBP_MALLOC_REFUSED;
         return result;
     }
     spiral->co_ord_cache.co_ords.size = size;
@@ -152,7 +178,7 @@ sxbp_status_t sxbp_cache_spiral_points(sxbp_spiral_t* spiral, size_t limit) {
         *spiral, &missing, current, smallest, limit
     );
     // return errors from previous call if needed
-    if(calculate_result.diagnostic != SXBP_OPERATION_OK) {
+    if(calculate_result != SXBP_OPERATION_OK) {
         return calculate_result;
     }
     // add the missing co-ords to the cache
@@ -168,7 +194,7 @@ sxbp_status_t sxbp_cache_spiral_points(sxbp_spiral_t* spiral, size_t limit) {
         limit > spiral->co_ord_cache.validity
     ) ? limit : spiral->co_ord_cache.validity;
     // return ok
-    result.diagnostic = SXBP_OPERATION_OK;
+    result = SXBP_OPERATION_OK;
     return result;
 }
 

saxbospiral/plot.h

@@ -33,7 +33,13 @@
 extern "C"{
 #endif
 
-// returns the sum of all line lengths within the given indexes
+/*
+ * returns the sum of all line lengths within the given indexes
+ *
+ * Asserts:
+ * - That start and end indexes are less than or equal to the spiral size
+ * - That spiral.lines is not NULL
+ */
 size_t sxbp_sum_lines(sxbp_spiral_t spiral, size_t start, size_t end);
 
 /*
@@ -45,20 +51,29 @@ size_t sxbp_sum_lines(sxbp_spiral_t spiral, size_t start, size_t end);
  * each line segment is only one unit long, meaning multiple ones are needed for
  * lines longer than one unit.
  * returns a status struct with error information (if any)
+ *
+ * Asserts:
+ * - That the output struct's items pointer is NULL
+ * - That start and end indexes are less than or equal to the spiral size
+ * - That spiral.lines is not NULL
  */
 sxbp_status_t sxbp_spiral_points(
     sxbp_spiral_t spiral, sxbp_co_ord_array_t* output,
     sxbp_co_ord_t start_point, size_t start, size_t end
 );
 
 /*
- * given a pointer to a spiral struct an limit, which is the index of the last
+ * given a pointer to a spiral struct and limit, which is the index of the last
  * line to use, calculate and store the co-ordinates of all line segments that
  * would make up the spiral if the current lengths and directions were used.
  * each line segment is only one unit long, meaning multiple ones are needed for
- * lines longer than one unit. The co-ords are stored in the
- * spiral's co_ord_cache member and are re-used if they are still valid
+ * lines longer than one unit. The co-ords are stored in the spiral's
+ * co_ord_cache member and are re-used if they are still valid
  * returns a status struct with error information (if any)
+ *
+ * Asserts:
+ * - That spiral->lines is not NULL
+ * - That limit is less than or equal to spiral->size
  */
 sxbp_status_t sxbp_cache_spiral_points(sxbp_spiral_t* spiral, size_t limit);
 

saxbospiral/render.c

@@ -20,6 +20,7 @@
  * You should have received a copy of the GNU Affero General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+#include <assert.h>
 #include <stdbool.h>
 #include <stdint.h>
 #include <stdlib.h>
@@ -39,8 +40,13 @@ extern "C"{
  * corners of the square needed to contain the points.
  * NOTE: This should NEVER be called with a pointer to anything other than a
  * 2-item struct of type co_ord_t
+ *
+ * Asserts:
+ * - That spiral.co_ord_cache.co_ords.items is not NULL
  */
 static void get_bounds(sxbp_spiral_t spiral, sxbp_co_ord_t* bounds) {
+    // preconditional assertions
+    assert(spiral.co_ord_cache.co_ords.items != NULL);
     sxbp_tuple_item_t min_x = 0;
     sxbp_tuple_item_t min_y = 0;
     sxbp_tuple_item_t max_x = 0;
@@ -70,10 +76,17 @@ static void get_bounds(sxbp_spiral_t spiral, sxbp_co_ord_t* bounds) {
  * given a spiral struct and a pointer to a blank bitmap_t struct, writes data
  * representing a monochromatic image of the rendered spiral to the bitmap
  * returns a status struct with error information (if any)
+ *
+ * Asserts:
+ * - That image->pixels is NULL
+ * - That spiral.lines is not NULL
  */
 sxbp_status_t sxbp_render_spiral(sxbp_spiral_t spiral, sxbp_bitmap_t* image) {
+    // preconditional assertions
+    assert(image->pixels == NULL);
+    assert(spiral.lines != NULL);
     // create result status struct
-    sxbp_status_t result = {{0, 0, 0}, 0};
+    sxbp_status_t result;
     // plot co-ords of spiral into it's cache
     sxbp_cache_spiral_points(&spiral, spiral.size);
     // get the min and max bounds of the spiral's co-ords
@@ -96,8 +109,7 @@ sxbp_status_t sxbp_render_spiral(sxbp_spiral_t spiral, sxbp_bitmap_t* image) {
     image->pixels = malloc(image->width * sizeof(bool*));
     // check for malloc fail
     if(image->pixels == NULL) {
-        result.location = SXBP_DEBUG;
-        result.diagnostic = SXBP_MALLOC_REFUSED;
+        result = SXBP_MALLOC_REFUSED;
         return result;
     }
     for(size_t i = 0; i < image->width; i++) {
@@ -108,8 +120,9 @@ sxbp_status_t sxbp_render_spiral(sxbp_spiral_t spiral, sxbp_bitmap_t* image) {
             for(size_t j = i; j > 0; j--) {
                 free(image->pixels[j]);
             }
-            result.location = SXBP_DEBUG;
-            result.diagnostic = SXBP_MALLOC_REFUSED;
+            // now we need to free() the top-level array
+            free(image->pixels);
+            result = SXBP_MALLOC_REFUSED;
             return result;
         }
     }
@@ -140,7 +153,7 @@ sxbp_status_t sxbp_render_spiral(sxbp_spiral_t spiral, sxbp_bitmap_t* image) {
         }
     }
     // status ok
-    result.diagnostic = SXBP_OPERATION_OK;
+    result = SXBP_OPERATION_OK;
     return result;
 }
 

saxbospiral/render.h

@@ -43,6 +43,10 @@ typedef struct sxbp_bitmap_t {
  * given a spiral struct and a pointer to a blank bitmap_t struct, writes data
  * representing a monochromatic image of the rendered spiral to the bitmap
  * returns a status struct with error information (if any)
+ *
+ * Asserts:
+ * - That image->pixels is NULL
+ * - That spiral.lines is not NULL
  */
 sxbp_status_t sxbp_render_spiral(sxbp_spiral_t spiral, sxbp_bitmap_t* image);