Merge pull request #118 from saxbophone/josh/102-add-assertions

Add Assertions

Author: saxbophone

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

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,11 +60,21 @@ 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};
     // the amount of space needed is the sum of all line lengths + 1 for end
@@ -91,15 +112,22 @@ sxbp_status_t sxbp_spiral_points(
 }
 
 /*
- * 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};
     // the amount of space needed is the sum of all line lengths + 1 for end

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,8 +76,15 @@ 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};
     // plot co-ords of spiral into it's cache
@@ -108,6 +121,8 @@ 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]);
             }
+            // now we need to free() the top-level array
+            free(image->pixels);
             result.location = SXBP_DEBUG;
             result.diagnostic = SXBP_MALLOC_REFUSED;
             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);
 

saxbospiral/serialise.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 <stdint.h>
 #include <stdio.h>
 #include <stdlib.h>
@@ -38,28 +39,49 @@ extern "C"{
 const size_t SXBP_FILE_HEADER_SIZE = 37;
 const size_t SXBP_LINE_T_PACK_SIZE = 4;
 
-// loads a 64-bit unsigned integer from buffer starting at given index
+/*
+ * loads a 64-bit unsigned integer from buffer starting at given index
+ *
+ * Asserts:
+ * - That buffer->bytes is not NULL
+ */
 static uint64_t load_uint64_t(sxbp_buffer_t* buffer, size_t start_index) {
+    // preconditional assertions
+    assert(buffer->bytes != NULL);
     uint64_t value = 0;
     for(size_t i = 0; i < 8; i++) {
         value |= (buffer->bytes[start_index + i]) << (8 * (7 - i));
     }
     return value;
 }
 
-// loads a 32-bit unsigned integer from buffer starting at given index
+/*
+ * loads a 32-bit unsigned integer from buffer starting at given index
+ *
+ * Asserts:
+ * - That buffer->bytes is not NULL
+ */
 static uint32_t load_uint32_t(sxbp_buffer_t* buffer, size_t start_index) {
+    // preconditional assertions
+    assert(buffer->bytes != NULL);
     uint32_t value = 0;
     for(size_t i = 0; i < 4; i++) {
         value |= (buffer->bytes[start_index + i]) << (8 * (3 - i));
     }
     return value;
 }
 
-// dumps a 64-bit unsigned integer of value to buffer at given index
+/*
+ * dumps a 64-bit unsigned integer of value to buffer at given index
+ *
+ * Asserts:
+ * - That buffer->bytes is not NULL
+ */
 static void dump_uint64_t(
     uint64_t value, sxbp_buffer_t* buffer, size_t start_index
 ) {
+    // preconditional assertions
+    assert(buffer->bytes != NULL);
     for(uint8_t i = 0; i < 8; i++) {
         uint8_t shift = (8 * (7 - i));
         buffer->bytes[start_index + i] = (uint8_t)(
@@ -68,10 +90,17 @@ static void dump_uint64_t(
     }
 }
 
-// dumps a 32-bit unsigned integer of value to buffer at given index
+/*
+ * dumps a 32-bit unsigned integer of value to buffer at given index
+ *
+ * Asserts:
+ * - That buffer->bytes is not NULL
+ */
 static void dump_uint32_t(
     uint32_t value, sxbp_buffer_t* buffer, size_t start_index
 ) {
+    // preconditional assertions
+    assert(buffer->bytes != NULL);
     for(uint8_t i = 0; i < 4; i++) {
         uint8_t shift = (8 * (3 - i));
         buffer->bytes[start_index + i] = (uint8_t)(
@@ -86,10 +115,17 @@ static void dump_uint32_t(
  * returns a serialise_result_t struct, which will contain information about
  * whether the operation was successful or not and information about what went
  * wrong if it was not successful
+ *
+ * Asserts:
+ * - That buffer.bytes is not NULL
+ * - That spiral->lines is NULL
  */
 sxbp_serialise_result_t sxbp_load_spiral(
     sxbp_buffer_t buffer, sxbp_spiral_t* spiral
 ) {
+    // preconditional assertions
+    assert(buffer.bytes != NULL);
+    assert(spiral->lines == NULL);
     sxbp_serialise_result_t result; // build struct for returning success / failure
     // first, if header is too small for header + 1 line, then return early
     if(buffer.size < SXBP_FILE_HEADER_SIZE + SXBP_LINE_T_PACK_SIZE) {
@@ -177,10 +213,17 @@ sxbp_serialise_result_t sxbp_load_spiral(
  * returns a serialise_result_t struct, which will contain information about
  * whether the operation was successful or not and information about what went
  * wrong if it was not successful
+ *
+ * Asserts:
+ * - That spiral.lines is not NULL
+ * - That buffer->bytes is NULL
  */
 sxbp_serialise_result_t sxbp_dump_spiral(
     sxbp_spiral_t spiral, sxbp_buffer_t* buffer
 ) {
+    // preconditional assertions
+    assert(buffer->bytes == NULL);
+    assert(spiral.lines != NULL);
     sxbp_serialise_result_t result; // build struct for returning success / failure
     // populate buffer struct, base size on header + spiral size
     buffer->size = (SXBP_FILE_HEADER_SIZE + (SXBP_LINE_T_PACK_SIZE * spiral.size));

saxbospiral/serialise.h

@@ -61,6 +61,10 @@ extern const size_t SXBP_LINE_T_PACK_SIZE;
  * returns a serialise_result_t struct, which will contain information about
  * whether the operation was successful or not and information about what went
  * wrong if it was not successful
+ *
+ * Asserts:
+ * - That buffer.bytes is not NULL
+ * - That spiral->lines is NULL
  */
 sxbp_serialise_result_t sxbp_load_spiral(
     sxbp_buffer_t buffer, sxbp_spiral_t* spiral
@@ -72,6 +76,10 @@ sxbp_serialise_result_t sxbp_load_spiral(
  * returns a serialise_result_t struct, which will contain information about
  * whether the operation was successful or not and information about what went
  * wrong if it was not successful
+ *
+ * Asserts:
+ * - That spiral.lines is not NULL
+ * - That buffer->bytes is NULL
  */
 sxbp_serialise_result_t sxbp_dump_spiral(
     sxbp_spiral_t spiral, sxbp_buffer_t* buffer