Increase buffer capacity safely and handle overflow errors (#122)

This pull request refactors the buffer management system in
`src/buffer.c` and updates its corresponding tests. The changes improve
the clarity of function names, introduce new helper functions for
managing buffer capacity, and enhance error handling.

Replaced `buffer_increase_capacity` with `buffer_expand_if_needed`,
which dynamically adjusts buffer capacity based on required length.
Introduced new helper functions `buffer_resize`,
`buffer_expand_capacity`, and `buffer_has_capacity` for more modular
buffer operations. Improved error handling by using `exit(1)` for
critical failures.

Alternative to #118

Might close #103 
Might close #121

Author: marcoroth

src/buffer.c

@@ -10,7 +10,7 @@
 bool buffer_init(buffer_T* buffer) {
   buffer->capacity = 1024;
   buffer->length = 0;
-  buffer->value = nullable_safe_malloc(buffer->capacity * sizeof(char));
+  buffer->value = nullable_safe_malloc((buffer->capacity + 1) * sizeof(char));
 
   if (!buffer->value) {
     fprintf(stderr, "Error: Failed to initialize buffer with capacity of %zu.\n", buffer->capacity);
@@ -50,39 +50,73 @@ size_t buffer_sizeof(void) {
  * or null termination.
  *
  * @param buffer The buffer to increase capacity for
- * @param required_length The additional length needed beyond current buffer length
- * @return true if capacity is sufficient (either already or after reallocation),
- *         false if reallocation failed
+ * @param additional_capacity The additional length needed beyond current buffer capacity
+ * @return true if capacity was increased, false if reallocation failed
  */
-bool buffer_increase_capacity(buffer_T* buffer, const size_t required_length) {
-  if (SIZE_MAX - buffer->length < required_length) {
+bool buffer_increase_capacity(buffer_T* buffer, const size_t additional_capacity) {
+  if (additional_capacity + 1 >= SIZE_MAX) {
     fprintf(stderr, "Error: Buffer capacity would overflow system limits.\n");
-    return false;
+    exit(1);
   }
 
-  const size_t required_capacity = buffer->length + required_length;
-
-  if (buffer->capacity >= required_capacity) { return true; }
+  const size_t new_capacity = buffer->capacity + additional_capacity;
 
-  size_t new_capacity;
-  if (required_capacity > SIZE_MAX / 2) {
-    new_capacity = required_capacity + 1024;
+  return buffer_resize(buffer, new_capacity);
+}
 
-    if (new_capacity < required_capacity) { new_capacity = SIZE_MAX; }
-  } else {
-    new_capacity = required_capacity * 2;
+/**
+ * Resizes the capacity of the buffer to the specified new capacity.
+ *
+ * @param buffer The buffer to resize
+ * @param new_capacity The new capacity to resize the buffer to
+ * @return true if capacity was resized, false if reallocation failed
+ */
+bool buffer_resize(buffer_T* buffer, const size_t new_capacity) {
+  if (new_capacity + 1 >= SIZE_MAX) {
+    fprintf(stderr, "Error: Buffer capacity would overflow system limits.\n");
+    exit(1);
   }
 
-  char* new_value = safe_realloc(buffer->value, new_capacity);
+  char* new_value = nullable_safe_realloc(buffer->value, new_capacity + 1);
 
-  if (unlikely(new_value == NULL)) { return false; }
+  if (unlikely(new_value == NULL)) {
+    fprintf(stderr, "Error: Failed to resize buffer to %zu.\n", new_capacity);
+    exit(1);
+  }
 
   buffer->value = new_value;
   buffer->capacity = new_capacity;
 
   return true;
 }
 
+/**
+ * Expands the capacity of the buffer by doubling its current capacity.
+ * This function is a convenience function that calls buffer_increase_capacity
+ * with a factor of 2.
+ *
+ * @param buffer The buffer to expand capacity for
+ * @return true if capacity was increased, false if reallocation failed
+ */
+bool buffer_expand_capacity(buffer_T* buffer) {
+  return buffer_resize(buffer, buffer->capacity * 2);
+}
+
+/**
+ * Expands the capacity of the buffer if needed to accommodate additional content.
+ * This function is a convenience function that calls buffer_has_capacity and
+ * buffer_expand_capacity.
+ *
+ * @param buffer The buffer to expand capacity for
+ * @param required_length The additional length needed beyond current buffer capacity
+ * @return true if capacity was increased, false if reallocation failed
+ */
+bool buffer_expand_if_needed(buffer_T* buffer, const size_t required_length) {
+  if (buffer_has_capacity(buffer, required_length)) { return true; }
+
+  return buffer_resize(buffer, buffer->capacity + (required_length * 2));
+}
+
 /**
  * Appends a null-terminated string to the buffer.
  * @note This function requires that 'text' is a properly null-terminated string.
@@ -99,7 +133,7 @@ void buffer_append(buffer_T* buffer, const char* text) {
 
   size_t text_length = strlen(text);
 
-  if (!buffer_increase_capacity(buffer, text_length)) { return; }
+  if (!buffer_expand_if_needed(buffer, text_length)) { return; }
 
   memcpy(buffer->value + buffer->length, text, text_length);
   buffer->length += text_length;
@@ -120,7 +154,7 @@ void buffer_append(buffer_T* buffer, const char* text) {
  */
 void buffer_append_with_length(buffer_T* buffer, const char* text, const size_t length) {
   if (!buffer || !text || length == 0) { return; }
-  if (!buffer_increase_capacity(buffer, length)) { return; }
+  if (!buffer_expand_if_needed(buffer, length)) { return; }
 
   memcpy(buffer->value + buffer->length, text, length);
 
@@ -161,7 +195,7 @@ void buffer_prepend(buffer_T* buffer, const char* text) {
 
   size_t text_length = strlen(text);
 
-  if (!buffer_increase_capacity(buffer, text_length)) { return; }
+  if (!buffer_expand_if_needed(buffer, text_length)) { return; }
 
   memmove(buffer->value + text_length, buffer->value, buffer->length + 1);
   memcpy(buffer->value, text, text_length);
@@ -171,29 +205,16 @@ void buffer_prepend(buffer_T* buffer, const char* text) {
 
 void buffer_concat(buffer_T* destination, buffer_T* source) {
   if (source->length == 0) { return; }
-  if (!buffer_increase_capacity(destination, source->length)) { return; }
+  if (!buffer_expand_if_needed(destination, source->length)) { return; }
 
   memcpy(destination->value + destination->length, source->value, source->length);
+
   destination->length += source->length;
   destination->value[destination->length] = '\0';
 }
 
-bool buffer_ensure_capacity(buffer_T* buffer, const size_t min_capacity) {
-  if (buffer->capacity >= min_capacity) { return true; }
-
-  if (min_capacity > SIZE_MAX) {
-    fprintf(stderr, "Error: Buffer capacity would overflow system limits.\n");
-    return false;
-  }
-
-  char* new_value = safe_realloc(buffer->value, min_capacity);
-
-  if (unlikely(new_value == NULL)) { return false; }
-
-  buffer->value = new_value;
-  buffer->capacity = min_capacity;
-
-  return true;
+bool buffer_has_capacity(buffer_T* buffer, const size_t required_length) {
+  return (buffer->length + required_length <= buffer->capacity);
 }
 
 void buffer_clear(buffer_T* buffer) {
@@ -204,7 +225,7 @@ void buffer_clear(buffer_T* buffer) {
 void buffer_free(buffer_T* buffer) {
   if (!buffer) { return; }
 
-  free(buffer->value);
+  if (buffer->value != NULL) { free(buffer->value); }
 
   buffer->value = NULL;
   buffer->length = buffer->capacity = 0;

src/include/buffer.h

@@ -13,8 +13,11 @@ typedef struct BUFFER_STRUCT {
 bool buffer_init(buffer_T* buffer);
 buffer_T buffer_new(void);
 
-bool buffer_increase_capacity(buffer_T* buffer, size_t required_length);
-bool buffer_ensure_capacity(buffer_T* buffer, size_t min_capacity);
+bool buffer_increase_capacity(buffer_T* buffer, size_t additional_capacity);
+bool buffer_has_capacity(buffer_T* buffer, size_t required_length);
+bool buffer_expand_capacity(buffer_T* buffer);
+bool buffer_expand_if_needed(buffer_T* buffer, size_t required_length);
+bool buffer_resize(buffer_T* buffer, size_t new_capacity);
 
 void buffer_append(buffer_T* buffer, const char* text);
 void buffer_append_with_length(buffer_T* buffer, const char* text, size_t length);

test/c/test_buffer.c

@@ -59,46 +59,74 @@ TEST(test_buffer_concat)
   buffer_free(&buffer2);
 END
 
+// Test increating
 TEST(test_buffer_increase_capacity)
   buffer_T buffer = buffer_new();
 
-  const size_t initial_capacity = buffer.capacity;
-  ck_assert_int_ge(initial_capacity, 1024); // Ensure initial capacity is at least 1024
+  ck_assert_int_eq(buffer.capacity, 1024);
 
-  // Increase capacity by a small amount, should NOT trigger reallocation
-  ck_assert(buffer_increase_capacity(&buffer, 100));
-  ck_assert_int_eq(buffer.capacity, initial_capacity); // No change expected
+  ck_assert(buffer_increase_capacity(&buffer, 1));
+  ck_assert_int_eq(buffer.capacity, 1025);
 
-  // Increase capacity beyond the current limit, should trigger reallocation
-  ck_assert(buffer_increase_capacity(&buffer, initial_capacity + 1));
-  ck_assert(buffer.capacity > initial_capacity); // Capacity should increase
+  ck_assert(buffer_increase_capacity(&buffer, 1024 + 1));
+  ck_assert_int_eq(buffer.capacity, 2050);
 
   buffer_free(&buffer);
 END
 
-// Test ensuring buffer capacity
-TEST(test_buffer_ensure_capacity)
+// Test expanding capacity
+TEST(test_buffer_expand_capacity)
   buffer_T buffer = buffer_new();
 
   ck_assert_int_eq(buffer.capacity, 1024);
 
-  ck_assert(buffer_ensure_capacity(&buffer, 512)); // Should not reallocate
+  ck_assert(buffer_expand_capacity(&buffer));
+  ck_assert_int_eq(buffer.capacity, 2048);
+
+  ck_assert(buffer_expand_capacity(&buffer));
+  ck_assert_int_eq(buffer.capacity, 4096);
+
+  ck_assert(buffer_expand_capacity(&buffer));
+  ck_assert_int_eq(buffer.capacity, 8192);
+
+  buffer_free(&buffer);
+END
+
+// Test expanding if needed
+TEST(test_buffer_expand_if_needed)
+  buffer_T buffer = buffer_new();
+
   ck_assert_int_eq(buffer.capacity, 1024);
 
-  ck_assert(buffer_ensure_capacity(&buffer, 1023)); // Should not reallocate
+  ck_assert(buffer_expand_if_needed(&buffer, 1));
   ck_assert_int_eq(buffer.capacity, 1024);
 
-  ck_assert(buffer_ensure_capacity(&buffer, 1024)); // Should not reallocate
+  ck_assert(buffer_expand_if_needed(&buffer, 1023));
   ck_assert_int_eq(buffer.capacity, 1024);
 
-  ck_assert(buffer_ensure_capacity(&buffer, 1025));
-  ck_assert_int_eq(buffer.capacity, 1025);
+  ck_assert(buffer_expand_if_needed(&buffer, 1024));
+  ck_assert_int_eq(buffer.capacity, 1024);
 
-  ck_assert(buffer_ensure_capacity(&buffer, 2048));
+  ck_assert(buffer_expand_if_needed(&buffer, 1025));
+  ck_assert_int_eq(buffer.capacity, 3074); // initial capacity (1024) + (required (1025) * 2) = 3074
+
+  buffer_free(&buffer);
+END
+
+// Test resizing buffer
+TEST(test_buffer_resize)
+  buffer_T buffer = buffer_new();
+
+  ck_assert_int_eq(buffer.capacity, 1024);
+
+  ck_assert(buffer_resize(&buffer, 2048));
   ck_assert_int_eq(buffer.capacity, 2048);
 
-  ck_assert(buffer_ensure_capacity(&buffer, 2049));
-  ck_assert_int_eq(buffer.capacity, 2049);
+  ck_assert(buffer_resize(&buffer, 4096));
+  ck_assert_int_eq(buffer.capacity, 4096);
+
+  ck_assert(buffer_resize(&buffer, 8192));
+  ck_assert_int_eq(buffer.capacity, 8192);
 
   buffer_free(&buffer);
 END
@@ -107,9 +135,13 @@ END
 TEST(test_buffer_clear)
   buffer_T buffer = buffer_new();
 
+  ck_assert_int_eq(buffer.capacity, 1024);
+
   buffer_append(&buffer, "Hello");
   ck_assert_str_eq(buffer.value, "Hello");
   ck_assert_int_eq(buffer.length, 5);
+  ck_assert_int_eq(buffer.capacity, 1024);
+
   buffer_clear(&buffer);
 
   ck_assert_str_eq(buffer.value, "");
@@ -195,7 +227,9 @@ TCase *buffer_tests(void) {
   tcase_add_test(buffer, test_buffer_prepend);
   tcase_add_test(buffer, test_buffer_concat);
   tcase_add_test(buffer, test_buffer_increase_capacity);
-  tcase_add_test(buffer, test_buffer_ensure_capacity);
+  tcase_add_test(buffer, test_buffer_expand_capacity);
+  tcase_add_test(buffer, test_buffer_expand_if_needed);
+  tcase_add_test(buffer, test_buffer_resize);
   tcase_add_test(buffer, test_buffer_clear);
   tcase_add_test(buffer, test_buffer_free);
   tcase_add_test(buffer, test_buffer_utf8_integrity);