vector.h

vector.h - Type-Safe Dynamic Arrays for C

vector.h is a comprehensive macro-based library designed to create type-safe dynamic arrays in C. This library prioritizes robust functionality and offers extensive features that enhance productivity while coding in C.

Key Features

• Type Safety: Effortlessly generate vectors for any data type, ensuring compile-time type checking and preventing potential runtime errors.
• Portability: Fully compatible with C89, tested across various compilers including GCC, Clang, MSVC, and ICX on architectures like x86, x86_64, and ARM64.
• Robust Memory Management: Incorporates extensive bounds checking and efficient memory management, minimizing common pitfalls associated with dynamic memory.
• Configurability: Adaptable to user needs with customizable allocators and null-pointer policies, providing flexibility in memory handling.
• Zero Dependencies: Relies solely on the standard C library, ensuring ease of integration into any project.

Quick Start

To begin utilizing vector.h, follow these simple steps:

1. Include the header file and declare your vector type:

   #include "vector.h"
   VECTOR_DECLARE(MyVector, my_vector, float)
   

2. Define the implementation in a separate source file:

   #include "my_vector.h"
   VECTOR_DEFINE(MyVector, my_vector, float)
   

3. Use the vector:

   MyVector v = {0};
   my_vector_push(&v, 3.14f);
   my_vector_push(&v, 2.71f);
   for (float *f = v.begin; f != v.end; f++) {
       printf("%.2f ", *f);
   }
   my_vector_free(&v);
   

Alternatively, for single-file implementation:

#include "vector.h"
VECTOR_DECLARE(MyVector, my_vector, float)
VECTOR_DEFINE(MyVector, my_vector, float)

API Overview

Here are some essential API functions offered by vector.h:

• VECTOR_SIZE(vec) - Returns the number of elements in the vector.
• VECTOR_CAPACITY(vec) - Retrieves the total allocated capacity of the vector.
• vector_push(vec, value) - Appends an element to the vector in amortized O(1) time complexity.
• vector_pop(vec) - Removes and returns the last element from the vector.
• vector_get(vec, idx) / vector_set(vec, idx, value) - Provides random access to elements.
• vector_insert(vec, idx, value) / vector_delete(vec, idx) - Facilitates element insertion or removal at specified indices.
• vector_clear(vec) - Removes all elements from the vector.
• vector_free(vec) - Frees allocated memory for the vector.

Configuration

Before including the library, certain configurations can be defined:

#define VECTOR_NO_PANIC_ON_NULL 1       /* Suppresses panic on null pointer access */
#define VECTOR_NO_PANIC_ON_OOB 1        /* Prevents panic on out-of-bounds access */
#define VECTOR_REALLOC my_realloc       /* Allows custom allocation function */
#define VECTOR_FREE my_free             /* Allows custom deallocation function */

Testing

For testing the library functions, use CMake:

mkdir build
cmake -S . -B build/ -DCMAKE_BUILD_TYPE=Debug
cd build
make test

Tests include normal functionality, edge cases, memory allocation errors, and null pointer handling.

Why Choose vector.h Over Other Libraries?

• Enhanced Convenience: Similar to other single-header libraries but with more powerful features.
• Improved Type Safety: Provides compile-time type checking unlike many alternatives.
• Optimized Iteration: Implements efficient iteration techniques akin to std::vector, improving performance.
• Memory Management: Offers better error handling by providing clear panic messages during out-of-bounds access without resorting to undefined behavior.
• Debugging Experience: Maintains straightforward pointer-based internals, aiding in debugging processes.
• Permissive Licensing: Released under a BSD0 license, allowing broad usage with minimal restrictions.

For developers and contributors interested in enhancing vector.h, it's advisable to start with vector.in.h, which includes hardcoded types and function names, and use libgen.py for generating the final library.