stb_vector is a single-header, type-safe, generic dynamic array library for C (also compatible with C++). Inspired by the stb libraries philosophy, it provides easy-to-use dynamic arrays similar to C++ std::vector with modern safety features and zero external dependencies.

• Features
• Why stb_vector?
• Quick Start
• Installation
• API Reference
• Building Examples
• Running Tests
• Comparison with C++ std::vector
• Performance
• Safety Features
• Thread Safety
• Custom Types
• Configuration
• License

• 🎯 Type-Safe: Generic programming with compile-time type checking
• 📦 Single Header: Just drop stb_vector.h into your project
• 🛡️ Memory Safe: Bounds checking, use-after-free detection, allocation failure handling
• ⚡ Fast: O(1) amortized push, cache-friendly contiguous storage
• 🔧 Easy to Use: Clean API similar to C++ vectors
• 🎨 Exception Handling: Try/catch style error handling using setjmp/longjmp
• 🧵 Thread-Aware: Thread-local error contexts for multi-threaded environments
• 🔓 No Dependencies: Pure C with standard library only
• 🌐 Portable: Works on Windows, Linux, macOS, Unix (32/64-bit)
• 🔄 C++ Compatible: Works seamlessly in C++ projects

C doesn't have built-in dynamic arrays. Traditional solutions involve:

• Manual memory management - Error-prone malloc/realloc/free
• Unsafe macros - Type-unsafe, hard to debug
• Complex libraries - Heavy dependencies, steep learning curve

stb_vector brings C++-style vectors to C with:

• ✅ Type safety without templates
• ✅ Automatic memory management
• ✅ Familiar API (like std::vector)
• ✅ Single-header simplicity
• ✅ Production-ready error handling

#define STB_VECTOR_IMPLEMENTATION
#include "stb_vector.h"
#include <stdio.h>

int main(void) {
    // Create a new integer vector
    Vector(int) *vec = vector_new(int);

    // Add elements
    $(vec)->push_back(10);
    $(vec)->push_back(20);
    $(vec)->push_back(30);

    // Access elements
    printf("Size: %zu\n", $(vec)->size());
    printf("First: %d\n", $(vec)->front());
    printf("Last: %d\n", $(vec)->back());

    // Iterate
    for (size_t i = 0; i < $(vec)->size(); ++i) {
        printf("%d ", $(vec)->get(i));
    }
    printf("\n");

    // Cleanup
    $(vec)->destroy();
    free(vec);

    return 0;
}

Output:

Size: 3
First: 10
Last: 30
10 20 30

1. Download stb_vector.h
2. Copy it to your project directory
3. Include it in ONE C file with the implementation:

#define STB_VECTOR_IMPLEMENTATION
#include "stb_vector.h"

4. In other files, just include without the define:

#include "stb_vector.h"

git clone https://github.com/haseeb-heaven/stb_vector.git
cd stb_vector
mkdir build && cd build
cmake ..
make

Vector(T) *vec = vector_new(T);              // Empty vector
Vector(T) *vec = vector_new(T, 10);          // Pre-sized (10 elements, zero-initialized)
Vector(T) *vec = vector_new(T, 10, value);   // Pre-filled (10 elements, all = value)

$(vec)->destroy();  // Free internal data
free(vec);          // Free the struct itself

mkdir build && cd build
cmake ..
make

# Run examples
./examples/example_c
./examples/example_cpp

# Run tests
./tests/test_vector

C Example:

gcc -o example_c examples/example_c.c -I. -std=c99
./example_c

C++ Example:

g++ -o example_cpp examples/example_cpp.cpp -I. -std=c++11
./example_cpp

cd build
make
./tests/test_vector

Tests cover:

• ✅ Creation and destruction
• ✅ Push/pop operations
• ✅ Insert/erase
• ✅ Resizing and reserving
• ✅ Bounds checking
• ✅ Error handling
• ✅ Edge cases (empty vector, large sizes)
• ✅ Memory leak detection

stb_vector is designed to be conceptually similar to C++ std::vector, making it intuitive for C++ developers working in C.

C++ std::vector:

std::vector<int> vec;
vec.push_back(10);
vec.push_back(20);
std::cout << vec[0] << std::endl;
for (int x : vec) {
    std::cout << x << " ";
}

C++ stb_vector:

Vector(int) *vec = vector_new(int);
$(vec)->push_back(10);
$(vec)->push_back(20);
std::cout << $(vec)->get(0) << std::endl;
for (size_t index = 0; index < $(vec)->size(); ++index) {
    std::cout << $(vec)->get(index) << " ";
}
$(vec)->destroy();
free(vec);

• Per-vector overhead: ~40 bytes (struct metadata)
• Growth strategy: Exponential (2x doubling)
• Memory layout: Contiguous array (cache-friendly)

On a typical modern CPU (x86_64):

• 1M push_back operations: ~5-10ms
• Random access (1M gets): ~2-3ms
• Resize to 1M elements: ~5-8ms

(Actual performance depends on hardware, compiler optimizations, and data types)

All access operations validate indices:

Vector(int) *vec = vector_new(int);
$(vec)->get(10);  // ERROR: Out of bounds

Magic number validation:

$(vec)->destroy();
$(vec)->push_back(10);  // ERROR: Invalid vector (magic number check fails)

Graceful error reporting:

stb_try(vec) {
    $(vec)->reserve(SIZE_MAX);  // Will fail
} stb_catch {
    printf("Error: %s\n", vec->error.message);
}

stb_try(vec) {
    $(vec)->push_back(10);
    $(vec)->get(100);  // Throws exception
    // Code below doesn't execute
} stb_catch {
    printf("Caught: %s\n", vec->error.message);
}

• Different vectors in different threads: Fully safe
• Thread-local error contexts: Each thread has its own error state

• Sharing same vector across threads: Requires external synchronization (mutex)

Example:

// Thread 1
Vector(int) *vec1 = vector_new(int);
$(vec1)->push_back(10);  // ✅ Safe

// Thread 2
Vector(int) *vec2 = vector_new(int);
$(vec2)->push_back(20);  // ✅ Safe

// Thread 1 and 2 accessing vec1
// ❌ NOT SAFE without mutex

You can use stb_vector with custom types:

typedef struct {
    int x;
    int y;
} Point;

// Declare vector for Point type
DECLARE_VECTOR(Point)

// Usage
Vector(Point) *points = vector_new(Point);
Point p = {10, 20};
$(points)->push_back(p);

Built-in types: int, float, double, char, long

You can customize memory allocation:

#define STB_VECTOR_MALLOC(sz, ctx)       my_malloc(sz)
#define STB_VECTOR_REALLOC(ptr, sz, ctx) my_realloc(ptr, sz)
#define STB_VECTOR_FREE(ptr, ctx)        my_free(ptr)

#define STB_VECTOR_IMPLEMENTATION
#include "stb_vector.h"

Other configuration:

• STB_VECTOR_INITIAL_CAPACITY (default: 1)
• STB_VECTOR_GROWTH_FACTOR (default: 2)

This software is dual-licensed. Choose whichever you prefer:

Copyright (c) 2025 Haseeb Mir

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED.

This is free and unencumbered software released into the public domain. Anyone is free to copy, modify, publish, use, compile, sell, or distribute this software.

Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.

git clone https://github.com/haseeb-heaven/stb_vector.git
cd stb_vector
mkdir build && cd build
cmake ..
make
make test

• API Reference
• Examples
• Tests

Inspired by:

• stb libraries by Sean Barrett
• C++ STL std::vector

Author: Haseeb Mir
Version: 1.0
Repository: https://github.com/haseeb-heaven/stb_vector

Made with ❤️ for the C community