A header-only C++17 library providing a vector container with stable IDs for accessing elements, even after insertions and deletions. Follows STL naming conventions and mimics std::vector's interface.

• Stable IDs: Objects are accessed via IDs that remain valid regardless of other insertions/deletions
• Handle System: Smart handle objects with generation tracking to detect use-after-erase
• Cache-Friendly: Data stored contiguously in memory for efficient iteration
• Custom Allocator Support: siv::vector<T, Allocator> with allocator propagation, like std::vector
• STL-Compatible: Familiar std::vector-like interface (iterators, type aliases, at(), front(), back(), etc.)
• Header-Only: Single header file, easy to integrate
• -fno-exceptions Compatible: Works with both -fexceptions and -fno-exceptions

Simply copy index_vector.hpp to your project and include it:

#include "index_vector.hpp"

#include "index_vector.hpp"

struct Entity {
    int x, y;
    std::string name;
};

int main() {
    siv::vector<Entity> entities;

    // Add objects - returns a stable ID
    siv::id_type player = entities.push_back({0, 0, "Player"});
    siv::id_type enemy  = entities.push_back({10, 5, "Enemy"});

    // Access via ID
    entities[player].x = 5;

    // Bounds-checked access
    entities.at(player).y = 10;

    // Erase objects - other IDs remain valid
    entities.erase(enemy);

    // player ID still works!
    printf("%s\n", entities[player].name.c_str());
}

Handles are smart references that detect when their object has been deleted:

siv::vector<Entity> entities;
siv::id_type id = entities.push_back({0, 0, "Test"});

// Create a handle
siv::handle<Entity> h = entities.make_handle(id);

// Use like a pointer
h->x = 10;
(*h).y = 20;

// Check validity
if (h.valid()) {
    // Safe to use
}

// After erasing, handle becomes invalid
entities.erase(id);
if (!h) {
    printf("Object was deleted!\n");
}

Iterate directly over the contiguous data:

// Range-based for loop
for (auto& entity : entities) {
    entity.x += 1;
}

// Reverse iteration
for (auto it = entities.rbegin(); it != entities.rend(); ++it) {
    it->y -= 1;
}

// Direct data pointer access
Entity* ptr = entities.data();

// Member function
entities.erase_if([](const Entity& e) {
    return e.x < 0;
});

// Free function (C++20 style) - returns number of elements removed
auto removed = siv::erase_if(entities, [](const Entity& e) {
    return e.x < 0;
});

Use a custom allocator just like std::vector:

#include <memory>

// Pool allocator, tracking allocator, etc.
template<typename T>
using my_allocator = std::allocator<T>; // your custom allocator

siv::vector<Entity, my_allocator<Entity>> entities;
siv::id_type id = entities.push_back({0, 0, "Test"});

// Handles carry the allocator type
siv::handle<Entity, my_allocator<Entity>> h = entities.make_handle(id);

// Or construct with an allocator instance
my_allocator<Entity> alloc;
siv::vector<Entity, my_allocator<Entity>> entities2(alloc);

Allocator defaults to std::allocator<T>.

Allocator defaults to std::allocator<T>. Must match the allocator of the owning siv::vector.

• Objects are stored contiguously in a data vector
• An index vector maps stable IDs to current data positions
• On deletion, the last element is swapped into the gap (O(1) erase)
• Generation counters detect use-after-erase scenarios
• Deleted ID slots are recycled on the next insertion

• Double-erase protection: erase(id) asserts that the ID is valid and the object has not already been erased
• Handle validity tracking: Handles use generation counters to detect use-after-erase; dereferencing an invalid handle triggers an assertion
• No dangling handle pointers: siv::vector is non-copyable and non-movable, preventing handles from pointing to a destroyed container
• Bounds-checked access: at(id) throws std::out_of_range (or asserts with -fno-exceptions); generation() and index_of() assert on invalid IDs
• [[nodiscard]] on insertions: push_back and emplace_back return values cannot be silently discarded
• Exception safety: Basic guarantee with self-recovery. Internal metadata uses reserve-before-modify to prevent desync on allocation failure. If element construction throws, the recycled slot is reclaimed on the next insertion
• Allocator propagation: Custom allocators are properly rebound for internal metadata and index vectors via std::allocator_traits::rebind_alloc
• Comparison semantics: Comparison operators operate on data-order (internal storage order), which may differ from insertion order after deletions
• Thread safety: Same guarantees as std::vector — concurrent reads are safe, concurrent writes require external synchronization

• C++17 or later
• Standard library only

MIT License - see LICENSE file.