C Hash Tables and Generic Dynamic Arrays Using STBDS

C is often criticized for not having built‑in hash tables, but third‑party libraries fill that gap. One notable example is STBDS, a single‑header library created by Shan Barrett. To activate its implementation you define a specific macro before including the header. Using STBDS starts with defining a struct that holds a key and a value; the hash table itself is simply an array of these structs. Elements are added with stb_put, the current size is obtained with stb_len, and items can be accessed or modified via the index returned for a given key.

STBDS Implementation Details

STBDS keeps its bookkeeping in a structure called stbds_array_header. This header is placed immediately before the actual array data in memory, a trick made possible by C’s low‑level pointer manipulation. Functions such as shlen are thin aliases for internal routines like stbds_shlen. Prefixes are added to identifiers to avoid colliding with other symbols in a program.

Dynamic Array Implementation in C

A classic dynamic array uses a struct that stores a pointer to the items, a count, and a capacity. STBDS adopts the metadata‑before‑data approach for dynamic arrays as well. Memory is allocated for both the header and the initial data buffer; the data pointer returned to the user points just past the header. Pointer arithmetic (header + 1) yields the start of the usable array. The array_init function performs the allocation and sets count and capacity, array_push increments the count and stores a new element while asserting that capacity is not exceeded, and array_length reads the count from the hidden header. Debuggers like GDB or its GUI front‑end GF2 can display the hidden header by casting pointers and using specific array‑display commands.

Advanced Macro Techniques

Functions can be turned into macros to achieve generic, inline‑like behavior. Wrapping macro parameters in parentheses is essential so that the entire substituted expression is evaluated correctly. Multi‑line macros require a backslash at the end of each line, and the do { … } while(0) idiom creates a single statement block that behaves safely in conditional contexts. With these patterns, macros can operate on any compatible data type, such as an array pointer matching the element type.

Generic Dynamic Arrays

To make a dynamic array type‑agnostic, the element size is derived from sizeof(*array) and the array is treated as a void*. Deallocation must first locate the hidden header by subtracting one from the data pointer before calling free. Automatic reallocation is triggered when the count reaches capacity; realloc expands the memory block, often doubling the capacity, and the header pointer is updated because realloc may move the block. Reducing the initial capacity to 1 and stepping through the code in a debugger clearly shows the reallocation process. The resulting interface is simple, though the type itself does not convey that it is a dynamic array and manual deallocation remains necessary.

Mechanisms & Explanations

Single‑header libraries combine declarations and definitions in one .h file; defining a macro like STB_IMPLEMENTATION activates the implementation part. STBDS’s metadata‑first storage relies on C pointer arithmetic: adding one to a header* yields a pointer to the first data element, while subtracting one from a data pointer reaches the header. Generic dynamic arrays follow the same pattern, using void* for type independence and realloc for growth. Macro expansion works by textual substitution, so parentheses around parameters prevent precedence errors. The do‑while(0) construct ensures that multi‑line macros behave like single statements, avoiding syntax issues in if/else chains. When a dynamic array exceeds its capacity, realloc allocates a larger block (commonly double the size), copies existing elements, and frees the old block, with the possibility that the memory address changes.

Frequently Asked Questions

What is STBDS and why use it?

STBDS is a single‑header C library that provides hash tables by storing metadata before the data array, allowing easy insertion and size queries without native language support.

How does the metadata‑before‑data technique work?

A header struct is allocated together with the data buffer; the data pointer returned to the user points just after the header, and pointer arithmetic lets the code retrieve the header when needed.

Why wrap macro parameters in parentheses?

Parentheses ensure the entire substituted expression is evaluated as a unit, preventing operator‑precedence problems and partial substitutions.

How does automatic reallocation expand a dynamic array?

When count equals capacity, realloc creates a larger memory block (often double the size), copies existing elements, updates the header, and frees the old block, possibly moving the array to a new address.