AxlData – Data Structures

Core collection types: hash table, dynamic array, doubly-linked list, singly-linked list, and queue.

Headers:

• <axl/axl-hash-table.h> – Hash table with string keys (FNV-1a, chained)

• <axl/axl-array.h> – Dynamic array (auto-growing, index access)

• <axl/axl-list.h> – Doubly-linked list

• <axl/axl-slist.h> – Singly-linked list

• <axl/axl-queue.h> – FIFO queue

Choosing a Collection

Type	Best for	Lookup	Insert/Remove
AxlHashTable	Key-value mapping	O(1) by key	O(1) amortized
AxlArray	Indexed, sorted data	O(1) by index	O(1) append
AxlList	Frequent insert/remove	O(n) by value	O(1) at position
AxlSList	Simple linked sequences	O(n)	O(1) prepend
AxlQueue	FIFO/LIFO patterns	O(1) head/tail	O(1) push/pop

AxlHashTable

String-keyed hash table with FNV-1a hashing, chained collision resolution, and automatic resize at 75% load factor. Keys are copied internally; values are opaque pointers (not copied, not freed).

AXL_AUTOPTR(AxlHashTable) h = axl_hash_table_new();

axl_hash_table_set(h, "name", "AXL");
axl_hash_table_set(h, "version", "0.1.0");

const char *name = axl_hash_table_get(h, "name");   // "AXL"
size_t count = axl_hash_table_size(h);               // 2

axl_hash_table_remove(h, "version");

// Iterate all entries
axl_hash_table_foreach(h, my_callback, user_data);

Typedefs

typedef struct AxlHashTable AxlHashTable

typedef void (*AxlHashTableForeachFunc)(const char *key, void *value, void *data)

AxlHashTableForeachFunc:

Callback for axl_hash_table_foreach.

typedef void (*AxlHashTableForeachWFunc)(const unsigned short *key, void *value, void *data)

AxlHashTableForeachWFunc:

Callback for axl_hash_table_foreach_w().

Functions

AxlHashTable *axl_hash_table_new(void)

Create a new hash table with string keys.

Returns:

new AxlHashTable, or NULL on allocation failure. Free with axl_hash_table_free().

void axl_hash_table_free(AxlHashTable *h)

Free a hash table. Keys are freed; values are NOT freed.

Parameters:

• h – hash table (NULL-safe)

int axl_hash_table_set(AxlHashTable *h, const char *key, void *value)

Insert or replace a key-value pair.

Parameters:

• h – hash table

• key – string key (copied internally)

• value – value pointer (not copied, not freed on removal)

Returns:

0 on success, -1 on allocation failure.

void *axl_hash_table_get(AxlHashTable *h, const char *key)

Look up a key.

Parameters:

• h – hash table

• key – key to look up

Returns:

value pointer, or NULL if not found.

bool axl_hash_table_remove(AxlHashTable *h, const char *key)

Remove an entry. The value is NOT freed.

Parameters:

• h – hash table

• key – key to remove

Returns:

true if removed, false if not found.

void axl_hash_table_foreach(AxlHashTable *h, AxlHashTableForeachFunc func, void *data)

Iterate all entries. Order is undefined.

Parameters:

• h – hash table

• func – callback

• data – opaque data passed to callback

size_t axl_hash_table_size(AxlHashTable *h)

Get the number of entries.

Parameters:

• h – hash table

Returns:

number of entries.

AxlHashTable *axl_hash_table_new_w(void)

Create a new hash table with UCS-2 (unsigned short) keys.

Returns:

new AxlHashTable, or NULL on allocation failure. Free with axl_hash_table_free().

int axl_hash_table_set_w(AxlHashTable *h, const unsigned short *key, void *value)

Insert or replace a key-value pair.

Parameters:

• h – hash table

• key – UCS-2 key (copied internally via AllocatePool)

• value – value pointer (not copied, not freed on removal)

Returns:

0 on success, -1 on allocation failure.

void *axl_hash_table_get_w(AxlHashTable *h, const unsigned short *key)

Look up a key.

Parameters:

• h – hash table

• key – UCS-2 key to look up

Returns:

value pointer, or NULL if not found.

bool axl_hash_table_remove_w(AxlHashTable *h, const unsigned short *key)

Remove an entry. The value is NOT freed.

Parameters:

• h – hash table

• key – UCS-2 key to remove

Returns:

true if removed, false if not found.

void axl_hash_table_foreach_w(AxlHashTable *h, AxlHashTableForeachWFunc func, void *data)

Iterate all UCS-2-keyed entries. Order is undefined.

Parameters:

• h – hash table

• func – callback

• data – opaque data passed to callback

AxlArray

Dynamic array that stores elements by value (not pointers). Auto-grows on append. Supports indexed access and sorting.

AXL_AUTOPTR(AxlArray) a = axl_array_new(sizeof(int));

int values[] = {50, 20, 40, 10, 30};
for (int i = 0; i < 5; i++) {
    axl_array_append(a, &values[i]);
}

axl_array_sort(a, int_compare);

for (size_t i = 0; i < axl_array_len(a); i++) {
    int *val = axl_array_get(a, i);
    axl_printf("%d ", *val);  // 10 20 30 40 50
}

Typedefs

typedef struct AxlArray AxlArray

typedef int (*AxlCompareFunc)(const void *a, const void *b)

Comparison function for axl_array_sort. Same signature as qsort.

Return:

< 0 if a < b, 0 if equal, > 0 if a > b.

Functions

AxlArray *axl_array_new(size_t element_size)

Create a new dynamic array for value-mode storage.

Parameters:

• element_size – size of each element in bytes

Returns:

new AxlArray, or NULL on failure. Free with axl_array_free().

void axl_array_free(AxlArray *a)

Free a dynamic array and its internal buffer.

Parameters:

• a – array (NULL-safe)

int axl_array_append(AxlArray *a, const void *element)

Append an element (value mode).

Parameters:

• a – array

• element – pointer to element data to copy (element_size bytes)

Returns:

0 on success, -1 on allocation failure.

void *axl_array_get(AxlArray *a, size_t index)

Get a pointer to the element at index (value mode).

Parameters:

• a – array

• index – element index

Returns:

pointer into internal buffer, or NULL if out of range.

size_t axl_array_len(AxlArray *a)

Get the number of elements in the array.

Parameters:

• a – array

Returns:

number of elements.

void axl_array_clear(AxlArray *a)

Remove all elements. Does not free the internal buffer.

Parameters:

• a – array

int axl_array_append_ptr(AxlArray *a, void *ptr)

Append a pointer (pointer mode).

Parameters:

• a – array

• ptr – pointer to store

Returns:

0 on success, -1 on allocation failure.

void *axl_array_get_ptr(AxlArray *a, size_t index)

Get stored pointer at index (pointer mode).

Parameters:

• a – array

• index – element index

Returns:

stored pointer, or NULL if out of range.

void axl_array_sort(AxlArray *a, AxlCompareFunc compare)

Sort array elements in place using insertion sort.

Parameters:

• a – array

• compare – comparison function (qsort-compatible)

AxlList

GLib-style doubly-linked list. Each node has data, next, and prev pointers. Functions return the new head (which may change after prepend, remove, or sort).

AxlList *list = NULL;
list = axl_list_append(list, "first");
list = axl_list_append(list, "second");
list = axl_list_prepend(list, "zeroth");

for (AxlList *n = list; n != NULL; n = n->next) {
    axl_printf("%s\n", (char *)n->data);
}
axl_list_free(list);

Typedefs

typedef void (*AxlFunc)(void *data, void *user_data)

AxlFunc:

Generic per-element callback (GFunc equivalent).

typedef void (*AxlDestroyNotify)(void *data)

AxlDestroyNotify:

Callback to free element data (GDestroyNotify equivalent).

Functions

AxlList *axl_list_append(AxlList *list, void *data)

Append data to the end of the list. O(n).

Parameters:

• list – current head (NULL for empty list)

• data – data pointer to store

Returns:

new head of the list.

AxlList *axl_list_prepend(AxlList *list, void *data)

Prepend data to the front of the list. O(1).

Parameters:

• list – current head (NULL for empty list)

• data – data pointer to store

Returns:

new head of the list.

AxlList *axl_list_insert(AxlList *list, void *data, int position)

Insert data at the given position. O(n).

Negative or out-of-range position appends to the end.

Parameters:

• list – current head

• data – data pointer to store

• position – 0-based insert position

Returns:

new head of the list.

AxlList *axl_list_insert_sorted(AxlList *list, void *data, AxlCompareFunc func)

Insert data in sorted order. O(n).

The list must already be sorted by the same comparator.

Parameters:

• list – current head (sorted)

• data – data pointer to insert

• func – comparison function

Returns:

new head of the list.

AxlList *axl_list_remove(AxlList *list, const void *data)

Remove the first element matching data. O(n).

Compares by pointer equality. Frees the node, not the data.

Parameters:

• list – current head

• data – data pointer to find and remove

Returns:

new head of the list.

AxlList *axl_list_reverse(AxlList *list)

Reverse the list in place. O(n).

Parameters:

• list – current head

Returns:

new head (was the tail).

AxlList *axl_list_concat(AxlList *list1, AxlList *list2)

Concatenate two lists. O(n) in length of list1.

list2 is appended to list1. Both must be distinct lists.

Parameters:

• list1 – first list

• list2 – second list (appended)

Returns:

head of the combined list.

AxlList *axl_list_sort(AxlList *list, AxlCompareFunc func)

Sort the list using merge sort. O(n log n), stable.

Parameters:

• list – current head

• func – comparison function

Returns:

new head of the sorted list.

AxlList *axl_list_copy(AxlList *list)

Shallow copy of the list. O(n).

Copies node structure; data pointers are shared, not duplicated.

Parameters:

• list – list to copy

Returns:

head of the new list, or NULL on failure.

void axl_list_free(AxlList *list)

Free all nodes. Does not free element data.

Parameters:

• list – head (NULL-safe)

void axl_list_free_full(AxlList *list, AxlDestroyNotify free_func)

Free all nodes, calling free_func on each element’s data.

Parameters:

• list – head (NULL-safe)

• free_func – called on each node’s data

size_t axl_list_length(AxlList *list)

Count elements. O(n).

Parameters:

• list – head

Returns:

number of elements.

AxlList *axl_list_nth(AxlList *list, size_t n)

Get the nth node. O(n).

Parameters:

• list – head

• n – 0-based index

Returns:

node at position n, or NULL if out of range.

void *axl_list_nth_data(AxlList *list, size_t n)

Get data from the nth node. O(n).

Parameters:

• list – head

• n – 0-based index

Returns:

data pointer, or NULL if out of range.

AxlList *axl_list_first(AxlList *list)

Get the first node (rewind to head). O(n).

Useful when you have a pointer to a middle node.

Parameters:

• list – any node in the list

Returns:

the first node, or NULL if list is empty.

AxlList *axl_list_last(AxlList *list)

Get the last node. O(n).

Parameters:

• list – head

Returns:

the last node, or NULL if list is empty.

AxlList *axl_list_find(AxlList *list, const void *data)

Find the first node with matching data (pointer equality). O(n).

Parameters:

• list – head

• data – data pointer to find

Returns:

matching node, or NULL.

AxlList *axl_list_find_custom(AxlList *list, const void *data, AxlCompareFunc func)

Find using a custom comparator. O(n).

Calls func(node->data, data) for each node. Returns the first node where func returns 0.

Parameters:

• list – head

• data – data to compare against

• func – comparison function

Returns:

matching node, or NULL.

void axl_list_foreach(AxlList *list, AxlFunc func, void *user_data)

Call func for each element. O(n).

Parameters:

• list – head

• func – callback

• user_data – passed to callback

struct AxlList

Public Members

void *data

struct AxlList *next

struct AxlList *prev

AxlSList

Singly-linked list – lighter than AxlList (no prev pointer). Use when you only traverse forward.

Functions

AxlSList *axl_slist_append(AxlSList *list, void *data)

Append data to the end. O(n).

Parameters:

• list – current head (NULL for empty)

• data – data pointer

Returns:

new head.

AxlSList *axl_slist_prepend(AxlSList *list, void *data)

Prepend data to the front. O(1).

Parameters:

• list – current head (NULL for empty)

• data – data pointer

Returns:

new head.

AxlSList *axl_slist_insert(AxlSList *list, void *data, int position)

Insert at position. O(n).

Parameters:

• list – current head

• data – data pointer

• position – 0-based position

Returns:

new head.

AxlSList *axl_slist_insert_sorted(AxlSList *list, void *data, AxlCompareFunc func)

Insert in sorted order. O(n).

Parameters:

• list – current head (sorted)

• data – data to insert

• func – comparison function

Returns:

new head.

AxlSList *axl_slist_remove(AxlSList *list, const void *data)

Remove first match by pointer equality. O(n).

Parameters:

• list – current head

• data – data to find and remove

Returns:

new head.

AxlSList *axl_slist_reverse(AxlSList *list)

Reverse in place. O(n).

Parameters:

• list – current head

Returns:

new head (was tail).

AxlSList *axl_slist_concat(AxlSList *list1, AxlSList *list2)

Concatenate two lists. O(n) in list1.

Parameters:

• list1 – first list

• list2 – appended to list1

Returns:

head of combined list.

AxlSList *axl_slist_sort(AxlSList *list, AxlCompareFunc func)

Sort using merge sort. O(n log n), stable.

Parameters:

• list – current head

• func – comparison function

Returns:

new head.

AxlSList *axl_slist_copy(AxlSList *list)

Shallow copy. O(n).

Parameters:

• list – list to copy

Returns:

new list head, or NULL on failure.

void axl_slist_free(AxlSList *list)

Free all nodes. Does not free element data.

Parameters:

• list – head (NULL-safe)

void axl_slist_free_full(AxlSList *list, AxlDestroyNotify free_func)

Free all nodes, calling free_func on each element’s data.

Parameters:

• list – head (NULL-safe)

• free_func – called on each data

size_t axl_slist_length(AxlSList *list)

Count elements. O(n).

Parameters:

• list – head

Returns:

number of elements.

AxlSList *axl_slist_nth(AxlSList *list, size_t n)

Get nth node. O(n).

Parameters:

• list – head

• n – 0-based index

Returns:

node, or NULL if out of range.

void *axl_slist_nth_data(AxlSList *list, size_t n)

Get data from nth node. O(n).

Parameters:

• list – head

• n – 0-based index

Returns:

data pointer, or NULL if out of range.

AxlSList *axl_slist_last(AxlSList *list)

Get last node. O(n).

Parameters:

• list – head

Returns:

last node, or NULL.

AxlSList *axl_slist_find(AxlSList *list, const void *data)

Find by pointer equality. O(n).

Parameters:

• list – head

• data – data to find

Returns:

matching node, or NULL.

AxlSList *axl_slist_find_custom(AxlSList *list, const void *data, AxlCompareFunc func)

Find with custom comparator. O(n).

Parameters:

• list – head

• data – data to compare against

• func – comparison function

Returns:

first node where func(node->data, data) == 0, or NULL.

void axl_slist_foreach(AxlSList *list, AxlFunc func, void *user_data)

Call func for each element. O(n).

Parameters:

• list – head

• func – callback

• user_data – passed to callback

struct AxlSList

Public Members

void *data

struct AxlSList *next

AxlQueue

FIFO queue with push/pop at both ends and peek. Can also be used as a stack (push/pop from the same end). Supports stack-allocated initialization.

AxlQueue q = AXL_QUEUE_INIT;    // stack-allocated
axl_queue_push_tail(&q, "first");
axl_queue_push_tail(&q, "second");

while (!axl_queue_is_empty(&q)) {
    char *item = axl_queue_pop_head(&q);
    axl_printf("dequeue: %s\n", item);
}

Defines

AXL_QUEUE_INIT

Static initializer for stack-allocated queues.

Functions

AxlQueue *axl_queue_new(void)

Allocate a new empty queue.

Returns:

new queue, or NULL on failure. Free with axl_queue_free().

void axl_queue_init(AxlQueue *queue)

Initialize a stack-allocated queue.

Parameters:

• queue – queue to initialize

void axl_queue_free(AxlQueue *queue)

Free queue and all nodes. Does not free element data.

Parameters:

• queue – queue (NULL-safe)

void axl_queue_free_full(AxlQueue *queue, AxlDestroyNotify free_func)

Free queue, calling free_func on each element’s data.

Parameters:

• queue – queue (NULL-safe)

• free_func – called on each data

void axl_queue_clear(AxlQueue *queue)

Remove all elements. Queue itself is not freed.

Parameters:

• queue – queue

bool axl_queue_is_empty(AxlQueue *queue)

Check if the queue is empty.

Parameters:

• queue – queue

Returns:

true if empty.

size_t axl_queue_get_length(AxlQueue *queue)

Get the number of elements. O(1).

Parameters:

• queue – queue

Returns:

element count.

int axl_queue_push_head(AxlQueue *queue, void *data)

Push data to the front. O(1).

Parameters:

• queue – queue

• data – data pointer

Returns:

0 on success, -1 on allocation failure.

int axl_queue_push_tail(AxlQueue *queue, void *data)

Push data to the back. O(1).

Parameters:

• queue – queue

• data – data pointer

Returns:

0 on success, -1 on allocation failure.

void *axl_queue_pop_head(AxlQueue *queue)

Remove and return the front element. O(1).

Parameters:

• queue – queue

Returns:

data pointer, or NULL if empty.

void *axl_queue_pop_tail(AxlQueue *queue)

Remove and return the back element. O(1).

Parameters:

• queue – queue

Returns:

data pointer, or NULL if empty.

void *axl_queue_peek_head(AxlQueue *queue)

Peek at the front element without removing. O(1).

Parameters:

• queue – queue

Returns:

data pointer, or NULL if empty.

void *axl_queue_peek_tail(AxlQueue *queue)

Peek at the back element without removing. O(1).

Parameters:

• queue – queue

Returns:

data pointer, or NULL if empty.

void *axl_queue_peek_nth(AxlQueue *queue, size_t n)

Peek at the nth element. O(n).

Parameters:

• queue – queue

• n – 0-based index from head

Returns:

data pointer, or NULL if out of range.

void axl_queue_foreach(AxlQueue *queue, AxlFunc func, void *user_data)

Call func for each element, head to tail. O(n).

Parameters:

• queue – queue

• func – callback

• user_data – passed to callback

AxlQueue *axl_queue_copy(AxlQueue *queue)

Shallow copy. O(n).

Parameters:

• queue – queue to copy

Returns:

new queue, or NULL on failure.

void axl_queue_reverse(AxlQueue *queue)

Reverse the queue in place. O(n).

Parameters:

• queue – queue

void axl_queue_sort(AxlQueue *queue, AxlCompareFunc func)

Sort the queue using merge sort. O(n log n).

Parameters:

• queue – queue

• func – comparison function

struct AxlQueue

Public Members

AxlList *head

AxlList *tail

size_t length