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).

.. code-block:: c

   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);

.. doxygenfile:: axl-hash-table.h

AxlArray
--------

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

.. code-block:: c

   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
   }

.. doxygenfile:: axl-array.h

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).

.. code-block:: c

   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);

.. doxygenfile:: axl-list.h

AxlSList
--------

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

.. doxygenfile:: axl-slist.h

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.

.. code-block:: c

   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);
   }

.. doxygenfile:: axl-queue.h