### Compile C Example (Bash)

Source: https://github.com/z-libs/zlist.h/blob/main/examples/README.md

Compiles a C example file using GCC. It includes necessary include paths for zlist.h and the generated registry header, then outputs an executable. The command also shows how to run the compiled example.

```bash
gcc c/example_0.c -I.. -Iinclude -o example_c
./example_c
```

--------------------------------

### Generated z_registry.h Example (C)

Source: https://github.com/z-libs/zlist.h/blob/main/examples/README.md

An example of an auto-generated C header file (`z_registry.h`) created by zscanner.py. This file defines macros for registering container types, such as lists, and should not be edited manually.

```c
/* AUTO-GENERATED BY Z-SCANNER - DO NOT EDIT */
#ifndef Z_REGISTRY_H
#define Z_REGISTRY_H

/* Vectors */
#define Z_AUTOGEN_VECS(X) \

/* Lists */
#define Z_AUTOGEN_LISTS(X) \
    X(int, Int) \
    X(Point, Point) \

/* Maps */
#define Z_AUTOGEN_MAPS(X) \

#endif // Z_REGISTRY_H

```

--------------------------------

### Compile C++ Example (Bash)

Source: https://github.com/z-libs/zlist.h/blob/main/examples/README.md

Compiles a C++ example file using G++. It specifies include paths for zlist.h and the registry header, creates an executable, and demonstrates how to run it. This is analogous to the C compilation process.

```bash
g++ cpp/example_0.cpp -I.. -Iinclude -o example_cpp
./example_cpp
```

--------------------------------

### Compilation Examples for zlist.h

Source: https://context7.com/z-libs/zlist.h/llms.txt

Provides command-line examples for compiling C and C++ programs that utilize zlist.h. It covers basic GCC and G++ compilation, including optimization flags, warnings, and specifying include paths. It also demonstrates using the z-scanner for automatic type registration.

```bash
# C compilation (GCC)
gcc -std=c11 main.c -o main

# C compilation with optimizations
gcc -std=c11 -O2 -Wall -Wextra main.c -o main

# C++ compilation
g++ -std=c++14 main.cpp -o main

# With include path (if zlist.h is in parent directory)
gcc -std=c11 -I.. main.c -o main

# Using the z-scanner for automatic type registration
python3 z-core/zscanner.py src/ include/z_registry.h
gcc -std=c11 -Iinclude main.c -o main

```

--------------------------------

### Register Types with zscanner.py (Bash)

Source: https://github.com/z-libs/zlist.h/blob/main/examples/README.md

This command uses the zscanner.py script to automatically generate a registry header file for C or C++ containers. It requires Git to be initialized for submodules and takes the source directory and output header file as arguments.

```bash
git submodule update --init --recursive
python3 ../z-core/zscanner.py c/ include/z_registry.h
```

--------------------------------

### Job Queue Example with zlist.h in C

Source: https://context7.com/z-libs/zlist.h/llms.txt

Demonstrates a job processing queue using zlist.h in C. It includes enqueuing, processing, failure handling, and moving failed jobs to a quarantine list for retries. This example showcases list manipulation functions like push_back, push_front, detach_node, and splice.

```c
#include <stdio.h>
#include <string.h>
#include <stdbool.h>

typedef struct {
    int id;
    char name[32];
    int retries;
} Job;

Job make_job(int id, const char* name) {
    Job j = { .id = id, .retries = 0 };
    snprintf(j.name, sizeof(j.name), "%s", name);
    return j;
}

#define REGISTER_ZLIST_TYPES(X) X(Job, Job)
#define ZLIST_SHORT_NAMES
#include "zlist.h"

int main(void) {
    list(Job) queue      = list_init(Job);
    list(Job) quarantine = list_init(Job);

    printf("=> Enqueuing tasks.\n");
    list_push_back(&queue, make_job(101, "Resize Images"));
    list_push_back(&queue, make_job(102, "Send Emails"));
    list_push_back(&queue, make_job(103, "Generate PDF"));

    printf("[!] Urgent task received: Database Backup\n");
    list_push_front(&queue, make_job(999, "DB Backup"));

    printf("\n=> Processing queue.\n");
    while (!list_is_empty(&queue)) {
        list_node(Job) *current = list_head(&queue);
        Job* j = &current->value;

        printf("Processing Job #%d (%s)... ", j->id, j->name);

        // Simulate failure for PDF generation
        if (strcmp(j->name, "Generate PDF") == 0) {
            printf("FAILED!\n");

            // Detach, update retry count, move to quarantine
            list_node(Job) *failed = list_detach_node(&queue, current);
            j->retries++;
            list_push_back(&quarantine, *j);
            ZLIST_FREE(failed);
        } else {
            printf("Done.\n");
            list_pop_front(&queue);
        }
    }

    printf("\n=> Quarantine review.\n");
    if (list_is_empty(&quarantine)) {
        printf("No failed jobs.\n");
    } else {
        list_foreach(&quarantine, it) {
            printf("Quarantined: %s (Retries: %d)\n",
                   it->value.name, it->value.retries);
        }

        printf("\nMoving failed jobs back to main queue for retry...\n");
        list_splice(&queue, &quarantine);
    }

    list_clear(&queue);
    list_clear(&quarantine);
    return 0;
}

```

--------------------------------

### Initialize Empty List with zlist.h (C)

Source: https://context7.com/z-libs/zlist.h/llms.txt

Demonstrates initializing an empty doubly-linked list using the zlist library. The `list_init(Type)` function creates a new list instance, which must be later deallocated using `list_clear()`. This example shows basic list initialization and checking if the list is empty.

```c
#include <stdio.h>

#define REGISTER_ZLIST_TYPES(X) X(int, Int)
#define ZLIST_SHORT_NAMES
#include "zlist.h"

int main(void) {
    // Initialize an empty list
    list(Int) nums = list_init(Int);

    printf("List initialized, is empty: %s\n", list_is_empty(&nums) ? "true" : "false");
    // Output: List initialized, is empty: true

    list_clear(&nums);
    return 0;
}
```

--------------------------------

### Add Elements to zlist.h List (C)

Source: https://context7.com/z-libs/zlist.h/llms.txt

Shows how to append (`list_push_back`) and prepend (`list_push_front`) elements to a zlist.h list. These operations are O(1) and return `Z_OK` on success or `Z_ENOMEM` if memory allocation fails. The example includes error checking and iterates through the list to display its contents.

```c
#include <stdio.h>

#define REGISTER_ZLIST_TYPES(X) X(int, Int)
#define ZLIST_SHORT_NAMES
#include "zlist.h"

int main(void) {
    list(Int) nums = list_init(Int);

    // Append to end
    list_push_back(&nums, 10);
    list_push_back(&nums, 20);
    list_push_back(&nums, 30);

    // Prepend to front (urgent item)
    list_push_front(&nums, 5);

    // Check return value for error handling
    int result = list_push_back(&nums, 40);
    if (result == Z_OK) {
        printf("Push successful\n");
    } else if (result == Z_ENOMEM) {
        printf("Out of memory!\n");
    }

    // List is now: 5 -> 10 -> 20 -> 30 -> 40
    printf("List contents: ");
    list_foreach(&nums, iter) {
        printf("%d ", iter->value);
    }
    printf("\n");
    // Output: List contents: 5 10 20 30 40

    list_clear(&nums);
    return 0;
}
```

--------------------------------

### Reverse Linked List In-Place (C)

Source: https://context7.com/z-libs/zlist.h/llms.txt

Demonstrates how to reverse a linked list in-place using the `list_reverse` function from zlist.h. This operation is performed in O(N) time complexity and does not require additional memory allocation. The example initializes a list, populates it, prints the original order, reverses it, and then prints the reversed order.

```c
#include <stdio.h>

#define REGISTER_ZLIST_TYPES(X) X(int, Int)
#define ZLIST_SHORT_NAMES
#include "zlist.h"

int main(void) {
    list(Int) nums = list_init(Int);

    list_push_back(&nums, 1);
    list_push_back(&nums, 2);
    list_push_back(&nums, 3);
    list_push_back(&nums, 4);

    printf("Original: ");
    list_foreach(&nums, iter) printf("%d ", iter->value);
    printf("\n");

    list_reverse(&nums);

    printf("Reversed: ");
    list_foreach(&nums, iter) printf("%d ", iter->value);
    printf("\n");
    // Output:
    // Original: 1 2 3 4
    // Reversed: 4 3 2 1

    list_clear(&nums);
    return 0;
}
```

--------------------------------

### C++ Linked List Usage with RAII and STL Compatibility

Source: https://context7.com/z-libs/zlist.h/llms.txt

Showcases the C++ wrapper for zlist.h, providing RAII (Resource Acquisition Is Initialization) semantics, STL-compatible iterators, and initializer list support. This example demonstrates creating lists of integers and custom structs, performing common operations like `push_front`, `push_back`, and iterating using range-based for loops. Memory management is handled automatically by the C++ class destructors.

```cpp
#include <iostream>
#include <string>

struct Point {
    float x, y;
};

// Register types for C++ template specialization
#define REGISTER_ZLIST_TYPES(X) \
    X(int, Int) \
    X(Point, Point)

#include "zlist.h"

int main() {
    // Initializer list construction
    z_list::list<int> numbers = {1, 2, 3, 4, 5};

    // STL-like operations
    numbers.push_front(0);
    numbers.push_back(6);

    // Range-based for loop
    std::cout << "Numbers: ";
    for (int n : numbers) {
        std::cout << n << " ";
    }
    std::cout << "\n";
    // Output: Numbers: 0 1 2 3 4 5 6

    // Access methods (throw on empty)
    std::cout << "Front: " << numbers.front() << "\n";
    std::cout << "Back: " << numbers.back() << "\n";
    std::cout << "Size: " << numbers.size() << "\n";

    // Struct list with RAII
    z_list::list<Point> path;
    path.push_back({1.0f, 2.0f});
    path.push_back({3.5f, 4.5f});

    for (const auto& p : path) {
        std::cout << "Point: {" << p.x << ", " << p.y << "}\n";
    }

    // Reverse in place
    numbers.reverse();
    std::cout << "Reversed: ";
    for (int n : numbers) std::cout << n << " ";
    std::cout << "\n";
    // Output: Reversed: 6 5 4 3 2 1 0

    // No manual cleanup needed - destructors handle it
    return 0;
}
```

--------------------------------

### Custom Memory Allocators with zlist.h in C

Source: https://context7.com/z-libs/zlist.h/llms.txt

Shows how to override the default memory allocation functions (malloc and free) used by zlist.h in C. This allows for custom memory management, such as tracking allocations and frees. The example defines `my_malloc` and `my_free` and then uses the `ZLIST_MALLOC` and `ZLIST_FREE` macros before including zlist.h.

```c
#include <stdio.h>
#include <stdlib.h>

// Custom allocation tracking
static size_t alloc_count = 0;
static size_t free_count = 0;

void* my_malloc(size_t sz) {
    alloc_count++;
    return malloc(sz);
}

void my_free(void* p) {
    if (p) free_count++;
    free(p);
}

// Override allocators BEFORE including zlist.h
#define ZLIST_MALLOC(sz) my_malloc(sz)
#define ZLIST_FREE(p)    my_free(p)

#define REGISTER_ZLIST_TYPES(X) X(int, Int)
#define ZLIST_SHORT_NAMES
#include "zlist.h"

int main(void) {
    list(Int) nums = list_init(Int);

    list_push_back(&nums, 10);
    list_push_back(&nums, 20);
    list_push_back(&nums, 30);

    printf("Allocations: %zu\n", alloc_count);
    // Output: Allocations: 3

    list_clear(&nums);

    printf("Frees: %zu\n", free_count);
    // Output: Frees: 3

    printf("Memory balanced: %s\n", alloc_count == free_count ? "yes" : "no");
    // Output: Memory balanced: yes

    return 0;
}

```

--------------------------------

### C Memory Allocator Override

Source: https://github.com/z-libs/zlist.h/blob/main/README.md

Example of overriding default memory allocators for C lists globally. By defining `ZLIST_MALLOC`, `ZLIST_FREE`, `ZLIST_REALLOC`, and `ZLIST_CALLOC`, custom memory management functions can be integrated.

```c
#define ZLIST_MALLOC  my_malloc
#define ZLIST_FREE    my_free
#define ZLIST_REALLOC my_realloc
#define ZLIST_CALLOC  my_calloc
```

--------------------------------

### Remove Elements from zlist.h List (C)

Source: https://context7.com/z-libs/zlist.h/llms.txt

Illustrates removing elements from the front (`list_pop_front`) and back (`list_pop_back`) of a zlist.h list. These operations are O(1) and are safe to call on an empty list, where they have no effect. The example shows the state of the list after removals.

```c
#include <stdio.h>

#define REGISTER_ZLIST_TYPES(X) X(int, Int)
#define ZLIST_SHORT_NAMES
#include "zlist.h"

int main(void) {
    list(Int) nums = list_init(Int);

    list_push_back(&nums, 10);
    list_push_back(&nums, 20);
    list_push_back(&nums, 30);
    // List: 10 -> 20 -> 30

    list_pop_front(&nums);  // Removes 10
    list_pop_back(&nums);   // Removes 30
    // List: 20

    printf("Remaining element: %d\n", list_head(&nums)->value);
    // Output: Remaining element: 20

    list_clear(&nums);
    return 0;
}
```

--------------------------------

### C++ Iterator Operations for Linked List Manipulation

Source: https://context7.com/z-libs/zlist.h/llms.txt

Details advanced iterator operations available in the C++ wrapper of zlist.h, providing bidirectional STL-compatible iterators. This example demonstrates inserting elements after a specific iterator position using `insert_after` and removing elements at an iterator's position using `erase`, which returns an iterator to the next element. It also shows reverse iteration using `const_iterator`.

```cpp
#include <iostream>

#define REGISTER_ZLIST_TYPES(X) X(int, Int)
#include "zlist.h"

int main() {
    z_list::list<int> nums = {10, 20, 30, 40, 50};

    // Insert after iterator position
    auto it = nums.begin();
    ++it;  // Points to 20
    nums.insert_after(it, 25);
    // List: 10 -> 20 -> 25 -> 30 -> 40 -> 50

    // Erase at iterator (returns next iterator)
    it = nums.begin();
    ++it; ++it;  // Points to 25
    it = nums.erase(it);  // it now points to 30
    // List: 10 -> 20 -> 30 -> 40 -> 50

    std::cout << "After modifications: ";
    for (int n : nums) std::cout << n << " ";
    std::cout << "\n";
    // Output: After modifications: 10 20 30 40 50

    // Reverse iteration using const_iterator
    std::cout << "Reverse (cend to cbegin): ";
    for (auto rit = nums.cend(); rit != nums.cbegin(); ) {
        --rit;
        std::cout << *rit << " ";
    }
    std::cout << "\n";
    // Output: Reverse (cend to cbegin): 50 40 30 20 10

    return 0;
}
```

--------------------------------

### C++ Doubly Linked List Wrapper with zlist.h

Source: https://github.com/z-libs/zlist.h/blob/main/README.md

Illustrates the usage of the zero-overhead C++ wrapper for zlist.h. It demonstrates RAII for automatic memory management, STL-compatible iterators, and range-based for loops for a more idiomatic C++ experience.

```cpp
#include <iostream>

// Register types (visible to C++ compiler).
#define REGISTER_ZLIST_TYPES(X) \
    X(int, Int)

#include "zlist.h"

int main()
{
    // RAII handles memory automatically.
    z_list::list<int> numbers = {1, 2, 3};

    numbers.push_front(0);
    numbers.push_back(4);

    // STL-compatible Iterators (Range-based for loop).
    for (int n : numbers)
    {
        std::cout << n << " ";
    }
        
    return 0;
}
```

--------------------------------

### Access zlist Elements: Head, Tail, and At Index (C)

Source: https://context7.com/z-libs/zlist.h/llms.txt

Demonstrates how to access the first (head) and last (tail) elements of a zlist in O(1) time, and an element at a specific index (at) in O(N) time. This requires including 'zlist.h' and registering the desired data types.

```c
#include <stdio.h>

typedef struct { float x, y; } Point;

#define REGISTER_ZLIST_TYPES(X) X(Point, Point)
#define ZLIST_SHORT_NAMES
#include "zlist.h"

int main(void) {
    list(Point) points = list_init(Point);

    list_push_back(&points, ((Point){1.0f, 2.0f}));
    list_push_back(&points, ((Point){3.0f, 4.0f}));
    list_push_back(&points, ((Point){5.0f, 6.0f}));

    // Access first element
    list_node(Point) *first = list_head(&points);
    if (first) {
        printf("First: {%.1f, %.1f}\n", first->value.x, first->value.y);
    }
    // Output: First: {1.0, 2.0}

    // Access last element
    list_node(Point) *last = list_tail(&points);
    if (last) {
        printf("Last: {%.1f, %.1f}\n", last->value.x, last->value.y);
    }
    // Output: Last: {5.0, 6.0}

    // Access by index (O(N) operation)
    list_node(Point) *middle = list_at(&points, 1);
    if (middle) {
        printf("Index 1: {%.1f, %.1f}\n", middle->value.x, middle->value.y);
    }
    // Output: Index 1: {3.0, 4.0}

    list_clear(&points);
    return 0;
}

```

--------------------------------

### Basic Doubly Linked List Operations in C with zlist.h

Source: https://github.com/z-libs/zlist.h/blob/main/README.md

Demonstrates fundamental operations of the zlist.h doubly linked list in C, including initialization, insertion at the front and back, iteration, and clearing the list. It uses pre-defined type registrations.

```c
#include "types.h"
#include <stdio.h>

int main(void)
{
    // Initialize.
    zlist_Int nums = zlist_init(Int);

    // O(1) Insertions (Returns Z_OK or Z_ENOMEM).
    zlist_push_back(&nums, 10);
    zlist_push_front(&nums, 5);

    // Iteration.
    zlist_node_Int *it;
    zlist_foreach(&nums, it)
    {
        printf("%d ", it->value);
    }
        
    // Cleanup.
    zlist_clear(&nums);
    return 0;
}
```

--------------------------------

### C API - Management Macros

Source: https://github.com/z-libs/zlist.h/blob/main/README.md

Macros for initializing, clearing, and manipulating lists in the C interface.

```APIDOC
## C API - Management Macros

### Description
Macros for initializing, clearing, and manipulating lists in the C interface using `_Generic` dispatch.

### Method
Macros

### Endpoint
N/A (C Macros)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
// Initialize a list named 'my_list'
zlist_init(my_list)

// Clear a list 'my_list'
zlist_clear(my_list)

// Move nodes from 'src_list' to 'dest_list'
zlist_splice(dest_list, src_list)

// Enable auto-cleanup for 'my_list' (GCC/Clang)
zlist_autofree(my_list)
```

### Response
#### Success Response (200)
N/A (Macros operate directly)

#### Response Example
N/A
```

--------------------------------

### C API - Access & State Macros

Source: https://github.com/z-libs/zlist.h/blob/main/README.md

Macros for checking list emptiness and accessing head, tail, and specific nodes in the C interface.

```APIDOC
## C API - Access & State Macros

### Description
Macros for checking list emptiness and accessing head, tail, and specific nodes in the C interface.

### Method
Macros

### Endpoint
N/A (C Macros)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
// Check if list 'my_list' is empty
if (zlist_is_empty(my_list)) { ... }

// Get pointer to the first node
zlist_node_T* head_node = zlist_head(my_list);

// Get pointer to the last node
zlist_node_T* tail_node = zlist_tail(my_list);

// Get pointer to the node at index 5 (O(N) scan)
zlist_node_T* node_at_5 = zlist_at(my_list, 5);
```

### Response
#### Success Response (200)
N/A (Macros operate directly)

#### Response Example
N/A
```

--------------------------------

### Using Short Names for zlist.h API in C

Source: https://github.com/z-libs/zlist.h/blob/main/README.md

Shows how to enable a shorter, more concise API for zlist.h by defining ZLIST_SHORT_NAMES before including the header. This simplifies function and type names, reducing potential namespace collisions.

```c
#define ZLIST_SHORT_NAMES
#include "zlist.h"

// Now you can use:
list(Int) l = list_init(Int);
list_push_back(&l, 10);
list_foreach(&l, it) { ... }
```

--------------------------------

### C List Management Macros

Source: https://github.com/z-libs/zlist.h/blob/main/README.md

Macros for initializing, clearing, and manipulating the structure of C lists. `zlist_init` creates a new list, `zlist_clear` removes all elements, and `zlist_splice` efficiently moves elements between lists. `zlist_autofree` provides automatic cleanup on supported compilers.

```c
#define zlist_init(Name) ...
#define zlist_clear(l) ...
#define zlist_splice(dest, src) ...
#define zlist_autofree(Name) ...
```

--------------------------------

### Configuration - Memory Management

Source: https://github.com/z-libs/zlist.h/blob/main/README.md

Defines for overriding global memory allocators for zlist.

```APIDOC
## Configuration - Memory Management

### Description
Allows overriding the default memory allocation functions (`malloc`, `free`, `realloc`, `calloc`) used by zlist globally.

### Method
Preprocessor Directives

### Endpoint
N/A (Configuration)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
// Define custom memory allocation functions
#define ZLIST_MALLOC  my_malloc
#define ZLIST_FREE    my_free
#define ZLIST_REALLOC my_realloc
#define ZLIST_CALLOC  my_calloc

// Include zlist.h after the defines
#include "zlist.h"
```

### Response
#### Success Response (200)
N/A (Configuration)

#### Response Example
N/A
```

--------------------------------

### C List Modification Macros

Source: https://github.com/z-libs/zlist.h/blob/main/README.md

Macros for adding, removing, and rearranging elements in C lists. `zlist_push_back` and `zlist_push_front` append/prepend elements, returning status codes. `zlist_pop_back` and `zlist_pop_front` remove elements from the ends. `zlist_insert_after` and `zlist_remove_node` modify specific positions, while `zlist_detach_node` removes a node without freeing it. `zlist_reverse` inverts the list order.

```c
#define zlist_push_back(l, val) ...
#define zlist_push_front(l, val) ...
#define zlist_pop_back(l) ...
#define zlist_pop_front(l) ...
#define zlist_insert_after(l, n, v) ...
#define zlist_remove_node(l, n) ...
#define zlist_detach_node(l, n) ...
#define zlist_reverse(l) ...
```

--------------------------------

### Safe API Error Handling with zerror.h and zlist.h

Source: https://github.com/z-libs/zlist.h/blob/main/README.md

Demonstrates the integration of zlist.h with zerror.h to provide a 'Safe API'. This API returns `zres` result types for operations, allowing for robust error handling, including stack traces on failure.

```c
zres res = zlist_push_back_safe(&list, 100);
if (zres_is_err(res))
{
    // Handle OOM with stack trace.
}
```

--------------------------------

### C API - Iteration Macros

Source: https://github.com/z-libs/zlist.h/blob/main/README.md

Macros for iterating through list elements in forward, reverse, and safe modes, with options for auto-declaration (GCC/Clang) or explicit declaration.

```APIDOC
## C API - Iteration Macros

### Description
Macros for iterating through list elements in forward, reverse, and safe modes, with options for auto-declaration (GCC/Clang) or explicit declaration.

### Method
Macros

### Endpoint
N/A (C Macros)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
// Forward iteration (GCC/Clang auto-declares 'it')
zlist_foreach(my_list, it) { ... }

// Safe forward iteration (GCC/Clang auto-declares 'it', 'tmp')
zlist_foreach_safe(my_list, it, tmp) { ... }

// Reverse iteration (GCC/Clang auto-declares 'it')
zlist_foreach_rev(my_list, it) { ... }

// Safe reverse iteration (GCC/Clang auto-declares 'it', 'tmp')
zlist_foreach_rev_safe(my_list, it, tmp) { ... }

// Portable C99 forward iteration (declares 'it')
zlist_foreach_decl(MyType, my_list, it) { ... }

// Portable C99 safe forward iteration (declares 'it', 'tmp')
zlist_foreach_safe_decl(MyType, my_list, it, tmp) { ... }

// Portable C99 reverse iteration (declares 'it')
zlist_foreach_rev_decl(MyType, my_list, it) { ... }

// Portable C99 safe reverse iteration (declares 'it', 'tmp')
zlist_foreach_rev_safe_decl(MyType, my_list, it, tmp) { ... }
```

### Response
#### Success Response (200)
N/A (Macros operate directly)

#### Response Example
N/A
```

--------------------------------

### C API - Modification Macros

Source: https://github.com/z-libs/zlist.h/blob/main/README.md

Macros for adding, removing, and rearranging nodes within a list in the C interface.

```APIDOC
## C API - Modification Macros

### Description
Macros for adding, removing, and rearranging nodes within a list in the C interface.

### Method
Macros

### Endpoint
N/A (C Macros)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
// Append value 'my_value' to the back of list 'my_list'
zlist_push_back(my_list, my_value)

// Prepend value 'my_value' to the front of list 'my_list'
zlist_push_front(my_list, my_value)

// Remove the tail node
zlist_pop_back(my_list)

// Remove the head node
zlist_pop_front(my_list)

// Insert 'new_value' after node 'existing_node'
zlist_insert_after(my_list, existing_node, new_value)

// Remove and free specific node 'node_to_remove'
zlist_remove_node(my_list, node_to_remove)

// Unlink node 'node_to_detach' without freeing
zlist_detach_node(my_list, node_to_detach)

// Reverse the list in-place
zlist_reverse(my_list)
```

### Response
#### Success Response (200)
N/A (Macros operate directly)

#### Response Example
N/A
```

--------------------------------

### C List Access and State Macros

Source: https://github.com/z-libs/zlist.h/blob/main/README.md

Macros to check the state and access elements within C lists. `zlist_is_empty` checks if the list has any nodes. `zlist_head`, `zlist_tail`, and `zlist_at` provide access to the first, last, and indexed nodes respectively, with `zlist_at` performing an O(N) scan.

```c
#define zlist_is_empty(l) ...
#define zlist_head(l) ...
#define zlist_tail(l) ...
#define zlist_at(l, idx) ...
```

--------------------------------

### Registering Custom Types for zlist.h in C

Source: https://github.com/z-libs/zlist.h/blob/main/README.md

Defines custom data structures and registers them for use with zlist.h using X-Macros. This allows the list implementation to be type-specific for user-defined types.

```c
#ifndef TYPES_H
#define TYPES_H

typedef struct { float x, y; } Point;

// Syntax: X(ValueType, ShortName).
#define REGISTER_ZLIST_TYPES(X) \
    X(int, Int)                 \
    X(Point, Point)

#include "zlist.h"

#endif
```

--------------------------------

### C++ list<T> Access and Modification Methods

Source: https://github.com/z-libs/zlist.h/blob/main/README.md

Methods for accessing and modifying elements within the C++ `z_list::list<T>` class. `front()` and `back()` access elements, potentially throwing `out_of_range`. `push_back()` and `push_front()` add elements, with `push_back` potentially throwing `bad_alloc`. `pop_back()`, `pop_front()`, `erase()`, and `reverse()` provide removal and reordering capabilities.

```cpp
class list<T> {
public:
  // ... constructors and management
  T& front();
  T& back();
  void push_back(const T& v);
  void push_front(const T& v);
  void pop_back();
  void pop_front();
  iterator erase(iterator it);
  void reverse();
  // ... other methods
};
```

--------------------------------

### Safe zlist Iteration with Element Removal (C)

Source: https://context7.com/z-libs/zlist.h/llms.txt

Illustrates how to safely iterate through a zlist and remove elements during traversal without corrupting the iteration process. It uses a temporary pointer (`safe`) to keep track of the next node. This requires including 'zlist.h' and registering the data types.

```c
#include <stdio.h>

#define REGISTER_ZLIST_TYPES(X) X(int, Int)
#define ZLIST_SHORT_NAMES
#include "zlist.h"

int main(void) {
    list(Int) nums = list_init(Int);

    list_push_back(&nums, 10);
    list_push_back(&nums, 20);
    list_push_back(&nums, 30);
    list_push_back(&nums, 40);
    list_push_back(&nums, 50);

    // Remove all even numbers safely during iteration
    printf("Removing even numbers...\n");
    list_foreach_safe(&nums, curr, safe) {
        if (curr->value % 20 == 0) {
            printf("Removing: %d\n", curr->value);
            list_remove_node(&nums, curr);
        }
    }

    printf("Remaining: ");
    list_foreach(&nums, iter) {
        printf("%d ", iter->value);
    }
    printf("\n");
    // Output: Remaining: 10 30 50

    list_clear(&nums);
    return 0;
}

```

--------------------------------

### Iterate zlist Forwards and Backwards (C)

Source: https://context7.com/z-libs/zlist.h/llms.txt

Shows how to iterate through all elements of a zlist from head to tail (forward) and tail to head (backward). On GCC/Clang, the iterator variable is auto-declared. This requires including 'zlist.h' and registering the data types.

```c
#include <stdio.h>

#define REGISTER_ZLIST_TYPES(X) X(int, Int)
#define ZLIST_SHORT_NAMES
#include "zlist.h"

int main(void) {
    list(Int) nums = list_init(Int);

    list_push_back(&nums, 10);
    list_push_back(&nums, 20);
    list_push_back(&nums, 30);

    // GCC/Clang: Auto-declares iterator
    printf("Forward: ");
    list_foreach(&nums, iter) {
        printf("%d ", iter->value);
    }
    printf("\n");
    // Output: Forward: 10 20 30

    // Reverse iteration
    printf("Reverse: ");
    list_foreach_rev(&nums, iter) {
        printf("%d ", iter->value);
    }
    printf("\n");
    // Output: Reverse: 30 20 10

    list_clear(&nums);
    return 0;
}

```

--------------------------------

### C++ API - class z_list::list<T>

Source: https://github.com/z-libs/zlist.h/blob/main/README.md

Methods for constructing, managing, accessing, and modifying list elements in the C++ wrapper.

```APIDOC
## C++ API - class z_list::list<T>

### Description
Methods for constructing, managing, accessing, and modifying list elements in the C++ wrapper within the `z_list` namespace.

### Method
Class Methods

### Endpoint
N/A (C++ Class)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```cpp
// Create a list of integers
z_list::list<int> my_list;

// Add elements
my_list.push_back(10);
my_list.push_front(5);

// Access elements (throws std::out_of_range if empty)
int first = my_list.front();
int last = my_list.back();

// Remove elements
my_list.pop_back();
my_list.pop_front();

// Clear the list
my_list.clear();

// Check if empty
if (my_list.empty()) { ... }

// Get size
size_t count = my_list.size();

// Reverse the list
my_list.reverse();
```

### Response
#### Success Response (200)
N/A (Methods operate directly)

#### Response Example
N/A
```

--------------------------------

### C List Iteration Macros (Smart and Explicit)

Source: https://github.com/z-libs/zlist.h/blob/main/README.md

Macros for iterating through C lists. 'Smart' macros (`zlist_foreach`, `zlist_foreach_safe`, `zlist_foreach_rev`, `zlist_foreach_rev_safe`) offer auto-declaration of loop variables on GCC/Clang. 'Explicit' macros (`zlist_foreach_decl`, `zlist_foreach_safe_decl`, `zlist_foreach_rev_decl`, `zlist_foreach_rev_safe_decl`) provide portable C99 variable declaration within the loop.

```c
#define zlist_foreach(l, it) ...
#define zlist_foreach_safe(l, it, tmp) ...
#define zlist_foreach_rev(l, it) ...
#define zlist_foreach_rev_safe(l, it, tmp) ...
#define zlist_foreach_decl(Name, l, it) ...
#define zlist_foreach_safe_decl(Name, l, it, tmp) ...
#define zlist_foreach_rev_decl(Name, l, it) ...
#define zlist_foreach_rev_safe_decl(Name, l, it, tmp) ...
```

--------------------------------

### C++ list<T> Class Methods

Source: https://github.com/z-libs/zlist.h/blob/main/README.md

The C++ interface for lists, encapsulated within the `z_list::list<T>` class. It provides constructors, a destructor, and methods for managing list size, emptiness, clearing, and moving elements (`splice`).

```cpp
class list<T> {
public:
  list();
  ~list();
  size_t size() const;
  bool empty() const;
  void clear();
  void splice(list& other);
  // ... other methods
};
```

--------------------------------

### Automatic List Cleanup with GCC/Clang Attributes (C)

Source: https://context7.com/z-libs/zlist.h/llms.txt

Illustrates automatic list cleanup in C using the `_cleanup_` attribute provided by GCC and Clang. The `list_autofree` macro ensures that the list is automatically deallocated when the scope in which it is declared ends, eliminating the need for manual `list_clear()` calls. This enhances code safety and reduces the risk of memory leaks.

```c
#include <stdio.h>

#define REGISTER_ZLIST_TYPES(X) X(int, Int)
#define ZLIST_SHORT_NAMES
#include "zlist.h"

void process_data(void) {
    // List is automatically cleared when function returns
    list_autofree(Int) nums = list_init(Int);

    list_push_back(&nums, 10);
    list_push_back(&nums, 20);
    list_push_back(&nums, 30);

    printf("Processing: ");
    list_foreach(&nums, iter) {
        printf("%d ", iter->value);
    }
    printf("\n");

    // No need to call list_clear() - cleanup is automatic!
}

int main(void) {
    process_data();
    printf("Function returned, list was auto-freed\n");
    return 0;
}
```

--------------------------------

### Register Types for zlist.h (C)

Source: https://context7.com/z-libs/zlist.h/llms.txt

Registers custom data types for use with the zlist library using X-Macros. This process generates type-safe list implementations at compile time, enabling the use of specific types like 'int' or custom structs. Ensure all desired types are defined within the REGISTER_ZLIST_TYPES macro before including 'zlist.h'.

```c
#include <stdio.h>

// Define custom types
typedef struct {
    float x, y;
} Point;

// Register types using X-Macro syntax: X(ValueType, ShortName)
#define REGISTER_ZLIST_TYPES(X) \
    X(int, Int)                 \
    X(Point, Point)

// Optional: Enable short names (list_push_back instead of zlist_push_back)
#define ZLIST_SHORT_NAMES
#include "zlist.h"

int main(void) {
    // Now you can use zlist_Int and zlist_Point
    zlist_Int nums = zlist_init(Int);
    zlist_Point points = zlist_init(Point);

    zlist_clear(&nums);
    zlist_clear(&points);
    return 0;
}
```

--------------------------------

### Portable zlist Iteration and Safe Removal (C99)

Source: https://context7.com/z-libs/zlist.h/llms.txt

Provides portable macros (`list_foreach_decl`, `list_foreach_safe_decl`) for iterating and safely removing elements from a zlist, ensuring compatibility with C99 compilers, including MSVC. This requires explicit declaration of the iterator variable.

```c
#include <stdio.h>

typedef struct { float x, y; } Point;

#define REGISTER_ZLIST_TYPES(X) 
    X(int, Int)                 
    X(Point, Point)

#define ZLIST_SHORT_NAMES
#include "zlist.h"

int main(void) {
    list(Point) points = list_init(Point);

    list_push_back(&points, ((Point){1.5f, 2.5f}));
    list_push_back(&points, ((Point){3.0f, 4.0f}));

    // Portable: Declares iter as zlist_node_Point* inside loop
    printf("Points:\n");
    list_foreach_decl(Point, &points, iter) {
        printf("  {%.1f, %.1f}\n", iter->value.x, iter->value.y);
    }
    // Output:
    //   {1.5, 2.5}
    //   {3.0, 4.0}

    // Portable safe iteration with removal
    printf("Clearing with portable safe iteration...\n");
    list_foreach_safe_decl(Point, &points, curr, safe) {
        printf("Removing {%.1f, %.1f}\n", curr->value.x, curr->value.y);
        list_remove_node(&points, curr);
    }

    list_clear(&points);
    return 0;
}

```

--------------------------------

### Insert Element After Node in zlist (C)

Source: https://context7.com/z-libs/zlist.h/llms.txt

Inserts a new element after a specified node in a zlist. If the provided node pointer is NULL, the element is inserted at the front of the list. This operation is efficient for linked list manipulation.

```c
#include <stdio.h>

#define REGISTER_ZLIST_TYPES(X) X(int, Int)
#define ZLIST_SHORT_NAMES
#include "zlist.h"

int main(void) {
    list(Int) nums = list_init(Int);

    list_push_back(&nums, 10);
    list_push_back(&nums, 30);
    // List: 10 -> 30

    // Insert 20 after the first node (10)
    list_node(Int) *first = list_head(&nums);
    list_insert_after(&nums, first, 20);
    // List: 10 -> 20 -> 30

    // Insert at front by passing NULL
    list_insert_after(&nums, NULL, 5);
    // List: 5 -> 10 -> 20 -> 30

    printf("List: ");
    list_foreach(&nums, iter) {
        printf("%d ", iter->value);
    }
    printf("\n");
    // Output: List: 5 10 20 30

    list_clear(&nums);
    return 0;
}

```

--------------------------------

### Merge Two zlists (Splice) (C)

Source: https://context7.com/z-libs/zlist.h/llms.txt

Moves all nodes from a source zlist to the end of a destination zlist in O(1) time. After the operation, the source list becomes empty. This is useful for efficiently combining lists or queues.

```c
#include <stdio.h>

#define REGISTER_ZLIST_TYPES(X) X(int, Int)
#define ZLIST_SHORT_NAMES
#include "zlist.h"

int main(void) {
    list(Int) main_queue = list_init(Int);
    list(Int) retry_queue = list_init(Int);

    // Main queue
    list_push_back(&main_queue, 1);
    list_push_back(&main_queue, 2);

    // Retry queue (failed items)
    list_push_back(&retry_queue, 100);
    list_push_back(&retry_queue, 200);

    printf("Before splice:\n");
    printf("  Main: ");
    list_foreach(&main_queue, iter) printf("%d ", iter->value);
    printf("\n  Retry: ");
    list_foreach(&retry_queue, iter) printf("%d ", iter->value);
    printf("\n");

    // Move all retry items to main queue
    list_splice(&main_queue, &retry_queue);

    printf("After splice:\n");
    printf("  Main: ");
    list_foreach(&main_queue, iter) printf("%d ", iter->value);
    printf("\n  Retry is empty: %s\n", list_is_empty(&retry_queue) ? "true" : "false");
    // Output:
    // Before splice:
    //   Main: 1 2
    //   Retry: 100 200
    // After splice:
    //   Main: 1 2 100 200
    //   Retry is empty: true

    list_clear(&main_queue);
    list_clear(&retry_queue);
    return 0;
}

```

--------------------------------

### Detach Node from zlist Without Freeing (C)

Source: https://context7.com/z-libs/zlist.h/llms.txt

Unlinks a node from a zlist without deallocating its memory, returning the detached node. This allows for manual memory management or moving the node to another list. The caller is responsible for freeing the detached node later using ZLIST_FREE.

```c
#include <stdio.h>
#include <string.h>

typedef struct {
    int id;
    char name[32];
} Job;

#define REGISTER_ZLIST_TYPES(X) X(Job, Job)
#define ZLIST_SHORT_NAMES
#include "zlist.h"

int main(void) {
    list(Job) queue = list_init(Job);
    list(Job) failed = list_init(Job);

    Job j1 = {101, "Process A"};
    Job j2 = {102, "Process B"};
    list_push_back(&queue, j1);
    list_push_back(&queue, j2);

    // Detach first job without freeing
    list_node(Job) *node = list_head(&queue);
    list_node(Job) *detached = list_detach_node(&queue, node);

    // Move to failed queue (reusing the value)
    list_push_back(&failed, detached->value);

    // Now manually free the detached node
    ZLIST_FREE(detached);

    printf("Queue: ");
    list_foreach(&queue, iter) {
        printf("%s ", iter->value.name);
    }
    printf("\n");
    // Output: Queue: Process B

    printf("Failed: ");
    list_foreach(&failed, iter) {
        printf("%s ", iter->value.name);
    }
    printf("\n");
    // Output: Failed: Process A

    list_clear(&queue);
    list_clear(&failed);
    return 0;
}

```

--------------------------------

### Remove Specific Node from zlist (C)

Source: https://context7.com/z-libs/zlist.h/llms.txt

Removes a specific node from a zlist in O(1) time. The function unlinks and frees the memory associated with the node. It's crucial to break the loop after removing a node as the iterator becomes invalidated.

```c
#include <stdio.h>

#define REGISTER_ZLIST_TYPES(X) X(int, Int)
#define ZLIST_SHORT_NAMES
#include "zlist.h"

int main(void) {
    list(Int) nums = list_init(Int);

    list_push_back(&nums, 10);
    list_push_back(&nums, 20);
    list_push_back(&nums, 30);

    // Find and remove the node containing 20
    list_foreach(&nums, iter) {
        if (iter->value == 20) {
            list_remove_node(&nums, iter);
            break;  // Must break - iterator is invalidated
        }
    }

    printf("After removing 20: ");
    list_foreach(&nums, iter) {
        printf("%d ", iter->value);
    }
    printf("\n");
    // Output: After removing 20: 10 30

    list_clear(&nums);
    return 0;
}

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.