list_template.h

Go to the documentation of this file.

// Copyright (c) 2026 abxh
// SPDX-License-Identifier: MIT


 
#ifdef __cplusplus
#ifdef __GNUC__
#define restrict __restrict__
#else
#define restrict
#endif
extern "C" {
#endif
 
#include <stdbool.h>
#include <stddef.h>
 
// macro definitions: {{{

#ifndef PASTE
#define PASTE(a, b) a##b
#endif

#ifndef XPASTE
#define XPASTE(a, b) PASTE(a, b)
#endif

#ifndef JOIN
#define JOIN(a, b) XPASTE(a, XPASTE(_, b))
#endif

#ifndef NAME
#error "Must define NAME."
#define FUNCTION_DEFINITIONS
#define TYPE_DEFINITIONS
#else
#define LIST_NAME NAME
#endif

#ifndef FUNCTION_LINKAGE
#define FUNCTION_LINKAGE
#endif

#define LIST_NODE_TYPE        struct JOIN(LIST_NAME, node)
#define LIST_NODE_ADD_BETWEEN JOIN(JOIN(internal, LIST_NAME), node_add_between)
#define LIST_NODE_ATTACH      JOIN(JOIN(internal, LIST_NAME), node_attach)
#define LIST_NODE_INIT        JOIN(LIST_NAME, node_init)
#define LIST_NODE_IS_SINGULAR JOIN(LIST_NAME, node_is_singular)

#ifndef LIST_FOR_EACH
#define LIST_FOR_EACH(node_ptr, head_ptr) \
    for ((node_ptr) = (head_ptr)->next_ptr; (node_ptr) != (head_ptr); (node_ptr) = (node_ptr)->next_ptr)
#endif

#ifndef LIST_FOR_EACH_REVERSE
#define LIST_FOR_EACH_REVERSE(node_ptr, head_ptr) \
    for ((node_ptr) = (head_ptr)->prev_ptr; (node_ptr) != (head_ptr); (node_ptr) = (node_ptr)->prev_ptr)
#endif

#ifndef LIST_FOR_EACH_SAFE
#define LIST_FOR_EACH_SAFE(node_ptr, next_ptr, head_ptr)                                                 \
    for ((node_ptr) = (head_ptr)->next_ptr, (next_ptr) = (node_ptr)->next_ptr; (node_ptr) != (head_ptr); \
         (node_ptr) = (next_ptr), (next_ptr) = (node_ptr)->next_ptr)
#endif

#ifndef LIST_FOR_EACH_REVERSE_SAFE
#define LIST_FOR_EACH_REVERSE_SAFE(node_ptr, prev_ptr, head_ptr)                                         \
    for ((node_ptr) = (head_ptr)->prev_ptr, (prev_ptr) = (node_ptr)->prev_ptr; (node_ptr) != (head_ptr); \
         (node_ptr) = (prev_ptr), (prev_ptr) = (node_ptr)->prev_ptr)
#endif
 
// }}}
 
// type definitions: {{{
 
struct JOIN(LIST_NAME, node);

#ifdef TYPE_DEFINITIONS

struct JOIN(LIST_NAME, node) {
    LIST_NODE_TYPE *prev_ptr; 
    LIST_NODE_TYPE *next_ptr; 
};
 
#endif
 
// }}}
 
// function declarations: {{{

FUNCTION_LINKAGE void JOIN(LIST_NAME, node_init)(LIST_NODE_TYPE *node_ptr);

FUNCTION_LINKAGE bool JOIN(LIST_NAME, node_is_first)(const LIST_NODE_TYPE *head_ptr, const LIST_NODE_TYPE *node_ptr);

FUNCTION_LINKAGE bool JOIN(LIST_NAME, node_is_last)(const LIST_NODE_TYPE *head_ptr, const LIST_NODE_TYPE *node_ptr);

FUNCTION_LINKAGE bool JOIN(LIST_NAME, node_is_singular)(const LIST_NODE_TYPE *node_ptr);

FUNCTION_LINKAGE void JOIN(LIST_NAME, node_add_after)(LIST_NODE_TYPE *prev_ptr, LIST_NODE_TYPE *node_ptr);

FUNCTION_LINKAGE void JOIN(LIST_NAME, node_add_before)(LIST_NODE_TYPE *next_ptr, LIST_NODE_TYPE *node_ptr);

FUNCTION_LINKAGE LIST_NODE_TYPE *JOIN(LIST_NAME, node_remove)(LIST_NODE_TYPE *node_ptr);

FUNCTION_LINKAGE void JOIN(LIST_NAME, node_replace)(LIST_NODE_TYPE *restrict old_ptr, LIST_NODE_TYPE *restrict new_ptr);
 
// }}}
 
// function definitions: {{{

#ifdef FUNCTION_DEFINITIONS
 
#include <assert.h>

 
// Add a node between two (known) nodes.
static inline void JOIN(JOIN(internal, LIST_NAME), node_add_between)(LIST_NODE_TYPE *node_ptr,
                                                                     LIST_NODE_TYPE *before_ptr,
                                                                     LIST_NODE_TYPE *after_ptr)
{
    before_ptr->next_ptr = node_ptr;
    node_ptr->prev_ptr = before_ptr;
 
    after_ptr->prev_ptr = node_ptr;
    node_ptr->next_ptr = after_ptr;
}
 
// Attach two nodes together, so anything in between is ignored.
static inline void JOIN(JOIN(internal, LIST_NAME), node_attach)(LIST_NODE_TYPE *prev_ptr, LIST_NODE_TYPE *next_ptr)
{
    prev_ptr->next_ptr = next_ptr;
    next_ptr->prev_ptr = prev_ptr;
}

 
FUNCTION_LINKAGE void JOIN(LIST_NAME, node_init)(LIST_NODE_TYPE *node_ptr)
{
    assert(node_ptr != NULL);
 
    node_ptr->prev_ptr = node_ptr->next_ptr = node_ptr;
}
 
FUNCTION_LINKAGE bool JOIN(LIST_NAME, node_is_first)(const LIST_NODE_TYPE *head_ptr, const LIST_NODE_TYPE *node_ptr)
{
    assert(head_ptr != NULL);
    assert(node_ptr != NULL);
 
    return node_ptr->prev_ptr == head_ptr;
}
 
FUNCTION_LINKAGE bool JOIN(LIST_NAME, node_is_last)(const LIST_NODE_TYPE *head_ptr, const LIST_NODE_TYPE *node_ptr)
{
    assert(head_ptr != NULL);
    assert(node_ptr != NULL);
 
    return node_ptr->next_ptr == head_ptr;
}
 
FUNCTION_LINKAGE bool JOIN(LIST_NAME, node_is_singular)(const LIST_NODE_TYPE *node_ptr)
{
    assert(node_ptr != NULL);
 
    return node_ptr->prev_ptr == node_ptr && node_ptr->next_ptr == node_ptr;
}
 
FUNCTION_LINKAGE void JOIN(LIST_NAME, node_add_after)(LIST_NODE_TYPE *prev_ptr, LIST_NODE_TYPE *node_ptr)
{
    assert(prev_ptr != NULL);
    assert(node_ptr != NULL);
    assert(LIST_NODE_IS_SINGULAR(node_ptr));
 
    LIST_NODE_ADD_BETWEEN(node_ptr, prev_ptr, prev_ptr->next_ptr);
}
 
FUNCTION_LINKAGE void JOIN(LIST_NAME, node_add_before)(LIST_NODE_TYPE *next_ptr, LIST_NODE_TYPE *node_ptr)
{
    assert(next_ptr != NULL);
    assert(node_ptr != NULL);
    assert(LIST_NODE_IS_SINGULAR(node_ptr));
 
    LIST_NODE_ADD_BETWEEN(node_ptr, next_ptr->prev_ptr, next_ptr);
}
 
FUNCTION_LINKAGE LIST_NODE_TYPE *JOIN(LIST_NAME, node_remove)(LIST_NODE_TYPE *node_ptr)
{
    assert(node_ptr != NULL);
    assert(!LIST_NODE_IS_SINGULAR(node_ptr));
 
    LIST_NODE_ATTACH(node_ptr->prev_ptr, node_ptr->next_ptr);
    LIST_NODE_INIT(node_ptr);
 
    return node_ptr;
}
 
FUNCTION_LINKAGE void JOIN(LIST_NAME, node_replace)(LIST_NODE_TYPE *restrict old_ptr, LIST_NODE_TYPE *restrict new_ptr)
{
    assert(old_ptr != NULL);
    assert(new_ptr != NULL);
    assert(!LIST_NODE_IS_SINGULAR(old_ptr));
    assert(LIST_NODE_IS_SINGULAR(new_ptr));
 
    LIST_NODE_ADD_BETWEEN(new_ptr, old_ptr->prev_ptr, old_ptr->next_ptr);
    LIST_NODE_INIT(old_ptr);
}
 
#endif
 
// }}}
 
// macro undefs: {{{
#undef NAME
#undef FUNCTION_LINKAGE
#undef FUNCTION_DEFINITIONS
#undef TYPE_DEFINITIONS
 
#undef LIST_NAME
#undef LIST_NODE_TYPE
#undef LIST_NODE_ADD_BETWEEN
#undef LIST_NODE_ATTACH
#undef LIST_NODE_INIT
#undef LIST_NODE_IS_SINGULAR
// }}}
 
#ifdef __cplusplus
}
#endif
 
// vim: ft=c fdm=marker