llist.h
=======

Implementation of a type-safe, generic doubly-linked list in C99.

Author:  Giovanni Santini
Mail:    giovanni.santini@proton.me
License: MIT


Documentation
-------------

This header provides a type-safe, generic doubly-linked list
implementation in C99, fully usable as a header-only library with
no dependencies.

The list supports:

  - O(1) push and pop at both the head and tail.
  - Iteration over elements via head/tail pointers.
  - Automatic tracking of list length.
  - Customizable value types and user-specified per-element free function.

Api:

   LLIST_DECLARE(prefix, type, free_fn)
       Declare a linked list for [type]
       Args:
         - prefix: define a prefix for the linked list functions and types.
         - type: the type of values stored in the linked list
         - free_fn: a function that will be called when a value gets deleted.
           It should have the following signature:

           void free_fn(type* value);

   prefix_llist
       The linked list type

   int prefix_llist_init(prefix_llist *list)
       Initialized a linked list with default values
       Returns 0 on success, or a negative LLIST_ERROR_ value otherwise.
       Remember to free the list when you are done with prefix_llist_free

   int prefix_llist_free(prefix_llist *list)
       Free all allocated memory from the list
       Returns 0 on success, or a negative LLIST_ERROR_ value otherwise.
       Time complexity: O(len)
   
   int prefix_llist_push_front(prefix_llist *list, type value)
       Adds [value] at the head of [list]
       Returns 0 on success, or a negative LLIST_ERROR_ value otherwise.
       Time complexity: O(1)

   int prefix_llist_push_back(prefix_llist *list, type value)
       Adds [value] at the tail of [list]
       Returns 0 on success, or a negative LLIST_ERROR_ value otherwise.
       Time complexity: O(1)

   int prefix_llist_pop_front(prefix_llist *list)
       Removes the head value from [list]
       Returns 0 on success, or a negative LLIST_ERROR_ value otherwise.
       Time complexity: O(1)

   int prefix_llist_pop_back(prefix_llist *list)
       Removes the tail value from [list]
       Returns 0 on success, or a negative LLIST_ERROR_ value otherwise.
       Time complexity: O(1)

   value* prefix_llist_head(prefix_llist *list)
       Returns a pointer to the head value from [list]
       In case of failure or if no head is found, returns NULL
       Time complexity: O(1)

   value* prefix_llist_tail(prefix_llist *list)
       Returns a pointer to the tail value from [list]
       In case of failure or if no tail is found, returns NULL
       Time complexity: O(1)

   int prefix_llist_len(prefix_llist *list)
       Returns the length of [list]
       In case of failure returns a negative LLIST_ERROR_
       Time complexity: O(1)


Usage
----

Just #include "llist.h".

You can tune the library by #defining the allocator and free
functions. See the "Config" comments under the "Configuration" section
in the header.

To create a linked list for a certain type you first need to
declare it using LLIST_DECLARE. You need to specify respectively
the prefix, the type, and the function to call when a value gets
deleted.  For example, the following code creates the type `Test`
and declares a linked list for this type:

   typedef int Test;  // This will be the value type stored in the list
   // Define a free function for the type in the list
   void test_free(Test* val) { printf("Value free\n"); return; }
   // Declare the list
   LLIST_DECLARE(test, Test, test_free)

Finally you can start using the list_* functions prefixed with your
specified name. Here is an example:

   int main(void)
   {
      test_llist list;
      test_llist_init(&list);

      test_llist_push_front(&list, 123);
      assert(test_llist_len(&list) == 1);
      assert(*test_llist_head(&list) == 123);
      assert(*test_llist_tail(&list) == 123);

      test_llist_free(&list);
      return 0;
   }


Code
----

The official git repository of llist.h is hosted at:

    https://github.com/San7o/llist.h

This is part of a bigger collection of header-only C99 libraries
called "micro-headers", contributions are welcome:

    https://github.com/San7o/micro-headers