ALIST(3)

NAME
alist - Doubly-linked lists

SYNOPSIS
#include <alist.h>

    typedef /* ... */ alist;
    alist	alist_new(void);
    alist	alist_copy(alist al);
    void	alist_delete(alist al);
    void	alist_clear(alist al);
    int	alist_count(alist al);
    int	alist_isempty(alist al);
    void *	alist_first(alist al);
    void *	alist_last(alist al);
    void *	alist_prev(alist al);
    void *	alist_next(alist al);
    void *	alist_current(alist al);
    int	alist_current_idx(alist al);
    void	alist_insert(alist al, unsigned int i, void *p);
    void	alist_prepend(alist al, void *p);
    void	alist_append(alist al, void *p);
    int	alist_remove(alist al);
    int	alist_remove_ptr(alist al, void *p);
    int	alist_remove_idx(alist al, unsigned int i);
    void *	alist_take(alist al);
    void *	alist_take_idx(alist al, unsigned int i);
    void	alist_sort(alist al, int (*cmp)(const void *p1, const void *p2));
    void *	alist_at(alist al, unsigned int i);
    int	alist_find(alist al, void *p);

DESCRIPTION
The alist library provides a high-level interface to doubly-linked lists.

The library provides one type: alist.

The alist_new() function allocates a new empty list.

The alist_copy() function allocates a new list and fills it with the items of the argument list al.

The alist_delete() function deallocates the argument list al.

The alist_clear() function removes all the items from the argument list al.

The alist_count() function returns the number of items contained in the argument list al.

The alist_isempty() function returns a zero value if the argument list al is empty, non-zero otherwise.

The alist_first() function returns the first item of the argument list al.

The alist_last() function returns the last item of the argument list al.

The alist_prev() function returns the previous item of the argument list al.

The alist_next() function returns the next item of the argument list al.

The alist_current() function returns the current item of the argument list al.

The alist_current_idx() function returns the current item index of the argument list al. The first item has a zero index, while the latest item has alist_count(al)-1 index.

The alist_insert() function inserts the p item at position i. Previously existing items at position i will be moved after the inserted item.

The alist_append() function appends the p item to the argument list al.

The alist_prepend() function prepends the p item to the argument list al.

The alist_remove() function removes the current item from the argument list al. The function will return a zero value if the operation was successful, -1 otherwise.

The alist_remove_ptr() function removes the argument item p from the argument list al. The function will return a zero value if the operation was successful, -1 otherwise.

The alist_remove_idx() function removes the item at index i from the argument list al. The function will return a zero value if the operation was successful, -1 otherwise.

The alist_take() function removes the current item from the argument list al. The function will return the removed item.

The alist_take_idx() function removes the item at index i from the argument list al. The function will return the removed item.

The alist_sort() functions sorts the argument list al using the comparison function pointed by the argument cmp.

The contents of the list are sorted in ascending order according to a comparison function pointed to by cmp, which is called with two arguments that point to the objects being compared. The comparison function must return an integer less than, equal to, or greater than zero if the first argument is considered to be respectively less than, equal to, or greater than the second. If two members compare as equal, their order in the sorted list is undefined.

The alist_at() function returns the item at index i contained in the argument list al.

The alist_find() function finds the first occurrence of the argument item p into the argument list al.

DEBUGGING
If you would like to debug your program, you should define the macro ALIST_NO_MACRO_DEFS before including the header of this library, i.e.

    #define ALIST_NO_MACRO_DEFS
    #include <alist.h>

This prevents defining at least the following function macros that makes code faster but debugging harder: alist_isempty(), alist_count(), alist_first(), alist_last(), alist_prev(), alist_next(), alist_current(), alist_current_idx(). Side effects (like incrementing the argument) in parameters of these macros should be avoided.

EXAMPLES
Sorting and printing a list of words:

    int sorter(const void *p1, const void *p2)
    {
    	return strcmp(*(char **)p1, *(char **)p2);
    }
    int main(void)
    {
    	alist al;
    	char *s;
    	al = alist_new();
    	alist_append(al, "long");
    	alist_append(al, "int");
    	alist_append(al, "double");
    	alist_append(al, "char");
    	alist_append(al, "float");
    	alist_sort(al, sorter);
    	for (s = alist_first(al); s != NULL; s = alist_next(al))
    		printf("Item #%d: %s\n",
    		       alist_current_idx(al) + 1, s);
    	alist_delete(al);
    	return 0;
    }

An address book:

    typedef struct person {
    	char *first_name;
    	char *last_name;
    	char *phone;
    } person;
    int sorter(const void *p1, const void *p2)
    {
    	person *pe1 = *(person **)p1, *pe2 = *(person **)p2;
    	int v;
    	if ((v = strcmp(pe1->last_name, pe2->last_name)) == 0)
    		v = strcmp(pe1->first_name, pe2->first_name);
    	return v;
    }
    int main(void)
    {
    	alist al;
    	person *p, p1, p2, p3, p4;
    	al = alist_new();
    	p1.first_name = "Joe";
    	p1.last_name = "Green";
    	p1.phone = "555-123456";
    	p2.first_name = "Joe";
    	p2.last_name = "Doe";
    	p2.phone = "555-654321";
    	p3.first_name = "Dennis";
    	p3.last_name = "Ritchie";
    	p3.phone = "555-314159";
    	p4.first_name = "Brian";
    	p4.last_name = "Kernighan";
    	p4.phone = "555-271828";
    	alist_append(al, &p1);
    	alist_append(al, &p2);
    	alist_append(al, &p3);
    	alist_append(al, &p4);
    	alist_sort(al, sorter);
    	for (p = alist_first(al); p != NULL; p = alist_next(al))
    		printf("Person #%d: %10s, %-10s Tel.: %s\n",
    		       alist_current_idx(al) + 1,
    		       p->first_name, p->last_name, p->phone);
    	alist_delete(al);
    	return 0;
    }

A list of lists:

    alist al1, al2, al3, al;
    char *s;
    al1 = alist_new();
    al2 = alist_new();
    al3 = alist_new();
    alist_append(al2, "obj1");
    alist_append(al2, "obj2");
    alist_append(al2, "obj3");
    alist_append(al3, "obja");
    alist_append(al3, "objb");
    alist_append(al3, "objc");
    alist_append(al1, al2);
    alist_append(al1, al3);
    for (al = alist_first(al1); al != NULL; al = alist_next(al1))
    	for (s = alist_first(al); s != NULL; s = alist_next(al))
    		printf("String: %s\n");
    alist_delete(al1);
    alist_delete(al2);
    alist_delete(al3);

AUTHORS
Sandro Sigala <sandro@sigala.it>