.\" -*- nroff -*-
.\" $Id: alist.3,v 1.2 2001/07/15 13:32:18 sandro Exp $
.Dd February 12, 2001
.Os
.Dt ALIST 3
.Sh NAME
.Nm alist
.Nd Doubly-linked lists
.Sh SYNOPSIS
.Fd #include <alist.h>
.Bd -literal

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);
.Ed
.Sh DESCRIPTION
The
.Nm
library provides a high-level interface to doubly-linked lists.
.Pp
The library provides one type:
.Fa alist .
.Pp
The
.Fn alist_new
function allocates a new empty list.
.Pp
The
.Fn alist_copy
function allocates a new list and fills it with the items of the argument
list
.Fa al .
.Pp
The
.Fn alist_delete
function 
deallocates the argument list
.Fa al .
.Pp
The
.Fn alist_clear
function removes all the items from the argument list
.Fa al .
.Pp
The
.Fn alist_count
function returns the number of items contained in the argument list
.Fa al .
.Pp
The
.Fn alist_isempty
function returns a zero value if the argument list
.Fa al
is empty, non-zero otherwise.
.Pp
The
.Fn alist_first
function returns the first item of the argument list
.Fa al .
.Pp
The
.Fn alist_last
function returns the last item of the argument list
.Fa al .
.Pp
The
.Fn alist_prev
function returns the previous item of the argument list
.Fa al .
.Pp
The
.Fn alist_next
function returns the next item of the argument list
.Fa al .
.Pp
The
.Fn alist_current
function returns the current item of the argument list
.Fa al .
.Pp
The
.Fn alist_current_idx
function returns the current item index of the argument list
.Fa al .
The first item has a zero index, while the latest item has
.Fa alist_count(al)-1
index.
.Pp
The
.Fn alist_insert
function inserts the
.Fa p
item at position
.Fa i .
Previously existing items at position
.Fa i 
will be moved after the inserted item.
.Pp
The
.Fn alist_append
function appends the
.Fa p
item to the argument list
.Fa al .
.Pp
The
.Fn alist_prepend
function prepends the
.Fa p
item to the argument list
.Fa al .
.Pp
The
.Fn alist_remove
function removes the current item from the argument list
.Fa al .
The function will return
a zero value if the operation was successful, -1 otherwise.
.Pp
The
.Fn alist_remove_ptr
function removes the argument item
.Fa p
from the argument list
.Fa al .
The function will return
a zero value if the operation was successful, -1 otherwise.
.Pp
The
.Fn alist_remove_idx
function removes the item at index
.Fa i
from the argument list
.Fa al .
The function will return
a zero value if the operation was successful, -1 otherwise.
.Pp
The
.Fn alist_take
function removes the current item from the argument list
.Fa al .
The function will return the removed item.
.Pp
The
.Fn alist_take_idx
function removes the item at index
.Fa i
from the argument list
.Fa al .
The function will return the removed item.
.Pp
The
.Fn alist_sort
functions sorts the argument list
.Fa al
using the comparison function pointed by the argument
.Fa cmp .
.Pp
The contents of the list are sorted in ascending order
according to a comparison function pointed to by
.Fa 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.
.Pp
The
.Fn alist_at
function returns the item at index
.Fa i
contained in the argument list
.Fa al .
.Pp
The
.Fn alist_find
function finds the first occurrence of the argument item
.Fa p
into the argument list
.Fa al .
.Sh DEBUGGING
If you would like to debug your program, you should define the macro
.Fa ALIST_NO_MACRO_DEFS
before including the header of this library, i.e.
.Bd -literal -offset indent
#define ALIST_NO_MACRO_DEFS
#include <alist.h>
.Ed
.Pp
This prevents defining at least the following function macros that makes
code faster but debugging harder:
.Fn alist_isempty ,
.Fn alist_count ,
.Fn alist_first ,
.Fn alist_last ,
.Fn alist_prev ,
.Fn alist_next ,
.Fn alist_current ,
.Fn alist_current_idx .
Side effects (like incrementing the argument) in parameters of these macros
should be avoided.
.Sh EXAMPLES
Sorting and printing a list of words:
.Bd -literal -offset indent
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;
}
.Ed
.Pp
An address book:
.Bd -literal -offset indent
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;
}
.Ed
.Pp
A list of lists:
.Bd -literal -offset indent
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);
.Ed
.Sh AUTHORS
Sandro Sigala <sandro@sigala.it>