List Library
[Reference documentation]

Some usefull functions and macro to handle a double chained list of any type of structure. More...

Data Structures
struct	Linkable
	element used to link structures each others More...
struct	LIST
	definition of a list of linked structures More...
struct	LinkablePtr
Defines
#define	listEmptyListInitializer()   {{NULL,NULL},{NULL,NULL}}
	this is a zero-ed LIST data
#define	listForEach(type, i, list)
	usefull macro to parse all elements of a list.
#define	listRewind(list)   &((list)->head)
	return the very first LINKABLE object of the list (before the first element linked)
#define	listEnd(list)   &((list)->tail)
	return the very last LINKABLE object of the list (after the last element linked)
#define	listNext(iter)   ((!((LINKABLE*)iter)->next->next) ? NULL : (((LINKABLE*)iter)->next))
	return the next element on list.
#define	listPrev(iter)   ((!((LINKABLE*)iter)->prev->prev) ? NULL : (((LINKABLE*)iter)->prev))
	return the previous element on list.
#define	listIsEmpty(list)   ( ((list)->head.next) == (&(list)->tail))
	return if the list is empty or not
#define	listFirst(list)   ( ((list)->head.next) == (&(list)->tail) ? NULL : ((list)->head.next))
	return the first linked element of the list (the LINKABLE object right after listRewind), or NULL if the list is empty
#define	listLast(list)   ( ((list)->tail.prev) == (&(list)->head) ? NULL : ((list)->tail.prev))
Typedefs
typedef Linkable	LINKABLE
	element used to link structures each others
typedef LinkablePtr	LINKABLEPTR
Functions
LIST *	createList (void)
	create an empty list
LIST *	listSplice (LIST *list, LINKABLE *first, LINKABLE *pastLast)
	splice a list (extract a part of a list)

---

Detailed Description

Some usefull functions and macro to handle a double chained list of any type of structure.

Heavily internally used by windom.

---

Define Documentation

#define listEmptyListInitializer (   )     {{NULL,NULL},{NULL,NULL}}

this is a zero-ed LIST data Warning: such list won't be reconized as an empty list. You should call listInit() to properly initialise/zero/empty a list.

#define listEnd (  list   )     &((list)->tail)

return the very last LINKABLE object of the list (after the last element linked)

#define listFirst (  list   )     ( ((list)->head.next) == (&(list)->tail) ? NULL : ((list)->head.next))

return the first linked element of the list (the LINKABLE object right after listRewind), or NULL if the list is empty

#define listForEach (  type, i, list   )

Value: if ( list ) for( i=(type)(list)->head.next; \ ((LINKABLE*)i) != &(list)->tail; \ i=(type)((LINKABLE*)i)->next ) usefull macro to parse all elements of a list. Parameters: type  is the type of the structure (to cast the i data) i  is the data to use in for loop. This data should be of the type type. list  is the list to parse. This macro is based on a real for instruction, so you may leave this loop by using the break instruction. Very important: the first data of the type structure must be a LINKABLE data. Exemple of use: typedef struct { LINKABLE link; int other_datas; } ELT; LIST *list; ELT *e; (...) listForEach( ELT*, e, list) { int found; if (e->other_datas) found = do_stuff(e); else found = do_other_stuff(e); if (found) break; }

#define listIsEmpty (  list   )     ( ((list)->head.next) == (&(list)->tail))

return if the list is empty or not

#define listLast (  list   )     ( ((list)->tail.prev) == (&(list)->head) ? NULL : ((list)->tail.prev))

#define listNext (  iter   )     ((!((LINKABLE*)iter)->next->next) ? NULL : (((LINKABLE*)iter)->next))

return the next element on list. If the end of the list is reached (that is if the next element is the very last LINKABLE object of the list)

#define listPrev (  iter   )     ((!((LINKABLE*)iter)->prev->prev) ? NULL : (((LINKABLE*)iter)->prev))

return the previous element on list. If the begin of the list is reached (that is if the previous element is the very first LINKABLE object of the list)

#define listRewind (  list   )     &((list)->head)

return the very first LINKABLE object of the list (before the first element linked)

---

Typedef Documentation

typedef struct Linkable LINKABLE

element used to link structures each others This data shall be set at the very first place of the structure if you want all the macro to work correctly.

typedef struct LinkablePtr LINKABLEPTR

---

Function Documentation

LIST* createList (  void   )

create an empty list Returns: a pointer to a new LIST, or NULL in case of failure. The list returned has been mallocated and initialised (listInit()). Don't forget to free() this LIST at the end.

LIST* listSplice (  LIST *  list, LINKABLE *  first, LINKABLE *  pastLast )

splice a list (extract a part of a list) Parameters: list  will contain the extracted list first  is the first element of the extract pastLast  is the element after the last element of the extract Returns: list Prerequise: a list of element exists. The elements first and pastLast are in this list of element. first must be ranged before pastLast in the list. This function will extract the element from first (included) to pastLast (excluded), and create a new list with these element. This is the list stored in list. These elements are removed from the original list.

---