WinDom: List Library

- Main Page
- Modules
- Data Structures
- Files
- Related Pages

# 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.