list.h

Go to the documentation of this file.

/**
 \file list.h
 
 \brief Double linked list code
 */

#ifndef LS_DEFINED
#define LS_DEFINED

#ifdef __cplusplus
extern "C" {
#endif


/* This can be typedef'ed to void if supported */
/* typedef struct ls_dummy_defn {
    int dummy;          // Not used
} ls_dummy;
*/

typedef void ls_dummy;

typedef ls_dummy *lsList;   /* List handle           */
typedef ls_dummy *lsGen;    /* List generator handle */
typedef ls_dummy *lsHandle; /* Handle to an item     */
typedef int lsStatus;       /* Return codes          */
typedef char *lsGeneric;    /* Generic pointer       */

#define LS_NIL      0   /* Nil for lsList       */

#define LS_BADSTATE -3  /* Bad generator state   */
#define LS_BADPARAM -2  /* Bad parameter value   */
#define LS_NOMORE   -1  /* No more items         */

#define LS_OK       0

#define LS_BEFORE   1   /* Set spot before object */
#define LS_AFTER    2   /* Set spot after object  */
#define LS_STOP     3   /* Stop generating items  */
#define LS_DELETE   4   /* Delete generated item  */

/*
 * For all those routines that take a handle,  this macro can be
 * used when no handle is required.
 */

#define LS_NH       (lsHandle *) 0

typedef lsGeneric (*LS_PFLSG) ();

extern lsList lsCreate (void);
  /* Create a new list */
extern lsStatus lsDestroy (lsList, void (*)());
  /* Delete a previously created list */
extern lsList lsCopy (lsList, LS_PFLSG);
   /* Copies the contents of a list    */

extern lsStatus lsFirstItem (lsList, lsGeneric *, lsHandle *);
  /* Gets the first item of a list */
extern lsStatus lsLastItem (lsList, lsGeneric *, lsHandle *);
  /* Gets the last item of a list */

extern lsStatus lsNewBegin (lsList, lsGeneric, lsHandle *);
  /* Add item to start of list */
extern lsStatus lsNewEnd (lsList, lsGeneric, lsHandle *);
  /* Add item to end of list */

extern lsStatus lsDelBegin (lsList, lsGeneric *);
  /* Delete first item of a list */
extern lsStatus lsDelEnd (lsList, lsGeneric *);
  /* Delete last item of a list */

extern int lsLength (lsList);
  /* Returns the length of the list */

extern lsGen lsStart (lsList);
  /* Begin generation of items in a list */
extern lsGen lsEnd (lsList);
  /* Begin generation at end of list */
extern lsGen lsGenHandle (lsHandle, lsGeneric *, int);
  /* Produces a generator given a handle */
extern lsStatus lsNext (lsGen, lsGeneric *, lsHandle *);
  /* Generate next item in sequence */
extern lsStatus lsPrev (lsGen, lsGeneric *, lsHandle *);
  /* Generate previous item in sequence */
extern lsStatus lsInBefore (lsGen, lsGeneric, lsHandle *);
  /* Insert an item before the most recently generated by lsNext */
extern lsStatus lsInAfter (lsGen, lsGeneric, lsHandle *);
  /* Insert an item after the most recently generated by lsNext  */
extern lsStatus lsDelBefore (lsGen, lsGeneric *);
  /* Delete the item before the current spot */
extern lsStatus lsDelAfter (lsGen, lsGeneric *);
  /* Delete the item after the current spot */
extern lsStatus lsFinish (lsGen);
  /* End generation of items in a list */

extern lsList lsQueryHandle (lsHandle);
  /* Returns the list of a handle */
extern lsGeneric lsFetchHandle (lsHandle);
  /* Returns data associated with handle */
extern lsStatus lsRemoveItem (lsHandle, lsGeneric *);
  /* Removes item associated with handle from list */

extern lsStatus lsSort (lsList, int (*)());

  /* Sorts a list */
extern lsStatus lsUniq (lsList, int (*)(), void (*)());
  /* Removes duplicates from a sorted list */
/*
 * Macro to iterate the items of a list.Note the following:
 * 1) in a for loop, the test is evaluate before the first time through the body
 * 2) the logical OR operator guarantees left to right evaluation, and the second
 *    operand is not evaluated if first operand evaluates to non-zero
 * 3) the comma operator returns the value of its second argument.
 */
#define lsForEachItem(                                         \
  list,  /* lsList, list to iterate */                         \
  gen,   /* lsGen, local variable for iterator */              \
  data   /* lsGeneric, variable to return data */              \
)                                              \
  for(gen = lsStart(list);                     \
      (lsNext(gen, (lsGeneric *) &data, LS_NH) == LS_OK)       \
      || ((void) lsFinish(gen), 0);                            \
      )

#ifdef __cplusplus
}
#endif

#endif