---

epList.h

Go to the documentation of this file.

#ifndef _EPLIST_H_
#define _EPLIST_H_

#include "epDefs.h"
#include "epUtils.h"

#define epDir_t           int  
#define _UNDETERMINED       0  
#define _FIFO               1  
#define _LIFO               2  

#define _sUNDETERMINED     "<none>"
#define _sFIFO             "<fifo>"
#define _sLIFO             "<lifo>"


#define searchDir_t       int
#define _NORMAL             0
#define _REVERSE            1

// ne marche pas sur plusieurs lignes ?!?!?!
#define _DIR_IS_VALID(dir) (((dir)==_UNDETERMINED) || ((dir)==_FIFO) || ((dir)==_LIFO)) 
#define _DIR_TO_STRING(dir) ((dir)==_FIFO?_sFIFO:((dir)==_LIFO?_sLIFO:_sUNDETERMINED))

struct epListElt_s {
  void *elt;                
  struct epListElt_s *prev, 
                     *next; 
};

typedef struct epList_s {
  epDir_t direction;        
  struct epListElt_s *head, 
                     *tail; 
  int numOfElements;        
  int (*elementDeallocatorFunction)(void *elt); 
  char *(*elementPrintFunction)(void *elt);     
} epList_t;


/* définition des messages d'erreur locaux */
/*static _ERROR_MSG[] = {
  "aaa",
  "bbb"
};
*/


/*
   Create & initialize a new list.<br>

   <b>visibility :: <i>public</i></b>

   @remarks
            If no <i>element deallocator function</i> is passed in argument 
            (i.e. <b>NULL</b>), then the default <i>pointer deallocator 
            function</i> is applied.

   @param   direction                   the list direction
   @param   elementDeallocatorFunction  the function used to deallocate an 
                                        element

   @return  the created list (a pointer) or <b>NULL</b> if an error occurs.
 */
epList_t *epList_create(const epDir_t direction, 
                        int (*elementDeallocatorFunction)(void *elt));

/*
   Destroy the list and all the elements contained into.<br>

   <b>visibility :: <i>public</i></b>

   @remarks
            1. <b>REALLY DESTROY</b> the elements, using the
               <i>elementDeallocatorFunction</i> function.<br>
            2. The return value is always <b>0</b>.

   @param   list  the considered list
   @retval     0  if OK,
   @retval    -1  else. 
 */
int epList_destroy(epList_t *list);

/*
   Insert a next-element at the specified indice into the list.<br>

   <b>visibility :: <i>public</i></b>

   @remarks  
             1. if <i>_FIFO</i> or <i>_LIFO</i> direction is set, then 
                <i>indice</i> is ignored (respectively insert at the 
                end/beginning of the list).<br>
             2. if <i>indice</i> is superior to the number of list's elements,
                then the new element is inserted at the list end. 
                So the best way to insert a new element at the end is to
                give the <i>infinite indice</i>.<br>
             3. <i>indice</i> varies from 0 to n-1, where n is the number of 
                list's elements, and 0 the first inserted element.

   @param    list    the considered list
   @param    indice  the to-insert indice
   @param    elt     the to-insert element 
   @retval        0  if <b>OK</b>,
   @retval       -1  else.
 */
int epList_put(epList_t *list, const int indice, const void *elt);

/*
   Return the <i>indice</i>th element of the list and throw it out the list 
   <b>if</b> <i>removeFromList</i> is set (equal <true>).<br>

   <b>visibility :: <i>public</i></b>

   @remarks  
             1. if <i>_FIFO</i> or <i>_LIFO</i> direction is set, then 
                <i>indice</i> is ignored and the first element is returned.<br>
             2. if <i>indice</i> is superior of n-1 (see <b>4.</b>) then an
                error is generate & NULL is returned.<br>
             3. <i>removeFromList</i> <b>DON'T REMOVE</b> the element from
                memory but only throw it out of the list.<br>
             4. <i>indice</i> varies from 0 to n-1, where n is the number of 
                list's elements, and 0 the first inserted element.

   @param    list               the considered list
   @param    indice             the indice of the desired element
   @param    removeFromList     <true> or <false>
   @return   the wanted element, or <null> if an error occur.
 */
void *epList_get(epList_t *list, const int indice, 
                 const boolean_t removeFromList);

/*
   Return the <i>indice</i>th element of the list (in fact, it is only an 
   encapsulation of <i>epList_get(list, indice, <b>false</b>)</i>).<br>

   <b>visibility :: <i>public</i></b>

   @remarks  
             see the <i>epList_get</i> remarks.

   @param    list               the considered list
   @param    indice             the indice of the desired element
   @return   the wanted element, or <null> of an error occur.
 */
void *epList_access(epList_t *list, const int indice);

void *__epList_search(const epList_t *list, const searchDir_t direction, 
                      int from, int to, const void *criterion, 
                      boolean_t (*comparisonFunction)
                      (const void *element, const void *criterion),
                      int *indice);

void *epList_search(const epList_t *list, const void *criterion, 
                    boolean_t (*comparisonFunction)
                    (const void *element, const void *criterion));

void *epList_rsearch(const epList_t *list, const void *criterion, 
                     boolean_t (*comparisonFunction)
                     (const void *element, const void *criterion));

/*
   Return the size of the list (the number of elements contained into).

   <b>visibility :: <i>public</i></b>

   @param   list      the considered list
   @return  its size,  or -1 if an error occur.
 */
int epList_size(epList_t *list);

/*
   Return <true> is the list is empty, <false> else.<br>

  <b>visibility :: <i>public</i></b>

  @remarks:
            With only a <true> or <false> value, we can't know if an error
            append(i.e. you give a NULL list in argument :-).<br>
            So if a such error append, -1 is return 
            (I know, its not proper!, I have to change it)<br>

  @param    list     the considered list
  @retval   <true>   if the list is empty,
  @retval   <false>  if not.
 */
boolean_t epList_isEmpty(epList_t *list);

/*
   Initialize the <i>elementPrintFunction</i> for the use of the
   <i>printIt</i> function.<br>

   <b>visibility :: <i>public</i></b>

   @remarks
             if you give a <b>NULL</b> eltPrintFunc, then only general list
             informations will be print on <i>printIt</i> function call.<br>

   @param    list                  the considered list
   @param    elementPrintFunction  the function to use
   @reval                      0  if <b>OK</b>,
   @retval                    -1  else.
 */
int epList_setElementPrintFunction(
  epList_t *list,
  char *(*elementPrintFunction)(void *elt));

int epList_printIt(epList_t *list, char *title);

/*
   Print the elements of the list.

   <b>visibility :: <i>private</i></b>

   @warning
            1. some memory leaks may be encountered: if the 
               <i>elementPrintFunction</i> allocate a new string, 
               <i>printElements</i> don't free it.<br>
 
   @param   list   the considered list
   @return         <none>.
 */
void epList_printElements(epList_t *list);

#endif  /* _EPLIST_H_ */

---