---

epList.h File Reference

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

Include dependency graph for epList.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Compounds
struct	epList_s
struct	epListElt_s
Defines
#define	epDir_t   int
#define	_UNDETERMINED   0
#define	_FIFO   1
#define	_LIFO   2
Typedefs
typedef struct epList_s	epList_t
Functions
epList_t*	epList_create (const epDir_t direction, int (*elementDeallocatorFunction)(void *elt))
int	epList_destroy (epList_t *list)
int	epList_put (epList_t *list, const int indice, const void *elt)
void*	epList_get (epList_t *list, const int indice, const boolean_t removeFromList)
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))
int	epList_size (epList_t *list)
boolean_t	epList_isEmpty (epList_t *list)
int	epList_setElementPrintFunction ( epList_t *list, char *(*elementPrintFunction)(void *elt))
int	epList_printIt (epList_t *list, char *title)
void	epList_printElements (epList_t *list)

---

Detailed Description

Author(s):

Guillaume Bour. U.B.O 2000/2001

Version:

0.1.0

Date:

28/12/2000

Date:

28/02/2001 methods epList_access(), epList_printIt() and epList_setElementDeallocatorFunction() added.

Date:

16/11/2001 method epList_search() added.

Date:

21/11/2001 fixed bug in method epList_search(). step until i <(=) to.

Date:

25/11/2001 added title parameter to epList_printIt() function.

Undetermined direction list. Header file

Definition in file epList.h.

---

Define Documentation

#define _DIR_IS_VALID( dir )   (((dir)==_UNDETERMINED) || ((dir)==_FIFO) || ((dir)==_LIFO))

Definition at line 50 of file epList.h.

#define _DIR_TO_STRING( dir )   ((dir)==_FIFO?_sFIFO:((dir)==_LIFO?_sLIFO:_sUNDETERMINED))

Definition at line 51 of file epList.h.

#define _EPLIST_H_

Definition at line 25 of file epList.h.

#define _FIFO   1

FIFO list direction Definition at line 35 of file epList.h.

#define _LIFO   2

LIFO list direction Definition at line 37 of file epList.h.

#define _NORMAL   0

Definition at line 46 of file epList.h.

#define _REVERSE   1

Definition at line 47 of file epList.h.

#define _UNDETERMINED   0

undetermined list direction Definition at line 33 of file epList.h.

#define _sFIFO   "<fifo>"

Definition at line 41 of file epList.h.

#define _sLIFO   "<lifo>"

Definition at line 42 of file epList.h.

#define _sUNDETERMINED   "<none>"

Definition at line 40 of file epList.h.

#define epDir_t   int

list direction type Definition at line 31 of file epList.h.

#define searchDir_t   int

Definition at line 45 of file epList.h.

---

Typedef Documentation

typedef struct epList_s epList_t

The list structure

---

Function Documentation

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 )

Return the first list element matching criterion, using the comparisonFunction. visibility :: private Remarks: 1. the arguments taken by the comparisonFunction are the current list element and the criterion. 2. the direction is either _NORMAL (from the beginning of the list to the end) or _REVERSE (inverse search). this function return respectively the first/the last element matching the criterion. 3. indice (if != NULL) return the position of the found element. 4. the found element is NOT remove from the list. 5. we can make search on a subset of the list, from from to to. 6. if from equals -1, the search begin at the beginning/end of the list (depends on the direction value) 7. if to equals -1, the search end at the end/beginning of the list (depends on the direction value) Parameters: list   the considered list direction   the search direction from   begin-of-search indice to   end-of-search indice criterion   the search criterion comparisonFunction   the discriminatory function indice   the indice of the first matched element Returns: the match element if found, or <null> if no one are found. Definition at line 330 of file epList.c. Referenced by epList_rsearch(), and epList_search().

void * epList_access ( epList_t * list, const int indice )

Return the indiceth element of the list (in fact, it is only an encapsulation of epList_get(list, indice, false)). visibility :: public Remarks: see the epList_get remarks. Parameters: list   the considered list indice   the indice of the desired element Returns: the wanted element, or <null> of an error occur. Definition at line 287 of file epList.c.

epList_t * epList_create ( const epDir_t direction, int(* elementDeallocatorFunction)(void *elt) )

Create & initialize a new list. visibility :: public Remarks: If no element deallocator function is passed in argument (i.e. NULL), then the default pointer deallocator function is applied. Parameters: direction   the list direction elementDeallocatorFunction   the function used to deallocate an element Returns: the created list (a pointer) or NULL if an error occurs. Definition at line 62 of file epList.c. Referenced by epQueue_create(), and epStack_create().

int epList_destroy ( epList_t * list )

Destroy the list and all the elements contained into. visibility :: public Remarks: 1. REALLY DESTROY the elements, using the elementDeallocatorFunction function. 2. The return value is always 0. Parameters: list   the considered list Return values: 0   if OK, -1   else. Definition at line 101 of file epList.c. Referenced by epQueue_destroy(), and epStack_destroy().

void * epList_get ( epList_t * list, const int indice, const boolean_t removeFromList )

Return the indiceth element of the list and throw it out the list if removeFromList is set (equal <true>). visibility :: public Remarks: 1. if _FIFO or _LIFO direction is set, then indice is ignored and the first element is returned. 2. if indice is superior of n-1 (see 4.) then an error is generate & NULL is returned. 3. removeFromList DON'T REMOVE the element from memory but only throw it out of the list. 4. indice varies from 0 to n-1, where n is the number of list's elements, and 0 the first inserted element. Parameters: list   the considered list indice   the indice of the desired element removeFromList   <true> or <false> Returns: the wanted element, or <null> if an error occur. Definition at line 230 of file epList.c. Referenced by epList_access(), epQueue_out(), and epStack_pop().

boolean_t epList_isEmpty ( epList_t * list )

Return <true> is the list is empty, <false> else. visibility :: public @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 :-). So if a such error append, -1 is return (I know, its not proper!, I have to change it) Parameters: list   the considered list Return values: <true>   if the list is empty, <false>   if not. Definition at line 472 of file epList.c. Referenced by epQueue_isEmpty(), and epStack_isEmpty().

void epList_printElements ( epList_t * list )

Print the elements of the list. visibility :: private Warning: 1. some memory leaks may be encountered: if the elementPrintFunction allocate a new string, printElements don't free it. Parameters: list   the considered list Returns: <none>. Definition at line 558 of file epList.c. Referenced by epList_printIt(), epQueue_printIt(), and epStack_printIt().

int epList_printIt ( epList_t * list, char * title )

Print the content of the list (its parameters and all its elements). visibility :: public Warning: 1. some memory leaks may be encountered (see the printElements function). Parameters: list   the considered list title   a title to print ahead Return values: 0   if OK, -1   else. Definition at line 520 of file epList.c.

int epList_put ( epList_t * list, const int indice, const void * elt )

Insert a next-element at the specified indice into the list. visibility :: public Remarks: 1. if _FIFO or _LIFO direction is set, then indice is ignored (respectively insert at the end/beginning of the list). 2. if indice 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 infinite indice. 3. indice varies from 0 to n-1, where n is the number of list's elements, and 0 the first inserted element. Parameters: list   the considered list indice   the to-insert indice elt   the to-insert element Return values: 0   if OK, -1   else. Definition at line 144 of file epList.c. Referenced by epQueue_in(), and epStack_push().

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

Return the first list element matching criterion, using the comparisonFunction. visibility :: public Remarks: 1. search from end to begin of the list 4. the found element is NOT remove from the list. Parameters: list   the considered list criterion   the search criterion comparisonFunction   the discriminatory function Returns: the match element if found, or <null> if no one are found. Definition at line 432 of file epList.c.

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

Return the first list element matching criterion, using the comparisonFunction. visibility :: public Remarks: 1. search from begin to end of the list 4. the found element is NOT remove from the list. Parameters: list   the considered list criterion   the search criterion comparisonFunction   the discriminatory function Returns: the match element if found, or <null> if no one are found. Definition at line 406 of file epList.c.

int epList_setElementPrintFunction ( epList_t * list, char *(* elementPrintFunction)(void *elt) )

Initialize the elementPrintFunction for the use of the printIt function. visibility :: public Remarks: if you give a NULL eltPrintFunc, then only general list informations will be print on printIt function call. Parameters: list   the considered list elementPrintFunction   the function to use @reval 0 if OK, Return values: -1   else. Definition at line 495 of file epList.c. Referenced by epQueue_setElementPrintFunction(), and epStack_setElementPrintFunction().

int epList_size ( epList_t * list )

Return the size of the list (the number of elements contained into). visibility :: public Parameters: list   the considered list Returns: its size, or -1 if an error occur. Definition at line 449 of file epList.c. Referenced by epQueue_size(), and epStack_size().

---