00001 /*! \file array.h 00002 Header file for array.c 00003 */ 00004 00005 #include <stdlib.h> 00006 00007 /*! \brief Data structure that defines an array handler. 00008 */ 00009 00010 struct s_array { 00011 /*! \brief Pointer to the first element of the array. */ 00012 void *first_element; 00013 00014 /*! \brief Size of the array (maximum number of elements). */ 00015 int array_size; 00016 00017 /*! \brief Current number of elements in the array. */ 00018 int number_of_elements; 00019 00020 /*! \brief User defined function used to copy data from/to the array. 00021 \param src Pointer to the data to copy. 00022 \param dest Pointer to the destination. 00023 \return Upon successful completion the function returns 0, otherwise it returns 1. 00024 \warning <UL> 00025 <li><i>data</i> is copied from <i>src</i> to <i>dest</i>. 00026 <li>The function <i>copy_data()</i> <FONT COLOR="#FF0000"><B>MUST take care of memory management</B></FONT> 00027 (if required). 00028 </UL> 00029 */ 00030 int (*copy_data)(void *src, void *dest); 00031 00032 /*! \brief User defined function used to remove an element from the array (it may be necessary to free memory for example). 00033 \param target Pointer to the element to remove. 00034 \return Upon successful completion the function returns 0, otherwise it returns 1. 00035 */ 00036 int (*remove_data)(void *target); 00037 00038 /*! \brief User defined function used to compare two elements of the array. 00039 \param d1 Pointer to the first element. 00040 \param d2 Pointer to the second element. 00041 \return The function must return: 00042 <UL> 00043 <li>-1 if <i>d1 < d2</i> 00044 <li>0 if <i>d1 = d2</i> 00045 <li>+1 if <i>d1 > d2</i> 00046 <li>-2 if an error occured. 00047 </UL> 00048 */ 00049 int (*compare)(void *d1, void *d2); 00050 00051 /*! \brief User defined function that returns a pointer to the element which index is <i>idx</i>. 00052 \param start Pointer to the first element of the array. 00053 \param idx Index of the element. 00054 \return The function returns a pointer to the element which index is <i>idx</i>. 00055 \warning The gap between two elements of the array depends on the type of data stored. 00056 */ 00057 void* (*index)(void *start, int idx); 00058 00059 /*! \brief User defined function used to initialize data (may be a NULL pointer if no initialization is required). 00060 \param data Pointer to the data to initialize. 00061 \return Upon successful completion the function returns 0, otherwise it returns 1 00062 */ 00063 int (*init_data)(void *data); 00064 00065 /*! \brief Number of elements scheduled for removing. 00066 */ 00067 int element_to_remove; 00068 00069 /*! \brief Pointer to an array of integers that will receive the index to remove from the array. 00070 This array is allocated during the initialization of the array. You must free the memory using 00071 the function array_free(). 00072 */ 00073 int *to_remove; 00074 }; 00075 00076 /*! \brief C data type for the <i>array</i> handler. 00077 */ 00078 00079 typedef struct s_array Array; 00080 00081 /*! \Brief This macro returns the size of the array (that is, the maximum number of elements that can be stored in the array). 00082 */ 00083 00084 #define array_size(array) (array.array_size) 00085 00086 /*! \Brief This macro returns the current number of element in the array. 00087 */ 00088 00089 #define array_number_of_elements(array) (array.number_of_elements) 00090 00091 /*! \Brief This macro return a pointer on the first element in the array. 00092 */ 00093 00094 #define array_first_elem(array) (array.first_element) 00095 00096 /*! \Brief This macro returns the number of element to remove. 00097 */ 00098 00099 #define array_to_remove(array) (array.element_to_remove) 00100 00101 00102 int array_init ( 00103 Array *array, 00104 void *first_element, 00105 int size, 00106 int (*copy_data)(void *src, void *dest), 00107 int (*remove_data)(void *target), 00108 int (*compare)(void *d1, void *d2), 00109 void* (*index)(void *start, int idx), 00110 int (*init_data)(void *data) 00111 ); 00112 00113 void array_free (Array *array); 00114 00115 int array_init_element (Array *array); 00116 00117 int array_add ( 00118 Array *array, 00119 void *element 00120 ); 00121 00122 int array_rem ( 00123 Array *array, 00124 int idx 00125 ); 00126 00127 int array_insert ( 00128 Array *array, 00129 int idx, 00130 void *data 00131 ); 00132 00133 int array_schedule_for_rem (Array *array, int idx); 00134 00135 int array_rem_all (Array *array); 00136 00137 int array_find ( 00138 Array *array, 00139 void *data 00140 );