Main Page   Alphabetical List   Data Structures   File List   Data Fields   Globals   Examples  

array.h

Go to the documentation of this file.
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                );

Generated on Thu Apr 3 16:23:42 2003 for Common_C_libraries by doxygen1.3-rc1