list.c

   File         : list.c
   Description  : Function Manipulations of listic Arrays
   Category     : Utility
   Author       : Charles Yates

   PLIST DLLEXP LIST_Init( int flags )
 
   Function     : LIST_Init
   Description  : Initialise a List Array.
   Input        : int flags - List behaviour flags
                    LIST_INIT_NORMAL    : Normal/Sparse array format
   Output       : None.
   Returns      : PLIST
                    An initialised List array
                    or NULL if an error occurs.

   void DLLEXP LIST_SetGrowth( PLIST list, int growth )
 
   Function     : LIST_SetGrowth
   Description  : Sets the growth factor of the list
   Input        : PLIST list - list to use
                  int growth - growth value to use
   Output       : list is updated to grow in quantities of growth
   Returns      : void

   int DLLEXP LIST_Prop( PLIST data, int prop, int index )
 
   Function     : LIST_Prop
   Description  : Returns property information about the given List array.
   Input        : PLIST data - The List array to examine.
                  int prop - The property to obtain
                    LIST_PROP_SIZE      : The size of the list
                    LIST_PROP_COUNT     : The number of initialised entries
                  int index - The entry to enquire on
   Output       : None.
   Returns      : int
                    The value of the requested property.

   int DLLEXP LIST_Count( PLIST data )
 
   Function     : int LIST_Count( PLIST data )
   Description  : Returns the number of populated items
   Input        : PLIST data - list structure to query
   Output       : void
   Returns      : int - number of items in the list

   int DLLEXP LIST_Get( PLIST data, int index, void *record, int length )
 
   Function     : LIST_Get
   Description  : Gets a copy of a value in the List.
   Input        : PLIST data - The List to obtain information from.
                  int index - The index to get the data from.
                  void *record - The variable to copy the information to.
                  int length - The length of the data to obtain.
   Output       : record contains a copy of value at Index.
   Returns      : int
                    LIST_OK when successful
                    LIST_ARR_RANGE when index is out of range
                    LIST_ARR_NULL when index is undefined

   void * DLLEXP LIST_GetPtr( PLIST data, int index )
 
   Function     : LIST_GetPtr
   Description  : Obtains the physical pointer of an item in the List.
   Input        : PLIST data - The List that is being examined.
                  int index - The index to get info from
   Output       : None.
   Returns      : Returns a pointer to the allocated memory in the structure
                  or NULL if it is unspecified.

   int DLLEXP LIST_Set( PLIST data, int index, void *record, int length )
 
   Function     : LIST_Set
   Description  : Sets a copy of a value in the List.
   Input        : PLIST data - The List to update.
                  int index - The index to update
                  void *record - The variable to copy the information from.
                  int length - The length of the data to copy.
   Output       : List( Index ) contains a copy of Record.
   Returns      : int
                    LIST_OK when successful
                    LIST_ARR_RANGE when index is out of range
                    LIST_MEM_FAIL when unable to allocate memory

   int DLLEXP LIST_DeleteRange( PLIST data, int index, int count )
 
   Function     : LIST_DeleteRange
   Description  : Deletes items in the List.
   Input        : PLIST data - The List to manipulate
                  int index - The position within the List
                  int count - number of items to delete
   Output       : List item specified is deleted and List is 'shrunk'
                  accordingly.
   Returns      : int
                    LIST_OK when successful
                    LIST_ERROR when unsuccessful

   int DLLEXP LIST_Delete( PLIST data, int index )
 
   Function     : LIST_Delete
   Description  : Deletes the item in the List.
   Input        : PLIST data - The List to manipulate
                  int index - The position within the List
   Output       : List item specified is deleted and List is 'shrunk'
                  accordingly.
   Returns      : int
                    LIST_OK when successful
                    LIST_ERROR when unsuccessful

   int DLLEXP LIST_Append( PLIST data, void *record, int length )
 
   Function     : LIST_Append
   Description  : Adds a copy of a value to the List.
   Input        : PLIST data - The List to update.
                  void *record - The variable to copy the information from.
                  int length - The length of the data to copy.
   Output       : The last item in the List contains a copy of Record.
   Returns      : int
                    LIST_OK when successful
                    LIST_ARR_RANGE when index is out of range
                    LIST_MEM_FAIL when unable to allocate memory

   int DLLEXP LIST_Clear( PLIST data )
 
   Function     : LIST_Clear
   Description  : Clears entries in the List array without destroying the
                  List structure.
   Input        : PLIST data - List to clear
   Output       : All items in data are removed.
   Returns      : int
                    LIST_OK when successful
                    LIST_FAIL when unsuccessful

   int DLLEXP LIST_Sort( PLIST list, int func( const void *, const void * ) )
 
   Function     : LIST_Sort
   Description  : Sort the list with the function given
   Input        : PLIST list - the list to sort
                  int (*func)( const void *, const void * ) - compare function
   Output       : list is sorted
   Returns      : 0 when successful

   int DLLEXP LIST_Close( PLIST data )
 
   Function     : LIST_Close
   Description  : The List specified is closed.
   Input        : PLIST data - The List to be closed
   Output       : data is destroyed.
   Returns      : int
                    LIST_OK when successful

   void DLLEXP LIST_Report( PLIST data, char *fileName )
 
   Function     : LIST_Report
   Description  : Outputs the contents of the array to the specified file.
   Input        : PLIST data - the List to be output.
                  char *fileName - the name of the file or NULL for stdout
   Output       : Contents of List are written to specified file.
   Returns      : void