liststring.c

   File         : liststring.c
   Description  : String List Functions
   Category     : Utility
   Author       : Charles Yates

   PLIST DLLEXP LIST_StringSplit( char *string, char *joint )
 
   Function     : PLIST LIST_StringSplit( char *string, char *joint )
   Description  : Constructs a new list list which contains the entries of
                  string split on the joint provided.
   Input        : char *string - string to split
                  char *joint - string to split on
   Output       : void
   Returns      : A populated list.

   PLIST DLLEXP LIST_StringSplitAll( char *string, char *joint )
 
   Function     : PLIST LIST_StringSplitAll( char *string, char *joint )
   Description  : Constructs a new list list which contains the entries of
                  string split on the joint provided including empty strings
   Input        : char *string - string to split
                  char *joint - string to split on
   Output       : void
   Returns      : A populated list.

   int DLLEXP LIST_StringAppend( PLIST data, char *record )
 
   Function     : LIST_StringAppend
   Description  : Convenience function for appending strings to the list
   Input        : PLIST data - The List to update.
                  char *record - The variable to copy the information from.
   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

   char * DLLEXP LIST_StringJoin(PLIST list, char *output, char *joint, int start, int end)
 
   Function     : LIST_JoinString
   Description  : The string content of the list are joined and returned.
   Input        : PLIST list - The List to be closed
                  char *output - output string
                  char *joint - separator for output string
                  int start - first index to read from
                  int end - last index (-1 == end of list)
   Output       : output contains the joined data
   Returns      : char * - address of output

   int DLLEXP LIST_StringSort( PLIST list )
 
   Function     : LIST_Sort
   Description  : Sorts the List provided
   Preconditions: List structure must be initialised
   Input        : PSTRLIST List - List structure to update
   Output       : void
   Returns      : int
                    LIST_SUCCESS when successful
   Special Logic: 
   Physically sorts the information in the list. This function must be
   used with care: if any other part of the program is referencing the same
   list and it requires that the order to be preserved, then this sort
   should not be called (however, the list could be duplicated and the sort
   can freely be carried out on the duplicate).
  
   This function has been implemented using the standard C qsort API. NB:
   LIST_Compare is called for each comparison, and both items are received
   in that function as pointers to pointers.