List Update

NAME

    
DLL_AddRecord, DLL_InsertRecord, DLL_SwapRecord,
DLL_UpdateCurrentRecord, DLL_DeleteCurrentRecord,
DLL_DeleteEntireList

SYNOPSIS

#include <linklist.h>

DLL_Return DLL_AddRecord(List *list, Info *info,
                         int (*pFun)(Info *, Info *));
DLL_Return DLL_InsertRecord(List *list, Info *info,
                            DLL_InsertDir dir);
DLL_Return DLL_SwapRecord(List *list, DLL_InsertDir dir);
DLL_Return DLL_UpdateCurrentRecord(List *list,
                                   Info *record);
DLL_Return DLL_DeleteCurrentRecord(List *list);
DLL_Return DLL_DeleteEntireList(List *list);

DESCRIPTION

    
These functions manipulate the data in the link list. They all return the enumerated type DLL_Return and take as their first argument, list, the pointer returned by DLL_CreateList.

DLL_AddRecord

    
This function adds a new node and record to the link list. The second argument is a pointer to the Info structure where the new data is stored. The third argument is a pointer to a function used to sort the insertion of the new data. The return value of this function is identical to the return value of the strcmp function of the standard C library.

Where the return value is

   less than zero:     arg1 < arg2,

   zero:               arg1 == arg2, or

   greater than zero:  arg1 > arg2.

Below is an example of this function:

   int sort_foo(Info *record, Info *compare)
      {
      return(strcmp(record->info_element,
                    compare->info_element));
      }

If a NULL is passed instead of the function pointer no sorting will take place causing the next new node and record to be added to the tail of the list. A return value of DLL_MEM_ERROR indicates that memory could not be allocated and DLL_NORMAL indicates that the function succeeded in its task.

DLL_InsertRecord

    
This function adds a new node and record to the link list above or below current record. The new record will be current after completion. The second argument is a pointer to the Info structure where the new data is stored. The third argument is passed an enumerated define of type DLL_InsertDir.

typedef enum
   {
   DLL_INSERT_DEFAULT, /* Use current insert setting */
   DLL_ABOVE,          /* Insert new record ABOVE current record */
   DLL_BELOW           /* Insert new record BELOW current record */ 
   } DLL_InsertDir;

In the current version the value DLL_INSERT_DEFAULT is not used; it has been included for conformity to other like definitions and possible future expansion.

The value DLL_NOT_MODIFIED, if returned, indicates that a wrong value was passed in the argument dir; DLL_MEM_ERROR indicates that memory could not be allocated; and DLL_NORMAL indicates that the function succeeded in its task.

DLL_SwapRecord

    
This function swaps the current record up or down one place in the list. The swapped record will remain current after completion. The second argument is passed the same enumerated define of type DLL_InsertDir as the function DLL_InsertRecord above. The value DLL_NOT_MODIFIED, if returned, indicates that a value other than the type DLL_InsertDir was passed in the argument dir; DLL_NULL_LIST indicates that the list is empty and there are no nodes to swap; DLL_NOT_FOUND indicates that the current node is either at the head and cannot be swapped above or is at the tail and cannot be swapped below; and DLL_NORMAL indicates that the function succeeded in its task.

DLL_UpdateCurrentRecord

    
This function replaces the current data in an Info structure with updated data from the application. The entire structure gets overwritten so all elements in the updating structure will need to be present whether or not they have been changed. The second argument of this function is passed a pointer to an Info structure which contains the updated information. The value DLL_NULL_LIST, if returned, indicates that the list is empty and DLL_NORMAL indicates that the function succeeded in its task.

DLL_DeleteCurrentRecord

    
This function deletes the current Node and its Info structures from the list. The value DLL_NULL_LIST, if returned, indicates that the list is empty and DLL_NORMAL indicates that the function succeeded in its task.

DLL_DeleteEntireList

    
This function deletes all the Node and Info structures from the list. It does not delete the Top Level Struct allowing the application to add new records without having to reinitialize the list again. The value DLL_NULL_LIST, if returned, indicates that the list is empty and DLL_NORMAL indicates that the function succeeded in its task.

EXAMPLE

    
Examples of most of these functions can be seen in the source file dll_test.c used in the testing of the link list API.