next up previous contents
Next: Input/Output Up: Functions Previous: List Update

Search

NAME
    
DLL_FindRecord, DLL_FindNthRecord, DLL_GetCurrentRecord,
DLL_GetPriorRecord, DLL_GetNextRecord - Search Functions.

SYNOPSIS
#include <linklist.h>

DLL_Return DLL_FindRecord(List *list, Info *record,
            Info *match, int (*pFun)(Info *, Info *));
DLL_Return DLL_FindNthRecord(List *list, Info *record,
            unsigned long skip);
DLL_Return DLL_GetCurrentRecord(List *list, Info *record);
DLL_Return DLL_GetPriorRecord(List *list, Info *record);
DLL_Return DLL_GetNextRecord(List *list, Info *record);

DESCRIPTION
    
These functions retreive data from the list. They all return the enumerated type DLL_Return and take as their first argument list the pointer returned by DLL_CreateList.

DLL_FindRecord
    
This function returns in its second argument a record found using the criteria passed in its third argument based on the logic of a function passed as its forth argument. See DLL_SetSearchModes for setting the search direction and origin. The form of the passed in function containing the search criteria is the same as that used by the DLL_AddRecord, but in this case a NULL function pointer cannot be passed. It is shown below for convenience.

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(rcrd->info_element,
                    cmp->info_element));
      }

The value DLL_NULL_FUNCTION, if returned, indicates that a NULL was passed as the fourth argument; DLL_NULL_LIST indicates that the list is empty; DLL_NOT_FOUND indicates that a record could not be found; and DLL_NORMAL indicates that the function succeeded in its task.

DLL_FindNthRecord
    
This function returns in its second argument the record found by adding the skip value passed in the third argument to the index value of the current record. The skip value is an unsigned long integer. See DLL_SetSearchModes for setting the search direction and origin. The value DLL_NULL_LIST, if returned, indicates that the list is empty; DLL_NOT_FOUND indicates that a record could not be found in the list or that the skip value was out of range; and DLL_NORMAL indicates that the function succeeded in its task.

DLL_GetCurrentRecord
    
This function returns in its second argument the current record. 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_GetPriorRecord
    
This function returns in its second argument the record just prior to the current record. The value DLL_NULL_LIST, if returned, indicates that the list is empty; DLL_NOT_FOUND indicates that the current record is at the head of the list and there is no prior record; and DLL_NORMAL indicates that the function succeeded in its task.

DLL_GetNextRecord
    
This function returns in its second argument the record just after the current record. The value DLL_NULL_LIST, if returned, indicates that the list is empty; DLL_NOT_FOUND indicates that the current record is at the tail of the list and there is no next record; 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.


next up previous contents
Next: Input/Output Up: Functions Previous: List Update
Carl John Nobile
1999-07-07