Pointer Manipulation

NAME
    
DLL_CurrentPointerToHead, DLL_CurrentPointerToTail,
DLL_IncrementCurrentPointer, DLL_DecrementCurrentPointer,
DLL_StoreCurrentPointer, DLL_RestoreCurrentPointer
-- Pointer Manipulation Functions.

SYNOPSIS
#include <linklist.h>

DLL_Return DLL_CurrentPointerToHead(List *list);
DLL_Return DLL_CurrentPointerToTail(List *list);
DLL_Return DLL_IncrementCurrentPointer(List *list);
DLL_Return DLL_DecrementCurrentPointer(List *list);
DLL_Return DLL_StoreCurrentPointer(List *list);
DLL_Return DLL_RestoreCurrentPointer(List *list);

DESCRIPTION
    
The current pointer in the link list keeps track of the last used node. In order for this to be of benefit there needs to be a way of controlling where this pointer is located within the list. These functions allow the repositioning and storing of this pointer during program execution.

All of these functions return the enumerated type DLL_Return and take only one argument list the pointer returned by DLL_CreateList.

DLL_CurrentPointerToHead
    
This function sets the current pointer to the head of the list and sets the index counter to 1. A return value of DLL_NULL_LIST indicates that the list has no nodes allocated and DLL_NORMAL indicates that the function succeeded in its task.

DLL_CurrentPointerToTail
    
This function sets the current pointer to the tail of the list and sets the index counter to the listsize counter. A return value of DLL_NULL_LIST indicates that the list has no allocated nodes and DLL_NORMAL indicates that the function succeeded in its task.

DLL_IncrementCurrentPointer
    
This function increments the current pointer and the index counter each by 1. A return value of DLL_NULL_LIST indicates that the list has no allocated nodes, DLL_NOT_FOUND indicates that the end of the list has been reached, and DLL_NORMAL indicates that the function succeeded in its task.

DLL_DecrementCurrentPointer
    
This function decrements the current pointer and the index counter each by 1. A return value of DLL_NULL_LIST indicates that the list has no allocated nodes, DLL_NOT_FOUND indicates that the beginning of the list has been reached, and DLL_NORMAL indicates that the function succeeded in its task.

DLL_StoreCurrentPointer
    
This function stores the current pointer and the index counter in the Top Level Struct for later retrieval. Only one value can be stored at a time so calling this function again will destroy the first stored pointer and index values. A return value of DLL_NOT_FOUND indicates that the list is empty and DLL_NORMAL indicates that the function succeeded in its task.

DLL_RestoreCurrentPointer
    
This function restores the current pointer and the index counter from the Top Level Struct. Since only one value can be stored at a time, calling this function again will return the last pointer and index values. A return value of DLL_NOT_FOUND 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.

Carl J. Nobile 2011-05-04