#ifndef ITERATOR_UTILITY_H
#define ITERATOR_UTILITY_H

// header files
#include "LLDataEngine.h"

typedef struct IteratorStruct
   {
    StateLLType *iterData;

    int currentIndex;
   } IteratorType;

// function prototypes

/*
Name: clearIterator
Process: clears the StateDataType sub-structure, and then the IteratorType
Function input/parameters: pointer to IteratorType (IteratorType *)
Function output/parameters: none
Function output/returned: NULL
Device input/---: none
Device output/---: none
Dependencies: clearDataStructure, free
*/
IteratorType *clearIterator( IteratorType *iterator );

/*
Name: createIterator
Process: initializes the IteratorType,
         and then the StateDataType sub-structure
Function input/parameters: initial capacity (int)
Function output/parameters: none
Function output/returned: pointer to initialized IteratorType (IteratorType *)
Device input/---: none
Device output/---: none
Dependencies: malloc, createDataStructure
*/
IteratorType *createIterator( int initialCapacity );

/*
Name: getFirst
Process: gets first value in iterator, returns true,
         returns false otherwise
Function input/parameters: pointer to IteratorType (IteratorType *)
Function output/parameters: return value (StateDataType *)
Function output/returned: Boolean result of operation
Device input/---: none
Device output/---: none
Dependencies: getItemAtIndex
*/
bool getFirst( IteratorType *iterator, StateDataType *returned );

/*
Name: getLast
Process: gets last value in iterator, returns true,
         returns false otherwise
Function input/parameters: pointer to IteratorType (IteratorType *)
Function output/parameters: return value (StateDataType *)
Function output/returned: Boolean result of operation
Device input/---: none
Device output/---: none
Dependencies: getItemAtIndex, getListSize
*/
bool getLast( IteratorType *iterator, StateDataType *returned );

/*
Name: getNext
Process: gets next value in iterator if available, returns true,
         otherwise, sets return value to empty, returns false
Function input/parameters: pointer to IteratorType (IteratorType *)
Function output/parameters: return value (StateDataType *)
Function output/returned: Boolean result of operation
Device input/---: none
Device output/---: none
Dependencies: getItemAtIndex, getListSize
*/
bool getNext( IteratorType *iterator, StateDataType *returned );

/*
Name: getPrevious
Process: gets previous value in iterator if available, returns true,
         otherwise, sets return value to empty, returns false
Function input/parameters: pointer to IteratorType (IteratorType *)
Function output/parameters: return value (StateDataType *)
Function output/returned: Boolean result of operation
Device input/---: none
Device output/---: none
Dependencies: getItemAtIndex
*/
bool getPrevious( IteratorType *iterator, StateDataType *returned );

/*
Name: insertAfterCurrentIndex
Process: inserts value immediately after currentIndex, if possible, returns true,
         otherwise, sets return value to empty, returns false
Function input/parameters: pointer to IteratorType (IteratorType *),
                           value to be inserted (const StateDataType)
Function output/parameters: none
Function output/returned: Boolean result of operation
Device input/---: none
Device output/---: none
Dependencies: insertItemAtIndex, getListSize
*/
bool insertAfterCurrentIndex( IteratorType *iterator, 
                                             const StateDataType toBeInserted );

/*
Name: insertAtCurrentIndex
Process: inserts value at currentIndex, if possible, returns true
         otherwise, sets return value to empty, returns false
Function input/parameters: pointer to IteratorType (IteratorType *),
                           value to be inserted (const StateDataType)
Function output/parameters: none
Function output/returned: Boolean result of operation
Device input/---: none
Device output/---: none
Dependencies: insertItemAtIndex
*/
bool insertAtCurrentIndex( IteratorType *iterator, 
                                             const StateDataType toBeInserted );

/*
Name: removeAtCurrentIndex
Process: removes value at current index if possible, returns true,
         otherwise, sets return value to empty, returns false
Function input/parameters: pointer to IteratorType (IteratorType *),
                           value to be remove (StateDataType *)
Function output/parameters: pointer to updated IteratorType (IteratorType *),
                            pointer to item removed (StateDataType *)
Function output/returned: Boolean result of operation
Device input/---: none
Device output/---: none
Dependencies: removeItemAtIndex, getListSize
*/
bool removeAtCurrentIndex( IteratorType *iterator, StateDataType *removedItem );


#endif   // ITERATOR_UTILITY_H