stack.c

   File         : stack.c
   Description  : Stack Functions
   Category     : Utility
   Author       : Charles Yates

   STACK DLLEXP STACK_Init()
 
   Function     : STACK_Init
   Description  : Initialise a stack.
   Input        : void
   Output       : None.
   Returns      : STACK - initialised stack or NULL if an error occurs.

   int DLLEXP STACK_Push( STACK stack, void *addr, int len )
 
   Function     : STACK_Push
   Description  : Pushes an item on to the stack.
   Input        : STACK stack - stack to update
                  void *addr - address of memory to store
                  int len - length of data at addr (0 can be used for strings)
   Output       : Copy of addr is created and pushed onto stack.
   Returns      : int - 0 on success, <> 0 otherwise

   void * DLLEXP STACK_Pop( STACK stack, void *addr, int len )
 
   Function     : STACK_Pop
   Description  : Pops an item from the stack
   Input        : STACK stack - stack to update
                  void *addr - address of memory to update
                  int len - length of data at addr (0 can be used for strings)
   Output       : The current head of the stack is popped and it's contents
                  are copied into the address given
   Returns      : int - 0 on success, <> 0 otherwise

   void * DLLEXP STACK_Head( STACK stack )
 
   Function     : STACK_Head
   Description  : Convenience, allows the top of the stack to be examined
                  without removing from the stack.
   Input        : STACK stack - stack to query
   Output       : void
   Returns      : void * - address of stack entry at top of stack.

   int DLLEXP STACK_Count( STACK stack )
 
   Function     : STACK_Count
   Description  : Convenience, allows the number of items on the stack to be
                  queried.
   Input        : STACK stack - stack to query
   Output       : void
   Returns      : int - number of items on stack.

   void DLLEXP STACK_Close( STACK stack )
 
   Function     : STACK_Close
   Description  : Destroys the stack.
   Input        : STACK stack - stack to destroy
   Output       : All items in stack and the stack itself are destroyed.
   Returns      : void