C02/doc/stack.txt

Sta Functions

This module contains functions to access and manipulate a stack 
of multi-byte entries stored in a contiguous section of memory.

Each entry of the stack consists of  1 to 255 bytes of data
followed by a single byte containing the number of data bytes,
allowing entries to be of different sizes. Entries may be
arrays, strings, or structs.

Usage: at the beginning of the program use the directives

  #include <stddef.h02>
  #include <memory.h02>
  #include <string.h02>
  #include <stack.h02>

The following application variables are defined:
  
  int stkbgn            Stack Begin: Address of the start of the stack.

  int stkend            Stack End: Address of the end of the stack.

  zeropage int stkptr   Stack Pointer: Current position in the stack.

                        The variables stkbgn and stkend must be set 
                        before calling any functions. A program can
                        use multiple stacks by saving and restoring
                        stkbgn, stkend, and stkptr.

The following application functions are defined:

  stkrst();             Stack Reset: Set stack pointer to stack begin 
                        address.

                        The first time s stack is used, this routine 
                        must be called after setting the variables 
                        stkbgn and stkend and before calling any other 
                        stack functions.

                        This routine can also be called to deallocate
                        all entries, effectively clearing the stack.

                        Note: Sets stkptr to stkbgn.

  r,i = stksiz();       Stack Size: Calculates and returns the current size
                        of the stack along with a flag indicating whether
                        the stack is populated or empty.
                        
                        Returns a char, which will be 255 (True) if the 
                        stack contains at least one entry, or 0 (False) if
                        the stack is empty, and int which is the size of
                        the stack.

                        Note: Subtracts stkbgn from stkptr.

  r = stkpsh(n,m);      Stack Push: Creates a new entry at the end of
                        the stack consisting of n bytes of array m.

                        Returns zero if n is 0 or an overflow would
                        occur. Otherwise, returns the the size of the
                        new entry.

                        Note: Sets srcptr to &m, dstptr to stkptr, 
                        updates stkptr, then calls memcpy().

  r = stkstr(s);        Stack String: Creates a new entry at the end of
                        the stack consisting the characters in string 
                        s, including the terminating ASCII null. This 
                        ensures that when the entry is popped off the
                        stack, the destination string will be properly
                        terminated.

                        Returns zero if s is empty or an overflow would
                        occur. Otherwise, returns the the size of the
                        new entry.

                        Note: Calls strlen(), then calls stkpsh().

  r = stkdup();         Stack Duplicate: Creates a new entry at the end 
                        of the stack consisting of the bytes in the last 
                        entry of the stack.

                        Returns zero if the stack is empty or an overflow 
                        would occur. Otherwise, returns the the size of 
                        the new entry.

                        Note: Sets dstptr to stkptr, sets srcptr to the 
                        beginning of the last entry, updates stkptr, 
                        then calls memcpy(). 

  r = stkovr();         Stack Over: Creates a new entry at the end of
                        the stack consisting of the bytes in the second 
                        to last entry of the stack.

                        Returns zero if the stack has less than two 
                        entries or an overflow would occur. Otherwise, 
                        returns the the size of the new entry.

                        Note: Sets dstptr to the stkptr and srcptr to 
                        the beginning of the second to last entry, 
                        updates stkptr then calls the memcpy().

  r = stkswp();         Stack Swap: Moves the last entry in the stack to
                        the second to last position and the second to 
                        last entry to the last position.

                        Returns zero if the stack has less than two 
                        entries or an overflow would occur. Otherwise, 
                        returns the the size of the new last entry.

                        Note: Saves stkptr, calls stkovr(), restores 
                        stkptr, then calls memcpy() twice.

  r = stktop(m);        Stack Top: Copies the bytes from the last entry 
                        of the stack into array m and leaves the entry 
                        on the stack.

                        Returns zero if the stack is empty. Otherwise, 
                        returns the the size of the new entry.

                        Note: Saves stkptr, calls stkpop(), then restores
                        stkptr.

  r = stkpop(m);        Stack Pop: Copies the bytes from the last entry 
                        of the stack into array m and deallocates the 
                        entry from the stack.

                        If the stack is empty, the value 0 is returned.
                        Otherwise, the number of bytes in the popped 
                        entry is returned.

                        Note: Sets dstptr to &m, sets stkptr to the 
                        beginning of the last entry, sets srcptr to 
                        stkptr, then calls the memcpy().

  r = stkdrp();         Stack Drop: Deallocates the last entry from the 
                        stack.

                        If the stack is empty, the value 0 is returned.
                        Otherwise, the number of bytes in the dropped 
                        entry is returned.

                        Note: Sets dstptr to &m, sets stkptr to the 
                        beginning of the last entry, sets srcptr to 
                        stkptr, then calls the memcpy().

The following utility functions are not normally used in applications:

Note: This module expects the following functions to be defined

  memcpy                Copy memory
  ressrc                Restore source pointer
  resrxy                Restore X and Y registers
  savrxy                Save X and Y registers
  setdst                Set destination pointer
  setsrc                Set source pointer
  strlen                Get string Length

along with the zero page integer variables
  
  srcptr                Source String Pointer 
  dstptr                Destination String Pointer
  stkptr                stack Pointer

the static integer variables

  stkbgn                Stack Start Address
  stkend                Stack End Address

and the transient variables 

  temp0, temp1, temp2   Temporary storage