mirror of
https://github.com/RevCurtisP/C02.git
synced 2024-06-01 05:41:34 +00:00
174 lines
7.3 KiB
Plaintext
174 lines
7.3 KiB
Plaintext
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
|