mirror of
https://github.com/RevCurtisP/C02.git
synced 2024-11-25 21:33:44 +00:00
180 lines
8.0 KiB
Plaintext
180 lines
8.0 KiB
Plaintext
Sta Functions
|
|
|
|
This library contains functions to access and manipulate a stack. The
|
|
entries on a stack are stored in contiguous bytes of memory.
|
|
|
|
Each element of the stack can vary in size from 1 to 255 bytes. Both
|
|
arrays and strings may be pushed onto and pulled off the stack.
|
|
|
|
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 functions are defined:
|
|
|
|
stkbgn(&b); Stack Begin: Sets the beginning of the stack
|
|
to address b.
|
|
|
|
The beginning of a stack is the first byte
|
|
of memory in the stack space.
|
|
|
|
Although stack space usually begins on a 256
|
|
byte boundary, this is not required.
|
|
|
|
Note: Sets variables stkslo and stkshi.
|
|
|
|
stkend(&e); Stack End: Sets the end of the stack to address
|
|
e. The end of a stack is the byte after the last
|
|
byte of memory in the stack space.
|
|
|
|
Although stack space usually ends on a 256
|
|
byte boundary, this is not required.
|
|
|
|
Note: Sets variables stkelo and steshi.
|
|
|
|
stkrst(); Stack Reset: Set stack pointer to stack begin
|
|
address.
|
|
|
|
This routine is called before populating a
|
|
stack with calls to the stkpsh function.
|
|
|
|
r = stkpsh(n ,&m); Stack Push: Creates a new entry at the end of
|
|
the stack consisting of n bytes of array m.
|
|
|
|
If n is 0 or the new entry would overflow the
|
|
end of the stack space, no entry is created and
|
|
a value of 0 is returned. Otherwise, the number
|
|
of bytes in the new entry is returned.
|
|
|
|
Note: Sets dstlo and dsthi to stkslo and stkhi
|
|
prior to the copy, updates stkslo and stkshi,
|
|
then calls the memcpy function.
|
|
|
|
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.
|
|
|
|
If the string is empty or the bew entry would
|
|
overflow the end of the stack space, no entry is
|
|
created and a value of 0 is returned. Otherwise,
|
|
the number of bytes in the new entry is returned.
|
|
|
|
Note: Calls the strlen function, then calls the
|
|
stkpsh function.
|
|
|
|
r = stkpop(&m); Stack Pop: Copies the bytes from the last entry of
|
|
the stack into array m and removes 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 dstlo and dsthi to the address of m,
|
|
updates stklo and stkhi to point to the beginning
|
|
of the last entry, sets srclo and srchi to stklo
|
|
and stkhi, then calls the memcpy function.
|
|
|
|
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.
|
|
|
|
If the stack is empty, the value 0 is returned.
|
|
Otherwise, the number of bytes in the entry is
|
|
returned.
|
|
|
|
Note: Calls stkpop, then restores stklo and stkhi
|
|
to their prior values.
|
|
|
|
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.
|
|
|
|
If the stack is empty or the new entry would
|
|
overflow the end of the stack space, no entry is
|
|
created and a value of 0 is returned. Otherwise,
|
|
the number of bytes in the new entry is returned.
|
|
|
|
Note: Sets dstlo and dsthi to the stklo and stkhi,
|
|
sets srclo and srchi to point to the beginning
|
|
of the last entry, updates stklo and stkhi, then
|
|
calls the memcpy function.
|
|
|
|
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.
|
|
|
|
If there are less than two entries in the stack
|
|
or the new entry would overflow the end of the
|
|
stack space, no entry is created and a value of
|
|
0 is returned. Otherwise, the number of bytes in
|
|
the new entry is returned.
|
|
|
|
Note: Sets dstlo and dsthi to the stklo and stkhi,
|
|
sets srclo and srchi to point to the beginning
|
|
of the second to last entry, updates stklo and
|
|
stkhi, then calls the memcpy function.
|
|
|
|
stkswp(n); 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.
|
|
|
|
If there are less than two entries in the stack
|
|
or there is not enough room in the stack space
|
|
to make a copy of the second to last entry, the
|
|
entries are not swapped and a value of 0 is
|
|
returned. Otherwise, the number of bytes in the
|
|
new last entry is returned.
|
|
|
|
Note: Calls stkovr, creating a copy of the second
|
|
to last stack entry, restores stklo and stkhi to
|
|
their original values, then calls the memcpy twice.
|
|
|
|
*,m,l = stkptr(); Stack Pointer: Returns the address contained in
|
|
the stack pointer as the most significant byte
|
|
and the least significant byte.
|
|
|
|
This is a utility function not normally used in
|
|
application code.
|
|
|
|
Note: Gets variables stkslo and stkshi.
|
|
|
|
stkset(&d); Stack Set: Sets stack pointer to address d.
|
|
|
|
This is a utility function not normally used in
|
|
application code.
|
|
|
|
Note: Sets variables stkslo and stkshi.
|
|
|
|
Note: This library expects the following functions to be defined
|
|
|
|
memcpl Copy memory (alternate entry point)
|
|
ressrc Restore source pointer
|
|
resrxy Restore X and Y registers
|
|
savrxy Save X and Y registers
|
|
setdst Set destination pointer
|
|
setsrc Set source pointer and initialize index
|
|
strlen Get string length
|
|
|
|
along with the zero page variable pairs
|
|
|
|
srclo, srchi Source String Pointer
|
|
dstlo, dsthi Destination String Pointer
|
|
stklo, stkhi stack Pointer
|
|
|
|
the static variable
|
|
|
|
stkslo, stkshi Stack Start Address
|
|
stkelo, stkehi Stack End Address
|
|
|
|
as well as the transient variables
|
|
|
|
temp0, temp1 Temporary storage
|
|
temp2, temp3
|