Power-Programmierung/CD1.mdf/pascal/library/dos/nicol/sti_stak/sti_stak.txt

Text File | 1990-08-22 | 13.0 KB | 529 lines

                                 GENERIC STACK SYSTEM 1.0

                               For Turbo Pascal Version 5.0












                                  Copyright 1990, 1991 By

                             Software Technology International

                                    All Rights Reserved






























                                            -1-
                                          NOTICE
                                          ------



                     All parts of this manual and the accompanying  soft-
                  ware  are  copyrighted material. You, as  a  registered
                  user, are granted permission to make as many copies  of
                  the  software, or manual, as you wish, as long as  they
                  are for your personal use. You may not copy this  soft-
                  ware,  or  manual,  in any form  whatsoever  for  usage
                  outside of your personal use. This includes, but is not
                  limited  to, duplication of the disk, the files on  the
                  disk or the manual, by manual or electronic means.



















































                                            -2-
                                     TABLE OF CONTENTS
                                     -----------------


                   Subject                                     Page
                   -----------------------------------------------------

                   GENERAL DESCRIPTION ......................   4
                     Introduction ...........................   4
                     The software ...........................   4

                   THE SOFTWARE IN DETAIL ...................   4
                     Functions and Procedures ...............   4
                     Usage Pointers .........................   7

                   INDEX ....................................   8

















































                                            -3-
                                GENERAL DESCRIPTION
                                    -------------------
                  Introduction
                  ------------

                     Welcome to Version 1.0 of Software Technology Inter-
                  nationals'  Generic Stack System. This group  of  func-
                  tions  will  enable your Turbo Pascal  Version  5.0  to
                  create stacks containing any data, and to have multiple
                  stacks  per program. The functions were written  to  be
                  flexible,  as fast as possible, and as easy to  use  as
                  possible.  We hope they live up to  your  expectations.
                  Please  feel free to write to us anytime with  bug  re-
                  ports or suggestions for future versions. If you are  a
                  registered  user, this will entitle you to a  free  up-
                  grade.
                     Remember  that  this  software  is  copyrighted,  so
                  please don't copy and distribute it, this is a  federal
                  offense.

                  The Software
                  ------------

                     These are a group of 4 procedures that allow you  to
                  create new stacks, destroy stacks, push data items, and
                  pop  data items. The kind of data you may stack can  be
                  any kind of valid Turbo Pascal data item.
                     The  procedures return error codes through a  single
                  variable to make error checking easy. They are  robust,
                  in that stack overflow or underflow will not crash  the
                  system (though HEAP overflow may).
                     The system can stack up to (65535 /  sizeof(Pointer)
                  = 16383) items per stack, though if the data items  are
                  large, you will surely run out of memory before then.































                                            -4-
                                  THE SOFTWARE IN DETAIL
                                  ----------------------


                  The Functions And Procedures
                  ----------------------------

                  Constants
                  ---------

                  MAXSTACK  = 16383;

                     This  is  the maximum number of items  that  may  be
                  stacked per stack.


                  STACK_ALL_OK    = 0;
                  STACK_OVERFLOW  = 1;
                  STACK_UNDERFLOW = 2;
                  STACK_NO_MEMORY = 3;

                     These are the error codes return through  STI_Stack-
                  Error. They are self explanatory.

                  Types
                  -----

                  STI_StackRec = array[1..MAXSTACK] of pointer;

                     This is an array type that enable easy access to the
                  stack itself.

                  STI_StackPtr = ^STI_Stack;

                     This is a pointer to a stack record. The  procedures
                  all expect a pointer like this to operate on.

                  STI_Stack    = record
                                   Stack  : ^STI_StackRec;
                                   Size   : word;
                                   StackP : word;
                                 end;

                     This is the actual declaration for the stack record.
                  Besides  the stack there are 2 variables. SIZE  is  the
                  size of the stack, and StackP is the stack pointer.  By
                  not actually using stack records, but rather a  pointer
                  to it, it makes it very easy to have multiple stacks.

















                                            -5-
                  Variables
                  ---------

                  STI_StackError : byte;

                     This  is the variable where all the error codes  are
                  passed. Having a single error variable makes it easy to
                  check for errors.


                  Procedures
                  ----------

                  procedure STI_Create_Stack(Var NewStack : STI_StackPtr;
                                                     Size : word);

                     This procedure creates a new stack from the  pointer
                  NEWSTACK. The SIZE parameter determines the actual size
                  of the stack. After creation the stack will occupy only
                  (Size x 4) + 4 bytes.

                  procedure STI_Destroy_Stack(
                                            Var OldStack : STI_StackPtr);

                     This  procedure is the opposite of  STI_Create_Stack
                  in  that it destroys the stack. It will use the  previ-
                  ously  assigned to the stack to free the  memory  used.
                  There is one point that needs to be watched for; if all
                  elements have not been popped, then the memory used  by
                  those will NOT be released.

                  procedure STI_Push(Var Stack : STI_StackPtr;
                                     Var Data;
                                         Size  : word);

                     This  procedure  pushes the DATA variable  onto  the
                  stack.  STACK must be a previously created  stack,  and
                  SIZE  must  be  the EXACT size of  the  DATA  variable,
                  otherwise  data  will be lost. If the  stack  is  over-
                  flowed, the data will not be stored.

                  procedure STI_Pop(Var Stack : STI_StackPtr;
                                    Var Data;
                                        Size  : word);

                     This procedure pops the stack into DATA. Again, SIZE
                  must  be the exact size of the DATA variable  otherwise
                  data  will  be lost AND memory will be wasted.  If  the
                  stack is underflowed, DATA will contain junk.
















                                            -6-
                                      USAGE POINTERS
                                      --------------

                     Basically,  these procedures are very easy  to  use.
                  With these procedures you may also push different sized
                  DATA  variables onto the stack AS LONG AS YOU POP  THEM
                  OFF  CORRECTLY. This is because, if the  SIZE  variable
                  passed to the STI_Pop procedure is wrong, you will lose
                  memory.

                     Another point to remember is that before  destroying
                  the stack, make sure all elements have been popped off,
                  otherwise, again, you will lose memory.

                     Other  than that, they are very simple, and  because
                  they  use a pointer, rather than a data record,  it  is
                  very easy to have multiple stacks per program.
















































                                            -7-
                                           INDEX
                                           -----

                    Topic                                     Page Number
                  -------------------------------------------------------

                 Constants.................................      5
                 Contents..................................      3
                 Copying...................................      2
                 Copyright.................................      2

                 Descriptions..............................      5

                 Error Codes...............................      6

                 Functions.................................      5

                 General Description.......................      4

                 Introduction..............................      4

                 Memory Usage..............................      6,7

                 Overflow..................................      4

                 Procedures................................      5,6

                 Return Codes..............................      5

                 Stack Overflow............................      6
                 Stack Size................................      4,5
                 STI_Create_Stack..........................      6
                 STI_Destroy_Stack.........................      6
                 STI_Pop...................................      6
                 STI_Push..................................      6
                 STI_Stack.................................      5
                 STI_StackError............................      6
                 STI_StackPtr..............................      5
                 STI_StackRec..............................      5

                 Types.....................................      5

                 Underflow.................................      4
                 Usage.....................................      7
                 Users.....................................      2

                 Variables.................................      6


















                                            -8-