home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / snip9707.zip / STACK.H < prev    next >
C/C++ Source or Header  |  1997-07-05  |  5KB  |  95 lines
  1. /* +++Date last modified: 05-Jul-1997 */
  2.  
  3. /* =======================================================================
  4.     STACK.h     Stack manager.
  5.                 A.Reitsma, Delft, Nederland.
  6.  
  7.                 v0.25  94-07-03  Public Domain.
  8.  
  9.  -  Four default stacks are created by StackSystemInit. User stacks must
  10.     be created by StackCreate; which may fail on insufficient memory.
  11.  -  Initially a stack has space for 32 items and can/will be grown (auto-
  12.     matically) in steps of 16 items as long as there is sufficient memory
  13.     space. Therefore the maximum ItemSize is 2kB.
  14.     In the DEBUG version -- NDEBUG not defined during compilation of
  15.     STACKS.c -- the maximum is actually restricted to 1kB by an assert.
  16.     A future version may have reduced initial sizes and growth factors
  17.     for large itemsizes.
  18.  -  Stacks do NOT decrease in size. Except by complete deletion.
  19.  -  Pushes fail when the stack is full and the memory resizing fails.
  20.     The return value indicates this.
  21.  -  Underflowing Pops return the Stack's bottom value.
  22.  -  Pushes and Pops do NOT check stack-integrity. Use StackCheck().
  23. ----------------------------------------------------------------------- */
  24.  
  25. #ifndef STACK_H
  26. #define STACK_H
  27.  
  28. #include "extkword.h"
  29.  
  30. enum StackErrors         /* Return values for StackCheck()          */
  31. {                        /* The highest value is reported.          */
  32.  
  33.     NO_PROBLEMS,         /* All is OK (multiple use)                */
  34.     STACK_EMPTY,         /* stack is empty: error on next pop       */
  35.     STACK_LIMIT_REACHED, /* stack is full: maybe error on next push */
  36.     STACK_UNDERFLOW,     /* one or more pop's too many              */
  37.     STACK_ERRORS,        /* Dummy to separate warnings and          */
  38.                          /* -------- REAL errors ---------          */
  39.     STACK_CORRUPT1,      /* stack.top > stack.max                   */
  40.     STACK_CORRUPT2,      /* top * itemsize != offset                */
  41.     STACK_NULL,          /* Stack deleted or not created            */
  42.     STACK_INV_NUMBER,    /* Stack number out of range               */
  43. };
  44.  
  45. enum StackDefault{ STACK_INT, STACK_LONG, STACK_PTRS, STACK_FAR_PTRS,
  46.                    STACK_COUNT_DEFAULT }; /* supplied for management    */
  47.  
  48. /* ---- management operations ----------------------------------------- */
  49.  
  50. int  StackSystemInit( int StackCountAdditional );
  51.         /* StackCountAdditional is the amount of User stacks.           */
  52.         /* Returns actual number of stacks, or -1 on memory error.      */
  53.         /* MUST be called before other use of Stack system.             */
  54.         /* Also creates the four default stacks                         */
  55.  
  56. int  StackCreate( int ItemSize );    /* Returns the Stack number to use */
  57.                                      /* or -1 on memory failure.        */
  58. void StackDelete( int Stack );       /* You MAY delete a default stack  */
  59.  
  60. int  StackAdapt( int Stack, int Free );
  61.         /* Grows Stack as far as possible and needed to have a Free     */
  62.         /* number of free locations. Partial growth is possible !!!     */
  63.         /* Returns -1 on memory error, including partial growth.        */
  64. int  StackCheck( int Stack );
  65.         /* Returns enum StackErrors value. Will clear underflow flag if */
  66.         /* it is the only problem. Major purpose is debugging.          */
  67.  
  68. /* ---- Generic push/pop operations ----------------------------------- */
  69.  
  70. int  Push( int Stack, void * Source );         /* returns -1 on failure */
  71. void Pop( int Stack, void * Destination );
  72.         /* Stack value is NOT validated.                                */
  73.         /* Destination buffer _MUST_ be at least of size ItemSize       */
  74.         /* as given on StackCreate() !!! Otherwise: major SNAFU.        */
  75.         /* These functions are not meant for the default stacks.        */
  76.  
  77. void StackUnpop( int Stack ); /* Reverse last pop. Purpose is to take a */
  78.                               /* look and not accepting the data ...    */
  79.  
  80. /* ---- Push/pop operations to/from default stacks -------------------- */
  81. /*      VERY destructive when the relevant Stack has been deleted !!!   */
  82.  
  83. int  PushInt( int Value );    /* non-zero return of pushes is failure!  */
  84. int  PopInt( void );          /* Pop's return the value                 */
  85. int  PushLong( long Value );
  86. long PopLong( void );
  87. int  PushPtr( void * Value );
  88. void * PopPtr( void );
  89. int  PushFptr( void FAR * Value );
  90. void FAR * PopFptr( void );
  91.  
  92. #endif /* STACK_H */
  93.  
  94. /* === STACK.h end ==================================================== */
  95.