home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD1.mdf / pascal / library / dos / arrays / generics / flxarray / flxarray.doc < prev    next >
Encoding:
Text File  |  1989-07-23  |  9.6 KB  |  228 lines
  1. {
  2. ******  The FlexArray and FlexStack Objects (and Descendants) *****
  3.  
  4.  
  5. Design and Implementation ---  Eric C. Wentz
  6.  
  7.                                1-703-860-3807
  8.  
  9.                                2374 Antiqua Court
  10.                                Reston, Va. 22091
  11.  
  12.  
  13. Last Modification Date : 7-22-89
  14.  
  15.  
  16. ********************************************************************
  17.  
  18.  
  19. Design Objective(s):
  20.  
  21.        (1) {FlexArray}
  22.  
  23.            Implementation of a fully Generic Array-like Object,
  24.            Capable of all Array functions.  Additionally, Dynamic
  25.            allocation and Re-Sizing should be incorporated to
  26.            enhance efficiency and utility.
  27.  
  28.        (2) {FlexStack}
  29.  
  30.            Implementation of a fully Generic Stack Object, capable
  31.            of all Stack functions for any Data type. Additionally,
  32.            Dynamic allocation and Re-Sizing would be nice.
  33.  
  34. Limitations:
  35.  
  36.            FlexArrays and FlexStacks are limited to the maximum size which
  37.            GetMem can allocate to a single variable, or 65521 bytes.
  38.  
  39.            As the FlexArray and the FlexStack are fundamentally defined
  40.            by use of Dynamically allocated arrays of un-typed bytes, it is
  41.            only possible to define them for similar-sized constituents.  In
  42.            particular it will not be possible to declare a FlexArray of
  43.            Ancestor-Objects and then use it to contain different-sized
  44.            Descendant Objects.  The user should be able to get around this by
  45.            declaring a FlexArray of pointers to such objects, but I have not
  46.            made any attempts to test this.
  47.  
  48.            As (I believe) Turbo allocates the same number of bytes for each
  49.            variant of a Variant record, there should be no problems with
  50.            variant records.
  51.  
  52. ***************************************************************************
  53. Comments Regarding Primary Benefits
  54. ***************************************************************************
  55.  
  56. The FlexArray, in and of itself, brings nothing new to the user other then
  57. the ability to Dynamically size (and grow or shrink) an array.  In fact,
  58. used simply as an array, the FlexArray is more clumsy then a normal
  59. array.  The importance of the FlexArray is not its mimicry of the normal
  60. array, but the Genericity inherent in its implementation.  By exploiting
  61. this feature of the FlexArray, it is possible to define more abstract
  62. Objects (such as the FlexStack) which require an Array as the fundamental
  63. DataStructure WITHOUT REGARD TO DATATYPE.  Using this concept, it is easy
  64. to implement a stack (for instance) and NEVER again need to go through the
  65. process of defining a stack, regardless of the type of variable which you
  66. later find you need to stack. -- See Unit Stacks for more details.
  67.  
  68. ADDED NOTE: The methods used to implement FlexArrays WILL provide
  69.             the same accessing speed as normal arrays, even though
  70.             we must sacrifice the easier notation inherent to normal
  71.             arrays.  Performance doesn't suffer by using FlexArrays!
  72.  
  73. ***************************************************************************
  74. Implementation {FlexArray} :
  75. ***************************************************************************
  76.  
  77. Unit GenArray; { Generic Arrays -- Maximum size 65521 bytes }
  78.  
  79. INTERFACE { NOT the entire Interface, but all needed definitions are here }
  80.  
  81. { NOTE: FlexArrays are Indexed from 0 to MaxElements-1 }
  82.  
  83. Type
  84.   FlexArray = Object
  85.  
  86.     Procedure Create;
  87.     Procedure Init (MaxElements,ElementSize : Word);  {Once CREATEd, you may}
  88.     Procedure Destroy;                                {Re-Use a FlexArray by}
  89.                                                       {DESTROYing and then  }
  90.                                                       {Re-INITting it.      }
  91.  
  92.     Procedure Accept (Var El; Index,Size : Word);   {Assign the Indexth El}
  93.     Procedure Retrieve (Var El; Index,Size : Word); {Get the Indexth El}
  94.  
  95.     Procedure Copy (F : FlexArray); {Target MUST be CREATEd or DESTROYed}
  96.  
  97.     Function MaxSize : Word;   {Report Current Array Length}
  98.     Function ElemSize : Word;  {Report Element Size}
  99.  
  100.     Procedure ReSize (NewMaxElements : Word);
  101.                                {Extend/Shrink to NewMaxElements}
  102.  
  103.   End;
  104.  
  105. IMPLEMENTATION { Not Reproduced }
  106.  
  107. ***************************************************************************
  108. Implementation {FlexStack} :
  109. ***************************************************************************
  110.  
  111. Unit GenStack; { FlexArray-Based Generic Stacks }
  112.  
  113. INTERFACE { NOT the entire Interface, but all needed definitions are here }
  114.  
  115. Type
  116.   FlexStack = Object(FlexArray)  {Dynamically allocated Stack}
  117.  
  118.     Procedure Create;
  119.  
  120.     Function Full : Boolean;
  121.     Function Depth : Word;
  122.     Function Empty : Boolean;
  123.  
  124.     Procedure Copy (F : FlexStack);
  125.     Procedure ReSize (Num : Word);     {Grow (or Shrink) by Num elements}
  126.  
  127.     {NOTE: It is an Error to ReSize a FlexStack to Zero (or Negative)}
  128.  
  129.     Procedure Push (Var El; Size : Word);  {Size of El MUST match ElementSize}
  130.     Procedure Pop (Var El; Size : Word);
  131.     Procedure Top (Var El; Size : Word);   {TOP does not POP the Stack}
  132.  
  133.     (* Applicable inherited procedures and functions: *)
  134.  
  135.     { Procedure Init (MaxElements,ElementSize); }
  136.     { Procedure Destroy;                        }
  137.     { Function MaxSize : Word;                  }
  138.     { Function ElemSize : Word;                 }
  139.  
  140.   End;
  141.  
  142. IMPLEMENTATION { Not Reproduced }
  143.  
  144. **************************************************************************
  145.  { UNIT DEPENDENCIES }
  146. **************************************************************************
  147.  
  148.         FlexPntr
  149.            |
  150.            |
  151.         GenArray
  152.            |    \
  153.            |     \
  154.         GenStack  {other Stack-based structures (GENERIC)}
  155.            |            \
  156.            |             \
  157.          Stacks           {Derived Application-level structures}
  158.  
  159.  
  160. ****************************************************************************
  161.  { ERROR MESSAGES }
  162. ****************************************************************************
  163.  
  164.     I have made considerable effort to anticipate all possible errors when
  165. manipulating FlexArrays, and have incorporated a simple error procedure into
  166. the implementation section of unit GenArray.  It prints a simple diagnostic
  167. message to the screen and HALTs the program.  This "bonehead" strategy seems
  168. to be sufficient for three reasons: (1) I BELIEVE that ALL conceivable errors
  169. will be due to developmental errors.  (2) I dislike the necessity of passing
  170. boolean "fail" variables.  (3) Enough statistical information methods are
  171. provided to enable the user to define more sophisticated error checking and
  172. recovery methods, if such is desired or needed by some situation which I have
  173. not anticipated. -- For example Unit GenStack also incorporates an error
  174. routine for stack-specific errors -- see below.
  175.  
  176. POSSIBLE ERROR MESSAGES: (Unit GenArray)
  177.  
  178.             Attempted Init on Un-Created or Initialized FlexArray.
  179.             Insufficient Memory for Requested FlexArray.
  180.             Attempted Accept with Incorrect Size Variable.
  181.             Attempted Accept on Un-Initialized FlexArray.
  182.             Attempted Retrieve with Incorrect Size Variable.
  183.             Attempted Retrieve with Un-Initialized FlexArray.
  184.             ***** INDEX OUT OF BOUNDS *****
  185.             Attempted Copy on Un-Created or Initialized FlexArray.
  186.             Attempted to ReSize FlexArray to Zero (or Negative).
  187.             Insufficient Memory for Requested ReSize operation.
  188.             Attempted to ReSize non-Initialized FlexArray.
  189.             Requested FlexArray or ReSize is Too Large.
  190.  
  191. POSSIBLE ERROR MESSAGES: (Unit GenStack)
  192.  
  193.             Attempted PUSH onto Full FlexStack.
  194.             Attempted POP or TOP from Empty FlexStack.
  195.  
  196.  
  197.   { To be honest, I must add that I may very easily have overlooked something.
  198.     If you find such an error, please write and let me know!!! }
  199.  
  200.  
  201. ******************************************************************************
  202.  { PROPRIETARY CODE }
  203. ******************************************************************************
  204.  
  205. Since the only significantly original work in these units is in Unit
  206. GenArray, I have elected not to distribute it in source form.  In fact,
  207. the source code for GenArray should be completely unnecessary to the user.
  208. However, if you really want it, you can convince me by sending me a check
  209. for $20.00 at the above address.
  210.  
  211. As to the FlexPntr unit.  ALL the code in it was either directly taken from
  212. an article in PROGRAMMERS JOURNAL by Tom Swann or inspired by the same article
  213. (Programming on the Variant Express PJ V6.5 Sept/Oct 1988), and is of such a
  214. fundamental nature that no changes are really possible or desireable in ANY
  215. context.  I have distributed it as a TPU simply because Turbo has no other
  216. method available for PRIVATE declarations (ala ADA).  Therefore, since I did
  217. not really originate the code, and since there is no reason to ever change
  218. any of it, I will NOT distribute the source code for any reason.  Those
  219. incureably interested individuals should look up the above article, paying
  220. particular attention to Mr. Swann's definitions of IntPtr and IntRec, which
  221. I have renamed "FlexPtr" and "FlxArray" respectively. NOTE: the array which
  222. Mr. Swann defines within the IntRec is referenced with field name "Flex" in
  223. my version of the construct, and is an array of Bytes, not Integers.
  224.  
  225. ******************************************************************************
  226. ******************************************************************************
  227. ******************************************************************************
  228. }