home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD1.mdf / forth / compiler / love / chap19.doc < prev    next >
Text File  |  1993-04-11  |  9KB  |  218 lines
  1.         Self-fetching Array Word Set with Bounds Checking
  2.  
  3.         This word set offers a set of self fetching arrays, both one
  4. and two dimensional (VECTOR and MATRIX).   Each use (fetch, store,
  5. or plus-store) takes only two bytes in the thread segment.
  6. Organizations of byte, cell, and double are available.  A fixed length
  7. string vector is also available.   All array indexes are zero based.
  8. These words require the multiple-cfa word set (MCFA.TXT) to be loaded
  9. in advance.
  10.  
  11.         Operation
  12.  
  13.         These arrays are declared just as any variable, with the size
  14. passed in.  These arrays may have up to 65535 elements.  VECTORs are
  15. one-dimensional and have a single number of elements passed in,
  16. MATRIXs have two dimensions and two sizes (rows,columns) are passed in.
  17. For example:
  18.  
  19. 365 VECTOR DayFlags   ( one flag for each day)
  20.   7 VECTOR Visits/Day ( visits per day)
  21. 10 10 DMATRIX HundredElementSquare
  22.  3  3 MATRIX TicTacToeBoard
  23.  
  24.         Data can subsequently be stored into the arrays with prefixes
  25. such as )-> )C-> etc.  Data are fetched simply by naming the array.
  26. In each case the array index(es) are passed in.  The data type *VECTOR,
  27. is for storing a vector of fixed length strings and is not
  28. self-fetching.  It returns the segment and offset of the string
  29. on the stack.  The storage word )*MOVEL> is available to store a string
  30. into the reference array.
  31.  
  32.         CVECTOR,VECTOR,DVECTOR declaration:
  33.         ( elements-- )
  34.  
  35.         array declared with:    fetch stack:
  36.         CVECTOR arrayname       arrayname ( index--c )
  37.  
  38.                                         (plus) store stack:
  39.                                         )C-> arrayname  ( c,index-- )
  40.                                         )C+> arrayname  ( c,index-- )
  41.  
  42.         array declared with:    fetch stack:
  43.         VECTOR arrayname        arrayname ( index--n )
  44.  
  45.                                         (plus) store stack:
  46.                                         )-> arrayname  ( n,index-- )
  47.                                         )+> arrayname  ( n,index-- )
  48.  
  49.         array declared with:    fetch stack:
  50.         DVECTOR arrayname       arrayname ( index--d )
  51.  
  52.                                         (plus) store stack:
  53.                                         )D-> arrayname  ( d,index-- )
  54.                                         )D+> arrayname  ( d,index-- )
  55.  
  56.         *VECTOR declaration:
  57.         ( elements, bytes -- )
  58.  
  59.         array declared with:            fetch stack:
  60.         *VECTOR stringarrayname         arrayname  ( index -- seg,ofs )
  61.  
  62.                         store stack:
  63.                         )*MOVEL> stringarrayname   ( seg,ofs,index -- )
  64.  
  65.  
  66.         CMATRIX,MATRIX,DMATRIX declaration:
  67.         ( rows,columns-- )
  68.  
  69.         array declared with:    fetch stack:
  70.         CMATRIX arrayname       arrayname ( row,col--c )
  71.  
  72.                                         (plus) store stack:
  73.                                         ]C-> arrayname  ( c,row,col-- )
  74.                                         ]C+> arrayname  ( c,row,col-- )
  75.  
  76.         array declared with:    fetch stack:
  77.         MATRIX arrayname        arrayname ( row,col--n )
  78.  
  79.                                         (plus) store stack:
  80.                                         ]-> arrayname  ( n,row,col-- )
  81.                                         ]+> arrayname  ( n,row,col-- )
  82.  
  83.         array declared with:    fetch stack:
  84.         DMATRIX arrayname       arrayname ( row,col--d )
  85.  
  86.                                         (plus) store stack:
  87.                                         ]D-> arrayname  ( d,row,col--)
  88.                                         ]D+> arrayname  ( d,row,col--)
  89.  
  90. Examples:
  91.  
  92. 365 VECTOR DayFlags   ( one flag for each day)
  93.         : SET-DAY-FLAG ( day-- )
  94.           -1 SWAP )-> DayFlags ;
  95.         : CHECK-DAY-FLAG ( day -- )
  96.           DayFlags
  97.           IF ." Set" THEN ;
  98.  
  99.         30 VECTOR jail ( 30 cells in jail)
  100.         : FILL10CELLS ( clear ten cells in jail ( -- )
  101.           10 0
  102.           DO -1 I )-> jail ( store true flag into cell) LOOP ;
  103.  
  104.         25 80 *VECTOR instruction-screen ( one screen-full of text)
  105.         : ENTER-INSTRUCTIONS ( -- )
  106.         25 0
  107.         DO TIB 80 BL FILL ( pre-fill to blanks )
  108.            TIB 80 EXPECT  ( get a line of text)
  109.            SPAN @ 0=      ( blank line exits)
  110.            IF LEAVE THEN
  111.            GET:VS TIB I )*MOVEL> instruction-screen
  112.         LOOP ;
  113.  
  114.         Declaration
  115.  
  116.         The data space of these arrays is allocated outside the
  117. L.O.V.E. Forth memory map.  When allocated during array declaration,
  118. the actual starting memory is relative to the variable HEAPSEG.  This
  119. is usually set from the L.O.V.E. Forth segment:  GET:HEAP prior to
  120. using the arrays, allowing the arrays to exist above the usual memory
  121. map (in the heap).  In order to use memory above the usual L.O.V.E.
  122. Forth memory map, variables MINHEAP and MAXHEAP must be set
  123. appropriately.  See instructions for saving the system.
  124.  
  125.         During array declaration only, VARIABLEs alloc.addr and
  126. alloc.seg are used.  They contain the "dictionary pointer" for the
  127. allocation.  They are initialized to 0 and then are updated after each
  128. array declaration.
  129.  
  130.         alloc.seg       contains the relative segment of the
  131.                         start for the next array
  132.                         (ie. relative to HEAPSEG)
  133.         alloc.ofs       contains the address relative to alloc.seg
  134.  
  135.         Automatic Fill Words
  136.  
  137.         A common operation for any array is to fill it with a
  138. particular number, usually zero.  A set of words performs this
  139. function.  No sizes need be specified, the array is filled based on its
  140. declared size.
  141.  
  142.         To fill a CVECTOR VECTOR DVECTOR or *VECTOR with zero use:
  143.         (0)C->  (0)->  (0)D-> and (0)*-> respectively.
  144.         For CMATRIX MATRIX and DMATRIX
  145.         [0]C->  [0]-> and [0]D-> are used.  All have stack action
  146.         ( -- ).
  147.  
  148.         To fill an array with a particular number the words
  149.                 (N)C->  (N)->  (N)D-> and (N)*->
  150.         are used for the VECTORs and
  151.                 [N]C->  [N]->  [N]D->
  152.         are used with the MATRIXes.   A byte is passed into
  153.         (N)C-> (N)*-> and (N)C-> , a single number is passed into
  154.         (N)-> and [N]-> , and a double number into (N)D-> and [N]D->.
  155.  
  156. Examples (with declarations from above):
  157.  
  158.         (0)-> jail                     ( clear jail)
  159.         BL (N)*-> instruction-screen   ( blank screen contents)
  160.         1. [N]D-> HundredElementSquare ( unit matrix )
  161.  
  162.         Other words
  163.  
  164.         SEG:OFS> returns the address of the array following, For
  165.         example to display the actual location in RAM of an array
  166.         above:
  167.                 HEX  SEG:OFS> jail U. U.  DECIMAL
  168.  
  169.         MAT-EVENPARA operates during declaration to ensure that the
  170.         next array starts on an even paragraph, by adjusting alloc.seg
  171.         and alloc.addr .  Several bytes may be wasted.
  172.  
  173.         Bounds Checking
  174.  
  175.         A bounds error occurs when an invalid index is used.  If for
  176. example, the program tries to store element 100 in a 50 element array,
  177. a bounds error occurs, as a 50 element array only supports indexes 0 to
  178. 49.  On a boundary error during a store or plus-store operation,
  179. nothing is actually stored or changed in the array.  Error flags are
  180. set, as described above.  On a boundary error during a fetch, 0 is
  181. returned (or double 0. in the case of a double array).  For string
  182. vectors, the address of the first element is returned.  This action is
  183. intended for real time and embedded programs, where execution cannot
  184. simply "ABORT".
  185.  
  186.         When such errors occur, bit flags are set in the VARIABLE
  187. bound.err which is a 3 cell array.  The contents of this can be printed
  188. with BOUND.  in the current base.
  189.  
  190.       first number  VECTOR errors
  191.         bit     description
  192.         ---     -----------
  193.         1       on CVECTOR fetch
  194.         2       on CVECTOR store          )C->
  195.         4       on CVECTOR plus-store     )C+>
  196.         10      on  VECTOR fetch
  197.         20      on  VECTOR store          )->
  198.         40      on  VECTOR plus-store     )+>
  199.         100     on DVECTOR fetch
  200.         200     on DVECTOR store          )D->
  201.         400     on DVECTOR plus-store     )D+>
  202.         8       on *VECTOR
  203.  
  204.       second number MATRIX row errors
  205.         bit     description
  206.         ---     -----------
  207.         1       on CMATRIX row fetch
  208.         2       on CMATRIX row store          ]C->
  209.         4       on CMATRIX row plus-store     ]C+>
  210.         10      on  MATRIX row fetch
  211.         20      on  MATRIX row store          ]->
  212.         40      on  MATRIX row plus-store     ]+>
  213.         100     on DMATRIX row fetch
  214.         200     on DMATRIX row store          ]D->
  215.         400     on DMATRIX row plus-store     ]D+>
  216.  
  217.       third number  MATRIX column errors
  218.         (as the above for row errors)