( FILE: ARRAY.4th -- 8 July 88 -- MFB )

( this file conatins an example of a defining word)

( ARRAY is a compiler word to define a two dim. array.
  The defined word, when executed, returns the address
  of specified cell (tos is row, nos is column)
  Each cell is 16 bits.  For example,
        8 3 ARRAY XYZ   ( 3 rows (0 to 2), 8 columns (0 to 7))
        0 4 0 XYZ !     ( store 0 in 0th row, 4th column)
        7 2 XYZ @       ( fetch last cell in array)

  No error checking at compile time or run time, add it if
  needed.
  More comments below
)

CROSS @ 0= IFTRUE ( see notes below)

: ARRAY ( col row -- word)
  0 DEFINE  ( put name in dictionary)
  CDH HEADB! ' XARRAY HEAD! ( put a call to run time code)
  OVER OVER * 2 * LUM @ SWAP - DUP LUM ! ( alloc memory)
  HEAD! ( store base address after call)
  HEAD! ( store number rows) ( for later error checking)
  2 * HEAD! ( store # bytes/row )
; IMMEDIATE

ENDIF

( ARRAY builds the following code:
        CALL xarray   ;call runtime, tos will have adr of dw's
        DW   base     ;base of data space allocated
        DW   #rows-1
        DW   #cols-1

  REMEMBER, in high mode, tick (') does not try to look up
  the address of following word.  Instead, it stores string
  in-line so word can be looked up when ARRAY (or other
  defining word) executes (because you may want to look in
  the "cross" dictionary).
)
( ---------------------------------------------------- )
( ** IF you want to make a COM (or ROM) file of a program
  that uses ARRAY, then everything above the dotted line
  loads before you enter CROSS-COMPILE mode, and
  everything after the line loads after cross mode.
  Because of the IFTRUE...ENDIF above, you can load this
  same file twice.  For example, during development,
               " ARRAY.4TH" LOAD
               " USERPROG" LOAD
  When ready to make a COM file:
               " ARRAY.4TH" LOAD
               " MAKECOM.4TH" LOAD
  MAKECOM would prompt you for a filename and you there are
  two (out of hundreds) approaches you could take:
       1. Answer MAKECOM with filename PROGX, where PROGX
          contains:
               " ARRAY.4TH" LOAD
               " USERPROG" LOAD
       2. Answer MAKECOM with USERPROG, and have the following
          line in USERPROG:
               CROSS @ IFTRUE " ARRAY.4TH" LOAD ENDIF

   In either case, what you are doing is: (1) defining
   the compile time activity of ARRAY before entering
   cross mode, and (2) defining the run time activity
   of ARRAY while in cross mode.

   Hint: when you create new defining words that you use
   all the time, put a "load" in MAKECOM to pick up the run
   time part, and use ATTACH to make both parts (compile and
   run) a permanent part of your system.
)

( run time for ARRAY)
( the call at the definition put the adr of the parameters
  for the def. on the stack. We could do the work in asm
  lang code for speed, but hi-level is pretty quick for
  most applications.
)
: XARRAY ( col row -- adr)
  SWAP OVER 4 + @ ( get 'column*2' dimension)
  * ( offset to correct row)
  SWAP @ ( get array base adr) + ( baseadr + rowofset)
  SWAP DUP + ( column offset) + ( got adr of cell)
;