ÉÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ»
       º  Lesson 7 Part 100 F-PC 3.5 Tutorial by Jack Brown  º
       ÈÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍͼ

           ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
           ³  Defining Multi-Dimensional Arrays  ³
           ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ


The following definition using CREATE ... DOES> can be used to define
multi dimensional arrays.  It is presented both as a tool to use and
something for you to study.  First here is the definition of the
multi-dimensional array defining word.

: ACHECK ( {n items} n -- {n items}  n )  \ Check parameters.
         DUP 1 < OVER 255 > OR
         ABORT" Illegal dimension in array definition."
         DUP 1+ ?ENOUGH ;

: *ARRAY  ACHECK
  CREATE
    DUP C,              ( save # of dimensions )
    1 SWAP              ( initialize total size )
    0 DO                ( loop on # of dimensions )
      OVER ,            ( save dimension )
      *                 ( increase total size )
      LOOP
    1 ,                 ( save dummy dimension )
    2 * ALLOT           ( allocate space for words )
  DOES>
    COUNT               ( get # of dimensions )
    0 SWAP              ( initialize offset )
    0 DO                ( loop on # of dimensions )
      >R                ( save offset )
      OVER DUP 0< ABORT" Negative array index."
      OVER @ < 0= ABORT" Array index too large."
      2+ DUP @          ( advance to next dimension )
      ROT R> + *        ( calculate offset so far )
      LOOP
    2 *                 ( double offset for words )
    + 2+ ;              ( calculate element address )


To define an array, the vector size for each dimension
must be on the stack followed by the total # of dimensions

 Example: to define a 3D array name MATRIX with a
 vector length of 5 in each dimension (i.e. x, y, z = 0...4)
 you would execute:

        5 5 5 3 *ARRAY MATRIX

To get an indexed address into the array, put the coordinates
on the stack followed by the name of the array.

 Example: to retrieve the value stored in (x,y,z) = (1,2,3)
 for the array above, you would execute:
        1 2 3 MATRIX @
 to store (x,y,z) = 5 at 3D space x=2,y=3,z=4 do:

        5 2 3 4 MATRIX !

Now you know why Forth does not have arrays and vectors built in as
part of the language.  If you need them, you add them yourself!

ÖÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ·
º  Problem 7.7  º
ÓÄÄÄÄÄÄÄÄÄÄÄÄÄÄĽ
a) Implement *ARRAY and the example MATRIX above.
b) Dump out the contents of the pfa of MATRIX and verify that it
   conforms to what is laid down when it was created with *ARRAY
   ie  Try  ' MATRIX >BODY 16 DUMP
c) Write a word that will fill each of the  125 cells of the *ARRAY
   MATRIX with the sum of its indices.  ie  (1,1,1) = 3  (1,2,3) = 6
d) Write a word that will Display the contents of a *ARRAY .  It
   Call it ADUMP and make its usage:   ADUMP MATRIX
   You might begin the definition with:  : ADUMP  ' >BODY ..... ;
   This will allow you to access the parameter field.
   Use  ADUMP to verify the operation of (c)

ÚÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ¿
³  Please Move to Lesson 7 Part 110  ³
ÀÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÙ