Defining and using Arrays¶
The traditional approach is the following:
create my-array 42 cells allot
This creates the dictionary entry named my-array and allocates 42 cells in RAM. BUT: the my-array dictionary entry is not connected to the allocated RAM. The correct solution is:
variable my-array 42 cells allot
This makes the dictionary entry named my-array, sets up the link to the RAM address and allocates an additional amount of 42 cells in RAM.
Forth 200x introduced a new word named Buffer:. With it the above code turns into
43 buffer: my-array
please note the different sizes! The buffer:
-implementation
allocates the exact number of bytes whereas the variable
version
adds the given size parameter to the 1 cell it allocates anyways.
The use of the array is quite simple:
: my-array-@ cells my-array + @ ;
: my-array-! cells my-array + ! ;
Arrays of structures¶
This example uses structures. Structures can be
used after including of the structures.frt
file. First a hash data structure consisting of
two elements is defined. This structure is used
to create an array of a few elements afterwards.
begin-structure hash
field: hash.key
field: hash.value
end-structure
\ inspired by CELLS
\ ( n -- size )
\ calculates the size of n items of the
\ type hash
: hash-cells hash * ;
\ define a hash-array
: hash:
hash-cells buffer:
does>
swap hash-cells +
;
The helper word hash-cells
calculates the size of the
data structure in terms of byes, just like the standard
word cells
does it.
Now we’re using the words (using the amforth-shell). First define an array of 4 hash pairs. After that store a key/value pair at a particular position and retrieve it again later.
(ATmega16)> 4 hash: my-hash
ok
(ATmega16)> 42 3 my-hash hash.key !
ok
(ATmega16)> 4711 3 my-hash hash.value !
ok
(ATmega16)> 3 my-hash hash.key @ .
42 ok
(ATmega16)> 3 my-hash hash.value @ .
4711 ok
(ATmega16)>
If you place the data structure in a different memory (e.g. the EEPROM) adapt the
code accordingly. buffer:
needs to be replaced with a similiar allocation word and
@
/!
with the proper memory access words. Remember, memory is not always 2 bytes per
cell.
See also