(   Title:  Plain Floating Point Arrays
     File:  plainfarray.fs
  Version:  0.5.1
   Author:  David N. Williams
  License:  LGPL
  Revised:  June 8, 2007
)
\ Copyright (C) 2007 David N. Williams
(
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or at your option any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free
Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
MA 02111-1307 USA.

If you take advantage of the option in the LGPL to put a
particular version of this library under the GPL, the author[s]
would regard it as polite if you would put any direct
modifications under the LGPL as well, and include a copy of this
request near the beginning of the modified library source.  A
"direct modification" is one that enhances or extends the
library in line with its original concept, as opposed to
developing a distinct application or library which might use it.

ANS Forth compatible except for:
- case sensitivity
- [UNDEFINED]

These words assume default ANS Forth floats.  They are expected
to work with or without a separate fstack.

The words differ from the conventions of the Forth Scientific
Library, or FSL, in a couple of ways:

1. The data field of a "plain" float array, or plain farray,
   does not include the number of elements, i.e., the dimension.
   The plain words here are for situations where it is not
   burdensome to deal with the dimension explicitly if needed,
   for example, with a dedicated constant.
   
   We do float align the array elements.  It would take a bit of
   juggling to do that and also include the dimension.  Various
   FSL utility interfaces allot a single cell for the dimension
   in the data header, and don't worry about the float alignment
   of the following data elements.

2. Instead of "}", we use "}F" for the word that leaves the
   address of an element.  That avoids conflict with a common
   usage for locals, and we think it's not a bad idea to include
   the data type in the name.

The revision date in the file header above may reflect cosmetic
changes not recorded in the change log below.

Version 0.5.1
 3Jun07 * Added PFARRAY and }F and more tests.
	* Added comments emphasizing departure from FSL
	  conventions.
 8Jun07 * Added final DROP to "}FARRAY.". 

Version 0.5.0
 2Jun07 * Started, based on sarray.fs.
 3Jun07 * Added tests and released.
)
decimal

s" FLOATING-EXT" environment? 0=
[IF] .( Floating point not available.) ABORT [THEN] ( flag) drop

\ Starting depth of current fstack frame:
  variable start-fdepth

-1 floats constant -1floats


\ *** PLAIN FARRAY DEFINING WORDS

: f[  ( -- )  fdepth start-fdepth ! ;

: ]f#  ( f: r1 ... rn -- s: array.dfa n )
(
Make an faligned, plain data-space array of floats from the
fstack frame started by the most recently executed F[.  Leave
the array data field address and the number of floats.
)
  fdepth start-fdepth @ - ( n) >r
  r@ ( n) falign here ( dfa) >r
  ( n) floats allot
  r@ ( dfa)   here -1floats + ( last.elem.addr)
  DO i f! -1floats +LOOP
  r> ( dfa) r> ( n) ;

: ]f  ( f: r1 ... rn -- array.addr )  ]f# drop ;

: pfarray  ( "name" dim -- )   \ name execution:  ( -- array.dfa )
(
Make a named, faligned, plain data-space array for dim float
elements, with all bytes initialized to zero.
)
  falign here swap ( here dim)
  floats ( size) dup allot
  over ( here) constant
  ( here size) 0 fill ;


\ *** PLAIN FARRAY ACCESS WORDS
(
In these words, dfa is the array data field address, the address
of the 0th element.  See the SYNTAX EXAMPLES section for usage.
)

[UNDEFINED] }F@ [IF]  \ primitive code candidates

: }f   ( dfa i -- elem.addr )  floats + ;
: }f@  ( dfa i -- f: r )       }f f@ ;
: }f!  ( f: r s: dfa i -- )    }f f! ;

[THEN]


\ *** SYNTAX EXAMPLES

0 [IF]  \ tested with pfe and gforth

cr
.( USING F[ ... ]F to define a plain farray) cr
f[ 0.1e 0.2e 0.3e ]f#
constant #fa1 constant fa1{

: }f.  ( dfa i -- )  }f@ f. ;

: }farray.  ( dfa dim -- )
  ( dim) 0 DO space ( dfa) dup i }f. LOOP ( dfa) drop ;

.( TESTING }F@) cr
.( You should see .1e, .2e, .3e in F. format:) cr
fa1{ #fa1 }farray. cr

.( DUMP of farray:)
fa1{ #fa1 floats dump cr

cr
.( USING PFARRAY to define a plain farray) cr
3 constant #fa2
#fa2 pfarray fa2{

.( DUMP of initialized farray:)
fa2{ #fa2 floats dump cr

.( TESTING }F!) cr
.( You should see .4e, .5e, .6e in F. format:) cr

.6e .5e .4e
:noname
  #fa2 0 DO fa2{ i }f! LOOP ; execute
fa2{ #fa2 }farray. cr

.( DUMP of farray:)
fa2{ #fa2 floats dump cr

[THEN]