FVALUE

Poll standings

Systems

[ ] conforms to ANS Forth.
  bigForth (Bernd Paysan)
  FirmWorks Open Firmware (Mitch Bradley)
  iForth (Marcel Hendrix)
  VFX Forth Windows/Linux/DOS (Stephen Pelc)
[ ] already implements the proposal in full since release [ ].
  iForth 1 (Marcel Hendrix)
  VFX Forth Windows/Linux/DOS 1999 (Stephen Pelc)
[ ] implements the proposal in full in a development version.
[ ] will implement the proposal in full in release [ ].
[ ] will implement the proposal in full in some future release.
  bigForth (Bernd Paysan)
  FirmWorks Open Firmware (Mitch Bradley)
[ ] There are no plans to implement the proposal in full in [ ].
  4th 3.5d, rel. 2 (Hans Bezemer)
[ ] will never implement the proposal in full.

Programmers

[ ] I have used (parts of) this proposal in my programs.
  Doug Hoffman
  Marcel Hendrix
  Jens-Hanno Schwalm (regularly! Using iForth and vfx)
  Ed Falat
[ ] I would use (parts of) this proposal in my programs if the systems
     I am interested in implemented it.
  Doug Hoffman
  David N. Williams
  Bernd Paysan
  Ed Falat
  Stephen Pelc
  Gerry Jackson
[ ] I would use (parts of) this proposal in my programs if this
     proposal was in the Forth standard.
  Doug Hoffman
  David N. Williams
  Ed Falat
  Stephen Pelc
  Gerry Jackson
[ ] I would not use (parts of) this proposal in my programs.
  Hans Bezemer
  Hugh Aguilar

Informal results

Proposal

History
=======
* First draft *
* First spell-checked draft         ** Marcel Hendrix, August 25, 2006
* Revised to align with RfD for TO  ** Marcel Hendrix, Saturday, February 21, 2009, 21:39
* Revised after comments            ** Marcel Hendrix, Monday, March 23, 2009, 06:52
* Revised for line length           ** Marcel Hendrix, Monday, June 08, 2009, 21:17

Rationale
=========
Problem
-------
The word VALUE was considered useful enough to be included in ANS94.
A search through 4827 source files shows 532 occurrences of VARIABLE
versus 4241 uses of VALUE. It would be obviously useful to have a 
variant of VALUE that works for floating-point values. 

The main idea behind FVALUE is that fetching a variable is more
frequent than changing it. Therefore both readability of source code 
and efficiency of execution can be achieved by making 'F@' the default
action of FVALUE.

Current practice
----------------
The proposed form of FVALUE has been in use in tForth, iForth, and their 
predecessors since 1985. FVALUE (with TO) is also in use for Mops and 
MacForth. The systems mentioned define more TO-like words that work on 
values, e.g. +TO, -TO, CLEAR, ... with obvious meanings.

This proposal does not propose to standardize on these extensions.

Solution
--------
Although many people have objected to parsing words, parsing
permits the host system the most flexibility in implementation
and is thus the preferred solution (see also TO).

The syntax is:
  123e0 FVALUE fdata
to define <fdata> as a floating-point value initialized to <123e0>.

To access the value of fdata:
   fdata 2e0 F+ F. <cr> 125.000000  ok

To change fdata:
   fdata 2e0 F+ TO fdata  fdata F. <cr> 125.000000  ok

EXCHANGE leaves r1 in fdata and returns the prior value r2.
   : EXCHANGE ( F: r1 -- r2 ) fdata FSWAP TO fdata ;
   
Proposal
========
12.6.1.xxxx FVALUE         "f-value"                           FLOATING EXT
     ( F: r -- ) ( "<spaces>name" -- )
     Skip leading space delimiters.  Parse name delimited by a space. Create
     a definition for name with the execution semantics defined below, with
     an initial value equal to r.
     name is referred to as an "f-value".
  name Execution: ( F: -- r )
     Place r on the FP stack.  The value of r is that given when name was
     created, until the phrase r TO name is executed, causing a new value of
     r to be associated with name.
TO name Run-time: ( F: r -- )
     Associate the value r with name.

See: 3.4.1 Parsing and 6.2.2295 TO.


See also
========
6.2.2295 TO in CORE EXT, currently found in 
http://www.forth200x.org/documents/forth07-2.pdf.

Note that the stack diagram of TO should be defined as
  ( integer VALUE or LOCAL ) Interpretation: ( x "<spaces>name" -- )
  ( floating-point FVALUE  ) Interpretation: ( "<spaces>name" -- ) ( F: r -- )

Labeling
=========
TBD

Reference Implementation
========================
The implementation of FVALUE requires carnal knowledge of the host
implementation, which is the main reason why it should be standardized.
The implementation below also works for, e.g., integer VALUEs and 
locals. 

VARIABLE %var  : TO  1 %var ! ;

: FVALUE  CREATE F,  
	  DOES>  %var @ IF  F!  ELSE  F@  THEN  
	  	 0 %var ! ;

: VALUE	  CREATE ,  
	  DOES>  %var @ IF   !  ELSE   @  THEN  
	  	 0 %var ! ;

Test Cases
==========
	T{ 0e0 FVALUE Tval -> }T
	T{ Tval -> 0e0 }T
	T{ 1e0 TO Tval -> }T
	T{ Tval -> 1e0 }T
	: SETTval Tval FSWAP TO Tval ; 
	T{ 2e0 SETTval Tval -> 1e0 2e0 }T
	T{ 5e0 FVALUE x -> }T
	: [execute] EXECUTE ; IMMEDIATE
	T{ ' Tval ] [execute] [ -> 2e0 }T

Voting instructions

Note that you can be both a system implementor and a programmer, so you can submit both kinds of ballots.

Ballot for systems

[ ] conforms to ANS Forth.
[ ] already implements the proposal in full since release [ ].
[ ] implements the proposal in full in a development version.
[ ] will implement the proposal in full in release [ ].
[ ] will implement the proposal in full in some future release.
[ ] There are no plans to implement the proposal in full in [ ].
[ ] will never implement the proposal in full.

Ballot for programmers

[ ] I have used (parts of) this proposal in my programs.
[ ] I would use (parts of) this proposal in my programs if the systems
     I am interested in implemented it.
[ ] I would use (parts of) this proposal in my programs if this
     proposal was in the Forth standard.
[ ] I would not use (parts of) this proposal in my programs.