8.6.2.0435
2VALUE
two-value
DOUBLE EXT
 
( x1 x2 "<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 of x1 x2.

name is referred to as a "two-value".

name Execution:
( -- x1 x2 )

Place cell pair x1 x2 on the stack. The value of x1 x2 is that given when name was created, until the phrase "x1 x2 TO name" is executed, causing a new cell pair x1 x2 to be assigned to name.

TO name Run-time:
( x1 x2 -- )

Assign the cell pair x1 x2 to name.

See:
3.4.1 Parsing and 6.2.2295 TO, A.8.6.2.0435 2VALUE.

Rationale:
Typical use:
: fn1 S" filename" ;
fn1 2VALUE myfile
myfile INCLUDED
: fn2 S" filename2" ;
fn2 TO myfile
myfile INCLUDED
Implementation:
The implementation of TO to include 2VALUEs requires detailed knowledge of the host implementation of VALUE and TO, which is the main reason why 2VALUE should be standardized. The order in which the two cells are stored in memory is not specified in the definition for 2VALUE but this reference implementation has to assume one ordering — this is not intended to be definitive.

: 2VALUE ( x1 x2 -- )
   CREATE , ,
   DOES> 2@ ( -- x1 x2 )
;

The corresponding implementation of TO disregards the issue that TO must also work for integer VALUEs and locals.

: TO ( x1 x2 "<spaces>name" -- )
   ' >BODY
   STATE @ IF
     POSTPONE 2LITERAL POSTPONE 2!
   ELSE
     2!
   THEN
; IMMEDIATE
Testing:
T{ 1 2 2VALUE t2val -> }T
T{ t2val -> 1 2 }T
T{ 3 4 TO t2val -> }T
T{ t2val -> 3 4 }T
: sett2val t2val 2SWAP TO t2val ;
T{ 5 6 sett2val t2val -> 3 4 5 6 }T