2010-03-16 PJK Revised after clf discussion
                Added rational for N>R and test cases.
2009-02-04 SFP Original RfD

Rationale
=========

Problem
-------
Several ANS words, e.g. GET-ORDER and SAVE-INPUT, return a variable
number of stack items. Interfacing with a host operating system
frequently requires a large number of stack items.  To prevent
interference with other items, these items are then saved on the
return stack. Saving several items to the return stack is tedious,
especially where the number of items is unknown at compile time.

Current practise
----------------
At least SwiftForth, VFX Forth, spForth, and some versions of
Win32Forth provide the words N>R and NR> with the following
or similar specification.

N>R     \ xn..x1 +n -- ; R: -- x1 .. xn +n
Transfer N items and count to the return stack.

NR>     \ -- xn..x1 +n ; R: x1 .. xn +n --
\ *G Pull n items and count off the return stack.

These words cannot be written without an intimate knowledge of the
underlying Forth.

Approach
--------
At least one system stores items on the return stack in the format

   R: -- xn .. x1 n

Because coding of this word is dependent on a number of CPU and Forth
design issues, we do not propose to mandate the order of x1..xn on
the return stack, only to specify that n itself is on the top of the
return stack.

A consequence of this is that N>R and NR> are used in pairs. I have
not yet seen any code that relies on the order of items on the return
stack, but it could be useful. It should also be noted that by
defining the order, the ambiguous condition in the proposal can be
removed.

Proposal
========
15.6.2.aaaa N>R                                      n-to-r TOOLS EXT

Interpretation: Interpretation semantics for this word are undefined.

Execution: ( i*x +n -- ) ( R: -- j*x +n )
   Remove n+1 items from the data stack and store them for later
   retrieval by NR>.  The return stack may be used to store the data.

   Until this data has been retrieved by NR>:
   * this date will not be overwritten by a subsequent invocation of
     N>R and
   * a program may not access data placed on the return stack before
     the invocation of N>R.

Rational:
   An implementation may store the stack items in any manner.  It may
   store them on the return stack, in any order.  A stack constrained
   system may prefer to use a buffer to store the items, and place the
   location of that buffer on the return stack.

15.6.2.bbbb NR>                                    n-r-from TOOLS EXT

Interpretation: Interpretation semantics for this word are undefined.

Execution: ( -- i*x +n ) ( R: j*x +n -- )
   Retrieve the items previously stored by an invocation of N>R.  n is
   the number of items placed on the data stack.

Ambiguous condition:
   It is an ambiguous condition if NR> is used with data not stored by
   N>R.

Reference Implementation
========================
This implementation depends on the return address being on the
return stack.

: N>R           \ xn .. x1 N -- ; R: -- x1 .. xn n
\ *G Transfer N items and count to the return stack.
   dup                   \ xn .. x1 N N --
   begin
     dup
   while
     rot r> swap >r >r   \ xn .. N N -- ; R: .. x1 --
     1-                  \ xn .. N 'N -- ; R: .. x1 --
   repeat
   drop                  \ N -- ; R: x1 .. xn --
   r> swap >r >r
;

: NR>           \ -- xn .. x1 N ; R: x1 .. xn N --
\ *G Pull N items and count off the return stack.
   r> r> swap >r dup
   begin
     dup
   while
     r> r> swap >r -rot
     1-
   repeat
   drop
;

Tests
=====

: TNR1 N>R SWAP NR> ;
T{ 1 2 10 20 30 3 TNR1 -> 2 1 10 20 30 3 }T

: TNR2 N>R N>R SWAP NR> NR> ;
T{ 1 2 10 20 30 3 40 50 2 TNR2 -> 2 1 10 20 30 3 40 50 2 }T

Author
======
Stephen Pelc <stephen...@mpeforth.com>
MicroProcessor Engineering
133 Hill Lane, Southampton SO15 5AF, England.

<snip>

IMO, data is definitely plural.
--
Coos

--
Coos

:-)

   In Latin, data is the plural of datum and, historically and in
   specialized scientific fields, it is also treated as a plural in
   English, taking a plural verb, as in the data were collected and
   classified. In modern non-scientific use, however, despite the
   complaints of traditionalists, it is often not treated as a plural.
   Instead, it is treated as a mass noun, similar to a word like
   information, which cannot normally have a plural and which takes a
   singular verb. Sentences such as data was (as well as data were)
   collected over a number of years are now widely accepted in standard
   English.

I put to you that the original intention "this date will not be
overwritten by a subsequent invocation of N>R" is valid.  The whole
point of the word is for processing multiple stack items otherwise
people would use >r .

Jerry Avins raised the question of the number of the noun. As the
quote clarifies, in some specialized scientific fields, the usage is,
essentially, "these data" signifying "these data points", while the
more common usage, and the normal usage in statistics in the social
sciences in the US, is "this data", signifying this collection of data
(and sometimes really meaning "this data file").

American academic editors tend to be rather more formal about their
writing style than British ones.  However, American non-academic
editors tend to be rather less formal than their British counterparts.
As with many things, there seem to be more extreme variations
Stateside.