N>R and NR>

`N>R` and `NR>` (v3)

[ RfDs/CfVs | Other proposals ]

Poll Standings

See below for voting instructions.

Systems

[ ] conforms to ANS Forth.: Jorge Acereda (fina-forth)
Leon Wagner (SwiftForth and SwiftX)
[ ] already implements the proposal in full since release [ ].: Leon Wagner (SwiftForth 2.0 and SwiftX 3.0) Hans Bezemer (4tH 3.5d)
[ ] implements the proposal in full in a development version.: Jorge Acereda (fina-forth)
[ ] will implement the proposal in full in release [ ].
[ ] will implement the proposal in full in some future release.: Jorge Acereda (fina-forth)
[ ] There are no plans to implement the proposal in full in [ ].
[ ] will never implement the proposal in full.: iForth (Marcel Hendrix)

Programmers

[ ] I have used (parts of) this proposal in my programs.: Jorge Acereda (fina-forth)
Leon Wagner
[ ] I would use (parts of) this proposal in my programs if the systems I am interested in implemented it.: Jorge Acereda (fina-forth)
[ ] I would use (parts of) this proposal in my programs if this proposal was in the Forth standard.: Jorge Acereda (fina-forth)
Bruce R. McFarling
Hans Bezemer
[ ] I would not use (parts of) this proposal in my programs.: Bernd Paysan
Marcel Hendrix

Informal Results

Hans Bezemer
4tH has long provided this functionality in the form of the reference implementation. No problems have been reported, although no example program in the official release uses it.
Bernd Paysan
I actually think that variable stack effects are not such a good idea, therefore, while N>R and NR> are completing the picture, it's the wrong picture.
The systems I maintain allow defining N>R and NR> without carnal knowledge, sane default assumptions about a return stack work.

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 --: 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 data 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.

See Also:

15.6.2.bbbb NR>.

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 a reference to the 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. It is an ambiguous condition if NR> is used with data not stored by N>R.
See Also:: 15.6.2.aaaa 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
;

Test Cases


: 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

Change History

2010-08-31 v3 (PJK): Revised "date"/"data" typo
Replaced "the location of that buffer" with "a reference to the buffer" in the rational
2010-03-16 v2 (PJK): Revised after comp.lang.forth discussion
Added rational and test cases
2000-02-04 v1 (SFP): Original RfD

Credits

Stephen Pelc, <stephen@mpeforth.com>
MicroProcessor Engineering Ltd - More Real, Less Time
133 Hill Lane, Southampton SO15 5AF, England
tel: +44 (0)23 8063 1441,
fax: +44 (0)23 8033 9691
web: www.mpeforth.com - free VFX Forth downloads

Peter Knaggs <pjk@bcs.org.uk>
Engineering, Mathematics and Physical Sciences,
University of Exeter, Exeter, Devon EX4 7QF, England
web: www.rigwit.co.uk

Voting Instructions

Fill out the appropriate ballot(s) below and mail it/them to <vote@forth200x.org>. Your vote will be published (including your name (without email address) and/or the name of your system) here. You can vote (or change your vote) at any time, and the results will be published here.

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

Ballot for systems

If you maintain several systems, please mention the systems separately in the ballot. Insert the system name or version between the brackets. Multiple hits for the same system are possible (if they do not conflict).

[ ] 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.

If you want to provide information on partial implementation, please do so informally, and I will aggregate this information in some way.

Ballot for programmers

Just mark the statements that are correct for you (e.g., by putting an "x" between the brackets). If some statements are true for some of your programs, but not others, please mark the statements for the dominating class of programs you write.

[ ] 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.

If you feel that there is closely related functionality missing from the proposal (especially if you have used that in your programs), make an informal comment, and I will collect these, too. Note that the best time to voice such issues is the RfD stage.

N>R and NR> (v3)