-
Notifications
You must be signed in to change notification settings - Fork 1
/
n-to-r.html
304 lines (258 loc) · 9.92 KB
/
n-to-r.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
<html>
<head>
<title>N>R and NR></title>
<style type="text/css">
ol li { margin-left: -1em; }
.item { width: 5em; }
ul.results { margin-left: 0em; padding-left: 20px; }
ul.results li { margin-bottom: 1ex; }
ul.results li:first-line { font-weight: bold; }
.history dd { margin-bottom: 1ex; }
.def dd { margin-bottom: 2ex; }
</style>
</head>
<body>
<h3><code>N>R</code> and <code>NR></code> (v3)</h3>
<p>
[ <a href="rfds.html">RfDs/CfVs</a> | <a href="proposals.html">Other proposals</a> ]
</p>
<h3>Poll Standings</h3>
See <a href="#voting">below</a> for voting instructions.
<h4>Systems</h4>
<dl>
<dt> [ ] conforms to ANS Forth.</dt>
<dd>Jorge Acereda (fina-forth)<br/>
Leon Wagner (SwiftForth and SwiftX)
</dd>
<dt> [ ] already implements the proposal in full since release [ ].</dt>
<dd> Leon Wagner (SwiftForth 2.0 and SwiftX 3.0)
Hans Bezemer (4tH 3.5d)
</dd>
<dt> [ ] implements the proposal in full in a development version.</dt>
<dd>Jorge Acereda (fina-forth)</dd>
<dt> [ ] will implement the proposal in full in release [ ].</dt>
<dt> [ ] will implement the proposal in full in some future release.</dt>
<dd>Jorge Acereda (fina-forth)</dd>
<dt> [ ] There are no plans to implement the proposal in full in [ ].</dt>
<dt> [ ] will never implement the proposal in full.
<dd> iForth (Marcel Hendrix)</dt>
</dl>
<h4>Programmers</h4>
<dl>
<dt> [ ] I have used (parts of) this proposal in my programs.</dt>
<dd>Jorge Acereda (fina-forth)<br/>
Leon Wagner
</dd>
<dt> [ ] I would use (parts of) this proposal in my programs if the systems I am interested in implemented it.</dt>
<dd>Jorge Acereda (fina-forth)</dd>
<dt> [ ] I would use (parts of) this proposal in my programs if this proposal was in the Forth standard.</dt>
<dd>Jorge Acereda (fina-forth)<br/>
Bruce R. McFarling<br/>
Hans Bezemer
</dd>
<dt> [ ] I would not use (parts of) this proposal in my programs.
<dd>Bernd Paysan
<br/>Marcel Hendrix</dt>
</dl>
<h4>Informal Results</h4>
<ul class="results">
<li>Hans Bezemer<br/>
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.
</li>
<li>Bernd Paysan<br/>
I actually think that variable stack effects are not such a good idea,
therefore, while <code>N>R</code> and <code>NR></code> are completing
the picture, it's the wrong picture.
<p/>
The systems I maintain allow defining <code>N>R</code> and <code>NR></code>
without carnal knowledge, sane default assumptions about a return stack work.
</li>
</ul>
<table width="500"><tr><td>
<h3>Problem</h3>
Several ANS words, e.g. <code>GET-ORDER</code> and <code>SAVE-INPUT</code>, 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.
<h3>Current practise</h3>
At least SwiftForth, VFX Forth, spForth, and some versions of
Win32Forth provide the words <code>N>R</code> and <code>NR></code> with the following
or similar specification.
<dl>
<dt><code>N>R \ xn..x1 +n -- ; R: -- x1 .. xn +n</code></dt>
<dd>Transfer <em>n</em> items and count to the return stack.</dd>
<dt><code>NR> \ -- xn..x1 +n ; R: x1 .. xn +n --</code></dt>
<dd>Pull <em>n</em> items and count off the return stack.</dd>
</dl>
These words cannot be written without an intimate knowledge of the
underlying Forth.
<h3>Approach</h3>
At least one system stores items on the return stack in the format
<blockquote>
R: -- xn .. x1 n
</blockquote>
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 <em>n</em> itself is on the top of the
return stack.
<p/>
A consequence of this is that <code>N>R</code> and <code>NR></code> 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.
<h3>Proposal</h3>
<pre>
15.6.2.aaaa N>R n-to-r TOOLS EXT
</pre>
<dl class="def">
<dt>Interpretation:</dt>
<dd>Interpretation semantics for this word are undefined.<p/></dd>
<dt>Execution: ( i*x +n -- ) ( R: -- j*x +n )</dt>
<dd>
Remove <em>n</em>+1 items from the data stack and store them for later
retrieval by <code>NR></code>. The return stack may be used to store the data.
Until this data has been retrieved by <code>NR></code>:
<ul>
<li>this data will not be overwritten by a subsequent invocation of
<code>N>R</code> and</li>
<li>a program may not access data placed on the return stack before
the invocation of <code>N>R</code>.</li>
</ul>
</dd>
<dt>See Also:</dt>
<dd>15.6.2.bbbb <code>NR></code>.</dd>
<dt>Rational:</dt>
<dd>
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.
</dd>
</dl>
<pre>
15.6.2.bbbb NR> n-r-from TOOLS EXT
</pre>
<dl class="def">
<dt>Interpretation:</dt>
<dd>Interpretation semantics for this word are undefined.</dd>
<dt>Execution: ( -- i*x +n ) ( R: j*x +n -- )</dt>
<dd>
Retrieve the items previously stored by an invocation of <code>N>R</code>. <em>n</em> is
the number of items placed on the data stack.
It is an ambiguous condition if <code>NR></code> is used with data not stored by
<code>N>R</code>.
</dd>
<dt>See Also:</dt>
<dd>15.6.2.aaaa <code>N>R</code>.</dd>
</dl>
<h3>Reference Implementation</h3>
This implementation depends on the return address being on the
return stack.
</td></tr></table>
<pre><code>
: 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
;
</code></pre>
<h3>Test Cases</h3>
<pre><code>
: 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
</code></pre>
<h3>Change History</h3>
<dl class="history">
<dt>2010-08-31 v3 (PJK)</dt>
<dd>Revised "date"/"data" typo<br/>
Replaced "<em>the location of that buffer</em>" with "<em>a reference to the buffer</em>" in the rational
</dd>
<dt>2010-03-16 v2 (PJK)</dt>
<dd>Revised after <code>comp.lang.forth</code> discussion<br/>
Added rational and test cases</dd>
<dt>2000-02-04 v1 (SFP)</dt>
<dd>Original RfD</dd>
</dl>
<h3>Credits</h3>
Stephen Pelc, <stephen<em>@</em>mpeforth<em>.</em>com><br/>
MicroProcessor Engineering Ltd - More Real, Less Time<br/>
133 Hill Lane, Southampton SO15 5AF, England<br/>
tel: +44 (0)23 8063 1441,<br/>
fax: +44 (0)23 8033 9691<br/>
web: <a href="http://www.mpeforth.com">www.mpeforth.com</a> - free VFX Forth downloads
<p>
Peter Knaggs <pjk<em>@</em>bcs<em>.</em>org<em>.</em>uk><br/>
Engineering, Mathematics and Physical Sciences,<br/>
University of Exeter, Exeter, Devon EX4 7QF, England<br/>
web: <a href="http://www.rigwit.co.uk">www.rigwit.co.uk</a>
</p>
<a name="voting"><h3>Voting Instructions</h3></a>
Fill out the appropriate ballot(s) below and mail it/them to
<[email protected]>. 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.
<p>
Note that you can be both a system implementor and a programmer, so
you can submit both kinds of ballots.
</p>
<h4>Ballot for systems</h4>
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).
<dl>
<dt>[ ] conforms to ANS Forth. </dt>
<dt>[ ] already implements the proposal in full since release [ ]. </dt>
<dt>[ ] implements the proposal in full in a development version. </dt>
<dt>[ ] will implement the proposal in full in release [ ]. </dt>
<dt>[ ] will implement the proposal in full in some future release. </dt>
<dt>[ ] There are no plans to implement the proposal in full in [ ]. </dt>
<dt>[ ] will never implement the proposal in full. </dt>
</dl>
If you want to provide information on partial implementation, please do
so informally, and I will aggregate this information in some way.
<h4>Ballot for programmers</h4>
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.
<dl>
<dt>[ ] I have used (parts of) this proposal in my programs.</dt>
<dt>[ ] I would use (parts of) this proposal in my programs if the systems
I am interested in implemented it.</dt>
<dt>[ ] I would use (parts of) this proposal in my programs if this
proposal was in the Forth standard.</dt>
<dt>[ ] I would not use (parts of) this proposal in my programs.</dt>
</dl>
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.
</body>
</html>