Proposal: Fix stack comments for N>R and NR>
This page is dedicated to discussing this specific proposal
LeonWagner
[307] Fix stack comments for N>R and NR>Proposal2023-09-13 12:09:40
Author:
Leon Wagner
Change Log
2023-09-13 Initial proposal
Problem:
The stack comments for N>R and NR> don't make it clear that n items are moved between the data and return stacks.
Solution:
The stack comments should more clearly indicate that n data stack items are moved to or from the return stack.
Proposal:
Change the stack comments for 15.6.2.1908 N>R to ( n*x +n -- ) ( R: -- n*x +n ) and 15.6.2.1940 NR> to ( -- n*x +n ) ( R: n*x +n -- )
AntonErtl
New Version: Fix stack comments for N>R and NR>
Author:
Anton Ertl
Leon Wagner
Change Log
2023-09-14 Revision after discussion (AE)
2023-09-13 Initial proposal
Problem:
The stack comments for N>R and NR> don't make it clear that n items are moved between the data and return stacks.
Solution:
The stack comments should more clearly indicate that n data stack items are moved to or from the return stack.
Proposal:
Change the stack comments for 15.6.2.1908 N>R to ( n*x +n -- ) ( R: -- n*x +n ) and 15.6.2.1940 NR> to ( -- n*x +n ) ( R: n*x +n -- )
In the definition of N>R, replace
( i * n +n -- ) ( R: -- j * x +n )
with
( x_n ... x_1 n -- ) ( R: -- j * x +n )
In the definition of NR>, replace
( -- i * x +n ) ( R: j * x +n -- )
with
( -- x_n ... x_1 +n ) ( R: j * x +n -- )
Discussion
On the return stack, j*x +n because the data may be in a separate buffer and only the address and +n on the return stack. +n on the return stack because the original specified that, and changing that would be a substantial change.
On the data stack x_n ... x_1 +n because that is the way we usually specify a numbered number of cells (even for +n=0). See, e.g., get-order.
AntonErtlNew Version: Fix stack comments for N>R and NR>
Author:
Anton Ertl Leon Wagner
- Anton Ertl
- Leon Wagner
Change Log
2023-09-14 Revision after discussion (AE) 2023-09-13 Initial proposal
- 2024-06-06 replaced some
nwith+n; formatting changes (AE) - 2023-09-14 Revision after discussion (AE)
- 2023-09-13 Initial proposal
Problem:
The stack comments for N>R and NR> don't make it clear that n items are moved between the data and return stacks.
The stack comments for N>R and NR> don't make it clear that +n items are moved between the data and return stacks.
Solution:
The stack comments should more clearly indicate that n data stack items are moved to or from the return stack.
The stack comments should more clearly indicate that +n data stack items are moved to or from the return stack.
Proposal:
In the definition of N>R, replace
( i * n +n -- ) ( R: -- j * x +n )
with
( x_n ... x_1 n -- ) ( R: -- j * x +n )
( x_n ... x_1 +n -- ) ( R: -- j*x +n )
In the definition of NR>, replace
( -- i * x +n ) ( R: j * x +n -- )
with
( -- x_n ... x_1 +n ) ( R: j * x +n -- )
( -- x_n ... x_1 +n ) ( R: j*x +n -- )
Discussion
On the return stack, j*x +n because the data may be in a separate buffer and only the address and +n on the return stack. +n on the return stack because the original specified that, and changing that would be a substantial change.
On the data stack x_n ... x_1 +n because that is the way we usually specify a numbered number of cells (even for +n=0). See, e.g., get-order.
AntonErtlNew Version: Fix stack comments for N>R and NR>
Author:
- Anton Ertl
- Leon Wagner
Change Log
- 2025-09-11 replaced +n with u (AE)
- 2024-06-06 replaced some
nwith+n; formatting changes (AE) - 2023-09-14 Revision after discussion (AE)
- 2023-09-13 Initial proposal
Problem:
The stack comments for N>R and NR> don't make it clear that +n items are moved between the data and return stacks.
The stack comments for N>R and NR> don't make it clear that u items are moved between the data and return stacks.
Solution:
The stack comments should more clearly indicate that +n data stack items are moved to or from the return stack.
The stack comments should more clearly indicate that u data stack items are moved to or from the return stack.
Proposal:
In the definition of N>R, replace
( i * n +n -- ) ( R: -- j * x +n )
( i * n u -- ) ( R: -- j * x u )
with
( x_n ... x_1 +n -- ) ( R: -- j*x +n )
( x_u ... x_1 u -- ) ( R: -- j*x u )
In the definition of NR>, replace
( -- i * x +n ) ( R: j * x +n -- )
( -- i * x u ) ( R: j * x u -- )
with
( -- x_n ... x_1 +n ) ( R: j*x +n -- )
( -- x_u ... x_1 u ) ( R: j*x u -- )
Discussion
On the return stack, j*x +n because the data may be in a separate buffer and only the address and +n on the return stack. +n on the return stack because the original specified that, and changing that would be a substantial change.
On the return stack, j*x u because the data may be in a separate buffer and only the address on the return stack. u on the return stack because the original specified that, and changing that would be a substantial change.
On the data stack x_n ... x_1 +n because that is the way we usually specify a numbered number of cells (even for +n=0). See, e.g., get-order.
On the data stack x_n ... x_1 u because that is the way we usually specify a numbered number of cells (even for u=0). See, e.g., get-order.
AntonErtl
We discussed your request for clarification for a while, with various reasons discusses why changing from +n to u would not make a difference or under what circumstances it would and eventually I suggested that we just follow your suggestion, and reached consensus on that.
Thinking about it again: In general, u is preferable to +n, because +n leaves it undefined what happens for negative n. +n is the right choice in cases where system behaviour varies for negative n, but otherwise, we should either specify u or n with a specific behaviour for negative n.
AntonErtl
The committee has accepted this as a non-substantive change in the 2025 meeting with vote #39: 8Y:0N:0A.
ruv
@AntonErtl wrote
In general, u is preferable to +n, because +n leaves it undefined what happens for negative n. +n is the right choice in cases where system behaviour varies for negative n, but otherwise, we should either specify u or n with a specific behaviour for negative n.
That's reasonable. Then, if the parameter is of type +n, it makes sense to specify for it u if it's an input parameter, and +n if it's an output parameter. Similarly, like we specify x for an input boolean (zero or nonzero), and flag for an output one.