Proposal: [307] Fix stack comments for N>R and NR>
This page is dedicated to discussing this specific proposal
ContributeContributions
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: [307] 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:
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: [307] Fix stack comments for N>R and NR>
Author:
- Anton Ertl
- Leon Wagner
Change Log
- 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.
Solution:
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 )
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.
ruv
[310] Why do we use +n and not u in the stack diagram for n>r and nr>Request for clarification2023-09-23 01:06:43
A citation from the Discussion section (in r1079):
On the data stack
x_n ... x_1 +nbecause that is the way we usually specify a numbered number of cells (even for+n=0). See, e.g.,get-order.
Well, in get-order n (the signed number data type) is probably incorrectly used after set-order, where n can be -1.
But in other words:
pick,
roll,
cs-pick,
cs-roll,
— the unsigned number data type (identified by u) is used to indicate the number of items.
So the question is: why is +n used in the stack diagrams for n>r and nr> instead of u?
ruv
In all cases where a stack parameter means the number of items on the stack, or a non-negative index of an item on the stack, this parameter shall have the data type "non-negative number" and the symbol +n should be used for this parameter in a stack diagram.
Rationale
We should use the smallest appropriate data type to describe a stack parameter. Thus, if it's known that a stack parameter always belongs to +n, we should not use the larger data type u to describe this parameter.
We shall be consistent. The word
depth ( -- +n )specifies that the returned parameter belongs to +n, that is, the stack depth cannot be more than max-n (the largest usable signed integer, see 3.2.6). It means, for other words, a count of some items on the stack or a non-negative index of a stack item shall be described with +n (or with a subtype of +n).In practice, it is almost impossible that the stack depth increases max-n. Because max-n means that the stack takes amount of memory that is equal to at least a half of theoretically available data space in a Forth system.