The return stack primarily exists for storing system data, such as return addresses and loop control parameters, but Forth also allows programmers to make use of it, albeit with restrictions stemming from the other uses. The primary use is for temporary storage of data; locals also provide this capability, and usually in a more convenient way; some purists (or puritans) prefer to avoid locals, though.
In Gforth 1.0 you can use the return stack during text interpretation
(and you cannot use locals for that). The only limitation here is
that you cannot pass data on the return stack into or out of an
included file, block, or evaluated string. Example:
1 >r : foo [ r> ] literal ; foo . \ prints 1
This interpretive usage of return-stack words is non-standard, and many other Forth systems do not have support this usage, or limit it to within one line.
In Gforth you can use the return stack for storing data while you also keep and access data in locals. However, the standard puts restrictions on mixing return stack and locals usage, for easy locals implementations, and there are systems that actually rely on these restrictions. So, if you want to produce a standard compliant program and you are using local variables in a definition, forget about return stack manipulations in that word (refer to the standard document for the exact rules).
>r ( w – R:w ) core “to-r”
r> ( R:w – w ) core “r-from”
r@ ( R:w – R:w w ) core “r-fetch”
r'@ ( r:w r:w2 – r:w r:w2 w ) gforth-1.0 “r-tick-fetch”
The second item on the return stack
rpick ( R:wu ... R:w0 u – R:wu ... R:w0 wu ) gforth-1.0 “rpick”
wu is the uth element on the return stack; 0
rpick is equivalent to r@.
rdrop ( R:w – ) gforth-0.2 “rdrop”
2>r ( w1 w2 – R:w1 R:w2 ) core-ext “two-to-r”
2r> ( R:w1 R:w2 – w1 w2 ) core-ext “two-r-from”
2r@ ( R:w1 R:w2 – R:w1 R:w2 w1 w2 ) core-ext “two-r-fetch”
2rdrop ( R:w1 R:w2 – ) gforth-0.2 “two-r-drop”
n>r ( x1 .. xn n – R:xn..R:x1 R:n ) tools-ext “n-to-r”
In Standard Forth, the order of items on the return stack is
not specified, and the only thing you can do with the items on
the return stack is to use nr>
nr> ( R:xn..R:x1 R:n – x1 .. xn n ) tools-ext “n-r-from”
In Standard Forth, the order of items on the return stack is
not specified, and the only thing you can do with the items on
the return stack is to use nr>
On some platforms (particularly, 32-bit platforms) floating-point numbers are not naturally aligned on the return stack and this can lead to (usually, but not always) small performance disadvantages.
f>r ( r – ) gforth-experimental “f-to-r”
Actual stack effect: ( r -- R:r )
fr> ( – r ) gforth-experimental “f-r-from”
Actual stack effect: ( R:r -- r )
fr@ ( – r ) gforth-experimental “f-r-fetch”
Actual stack effect: ( R:r -- R:r r )