wfroth reference : Stack Operations

 

This chapter presents a complete reference on wfroth.

Last update:

1-January-1999

State (estimation)

100%


This chapter includes the following sections:


Introduction

Numeric objects stored on stack parameters are untyped: they are only 32-bits integers. Interpretation of their value is made by each word. For example, a same value can be interpreted as a signed integer (for example the word .), an an unsigned integer (U.), or a string (type). It's the programmer's responsability to be sure that the correct stack parameters are available for each definition: right number of parameters and right type for each parameter. You can use the word ?ENOUGHT to check for the number of parameters.

 

Actions on the Parameters Stack

.s

( --- )

Print all values available on stack. This is not destructive. Each value is interpreted as a signed integer, and is shown in decimal, whatever the value of the current base for integer numeric I/O. The purpose of this word is above all for debugging, or learning stack manipulation.

 

DEPTH

( --- n )

Push the number of integers available on stack. If n is zero that means that stack is empty.

 

?ENOUGHT

( n --- )

Allows to verify at run-time if there is at least n integers available on stack. n must be a constant number compiled before the call of ?ENOUGHT. If the variable ?SAFE is FALSE, there is nothing compiled into your definition, and the constant is removed: for example "3 ?ENOUGHT" does not compile anything. If the variable ?SAFE is TRUE, then ?ENOUGHT is compiled and will be executed at run-time. That means that you can test your program without any source modification, just change the value of variable ?SAFE.

 

DROP

( n --- )

Discard the value which is on top of the stack.

 

DDROP

( n1 n2 --- )

Alias: 2DROP

Discard the two values which are on top stack.

: DDROP DROP DROP ;

 

DROPS

( n --- )

Discard the n top values from stack.

: DROPS TIMES drop ENDTIMES ;

 

UNDER

( n1 n2 --- n2 )

Alias: NIP

Discard the value which under the top of the stack. We could define UNDER as:

: UNDER swap drop ;

 

BELOW

( n1 n2 n3 --- n2 n3 )

Discard the value which under-under the top of the stack. We could define UNDER as:

: BELOW rot drop ;

 

DUP

( n --- n n )

Duplicate the value which is on top stack.

 

DDUP

( n1 n2 --- n1 n2 n1 n2 )

Alias: 2DUP

Duplicate the two values which are on top stack. This word could be defined as:

: DDUP over over ;

 

OVER

( n1 n2 --- n1 n2 n1 )

Duplicate the value which is under the top stack.

 

ABOVE

( n1 n2 n3 --- n1 n2 n3 n1 )

Duplicate the value which is under under the top stack.

 

SWAP

( n1 n2 --- n2 n1 )

Exchange the two values on top stack.

 

DSWAP

( n1 n2 n1 n2 --- n2 n1 n2 n1 )

Alias: 2SWAP

Exchange the two couples on top stack.

 

ROT

( n1 n2 n3 --- n2 n3 n1 )

Rotate the top three values on stack.

 

-ROT

( n1 n2 n3 --- n3 n1 n2 )

Rotate the top three values on stack.

 

ROLL

( n --- )

Rotate the top n values on stack. ROT can be defined as:

: ROT 3 roll ;

 

-ROLL

( n --- )

Rotate the top n values on stack. -ROT can be defined as:

: -ROT 3 -roll ;

 

PICK

( n1 --- n2 )

Duplicate the n1-th value which is under the top stack. The next definitions can be defined using PICK:

: OVER 2 pick ;

: ABOVE 3 pick ;

 

Actions on the Return Stack

The Return Stack is used by wfroth to save/restore the nested calls to the definitions (forth vm). The Return Stack is also used to save current index and limit for loops (do..loop). Therefore:

         leaving a definition, always lets the Return Stack in the state you have found when entering into this definition:

Correct:

: test 10 >R " hello" type R> drop ;

Incorrect:

: test 10 >R " hello" type R drop ;

         always let the return stack in the same state within a do..loop

Correct:

: test 10 1 DO I . space 10 >R R> drop LOOP ;

Incorrect:

: test 10 1 DO I . space 10 >R R drop LOOP ;

 

Definition

Return Stack

Parameters Stack

>R

( --- n )

( n --- )

Push a value into the Return Stack.

 

Definition

Return Stack

Parameters Stack

R>

( n --- )

( --- n )

Pop a value from the Return Stack.

 

Definition

Return Stack

Parameters Stack

Alias

R

( n --- n )

( --- n )

R

Copy a value on top of the Return Stack.

 

Definition

Return Stack

RDROP

( n --- )

Discard the value from the Return Stack.

: RDROP R> drop ;

 

Definition

Return Stack

RUNDER

( n1 n2 --- n2 )

Discard the value under top the Return Stack.

: RUNDER R> R> drop >R ;

 

Definition

Return Stack

RBELOW

( n1 n2 n3 --- n2 n3 )

Discard the value under-under top the Return Stack.

: RBELOW R> R> R> drop >R >R ;

 

Definition

Return Stack

RDUP

( n --- n n )

Duplicate the value on top of the Return Stack.

: RDUP R >R ;

 

Definition

Return Stack

RSWAP

( n1 n2 --- n2 n1 )

Exchange the 2 values on top of the Return Stack.

: RSWAP R> R> swap >R >R ;

 

Definition

Return Stack

ROVER

( n1 n2 --- n1 n2 n1 )

Duplicate the value under-top of the Return Stack.

: ROVER R> R> dup -rot >R >R >R ;

 

Definition

Return Stack

RABOVE

( n1 n2 n3 --- n1 n2 n3 n1 )

Duplicate the value under-under-top of the Return Stack.

: RABOVE R> R> R -rot >R >R >R ;