.he 'RETURN''Page %'
.fo 'Steven Hardy & Aaron Sloman''February 78'
RETURN
.br
------
.br
RETURN is a syntax word - like: FUNCTION, END, IF, THEN, CLOSE, VARS

Its effect is to terminate execution of the current function, as if it were
equivalent to the (illegal) command:
 	: GOTO END

For example, suppose you wish to define a function called MULTIPLES which
prints out twenty multiples of a given number, but stops as soon as the
number to be printed exceeds 100. You could define it thus:
.ne11
 	: FUNCTION MULTIPLES(NUM);
 	: VARS TOTAL;
 	: NUM -> TOTAL;		;;; get multiples by repeatedly adding
 				;;; NUM to TOTAL
 	:	REPEAT 20 TIMES
 	:		PPR(TOTAL);
 	:		IF	TOTAL > 100
 	:		THEN	RETURN
 	:		ELSE	NUM + TOTAL -> TOTAL
 	:		CLOSE
 	: END;

So MULTIPLES(3); will cause 20 numbers to be printed out, 3 6 9, etc.,
whereas MULTIPLES(10) will cause only 10 numbers to be printed out.

If you wish the function to leave some result on the stack before it stops, you
can specify the result between parentheses, after
RETURN, as in the following function, which takes takes a number NUM,
and produces the first multiple of NUM which is bigger than 100 but returns the word "TOOSMALL" if it hasn't got above 100
after trying a thousand multiples:

.ne 11
 	: FUNCTION MULTOVER100(NUM);
 	:	VARS TOTAL;
 	:	NUM -> TOTAL;
 	:	REPEAT 1000 TIMES
 	:		IF	TOTAL > 100
 	:		THEN	RETURN(TOTAL)
 	:		ELSE	NUM + TOTAL -> TOTAL
 	: 		CLOSE;
 	:	CLOSE;
 	:	"TOOSMALL"
 	: END;

The last line could have been RETURN("TOOSMALL") but since it is just before
END anyway, the use of RETURN there is redundant.

If the function has any "output locals", then their values are put onto the
stack before the function finishes, even if the termination is achieved by RETURN.
(See FUNCTION  and => ).
.br
So we could redefine MULTOVER100, using TOTAL as an output local, thus:

.ne10
 	: FUNCTION MULTOVER100(NUM) => TOTAL;
 	:	NUM -> TOTAL;
 	:	REPEAT 1000 TIMES
 	:		IF	TOTAL > 100
 	:		THEN	RETURN
 	:		ELSE	NUM + TOTAL -> TOTAL
 	:		CLOSE
 	:	CLOSE;
 	:	"TOOSMALL" -> TOTAL
 	: END;

If TOTAL is an output local then RETURN is equivalent to what would be
achieved by RETURN(TOTAL) in the case where TOTAL is not an output
local.

The combination " ; RETURN CLOSE" occurs quite frequently. This may be
abbreviated by the single syntax word "EXIT".
